ARTICLE · 1230747
离线数仓开发插件拆解第二篇 | 离线数开流水线的四层架构
目录
• 一条命令为什么不能直接改状态[2] • 命令层负责发起，不负责放行[3] • 状态机只记录事实和允许的走法[4] • 硬门把证据挡在工具调用之前[5] • 执行引擎负责落产物和连接外部系统[6] • 一次 P3 到 P4 的推进怎样走完[7] • 四层分开的实际代价和边界[8]
一条命令为什么不能直接改状态
离线数开流水线常用一条命令推进阶段。
1 ddp.py advance --ticket T-0002 --phase 4 --reason "P3 出口"
命令看起来很简单，目标从 P3 改成 P4，写进状态文件就结束了。真要让模型这样做，问题会马上出现。P3 的设计、DDL、ETL、调度任务和开发环境回执到底齐不齐，谁来判断。测试计划还没写好，阶段能不能先过去。人工确认还没完成，命令能不能先把状态改掉。
流水线的做法是把这些问题拆给四个位置处理。命令层负责把人的动作翻译成一次明确请求，状态机负责记住当前阶段和允许的走法，硬门负责检查这次动作和这一阶段的出口，执行引擎负责调用平台、读写产物并留下记录。四层共同完成一次阶段推进，任何一层都能拒绝继续。
下面这张图是它们在一次动作里的关系。
这张图里没有“模型说自己已经做完”这一步。模型可以发起命令、编写产物、根据报错修复，阶段能不能过只看状态、文件和机器回执。
命令层负责发起，不负责放行
命令层是使用者最常接触的一层。setup 建立运行时，submit 创建工单，sds-design 做数据概要设计，start 进入研发态，advance 推进阶段，status 查看门控缺口。不同宿主会提供斜杠命令或技能入口，底层调用的是同一个引擎。
这一层主要做三件事。它把用户的意图整理成带参数的命令，给模型说明当前阶段应该做什么，再把执行结果和失败原因显示出来。比如 start 会要求先选运行模式、落模式台账、创建工单目标，然后才进入准入门。advance 会带上工单编号、目标阶段和推进理由。
命令提示词能统一做法，靠它做安全控制并不可靠。模型可能漏掉一个检查，也可能把失败解释成通过。因此，命令层写“必须检查”之后，硬门还要独立检查一次。命令层可以换宿主、换措辞，门控和执行流程不跟着重写。
状态机只记录事实和允许的走法
状态机把一张工单现在走到哪里，收在 _state.json 里。这个文件记录当前阶段、已完成阶段、运行模式、难度定级、SDS 状态、是否等待确认、转场日志和门控上下文。_context.md 是给人看的镜像，机器状态仍以 _state.json 为准。
状态机的规则很窄。前向推进只能从当前阶段走到下一阶段，P3 不能一步跳到 P5。每一次前向转场都要先跑当前阶段的出口门，通过后把当前阶段加入 completed，再更新 current_phase。回跳需要显式带上允许回跳的参数和原因，而且不会重复追加完成记录。工单完成后，状态机会拒绝新的转场。
这套规则解决的是上下文漂移。会话可以关掉，模型可以换一个，开发者隔几天回来，当前阶段仍然从文件里读，不靠上一轮聊天的记忆。状态机也不判断内容写得好不好，它调用阶段出口门，根据返回结果决定是否保存转场。
状态文件由引擎写入。开发者直接调用写文件工具修改 _state.json、_context.md 或自动决策日志，会命中状态写门。把 verify_result、self_check_result 或 user_confirmed 直接用 ctx set 改成通过，也会被拒绝。这三个受保护键只能通过 evidence verify、evidence selfcheck 和 evidence confirm 写入，这几个命令会先检查真实产物和确认记录。
硬门把证据挡在工具调用之前
硬门分成两个时点。工具执行前，PreToolUse 可以返回阻断决定，直接拦下命令或写文件动作。工具执行后，PostToolUse 已经无法撤销刚才的写入，它负责重新检查产物，把结果写成可机读的上下文键，同时给模型一条修复提示。
工具执行前的门会检查动作发生的条件。没有初始化项目，直接调用平台命令行会被拦下。工单还在 P2，提前创建数据任务会被拦下。awaiting_confirmation=true 时，生产命令和交付物写入会被锁住，避免人在确认期间同时改文件。发布动作缺少 [已确认发布] 标记，或者改动过的任务没有生成差异页，也会被拒绝。
工具执行后的门负责补上结果。SQL 文件刚写进工单目录，校验器会重新跑 SQL 规则，并把结果写进 sql_compliance_result。test_runs.json 写入以后，测试证据会重新对照报告和账本，结果进入 test_evidence_ok。部署计划写完，同样会经过格式和参数检查。
这些上下文键会被下一次硬门读取，校验和阻断因此能连起来。
1 写入产物 -> PostToolUse 校验 -> 写 context 键 -> PreToolUse 读取并决定放行
出口门是另一组检查。它以当前阶段为输入，读取该阶段应该存在的文件，再调用对应的验证器。P1 检查设计字段、字段映射、验证证据和确认条件。P2 检查架构文档、链路图和交付表清单。P3 检查 SQL、自检结果、执行回执和交付清单。P4 把报告里的成功用例与 test_runs.json 的机器记录逐条比对。每一道门返回问题列表，只有 FAIL 或 HALTED 会阻断，WARN 留给人和模型判断。
门控不靠提示词。SQL 文件里没有来源血缘，执行账本里没有当前脚本对应的 query_id，生产发布没有确认标记，这些条件都能被代码直接判断。判断依据放在产物、状态和运行账本里，模型换了表达方式也不会改变结果。
执行引擎负责落产物和连接外部系统
执行引擎是命令落地的地方。它解析子命令和参数，先把状态读写交给状态机，再让验证器运行阶段出口门。连接器负责访问任务单、数据平台、质量系统和知识库，文件和目录的创建、执行回执的落盘、交付摘要的生成也由这一层完成。
可替换的连接器把外部平台挡在流程之外。mock 模式把工单、平台任务、执行回执和知识索引写到本地目录，适合检查完整流程。live 模式按执行器注册表选择数据库直连、命令行客户端或平台命令行适配器，再通过环境配置决定连接哪个环境。
真跑证据在这一层生成。platform run-sql 执行一段 SQL，拿到 query_id 后，把执行时间、环境、证据级别和 SQL 内容指纹一起写进运行账本。后续验证时，门会同时检查 query_id 是否存在、证据有没有过期、脚本内容有没有变。换了一份 SQL 却拿旧回执过关，会在内容指纹对不上时失败。
执行引擎还负责把流程产物放进正确目录。工单目录里保存设计、架构、SQL、测试、部署、确认记录和交付文件，运行目录保存执行账本、模式台账和缓存。模型可以编辑工单目录里的业务产物，机器状态和引擎目录有独立写门。这样即使换了宿主，也不会把不同工单的执行回执混在一起。
一次 P3 到 P4 的推进怎样走完
回到开头那条 advance --phase 4。
命令层先把工单、目标阶段和原因交出去。工具调用前，硬门读取当前状态，确认工单确实在 P3，接着检查交付清单和进入测试阶段前的条件。条件不满足时，命令不会执行，返回的是一组具体缺口。
硬门放行后，执行引擎再次检查同类条件，并调用 P3 的阶段出口门。SQL 规则、开发环境回执、脚本内容和当前版本是否一致，会在这一步重新核对。通过后，状态机把 P3 追加到 completed，把 current_phase 改成 4，并写一条带时间、来源和原因的转场记录。
如果门没通过，状态保持不变。模型看到的是缺失项，不是“已进入 P4，但好像还少点东西”。下次修复产物后重新推进，仍然从 P3 开始检查。
P4 完成测试后，测试报告和 test_runs.json 还要经过报告与证据的一一比对。只有成功用例都有对应执行编号，P4 到 P5 的推进才有依据。执行引擎在这一段既是动作的执行者，也是证据的保存者。
这个例子说明四层并没有做重复劳动。命令层管意图和展示，状态机管顺序，硬门判断条件和证据，执行引擎完成动作并落盘。每层能回答的问题不同，把它们合在一处，失败时就很难说清是命令写错了、状态乱了，还是平台真的没有执行成功。
四层分开的实际代价和边界
拆开后，宿主和平台都更容易替换。命令入口可以服务于不同宿主，数据平台可以按执行器注册表接入，状态机和阶段门不必跟着改写。重新进入一条旧工单时，状态、设计和执行账本都能从文件恢复，交接不依赖谁记得上一轮对话。
代价是配置项变多。项目要先初始化，模式和执行环境要写清楚，宿主的 hook 启动器必须可用。尤其是 hook 启动失败时，宿主可能按放行处理，表面上看流程还在工作，硬门却没有生效。因此部署后要单独检查启动器，不能只看命令是否能运行。
这些门能确认某个动作在何时发生，某份文件是否被执行过，某次发布有没有拿到确认。它们不能替你确认业务口径一定正确，也不能保证所有真实平台都能被同一个适配器完整覆盖。live 模式仍然依赖现场配置、权限、网络和平台返回契约，mock 跑通只证明流程本身成立。
下一篇进入 P1，数据概要设计。会讲 verify 和 generate 两种模式怎样选，八条硬规则检查什么，以及为什么设计结论一定要贴回工单，成为后续阶段共同读取的契约。
项目地址 MrSuiChuan/data-development-pipeline[1]许可证 Apache-2.0
引用链接
[1] MrSuiChuan/data-development-pipeline: https://github.com/MrSuiChuan/data-development-pipeline
重磅开源 | 离线开发插件 data-development-pipeline 架构与流程说明
继续开源 | 实时数仓开发插件 realtime-data-pipeline 架构和流程说明
