Codex Skill：ask_codex.sh 使用说明

这个仓库提供了一个用于调用 Codex CLI 的 Bash 封装脚本：scripts/ask_codex.sh。

它的目标是：

• 用统一参数格式发起 Codex 任务
• 支持新会话与多轮续聊（session）
• 支持指定重点文件上下文（--file）
• 自动保存响应到 markdown 文件，便于追踪和归档
• 在执行过程中输出简要进度信息

适用于：把“自然语言任务 + 代码上下文”稳定地交给 Codex 执行的场景。

---

目录结构

.
├── README.md
├── SKILL.md
└── scripts/
    └── ask_codex.sh

• scripts/ask_codex.sh：核心脚本（命令解析、参数拼装、调用 codex、结果提取）
• SKILL.md：技能描述与操作约束

---

功能概览

ask_codex.sh 主要能力包括：

1. 任务输入灵活

   • 位置参数：ask_codex.sh "任务描述"
   • 显式参数：-t/--task
   • 标准输入：无参数时可从 stdin 读取

2. 文件上下文注入

   • 可重复使用 -f/--file
   • 支持逗号分隔批量传入
   • 自动将相对路径基于 workspace 解析
   • 兼容去除行号尾缀（如 a.py:12、a.py#L12）

3. 多轮会话

   • 使用 --session <id> 继续已有 thread
   • 便于迭代补充需求

4. 执行模式控制

   • --read-only：只读模式
   • --full-auto：全自动（默认）
   • --sandbox <mode>：手动覆盖沙箱模式

5. 输出归档与可追踪

   • 自动生成时间戳输出文件（默认写入 .runtime/）
   • 标准输出返回：
     • session_id=<thread_id>
     • output_path=<file>
   • 汇总 agent 消息、shell 执行片段与工具调用信息

---

运行前依赖

脚本会强制检查以下命令：

• codex
• jq

可选（提升流式显示体验）：

• script（若缺失会自动降级为非 pseudo-TTY 执行）

---

快速开始

1）给脚本可执行权限

chmod +x scripts/ask_codex.sh

2）最小调用

scripts/ask_codex.sh "为 src/api.ts 增加错误处理"

成功后会输出：

session_id=<thread_id>
output_path=<某个 markdown 文件路径>

3）查看结果

cat <output_path>

---

命令行参数详解

Usage:
  ask_codex.sh <task> [options]
  ask_codex.sh -t <task> [options]

任务输入

• <task>：第一个位置参数作为任务文本
• -t, --task <text>：显式传任务文本
• stdin：若未传 <task>/--task，则从标准输入读取

文件上下文

• -f, --file <path>：重点文件（可重复）
• --focus：--file 的别名

会话续聊

• --session <id>：继续之前会话

执行配置

• -w, --workspace <path>：工作目录（默认当前目录）
• --model <name>：模型覆盖
• --reasoning <low|medium|high>：推理强度（默认 medium）
• --sandbox <mode>：沙箱模式覆盖
• --read-only：只读执行
• --full-auto：全自动执行（默认）

输出配置

• -o, --output <path>：指定输出 markdown 路径
• -h, --help：显示帮助

---

常见用法示例

示例 A：带重点文件的新任务

scripts/ask_codex.sh "重构用户模块并补充类型" \
  -f src/user/service.ts \
  -f src/user/types.ts

示例 B：继续已有会话

scripts/ask_codex.sh "再补充重试与超时控制" --session <thread_id>

示例 C：只读分析

scripts/ask_codex.sh "分析这次构建失败的根因并给出修复建议" \
  --read-only \
  -f package.json \
  -f scripts/build.sh

示例 D：通过 stdin 传任务

cat task.txt | scripts/ask_codex.sh -f src/main.ts

---

脚本执行流程（高层）

1. 解析 CLI 参数（workspace、task、file refs、session、sandbox 等）
2. 检查依赖（codex、jq）
3. 校验输入并标准化 workspace
4. 处理输出路径（默认时间戳文件）
5. 构造包含重点文件清单的最终 prompt
6. 根据是否有 --session 选择“新会话”或“续聊”命令
7. 执行 Codex，并流式记录 JSON 事件
8. 提取 thread_id 与关键信息，写入 markdown 输出
9. 向 stdout 返回 session_id 与 output_path

---

输出内容说明

输出 markdown 可能包含：

• ### Shell: ...：Codex 运行的命令片段及聚合输出
• ### File written / File patched：工具调用产生的文件写入/修改信息
• Agent 消息文本：Codex 的自然语言说明与总结

当未捕获到有效内容时，输出文件会写入：

(no response from codex)

---

注意事项与最佳实践

1. 任务描述要聚焦

   • 清晰说明目标与约束，避免冗长上下文

2. 优先提供高信号文件

   • 一般给 2–6 个关键入口文件即可

3. 合理使用续聊

   • 同一问题的增量需求用 --session，能保留上下文

4. 路径尽量可解析

   • --file 传仓库内相对路径最稳妥

5. 结果统一落盘

   • 使用 -o 指定输出路径，便于流水线集成和日志收集

---

故障排查

1）提示缺少命令

• 报错：[ERROR] Missing required command: codex 或 jq
• 处理：安装对应命令并确保在 PATH 中可见

2）任务为空

• 报错：[ERROR] Request text is empty...
• 处理：提供位置参数、--task 或标准输入内容

3）workspace 不存在

• 报错：[ERROR] Workspace does not exist: ...
• 处理：确认 -w 路径正确

4）有 stderr 输出但无结果

• 检查 output_path 文件内容与 stderr 信息
• 确认 Codex 执行环境、权限与模型参数是否正确

---

适用场景建议

适合：

• 批量重构
• 多文件一致性改造
• 自动补充测试/文档
• 在 CI 或脚本化流程中调用 Codex

不建议：

• 需要复杂交互式人工判断、频繁手动确认的流程

---

许可证

MIT