v0.10: add native Codex adapter for deep research

docs/codex-usage.md

@@ -1,6 +1,24 @@
-# Codex Usage
+# Codex Native Adapter
 
-> v0.9 的 Codex 兼容是第一阶段：不复刻 OpenCode subagent，而是沿用 AGENTS.md 的研究规则和 Python 脚本流水线。Codex 负责规划、审阅、修补、执行脚本；确定性编排交给脚本。
+> 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
 
@@ -9,56 +27,77 @@ 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 调度已经稳定：
+首次使用 Codex adapter 前确认：
 
 ```bash
-opencode
-/dr-init <topic>
-/dr-frame <slug>
-/dr-research <slug>
-/dr-review <slug>
+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>
 ```
 
-Codex 可用于：
+## Codex Commands
 
-- 审阅 `framework.md` 和 `critique.md`
-- 修正文档、脚本和配置
-- 运行静态检查、引用检查和出稿脚本
-- 对某个章节做人工式复核建议
-
-### Phase 4
-
-Codex 可直接运行 Python 化流水线：
+Codex custom command templates 位于 `.codex/commands/`。在 CLI 中可以用 `scripts/dr.py prompt` 展开：
 
 ```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>
+uv run python scripts/dr.py prompt dr-frame dual-target-rnai-pipeline-2026
+codex exec "$(uv run python scripts/dr.py prompt dr-frame dual-target-rnai-pipeline-2026)"
+```
+
+建议流程：
+
+```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/translate.py <slug> --workers 1
-uv run python scripts/polish.py <slug> --workers 1
-uv run python scripts/build_glossary.py <slug> --workers 3
+uv run python scripts/dr.py finalize <slug> \
+  --translate-workers 1 \
+  --glossary-workers 3 \
+  --polish-workers 1
 ```
 
+## Subagent Usage
+
+Codex subagents 不会自动启动；主线程必须明确要求。例如：
+
+```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 提交系统迭代时必须只 stage 相关系统文件：
+本仓库常有大量 `projects/**` 研究产物处于修改状态。Codex adapter 提交时只 stage 系统文件：
 
 ```bash
-git add README.md PLAN.md docs configs scripts .opencode/commands/dr-finalize.md
+git add .codex .agents/skills scripts/dr.py docs configs README.md PLAN.md
 git diff --staged --name-only
 ```
 
@@ -68,18 +107,17 @@ git diff --staged --name-only
 - 已生成 PDF/DOCX/TXT
 - 临时检查脚本或一次性研究产物
 
-## What Codex Should Not Do Yet
+## Installing Hidden Directories
 
-- 不直接替代 OpenCode 的 `/dr-research` 多 agent 调度。
-- 不在 Codex 内复刻 dr-analyst/dr-verifier 的长流程并行。
-- 不把普通网页当作 Tier 1-2 证据。
-- 不在未检查 staged 列表前 commit。
+如果 Codex 桌面沙盒禁止 agent 写入 `.codex` 或 `.agents/skills`，请在本机直接运行：
 
-## Future Platform Adapters
+```bash
+uv run python scripts/install_codex_adapter.py --force
+```
 
-后续 Gemini CLI / Claude Code 兼容应沿用同一原则：
+安装来源：
 
-1. 共享 `AGENTS.md` 方法论。
-2. 共享 `scripts/` 的确定性流水线。
-3. 平台只提供交互、审阅、调度或修补能力。
-4. 不为每个平台复制一套研究逻辑。
+- `codex_adapter_templates/codex/**` → `.codex/**`
+- `.opencode/skills/**` → `.agents/skills/**`
+
+安装后，在 Codex 中运行 `/debug-config`，确认 project `.codex/config.toml` 已加载。