using-codex-ride

# 使用 Codex Ride 这是 `codex-ride` 的 bootstrap skill。 职责： 1. 看用户请求、session state、artifact 2. 判断当前 phase 3. 在做实质动作前，路由到正确 phase skill ## 指令优先级 顺序： 1. 用户直接指令 2. 已批准 workflow artifact 3. `codex-ride` phase skill 4. 默认助手行为 用户明确 override gate，就记录并继续。 ## 核心规则 在没判断 phase 前，不要写代码、计划、报告。 ### Worktree 规则 (强制) codex-ride workflow 的所有写动作 (spec / plan / task / execute / review / report) 必须在 git worktree 中进行，禁止直接污染主工作树。 - 路径约定：worktree 放在**项目根目录**的 `worktrees/` 子目录下，路径形如 `worktrees/<worktree-name>` - 命名按"任务簇"取名 (例如 `worktrees/auth-overhaul`、`worktrees/billing-q2`)，**不**绑死单个 workflow slug - **每个 worktree 同一时间只活跃一个 workflow**：`.codex-ride/session.json` 是**按 CWD** 存的，每个 worktree 独立一份 state，互不污染 - 同一 workflow 的所有阶段始终共用同一个 worktree，从 spec 起一直用到 report；不要中途切到别的 worktree - 进入任何 phase skill 前先检查 `pwd`： - 若已在某 `<project-root>/worktrees/<name>` 内 -> 继续在该 worktree 工作 - 若仍在主工作树 -> 先与用户确认 worktree 名 (新建或复用现有)： - 新建：`git worktree add worktrees/<name> -b codex-ride/<name>` - 复用：直接 `cd worktrees/<name>` - 用户离开 worktree 后再继续 workflow，必须先 `cd` 回原 worktree，不要在主工作树续跑 - worktree 目录要纳入 `.gitignore` (`worktrees/`)，避免误提交 #### 多 spec 推进模式 复杂任务拆成多个 spec 时, 按是否需要并行选择模式: ##### A. 串行 (默认, 同一 worktree) - 上一个 workflow 完成 (final report 出 / STATUS=done) 后再起下一个 - 切换到下一 spec：先 `codex-ride state:get` 确认当前 workflow 已 done，再 `codex-ride init --slug <new-slug> --force` 起新 workflow - 优点：分支线性, merge 简单, 配额 / 资源不抢 ##### B. 并行 (各自一个 worktree) - 每个并行 spec 独占一个 worktree (`worktrees/<task-cluster>`) - 每个 worktree 独立 `.codex-ride/session.json`、独立 codex-worker、独立分支 (`codex-ride/<task-cluster>`) - 启动方式：**多开 rider session** (多终端 / 多 IDE 窗口)，每个 session 进入一个 worktree (`cd worktrees/<name>`)；单 rider session 的 CWD 单一，无法同时管多个 worktree - 必须满足的约束： - **write-scope 不重叠**：每个 workflow 的 `codex-ride run --write-scope <path>` 划独立目录 (例如 `src/auth/` vs `src/billing/`)；重叠会让两个 phaseExecution 互相覆盖且产生未提交冲突 - **远端 merge 串行**：worktree A 的 PR merge 后，worktree B 要 `git fetch && git rebase origin/main` 再继续，避免 PR 间冲突堆积 - **配额 / 资源**：codex 并发跑会摊薄 RPS, 磁盘 / CPU 共享; 同时跑 <=2–3 个 worktree 较稳 - **memsearch 是全局**：不同 worktree 的 session 写入会交叉, 检索时按 worktree slug / spec slug 过滤 - 启动顺序建议： 1. `git worktree add worktrees/<name-A> -b codex-ride/<name-A>` (主 rider session 内) 2. 新开 rider session, `cd worktrees/<name-A>`, 跑 spec / run 3. 再回主 session 加 worktree B, 重复 ### 后台任务看护规则 codex-ride dispatch 会等待 detached codex-worker 完成并返回 JSON；长任务可用 `codex-ride job:status` 做轻量状态检查。 防卡死兜底 (可选, 长跑 phaseExecution 等场景建议开)： - 派完 codex-worker 后，必要时定期执行 `codex-ride job:status --job-id <id>` - 间隔按任务长度选，**避开 ~600s** (付 cache miss 又拿不到长间隔好处)： - 长任务 (>30min)：1500–1800s，摊薄 cache miss - 活跃监控 (即将完成 / 卡边缘)：<=270s，留在 5min cache 内 - 回调触发时只做轻量检查： - 跑 `codex-ride job:status --job-id <id>` 或读 `last_result_file_path` - 仍 running 且有进展 -> 继续等待或稍后再查 - 仍 running 但日志 / 输出无变化 (疑似卡死) -> 提示用户并问是否 stop / restart - 已完成 -> 进入正常结果处理 - 不可主动通知的任务 (`codex-ride drive` 等跨 session detached) 不适用本节，按 `drive` skill 规则单独处理 ### Token 节流规则 总原则：rider 只读结构化字段 / 摘要 / diff，**不**读原始大文件。 > **CLI 现状**：当前 `codex-ride.manifest.json` 只有 6 个固定 codex-worker job (`specAdversarialReview` / `phasePlanSynthesis` / `phaseTaskSynthesis` / `phaseExecution` / `phaseReview` / `finalSpecReview`)，**没有**通用 codex 摘要 / finalReport / recovery job。所以"重活儿派 codex"暂不可行，先用以下变通手段；若后续给 manifest 加通用 `summarize` job，可把"派 sub-agent"全部替换为"派 codex-worker"。 可用减负手段优先级： 1. **结构化字段提取** (最省)：`codex-ride state:get`、`jq` 抽 result.json 字段、`grep -A N <heading>` 抽段 2. **Shell 限幅**：`head` / `tail` / `wc -l` / `grep -c`，禁全文读取 / `cat` 3. **本地摘要**（兜底）：必要时让 codex-worker 输出短摘要 artifact，主 rider 只读摘要 #### 看护期 (后台 codex-worker 仍在跑) - 不直接读取 >200 行的 codex-worker 日志 / phase 输出 - - `codex-ride job:status --job-id <id>` 看 JSON - - `tail -50 <log> | grep -E 'ERROR|FAIL|done'` 抽关键行 - - 比对 mtime / 行数；无变化跳过深查 - 多 job 批量查，避免频繁轮询 #### 最终报告生成 (`reporting-results`) - rider 仍是写报告主体 (CLI 没 finalReport job)，但读 artifact 时**分段读，不全读**： - `head -100 <spec>` 读目标 / 非目标段 - `grep -A 10 '## verdict\|## blockers' <phaseReview>` 抽 verdict / blockers - 完整读取只对 final report template 用一次 - 跨 phase 合成时优先读取各 artifact 的摘要段；需要额外压缩时派 codex-worker 生成 <=500 字 phase 摘要和风险列表 #### plan / task 文档回读 - codex-worker 出完 plan list / task list 后，rider 不读全文 - 默认：`head -50 <file>` + `grep -c '^### phase' <file>` 算 phase 数 -> 一句话告诉用户 - 用户问到具体 phase 才精读那一段 #### phase review 回读 - 只用 `grep -A` 抽三段：`verdict` / `blockers` / `top_issues` (前 3 条) - 完整 review markdown 不读 #### spec 对抗审 revise 循环 - 每轮 revise 不把 spec 全文 + review 全文带进 rider context - spec 改动用 `git diff <spec_path>` 给 rider，原文留在文件系统 - review 结果只看 verdict + critical issues，用 `grep -A` 抽 #### Shell 输出强制限幅 | 命令 | 默认形式 | | ----------------- | -------------------------------------------- | | `git log` | `git log -n 10 --oneline` | | `git diff` | `git diff --stat`，要全文派 sub-agent 摘要 | | `find` | 必须 `\| head -50` | | `grep` | 必须 `\| head -50` 或 `-c` 计数 | | `ls` | 子目录深时用 `-1 \| head` | | `cat` / `tail -f` | **禁**直接对大文件用；改 `tail -50` 或抽段读 | 要全文分析的：派 sub-agent，主 rider 只读摘要。 #### artifact recovery - 断线 / 续跑时禁止 rider 重读所有 artifact - 实操：`codex-ride state:get` 读 `current_phase` / `active_job_id` / `last_result_file_path` / `phase_result_dir` 等关键字段，只 `head` 当前 phase artifact - 全链分析时优先派 codex-worker 写 recovery summary artifact #### state 查询去重 - 每个 skill 入口处一次性 `codex-ride state:get` 拉全字段，关键字段记到对话文本 - 同一 skill 内后续动作复用，不再重复 `state:get` - 只在状态明确变化后 (派完 job / 收到 notification / 用户改了 state) 再查 #### session 接力 单 workflow 完成 (final report 出) 后按用户全局规则：memsearch 存档 + 提示 `/clear` 或开新 session。本节不再赘述。 #### 状态汇报一行制 中间汇报压成一行；JSON / 摘要文件不要展开重述。例： - `phase-2: pass, 0 blocker, next=phase-3` - `<job-id>: running, 12/20 task done, last_progress 3min ago` 按状态路由： - 用户明确要“开 detached codex 做用户指定任务” -> `drive` - 没有已批准 spec -> `drafting-specs` - spec 已批准，但没有 phase plan list -> `writing-phase-plans` - phase plan list 已有，但缺 phase task list -> `writing-phase-tasks` - 已有 ready 的 phase task list，且还有 phase 没执行完 -> `executing-phase-tasks` - 某个已完成 phase 还没 review，或 final spec review 还没做 -> `reviewing-phase-results` - 所有 phase 都 review 完，且 final spec review 通过 -> `reporting-results` ## CC 调用指南 codex-ride 通过 `codex-ride` CLI 命令操作 workflow。以下是 rider 在各阶段应调用的命令: ### 启动 workflow ```bash cd <target-project-root> codex-ride init --slug <project-slug> codex-ride state:set --set spec_path=<spec-file-path> ``` ### 写 spec 阶段 (drafting-specs) rider 和用户一起写 spec, 落盘到 spec_path。spec 写好后: ```bash codex-ride state:set --set spec_approved=true ``` ### 自动推进 (spec 批准后) ```bash codex-ride run --write-scope <allowed-write-path> ``` 这会自动推进: plan -> task -> execute -> review -> report, 直到完成或需要用户介入。 如果 `rider` 自己中途断线、报错、额度耗尽： - 直接再次执行 `codex-ride run --write-scope <allowed-write-path>` - harness 会先检查 `active_job_id` - 如果后台 codex-worker 还活着，就接管等待 - 如果后台 codex-worker 已结束，就读取结果或做 artifact recovery ### 启动 detached codex drive 如果用户要的不是 workflow gate，而是“把这个任务交给 codex 一直做”： ```bash codex-ride drive "<user task>" ``` 如果是接管当前仍在进行的 drive： ```bash codex-ride drive ``` 这个模式下： - 任务文本直接来自用户 - codex 只是停下来问“是否继续”时，会自动 `resume` - 监控只看 4 类里程碑：PR merge、CI 失败、需要用户介入、drive 结束 - 非里程碑进展静默 - 真 blocker / 真决策需求时才交还用户 ### 查看状态 ```bash codex-ride state:get codex-ride resolve-phase codex-ride job:status codex-ride job:status --job-id <job-id> ``` 用途： - `state:get`：看 workflow state 真源 - `resolve-phase`：看当前 phase 推断结果 - `job:status`：看 active job 或指定 job 的 detached runner / codex-worker / result 状态 ### 手动 dispatch (高级) ```bash codex-ride dispatch --job <job-name> [--phase-id <id>] [--write-scope <path>] ``` ## Gate 规则 默认 gate： - spec 批准前，不写 phase plan - phase review 过前，不开下一个依赖 phase 执行 - final spec review 过前，不出最终报告 除非用户明确要求，否则不要跳 gate。 ## 会话合同 追踪或推断这些字段： - `workflow_id` - `current_phase` - `spec_path` - `spec_review_path` - `spec_review_passed` - `spec_approved` - `phase_plan_list_path` - `phase_plan_review_passed` - `phase_task_dir` - `phase_result_dir` - `phase_review_dir` - `ready_phase_ids` - `active_phase_id` - `completed_phase_ids` - `reviewed_phase_ids` - `final_spec_review_path` - `final_report_path` - `active_job_id` - `last_result_file_path` - `override_log_path` - `job_attempts` - `current_execution_root` 如果没有结构化 state，就根据明确 approval、artifact 是否存在、最近 review 结果来推断。 ## 响应模式 开工时： 1. 说当前用哪个 `codex-ride` skill 2. 说为什么 3. 按该 skill 执行 示例： - "Using `drafting-specs`，因为现在还没有已批准 spec。" - "Using `writing-phase-tasks`，因为已有 phase plan list，现在要按 phase 产 task list。" - "Using `reviewing-phase-results`，因为某个 phase 刚执行完，必须对照 plan 审。" - "Using `codex-ride run`，因为 spec 已批准，自动推进 workflow 到完成。" - "Using `codex-ride drive`，因为用户要启动 detached codex 执行他指定的任务，而不是走 workflow gate。" ## 反模式 - 粗糙请求直接进 execution - 没书面 spec 就 planning - 上个依赖 phase 还没 review 就跑后续 phase - final spec review 没过就宣称完成