171 lines
7.5 KiB
Markdown
171 lines
7.5 KiB
Markdown
# 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/
|