Apache SeaTunnel LLM Context Guide 详解让 AI Agent 安全、一致、可验证地参与数据集成项目开发【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelApache SeaTunnel 作为一款多模态、高性能、分布式的海量数据集成工具其代码库横跨连接器、引擎、转换插件、翻译层与 E2E 测试等大量模块。为了让 LLM / AI Agent 在参与 SeaTunnel 开发时能够做出安全、一致、可验证的修改仓库在根目录提供了 GEMINI.mdLLM Context Guide作为给 AI 助手的上岗手册。本文以该指南为骨架结合仓库真实源码与配置系统讲解 Agent 在 SeaTunnel 中提交代码前必须遵循的验证流程、提交规范、代码标准、架构约束与测试要求帮助读者无论人类开发者还是 AI Agent在提交 PR 前一次性做对。变更前必读验证命令是硬性门槛指南的第一条红线是Agent 必须在本地运行验证命令之后才能建议或敲定任何改动。这是为了让 LLM 生成的代码在进入评审前就通过 SeaTunnel 的质量门禁否则大概率导致 PR 被拒。# 格式化代码强制 ./mvnw spotless:apply # 快速验证强制 ./mvnw -q -DskipTests verify # 单元测试强烈推荐 ./mvnw test这三条命令与仓库根目录 pom.xml 中的实际构建配置相互印证SeaTunnel 使用 Spotless Maven 插件spotless-maven-plugin版本见 pom.xml配合Google Java FormatAOSP 风格做代码格式化并提供了skip.spotless开关pom.xml用于在特殊场景下跳过格式化检查。也就是说spotless:apply不仅是整理格式它执行的是与 CI 中spotless-check相同的格式化规则——先在本地 apply再通过verify让检查门禁通过是 Agent 提交代码的标准动作。Git 提交信息规范[Type][Module] DescriptionSeaTunnel 对提交信息执行严格的格式约定以维持干净、可检索的提交历史[Type][Module] DescriptionType 类型Feature– 新功能Fix– Bug 修复Improve– 对既有行为的改进Docs– 仅文档变更Test– 测试用例或测试框架变更Chore– 构建、依赖或维护性任务Module 模块名与仓库目录一一对应Module对应目录Connector-V2seatunnel-connectors-v2Zetaseatunnel-engineZeta 引擎Coreseatunnel-coreAPIseatunnel-apiTransform-V2seatunnel-transforms-v2Formatseatunnel-formatsTranslationseatunnel-translationE2Eseatunnel-e2e正确示例[Fix][Connector-V2] Fix MySQL source split enumeration bug [Fix][Zeta] Fix checkpoint timeout under heavy backpressure [Feature][Transform-V2] Add LLM transform plugin [Improve][Core] Optimize jar package loading speed [Docs] Update quick start guide仓库结构导航先认路再动手指南给出了面向 Agent 的仓库结构地图标注了各模块的职责其中 seatunnel-connectors-v2 被明确标注为主要贡献区域Source 与 Sink 连接器seatunnel/ ├── seatunnel-api/ # 核心 API 定义 ├── seatunnel-connectors-v2/ # Source Sink 连接器主要贡献区域 ├── seatunnel-transforms-v2/ # Transform 插件含 LLM ├── seatunnel-engine/ # Zeta 引擎与 Web UI ├── seatunnel-core/ # 任务提交与 CLI 入口 ├── seatunnel-translation/ # Flink Spark 适配器 ├── seatunnel-formats/ # 数据格式JSON、Avro 等 ├── seatunnel-e2e/ # 端到端集成测试 ├── docs/ # 文档en 与 zh └── config/ # 默认配置从源码结构看这一布局与实际的 Maven 多模块工程完全吻合seatunnel-engine下同时包含 seatunnel-engine-uiWeb UIconfig 目录存放了 seatunnel.yaml、hazelcast.yaml 等默认配置docs 下按en与zh双语组织。Agent 在定位改动点时应先依据该地图判断我的改动属于哪个 Module这直接决定了提交信息的[Module]前缀。Java 代码标准格式、导入、可空性与可见性格式化Google Java FormatAOSPSeaTunnel 由 Spotless 强制执行Google Java FormatAOSP 风格。根 pom.xml 中googleJavaFormat配置即为此规则的落地。Agent 生成或修改 Java 代码后必须运行./mvnw spotless:apply而不是凭 LLM 的记忆手工排版。导入规范禁止通配符导入no wildcard imports优先使用shaded 依赖org.apache.seatunnel.shade.*这一规则与 SeaTunnel 的隔离依赖策略相关——为避免依赖冲突SeaTunnel 将常用第三方库 shade 到自身命名空间下详细背景可参考 connector-isolated-dependency.md。可空性与可见性可空性避免隐式的 null 假设不依赖这里应该不会为 null的直觉可见性保持 API 最小化能 package-private 就优先 package-private不随意暴露 public 成员注释要求重要方法必须添加注释包括公共 API、生命周期钩子初始化、start/stop、checkpoint、复杂或性能关键的逻辑。指南给出一个典型范例——Source 分片枚举方法/** * Enumerates source splits for parallel reading. * Called once during job initialization. * * param context Split enumeration context * return Collection of discovered splits */ Override public ListSourceSplit enumerateSplits(SplitEnumerationContext context) { // Implementation }这一签名与 seatunnel-api 中的SeaTunnelSource/SourceSplitEnumerator接口设计一致是 Connector V2 并行读取的关键入口详见下文架构指南。ASF License 头新增文件的强制要求所有新增文件必须包含 Apache Software Foundation 的 License 头这是 Apache 项目的硬性合规要求/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the License); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */在仓库中无论是 Java 源码、shell 脚本还是 HOCON 配置文件均以该头文件开头例如 bin/install-plugin.sh 与 config/v2.batch.config.template。Agent 新建任何类型文件时都应将此头原样带上且不要在 License 头与代码之间插入无关内容。向后兼容不可逾越的硬约束指南用 强调Agent 必须把向后兼容视为硬约束。不得删除或重命名已有的配置项Option不得随意修改默认值不得破坏公共 API 或 SPI 契约任何不兼容变更必须被显式记录在docs/en/introduction/concepts/incompatible-changes.md该文件确实存在于仓库incompatible-changes.md提供迁移指南在 PR 描述中清晰说明原因这条规则对 LLM 尤其关键LLM 在重构时倾向于顺手改名或顺手改默认值而在 SeaTunnel 中Option 名称是稳定契约连接器配置一旦发布就有大量线上任务依赖它随意改名会直接破坏用户作业。依赖规则非必要不引入不得引入不必要的新依赖优先使用org.apache.seatunnel.shade.*下已有的 shaded 依赖任何新依赖必须在 PR 描述中说明理由并考虑shading、体积、冲突风险SeaTunnel 对依赖体积和冲突极其敏感——连接器以 jar 形式分发并由用户独立加载引入冗余依赖会显著增大安装包并引入类加载冲突。相关背景可参考 connector-isolated-dependency.md。架构指南Connector V2 与 Zeta 引擎Connector V2三层职责清晰实现SeaTunnelSource或SeaTunnelSink接口使用Option定义配置项通过SourceSplitEnumerator支持并行度避免把连接器专属逻辑泄漏到引擎或 core 中在源码层面这三个接口都定义在 seatunnel-api 模块中SeaTunnelSource.java、SeaTunnelSink.java、SourceSplitEnumerator.java。这意味着连接器只依赖seatunnel-api这层抽象契约引擎与连接器之间的边界由 SPI 强制隔离——Agent 在写连接器时不应去 import engine 或 core 的内部类。Zeta 引擎Client / Master / Worker 三段式Client提交作业配置Master调度与协调Worker执行任务Source → Transform → SinkAgent 应尊重任务边界与生命周期语义不要跨越进程边界共享状态不要绕过生命周期钩子如 checkpoint、initialize直接操作资源。配置Option规则从随手写死到契约化指南要求所有面向用户的配置必须用Option定义且每个 Option 必须包含name名称type类型default value默认值如适用clear description清晰描述Option 名称是稳定契约不得轻率重命名。在源码中Option类位于 seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/Option.java配套的Options工具类与OptionRule校验规则也在同一包下。这一设计让连接器的每个配置项都具备类型安全、默认值与校验能力配置解析逻辑HOCON则位于 seatunnel-config 模块。Agent 开发连接器时应通过Option声明参数并配合OptionRule做必填/可选约束而不是在代码中手动解析字符串。错误处理与日志可诊断性优先异常必须携带足够的上下文表、任务、配置键避免吞异常不要 catch 后静默使用正确的日志级别INFO– 生命周期事件WARN– 可恢复问题ERROR– 导致任务失败的错误绝不记录敏感信息密码、令牌、凭据对 Agent 而言这条规则的现实意义是生成的代码在出错时应让运维人员看日志即知问题出在哪个表、哪个任务、哪个配置键而不是打印一个干巴巴的Exception。文档规则文档是功能的一部分任何用户可见的变更必须同步更新 docs/en 与 docs/zh配置名、默认值、示例必须与代码完全一致文档不是事后补充而是功能交付的一部分这与 SeaTunnel 的文档体系直接相关仓库对连接器文档有专门的格式规范见 docs-format-specification.md并有工具脚本用于同步文档tools/documents/sync.sh。Agent 改配置、改行为时最容易犯的错就是代码改了文档没改或文档示例与代码不一致——这两者都会被评审直接打回。测试指南单元测试与 E2E 测试单元测试位于各模块src/test/java下验证行为而非实现细节优先编写确定性、最小化的测试./mvnw test例如Option的单元测试就位于 seatunnel-api/src/test/java/org/apache/seatunnel/api/configuration/OptionTest.java。E2E 测试位于 seatunnel-e2e 模块使用Testcontainers启动真实依赖数据库、消息队列等测试类继承TestSuiteBase./mvnw -DskipUT -DskipITfalse verifyTestSuiteBase在源码中确有实现seatunnel-e2e/seatunnel-e2e-common/src/test/java/org/apache/seatunnel/e2e/common/TestSuiteBase.java。每个连接器在 seatunnel-e2e/seatunnel-connector-v2-e2e 下都有对应的-e2e子模块例如 Kafka 的 connector-kafka-e2e。Agent 新增或修改连接器时应同时补充 E2E 测试并扩展对应TestSuiteBase子类确保真实环境下的连通性。性能意识热路径上的三思Agent 必须考虑性能影响避免在热路径上创建不必要对象谨慎使用大内存缓冲区考虑并行度与资源占用这条对 LLM 尤其重要LLM 生成的代码倾向于每行都 new 一个对象用流式 API 链式处理这在数据量每秒数百万条的数据集成场景中是灾难。生成代码时应优先复用对象、避免在循环内做昂贵操作。PR 范围规则一次 PR 解决一个问题保持改动最小且聚焦避免无关重构或纯格式化改动一个 PR 只解决一个问题结合提交规范Agent 应保证 PR 标题与内容严格对应[Type][Module]中描述的那一个问题——混入无关改动会显著增加评审负担并被要求拆分。运行与调试从源码构建到跑通一个任务从源码构建./mvnw clean install -DskipTests -Dskip.spotlesstrue注意这里通过-Dskip.spotlesstrue跳过 Spotless 检查用于加速本地构建但提交前仍需按指南第一部分运行spotless:apply。安装连接器sh bin/install-plugin.sh $current_version从源码看bin/install-plugin.sh 会根据 config/plugin_config 中选中的连接器列表下载插件 jar默认版本为3.0.0并支持通过环境变量SEATUNNEL_PLUGIN_DOWNLOAD_METHODhttps或maven与SEATUNNEL_MAVEN_REPOSITORY控制下载方式与仓库地址bin/install-plugin.sh。运行任务Zeta 引擎本地模式sh bin/seatunnel.sh --config config/v2.batch.config.template -e local在源码仓库中启动脚本位于 seatunnel-core/seatunnel-starter/src/main/bin/seatunnel.sh发行包安装后会统一出现在bin/目录下。该脚本显式支持-e local/--deploy-mode local参数见 seatunnel.sh即以本地模式运行 Zeta 引擎。-e local对应的配置模板 config/v2.batch.config.template 是 Agent 本地调试最常用的冒烟测试配置它演示了完整的env / source / sink三段式结构env { # You can set SeaTunnel environment configuration here parallelism 2 job.mode BATCH checkpoint.interval 10000 } source { # This is a example source plugin **only for test and demonstrate the feature source plugin** FakeSource { parallelism 2 plugin_output fake row.num 16 schema { fields { name string age int } } } } sink { Console { } }FakeSource生成 16 行模拟数据name字符串、age整数Consolesink 打印到控制台——不依赖任何外部系统即可验证插件装配与引擎调度是否正确。Agent 调试连接器或引擎改动时建议先用它跑通本地链路再进入 E2E 测试。结语Agent 协作的黄金清单综合全文AI Agent 在 SeaTunnel 仓库中做任何贡献都应遵循以下提交前自检清单验证先行运行./mvnw spotless:apply与./mvnw -q -DskipTests verify本地跑./mvnw test提交规范按[Type][Module] Description书写提交信息代码标准Google Java FormatAOSP、无通配符导入、优先 shaded 依赖、注释覆盖公共 API 与生命周期钩子合规新文件带上 ASF License 头兼容不删改 Option、不破坏 SPI不兼容变更必须写入 incompatible-changes.md 并给出迁移方案测试单元测试验证行为E2E 测试基于 Testcontainers 继承TestSuiteBase文档用户可见变更同步更新 docs/en 与 docs/zh聚焦一个 PR 只解决一个问题改动最小且可验证。GEMINI.md 这份 LLM Context Guide 本质上把 Apache 项目的社区成熟实践格式化门禁、License 合规、向后兼容、PR 评审翻译成了 Agent 可执行的规则集。遵循它AI 生成代码就能从看起来能跑进化到符合项目规范、可被评审接受。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
