docs: de-emphasize legacy contract wording
This commit is contained in:
Codex
@@ -1,8 +1,8 @@
|
||||
# Host Codex Commander Skeleton
|
||||
|
||||
本文定义 host Codex 指挥官的本地 skeleton 阶段。仓库内正式 `commander` CLI 当前只提供 `/health`、`/api/commander/contract`、`.state/commander/` 状态读写、trace summary dry-run 聚合和 approval draft preview；不接 live bridge，不发送 ClaudeQQ，不接管人工指挥官。高风险 Code Queue recovery 的 ClaudeQQ 审批在本阶段只生成 200 字以内中文纯文本草案和 backend-core proxy 命令，不走本机 skill、powershell 或本地 ClaudeQQ server。
|
||||
本文定义 host Codex 指挥官的本地 skeleton 阶段。仓库内正式 `commander` CLI 当前只提供 `/health`、`/api/commander/contract`、`.state/commander/` 状态读写、trace summary dry-run 聚合和 approval draft preview；不接 live bridge，不发送 ClaudeQQ，不接管人工指挥官。高风险 Code Queue recovery 的 ClaudeQQ 审批在本阶段只生成 200 字以内中文纯文本草案和 backend-core proxy 命令，不走本机 skill、powershell 或本地 ClaudeQQ server。这里的 `contract` 是历史接口名，不代表合同测试入口。
|
||||
|
||||
当前允许存在一个 operator-run 的高鲁棒 stdio 保活形态，用于在人工授权下让 host Codex 持续承担指挥官工作。该形态不是仓库内正式 daemon，也不替代 skeleton contract；它应被视为过渡运行方式，后续产品化仍必须回到本文件的 contract、state、approval 和安全边界。
|
||||
当前允许存在一个 operator-run 的高鲁棒 stdio 保活形态，用于在人工授权下让 host Codex 持续承担指挥官工作。该形态不是仓库内正式 daemon，也不替代 skeleton dry-run surface；它应被视为过渡运行方式，后续产品化仍必须回到本文件的 state、approval 和安全边界。
|
||||
|
||||
## 边界
|
||||
|
||||
@@ -74,11 +74,11 @@ host commander 不直接编辑 HWLAB 业务代码，不以本地热修绕过 HWL
|
||||
|
||||
## Dev 验证计划
|
||||
|
||||
`commander smoke --dry-run` 是无 daemon smoke contract。它只输出验证计划，不启动 HTTP daemon、不打开 SSH/PTY/stdio bridge、不发送 ClaudeQQ、不重启服务、不 interrupt/cancel 任务、不部署、不跑全量 check/e2e。
|
||||
`commander smoke --dry-run` 是无 daemon smoke plan。它只输出验证计划，不启动 HTTP daemon、不打开 SSH/PTY/stdio bridge、不发送 ClaudeQQ、不重启服务、不 interrupt/cancel 任务、不部署、不跑全量 check/e2e。
|
||||
|
||||
指挥官派发或审阅任何 `DEV smoke` 时，必须沿用 `docs/reference/code-queue-supervision.md` 的 DEV 测试授权分级：未显式授权的 smoke 默认是 `read-only`；读取 live DEV 状态必须标成 `live-read`；触发 deploy、rollout、task、operation、audit、evidence 或硬件/虚拟硬件链路的 smoke 必须标成 `live-mutating`，并在 prompt 中逐项列出授权命令和 closeout 证据要求。
|
||||
|
||||
需要验证的 source/contract 面：
|
||||
需要验证的 source summary 面：
|
||||
|
||||
- health endpoint：用 `createCommanderRequestHandler` 和临时 `RuntimeConfig` 调用 `GET /health`，期望返回 `service=host-codex-commander`、`stateRoot` 和日志文件路径；禁止 `Bun.serve` 和端口监听。
|
||||
- state file：只在临时目录写读 `sessions/<sessionId>.json`、`events/<sessionId>.jsonl` 和 `approvals/draft.json`，确认 session 状态和 redaction round-trip；禁止触碰真实 `.state/commander/`。
|
||||
@@ -86,20 +86,20 @@ host commander 不直接编辑 HWLAB 业务代码，不以本地热修绕过 HWL
|
||||
- approval draft preview：只运行 `commander approval request --dry-run` 或 `buildCommanderApprovalDraft`，确认 `requiresExplicitUserApproval=true`、`claudeqq.mutation=false`、`sendImplemented=false`、`dryRunNoClaudeQqSend=true`、`notificationDraft.message` 为 200 字以内中文纯文本、`notificationPath.error=notification-path-unavailable`，并返回 backend-core `microservice proxy claudeqq /api/push/text` 命令；禁止 POST ClaudeQQ。
|
||||
- SSH bridge boundary：只检查 `commander plan --dry-run` 中 `bridge.mutation=false`、`startPlan.enabled=false` 和 `safetyBoundary.phaseOneMutationAllowed=false`；禁止打开 SSH、PTY 或 stdio bridge。
|
||||
|
||||
轻量契约测试是：
|
||||
历史命名的 dry-run 脚本是：
|
||||
|
||||
```bash
|
||||
bun scripts/host-codex-commander-no-daemon-smoke-contract-test.ts
|
||||
```
|
||||
|
||||
该测试只执行 CLI dry-run 和短命 source-level handler/helper，不启动长期进程。
|
||||
该脚本保留历史 `contract-test` 文件名，但只执行 CLI dry-run 和短命 source-level handler/helper，不启动长期进程，也不代表新增合同测试政策。
|
||||
|
||||
## HTTP
|
||||
|
||||
| Method | Path | 说明 |
|
||||
| --- | --- | --- |
|
||||
| GET | `/health` | 返回 service id、启动时间、state root 和日志文件 |
|
||||
| GET | `/api/commander/contract` | 返回机器可读 contract |
|
||||
| GET | `/api/commander/contract` | 返回机器可读 dry-run surface |
|
||||
| GET | `/api/commander/sessions` | 读取本地 session 摘要 |
|
||||
| POST | `/api/commander/state` | 写入本地 session state |
|
||||
| GET | `/api/commander/trace-summary` | 对 mock trace JSONL 做 dry-run 摘要 |
|
||||
@@ -147,4 +147,4 @@ trace summary 输入 mock Code Queue trace JSONL 和可选 task summary，输出
|
||||
|
||||
## 进入真实运行态前
|
||||
|
||||
启用 daemon、PTY/stdio bridge、SSH bridge 或 ClaudeQQ 发送路径前，必须先获得人工授权。授权必须绑定一个精确 action 和目标 session/task/service，已有 smoke/skeleton contract 通过，风险审查确认不会打印 token、不会直接 patch 数据库、不会绕过 backend 确认策略，并且已有可审计的 approval id、回滚步骤和观测步骤。ClaudeQQ 发送只能通过 backend-core `/api/microservices/claudeqq/proxy`，并设置超时和结构化失败输出。
|
||||
启用 daemon、PTY/stdio bridge、SSH bridge 或 ClaudeQQ 发送路径前，必须先获得人工授权。授权必须绑定一个精确 action 和目标 session/task/service，已有 smoke/skeleton dry-run 检查通过，风险审查确认不会打印 token、不会直接 patch 数据库、不会绕过 backend 确认策略，并且已有可审计的 approval id、回滚步骤和观测步骤。ClaudeQQ 发送只能通过 backend-core `/api/microservices/claudeqq/proxy`，并设置超时和结构化失败输出。
|
||||
|
||||
Reference in New Issue
Block a user