workflow_module_integration_protocol
道-方法 · 道层 skill 全文
本页是 <code>rules/skills/drafts/workflow_module_integration_protocol.md</code> 的逐字投影（仅隐私清洗，零改写）。
时点提示：本页是仓内文件 rules/skills/drafts/workflow_module_integration_protocol.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。
报告元数据（frontmatter）
name: workflow_module_integration_protocol
description: 标准化模块接入协议 v0.1——模块自描述契约（MODULE.md）为中心，规定注册/调用/留痕/测试/依赖版本五件事，容纳实现态与设计态模块共存
type: Workflow（道层/治理）
status: draft (Beta) — 晋级前需 ≥1 个真实模块端到端跑通协议校验（P5 eval_harness 集成验证）
created: 2026-07-04
version: 0.1.0 (draft)模块接入协议 v0.1（道·治理）
一句话
每个模块（工具/skill/adhoc program）拥有自己的一份契约文件 MODULE.md，声明它是什么、怎么被调用、怎么留痕、怎么被测试、依赖什么；中央目录只是从这些契约派生的投影，不是权威源；成熟度差异（已实现/设计态/仅占位）由契约内容本身承载，不靠单独的分类表。
何时用
新建一个工具/skill/program 模块、要让它被别的模块正式引用、或要登记它"将来会被怎么接入"时，写一份 MODULE.md。既有模块补契约同理。跨模块调用、留痕、测试集成的具体做法见下文"协议五件事"。
不做什么（边界）
- 不管运行时 agent 授权（谁能读什么、禁读什么、grant/handoff 怎么传）——那是
workflow_agent_communication_protocol的职责，本协议是系统契约层（模块与模块之间的静态契约），两层不共用一套 schema。 - 不替代 gate 执行配置——gate 类模块的执行细节（entrypoint/regulator/exit_codes）真源仍是
gate_manifest；MODULE.md 只放指针，不复制。 - 不建中央权威目录——v0.1 阶段不建单一 manifest 文件汇总所有模块；见"占位契约机制"一节的理由。
- 不规定模块内部实现——契约只管对外可见的接口面（owned_decision/interface_surface/essential_outputs 等），不管模块内部怎么写代码。
协议五件事
契约分两层：静态注册契约（本节，模块自己拥有）＋运行时调用信封（第 2 件事，复用既有 grant/Charter，不新造）。
1. 如何注册（登记面 + 字段）
登记面 = 模块自有目录下一份 MODULE.md（工具模块放 tools/<m>/MODULE.md；设计态 program 模块放 adhoc_jobs/<program>/MODULE.md）。frontmatter 载机读字段（schema_version: module-1 起），正文载人读契约。
静态契约字段与何时必填（精简 take/leave 理由）：
| 字段 | 必填条件 | 一句话理由 |
|---|---|---|
module_id | 总是 | 聚合根 identity，外部唯一引用锚，不穿透内部 |
capability_class | 总是 | 能力类别（如 test_evaluation/context_collection/requirement_analysis），设计态模块靠它先占坑 |
maturity | 总是 | implemented / design_only / placeholder，解"模块未实现也要模块化"与"现在就要协议"的张力（见下节） |
contract_version | 总是 | 契约自身版本，供 depends_on pin |
owned_decision | implemented | 深模块的"secret"——它封装的那个易变决策，一行说清楚 |
interface_surface | implemented | 对外最小入口（CLI 签名/callable/artifact 契约）；gate 类模块此字段指向 gate_manifest 行，不复制 entrypoint/exit_codes |
essential_outputs | implemented | 他人可消费的持久结果契约；禁列内部临时文件——跨模块只应引用 essential state，不应读另一模块的缓存/中间产物 |
depends_on | implemented | 显式依赖声明，带 contract_version pin；依赖不能是"agent 记得怎么调"的隐性知识 |
receipts | implemented | 声明它发哪些 tool 名到 trace 总线 |
test_contract | implemented | provider 契约测试路径 + e2e 路径 |
paired_skill | implemented | 治理它的 dao/shu skill |
context_assumptions | implemented | 本模块对输入/环境的假设——把运行时耦合（环境变量、目录结构假设等）从"接入时的运行时惊喜"变成声明字段，这是本协议信息密度最高、价值最大的字段 |
verified_against | implemented | 输出已针对哪些 oracle/契约/证据验证过 |
design_only/placeholder 模块只需填 module_id/capability_class/maturity/schema_version/contract_version + 一个对齐触发条件（见"占位契约机制"），不填 interface_surface/essential_outputs（尚无实现，填了即冒充）。
两个字段不进静态契约，留给运行时信封：repair_request（契约不匹配时的修复动作）、clarification_needed（首次接入/跨版本触发澄清）——它们是运行时失败响应，不是静态声明。
2. 如何被调用（运行时信封）
按 module_id 引用，不穿透内部实现。调用复用既有 dispatch_helper() + Charter（scope_in/forbidden_read/tool_grant），不新造调用层。运行时信封复用 workflow_agent_communication_protocol 的 grant/handoff（may_read/forbidden_read/output_contract/named_inputs）承载：调用方声明的 context_assumptions（它对被调模块的假设）+ repair_request（消费方发现契约不匹配时发，不是裸错误码）+ clarification_needed（首次接入或跨版本时触发协调者，不静默假设兼容）。消费方只读被调方 essential_outputs 声明的结果契约，禁解析其内部临时文件。
3. 如何留痕（接 receipts 总线）
复用统一 trace bus（contexts/tool_receipts/receipts.jsonl），沿用既有行 schema。模块 receipts 字段声明它发的 tool 名前缀。不新建第二条 trace 总线——自定义 trace 格式曾因不兼容仓库校验器酿成事故，这是已发生过的教训，不要重蹈。
4. 如何被测试（provider 契约测试 + e2e 分离）
模块交 provider 契约测试（证接口如声明工作，含畸形/超范围输入行为）＋ 登记 e2e（真实场景集成）。这是本协议与测试能力模块（eval_harness）的接口：eval_harness 既是一个待接入模块（自己也要填 4.1 契约），又是测试能力的提供者（别的模块经它做 e2e）。
5. 如何声明依赖与版本
depends_on 带 contract_version pin；模块自身带 contract_version；路径变更走 reference_validator.py rename 的 CASCADE 机制，不手改引用。设计本身即分阶段传输的通信，允许占位契约（下节），不必一次到位。
占位契约机制
这条机制解的张力：一边是"模块尚未完全实现也要坚持模块化 mindset"，另一边是"协议现在就要能覆盖所有已知模块"。两者不矛盾——用成熟度分档化解：
- 实现态模块（
maturity: implemented）：给完整契约，4.1 全字段填满。 - 设计态/占位模块（
maturity: design_only或placeholder）：给占位契约——module_id+capability_class+ 一条将来对齐义务（alignment_trigger：什么条件满足后回来补interface_surface/essential_outputs），不填实现字段。
占位契约的唯一硬义务：声明将来它会以什么 module_id 被引用、大致属于哪个能力类别、一条可核验的对齐触发条件。这样协议第一版就能对所有已知模块登记，而不必等它们全部实现完才纳入。
复用不重造（扩展谁 / 指向谁 / 绝不平行复制谁）
| 既有资产 | 关系 | 单一真源纪律 |
|---|---|---|
gate_manifest（工具路径查 tools/INDEX.md） | gate 类模块的 interface_surface/test_contract 指向其行；gate_manifest 仍是 gate 执行配置（entrypoint/regulator/exit_codes）SSOT | MODULE.md 不复制这些字段，只放指针 |
plan_loader schema | phase 类工作的 MODULE.md 指向其 plan.yaml；协议复用其字段词表（entry_criteria/exit_criteria/expected_outputs/depends_on/skill_injection） | 不替换 plan_loader，phase 契约仍是 phase 执行真源 |
Charter + dispatch_helper() | 第 2 件事的运行时调用信封直接复用 | 不新造调用层 |
tools/INDEX.md | module_id → 路径 解析默认走 INDEX.md | MODULE.md 不硬编码兄弟模块路径，按名引用 |
workflow_agent_communication_protocol | 运行时 agent 授权层复用它；本协议是系统契约层（新层） | 两层不共用一套 schema，各自的文档里写清楚边界 |
reference_validator | 校验器复用其依赖图 + CASCADE 改名 | — |
登记面裁定（各归属唯一位置，不平行复制）：
- 协议 spec（本文件）——治理纪律的家在 skill 系统，不另起平行 spec 位置。
- 每模块契约 →
<module_dir>/MODULE.md（authored 本质态）。 - 校验器 →
module_registry（工具，路径查tools/INDEX.md），镜像既有 gate check.py 的形态：校验 frontmatter 合规。 - 派生中央目录 → v0.1 明确延后；≥2 个
implemented模块接入后再建为 GENERATED 投影，不 authored、不平行复制。
验收标准
一个没有任何上下文的 agent，拿这份 MODULE.md 就能判断它合规与否：
schema_version精确等于module-1。maturity∈{implemented, design_only, placeholder}，没有第四个值。maturity: implemented时，4.1 表中标"implemented"的字段全部非空。essential_outputs不含临时文件路径（如/tmp/*、worker workdir 内部产物）——只列他人可长期依赖的持久产物。depends_on每一条都带版本 pin，不是裸模块名。maturity为design_only/placeholder时，只填五个总是必填字段（module_id/capability_class/maturity/schema_version/contract_version）+alignment_trigger，且不得填interface_surface/essential_outputs（这是防占位冒充实现的关键检查）。
以上标准由配套工具机械核验，见下节；agent 自己判断时也应按这张清单逐条过，而不是凭感觉判断"看起来像那么回事"。
配套工具
module_registry 的校验器（按名引用，工具路径查 tools/INDEX.md）对上述验收标准做机械校验，输出 PASS/FLAG + 逐条可定位缺陷（字段名 + 期望 + 实际）。新写或修改一份 MODULE.md 后，跑一次该校验器确认合规。
已知陷阱
本 skill 是全新 draft，尚无自身的真实踩坑记录。但协议设计本身吸取了一条已发生的失效前车：gate_manifest 曾试图作"中央注册表"覆盖全部 gate，结果绝大多数行长期停留在"已登记但未真正驱动执行"的状态——注册 ≠ 强制。这是本协议选择"模块自描述契约为中心、中央目录只做延后的派生投影"而非"扩大中央 manifest"的直接原因，写在这里提醒：任何试图把本协议改回"先建一个大 manifest 再登记"的提案，都要先回答"如何不重蹈这条覆辙"。
claim ceiling
observational——本协议是纸面设计 + 4 个契约实例（1 个 implemented + 3 个占位态），尚未经过运行时真实调用验证。首个真验证 = 一个模块（eval_harness）真实端到端集成跑通该协议后的运行时观测。晋级前禁止声称"协议已验证 / production-ready"，也禁止声称"四个模块已接入"——占位态模块只是登记了将来怎么接，不是可调用状态。