kanban-codex-lane

Kanban Codex Lane

概述

此技能定义了适用于 Kanban 工作器的轻量级 Hermes+Codex 双通道约定。Hermes 始终是任务负责人：它调用 kanban_show，判断是否适合使用 Codex，创建或选择隔离的工作区，启动并监控 Codex，协调处理任何差异，运行验证，并编写最终的 kanban_complete 或 kanban_block 交接。Codex 仅作为输入通道。Codex 的输出不代表任务已完成，不是可信的审查结果，也不得直接写入持久化的 Kanban 状态。

这项约定旨在让 Hermes 工作器能够使用 Codex 提供范围明确的实现协助，同时不改变调度器。调度器仍必须启动 Hermes 工作器。工作器可以选择在自身运行过程中启动 Codex，然后通过独立审查和测试，接受、部分接受或拒绝该通道的结果。

适用场景

满足以下所有条件时，使用 Codex 通道：

• Kanban 任务属于编码、重构、文档编写、测试或机械式迁移任务，且验收标准明确。
• Hermes 可以在一次运行中评估范围明确的差异。
• 仓库可以复制到隔离的 git worktree/branch，或在其中检出。
• Codex 退出后，Hermes 可以自行运行相关测试。
• 提示词可以说明所有安全约束和禁止更改的文件。

满足以下任一条件时，不要使用 Codex 通道：

• 任务需要的人工判断尚未记录在 Kanban 正文中。
• 工作器缺少仓库访问权限或 Codex 身份验证，或没有时间协调处理结果。
• 更改涉及机密、凭据存储、用户私人数据或生产订单录入系统。
• 直接进行小幅编辑比启动另一个 Agent 更快、更安全。
• 任务仅需研究，应该生成书面交接，而非差异。
• 工作器可能仅凭 Codex 的自我报告就将任务标记为 Done。

负责人规则

1. Hermes 负责 Kanban 生命周期。Codex 绝不能调用 kanban_complete、kanban_block、kanban_create、网关消息传递功能或任何 Hermes 看板 CLI 来代替工作器。
2. Hermes 负责最终验收。在审查和验证之前，应将 Codex 提交/差异视为不可信补丁。
3. Hermes 负责测试执行。Codex 可以运行测试，但这些运行结果仅供参考；必须由 Hermes 使用仓库的规范封装程序重新执行必要的验证。
4. Hermes 负责安全。如果 Codex 更改了安全边界、风险关卡、实盘交易行为或机密处理，即使测试通过，也要拒绝该通道的结果。
5. Hermes 负责清理。终止卡住的 Codex 进程，并在不再需要时移除临时 worktree。

必需的 Worktree 和 Branch 模式

切勿直接在共享且存在未提交更改的检出目录中运行 Codex。使用能将通道与 Kanban 任务关联起来的 branch/worktree 名称，确保不可信编辑保持隔离。

建议变量：

TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
REPO="/path/to/repo"
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"

创建隔离通道：

git -C "$REPO" fetch --all --prune
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
git -C "$WORKTREE" status --short --branch

如果当前 Kanban 工作区已经是为此任务创建的隔离 git worktree，只有在 git status --short 除有意进行的 Hermes 编辑外保持干净时，才可以在其中创建一个同级 Codex branch。否则，请创建单独的临时 worktree，并在协调处理后将已接受的提交 cherry-pick 或复制回来。

协调处理后进行清理：

git -C "$REPO" worktree remove "$WORKTREE"
git -C "$REPO" branch -D "$BRANCH"  # only after accepted commits were copied/cherry-picked or intentionally rejected

如果需要将 worktree 保留为审查材料，请在 codex_lane.artifacts 中记录，并在交接中提及。

Codex 能力检查

启动 Codex 之前先运行以下检查。缺少 Codex 是跳过该通道的常见理由；只要 Hermes 能直接完成任务，就不会阻塞任务。

command -v codex
codex --version
codex features list | grep -i goals || true

如果需要 /goal 支持，请先确认功能可用，再启用功能标志或通过该标志启动：

codex features enable goals || true
codex --enable goals --version

可以通过 OPENAI_API_KEY 或 Codex CLI OAuth 状态（通常位于 ~/.codex/auth.json）进行身份验证。不要打印令牌文件。缺少 OPENAI_API_KEY 并不能证明身份验证不可用。

模式选择

对于范围明确的一次性编辑，使用 codex exec，让 Codex 自行退出：

terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)

只有对于适合持续跟踪目标的更广泛多步骤工作，才使用 Codex /goal。在 PTY/tmux 会话中以交互方式启动；如果该功能默认禁用，则使用 codex --enable goals 启动。目标应自成一体，并包含仓库路径、任务 ID、安全约束、允许的范围、验收标准、测试和提交要求。

可粘贴到 Codex 中的 /goal 目标文本示例：

/goal Work in this repository only: <WORKTREE>. Task: <TASK_ID> <TITLE>.
Hermes owns the Kanban lifecycle; do not call Hermes kanban tools or messaging.
Create small commits on branch <BRANCH>. Follow the PMB safety constraints in the prompt.
Run the requested verification commands and report exact outputs. Stop after producing a diff and summary.

不要在 prediction-market-bot 或安全敏感的仓库中使用 --yolo。优先在隔离的工作树中使用 --full-auto，然后依靠 Hermes 进行协调。

提示词构造

处理 prediction-market-bot 工作时，使用链接的模板 templates/pmb-codex-lane-prompt.md。对于其他仓库，保持相同结构，并将 PMB 专属安全区块替换为仓库专属的不变量。

每个 Codex 提示词都必须包含：

• task_id、标题和完整的 Kanban 验收标准。
• 仓库路径、工作树路径、分支名称和允许修改的文件范围。
• 明确声明：Hermes 负责 Kanban 生命周期；Codex 仅作为输入通道。
• 必需的输出：简明摘要、变更文件、提交、运行的测试和已知风险。
• 禁止的操作：访问机密信息、对外发送消息、修改看板、无关重构，以及非必需的依赖升级。
• Codex 可以运行的验证命令，以及 Hermes 随后将运行的命令。

对于 PMB，必须逐字包含以下安全约束：

PMB safety constraints:
- live-SIM is paper-only; do not add or enable live REST order entry.
- Never use market orders.
- Do not add execution crossing or bypass price/risk checks.
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
- Keep research/selection outside the C++ hot path unless explicitly requested.
- Do not read, print, write, or require secrets/tokens/credentials.

监控、超时与终止行为

长时间运行的 Codex 通道应在后台启动，并启用 PTY 和完成通知：

result = terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)
session_id = result["session_id"]

在不干扰其运行的情况下进行监控：

process(action="poll", session_id=session_id)
process(action="log", session_id=session_id, limit=200)
process(action="wait", session_id=session_id, timeout=300)

向运行时间超过两分钟的通道每隔几分钟发送一次 Kanban 心跳，例如 kanban_heartbeat(note="Codex lane running in <WORKTREE>; waiting for tests/diff")。

终止条件：

• 在任务剩余运行时间预算内没有有用输出。
• Codex 请求机密信息、生产凭据或外部权限。
• Codex 尝试修改工作树之外的文件。
• Codex 开始进行无关重写或大量改动依赖。
• Codex 接近工作进程超时时仍在运行，且没有安全的部分产物。

终止命令：

process(action="kill", session_id=session_id)

终止后，检查 git status --short，仅在安全的情况下保留有用的补丁，并记录 codex_lane.result: timed_out 或 rejected，同时填写具体的 rejected_reason。

协调检查清单

接受任何 Codex 通道结果前，Hermes 必须完成以下检查：

• git -C <WORKTREE> status --short --branch 仅显示预期文件。
• Hermes 已审查 git -C <WORKTREE> diff --stat 和 git diff。
• 未包含机密信息、凭据、生成的缓存、无关数据或本地产物。
• 保留了 PMB 安全约束：不得通过实时 REST 下单、不得使用市价单、不得跨越执行、不得伪造被动成交或盈亏、不得弱化风险门控、不得包含机密信息。
• Codex 的提交足够小，可以干净地挑选或压缩。
• Hermes 自行运行了规范测试：Hermes Agent 使用 scripts/run_tests.sh，其他仓库使用仓库文档中指定的封装命令。
• Codex 运行的测试与 Hermes 运行的测试分别列出。
• 已将接受的提交或差异应用到由 Hermes 管理的工作区或分支。
• 对于被拒绝或部分完成的工作，记录了具体原因；如有用，也记录了产物路径。

验收结果：

• accepted：Codex 的差异或提交已审查、应用并验证。
• partial：经编辑或挑选提交后，接受了部分 Codex 工作；已记录被拒绝的部分。
• rejected：未接受任何 Codex 更改；已记录原因。
• timed_out：Codex 超出通道预算；可能存在也可能不存在有用产物。

kanban_complete 元数据架构

对于考虑过该执行通道的每项任务，都要将此对象放在 metadata.codex_lane 下。如果未使用 Codex，请设置 used: false，并在 rejected_reason 或同级的 notes 字段中说明原因。

{
  "codex_lane": {
    "used": true,
    "mode": "exec | goal | skipped",
    "worktree": "/absolute/path/to/codex/worktree",
    "branch": "codex/t_caa69668/20260508100000",
    "command": "codex exec --full-auto ...",
    "result": "accepted | rejected | partial | timed_out",
    "accepted_commits": ["<sha1>", "<sha2>"],
    "rejected_reason": "empty when fully accepted; otherwise concrete reason",
    "tests_run": [
      {"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
      {"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
    ],
    "artifacts": ["/absolute/path/to/log-or-patch"]
  }
}

对于有意跳过 Codex 的任务：

{
  "codex_lane": {
    "used": false,
    "mode": "skipped",
    "worktree": null,
    "branch": null,
    "command": null,
    "result": "rejected",
    "accepted_commits": [],
    "rejected_reason": "Direct Hermes edit was smaller and safer than spawning Codex.",
    "tests_run": [],
    "artifacts": []
  }
}

常见陷阱

1. 将 Codex 的自我报告视为验证结果。务必检查差异，并从 Hermes 重新运行测试。
2. 在用户有未提交更改的主检出目录中运行 Codex。务必在工作树或分支中隔离运行。
3. 让 Codex 管理 Kanban。Codex 可以总结进度，但看板状态应由 Hermes 更新。
4. 在提示词中遗漏 PMB 安全不变量。缺少安全说明意味着执行通道配置失败。
5. 对快速编辑使用 /goal。除非需要持久的多步续接，否则优先使用 codex exec。
6. 终止卡住的执行通道时不记录原因。rejected_reason 必须说明此决定的原因。
7. 因测试通过就接受范围过广且无关的清理。应拒绝这些更改，或只挑取范围内的更改。

验证清单

• 仅在运行 command -v codex、codex --version 和可选的目标功能检查后，才跳过 Codex 或启动 Codex。
• Codex 仅在隔离的工作树或分支中运行。
• 提示词包含任务范围、所有权规则、适用时的 PMB 安全约束，以及验证命令。
• Hermes 检查了 git diff 和安全敏感文件。
• Hermes 独立运行了标准测试。
• kanban_complete.metadata.codex_lane 符合上述架构。
• 已清理临时进程和不必要的工作树。