6.5 KiB
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 生效后启动报错，先按下面顺序排查：
- 确认当前 project 已被 Codex trust。未 trust 时，Codex 会跳过项目级
.codex/**，此时--profile deep-research会报 profile 不存在。 - Tavily / Brave / Exa MCP 默认启用但不是 required。若某个 server 启动异常，先确认对应环境变量存在，再临时把该 server 改成
enabled = false。 - 如果要完全离线排障，先把第三方 MCP 全部关掉，只保留 OpenAI Docs MCP 和内置 web search。
- 如果仍然报错，临时保留最小配置确认 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。