feat(ack): add one-off delivery routing

2026-08-01 15:25:15 +08:00
parent f8d03fad4d
commit a0f1c15b85
21 changed files with 871 additions and 58 deletions
@@ -0,0 +1,108 @@
+# ACK 一次性交付路由
+
+本文件定义用户显式调用 `$ack` 后，直接要求创建发布相关 PR/MR、发布源码版本、
+上传 DEB 或发布 Docker 镜像时的路由。它不要求先跑 Developer → Test 闭环，也不读取
+或修改 `delivery.yaml`；项目已有的“verified 后按 profile 交付”仍按 `delivery.md`
+执行。
+
+## 1. 只按用户目标选择能力
+
+| 用户目标 | 路由 | 不得顺带执行 |
+| --- | --- | --- |
+| 创建普通或发布 PR/MR，以及版本号、release/hotfix 分支、合并、正式 tag、Forge Release、恢复中断的源码发布 | `manage-release` | 未请求的版本升级、合并、tag、Forge Release、清理、普通产物上传 |
+| 构建、检查、上传 `.deb`，发布到 APT/DEB 仓库 | `deb-publisher` | tag、Forge Release、Docker 镜像 |
+| 构建并推送 Docker/OCI 镜像到 registry | `publish-docker-image` | 源码版本、DEB、额外 tag；用户说的 `docker-publisher` 视为这个已安装 Skill 的别名 |
+
+“创建 PR/MR”路由到 `manage-release`，但必须区分权限上限：发布版本、release/hotfix
+分支或版本升级对应的 PR/MR 走发布流程；普通 PR/MR 只走它的 ACK `PR-only` 入口，
+不得推断版本升级、release 分支、合并、tag 或 Forge Release。ACK 功能任务在 verified
+后按 profile 自动开 PR 时，仍使用 `delivery.md` 的 `pull-request` 动作，不重复建立
+一次性操作。
+
+只说“发布一下”时先从用户文字和项目发布入口判断目标。DEB、镜像和源码发布仍有两个
+以上合理候选时，先问一个最小澄清问题；不要根据最近文件或历史命令猜。用户明确要求
+多个产物时，为每个能力建立独立操作，按用户给出的顺序执行，不能由一个 Skill 暗中
+扩大到另一个 Skill。
+
+## 2. 用低成本 Operator 派发
+
+一次性交付由 `operator` worker 执行，Coordinator 不亲自运行低层 Skill。机器事实仍
+只读 `docs/ack/tasks.yaml.project.orchestration`：
+
+- `defaults.operator` 必须指向 `role: operator`、`tier: standard` 的 profile。
+- Operator 默认 profile 的 `cli`、`tier`、`model` 和 `reasoningEffort` 必须与
+  `defaults.test` 完全相同；校验器会拒绝漂移。`permissionMode` 仍按项目需要显式写
+  `read-only` 或 `workspace-write`，发布通常需要后者。
+- 旧项目没有 `defaults.operator` 时，普通 ACK 闭环仍可运行，但一次性交付路由必须
+  fail closed。先按当前模板补 operator allowlist/profile/default 并校验，不能临时猜
+  模型或让 Coordinator 代跑。
+- launcher 只给 Operator 固定的发布凭据 allowlist：`DEB_SERVER_URL`、`DEB_TOKEN`、
+  `DEB_REPOSITORY`、`DEB_UPLOAD_PATH` 和 `SSH_AUTH_SOCK`；Docker/Forge 使用 HOME
+  中自己的凭据存储。值不写入任务板或 receipt。缺少凭据时由低层 Skill 标记 blocked，
+  不通过 prompt、自由 env 或命令行注入秘密。
+
+路由后在权威任务板新增一条最小记录：
+
+```yaml
+- id: "DELIVERY-001"
+  type: "delivery-operation"
+  title: "publish one DEB"
+  status: "open"
+  operation:
+    skill: "deb-publisher"
+    request: "<保留用户本次请求的授权语义；凭据值必须替换为 [REDACTED]>"
+  dispatch:
+    operator:
+      profileId: "<defaults.operator>"
+      receiptId: null
+      attemptId: null
+      taskId: null
+      dispatchId: null
+    rounds: []
+```
+
+运行 `validate_tasks.py` 后，用 `launch_worker.py plan|launch` 创建 fresh worker，参数
+使用 `--role operator`、本操作 ID 和 `<operation-id>-A1`。审阅 fingerprint，成功后
+把 receipt 写入 `workerReceipts` 并与 `dispatch.operator` 精确绑定，再投递下节的
+prompt。Orca 模式按 `orca-adapter.md` 登记单一操作任务，并把 runtime task/dispatch
+ID 写入 `dispatch.operator`；不创建 Developer/Test 子任务链。不得复用 Test terminal；
+“同模型档位”不等于“同角色或同 worker”。
+
+## 3. Operator 派发 Prompt
+
+```text
+你是 ACK 一次性交付 Operator。请在 <worktree> 执行以下原始请求：
+<operation.request>
+
+ACK 已选择且只授权你加载：$<operation.skill>
+先完整读取该 Skill 及它要求的 references，再读取可信 base 上的项目发布规则。
+
+边界：
+- 原始请求是授权上限；除已脱敏的凭据值外保持原意，不得因 ACK 路由、项目配置或
+  历史操作扩大远端写权限。
+- 严格遵守低层 Skill 的确认点、硬停止条件、恢复流程和完成标准。
+- 不修改 docs/ack/tasks.yaml、knowledge.yaml 或 delivery.yaml。
+- 不把 token、密码、私钥路径或认证配置写入消息、文件、提交或日志。
+- 发生部分成功或外部状态不确定时停止自动重试，先按低层 Skill 核对真实状态。
+
+完成或阻塞后只回传：所选 Skill、实际执行到的阶段、准确目标、非敏感证据、
+未完成项和安全恢复动作。不要把命令已运行等同于发布已验证。
+```
+
+## 4. 状态与完成
+
+Coordinator 在派发后把操作标为 `dispatched`，只读 Operator 的结构化证据做终检：
+
+- `manage-release` 必须按其完成标准证明 PR/MR、merged commit、远端 tag 或 Forge
+  Release 中用户实际要求的最远阶段。
+- `deb-publisher` 必须分别证明包元数据/摘要、上传接受和仓库可见性。
+- `publish-docker-image` 必须证明完整镜像引用、platform、源 commit 和远端 digest；
+  registry 无法查询时明确限制。
+
+证据满足原始请求才把操作标为 `verified`；安全停止但可恢复时标为 `blocked` 并记录
+恢复动作。`worker_done` 不等于完成。涉及远端写入的失败不自动进入第二轮；先由对应
+低层 Skill 执行真实状态发现和恢复，再由用户决定是否继续。
+
+Operator receipt 和操作证据写在该任务中，不写入 `deliveryRuns`。一次性交付不会因
+项目其它任务未 `verified` 而被拦截，也不会触发 `delivery.yaml` 的 profile；两种流程
+必须保持独立，避免同一请求被重复发布。