多仓项目如何用 Harness 保持交付一致

一个产品拆成前端、客户端、网关、服务和自动化测试后，最危险的不是仓库数量，而是每个仓库都“各自完成”，最终却没有形成可交付的组合。Harness 的职责不是统一语言和构建工具，而是统一范围、顺序和证据。

图：提供方先于消费方，组合验证通过后才更新根版本指针；点击查看原图。

先建立职责地图

根协调仓只保存仓库清单、固定版本、协作规则和验证入口，不复制业务源码。每个子仓继续遵守自己的依赖、测试与发布规范。再为每个仓库维护一份轻量 Profile：它负责什么、向谁提供接口、依赖谁、最低验证是什么、版本号从哪里取得。

这样做的价值是让 Agent 在开始前先回答“真正受影响的是哪些仓库”，而不是因为不了解系统就把所有仓库初始化、更新和测试一遍。

提供方先于消费方

跨仓变更按“契约提供方 → 消费方 → 端到端验证 → 根版本指针”推进。例如服务先发布兼容接口，客户端再切换调用，自动化测试最后覆盖组合路径。任一上游没有通过原生测试，下游就不应假装进入集成阶段。

最关键的门禁

子仓本地提交并不等于可交付。更新根仓版本指针前，必须证明该提交已经存在于约定远端目标分支；如果通过 PR 交付，还要确认 PR 已合入，而不是只创建了页面。根仓永远最后更新，避免他人拉取后得到无法获取的子仓提交。

可执行检查

列出本次验收条件对应的仓库与契约。
逐仓记录基线提交、工作区状态和原生验证。
按依赖顺序完成提交与远端可达性证明。
只更新发生变化的版本指针。
在干净环境做一次最小初始化，确认组合可复现。

验收结果至少包含每个仓库的精确版本、真实测试结果、未执行项和剩余风险。

第二轮实践复核

可复用交付物： 仓库职责矩阵、依赖顺序图和可达提交清单。这些内容是从工程实践抽象出的通用方法，不包含内部仓库、真实工作项、业务数据、凭据、地址或实现源码。

最低验收： 逐仓证明“原生验证通过 → 远端目标分支可获取 → 根指针最后更新”。验收记录必须分开事实、推断、缺口和授权范围；只读检查不能自动扩展为提交、推送、评论或发布。

用版本矩阵冻结一次交付

delivery: REL-2026-08-22-01
repositories:
  contract:
    sha: "<sha-a>"
    remote_ref: "origin/main"
    verify: "make test-contract"
  service:
    sha: "<sha-b>"
    depends_on: ["contract@<sha-a>"]
    verify: "go test ./..."
  web:
    sha: "<sha-c>"
    depends_on: ["contract@<sha-a>", "service-api=v2"]
    verify: "npm test"

命令来自各仓 Profile，根 Harness 不用一个通用命令替代原生验证。矩阵还应记录工具链与锁文件摘要，使“同一个 SHA”不会因外部依赖漂移产出不同结果。

依赖图决定并行，不靠仓库列表顺序

契约兼容检查通过后，互不依赖的消费方可以并行验证；服务提供方失败时，所有下游节点标记 blocked 而不是继续跑出一堆无意义错误。循环依赖说明版本边界有问题，应先引入兼容层或拆成两阶段发布。

门禁	检查	失败行为
范围	验收条件映射到仓库	不扫描/修改无关仓库
基线	SHA、remote、工作区状态	保留用户修改并停止
契约	提供方新旧兼容	阻断消费方切换
可达	SHA 可从权威 ref 获取	不更新根指针
组合	干净环境按矩阵初始化	不宣称可交付

失败恢复

为每个节点保存状态：planned、running、verified、published、failed，以及输入摘要。重试只重跑输入未变化的失败节点；上游 SHA 变化后，下游验证全部失效。外部发布动作绑定 delivery ID 与仓库 SHA，重复恢复不会二次创建发布。

演练提供方 PR 未合入、一个仓库凭据缺失、远端被 force-push、根指针提前更新和组合测试失败。回滚按依赖反序执行：先关闭消费方新能力，再恢复提供方；数据迁移独立处理。最终用全新 clone 只依据根提交和矩阵重建，才算交付闭环。

公开规范

Git Submodules

规范复核日期：2026-08-22。

小规模演练

从一项只涉及两个仓库的兼容变更开始：先画依赖顺序，再分别运行原生验证，最后在隔离 clone 验证根指针。

失败注入： 故意提供一个缺字段、过期版本或无权限目标，确认流程停在预定门禁。
观测指标： 远端不可达提交数、无关仓库变更数、组合验证失败数。
回滚方法： 任何提供方未验证或提交未进入目标分支时停止；根仓保持原指针即可回退。