From 5f091c0b6327d63bef39b01d556126536678cc09 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 22 May 2026 17:01:40 +0000 Subject: [PATCH] docs: update commander supervision references --- docs/reference/code-queue-supervision.md | 10 +++++++++ docs/reference/host-codex-commander.md | 28 +++++++++++++++++++++++- docs/reference/secretary-reference.md | 2 ++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index c98259c2..10e3cf5a 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -26,6 +26,16 @@ 指挥官的最终目标是推动整体开发波次持续前进：跟踪队列进展、及时纠偏、审查完成质量，并安排下一轮任务，让交付计划持续复利式推进，而不是一批任务结束后停滞。 +## HWLAB / #20 监督口径 + +当 HWLAB 是当前优先级最高的推进对象时，所有派单 prompt 的开头都必须显式引用 `DC-DCSN-P0-2026-003`，并说明任务究竟服务于 M3 虚拟硬件可信闭环的哪一环。如果任务只是在做发布前置、诊断、证据收口或文档治理，也必须明确写出它不抢占 M3 P0。 + +审阅 HWLAB runner 输出时，不能把 `SOURCE`、`LOCAL`、`DRY-RUN`、fixture 或只读报告误当成 `DEV-LIVE`。除非输出真的证明了 `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` 的真链路，并且带有 operation / audit / evidence 关联，否则只能归类为 support、diagnostics 或 contract。 + +`split-brain live` 且 heartbeat/trace 新鲜时，指挥官必须继续监督，不把它当作服务中断。此类状态的优先动作是继续轮询、继续审阅、继续派单，而不是默认 interrupt 或 cancel。 + +每次新派一批任务、接收一批 completed unread 结果，或者发生实质态势变化时，都要同步更新 `#20` 的正文主表；如果当天有滚动简报，则同时更新当日简报 issue 的正文主内容，而不是只在聊天中补上下文。 + ## 任务设计 每个 Code Queue task 都必须有清晰且狭窄的 ownership 边界。 diff --git a/docs/reference/host-codex-commander.md b/docs/reference/host-codex-commander.md index b9171ee6..b68775b5 100644 --- a/docs/reference/host-codex-commander.md +++ b/docs/reference/host-codex-commander.md @@ -1,6 +1,8 @@ # 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 指挥官的本地 skeleton 阶段。仓库内正式 `commander` CLI 当前只提供 `/health`、`/api/commander/contract`、`.state/commander/` 状态读写、trace summary dry-run 聚合和 approval draft preview；不接 live bridge，不发送 ClaudeQQ，不接管人工指挥官。 + +当前允许存在一个 operator-run 的高鲁棒 stdio 保活形态，用于在人工授权下让 host Codex 持续承担指挥官工作。该形态不是仓库内正式 daemon，也不替代 skeleton contract；它应被视为过渡运行方式，后续产品化仍必须回到本文件的 contract、state、approval 和安全边界。 ## 边界 @@ -20,6 +22,30 @@ bun scripts/cli.ts commander approval request --action --dry-run [--rea `plan`、`smoke` 与 `approval request` 必须显式使用 `--dry-run`，缺失时返回 `error=dry-run-required`。 +## Operator-Run Stdio Loop + +当前高鲁棒指挥官循环脚本固定放在 `/root/.unidesk/commander_loop.py`，工作目录使用 `/root/unidesk/`。它通过 `codex app-server --listen stdio://` 直连 Codex app-server JSON-RPC，而不是反复启动普通交互式 CLI；外层必须有持续循环和异常保护，fatal error 后自动重启，避免单次 stdio、网络或 app-server 错误让指挥官长期停止。 + +指挥 prompt 固定放在 `/root/.unidesk/commander_prompt.md`。脚本启动时读取该文件；运行中检测到 prompt 文件变化时，优先通过 `turn/steer` 注入当前 active turn。如果 steer 失败，脚本应记录失败、interrupt 当前 turn 并回到外层循环重启；不能静默忽略 prompt 变更。默认可以尝试 resume 指定 commander thread；resume 失败时必须降级为新 thread 继续运行。 + +前台输出应保持低噪声、单行化和可读：只显示时间、总运行时间、message、tool command start/completed/failed、stderr 和关键状态；完整 app-server JSON-RPC 事件不应直接刷屏。前台输出只是监督界面，分析和追责以 JSONL 文件日志为准。 + +完整日志必须写入 `/root/unidesk/logs/commander.log.<启动时间戳>.jsonl`，其中启动时间戳精确到秒，例如 `commander.log.YYYYMMDD_HHMMSS.jsonl`。后续分析时先用以下命令定位当前或最近一次运行日志： + +```bash +ls -t /root/unidesk/logs/commander.log.*.jsonl | head -n 1 +``` + +日志中应保留完整 JSON-RPC 事件和脚本派生事件，重点关注： + +- `thread/resume/requested`、`thread/resumed`、`thread/start/requested`：确认是否复用了预期 thread。 +- `turn/started`：确认当前 active turn。 +- `prompt/loaded`、`prompt/changed`、`prompt/steered`、`prompt/steer_failed`：确认外部 prompt 是否真实注入。 +- `item/completed` 中的 `agentMessage` 和 `commandExecution`：复盘 commander 说了什么、派了什么命令以及命令结果。 +- `stderr`：定位 Codex core、stdio bridge 或工具路由错误。 + +该运行形态可以用于指挥 Code Queue、审阅任务、创建/更新 issue、PR 收口和必要的热修复例外，但不得被解释为普通 worker。涉及实现、测试和 PR 创建的常规工作仍应优先通过 Code Queue 派单；host commander 直接执行只适用于授权的 PR 收口、基础设施热修复或 runner 权限缺口，并且必须留下复盘和长期改进 issue。 + ## Dev 验证计划 `commander smoke --dry-run` 是无 daemon smoke contract。它只输出验证计划，不启动 HTTP daemon、不打开 SSH/PTY/stdio bridge、不发送 ClaudeQQ、不重启服务、不 interrupt/cancel 任务、不部署、不跑全量 check/e2e。 diff --git a/docs/reference/secretary-reference.md b/docs/reference/secretary-reference.md index d925fbeb..efb19252 100644 --- a/docs/reference/secretary-reference.md +++ b/docs/reference/secretary-reference.md @@ -25,6 +25,8 @@ 日程安排按“硬约束、清醒时间、依赖阻塞、可并行性”的顺序处理。外部截止、现场条件、必须由用户亲自完成的判断、会被并发放大的方向错误可以插队；材料整理、归档、清单补全、方案调研等低风险事项应放入边角时间。 +秘书排程必须基于可查询记录，不凭印象空口安排。给出当天或后续时间表前，应优先查看 `Todo Note`、当日日程文件和用户最近反馈；若这些记录与记忆冲突，以可查询记录和用户最新反馈为准。临时口头安排可以先快速响应，但必须尽快回写到 `Todo Note` 或当日日程文件，避免后续排程失去依据。 + 给用户下一步时，秘书默认输出三个要素：一个明确当前动作、一个时间盒、一个反馈格式。反馈格式应简单，例如“完成/未完成 + 卡点”“路径 + 当前状态 + 下一步阻塞”。用户反馈后，只根据真实进展滚动调整下一段安排，不补写无依据的完成状态。 秘书应保护用户的整片清醒时间。论文正文审阅、关键技术取舍、现场硬件测试和外部重要沟通属于高价值时间块；普通跟进、填表、催办、归档和状态检查应尽量压缩在短时间块内。