受治理的研发交付

这一页讲怎样让多个 Agent 在一个 GitHub 仓库 Workroom 里完成一次完整的研发交付：从需求、设计、实现、测试、独立 Review，一直到发布和上线后的健康检查，全部放在同一个有版本的计划里，每一步都有人或独立角色把关。

它的几个核心保证：

写代码和 Review 的必须是不同角色；
发布要单独授权：计划被批准，不等于任何一次具体发布被批准；
结果说不清就只查询，不重试：进程重启或响应丢失后，只去查原来那次操作的结果，不会重复发布；
发布失败不自动回滚：回滚是另一次需要授权的操作。

这是高级方案

它面向要自行装配 CI/CD 连接的部署者，需要编写可信的 Host 代码。默认的 IM 安装不包含这些能力；只想用 Agent 处理 Issue 和 PR 评论，读把 GitHub 仓库作为 Workroom 就够了。

文中常用术语：Effect 指一次对外部系统的副作用（如一次部署），Effect Ledger 是记录这些副作用的账本，Journal 是任务事实的事件日志。Workroom 本身的规则见 Agent 深入：Workroom Kernel。

可复用的入口

以下入口从 @zhin.js/agent/runtime 导出，供可信 Host 组合使用，不能直接暴露成模型可写的状态迁移工具：

入口	用途
`createSoftwareDeliveryPlan`	生成七阶段纯 Plan proposal；不执行模型，也不直接创建 Task facts
`createGitHubWorkroomCapability`	GitHub REST ref/草稿 PR 传输及查询恢复；注册到 `workroomGitHubCapabilityToken`
`workroomDeliveryProviderToken`	挂载特定 CI/CD 系统的可信 provider
`WorkroomDeliveryGateway`	核对 CI 证据、产物与环境，将部署及健康观察转换为 Effect receipt

createSoftwareDeliveryPlan 输入要求需求引用、非空验收条件引用、仓库、环境、七个阶段的角色/能力/尝试预算、Scheduler policy、Project/Profile authority 和 Sponsor。需求与验收条件必须是带 SHA-256 摘要的不可变引用。模板生成 requirements → design → implement → test → review → release → health；依赖沿用 Kernel 的 accepted 语义。实现和 Review 角色必须不同，真正的 principal 职责分离仍由验收权威执行。

生成 proposal 后，可信 planning adapter 必须通过现有 admitWorkflowPlan 接受计划；模板不会授予调用者项目权限。release 带计划层 Sponsor gate。这个 gate 只允许任务进入执行，不等于批准任何具体发布；发布仍须经过绑定 exact Effect Intent 的 P7 授权。

安装外部连接

按 GitHub Workroom 建立 Project、成员和仓库绑定。
在 generation Resource 中提供 Workspace Lease、分支保护权威、凭据端口和 P7 持久授权事实。凭据只能在可信 provider 内使用，不能进入 Plan、模型上下文或 Journal。
用 createGitHubWorkroomCapability({ credentials, binding }) 创建 GitHub provider，注册到 workroomGitHubCapabilityToken。GitHub Enterprise 可由 Host 固定配置 apiBaseUrl；请求禁止跟随重定向。每个 generation 创建自己的实例。binding 的 ref/digest 必须匹配 intent.capability；省略时 helper 使用自身 provider 身份。现有自定义 GitHub capability 必须补充显式 binding，缺失或错配会阻塞，不能沿用未绑定的宽泛授权。
发布连接按 WorkroomDeliveryProviderPort 实现并注册到 workroomDeliveryProviderToken。标准 installWorkroomEffectResources 已路由 delivery_release；缺 provider 时保留可恢复 blocker。
可信集成层用 workroomEffectIntentWriterToken 记录发布 intent；它只记录意图，不能授权或执行。既有后台 Effect runtime 调度和恢复执行。

GitHub REST provider 只发布已经上传到 GitHub 的 commit，不上传本地 Git objects，不自动合并 PR。ref 与 PR 操作都读取 immutable base/head 的实际 diff 并检查 path scope；无法证明完整 diff 时拒绝。需要本地 Coding Agent/CI worker 在受控 workspace 中生成并上传 commit。仓库原有的分支保护与可信租约仍是必要边界。

发布的精确契约

delivery_release 的参数为：

typescript

{
  kind: 'delivery_release',
  parameters: {
    repositoryId: 'github:owner/repo',
    headSha: '完整的 40 或 64 位 Git SHA',
    artifactDigest: 'sha256:构建产物的摘要',
    environment: 'staging',
    pipelineRef: '固定版本的发布流水线引用',
  },
}

此处展示字段形状，示意字符串不能作为有效摘要提交。完整 intent 还必须固定 candidate hash、provider capability、目标摘要、CI 证据引用/摘要、风险、幂等键和创建时间。

Provider 的三个方法各有明确职责：

inspect：只读查询 CI。返回当前 candidate、目标及产物、非空检查结果、证据引用/摘要和有效期。证据必须来自受信 CI，检查集合由可信 policy 固定；模型不能声明哪些检查已经通过。
dispatch：接收具体授权摘要、有效期、证据摘要和幂等键。外部执行端必须原子校验这些前置条件并去重，拒绝移动后的目标和过期授权。前置检查与真正执行之间的竞态不能仅靠本地先查询解决。
query：按原始 Effect/幂等键查询实际部署及健康结果。不能重发、回滚或创建另一条发布。

Gateway 会在准备和执行前重新检查证据。只有 status: succeeded 且 health: passed 才产生 committed；部署失败，或部署成功但健康检查失败，产生 failed；部署状态尚未确定时保持 outcome_unknown。观察必须绑定同一 Effect、candidate、commit、产物、环境和流水线；落后于已持久观察时间的回执被拒绝。

发布失败不自动回滚。回滚必须作为新的受授权副作用明确绑定原产物和目标，不能把失败回执当成回滚授权。

人工 Gate 与恢复

Reviewer 和 Sponsor 控制重新核对认证主体、当前 Assignment/candidate、Contract/Policy 和 deadline。授权查询结束后再检查当前时钟，避免长期无人操作或授权查询耗时导致过期审批生效。事件记录同一检查时间，重放不会使用今天的时钟改写历史。

Effect attempt 在外部写之前持久化。进程重启、dispatch 响应丢失或未知健康状态都只查询原操作。重复投递不分配第二次写权限；同一项目内不同 intent 不能复用幂等键。Unknown blocker 只提供 reconcile，不把已开始的操作显示为可无条件重试或取消。

运维人员通过现有 Workroom 状态/验收投影和 Effect blocker 查看阻塞、owner、deadline 和恢复动作。此方案没有新增独立 Console 页面；Kernel Journal 与 Effect Ledger 各自继续是任务事实与副作用事实的唯一来源。审计摘要用于完整性校验，不宣称抵御拥有存储写权限的攻击者。

可重复验收与边界

bash

pnpm check:delivery

验收覆盖真实 Kernel admission/调度/验收链、独立 Reviewer/Sponsor、拒绝过期和越权、文件 Journal 重启恢复、CI/产物/环境错配、未知结果仅查询、健康检查失败、GitHub HTTP 契约和统一 Host composition。

这些测试在本地运行，外部 GitHub/CI/CD 使用确定性 HTTP/typed provider fixtures。没有真实仓库、CI 配置、凭据和预发布环境的 smoke 结果，不能声称已完成实际生产交付。当前提供 GitHub ref/PR REST 连接和 CI/CD provider 接入契约；具体 CI/CD 产品的 provider、生产凭据管理及持续监控集成须由部署者装配。

下一步

把 GitHub 仓库作为 Workroom：先把仓库接入 Workroom
Agent 深入：Workroom Kernel：任务、分派、验收与 Gate 的规则

受治理的研发交付 ​

可复用的入口 ​

安装外部连接 ​

发布的精确契约 ​

人工 Gate 与恢复 ​

可重复验收与边界 ​

下一步 ​