# 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

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

首次使用 Codex adapter 前确认：

```bash
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>
```

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

```bash
uv run python scripts/deploy_check.py
```

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

```bash
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` 展开：

```bash
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 审校决策这类人类暂停点需要停下来。

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

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

```bash
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 翻译整篇：

```bash
uv run python scripts/dr.py finalize <slug> \
  --translate-workers 4 \
  --glossary-workers 4 \
  --polish-workers 4
```

网络不稳时：

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

## 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`。

```text
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 系统文件：

```bash
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`，请在本机直接运行：

```bash
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 主体能启动：

```toml
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。