用途
Ship 用于发布已验证的工作,通过简洁、非破坏性的证据链完成公开。它可以创建、更新或提升拉取请求(PR),也可以只读地观察并采纳一个已公开的、当前 PR 元组无法真实表示的默认分支主题。Ship 永不执行合并。
Ship 是唯一的公开效果与发布证据所有者。Actuating 提供当前 Git 与验证事实;Ship 不要求 Actuating 的闭包回执、Construction 引用、Evidence head 或 Ledger 事件。
- 验证完整的工作 -> 就绪(ready)PR
- 未完成但有明确授权的工作 -> 草稿(draft)PR
主要能力
- 创建、更新、最终确定或提升拉取请求。
- 在 Actuating 显式交接时,只读观察已公开的默认分支主题(observe-existing)。
- 在 Actuating 显式交接时,采纳已公开主题(adopt-existing)。
- 管理 PR 正文中的受管区块,保留人工编写的内容。
- 执行公开变更与回读,确保发布声明与实时状态一致。
- 生成 Ship 回执(ship-record.md),包含完整不可变的发布证据。
使用方式
当用户要求创建、更新、最终确定或提升 PR 时,或当 Actuating 提供当前发布交接时,使用 Ship。
只有显式的 Actuating 交接才能选择 observe-existing 或 adopt-existing。直接的 Ship 请求使用 pull-request 路径。
对于 pull-request 路径,在任何推送或 PR 效果之前阅读 pull-request.md;它负责就绪状态、受管正文保留、变更顺序和回读。对于显式的 Actuating observe-existing 或 adopt-existing 交接,阅读 existing-publication.md;这些路径保持只读。所有路径都保留 Input、Receipts、Guardrails 和 Output。不要因为共享同一包就加载另一路径的流程。
输入结构(ship_input)包括:source(direct | actuation)、publication_route(pull-request | observe-existing | adopt-existing)、repository、base(branch、sha)、head(branch、sha)、existing_pr(exists、url、draft)、existing_publication(branch、head_sha、comparison_base_sha、publication_observation_ref、release)、validation(build、lint、tests、language_specific、acceptance 各为 pass | fail | missing | not-run)、task_state(complete、blocked、deferred、open)、proof_summary、actuation(goal_context_digest、review_contract_digest、review_context_digest、publication_required)、user_requested_pr_mode(ready | draft | update-existing | promote-draft | none)、repo_policy_pr_mode(ready | draft | unknown)。
直接发布省略 actuation。对于 Actuating 输入,精确的 repository、base/head、validation、task state 和 Goal context 是必需的。Ship 将 Actuating 绑定复制到其回执中,但从不将其解释为架构、审查、变更或闭包权威。
回执:阅读 ship-record.md。对于 Actuating 路径,返回完整的规范回执字节和 SHA-256 摘要。Actuating 将所有者签发的回执直接与当前 Git 和审查上下文比较,不将回执复制到工作流事件日志中。
适用场景
- 用户要求创建、更新、最终确定或提升 PR。
- Actuating 提供当前发布交接。
- 需要发布已验证完整的工作(生成就绪 PR)。
- 需要发布未完成但有明确授权的工作(生成草稿 PR)。
- 需要只读观察或采纳已公开的默认分支主题(仅限 Actuating 显式交接)。
限制
- 不要用于用户想要合并/落地的情况。
- 不要用于实现未完成且没有可接受的草稿理由的情况。
- 不要用于验证失败且没有可接受的注意事项的情况。
- 不要用于未请求发布/回读的情况。
- 绝不在没有验证证据或明确报告的限制下发布。
- 绝不在完整验证后默认创建草稿。
- 绝不创建重复的精确元组 PR。
- 绝不使用采纳来伪装变更或避免新的审查。
- 绝不覆盖受管区块之外的人工编写正文内容。
- 绝不在更新证据之前提升 PR。
- 绝不在没有匹配的实时回读的情况下声称发布成功。
- 绝不要求或合成 Actuating 闭包回执。
- 绝不选择架构、分类发现、计算审查信用、决定闭包或选择 Actuating 的下一步行动。
- 绝不合并或落地。
- 绝不暂存或提交无关工作。
输出
简洁地报告 PR 链接、结果公开状态、head 以及相关的验证或限制。当外围工作流需要该交接时,包含回执身份和下一个所有者。在 Ship 回执中保留完整的不可变发布证据;不要将其字段重复为强制聊天表单。