SeaTunnel AI CLI 设计思路解析多智能体与分层校验如何把自然语言变成可运行的配置【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelSeaTunnel AI CLI 是内置在 SeaTunnel 主仓库seatunnel-cli模块中的自然语言配置生成工具你用中文或英文描述一个数据同步任务它会生成一份经过校验、可直接投产的 SeaTunnel HOCON 配置。本文聚焦该工具的核心设计文档 docs/zh/ai-cli/design.md深入拆解其多智能体 分层校验流水线为何优于单次 LLM 调用并结合仓库源码agents.py、connectors.py、skills.py、memory.py还原每一层的真实实现。读完后你将理解这套系统的意图识别、连接器知识注入、三级校验与自动修复机制并据此判断该工具在什么场景下值得信任、什么场景下需要人工复核。为什么不是一次 LLM 调用SeaTunnel 配置生成本质上是一个领域 DSL 问题模型需要输出的不是自然语言而是结构严格、选项精确的 HOCON 配置文件。设计文档明确列出了四类单次生成无法可靠处理的失败模式150 连接器、每个 20–50 个选项没有任何模型对每个选项名、类型和约束拥有完整且最新的知识。连接器选项随版本演进模型记忆必然滞后条件选项依赖许多连接器存在仅当某选项取特定值时另一批选项才合法的规则。例如文件类 sink 中 text 格式专属的选项出现在 PARQUET 格式配置里会直接导致运行时类型不匹配错误DAG 接线语义plugin_output/plugin_input路由标签必须在 source / transform / sink 块之间精确配对。多源、多 sink、带 transform 的宽 DAG 中任何一条标签悬空或重复都会让数据流断掉或串流模式推断CDC 源必须是 STREAMING 模式有界源如 JDBC 全量查询不应携带流式专属选项如checkpoint.interval、start_mode等。这需要基于场景语义的推断而非选项堆砌。因此AI CLI 采用三条与单次生成截然不同的策略用权威连接器元数据为模型接地prompt 中的每条选项知识都来自引擎而非模型记忆、对每一份候选配置做确定性校验结论由解析器和引擎给出LLM 从不担任裁判、用真实报错驱动修复修复 Agent 拿到的是实际校验输出和引擎堆栈而不是凭空猜测。多智能体流水线Planner → Config → Validator → Fix/Repair设计文档给出了完整的流水线图实际实现位于 agents.py由Orchestratoragents.py统一协调用户输入自然语言 │ ▼ ┌─────────────────┐ ┌──────────────────────┐ │ Planner Agent │───▶│ 连接器知识库工具 │ │ 意图识别 │◀───│ │ │ 必要时追问 │ └──────────────────────┘ └────────┬────────┘ │ 结构化计划 ▼ ┌─────────────────┐ │ Config Agent │ 生成 HOCON 配置 └────────┬────────┘ ▼ ┌─────────────────┐ ┌──────────────────────┐ │ Validator Agent │───▶│ 本地校验 │ │ │ │ 引擎 --check │ └────────┬────────┘ └──────────────────────┘ │ 通过 ── 是 ─▶ 输出并自动保存 │ 否最多 3 轮 ▼ ┌─────────────────┐ │ Fix Agent │ 修正错误重新校验 └─────────────────┘ 后续 /check 或 /run 失败时 ▼ ┌─────────────────┐ │ Repair Agent │ 诊断真实引擎/运行时报错修补配置 └─────────────────┘Planner Agent意图分类与连接器选择Planner 负责三类意图分类新建管道输出PLAN:前缀、提问/诊断输出CHAT:前缀、错误诊断用户粘贴日志或堆栈时永远按 CHAT 处理。它的系统提示词PLANNER_SYSTEM明确要求只有在用户明确请求创建/修改管道配置时才输出PLAN:其余一切问候、概念提问、错误日志、配置审查都走CHAT:只在没有合理默认值时才通过ask_user工具追问。Planner 内置了默认假设并行度默认 2、job.mode按上下文推断CDC/Kafka → STREAMING否则 BATCH、端口用标准默认值MySQL 3306、PostgreSQL 5432、Kafka 9092、主机优先取记忆中的值否则 localhost安全红线绝不在配置中写入真实密码/API Key/Token一律用${MYSQL_PASSWORD}这类环境变量占位。规划阶段通过工具调用循环tool-use loop访问连接器知识库Planner 可用的工具定义在 agents.pylist_connectors列出全部连接器、get_connector_info按 connector_name connector_type 查详细选项、route_connectors按用户文本做关键词路由、validate_config校验 HOCON、ask_user追问缺失的关键信息。工具循环最多 5 轮。Config Agent基于注入元数据编写 HOCONConfig Agent 的系统提示词CONFIG_SYSTEM_TEMPLATE把克制写成了硬规则极简主义只包含 ALWAYS Required 选项和关键 Optional 选项不要把所有可能的选项都加上以防万一——多余选项会造成运行时错误选项位置source 与 sink 的选项集不同严禁把 sink 专属选项放到 source 块上反之亦然必须带connector_type调用get_connector_info获取类型专属选项元数据即唯一事实来源严格使用元数据返回的选项名不发明选项名尊重类型string/boolean/list检查[aliases: ...]中的别名条件选项仅当触发条件实际匹配时才包含。生成结束后配置从响应中通过正则提取_parse_config_response支持hocon、、conf三种代码块以及无代码块时从env {开始的裸配置回退解析。若检测到配置含硬编码凭证还会追加安全警告。Validator Agent确定性检查 LLM 语义审查校验是双轨的_run_validator本地确定性校验validate_hocon见下文校验管道一节LLM 语义审查把配置凭证先替换为占位符连同本地校验结果一起交给 Validator Agent。其系统提示词VALIDATOR_SYSTEM按严重度排序条件选项不匹配、source/sink 选项混用、缺失必填项、HOCON 语法错误、选项类型不匹配为 FAIL 级STREAMING 缺少checkpoint.interval、缺少env块为警告级。输出PASS/PASS_WITH_NOTES/FAIL。Fix / Repair Agent真实报错驱动修补校验失败后Orchestrator 在最多 3 轮内循环执行校验 → 修复 → 再校验process_user_input。修复的关键设计是在原配置上修补而不是从头重新生成。Fix Agent 收到的 prompt 包含当前配置 校验错误列表并明确要求修复所有问题保持其余正确部分不变_run_fix。生成阶段之后如果用户在交互会话里执行/check或/run失败Repair Agent 会拿到真实引擎报错seatunnel.sh --check的输出、REST API 提交结果或作业失败堆栈同样在原配置上做最小修补。这个闭环正是真实报错是最好的提示词这一原则的落地。连接器知识库两级解析让选项知识保持准确连接器元数据是整套系统的接地基础。设计文档指出它采用两级解析实现在 connectors.py运行时 API运行中 SeaTunnel 引擎的 option-rules 接口GET /option-rules?typesourcepluginFakeSource始终最新。获取顺序为内存缓存 → 实时 API → 磁盘缓存_fetch_option_rules。API 底层调用的是 Java 侧的factory.optionRule()与 SeaTunnel Web 同源内置元数据connector_metadata.json通过 Java 运行时反射SeaTunnelMetadataExporterPluginDiscoveryoptionRule()从引擎导出随 CLI 打包包含 source/sink/transform 的必填/可选选项、条件选项组when/equals/then_require和取值约束value constraints。查找路径支持$SEATUNNEL_METADATA_JSON显式覆盖、CLI 包内、数据目录、$SEATUNNEL_HOME等_get_runtime_metadata_paths。两级之间由fetch_connector_metadata统一收敛优先运行时 API回退运行时 JSON返回结果带source字段标明数据来自哪一级。Prompt 按请求动态组装关键设计是Prompt 只注入 Planner 选中的连接器元数据条件选项按触发条件显式分组——这是对抗模型编造选项、误放选项最有效的单项措施。格式化函数format_metadata_for_prompt把元数据组织成四段ALWAYS Required必须包含完整细节含类型、默认值、别名、取值集合Conditional仅当format text时包含row_delimiter、text_save_mode…这类按触发条件分组列表Key Optionalusername/password/query/table_path 等重要选项带类型Other Optional其余选项的紧凑 key 列表控制 token 预算。由于选项可能带 Java 完整类名如java.lang.String转换时会剥离包名前缀归一化为string、boolean、enumX等简洁类型对 Java 源码里描述过弱的常用 keyurl、bucket、driver通过_DESCRIPTION_ENRICHMENTS补充了格式提示如bucket必须以s3a://开头、JDBC URL 必须包含数据库名——这些补充是通用格式事实而非连接器专属业务规则。三层生成策略在元数据之上Skill 框架skills.py叠加了三层生成策略由SkillRouter按触发器打分匹配、SkillExecutor组装增强 promptbuild_enriched_prompt层级来源作用Skill 场景手册seatunnel-cli/seatunnel_cli/skills/ 下的 8 个 Markdownbatch_sync、cdc_realtime、conditional_routing、cross_database、data_quality、file_etl、multi_pipeline、transform_chain提供场景剧本领域知识、SOP、约束、HOCON 模式模板黄金样例seatunnel-cli/seatunnel_cli/golden_examples/ 下已验证的 source→sink 配对模板如 kafka_clickhouse、mysql_cdc_starrocks提供已知能跑的结构参考连接器元数据connectors.py 按需拉取权威选项规则约束选项名与类型流水线展开时还有两道关键逻辑expand_pipelinesskills.py会把多表 单表 sink的管道按表拆分成多条子管道多表原生 sink 如 Jdbc/Doris/StarRocks/Paimon/Iceberg/Hudi 除外见 connectors.py 的_MULTI_TABLE_SINKSllm_check_missing_info会用快速模型判断哪些必填选项用户尚未显式或隐式提供只在真正缺失时才追问用户以mysql -h host -P port -uuser mydb这类命令行形式提供的信息也能被识别为已提供。关键词路由KEYWORD_ALIASES把mysql映射到[Jdbc, MySQL-CDC]、把s3映射到[S3File, S3Redshift]中文关键词实时同步 → CDC/Kafka、增量 → CDC/Jdbc、全量 → Jdbc也在其中。校验管道从 HOCON 语法到真实执行的三级递进设计文档给出了校验管道的三层结构其中第一层本地校验的核心实现是validate_hocon阶段方式能抓住什么1. 本地校验HOCON 语法、结构、必填项对照元数据、路由标签配对、未解析的${VAR}占位符字段级豁免file_name_expression中的${now}等引擎模板变量不误报、安全检查语法错误、缺失/未知选项、接线错误2. 引擎 dry-runseatunnel.sh --check/--dry-run static—— 引擎的真实解析路径插件可加载性、选项类型、未知 key、DAG 拓扑3. 真实执行/run走 REST API 或seatunnel.sh一切运行时问题连接、schema、CDC 前置条件validate_hocon内部各检查项的源码细节很能说明设计取舍结构检查缺env块告警推荐设置job.mode和并行度、缺source/sink块直接报错、花括号不配对报错HOCON 解析用 pyhocon 解析失败即报错连接器选项校验对多连接器场景如两个同名Jdbc块pyhocon 会错误合并用原始文本的花括号计数逐个提取连接器块再校验_extract_connector_blocks_raw这是多管道配置正确校验的关键技巧条件选项不匹配检查_check_conditional_mismatches读取元数据中的条件组若配置里出现了某条件选项但触发条件未满足报条件不匹配错误——这类问题正是运行时类型不匹配报错的主要来源枚举值还做了大小写不敏感比较路由标签配对_validate_routing_pairsplugin_output重复报错、plugin_input找不到对应 output 报错、悬空 output 给警告。该检查独立于 pyhocon任何配置都会执行STREAMING 模式检查job.mode STREAMING时必须设置checkpoint.interval否则告警占位符检查${ENV_VAR}未在环境变量中解析则报错——但做了字段级豁免file_name_expression里的${now}、${uuid}、${transactionId}以及partition_dir_expression里的${k0}${v0}这类引擎模板变量不误报agents.py而同样的变量名出现在 URL、凭证等无关字段中仍会被诊断为环境变量安全检查检测硬编码密码password xxx并建议改用环境变量、检测空字符串值。第二层引擎 dry-run 由dry_run_config实现本地校验通过后把配置写入临时文件调用sh seatunnel.sh --check --config tmp30 秒超时返回码为 0 即 PASS若引擎 REST API 在运行默认http://localhost:5801可用SEATUNNEL_API_BASE覆盖见 connectors.py还会尝试第三阶段。三层逐级递进任一层失败都会把该层的真实报错喂给修复循环。设计原则设计文档把整条流水线的取舍浓缩为四条原则接地不轻信prompt 里每一条连接器知识都来自引擎元数据运行时 API 或反射导出的 JSON不依赖模型记忆。对应实现就是两级元数据解析 按请求动态组装确定性校验LLM 修复结论由解析器和引擎给出LLM 只负责生成与修复从不担任裁判。这也意味着所有判定门见下文基准测试都是确定性的没有LLM 当裁判的环节真实报错是最好的提示词修复 Agent 接收实际校验输出和堆栈。实测证明结构化、具体的错误信息比原始噪声的修复成功率高得多——这正是 Fix/Repair Agent 与生成阶段分开设计的原因默认安全生成的配置对所有凭证使用${ENV_VAR}占位Config Agent 系统提示词里的 SECURITY 硬规则会话存储脱敏/remember拒绝敏感值。这些在 memory.py 中有完整实现redact_credentialsmemory.py用多组正则Anthropic/OpenAI API Key、AWS Access Key、Slack token、GitHub/GitLab PAT、JDBC URL 内嵌密码等清洗文本MemoryStore.add在写入前用contains_credential做安全闸门命中凭证模式的记忆直接拒绝memory.py会话保存前对完整对话历史做脱敏_redact_conversation_history记忆注入 prompt 前还做了防 prompt injection 的清洗_sanitize_for_prompt。凭证在发送给 LLM 之前也会先替换为${_CRED_N_}占位符、修复完成后再还原避免密钥经模型中转。用数据说话不靠假设这套架构由专门的基准测试持续度量100 个任务20 简单 45 中等 35 复杂覆盖 12 个 ETL 场景类别含 10 个中文任务和 18 个针对已知 LLM 错误模式的规则探针、多层判定门L1 静态 HOCON 解析 连接器元数据 断言L3 真实执行 在官方apache/seatunnel镜像中对真实 MySQL/PostgreSQL/Kafka/ClickHouse/Elasticsearch 运行作业批任务看退出码、流任务看 60 秒健康存活、覆盖7 个大模型。基准工程随仓库发布在 seatunnel-cli/benchmark/100 个声明式任务、分层判定门、Docker 数据环境、报告生成器。基准结果直接驱动改进路线——连接器知识注入、修复循环的结构化错误解析都是从数据中长出来的改进点。文档记录的核心发现是静态排名在真实执行下反转静态门冠军GPT-5.6 Terra93%在真实执行下衰减 -20 个百分点而静态门第三的 Claude Opus 4.8 以真实执行 85% 登顶——看着对和能跑是两种不同的模型能力这正是基准必须真实执行配置、并对只做静态检查就宣称准确率保持警惕的原因。修复循环的实测效果同样来自数据把真实引擎报错喂回修复 Agent可挽回约 47% 的运行时失败同一个模型修复结构化校验错误的成功率约为修复原始 Java 堆栈的 2 倍——证明修复循环下一步最有杠杆的改进是结构化错误解析而不是更聪明的模型。这也意味着任何对 prompt、元数据或修复逻辑的修改都可以在同一任务集上做 A/B 对照基准测试保存带task_sha256指纹的结果用 compare.py 离线对比两份results.json把架构改进是否有效从直觉问题变成可量化问题。延伸阅读AI CLI 概览核心能力全景与安装方式发行版bin/seatunnel-ai.sh或 pip 源码安装快速开始四种 LLM 提供商配置AWS Bedrock / Anthropic / OpenAI 兼容 / OrcaRouter、bedrock-mantle端点、单发与交互模式以及/check、/run、/connectors、/remember、/sessions、/resume等常用命令模型基准测试7 个模型的实测准确率、模型行为画像一次写对型 / 迭代修复型 / 修复失能型与选型建议以及 Doris/StarRocks 目标端、PostgreSQL-CDC、条件路由、宽 DAG 等已知弱场景。需要说明的是模型与 CLI 都在持续演进文档中的基准数字是特定时间点的快照对于弱场景聚类涉及的管道形态条件路由拆流、PostgreSQL-CDC 前置配置、Doris/StarRocks 选项生产使用前建议对生成的配置做人工复核。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考