Apache SeaTunnel LLM Context Guide 详解：让 AI Agent 安全、一致、可验证地参与数据集成项目开发

Apache SeaTunnel LLM Context Guide 详解：让 AI Agent 安全、一致、可验证地参与数据集成项目开发

【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel

Apache SeaTunnel 作为一款多模态、高性能、分布式的海量数据集成工具，其代码库横跨连接器、引擎、转换插件、翻译层与 E2E 测试等大量模块。为了让 LLM / AI Agent 在参与 SeaTunnel 开发时能够做出安全、一致、可验证的修改，仓库在根目录提供了 GEMINI.md（LLM 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 Format（AOSP 风格）做代码格式化，并提供了skip.spotless开关（pom.xml）用于在特殊场景下跳过格式化检查。也就是说，spotless:apply不仅是"整理格式"，它执行的是与 CI 中spotless-check相同的格式化规则——先在本地 apply，再通过verify让检查门禁通过，是 Agent 提交代码的"标准动作"。

Git 提交信息规范：[Type][Module] Description

SeaTunnel 对提交信息执行严格的格式约定，以维持干净、可检索的提交历史：

[Type][Module] Description

Type 类型：

• Feature– 新功能
• Fix– Bug 修复
• Improve– 对既有行为的改进
• Docs– 仅文档变更
• Test– 测试用例或测试框架变更
• Chore– 构建、依赖或维护性任务

Module 模块名（与仓库目录一一对应）：

Module	对应目录
Connector-V2	seatunnel-connectors-v2
Zeta	seatunnel-engine（Zeta 引擎）
Core	seatunnel-core
API	seatunnel-api
Transform-V2	seatunnel-transforms-v2
Format	seatunnel-formats
Translation	seatunnel-translation
E2E	seatunnel-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-ui（Web UI）；config 目录存放了 seatunnel.yaml、hazelcast.yaml 等默认配置；docs 下按en与zh双语组织。Agent 在定位改动点时，应先依据该地图判断"我的改动属于哪个 Module"，这直接决定了提交信息的[Module]前缀。

Java 代码标准：格式、导入、可空性与可见性

格式化：Google Java Format（AOSP）

SeaTunnel 由 Spotless 强制执行Google Java Format（AOSP 风格）。根 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 List<SourceSplit> 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 → Sink）

Agent 应尊重任务边界与生命周期语义：不要跨越进程边界共享状态，不要绕过生命周期钩子（如 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 -DskipIT=false verify

TestSuiteBase在源码中确有实现：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.spotless=true

注意这里通过-Dskip.spotless=true跳过 Spotless 检查，用于加速本地构建；但提交前仍需按指南第一部分运行spotless:apply。

安装连接器

sh bin/install-plugin.sh $current_version

从源码看，bin/install-plugin.sh 会根据 config/plugin_config 中选中的连接器列表下载插件 jar，默认版本为3.0.0，并支持通过环境变量SEATUNNEL_PLUGIN_DOWNLOAD_METHOD（https或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 仓库中做任何贡献，都应遵循以下"提交前自检清单"：

1. 验证先行：运行./mvnw spotless:apply与./mvnw -q -DskipTests verify，本地跑./mvnw test；
2. 提交规范：按[Type][Module] Description书写提交信息；
3. 代码标准：Google Java Format（AOSP）、无通配符导入、优先 shaded 依赖、注释覆盖公共 API 与生命周期钩子；
4. 合规：新文件带上 ASF License 头；
5. 兼容：不删改 Option、不破坏 SPI，不兼容变更必须写入 incompatible-changes.md 并给出迁移方案；
6. 测试：单元测试验证行为，E2E 测试基于 Testcontainers 继承TestSuiteBase；
7. 文档：用户可见变更同步更新 docs/en 与 docs/zh；
8. 聚焦：一个 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