# v0.20 Platform Adapters

> v0.20 的默认核心入口是 Python core：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml`、`platform_adapters/**`。各平台运行环境由 `scripts/update_platform_envs.py` 重建到 `platform_envs/`。Antigravity 例外：它在生成的 `platform_envs/antigravity` 中使用 `.agent/skills` 与 `.agent/rules` 走 native Deep Research，让 Antigravity 模型配额承担主要研究工作。

## Shared Rule

除 Antigravity native 模式外，不要让平台 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>
```

Antigravity 不走这条最小链路作为默认研究主流程；详见下方 Antigravity 章节。

## 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 工作；浏览器操作由 browser subagent 执行；Agent Manager 可管理多个任务流和 artifacts。基于 Codex 的 skill-driven 经验，本项目在 Antigravity 中不再默认把研究主流程交给 Python model workers，而是让 Antigravity 用自己的模型配额按 phase 执行研究。

本项目已提供 Antigravity adapter 源模板。注意：Git 跟踪的是非隐藏源目录 `platform_adapters/antigravity/agent/`；Antigravity 实际打开的是脚本生成的 `platform_envs/antigravity`，其中才包含 `.agent/` 单数目录。

- `platform_adapters/antigravity/agent/agents.md`：Antigravity 角色定义，只定义 Research Manager / Strategist / Analyst / Reviewer / Final Editor 等角色。
- `platform_adapters/antigravity/agent/skills/antigravity-surface-adapter/SKILL.md`：Antigravity 专用执行说明。
- `platform_adapters/antigravity/agent/skills/method-selection/SKILL.md`：按场景选择研究方法，避免默认套用麦肯锡/MECE。
- `platform_adapters/antigravity/agent/skills/research-quality-gates/SKILL.md`：把 search receipt、source access、claims ledger、delta retrieve、continuation state 和 final fact check 做成阶段质量门。
- `platform_adapters/antigravity/agent/rules/deep-research-antigravity.md`：workspace rule，约束其优先使用 Antigravity 模型配额，避免主流程落回 ZenMux。
- `platform_adapters/antigravity/agent/workflows/deep-research-native.md`：可按 slash workflow 执行的四阶段研究流程与反幻觉 gate。

推荐方式是重建 clean workspace，只让 Antigravity 看到必要文件：

```bash
python scripts/update_platform_envs.py --platform antigravity
```

然后打开 `platform_envs/antigravity`。也可以使用 sparse checkout，见 `docs/antigravity-clean-workspace.md`。

部署到另一个 Antigravity workspace：

```bash
uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace --dry-run
uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace
```

该命令只写 workspace-local `.agent/agents.md`、`.agent/skills`、`.agent/rules` 和 `.agent/workflows`，不修改全局 Antigravity/Gemini 设置；已有文件默认跳过，`--force` 才会备份为 `.bak` 后覆盖。

本项目调用方式：

1. 在 Antigravity 打开 `platform_envs/antigravity`，不要打开完整多平台仓库。
2. 在 Customizations / Rules 中确认 workspace rule 已启用；若未自动启用，手动 at mention `deep-research-antigravity` 或直接引用该文件。
3. 选择模型：

| Phase / 工作 | Antigravity model | 用法 |
|---|---|---|
| Surface 管理、读 skill、状态推进 | Gemini 3 Flash | 管任务清单、跑轻量命令、收集 artifact |
| Phase 0-1 材料解读、框架规划 | Claude Opus 4.6 (Thinking) | 大局观、研究假设、章节结构 |
| Phase 2 证据包与章节草稿 | Gemini 3.1 Pro (Low) | 质量/速度均衡，按 skill 写 artifacts |
| Phase 3 总编审校 | Gemini 3.1 Pro (High) | 先试高强度 Gemini，不行再换 |
| Phase 4 最终统稿 | Claude Opus 4.6 (Thinking) | 保证中文终稿和交付质量 |

4. 给 Agent Manager 一个明确任务：

```text
请加载 .agent/agents.md、.agent/rules/deep-research-antigravity.md、.agent/skills/antigravity-surface-adapter/SKILL.md、.agent/skills/research-quality-gates/SKILL.md 和 AGENTS.md。
这是生成的 Antigravity clean workspace，不要读取父级仓库里的其他平台 adapter。
用 Gemini 3 Flash 做流程管理，按 skill 要求在需要时提示我切换模型。
研究主题："ADC 全球竞争格局"，slug: adc-global-landscape，method: mckinsey_market。
请先创建/确认项目目录，然后进入 Phase 0-1，并在生成 phase1/framework.md 和 research_brief 后暂停。
```

使用建议：

- Antigravity 的 Gemini/Opus/Gemini Computer Use/Browser 能力适合可视化 QA、PDF/HTML 预览、跨文件审阅。
- Opus 额度有限，但 Phase 0-1 和 Phase 4 的价值最高，优先花在框架和终稿，不花在 routine 管理。
- 不要默认运行 `dr.py run`、`research --execute-packets`、`research --assemble-chapters`，这些会把主流程重新导向 Python/ZenMux。
- Python core 可用于 `init/status/skills validate/finalize/render` 等辅助动作。
- 若本机安装了 `paperfoot/search-cli` 的 `search` 命令，Antigravity Phase 0-2 可优先用 `search agent-info`、`search ... --json` 做统一检索入口。
- Phase 2 不只产出章节草稿；必须维护 `search_log.jsonl`、`sources.jsonl`、`claims_ledger.jsonl`、`coverage_matrix.md` 和 `unsupported_claims.md`，否则 Phase 3/4 不得声称已验证。
- 不建议依赖 SOUL.md：它不是 Antigravity 官方 Deep Research 约束入口。本项目用 `AGENTS.md`、`.agent/agents.md`、`.agent/rules`、`.agent/skills` 和 `.agent/workflows` 分层约束。

## 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 Flash/Opus/Gemini Pro 分 phase 执行研究 | `platform_envs/antigravity/.agent/skills` + Antigravity model selector |

核心原则：除 Antigravity 外，平台模型负责“怎么帮用户操作项目”，ZenMux/Python role 模型负责“研究任务用哪个模型执行”。Antigravity 专门走 native 模式，以消耗 Antigravity 自身模型配额并降低 Python-core 碎片化风险。

## 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/
- Google Antigravity rules/workflows: https://antigravity.google/docs/rules-workflows
- Google Antigravity skills: https://antigravity.google/docs/skills
- Google Antigravity models: https://antigravity.google/docs/models
- Google Antigravity permissions: https://antigravity.google/docs/agent-permissions
- paperfoot/search-cli skill: https://github.com/paperfoot/search-cli/blob/master/SKILL.md
- Gemini CLI GEMINI.md context: https://geminicli.com/docs/cli/gemini-md/
- Gemini CLI GEMINI.md examples issue: https://github.com/google-gemini/gemini-cli/issues/9241
- Practical GEMINI.md hierarchy: https://medium.com/google-cloud/practical-gemini-cli-instruction-following-gemini-md-hierarchy-part-1-3ba241ac5496
- Claude Code best-practice CLAUDE.md: https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md
- Claude MD guide: https://github.com/MuhammadUsmanGM/claude-code-best-practices/blob/main/guides/claude-md-guide.md
- Writing a good CLAUDE.md: https://www.humanlayer.dev/blog/writing-a-good-claude-md