109 lines
6.0 KiB
Markdown
109 lines
6.0 KiB
Markdown
# 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；两种流程
|
||
必须保持独立，避免同一请求被重复发布。
|