kai/deep_research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.20 alpha skill-driven python core

Browse Source
This commit is contained in:
kai
2026-05-06 16:26:41 +08:00
parent d1169646b8
commit db626f1d58
87 changed files with 5213 additions and 2865 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/codex-usage.md
+43 -43
View File
@@ -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 主体能启动：
docs/platform-adapters.md
+170
View File
@@ -0,0 +1,170 @@
# v0.20 Platform Adapters
> v0.20 的唯一核心入口是 Python core：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml`、`.agents/skills`。所有 IDE/CLI agent 只做 surface adapter。
## Shared Rule
不要让平台 agent 自己调度 Phase 2 并发、模型选择或上下文压缩。平台只负责：
- 运行 `uv run python scripts/dr.py ...`
- 展示产物路径与失败包
- 做少量人工访谈、审阅、解释
- 必要时调用其原生强模型做“补充审校”，但不得覆盖 Python runtime 的产物 schema
最小可执行链路：
```bash
uv run python scripts/dr.py init "研究主题" --slug <slug> --method mckinsey_market
uv run python scripts/dr.py frame <slug>
uv run python scripts/dr.py research <slug> --workers 6
uv run python scripts/dr.py research <slug> --workers 6 --execute-packets
uv run python scripts/dr.py research <slug> --workers 6 --build-briefs
uv run python scripts/dr.py research <slug> --workers 6 --assemble-chapters
uv run python scripts/dr.py review <slug>
uv run python scripts/dr.py finalize <slug>
```
## OpenCode
官方机制：OpenCode 支持 `.opencode/commands/*.md` 自定义命令；文件名就是 slash command，内容是 prompt，frontmatter 可指定 `agent`、`model`、`subtask`。OpenCode 也支持 primary/subagent 两类 agent，但 v0.20 不再把平台 subagent 当默认并发机制。
本项目调用方式：
```text
/dr-init "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market
/dr-frame adc-global-landscape
/dr-research adc-global-landscape
/dr-review adc-global-landscape
/dr-finalize adc-global-landscape
/dr-status adc-global-landscape
```
使用建议：
- OpenCode 适合做表层 TUI、人工访谈和快速查看状态。
- 不要让 `dr-pm` 在 OpenCode 里 spawn 多个 dr-analyst；Phase 2 并发已经由 Python worker pool 控制。
- 如果要用 OpenCode 原生模型优势，只用于 `frame` 前的人工访谈或 `review` 后的解释，不改变 `configs/models.yaml` 的 role/task 映射。
## Codex
官方机制：Codex CLI 使用 `AGENTS.md` 作为项目指令；用户级配置位于 `~/.codex/config.toml` 或 `$CODEX_HOME/config.toml`，项目级 `.codex/**` 只作为可选覆盖。v0.20 推荐用部署脚本把 adapter 模板写到用户级 Codex home，避免在研究项目里维护 `.codex`。Codex 可通过 `/model` 选择 GPT 系列模型、通过 `/permissions` 调整审批/沙盒，也支持多 agent thread，但 v0.20 默认不使用它做研究并发。
本项目调用方式：
```bash
uv run python scripts/deploy_adapters.py codex --force
codex
```
默认部署不会复制 `config.toml`，避免覆盖用户级 Codex 设置；只有明确需要 bundled `deep-research` profile 时才加 `--include-config`，然后用 `codex --profile deep-research`。
在 Codex 里直接要求：
```text
运行：uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market
```
或用已有 wrapper prompt：
```bash
codex exec "$(uv run python scripts/dr.py prompt dr-run 'adc-global-landscape')"
codex exec "$(uv run python scripts/dr.py prompt dr-research 'adc-global-landscape')"
```
使用建议：
- Codex 原生 GPT 系列适合代码改造、回归测试、schema/debug、review。
- 研究模型混合仍由 Python core 调 ZenMux；Codex 当前会话模型不决定 `dr_analyst`、`dr_verifier` 等 role。
- `codex_native` profile 可用于偏 OpenAI/GPT 的执行环境，但仍通过 `configs/models.yaml` 解析。
## Claude Code
官方机制：Claude Code 推荐用 `.claude/skills/<name>/SKILL.md` 定义可调用 skill；目录名成为 slash command。旧 `.claude/commands/*.md` 仍兼容，但 skill 优先。Claude Code 的优势是 Claude/Opus/Sonnet 对长文风格和中文润色的稳定性。
本项目调用方式：
```bash
claude
```
在 Claude Code 中：
```text
/dr-run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market
/dr-research adc-global-landscape
/dr-finalize adc-global-landscape
```
使用建议：
- Claude Code 适合 Phase 1 人工访谈增强、Phase 4 中文风格润色建议、复杂报告结构讨论。
- 默认不要让 Claude Code 直接整章写作或并发 spawn；让 Python core 生成 packets、briefs、drafts。
- 若想优先用 Claude/Opus 成本包，可在 `configs/models.yaml` 里选择或新增 profile，而不是在 Claude Code prompt 里手工指定。
## Gemini CLI
官方机制：Gemini CLI 支持 `GEMINI.md` 作为项目记忆，也支持 `.gemini/commands/*.toml` 自定义命令；TOML command 用 `prompt` 字段，支持 `{{args}}` 参数和 `!{...}` shell 注入。
本项目调用方式：
```bash
gemini
```
在 Gemini CLI 中：
```text
/dr:run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market
/dr:research adc-global-landscape
/dr:review adc-global-landscape
/dr:finalize adc-global-landscape
```
使用建议：
- Gemini CLI 适合长上下文审校、框架替代方案、图表/多模态材料理解。
- 对需要本地 shell 的命令，Gemini CLI 会在执行 shell injection 前要求确认，这是好事。
- 研究执行仍以 Python core 为准；Gemini 模型可作为 `phase3_review` 或 `final_editorial` profile 的候选模型。
## Antigravity
官方公开资料把 Antigravity 定位为 agent-first IDE：agent 可访问 editor、terminal、browser，并可并行规划、执行、验证。它适合把开发者提升为 Agent Manager，但不适合让每个 Antigravity agent 自己维护 Deep Research 的状态机。
本项目调用方式：
1. 在 Antigravity 打开仓库根目录。
2. 确认 agent 能读 `AGENTS.md`。
3. 给 Agent Manager 一个明确任务：
```text
请只作为 surface adapter，不要自行调度研究 agent。
在终端运行：
uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market
然后汇报生成的项目目录、framework 路径和下一步命令。
```
使用建议：
- Antigravity 的 Gemini/Opus/Gemini Computer Use/Browser 能力适合可视化 QA、PDF/HTML 预览、跨文件审阅。
- 如果 Antigravity 提供 Opus 和 Gemini 模型，优先用它们做“表层审阅/交互”，不要替代 Python core 的 role/task 模型。
- 对高成本/长任务，要求 Antigravity 先 dry-run，再运行真实 `--execute-packets`。
## Model Strategy Across Platforms
| Platform | Surface model priority | Deep Research model source |
|---|---|---|
| OpenCode | 可用 Claude/ZenMux provider 做 TUI 增强 | `configs/models.yaml` |
| Codex | GPT 系列用于代码、测试、schema、review | `configs/models.yaml` |
| Claude Code | Opus/Sonnet 用于访谈、中文风格、结构讨论 | `configs/models.yaml` |
| Gemini CLI | Gemini 用于长上下文、多模态、框架审阅 | `configs/models.yaml` |
| Antigravity | Gemini/Opus 用于 IDE agent、browser/PDF QA | `configs/models.yaml` |
核心原则：平台模型负责“怎么帮用户操作项目”，ZenMux/Python role 模型负责“研究任务用哪个模型执行”。
## Sources
- OpenCode commands and agents: https://opencode.ai/docs/commands/ , https://opencode.ai/docs/agents/
- Codex CLI slash commands and config: https://developers.openai.com/codex/cli/slash-commands , https://developers.openai.com/codex/config-reference
- Claude Code skills/slash commands: https://code.claude.com/docs/en/slash-commands
- Gemini CLI custom commands: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md
- Google Antigravity announcement: https://blog.google/products-and-platforms/products/gemini/gemini-3/