v0.20 alpha skill-driven python core

docs/codex-usage.md

@@ -1,6 +1,6 @@
 # Codex Native Adapter
 
-> v0.10 起，Codex 不再只是 OpenCode 的辅助执行环境，而是 Deep Research 的并列 adapter。共享核心是 `AGENTS.md`、`scripts/`、`configs/` 和 `.agents/skills`；OpenCode 使用 `.opencode/**`，Codex 使用 `.codex/**`。
+> v0.20 起，Codex 是 Deep Research 的表层 adapter。共享核心迁移到 Python runtime：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml` 和 `.agents/skills`。Codex 不再复制核心调度逻辑。
 
 ## Architecture
 
@@ -8,17 +8,17 @@
 |---|---:|---:|---:|
 | 方法论 | `AGENTS.md` | ✅ | ✅ |
 | Skills | `.agents/skills` | 继续保留 `.opencode/skills` | ✅ |
-| Agent 定义 | 否 | `.opencode/agents/*.md` | `.codex/agents/*.toml` |
-| 命令入口 | 部分共享脚本 | `.opencode/commands/*.md` | `.codex/commands/*.md` + `scripts/dr.py` |
+| Agent 定义 | Python role runtime 为准 | `.opencode/agents/*.md` 仅兼容 | `$CODEX_HOME/agents/*.toml` 仅兼容 |
+| 命令入口 | `scripts/dr.py` | `.opencode/commands/*.md` wrapper | `$CODEX_HOME/commands/*.md` wrapper |
 | Phase 4 确定性流水线 | `scripts/*.py` | ✅ | ✅ |
 
 Codex 官方行为要点：
 
-- 项目级配置放在 `.codex/config.toml`，项目被 trust 后才会加载。
+- 用户级配置放在 `~/.codex/config.toml` 或 `$CODEX_HOME/config.toml`；项目级 `.codex/**` 不是 v0.20 推荐路径。
 - Codex 会从项目根向当前目录读取 `AGENTS.md`。
 - repo skills 放在 `.agents/skills/*/SKILL.md`。
-- custom agents 放在 `.codex/agents/*.toml`。
-- subagents 只有在主线程明确要求时才会启动。
+- adapter templates 保存在 `codex_adapter_templates/codex/**`，部署脚本会复制到 `$CODEX_HOME`。
+- subagents/agent threads 是 Codex 表层增强能力；v0.20 默认研究并发由 Python worker pool 执行。
 
 ## Setup
 
@@ -30,19 +30,21 @@ source scripts/activate.sh
 首次使用 Codex adapter 前确认：
 
 ```bash
-uv run python scripts/install_codex_adapter.py
-find .codex -maxdepth 3 -type f | sort
+uv run python scripts/deploy_adapters.py codex --dry-run
+uv run python scripts/deploy_adapters.py codex --force
 find .agents/skills -maxdepth 2 -name SKILL.md | sort
 uv run python scripts/dr.py status <slug>
 ```
 
+默认部署不会写入 `config.toml`，避免覆盖现有 Codex 全局配置。只有确认要安装本项目 bundled profile 时，才运行 `uv run python scripts/deploy_adapters.py codex --force --include-config`。
+
 新机器部署后可以先跑自检：
 
 ```bash
 uv run python scripts/deploy_check.py
 ```
 
-如果隐藏目录缺失或 skills 没同步：
+如果 `$CODEX_HOME` adapter 缺失或 skills 没同步：
 
 ```bash
 uv run python scripts/deploy_check.py --repair --force
@@ -58,17 +60,19 @@ uv run python scripts/deploy_check.py --repair --force
 
 ## Codex Commands
 
-Codex custom command templates 位于 `.codex/commands/`。在 CLI 中可以用 `scripts/dr.py prompt` 展开：
+Codex custom command templates 的真源位于 `codex_adapter_templates/codex/commands/`，部署后位于 `$CODEX_HOME/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 审校决策这类人类暂停点需要停下来。
+推荐入口是 Python core。Codex command 只包装 CLI，不再让 Codex 主线程主动调度 subagents。
 
 ```bash
-codex exec "$(uv run python scripts/dr.py prompt dr-run <slug-or-topic>)"
+uv run python scripts/dr.py run <slug-or-topic>
+uv run python scripts/dr.py research <slug> --workers 6
+uv run python scripts/dr.py finalize <slug>
 ```
 
 分阶段命令保留为调试和人工接管入口：
@@ -81,17 +85,16 @@ codex exec "$(uv run python scripts/dr.py prompt dr-review <slug>)"
 uv run python scripts/dr.py finalize <slug>
 ```
 
-Phase 4 推荐走确定性 CLI，而不是让单个 agent 翻译整篇：
+Phase 4 默认中文原生成稿：
 
 ```bash
-uv run python scripts/dr.py finalize <slug> \
-  --model-profile medium
+uv run python scripts/dr.py finalize <slug> --model-profile medium
 ```
 
-等价底层入口（统一 pipeline）：
+旧英译中 pipeline 仅用于兼容旧项目：
 
 ```bash
-uv run python scripts/phase4_pipeline.py <slug>
+uv run python scripts/dr.py finalize <slug> --legacy-translate
 ```
 
 网络不稳时可显式降并发：
@@ -112,31 +115,16 @@ uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mo
 uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode off
 ```
 
-## Subagent Usage
+## Adapter Boundary
 
-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`：出稿执行与格式验证。
+Codex 可以继续用于审阅、解释和少量人工接管，但默认研究并发由 Python task-card runtime 控制。模型选择与 role/task 映射以 `configs/models.yaml` 为准。
 
 ## Git Hygiene
 
 本仓库常有大量 `projects/**` 研究产物处于修改状态。Codex adapter 提交时只 stage 系统文件：
 
 ```bash
-git add .codex .agents/skills scripts/dr.py docs configs README.md PLAN.md
+git add codex_adapter_templates .agents/skills scripts docs configs README.md PLAN.md AGENTS.md
 git diff --staged --name-only
 ```
 
@@ -146,26 +134,38 @@ git diff --staged --name-only
 - 已生成 PDF/DOCX/TXT
 - 临时检查脚本或一次性研究产物
 
-## Installing Hidden Directories
+## Deploying Adapter Files
 
-如果 Codex 桌面沙盒禁止 agent 写入 `.codex` 或 `.agents/skills`，请在本机直接运行：
+不要在仓库内维护 `.codex/**`。如果需要 Codex native adapter，请把模板部署到用户级 Codex home：
+
+```bash
+uv run python scripts/deploy_adapters.py codex --force
+```
+
+兼容旧命令仍可用，但默认也会走外部部署：
 
 ```bash
 uv run python scripts/install_codex_adapter.py --force
 ```
 
-安装来源：
+部署来源：
 
-- `codex_adapter_templates/codex/**` → `.codex/**`
-- `.opencode/skills/**` → `.agents/skills/**`
+- `codex_adapter_templates/codex/**` → `$CODEX_HOME/**` 或 `~/.codex/**`
+- `.agents/skills/**` → `$CODEX_HOME/skills/**`
 
-安装后，在 Codex 中运行 `/debug-config`，确认 project `.codex/config.toml` 已加载。
+如果旧版本已经把仓库内 `.codex/**` 加进 Git，需要在本机清一次索引，让它回到“本地部署产物”身份：
+
+```bash
+git rm -r --cached .codex
+```
+
+部署后，在 Codex 中运行 `/debug-config`，确认 user config 或 `CODEX_HOME` config 已加载。
 
 ## Config Troubleshooting
 
-如果 `.codex/config.toml` 生效后启动报错，先按下面顺序排查：
+如果 Codex adapter 配置生效后启动报错，先按下面顺序排查：
 
-1. 确认当前 project 已被 Codex trust。未 trust 时，Codex 会跳过项目级 `.codex/**`，此时 `--profile deep-research` 会报 profile 不存在。
+1. 确认部署目标正确：默认是 `$CODEX_HOME`，未设置时是 `~/.codex`。
 2. Tavily / Brave / Exa MCP 默认启用但不是 required。若某个 server 启动异常，先确认对应环境变量存在，再临时把该 server 改成 `enabled = false`。
 3. 如果要完全离线排障，先把第三方 MCP 全部关掉，只保留 OpenAI Docs MCP 和内置 web search。
 4. 如果仍然报错，临时保留最小配置确认 Codex 主体能启动：