190 lines
6.5 KiB
Markdown
190 lines
6.5 KiB
Markdown
# Codex Native Adapter
|
||
|
||
> v0.20 起，Codex 是 Deep Research 的表层 adapter。共享核心迁移到 Python runtime：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml` 和 `.agents/skills`。Codex 不再复制核心调度逻辑。
|
||
|
||
## Architecture
|
||
|
||
| Layer | Shared | OpenCode | Codex |
|
||
|---|---:|---:|---:|
|
||
| 方法论 | `AGENTS.md` | ✅ | ✅ |
|
||
| Skills | `.agents/skills` | 继续保留 `.opencode/skills` | ✅ |
|
||
| 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` 或 `$CODEX_HOME/config.toml`；项目级 `.codex/**` 不是 v0.20 推荐路径。
|
||
- Codex 会从项目根向当前目录读取 `AGENTS.md`。
|
||
- repo skills 放在 `.agents/skills/*/SKILL.md`。
|
||
- adapter templates 保存在 `codex_adapter_templates/codex/**`，部署脚本会复制到 `$CODEX_HOME`。
|
||
- subagents/agent threads 是 Codex 表层增强能力；v0.20 默认研究并发由 Python worker pool 执行。
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
cd /Users/tankai/Documents/Projects/deep_research
|
||
source scripts/activate.sh
|
||
```
|
||
|
||
首次使用 Codex adapter 前确认：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
如果 `$CODEX_HOME` adapter 缺失或 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_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)"
|
||
```
|
||
|
||
推荐入口是 Python core。Codex command 只包装 CLI，不再让 Codex 主线程主动调度 subagents。
|
||
|
||
```bash
|
||
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>
|
||
```
|
||
|
||
分阶段命令保留为调试和人工接管入口：
|
||
|
||
```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 默认中文原生成稿：
|
||
|
||
```bash
|
||
uv run python scripts/dr.py finalize <slug> --model-profile medium
|
||
```
|
||
|
||
旧英译中 pipeline 仅用于兼容旧项目：
|
||
|
||
```bash
|
||
uv run python scripts/dr.py finalize <slug> --legacy-translate
|
||
```
|
||
|
||
网络不稳时可显式降并发：
|
||
|
||
```bash
|
||
uv run python scripts/dr.py finalize <slug> \
|
||
--model-profile medium \
|
||
--translate-workers 1 \
|
||
--glossary-workers 3 \
|
||
--polish-workers 1
|
||
```
|
||
|
||
术语核查策略可选：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## Adapter Boundary
|
||
|
||
Codex 可以继续用于审阅、解释和少量人工接管，但默认研究并发由 Python task-card runtime 控制。模型选择与 role/task 映射以 `configs/models.yaml` 为准。
|
||
|
||
## Git Hygiene
|
||
|
||
本仓库常有大量 `projects/**` 研究产物处于修改状态。Codex adapter 提交时只 stage 系统文件：
|
||
|
||
```bash
|
||
git add codex_adapter_templates .agents/skills scripts docs configs README.md PLAN.md AGENTS.md
|
||
git diff --staged --name-only
|
||
```
|
||
|
||
提交前确认 staged 列表不包含：
|
||
|
||
- `projects/**`
|
||
- 已生成 PDF/DOCX/TXT
|
||
- 临时检查脚本或一次性研究产物
|
||
|
||
## Deploying Adapter Files
|
||
|
||
不要在仓库内维护 `.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_HOME/**` 或 `~/.codex/**`
|
||
- `.agents/skills/**` → `$CODEX_HOME/skills/**`
|
||
|
||
如果旧版本已经把仓库内 `.codex/**` 加进 Git，需要在本机清一次索引，让它回到“本地部署产物”身份：
|
||
|
||
```bash
|
||
git rm -r --cached .codex
|
||
```
|
||
|
||
部署后，在 Codex 中运行 `/debug-config`，确认 user config 或 `CODEX_HOME` config 已加载。
|
||
|
||
## Config Troubleshooting
|
||
|
||
如果 Codex adapter 配置生效后启动报错，先按下面顺序排查：
|
||
|
||
1. 确认部署目标正确：默认是 `$CODEX_HOME`，未设置时是 `~/.codex`。
|
||
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。
|