Codex
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Host Codex Commander Skeleton
|
|
|
|
本文定义 host Codex 指挥官的本地 skeleton 阶段。当前只提供 `/health`、`/api/commander/contract`、`.state/commander/` 状态读写、trace summary dry-run 聚合和 approval draft preview；不接 live bridge，不发送 ClaudeQQ，不接管人工指挥官。
|
|
|
|
## 边界
|
|
|
|
- `host-codex-commander` 是独立的本地 skeleton，不是运行中的 live daemon。
|
|
- 只允许本地文件状态、trace 摘要和审批草案预览。
|
|
- 所有输出必须 redaction token/secret/URL credential。
|
|
- 不得重启或接管 Code Queue backend，不得 cancel/interrupt 运行任务，不得打印 token 明文。
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
bun scripts/cli.ts commander contract
|
|
bun scripts/cli.ts commander plan --dry-run [--session-id primary]
|
|
bun scripts/cli.ts commander smoke --dry-run [--session-id primary]
|
|
bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]
|
|
```
|
|
|
|
`plan`、`smoke` 与 `approval request` 必须显式使用 `--dry-run`，缺失时返回 `error=dry-run-required`。
|
|
|
|
## Dev 验证计划
|
|
|
|
`commander smoke --dry-run` 是无 daemon smoke contract。它只输出验证计划，不启动 HTTP daemon、不打开 SSH/PTY/stdio bridge、不发送 ClaudeQQ、不重启服务、不 interrupt/cancel 任务、不部署、不跑全量 check/e2e。
|
|
|
|
需要验证的 source/contract 面：
|
|
|
|
- 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/`。
|
|
- trace summary dry-run：只喂 mock JSONL 给 `summarizeCommanderTrace`，确认 `taskId`、`sessionId`、`lastSeq`、`status`、`redactionsApplied` 和有界摘要；禁止读取 live Code Queue trace、标记已读、interrupt 或 cancel。
|
|
- approval draft preview：只运行 `commander approval request --dry-run` 或 `buildCommanderApprovalDraft`，确认 `requiresExplicitUserApproval=true`、`claudeqq.mutation=false`、`sendImplemented=false` 和敏感信息脱敏；禁止 POST ClaudeQQ。
|
|
- SSH bridge boundary：只检查 `commander plan --dry-run` 中 `bridge.mutation=false`、`startPlan.enabled=false` 和 `safetyBoundary.phaseOneMutationAllowed=false`；禁止打开 SSH、PTY 或 stdio bridge。
|
|
|
|
轻量契约测试是：
|
|
|
|
```bash
|
|
bun scripts/host-codex-commander-no-daemon-smoke-contract-test.ts
|
|
```
|
|
|
|
该测试只执行 CLI dry-run 和短命 source-level handler/helper，不启动长期进程。
|
|
|
|
## HTTP
|
|
|
|
| Method | Path | 说明 |
|
|
| --- | --- | --- |
|
|
| GET | `/health` | 返回 service id、启动时间、state root 和日志文件 |
|
|
| GET | `/api/commander/contract` | 返回机器可读 contract |
|
|
| GET | `/api/commander/sessions` | 读取本地 session 摘要 |
|
|
| POST | `/api/commander/state` | 写入本地 session state |
|
|
| GET | `/api/commander/trace-summary` | 对 mock trace JSONL 做 dry-run 摘要 |
|
|
| POST | `/api/commander/trace-summary` | 读取 mock trace JSONL 并更新本地 session 状态 |
|
|
| POST | `/api/commander/approvals` | 生成 approval draft preview 并落盘 |
|
|
|
|
## State
|
|
|
|
状态根目录固定为 `.state/commander/`，至少包含：
|
|
|
|
- `sessions/<sessionId>.json`
|
|
- `events/<sessionId>.jsonl`
|
|
- `approvals/<approvalId>.json`
|
|
- `logs/commander.jsonl`
|
|
|
|
session 状态只保留 `unknown`、`discovered`、`planned`、`starting`、`running`、`attention_required`、`stopping`、`stopped`、`degraded`。
|
|
|
|
## Trace summary
|
|
|
|
trace summary 输入 mock Code Queue trace JSONL 和可选 task summary，输出：
|
|
|
|
- `taskId`
|
|
- `sessionId`
|
|
- `lastSeq`
|
|
- `status`
|
|
- `keyEvents`
|
|
- `openQuestions`
|
|
- `recommendedNextActions`
|
|
- `redactionsApplied`
|
|
|
|
输出只做摘要，不返回 live transcript。
|
|
|
|
## Approval draft
|
|
|
|
高风险动作只生成 approval draft JSON / Markdown preview。preview 必须显示 redaction 结果，并明确 `sendImplemented=false`。
|
|
|
|
## 进入真实运行态前
|
|
|
|
启用 daemon、PTY/stdio bridge、SSH bridge 或 ClaudeQQ 发送路径前，必须先获得人工授权。授权必须绑定一个精确 action 和目标 session/task/service，已有 smoke/skeleton contract 通过，风险审查确认不会打印 token、不会直接 patch 数据库、不会绕过 backend 确认策略，并且已有可审计的 approval id、回滚步骤和观测步骤。
|