Julep Golden Corpus 深度解析:用哈希钉扎守护跨语言线格式契约

原创2026-10-08 21:46:561,883 阅读
文章标签:AI AgentAgent 框架后端

Julep Golden Corpus 深度解析:用哈希钉扎守护跨语言线格式契约

Julep 用一套名为 golden corpus(黄金语料)的测试套件,把 Python 前端编译产物——冻结 IR JSON、工具清单(manifest)、校验诊断、shape 投影与快照哈希——钉扎为不可漂移的跨语言线格式契约。本文以 tests/golden/ 包为主线,讲解这套语料的组成、钉扎内容、确定性双断言机制,以及何时、如何安全地再生成语料,帮助你在修改 IR 或哈希逻辑时避免静默破坏兼容性。

为什么需要 Golden Corpus:Python 是规范前端,线格式由语料守护

Julep 的架构将"作者态"(Python 中的 seq/par/alt/each 等流式 DSL)与"线格式"(冻结后的 JSON)解耦:一旦 deploy(...) 冻结出 Deployment,其 flow_json()、manifest_json()、artifact_hash() 就成为可发布、可校验、跨语言复用的产物。规范 §13(见 specification.md 的 "13. Golden corpus (cross-language contract)" 一节)明确指出:

Because Python is canonical and other frontends are deferred, the wire format is preserved by a language-neutral golden corpus — the conformance suite any future frontend MUST pass.

也就是说,未来任何其他语言的前端(Rust、Go、TypeScript……)只要想产出与 Julep 兼容的线格式,就必须通过这套语料的一致性校验。因此 README.md 的第一句话就是"the files in this package pin the §13 golden corpus as the cross-language wire-format contract"——这不是普通的回归测试,而是一份可执行的规范。

语料包结构:tests/golden/ 五个文件的职责分工

tests/golden/ 目录包含五个互相配合的文件,构成一条"构建 → 快照 → 再生成 → 校验"的完整流水线:

文件 职责
fixtures.py 定义 §13 要求的全部 fixture 构建器,产出 GoldenFixture(可部署的流程 + 快照 + 能力清单)
snapshot.py 对单个 fixture 做规范化快照:生成 canonical JSON 与五类派生哈希
regenerate.py 从当前构建器重新生成 golden_hashes.json,支持 --update 写回
test_golden.py 双断言:fixture 构建确定性 + 与已提交钉扎值的已知值比对
golden_hashes.json 提交入库的钉扎值(每个 fixture 一组哈希 + shape 值 + 工具哈希计数)

钉扎什么:一个 fixture 的完整快照载荷

snapshot_fixture()(snapshot.py)对每个 fixture 依次执行 fixture.deploy()、validate(deployment.flow, deployment.manifest)、manifest_to_json(...) 与 shape 折叠,产出如下 payload:

payload: dict[str, Any] = {
    "name": fixture.name,
    "flowJson": deployment.flow.to_json(),          # 冻结后的 IR JSON
    "manifestJson": manifest_json,                  # 工具清单 JSON
    "toolHashes": sorted(deployment.manifest),      # 清单中的工具哈希键
    "capabilities": _capability_json(fixture.capabilities),
    "validateDiagnostics": [...],                    # 校验诊断(code/message/nodeId/severity)
    "deployDiagnostics": [...],                     # 部署诊断
    "shapes": shape_json,                            # surface/closed shape 投影
}

README 强调"钉扎值会在 IR、manifest JSON、diagnostics、shape projection 或 snapshot hashing 变化时失败",这正好对应 payload 的五个哈希组件:

哈希键 计算对象 含义
flowJson payload["flowJson"] 冻结 IR 的结构漂移
manifestJson payload["manifestJson"] 工具契约/清单漂移
validateDiagnostics payload["validateDiagnostics"] 校验诊断漂移
shapes payload["shapes"] shape 投影漂移
snapshot 整个 payload 上述任意一项变化的最终哨兵

哈希算法在 snapshot.py 中是严格规范化的:

def canonical_json(value: Any) -> str:
    """Strict canonical JSON for tests; non-JSON values should fail loudly."""
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)

def _sha256_json(value: Any) -> str:
    return "sha256:" + hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()

sort_keys=True + separators=(",", ":") 保证任何语言实现只要按同一规则序列化,就能得到字节完全一致的输入——这正是"跨语言契约"成立的前提。键带 sha256: 前缀便于肉眼识别哈希类型。

16 个 fixture:从 §13 必选项到 record-binding 扩展

规范 §13 要求至少覆盖:simple pipeline · subagent firewall · race · quorum · hedge · human gate · staged plan · agent app · frozen manifest · capability manifest。FIXTURE_BUILDERS(fixtures.py)在此基础上额外加入了 each_fanout 与五个 record_binding_*,共 16 个:

fixture 名 构建器要点(源码摘录)
simple_pipeline seq(call(mcp("srv","extract")), call(mcp("srv","summarize")))
subagent_firewall seq(call(parent_read), sub("child.agent", Contract.agent()), call(parent_summarize))
each_fanout seq(call(list_items), each(call(process_item), max_parallel=4))
race race(call(primary), call(replica)),并带 CapabilityManifest
quorum quorum(vote_a, vote_b, vote_c, k=2)
hedge hedge(call(near), call(far), hedge_ms=50)
human_gate seq(human_gate(timeout_s=60), call(record_approval))
staged_plan stage("planner.reasoner"),空快照
agent_app app("support.controller"),空快照
frozen_manifest 原生工具 native_index(ToolContract(Effect.READ, Idempotency.NATIVE))混排 MCP 工具
capability_manifest 含 budget、reasoners、memory 的完整能力清单
record_binding_straight/cond/each/inline/external_rename 用 @flow 装饰器书写的真实调用绑定变体,覆盖 cond/each/内联与外部重命名

每个 fixture 由 GoldenFixture 封装(fixtures.py),其 deploy() 以 strict=False 部署,以便语料能钉住"含告警但可部署"的状态,同时保留 skip_reason 字段用于记录"文档化跳过"——regenerate.py 会拒绝钉扎任何被跳过的 fixture,从机制上杜绝"欠覆盖"。

record_binding 变体为什么值得单独钉扎

_record_* 系列(fixtures.py)把"记录字段绑定"这一易错点做成 5 个显式变体:直线绑定、cond 分支内绑定、each 体内绑定、内联子流程绑定、跨流程外部重命名。以 record_binding_external_rename 为例,它在一个流程内调用另一个流程的返回值,再与外部上下文字段拼接调用 record_lookup。这类数据流重命名如果发生 IR 级漂移,只有钉扎比对能第一时间发现。

双重断言:确定性 + 已知值

test_golden.py 用 pytest 参数化遍历全部构建器,做两层检查:

  1. 确定性(test_golden_fixture_is_deterministic):同一构建器实例化两次,canonical_json 与 hashes 必须完全一致——防止哈希逻辑依赖全局状态或时间。
  2. 已知值(test_phase4_known_value_hashes):snapshot.hashes 必须等于已提交的 GOLDEN_HASHES[name],payload["shapes"] 必须等于 shapeValues,工具哈希数量必须等于 toolHashesCount。

正如规范 §13 所述:"The golden hashes MUST be asserted as known values (not merely 'deterministic')",确定性断言只能证明"今天和昨天一致",已知值断言才能证明"和提交时一致"——任何无意触碰 IR 或哈希逻辑的重构都会立刻红。

shapeValues:closed 与 surface 双投影

钉扎不仅包含哈希,还直接内联了 shape 投影结果。_shape_json()(snapshot.py)对流程树每个节点记录 op、id、closed 与 surface 两个 shape。以 golden_hashes.json 中的 each_fanout 为例:

"shapeValues": {
  "nodes": [
    { "closed": "Dataflow", "id": "$",     "op": "seq",  "surface": "Dataflow" },
    { "closed": "Pipeline","id": "$.L",   "op": "prim", "surface": "Pipeline" },
    { "closed": "Dataflow", "id": "$.R",   "op": "each", "surface": "Dataflow" },
    { "closed": "Pipeline","id": "$.R.B", "op": "prim", "surface": "Pipeline" }
  ],
  "root": { "closed": "Dataflow", "surface": "Dataflow" }
}

两个投影的语义在 julep/shapes.py 的模块文档中有权威解释:surface_shape 是"父调度器看到的形状"(Sub 对外是单个调度单元,计为 Pipeline),closed_shape 是"预算与准入看到的形状"(Sub 会揭开自身契约形状,隐藏的 Agent 也要按 Agent 收费)。两者都是纯结构折叠,满足 join 半格(par >= Dataflow、alt >= Branching、app == Agent 等),因此可以在不执行流程的前提下做可判定计算。钉扎这两个投影,等于把预算/准入语义也纳入了线格式契约。

再生成:只有线格式有意变更时才允许

README 给出的再生成命令是:

python -m tests.golden.regenerate --update

其实现位于 regenerate.py:build_golden_hashes() 按字典序遍历 FIXTURE_BUILDERS,跳过带 skip_reason 的 fixture(有跳过则整体抛 RuntimeError),对每个 fixture 调 snapshot_fixture 并写入 flowJson/manifestJson/validateDiagnostics/shapes/snapshot 五个哈希 + shapeValues + toolHashesCount;render_golden_hashes() 以 json.dumps(indent=2, sort_keys=True) 输出,保证文件本身也是规范化的。--update 标志决定是写回 golden_hashes.json 还是仅打印到 stdout(不带 --update 时可当作"预览再生成"使用,非常适合先看 diff 再落盘)。

CONTRIBUTING.md("The golden corpus is a contract"一节)给出了配套纪律:

  • 只有 IR、manifest JSON、diagnostics、shape projection 或 snapshot hashing 有意变更时才能再生成;
  • 必须把 golden_hashes.json 的 diff 作为格式变更的一部分提交审查;
  • 如果某个钉扎值意外移动,停下来调查,而不是"顺手更新"。

红线:计划文档中的 "golden corpus must not move"

仓库内大量 RFC 计划把"黄金语料不得移动"当作改动是否触碰线格式的判据,这是最实用的开发守则:

  • docs/plans/2026-06-29-ws5-object-first-reasoners.md:think(obj, …) 只改变作者态,必须降级成与字符串写法完全相同的 ThinkStep(reasoner=obj.name)——"If a golden hash changes, stop — something lowered differently."
  • docs/plans/2026-06-29-ws4-onramp-switch-on.md:switch_on(...) 必须产出与手写 switch(...) 相同的 IR,"the golden corpus must not move for existing flows"。
  • docs/plans/2026-06-11-code-as-data-distribution.md:arr 静态参数与 Ann 重试字段"缺省即缺省(absent-when-unset)",保证语料不动。
  • docs/plans/2026-06-29-ws3-teaching-errors.md、docs/plans/2026-06-07-prompt-renderers.md:错误路径与渲染器新增键都以"add keys only when present"约束语料不动。

反过来,docs-site/content/docs/concepts/model.md 把语料定位为"冻结 IR 不是 Python 实现细节"的证明,docs-site/content/docs/internals/typed-flow-calculus.md 则记录了"每个阶段都以 JSON 相等性做闸门、黄金语料逐阶段保持不变"的落地过程。开发者在任何重构前,先跑一遍 python -m pytest tests/golden(或 ca test),就能在 CI 之前确认线格式是否被无意触碰。

小结:把语料当作可执行的跨语言规范

tests/golden/ 包的价值不在于"测了几个 fixture",而在于它把"跨语言线格式契约"从文字规范变成了可执行断言:fixtures.py 定义覆盖矩阵,snapshot.py 定义规范化与哈希,regenerate.py 定义受控再生成,test_golden.py 把已知值钉进 CI。对贡献者而言,理解这套机制意味着两件事:修改 IR、manifest 或哈希逻辑时,先看钉扎是否意外移动;确需变更线格式时,走 python -m tests.golden.regenerate --update 并连同 diff 一起审查,让每一次格式演进都留下显式、可审计的痕迹。

登录后查看全文
julep