codex-delegate

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codex Delegate

## 目标

把一个可以独立完成的长任务交给后台 subagent；subagent 内部用 `shell` 启动 `codex exec`，再用 `write_stdin` 长等待直至完成，最后由后台 subagent 把结果带回主会话。

## 流程

```
┌─ 主会话
│  ├─ shell(command -v codex && codex --version)
│  └─ spawn(run_in_background=true, profile="scripting" 或 "general")
│     └─ 后台 subagent
│        ├─ write_file(<task_dir>/prompt.txt)
│        ├─ shell(yield_time_ms=30000)
│        │  └─ codex exec --cd <repo> --output-last-message <task_dir>/codex-result.md - < <task_dir>/prompt.txt
│        │     └─ 若返回 execution_id，write_stdin(yield_time_ms=300000) 续接到完成
│        ├─ read_file(<task_dir>/codex-result.md)
│        └─ read_file(<task_dir>/codex-session.txt)
└─ subagent 完成后回灌结果
```

## 使用规则

1. 主 agent 必须先检查 `codex` 是否存在：调用 `shell(command="command -v codex && codex --version")`。如果失败，直接告诉用户本机没有可用 Codex CLI，不要 spawn。不要把这个检查下放给 subagent。
2. 如果用户已经给出 repo 路径，主 agent 不要为了理解任务先 `list_dir`、`read_file`、`shell find/grep` 探索该仓库；只把 repo 路径和任务目标原样传给 spawn。代码库探索由 Codex delegate 完成。
3. 只有用户没给 repo 路径、路径明显缺失、或用户要求主 agent 先确认路径时，主 agent 才做最小路径检查。
4. 主 agent 不要在 spawn task 里写“重点读取这些文件”“我已经发现这些入口”“候选路径如下”这类预探索结果；除非用户原文明确指定文件。spawn task 只能包含用户给出的 repo 路径、用户目标、输出要求和本技能的执行约束。
5. Codex prompt 必须要求 Codex 自己从整个 repo 发现入口、目录和相关文件，而不是沿着主 agent 预先挑出的文件列表工作。
6. 检查通过后，外层必须用 `spawn(run_in_background=true)`，不要在主会话里直接跑长时间 `codex exec`。
7. subagent 的 `profile` 选 `scripting`；如果任务还需要联网调研，选 `general`。
8. subagent 内部启动 `codex exec` 时把 `yield_time_ms` 设为 30000；若返回 `execution_id`，用空 `chars` 的 `write_stdin` 续接，并把 `yield_time_ms` 设为 300000，直到结果不再返回 `execution_id`。
9. `timeout` 是 execution 进程组的硬截止，默认 14400 秒；它不控制单次等待。只有需要更短硬截止时才显式传入。
10. `codex exec` 要用 `--cd <repo>` 指定工作目录，避免依赖 shell 的 `cd` 状态。
11. 默认把任务说明写入 prompt 文件，再用 `codex exec --cd <repo> - < prompt.txt` 读取，避免 shell 引号、换行和特殊字符破坏 prompt。
12. 必须给 `codex exec` 加 `--output-last-message <task_dir>/codex-result.md`，完成后读这个文件作为主要结果；不要从 `/tmp/roxy-shell-*.log` 里 grep 或 tail 输出。
13. 同时把 stdout+stderr 保存到 `<task_dir>/codex-run.log`，因为 `session id: ...` 在 stderr 里。
14. 如果需要后续复用同一个 Codex 会话，必须从 `codex-run.log` 提取 session id，写入 `<task_dir>/codex-session.txt`，并在回复里告诉主会话这个 session id。
15. prompt、result、run log、session id 都必须放在 subagent 任务目录 `<task_dir>`；不要写 `/tmp`，也不要依赖 `/tmp/roxy-shell-*.log`。

## 推荐调用形态

外层：

```text
shell(
  command="command -v codex && codex --version",
  description="检查 codex"
)

spawn(
  task="用户给出的 repo 路径是 /path/to/repo；用户目标是：<原样概括用户目标>。不要让主 agent 先探索这个仓库，不要使用主 agent 预选的文件列表；Codex CLI 必须把 /path/to/repo 当作完整代码库，自行发现入口、目录和相关文件。在当前 subagent 任务目录写入 prompt.txt，然后用 shell 执行 codex exec --cd /path/to/repo --output-last-message <当前任务目录>/codex-result.md - < <当前任务目录>/prompt.txt，并用 2>&1 | tee <当前任务目录>/codex-run.log 保存完整日志。shell 返回 execution_id 时，使用 write_stdin 的空 chars 和 yield_time_ms=300000 续接到命令结束；不要写 /tmp，不要读取 /tmp/roxy-exec 日志。完成后读取 codex-result.md，总结结果；从 codex-run.log 提取 Codex session id 写入 codex-session.txt 并带回。",
  label="codex delegate",
  profile="scripting",
  run_in_background=true
)
```

subagent 内层：

```text
shell(
  command="bash -lc 'set -o pipefail; codex exec --cd /path/to/repo --output-last-message /path/to/task_dir/codex-result.md - < /path/to/task_dir/prompt.txt 2>&1 | tee /path/to/task_dir/codex-run.log; sed -n \"s/^session id: //p\" /path/to/task_dir/codex-run.log | tail -1 > /path/to/task_dir/codex-session.txt'",
  description="阻塞 codex",
  yield_time_ms=30000
)

write_stdin(
  execution_id=<shell 返回的 execution_id>,
  chars="",
  yield_time_ms=300000
)
```

完成后：

```text
read_file(path="/path/to/task_dir/codex-result.md")
read_file(path="/path/to/task_dir/codex-session.txt")
```

需要续聊同一个 Codex 会话时：

```text
codex exec resume <session_id> --output-last-message /path/to/task_dir/codex-result-2.md - < /path/to/task_dir/prompt-2.txt
```

## 注意

- 不要把 `codex exec` 命令末尾加 `&`、`nohup`、`disown`，也不要用 shell 后台化包装。
- 用户消息里已经有 repo 路径时，主 agent 不要提前读这个 repo 的文件来“了解一下”；直接委托 Codex CLI。
- 主 agent 不要把自己猜的入口文件、相关目录、搜索结果塞进 Codex prompt；这些会污染 Codex 对完整 repo 的自主分析。
- Codex prompt 可以写“请自行在整个 repo 中定位相关实现”，不要写“请重点读取以下文件”，除非这些文件来自用户原文。
- 不要调用已删除的 `task_output`。只在 `shell` 返回 `execution_id` 后调用 `write_stdin`，并使用 300000ms 长等待，避免无信息的短周期轮询。
- 简短 prompt 可以作为参数传给 `codex exec --cd <repo> '<任务说明>'`，但默认优先用 stdin 文件形态。
- `--last` 只适合人工临时使用；自动化续聊必须传明确的 `<session_id>`，避免串到别的 Codex 会话。
- 如果不用 `bash -lc`，也可以分两步执行：先跑 `codex exec ... 2>&1 | tee codex-run.log`，再用 `sed` 从 `codex-run.log` 提取 session id。
- 如果 `write_file` 因路径限制失败，说明路径没用当前 subagent 任务目录；修正为 `<task_dir>/prompt.txt`，不要改用 shell 写 `/tmp`。

From namei32/roxy-agent, MIT.

More from namei32/roxy-agent