# Codex Usage

> v0.9 的 Codex 兼容是第一阶段：不复刻 OpenCode subagent，而是沿用 AGENTS.md 的研究规则和 Python 脚本流水线。Codex 负责规划、审阅、修补、执行脚本；确定性编排交给脚本。

## Setup

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

Codex 会读取项目根目录的 `AGENTS.md`，研究方法、信源分级、输出规范仍与 OpenCode 一致。

## Recommended Codex Workflow

### Phase 1-3

OpenCode 仍是主入口，因为 `.opencode/commands` 与 subagent 调度已经稳定：

```bash
opencode
/dr-init <topic>
/dr-frame <slug>
/dr-research <slug>
/dr-review <slug>
```

Codex 可用于：

- 审阅 `framework.md` 和 `critique.md`
- 修正文档、脚本和配置
- 运行静态检查、引用检查和出稿脚本
- 对某个章节做人工式复核建议

### Phase 4

Codex 可直接运行 Python 化流水线：

```bash
uv run python scripts/translate.py <slug> --workers 4
uv run python scripts/build_glossary.py <slug> --workers 4
uv run python scripts/apply_glossary.py <slug> --input phase4/final_zh.md --dry-run
uv run python scripts/apply_glossary.py <slug> --input phase4/final_zh.md
uv run python scripts/polish.py <slug> --workers 4
uv run python scripts/build_report.py <slug>
```

网络不稳时：

```bash
uv run python scripts/translate.py <slug> --workers 1
uv run python scripts/polish.py <slug> --workers 1
uv run python scripts/build_glossary.py <slug> --workers 3
```

## Git Hygiene

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

```bash
git add README.md PLAN.md docs configs scripts .opencode/commands/dr-finalize.md
git diff --staged --name-only
```

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

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

## What Codex Should Not Do Yet

- 不直接替代 OpenCode 的 `/dr-research` 多 agent 调度。
- 不在 Codex 内复刻 dr-analyst/dr-verifier 的长流程并行。
- 不把普通网页当作 Tier 1-2 证据。
- 不在未检查 staged 列表前 commit。

## Future Platform Adapters

后续 Gemini CLI / Claude Code 兼容应沿用同一原则：

1. 共享 `AGENTS.md` 方法论。
2. 共享 `scripts/` 的确定性流水线。
3. 平台只提供交互、审阅、调度或修补能力。
4. 不为每个平台复制一套研究逻辑。