mini-openclaw/docs/project-process/07-delivery.md

阶段 ⑦ 交付与发布（Delivery & Release）

定义：让当前结果在真实交付边界被接受——真实的评审、必需的 CI、合并、发布——且高风险动作有风险匹配的审批、副作用有可用的回滚/恢复路径。本地测试与 agent 一句"done"属于阶段 ⑥，不属于交付。 输入：⑥ 已通过的实现（验证记录 + 门禁结果 + 审查结论）。 输出：已接受的修订 + 构建/安装包 + 发布记录 + 审计。 进入下一阶段（⑧ 学习与沉淀）：交付边界接受完成、发布记录落档。

---

1. 要求（Requirements）

1.1 进入条件

• 阶段 ⑥ 全部质量门通过，无未解决阻塞项。

1.2 完成条件（DoD）

• 真实接受边界（合并/发布/部署）绑定到当前修订，有修订级决策证据（不是"跑过 CI"而是"这个 revision 合并了/发布了"）
• 每个高风险动作（发布、删除、生产数据、外发、签名）在副作用之前获得所需审批并留审计
• 实际副作用有风险匹配的回滚/恢复路径（回滚、恢复、重试、补偿、幂等重放、安全中止之一）且含 owner 与后置条件
• 发布记录（版本、变更、产物、验证）落档

---

2. 规则（Rules）

2.1 接受边界

编号	规则
R-7.1	真实边界证据：把真实接受决策绑定到当前修订与目标分支/环境。本地测试、自测、agent 完成声明均不是交付证据；外部边界打不开时记 Unobserved，不编造缺失的 PR/部署。
R-7.2	合并路径：改动经默认分支可比较的 diff 进入（分支/PR 或等价受控路径）；直接在默认分支开发、无可评审 base diff 属交付缺陷。
R-7.3	必需检查绑定：合并前必需检查对最终修订全绿，且与本地命令一致或有明确差异说明。

2.2 高风险审批

编号	规则
R-7.4	破坏性/特权/外部/不可逆/共享状态/凭据/发布/生产动作，在效果发生前取得所需的人或策略 owner 决策；安全拒绝 + 可用升级路径是正确的控制行为，不是失败。
R-7.5	高风险动作留审计：谁、何时、什么、批准人/策略、审计引用。
R-7.6	确认无高风险动作时记 N/A（须经检查证明），不允许无理由的 N/A 阻塞结果。

2.3 回滚与恢复

编号	规则
R-7.7	每个实际副作用有风险比例匹配的回滚/恢复路径，且绑定到受影响资源/入口/owner/后置条件。
R-7.8	回滚/恢复须可验证（安全模拟、演练、可比的保留任务或实际恢复结果）；禁止仅为提高证据强度而执行破坏性回滚。
R-7.9	恢复路径对失败与超时也要可运行（清理不得只在成功路径执行）。

---

3. 输出规范

3.1 发布流程（本仓）

发布链唯一权威：docs/release-process.md（ci-local 门禁 / release.mjs / 四包发布 / pack-audit / install-acceptance / 签名 / OTA）；签名细节 docs/release-signing.md；本地最短路径 docs/local-build-quickstart.md。以下为阶段 ⑦ 在本仓的落地步骤，任一步非零即中止。

Step 0  离线门禁（提交/合并/发布前必过）
        Windows: build\ci-local.ps1 · macOS/Linux: build/ci-local.sh → run-local-ci.mjs 八步：
        ① 删 release/ → ② npm ci 离线干净安装 → ③ npm run ci:check
        （build:verify:runtime → vitest 全量 → build）→ ④ playwright E2E（不重构建）
        → ⑤ electron-builder --publish never 打安装包 → ⑥ package:audit
        （asar 禁 dist/mac-*、release/、.map/.d.ts/.ts；体积预算 140 MiB）
        → ⑦ verify-packaged-app（extraResources 五件断言 + 真启动 5s 冒烟）
        → ⑧ write-build-report（逐产物 SHA-256 → build-report + SHA256SUMS）

Step 1  版本与变更（SDK 四包发布时）
        node scripts/release.mjs --registry <内网源URL> [--bump patch|minor|major]
          [--skip-publish] [--dry-run]
        九步编排：install → build（拓扑序 api→agent-sdk→account→web-ui）
        → sync-web-ui-dist（dist/renderer → packages/web-ui/dist，断言 index.html 字节一致）
        → test → pack-audit → bump（四包+根 lockstep，dk-* 互引钉新版，再生 lockfile）
        → publish-sdks.mjs 逐包 npm publish 内网源 → install-acceptance
        → npm run package
        日常验证用 --dry-run --skip-publish（shouldPublish 独立纯函数，零副作用有测试断言）

Step 2  构建安装包 + 产物审计
        npm run package = build + electron-builder --publish never + package:audit + pack:sdks
        审计（scripts/pack-audit.mjs）：tarball 顶层 ⊆ {dist, bin, README, LICENSE, package.json}；
        零测试产物；dk-account 防误发（registry 锁内网 GitLab）；公开三包无 /account/ 路径泄漏
        安装验收（scripts/install-acceptance.mjs）：spawn dk-web → listening banner →
        GET /health 200 + GET / 200 含 <div id="root"> + 入口 JS 200

Step 3  签名与公证（对外发布 / CI 打 Git tag 触发）
        build/sign-local.sh（mac/Linux）/ build/sign-local.ps1（Windows）→ run-signing-build.mjs
        （仅 darwin/win32；保留 APPLE_*/CSC_* 变量且不设断网）
        npm ci → build → electron-builder --config.forceCodeSigning=true → package:audit
        → 验签：mac codesign --verify --deep --strict；win Get-AuthenticodeSignature 双件 Valid
        → 有 APPLE_APP_SPECIFIC_PASSWORD 时 DMG 公证 + stapler 装订 → 冒烟 + 构建报告

Step 4  OTA 更新（走 OTA 通道时）
        npm run ota:manifest（scripts/ota/generate-manifest.mjs）：扫 release/ 安装包算 SHA-256
        → scripts/ota/latest.json；强制单一版本、单平台唯一；缺平台填全 0（运行侧 A6 守卫拒绝）

Step 5  发布记录落档
        build-report + SHA256SUMS（产物校验值）· 版本与变更（release.mjs bump）·
        验证摘要（⑥ 门禁结果绑定修订）· 审批人/审计引用（高风险动作）

合并/发布边界绑定：改动经默认分支（build）可比较的 diff 进入；必需检查（ci-local 全链）对最终修订全绿。本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 scripts/release.mjs 编排。

3.2 交付记录模板

目标边界：    分支 / 环境 / 发布通道
修订绑定：    合并/发布的 revision 与决策证据（PR 号 / 发布记录）
高风险动作：  动作 | 审批人/策略 | 时间 | 审计引用
回滚路径：    受影响资源 | 路径 | owner | 后置条件 | 验证方式
验证摘要：    ⑥ 的门禁结果绑定
残余风险：    未覆盖边界、需人工确认项

3.3 交付物清单

• 合并/发布证据（绑定修订）
• 构建产物 + 审计记录（build-report / SHA256SUMS / package:audit 结果）
• 发布记录（版本/变更/验证/审批）
• 回滚路径文档（高风险动作必填）

---

4. 反模式

• 本地验证冒充交付：只有本地测试支持交付声明。
• 先斩后奏的审批：效果发生了才补审批，或自查自批。
• 回滚路径悬空：有"看起来像回滚"的文件/命令，但连不上实际资源/修订/权限/后置条件（文件名匹配不算证据）。
• 只走发布后自动化：仅在推到默认分支/发布时跑的检查不算接受时验证。
• 无边界的高危可达性：默认路径能触达生产/凭据/破坏性命令而无边界。

---

5. 轻量路径（小改动）

• 内部改动：合并路径 + 必需检查即可，无发布/回滚部分（记 N/A 需检查证明）。
• 任何触达发布/生产/凭据的动作：审批与审计条款不可省略。

---

6. 相关文档

• 输入：阶段 ⑥ 06-validation.md
• 发布链唯一权威与签名：docs/release-process.md、docs/release-signing.md（本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 scripts/release.mjs 编排）
• 本地/CI 补充：docs/local-build-quickstart.md、docs/ci-runner-setup.md、docs/architecture/reproducible-build-baseline.md
• 完成后进入：阶段 ⑧ 08-learning.md