本指南旨在将 Claude Code CLI 和 Codex CLI 定义为通用的“智能算力节点”。它们不仅是代码助手，更是集成到自动化流水线中的高级推理引擎。
直接调用 LLM API（如 chat/completions）虽然简单，但在处理复杂任务（如全文翻译、大规模重构）时存在明显短板。引入 CLI Agent 作为中间层有以下核心优势：
- 对抗“模型偷懒” (Anti-Laziness)：
当任务量大时，直接调 API 容易导致模型输出
(此处省略...)或截断。CLI Agent（尤其是 Claude Code）天生具备“循环执行”和“自我纠正”能力，它能感知文件状态，分块或循环操作，确保任务真正完成。 - 原生文件上下文支持： 它们能自动处理文件读取、编码和写入，将“推理”与“IO”解断。你只需要下达目标（Goal），剩下的读取细节由 Agent 优化。
- 继承工具链 (Tool-Rich Environment)：
它们内置了成熟特有的 MCP (Model Context Protocol) 插件。例如在我们的环境里，它们可以随时调用
Tavily进行联网搜索，或者写临时脚本来处理数据，这些能力通过 API 模拟成本极高。 - 优化后的上下文管理： Agent 框架会自动处理 Context Window 的消耗和长对话的压缩，这比手动编写 API 逻辑更稳健且高效。
在生产环境中，严禁使用 echo | claude 这种管道模式处理核心逻辑。我们统一采用文件响应模式 (File-Based Mode)。
- 确定性：AI 在“编辑文件”时的心理模型是“完成工作并保存”，而在“对话”时的心理模型是“回答问题”。前者更不容易产生截断。
- 可审计：任务前后文件系统的变化（git diff）是唯一的真理。
- 大容量：绕过了命令行参数长度限制，让 Agent 自己决定如何高效读取文件。
# 1. 准备上下文（将待处理内容存入文件）
cp raw_data.json task_context.json
# 2. 下达指令（让 Agent 修改该文件）
codex exec --full-auto "读取 task_context.json，将其中的中文翻译为英文，保持 JSON 结构不变。直接修改原文件。"在我们的自动化翻译脚本中，我们不再手动解析文本发送给 API，而是直接把整个 Tiptap JSON 交给 CLI Agent。
# 核心逻辑：直接让 Agent 修改目标文件
prompt = f"""你是一个专业内容翻译官。
1. 读取 {target_file}。
2. 将其中的 Tiptap JSON 文本节点从中文翻译为英文。
3. 保持专业术语（如 "vibe coding"）不变。
4. 确保文件仍然是合法的 JSON 格式。
直接在原文件上修改。"""
# 调用命令 (以 Codex 为例，使用最新模型与推理控制)
subprocess.run([
"codex", "exec",
"--dangerously-bypass-approvals-and-sandbox",
"-m", "gpt-5.2", # 显式指定最新模型
"-c", 'model_reasoning_effort="low"', # 调整推理强度（low/medium/high）
"-C", str(target_dir),
prompt.replace('\0', '') # 重要：清理 Nul Byte 以免触发系统错误
])在 GPT-5.2 时代，我们可以通过参数精确控制 AI 的“思考成本”和“推理深度”。
-m, --model: 推荐使用gpt-5.2。这是专为 Agentic 工作流优化的版本，在处理长上下文和复杂重构时表现更稳。-c model_reasoning_effort:low: 适合简单的格式转换、文本翻译、README 更新。速度极快，成本低。medium(默认): 适合常规 Bug 修复、单文件重构。high: 适合跨文件逻辑迁移、深层代码审计。
性能贴士：对于批量翻译等任务，强制指定
low可以将响应速度提升 2x 以上，且基本不影响直译质量。
在长耗时任务（如大规模翻译）中，单纯等待进程结束（Block）会失去对任务进度的感知。我们鼓励使用 JSON 流 (Streaming JSON) 模式。
- Claude Code: 使用
--output-format stream-json。 - Codex: 使用
--json。它会输出包含thought(思考过程)、call(工具调用) 和response的结构化事件。
在编写集成脚本时，强烈建议默认开启并实时打印 AI 的日志（尤其是 thought 和 call 事件）。
- 透明性：开发者可以即时看到 AI 是否在正确读取文件，或者是否陷入了死循环。
- 调试效率：当任务失败时，最直观的错误原因通常就在最后几行
thought或call中。 - 反馈感：在处理大型文件时，滚动的实时日志比静止的进度条能提供更强的确定性。
对于多进程或长耗时任务，强烈建议应用程序将中间结果以 JSON Lines 格式打印到标准输出 (stdout)，即使是多进程交错输出也易于机器解析和监控。
标准日志字段：
{"event": "task_completed", "id": "post_123", "status": "success", "details": "Translated 5 comments"}- 必备字段：
event: 事件类型（如start,progress,complete,error）。id: 任务唯一标识（如post_id,file_path）。status: 当前状态。
- 目的：
- 实时可观测性：在 CI/CD 或终端中提供即时的进度反馈。
- 解耦：脚本只需负责打印 (Print) 中间状态到 stdout，无需负责汇总或解析最终的硬盘文件。外部工具若有需要，可直接通过管道消费这些日志。
警告：如果通过 stdin 传递 Prompt，或 Prompt 中包含不可见的 \0 字符，Codex CLI (Rust 核心) 会抛出 nul byte found 错误并崩溃。
对策：
- 优先将 Prompt 作为最后一个命令行参数传递，而非通过管道。
- 在传递前，务必对字符串执行
.replace('\0', '')。
| 场景 | 推荐参数 (Claude) | 推荐参数 (Codex) |
|---|---|---|
| 翻译/文档改写 | --permission-mode acceptEdits |
--full-auto |
| 自动化测试/部署 | --permission-mode bypassPermissions |
--dangerously-bypass-approvals-and-sandbox |
如果你正在编写一个 Agent（如 Gemini）来调用这些 CLI，请提供如下“元指令”：
“当面临大规模文本处理或文件系统操作时，请调用底层的
claude或codex。
- 优先使用文件响应模式，先将待处理内容存入本地临时文件。
- 使用流模式 (
--json) 并实时解析事件以便监控进度。- 设置合理的
reasoning_effort（如翻译设为low）。- 传递 Prompt 前清理空字符，并将其作为命令行参数传递。”
注：当前 Claude 配额受限时，优先使用 Codex 进行测试。
对于超大文件（超过 2000 行），系统会自动切换到并行模式以突破单线程速度瓶颈：
- 自动拆分：文件按每 1000 行拆分为独立的 chunks。
- 高并发：使用
ProcessPoolExecutor启动最多 8 个 workers 并行处理。 - 上下文保留：每个 worker 仍读取完整文件以保持上下文理解，但通过 Prompt 严格限制它们只修改分配的行范围。
- 效果：20k 行的巨型文件翻译仅需 ~8 分钟（串行需要 45+ 分钟）。
为了在无人值守的情况下处理复杂任务，Prompt 设计至关重要：
- 分块编辑指令：明确告诉 AI 如果文件太大，可以分块（如每 1000 行）进行编辑。
- 持久性指令：使用强烈的指令词（如 "MUST persist"、"complete the ENTIRE file"），防止 AI 中途偷懒或放弃。
- 自我纠正：要求 AI 在提交最终结果前进行自我质量检查和 JSON 格式验证。
为了防止大文件处理被意外 kill，系统采用动态超时策略：
- 计算公式：基准 10 分钟 + 每 5000 行增加 10 分钟。
- 范围限制：最少 10 分钟，最多 45 分钟。
- 粒度：每个并行 worker 都有独立的超时配额，确保复杂段落有足够时间处理。
经过测试，这是目前性价比最高的翻译配置：
- 模型：
gpt-5.2（比旧版更智能且稳定）。 - 推理强度 (Reasoning Effort)：
low。对于翻译任务，"low" 已经足够且速度最快，不需要 "high" 的深度推理成本。 - 调用示例:
codex exec ... -m gpt-5.2 -c 'model_reasoning_effort="low"' ...
在并发模式下，子进程的输出如果不强制刷新会被缓冲区卡住。
- 技巧：在 Python 脚本的
print()中强制使用flush=True。 - 效果：这确保了即使在 8 个进程并行狂奔时，你也能在终端看到交错但实时的进度日志（如
[L1-1000],[L2001-3000]），这对长耗时任务的心理安全感非常重要。