{"owner":"apache","repo":"seatunnel","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# LLM Context Guide for Apache SeaTunnel\n\nThis guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.\n\n## ⚠️ CRITICAL: Validate Before Proposing Changes\n\n**Agents MUST run verification commands locally before suggesting or finalizing changes.**\n\n```bash\n# Format code (mandatory)\n./mvnw spotless:apply\n\n# Quick verification (mandatory)\n./mvnw -q -DskipTests verify\n\n# Unit tests (strongly recommended)\n./mvnw test\n```\n\nFailure to meet these requirements will likely result in PR rejection.\n\n## Git Commit Message Convention\n\nSeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.\n\n**Format**:\n\n```\n[Type][Module] Description\n```\n\n### Types\n\n* `Feature`  – New features\n* `Fix`      – Bug fixes\n* `Improve`  – Improvements to existing behavior\n* `Docs`     – Documentation-only changes\n* `Test`     – Test cases or test framework changes\n* `Chore`    – Build, dependency, or maintenance tasks\n\n### Modules\n\n* `Connector-V2`  – seatunnel-connectors-v2\n* `Zeta`          – seatunnel-engine (Zeta engine)\n* `Core`          – seatunnel-core\n* `API`           – seatunnel-api\n* `Transform-V2`  – seatunnel-transforms-v2\n* `Format`        – seatunnel-formats\n* `Translation`   – seatunnel-translation\n* `E2E`           – seatunnel-e2e\n\n### Examples\n\n* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`\n* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`\n* `[Feature][Transform-V2] Add LLM transform plugin`\n* `[Improve][Core] Optimize jar package loading speed`\n* `[Docs] Update quick start guide`\n\n## Repository Structure\n\n```text\nseatunnel/\n├── seatunnel-api/              # Core API definitions\n├── seatunnel-connectors-v2/    # Source & Sink connectors (main contribution area)\n├── seatunnel-transforms-v2/    # Transform plugins (including LLM)\n├── seatunnel-engine/           # Zeta engine & Web UI\n├── seatunnel-core/             # Job submission & CLI entry points\n├── seatunnel-translation/      # Flink & Spark adapters\n├── seatunnel-formats/          # Data formats (JSON, Avro, etc.)\n├── seatunnel-e2e/              # End-to-End integration tests\n├── docs/                       # Documentation (en & zh)\n└── config/                     # Default configurations\n```\n\n## Code Standards\n\n### Java Backend\n\n* **Formatting**: Google Java Format (AOSP style), enforced by Spotless\n* **Imports**:\n    * No wildcard imports\n    * Use shaded dependencies: `org.apache.seatunnel.shade.*`\n* **Nullability**: Avoid implicit null assumptions\n* **Visibility**: Keep APIs minimal; prefer package-private when possible\n* **Comments**: Add comments for important methods (public APIs, complex logic). Important methods include public APIs, lifecycle hooks (initialization, start/stop, checkpoint), and complex or performance-critical logic. Example:\n\n```java\n/**\n * Enumerates source splits for parallel reading.\n * Called once during job initialization.\n *\n * @param context Split enumeration context\n * @return Collection of discovered splits\n */\n@Override\npublic List<SourceSplit> enumerateSplits(SplitEnumerationContext context) {\n    // Implementation\n}\n```\n\n### Apache License Header (MANDATORY)\n\nAll **new files** MUST include the ASF license header:\n\n```java\n/*\n * Licensed to the Apache Software Foundation (ASF) under one or more\n * contributor license agreements.  See the NOTICE file distributed with\n * this work for additional information regarding copyright ownership.\n * The ASF licenses this file to You under the Apache License, Version 2.0\n * (the \"License\"); you may not use this file except in compliance with\n * the License.  You may obtain a copy of the License at\n *\n *    http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n```\n\n## 🚨 Backward Compatibility (VERY IMPORTANT)\n\nAgents MUST treat backward compatibility as a **hard constraint**.\n\n* DO NOT remove or rename existing config options\n* DO NOT change default values casually\n* DO NOT break public APIs or SPI contracts\n\nAny incompatible change MUST:\n\n* Be explicitly documented\n* Be documented in `docs/en/introduction/concepts/incompatible-changes.md`\n* Include migration guidance\n* Be clearly explained in the PR description\n\n## Dependency Rules\n\n* DO NOT introduce new dependencies unless absolutely necessary\n* Prefer existing shaded dependencies under `org.apache.seatunnel.shade.*`\n* Any new dependency MUST:\n    * Be justified in the PR description\n    * Consider shading, size, and conflict risks\n\n## Architecture Guidelines\n\n### Connector (V2)\n\n* Implement `SeaTunnelSource` or `SeaTunnelSink`\n* Define configs using `Option`\n* Support parallelism via `SourceSplitEnumerator`\n* Avoid connector-specific logic leaking into engine or core\n\n### Zeta Engine\n\n* **Client**: Submits job config\n* **Master**: Schedules & coordinates\n* **Worker**: Executes tasks (Source → Transform → Sink)\n\nRespect task boundaries and lifecycle semantics.\n\n## Configuration (Option) Rules\n\n* All user-facing configs MUST be defined using `Option`\n* Each option MUST include:\n    * name\n    * type\n    * default value (if applicable)\n    * clear description\n* Option names are **stable contracts** and must not be renamed lightly\n\n## Error Handling & Logging\n\n* Exceptions MUST include sufficient context (table, task, config key)\n* Avoid swallowing exceptions\n* Use proper log levels:\n    * INFO  – lifecycle events\n    * WARN  – recoverable issues\n    * ERROR – task-failing errors\n* NEVER log sensitive information (passwords, tokens, credentials)\n\n## Documentation Rules\n\n* Any user-visible change MUST update:\n\n    * `docs/en`\n    * `docs/zh`\n* Config names, defaults, and examples MUST match the code exactly\n* Documentation is part of the feature, not an afterthought\n\n## Testing Guidelines\n\n### Unit Tests\n\n* Located under `src/test/java`\n* Validate behavior, not implementation details\n* Prefer deterministic and minimal tests\n\nCommand:\n\n```bash\n./mvnw test\n```\n\n### E2E Tests\n\n* Located in `seatunnel-e2e`\n* Uses Testcontainers\n* Extend `TestSuiteBase`\n\nCommand:\n\n```bash\n./mvnw -DskipUT -DskipIT=false verify\n```\n\n## Performance Awareness\n\nAgents MUST consider performance implications:\n\n* Avoid unnecessary object creation in hot paths\n* Be cautious with large in-memory buffers\n* Consider parallelism and resource usage\n\n## PR Scope Rule\n\n* Keep changes minimal and focused\n* Avoid unrelated refactors or formatting-only changes\n* One PR should solve **one problem**\n\n## Running & Debugging\n\n### Build from Source\n\n```bash\n./mvnw clean install -DskipTests -Dskip.spotless=true\n```\n\n### Install Connectors\n\n```bash\nsh bin/install-plugin.sh $current_version\n```\n\n### Run Job (Zeta)\n\n```bash\nsh bin/seatunnel.sh --config config/v2.batch.config.template -e local\n```\n"},"files":{"AGENTS.md":"# LLM Context Guide for Apache SeaTunnel\n\nThis guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.\n\n## ⚠️ CRITICAL: Validate Before Proposing Changes\n\n**Agents MUST run verification commands locally before suggesting or finalizing changes.**\n\n```bash\n# Format code (mandatory)\n./mvnw spotless:apply\n\n# Quick verification (mandatory)\n./mvnw -q -DskipTests verify\n\n# Unit tests (strongly recommended)\n./mvnw test\n```\n\nFailure to meet these requirements will likely result in PR rejection.\n\n## Git Commit Message Convention\n\nSeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.\n\n**Format**:\n\n```\n[Type][Module] Description\n```\n\n### Types\n\n* `Feature`  – New features\n* `Fix`      – Bug fixes\n* `Improve`  – Improvements to existing behavior\n* `Docs`     – Documentation-only changes\n* `Test`     – Test cases or test framework changes\n* `Chore`    – Build, dependency, or maintenance tasks\n\n### Modules\n\n* `Connector-V2`  – seatunnel-connectors-v2\n* `Zeta`          – seatunnel-engine (Zeta engine)\n* `Core`          – seatunnel-core\n* `API`           – seatunnel-api\n* `Transform-V2`  – seatunnel-transforms-v2\n* `Format`        – seatunnel-formats\n* `Translation`   – seatunnel-translation\n* `E2E`           – seatunnel-e2e\n\n### Examples\n\n* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`\n* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`\n* `[Feature][Transform-V2] Add LLM transform plugin`\n* `[Improve][Core] Optimize jar package loading speed`\n* `[Docs] Update quick start guide`\n\n## Repository Structure\n\n```text\nseatunnel/\n├── seatunnel-api/              # Core API definitions\n├── seatunnel-connectors-v2/    # Source & Sink connectors (main contribution area)\n├── seatunnel-transforms-v2/    # Transform plugins (including LLM)\n├── seatunnel-engine/           # Zeta engine & Web UI\n├── seatunnel-core/             # Job submission & CLI entry points\n├── seatunnel-translation/      # Flink & Spark adapters\n├── seatunnel-formats/          # Data formats (JSON, Avro, etc.)\n├── seatunnel-e2e/              # End-to-End integration tests\n├── docs/                       # Documentation (en & zh)\n└── config/                     # Default configurations\n```\n\n## Code Standards\n\n### Java Backend\n\n* **Formatting**: Google Java Format (AOSP style), enforced by Spotless\n* **Imports**:\n    * No wildcard imports\n    * Use shaded dependencies: `org.apache.seatunnel.shade.*`\n* **Nullability**: Avoid implicit null assumptions\n* **Visibility**: Keep APIs minimal; prefer package-private when possible\n* **Comments**: Add comments for important methods (public APIs, complex logic). Important methods include public APIs, lifecycle hooks (initialization, start/stop, checkpoint), and complex or performance-critical logic. Example:\n\n```java\n/**\n * Enumerates source splits for parallel reading.\n * Called once during job initialization.\n *\n * @param context Split enumeration context\n * @return Collection of discovered splits\n */\n@Override\npublic List<SourceSplit> enumerateSplits(SplitEnumerationContext context) {\n    // Implementation\n}\n```\n\n### Apache License Header (MANDATORY)\n\nAll **new files** MUST include the ASF license header:\n\n```java\n/*\n * Licensed to the Apache Software Foundation (ASF) under one or more\n * contributor license agreements.  See the NOTICE file distributed with\n * this work for additional information regarding copyright ownership.\n * The ASF licenses this file to You under the Apache License, Version 2.0\n * (the \"License\"); you may not use this file except in compliance with\n * the License.  You may obtain a copy of the License at\n *\n *    http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n```\n\n## 🚨 Backward Compatibility (VERY IMPORTANT)\n\nAgents MUST treat backward compatibility as a **hard constraint**.\n\n* DO NOT remove or rename existing config options\n* DO NOT change default values casually\n* DO NOT break public APIs or SPI contracts\n\nAny incompatible change MUST:\n\n* Be explicitly documented\n* Be documented in `docs/en/introduction/concepts/incompatible-changes.md`\n* Include migration guidance\n* Be clearly explained in the PR description\n\n## Dependency Rules\n\n* DO NOT introduce new dependencies unless absolutely necessary\n* Prefer existing shaded dependencies under `org.apache.seatunnel.shade.*`\n* Any new dependency MUST:\n    * Be justified in the PR description\n    * Consider shading, size, and conflict risks\n\n## Architecture Guidelines\n\n### Connector (V2)\n\n* Implement `SeaTunnelSource` or `SeaTunnelSink`\n* Define configs using `Option`\n* Support parallelism via `SourceSplitEnumerator`\n* Avoid connector-specific logic leaking into engine or core\n\n### Zeta Engine\n\n* **Client**: Submits job config\n* **Master**: Schedules & coordinates\n* **Worker**: Executes tasks (Source → Transform → Sink)\n\nRespect task boundaries and lifecycle semantics.\n\n## Configuration (Option) Rules\n\n* All user-facing configs MUST be defined using `Option`\n* Each option MUST include:\n    * name\n    * type\n    * default value (if applicable)\n    * clear description\n* Option names are **stable contracts** and must not be renamed lightly\n\n## Error Handling & Logging\n\n* Exceptions MUST include sufficient context (table, task, config key)\n* Avoid swallowing exceptions\n* Use proper log levels:\n    * INFO  – lifecycle events\n    * WARN  – recoverable issues\n    * ERROR – task-failing errors\n* NEVER log sensitive information (passwords, tokens, credentials)\n\n## Documentation Rules\n\n* Any user-visible change MUST update:\n\n    * `docs/en`\n    * `docs/zh`\n* Config names, defaults, and examples MUST match the code exactly\n* Documentation is part of the feature, not an afterthought\n\n## Testing Guidelines\n\n### Unit Tests\n\n* Located under `src/test/java`\n* Validate behavior, not implementation details\n* Prefer deterministic and minimal tests\n\nCommand:\n\n```bash\n./mvnw test\n```\n\n### E2E Tests\n\n* Located in `seatunnel-e2e`\n* Uses Testcontainers\n* Extend `TestSuiteBase`\n\nCommand:\n\n```bash\n./mvnw -DskipUT -DskipIT=false verify\n```\n\n## Performance Awareness\n\nAgents MUST consider performance implications:\n\n* Avoid unnecessary object creation in hot paths\n* Be cautious with large in-memory buffers\n* Consider parallelism and resource usage\n\n## PR Scope Rule\n\n* Keep changes minimal and focused\n* Avoid unrelated refactors or formatting-only changes\n* One PR should solve **one problem**\n\n## Running & Debugging\n\n### Build from Source\n\n```bash\n./mvnw clean install -DskipTests -Dskip.spotless=true\n```\n\n### Install Connectors\n\n```bash\nsh bin/install-plugin.sh $current_version\n```\n\n### Run Job (Zeta)\n\n```bash\nsh bin/seatunnel.sh --config config/v2.batch.config.template -e local\n```\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# LLM Context Guide for Apache SeaTunnel\n\nThis guide helps AI assistants (LLMs / Agents) make **safe, consistent, and verifiable** changes to the Apache SeaTunnel codebase. It mirrors practices from mature Apache projects and adapts them to SeaTunnel’s **build, testing, architecture, and documentation conventions**.\n\n## ⚠️ CRITICAL: Validate Before Proposing Changes\n\n**Agents MUST run verification commands locally before suggesting or finalizing changes.**\n\n```bash\n# Format code (mandatory)\n./mvnw spotless:apply\n\n# Quick verification (mandatory)\n./mvnw -q -DskipTests verify\n\n# Unit tests (strongly recommended)\n./mvnw test\n```\n\nFailure to meet these requirements will likely result in PR rejection.\n\n## Git Commit Message Convention\n\nSeaTunnel follows a **strict commit message format** to maintain a clean and searchable history.\n\n**Format**:\n\n```\n[Type][Module] Description\n```\n\n### Types\n\n* `Feature`  – New features\n* `Fix`      – Bug fixes\n* `Improve`  – Improvements to existing behavior\n* `Docs`     – Documentation-only changes\n* `Test`     – Test cases or test framework changes\n* `Chore`    – Build, dependency, or maintenance tasks\n\n### Modules\n\n* `Connector-V2`  – seatunnel-connectors-v2\n* `Zeta`          – seatunnel-engine (Zeta engine)\n* `Core`          – seatunnel-core\n* `API`           – seatunnel-api\n* `Transform-V2`  – seatunnel-transforms-v2\n* `Format`        – seatunnel-formats\n* `Translation`   – seatunnel-translation\n* `E2E`           – seatunnel-e2e\n\n### Examples\n\n* `[Fix][Connector-V2] Fix MySQL source split enumeration bug`\n* `[Fix][Zeta] Fix checkpoint timeout under heavy backpressure`\n* `[Feature][Transform-V2] Add LLM transform plugin`\n* `[Improve][Core] Optimize jar package loading speed`\n* `[Docs] Update quick start guide`\n\n## Repository Structure\n\n```text\nseatunnel/\n├── seatunnel-api/              # Core API definitions\n├── seatunnel-connectors-v2/    # Source & Sink connectors (main contribution area)\n├── seatunnel-transforms-v2/    # Transform plugins (including LLM)\n├── seatunnel-engine/           # Zeta engine & Web UI\n├── seatunnel-core/             # Job submission & CLI entry points\n├── seatunnel-translation/      # Flink & Spark adapters\n├── seatunnel-formats/          # Data formats (JSON, Avro, etc.)\n├── seatunnel-e2e/              # End-to-End integration tests\n├── docs/                       # Documentation (en & zh)\n└── config/                     # Default configurations\n```\n\n## Code Standards\n\n### Java Backend\n\n* **Formatting**: Google Java Format (AOSP style), enforced by Spotless\n* **Imports**:\n    * No wildcard imports\n    * Use shaded dependencies: `org.apache.seatunnel.shade.*`\n* **Nullability**: Avoid implicit null assumptions\n* **Visibility**: Keep APIs minimal; prefer package-private when possible\n* **Comments**: Add comments for important methods (public APIs, complex logic). Important methods include public APIs, lifecycle hooks (initialization, start/stop, checkpoint), and complex or performance-critical logic. Example:\n\n```java\n/**\n * Enumerates source splits for parallel reading.\n * Called once during job initialization.\n *\n * @param context Split enumeration context\n * @return Collection of discovered splits\n */\n@Override\npublic List<SourceSplit> enumerateSplits(SplitEnumerationContext context) {\n    // Implementation\n}\n```\n\n### Apache License Header (MANDATORY)\n\nAll **new files** MUST include the ASF license header:\n\n```java\n/*\n * Licensed to the Apache Software Foundation (ASF) under one or more\n * contributor license agreements.  See the NOTICE file distributed with\n * this work for additional information regarding copyright ownership.\n * The ASF licenses this file to You under the Apache License, Version 2.0\n * (the \"License\"); you may not use this file except in compliance with\n * the License.  You may obtain a copy of the License at\n *\n *    http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n```\n\n## 🚨 Backward Compatibility (VERY IMPORTANT)\n\nAgents MUST treat backward compatibility as a **hard constraint**.\n\n* DO NOT remove or rename existing config options\n* DO NOT change default values casually\n* DO NOT break public APIs or SPI contracts\n\nAny incompatible change MUST:\n\n* Be explicitly documented\n* Be documented in `docs/en/introduction/concepts/incompatible-changes.md`\n* Include migration guidance\n* Be clearly explained in the PR description\n\n## Dependency Rules\n\n* DO NOT introduce new dependencies unless absolutely necessary\n* Prefer existing shaded dependencies under `org.apache.seatunnel.shade.*`\n* Any new dependency MUST:\n    * Be justified in the PR description\n    * Consider shading, size, and conflict risks\n\n## Architecture Guidelines\n\n### Connector (V2)\n\n* Implement `SeaTunnelSource` or `SeaTunnelSink`\n* Define configs using `Option`\n* Support parallelism via `SourceSplitEnumerator`\n* Avoid connector-specific logic leaking into engine or core\n\n### Zeta Engine\n\n* **Client**: Submits job config\n* **Master**: Schedules & coordinates\n* **Worker**: Executes tasks (Source → Transform → Sink)\n\nRespect task boundaries and lifecycle semantics.\n\n## Configuration (Option) Rules\n\n* All user-facing configs MUST be defined using `Option`\n* Each option MUST include:\n    * name\n    * type\n    * default value (if applicable)\n    * clear description\n* Option names are **stable contracts** and must not be renamed lightly\n\n## Error Handling & Logging\n\n* Exceptions MUST include sufficient context (table, task, config key)\n* Avoid swallowing exceptions\n* Use proper log levels:\n    * INFO  – lifecycle events\n    * WARN  – recoverable issues\n    * ERROR – task-failing errors\n* NEVER log sensitive information (passwords, tokens, credentials)\n\n## Documentation Rules\n\n* Any user-visible change MUST update:\n\n    * `docs/en`\n    * `docs/zh`\n* Config names, defaults, and examples MUST match the code exactly\n* Documentation is part of the feature, not an afterthought\n\n## Testing Guidelines\n\n### Unit Tests\n\n* Located under `src/test/java`\n* Validate behavior, not implementation details\n* Prefer deterministic and minimal tests\n\nCommand:\n\n```bash\n./mvnw test\n```\n\n### E2E Tests\n\n* Located in `seatunnel-e2e`\n* Uses Testcontainers\n* Extend `TestSuiteBase`\n\nCommand:\n\n```bash\n./mvnw -DskipUT -DskipIT=false verify\n```\n\n## Performance Awareness\n\nAgents MUST consider performance implications:\n\n* Avoid unnecessary object creation in hot paths\n* Be cautious with large in-memory buffers\n* Consider parallelism and resource usage\n\n## PR Scope Rule\n\n* Keep changes minimal and focused\n* Avoid unrelated refactors or formatting-only changes\n* One PR should solve **one problem**\n\n## Running & Debugging\n\n### Build from Source\n\n```bash\n./mvnw clean install -DskipTests -Dskip.spotless=true\n```\n\n### Install Connectors\n\n```bash\nsh bin/install-plugin.sh $current_version\n```\n\n### Run Job (Zeta)\n\n```bash\nsh bin/seatunnel.sh --config config/v2.batch.config.template -e local\n```\n","category":"root","tokens":1809}]}