deep_research/docs/codex-usage.md

Codex Native Adapter

v0.10 起，Codex 不再只是 OpenCode 的辅助执行环境，而是 Deep Research 的并列 adapter。共享核心是 AGENTS.md、scripts/、configs/ 和 .agents/skills；OpenCode 使用 .opencode/**，Codex 使用 .codex/**。

Architecture

Layer	Shared	OpenCode	Codex
方法论	AGENTS.md	✅	✅
Skills	.agents/skills	继续保留 .opencode/skills	✅
Agent 定义	否	.opencode/agents/*.md	.codex/agents/*.toml
命令入口	部分共享脚本	.opencode/commands/*.md	.codex/commands/*.md + scripts/dr.py
Phase 4 确定性流水线	scripts/*.py	✅	✅

Codex 官方行为要点：

• 项目级配置放在 .codex/config.toml，项目被 trust 后才会加载。
• Codex 会从项目根向当前目录读取 AGENTS.md。
• repo skills 放在 .agents/skills/*/SKILL.md。
• custom agents 放在 .codex/agents/*.toml。
• subagents 只有在主线程明确要求时才会启动。

Setup

cd /Users/tankai/Documents/Projects/deep_research
source scripts/activate.sh

首次使用 Codex adapter 前确认：

uv run python scripts/install_codex_adapter.py
find .codex -maxdepth 3 -type f | sort
find .agents/skills -maxdepth 2 -name SKILL.md | sort
uv run python scripts/dr.py status <slug>

新机器部署后可以先跑自检：

uv run python scripts/deploy_check.py

如果隐藏目录缺失或 skills 没同步：

uv run python scripts/deploy_check.py --repair --force

默认自动化权限：

• sandbox_mode = "workspace-write"：允许写入当前研究 workspace。
• approval_policy = "never"：命令执行不逐次弹窗。
• web_search = "live"：默认使用实时网络检索。
• [sandbox_workspace_write].network_access = true：脚本和 MCP server 默认可访问网络。
• Tavily / Brave / Exa MCP 默认启用，且 required = false，某个搜索服务临时不可用时不阻塞 Codex 主流程。

Codex Commands

Codex custom command templates 位于 .codex/commands/。在 CLI 中可以用 scripts/dr.py prompt 展开：

uv run python scripts/dr.py prompt dr-run dual-target-rnai-pipeline-2026
codex exec "$(uv run python scripts/dr.py prompt dr-run dual-target-rnai-pipeline-2026)"

推荐入口是 dr-run：让 Codex 主线程进入 PM 模式，读取 manifest，判断当前应该继续哪个 phase，并在 Phase 2 主动调度 dr-analyst / dr-verifier subagents。用户不需要逐个执行每个 phase；只有 Phase 1 框架确认和 Phase 3 审校决策这类人类暂停点需要停下来。

codex exec "$(uv run python scripts/dr.py prompt dr-run <slug-or-topic>)"

分阶段命令保留为调试和人工接管入口：

codex exec "$(uv run python scripts/dr.py prompt dr-init '<topic>')"
codex exec "$(uv run python scripts/dr.py prompt dr-frame <slug>)"
codex exec "$(uv run python scripts/dr.py prompt dr-research <slug>)"
codex exec "$(uv run python scripts/dr.py prompt dr-review <slug>)"
uv run python scripts/dr.py finalize <slug>

Phase 4 推荐走确定性 CLI，而不是让单个 agent 翻译整篇：

uv run python scripts/dr.py finalize <slug> \
  --model-profile medium

等价底层入口（统一 pipeline）：

uv run python scripts/phase4_pipeline.py <slug>

网络不稳时可显式降并发：

uv run python scripts/dr.py finalize <slug> \
  --model-profile medium \
  --translate-workers 1 \
  --glossary-workers 3 \
  --polish-workers 1

术语核查策略可选：

uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode low-confidence
uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode full
uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode off

Subagent Usage

Codex 的平台限制是：subagents 不会仅因为 .codex/agents/*.toml 存在就自动启动，必须由当前主线程明确要求。dr-run 已把这个要求写进 PM prompt：Phase 1 会调度 dr-plan / dr-searcher，Phase 2 会调度 dr-analyst / dr-verifier，Phase 3 会调度 dr-chief-editor。

Spawn dr-searcher agents in parallel for four keyword groups, wait for all results, then synthesize phase1/initial-scan.md.

推荐映射：

• dr-plan：访谈、框架、初扫综合。
• dr-pm：Phase 2 批次规划与调度。
• dr-searcher：轻量检索。
• dr-analyst：章节英文深研。
• dr-verifier：反方验证，必须独立于 analyst。
• dr-chief-editor：Phase 3 只读审校。
• dr-editor-in-chief：Phase 4 合稿与脚本调度。
• dr-reporter：出稿执行与格式验证。

Git Hygiene

本仓库常有大量 projects/** 研究产物处于修改状态。Codex adapter 提交时只 stage 系统文件：

git add .codex .agents/skills scripts/dr.py docs configs README.md PLAN.md
git diff --staged --name-only

提交前确认 staged 列表不包含：

• projects/**
• 已生成 PDF/DOCX/TXT
• 临时检查脚本或一次性研究产物

Installing Hidden Directories

如果 Codex 桌面沙盒禁止 agent 写入 .codex 或 .agents/skills，请在本机直接运行：

uv run python scripts/install_codex_adapter.py --force

安装来源：

• codex_adapter_templates/codex/** → .codex/**
• .opencode/skills/** → .agents/skills/**

安装后，在 Codex 中运行 /debug-config，确认 project .codex/config.toml 已加载。

Config Troubleshooting

如果 .codex/config.toml 生效后启动报错，先按下面顺序排查：

1. 确认当前 project 已被 Codex trust。未 trust 时，Codex 会跳过项目级 .codex/**，此时 --profile deep-research 会报 profile 不存在。
2. Tavily / Brave / Exa MCP 默认启用但不是 required。若某个 server 启动异常，先确认对应环境变量存在，再临时把该 server 改成 enabled = false。
3. 如果要完全离线排障，先把第三方 MCP 全部关掉，只保留 OpenAI Docs MCP 和内置 web search。
4. 如果仍然报错，临时保留最小配置确认 Codex 主体能启动：

model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "never"
project_doc_max_bytes = 65536
web_search = "live"

[agents]
max_threads = 6
max_depth = 1

[sandbox_workspace_write]
network_access = true

这个最小配置只启用模型、沙盒、项目说明、web search 与 subagent 上限；确认能启动后，再逐个恢复 profiles 和 MCP server。