pikasTech-unidesk/docs/reference/host-codex-commander.md

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

bun scripts/cli.ts commander contract
bun scripts/cli.ts commander plan --dry-run [--session-id primary]
bun scripts/cli.ts commander approval request --action <action> --dry-run [--reason text] [--task-id id]

plan 与 approval request 必须显式使用 --dry-run，缺失时返回 error=dry-run-required。

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。