124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# 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>
|
||
```
|
||
|
||
## Codex Commands
|
||
|
||
Codex custom command templates 位于 `.codex/commands/`。在 CLI 中可以用 `scripts/dr.py prompt` 展开：
|
||
|
||
```bash
|
||
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/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 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` 已加载。
|