| name | codex-loop |
| description | 用于启动或续跑 `.trellis/scripts/multi-agent/codex-loop.sh` 的执行技能。适合需要在独立 worktree 中让 Codex 按 implement/check 多轮循环推进任务，直到通过校验门。触发方式：用户提及 "codex-loop"、"Ralph Loop"、"loop 修复"、"继续 loop"、"多轮修到通过"、"在 worktree 里反复实现和检查" 等关键词时激活。 |
| license | MIT |
| allowed-tools | Shell, Read, Glob, Grep |
Codex Loop
目标
把 codex-loop 当成一个现成的循环执行器来用，不重写它的流程。唯一真相源是：
.trellis/scripts/multi-agent/codex-loop.sh.trellis/scripts/multi-agent/codex-loop-live.sh.trellis/scripts/multi-agent/codex-loop-batch.sh.trellis/worktree.yaml- 任务目录中的
task.json / prd.md / codex-loop/
适用场景：
- 用户明确希望“循环修到通过”
- 任务需要隔离 worktree，避免污染主工作区
- 需要可恢复的 round 日志、状态文件、最后反馈
- 需要把“实现”和“检查”拆成多轮、让脚本驱动收敛
不适用场景：
- 只需要一次性小改动
- 用户只是在问原理，不要求实际执行
- 当前仓库没有
codex CLI 或没有可用的验证手段
参数映射
codex-loop.sh 的最小必填参数：
--name <task-name>--type <backend|frontend|fullstack|test|docs>--requirement "<requirement>"
常用可选参数：
--task-dir <dir>: 续跑已有 task--rounds <n>: 最大循环轮数，默认 3--model <model>: 默认 gpt-5.4--sandbox <mode>: 默认 workspace-write--approval <policy>: 默认 never--search: 允许 codex exec 使用 web search--dry-run: 只打印计划，不执行
类型选择规则：
- 后端/CLI/服务端逻辑改动选
backend
- 纯前端界面改动选
frontend
- 同时跨 UI + API/核心逻辑选
fullstack
- 以测试补强、回归修复为主选
test
- 纯文档/spec/changelog 选
docs
执行流程
1. 先确认是否适合用 loop
先检查：
codex 命令可用- 目标需求适合多轮收敛，不是一次性改完即可
- 仓库存在
.trellis/scripts/multi-agent/codex-loop.sh
- 必要时查看
.trellis/worktree.yaml 的 verify 配置
若用户表达含糊，优先自己补齐这三个信息：
- 任务名
--name
- 开发类型
--type
- 一句话验收目标
--requirement
2. 先跑 dry-run
除非用户明确要求立即执行，否则先执行：
./.trellis/scripts/multi-agent/codex-loop.sh \
--name <task-name> \
--type <type> \
--requirement "<requirement>" \
--dry-run
确认以下信息是否合理：
- 生成或复用的 task 目录
codex/ 前缀分支名- worktree 路径
- verify 模式是
shell 还是 codex-check
3. 正式执行
dry-run 无误后，默认通过 live 包装脚本执行正式 loop：
./.trellis/scripts/multi-agent/codex-loop-live.sh \
--name <task-name> \
--type <type> \
--requirement "<requirement>"
如果用户要求续跑已有 task，改为：
./.trellis/scripts/multi-agent/codex-loop-live.sh \
--task-dir <task-dir> \
--name <task-name> \
--type <type> \
--requirement "<requirement>"
4. 读取产物并汇报
执行后优先读取：
<task-dir>/codex-loop/status.json<task-dir>/codex-loop/last-feedback.md<task-dir>/codex-loop/round-*/implement.log<task-dir>/codex-loop/round-*/check.log
最重要的结论只有三类：
passed: loop 已收敛，给出 task、branch、worktree、剩余人工动作stalled: 连续两轮无 diff 进展，需要人工改策略failed: implement/check/shell verify 失败，汇总最后反馈
Session 记录
codex-loop.sh 每一轮结束后都会自动执行一次 session 记录，写入当前开发者的 journal：
- 记录标题固定为
Codex Loop 第N轮 - <task-name>
- 摘要与详细内容使用中文
- 必须包含本轮
check 结果
- 若存在
shell verify，必须同时记录通过/失败结果
- 若工作区 journal 目录不存在，脚本应先自动补齐再写入
这类记录属于 loop 的运行轨迹，即使当前轮尚未 commit，也应该照常记录；不要把它和用户在任务收尾时手动执行的 /trellis-record-session 混为一谈。
质量门解释
codex-loop 有两层通过条件，缺一不可：
- 检查 worker 的最终输出包含
CODEX_LOOP_CHECK_PASS
- 如果
.trellis/worktree.yaml 配置了 verify:，这些 shell 命令必须全部通过
如果 verify: 为空，就退化为依赖 check worker 的结论。
因此：
- 不要在技能里重复定义 lint/typecheck/test 的固定清单
- 应以
.trellis/worktree.yaml 为准读取真实质量门
常见决策
新开 loop
在这些条件下直接新开：
- 用户要解决一个明确需求
- 还没有现成 task 目录
- 需要完整的 worktree 隔离和 round 日志
续跑 loop
在这些条件下复用已有 task：
- 已存在 task 目录与
codex-loop/ 日志
- 上一轮是
failed 或 stalled
- 用户要“继续上次 loop”或“根据最后反馈再跑一轮”
不启动 loop
遇到以下情况应改用普通实现流程：
- 需求太小，开 worktree 成本高于收益
- 当前工作树已有用户未提交改动且任务强相关，隔离执行会增加同步成本
- 用户只需要审阅、解释、方案设计，不需要脚本实际执行
输出要求
每次使用此技能，都给用户一个简短执行摘要：
- 本次是
dry-run、正式执行，还是续跑
- 使用的
name/type/requirement
- 生成或复用的 task / branch / worktree
- 当前结果是
passed、stalled 还是 failed
- 若未通过，指出下一步阻塞来自哪里：implement、check 或 shell verify
- 若实际执行了 round，补充说明本轮 session 已自动记录
实时汇报要求
只要实际启动了 loop，就必须在当前界面全过程持续汇报进度，不能只把信息写入 task 目录后静默运行，也不能只在少数关键节点补发摘要。
强制要求：
- loop 开始前，说明这是
dry-run、正式执行还是续跑
- 每进入新一轮时，立即汇报当前
round / max_rounds
- implement 阶段执行期间持续同步正在做什么，完成后汇报本轮是否产生了实质改动
- check 阶段执行期间持续同步正在检查什么，完成后汇报当前判定是
PASS 还是 FAIL
- 若存在 shell verify，执行期间持续同步正在跑哪条命令，完成后汇报通过情况；失败时指出具体失败命令
- 若 loop 因无进展、校验失败、脚本报错或达到最大轮数而中断，要立即汇报原因
- loop 终止时，明确说明最终状态是
passed、stalled 还是 failed
汇报内容可以简短，但必须让用户在当前界面实时看见进度，而不需要主动去打开：
status.jsonlast-feedback.mdimplement.logcheck.log
如果运行方式不支持自动流式展示脚本内部输出，就必须主动轮询并读取产物，把最新状态不断同步到当前界面，直到 loop 结束；不允许因为“工具不支持流式”而退化为静默执行。
批量模式（Multi-Todo）
当用户有多个 todo 需要依次 loop 执行时，使用 codex-loop-batch.sh 包装器。
Todos JSON 格式
创建一个 JSON 文件描述所有待执行 todo：
{
"verify": ["pnpm type-check"],
"todos": [
{
"name": "m6-converge-acp",
"todo_id": "m6-phase7",
"type": "backend",
"requirement": "Refactor VfsInterceptor to use VfsKernel...",
"task_dir": ".trellis/tasks/03-20-m6-converge-acp",
"rounds": 5
},
{
"name": "m6-cleanup-legacy",
"todo_id": "m6-phase8",
"type": "backend",
"requirement": "Remove ContextManager exports...",
"rounds": 3
}
]
}
字段说明：
verify（可选）：batch 级别的 verify 命令，会临时覆盖 worktree.yaml 中的 verify: 配置，全部 todo 执行完后自动恢复todos[].name：任务名（必填）todos[].todo_id（可选）：关联的 Cursor TodoWrite ID，用于自动同步进度todos[].type：开发类型（必填）todos[].requirement：需求描述（必填）todos[].task_dir（可选）：续跑已有 task 目录；为空时自动创建todos[].rounds（可选）：最大轮数，默认 3
批量执行流程
./.trellis/scripts/multi-agent/codex-loop-batch.sh \
--todos-file path/to/todos.json \
--dry-run
./.trellis/scripts/multi-agent/codex-loop-batch.sh \
--todos-file path/to/todos.json
./.trellis/scripts/multi-agent/codex-loop-batch.sh \
--todos-file path/to/todos.json \
--continue-on-failure
进度文件
脚本自动在 todos JSON 同目录下写入 batch-progress.json，每个 todo 状态变化时即时更新：
{
"total": 2,
"current_index": 1,
"updated_at": "2026-03-20T15:30:00+08:00",
"results": [
{
"name": "m6-converge-acp",
"todo_id": "m6-phase7",
"state": "passed",
"round": 3,
"task_dir": ".trellis/tasks/03-20-m6-converge-acp"
},
{
"name": "m6-cleanup-legacy",
"todo_id": "m6-phase8",
"state": "running",
"round": 1,
"task_dir": ""
}
]
}
state 取值：pending / running / passed / failed / stalled / skipped
Todo 进度同步协议
codex-loop 的执行结果必须实时同步到 Cursor 的 TodoWrite。这是强制规则，不允许全部跑完后才一次性更新。
状态映射
| codex-loop state | TodoWrite status |
|---|
running | in_progress |
passed | completed |
failed / stalled | 保持 in_progress（由 assistant 决定下一步） |
单任务模式
直接调用 codex-loop-live.sh 执行单个 todo 时：
- 启动前：如果 assistant 当前有活跃 todo list 且本次 loop 对应某个 todo，立即
TodoWrite 将其标记为 in_progress
- 监控中：持续轮询
status.json，检测到 state 变化时在汇报的同时判断是否需要更新 TodoWrite
- 结束后：读取
status.json 最终 state
passed → TodoWrite 该 todo 为 completedfailed / stalled → 保持 in_progress，汇报失败原因后由 assistant 或用户决定下一步
批量模式
调用 codex-loop-batch.sh 执行多个 todo 时：
- 启动前：根据 todos JSON 中的
todo_id 字段创建或更新 TodoWrite 条目，全部初始化为 pending
- 监控中：轮询
batch-progress.json，每当检测到某个 todo 的 state 发生变化：
state 变为 running → TodoWrite 对应 todo 为 in_progressstate 变为 passed → TodoWrite 对应 todo 为 completedstate 变为 failed / stalled → 保持 in_progressstate 变为 skipped → 保持 pending
- 结束后：做一次最终同步，确认
batch-progress.json 中所有 todo_id 非空的条目状态都已同步到 TodoWrite
跳过同步条件
todo_id 字段为空或不存在时，跳过 TodoWrite 同步，不报错- assistant 当前没有活跃 todo list 时，跳过同步
注意事项
- 不要手工模拟
codex-loop 的多轮逻辑，优先直接调用脚本
- 默认使用
codex-loop-live.sh，只有在用户明确要求底层原始脚本时才直接调用 codex-loop.sh
- 批量执行多个 todo 时使用
codex-loop-batch.sh
- 不要在主工作区修改 loop 目标代码；脚本会在独立 worktree 中执行
- 不要假设验证命令存在；先读
.trellis/worktree.yaml
- 若用户只想创建技能或文档而非实际跑 loop，可以只更新技能文件，不执行脚本
