v0.20 alpha skill-driven python core

AGENTS.md

@@ -1,15 +1,22 @@
 # AGENTS.md — 生物医药 Deep Research 系统规则
 
-> 本文件为 OpenCode 会自动读取的项目级指令文件。
-> 所有 agent / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。
+> 本文件为跨平台项目级指令文件。Codex、OpenCode、Claude Code、Antigravity、Gemini CLI 均应以本文件为运行规则。
+> 所有平台 adapter / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。
 
 ---
 
 ## 1. 项目使命
 
-本项目通过多 agent 协作，以**麦肯锡、德勤等顶尖机构的研究方法**，对生物医药领域（研发、工艺、管理、投资）的指定主题进行深度研究，输出专业级报告（PDF + DOCX）。
+本项目通过**Python core + skills + 可选多模型角色**协作，以**麦肯锡、德勤等顶尖机构的研究方法**，对生物医药领域（研发、工艺、管理、投资）的指定主题进行深度研究，输出专业级报告（PDF + DOCX）。
 
-本项目**不涉及代码开发**，所有"代码"都是为**研究流水线**服务（如 ReportLab 模板、下载脚本、信源 API 调用）。
+本项目**不涉及业务代码开发**，所有"代码"都是为**研究流水线**服务（如 Python runtime、ReportLab/Quarto 模板、下载脚本、信源 API 调用）。
+
+### 1.1 v0.20 架构原则
+
+- `scripts/dr.py` 与 `scripts/runtime/*` 是核心编排真源；OpenCode、Codex、Claude Code、Antigravity、Gemini CLI 只是表层入口。
+- 模型选择以 `configs/models.yaml` 为准，由 Python runtime 解析 role/task 映射。
+- Skills 以 `.agents/skills` 为 canonical registry；adapter skill 目录由 `uv run python scripts/dr.py skills sync` 同步。
+- 默认工作链路为中文主写作；英文只保留在检索关键词、原文摘录、source title、DOI/URL 与来源笔记中。
 
 ---
 
@@ -17,7 +24,7 @@
 
 ### 2.1 麦肯锡核心原则
 
-1. **MECE**（Mutually Exclusive, Collectively Exhaustive）：章节划分互斥且穷尽
+1. **研究方法适配场景**：MECE 是常用方法之一，但 GMP/CMC/管理咨询/研发立项等场景必须选择匹配框架
 2. **SCQA 叙事**（Situation → Complication → Question → Answer）：每章节开头用此结构引入
 3. **金字塔原理**：结论先行，论据支撑，纵向深入，横向 MECE
 4. **"每个标题即一个观点"**：标题不能是"概述""现状"这类模糊词，必须包含判断
@@ -55,28 +62,29 @@
 ## 3. Phase 工作流（4 阶段）
 
 ### Phase 1：框架规划
-- **驱动命令**：`/dr-init <topic>` → `/dr-frame`
-- **主导 agent**：dr-plan
-- **产出**：`projects/<slug>/phase1/framework.md`（8-15 章大纲，每 section 带研究思路与字数配额）
+- **驱动命令**：`uv run python scripts/dr.py init <topic>` → `uv run python scripts/dr.py frame <slug>`（`/dr-init`、`/dr-frame` 只是薄封装）
+- **主导入口**：Python core 生成项目骨架与 framework；dr-plan 可作为表层访谈增强
+- **产出**：`projects/<slug>/phase1/framework.md`（记录 research_method、8-15 章大纲，每 section 带研究思路与字数配额）
 - **暂停点**：用户确认框架
 
 ### Phase 2：深度研究
-- **驱动命令**：`/dr-research`
-- **主导 agent**：dr-pm（调度 3-4 个 dr-analyst 并行 + dr-verifier 反方验证）
-- **产出**：`projects/<slug>/phase2/drafts/chXX.md` + `evidence/chXX-evidence.md` + `sources.jsonl`
+- **驱动命令**：`uv run python scripts/dr.py research <slug> --workers 6`
+- **主导入口**：Python core 生成 task cards 并控制并发
+- **产出**：`projects/<slug>/phase2/task_cards.json` + `packets/*.json` + `drafts/chXX.md` + `evidence/chXX-evidence.md` + `sources.jsonl`
 - **不暂停**：全自动跑完
 
 ### Phase 3：总编审校
-- **驱动命令**：`/dr-review`
-- **主导 agent**：dr-chief-editor（Gemini 3.1 Pro 1M 上下文通读）
+- **驱动命令**：`uv run python scripts/dr.py review <slug>`（`/dr-review` 只是薄封装）
+- **主导入口**：Python core deterministic review；dr-chief-editor/Gemini 可作为后续深度审校增强
 - **产出**：`projects/<slug>/phase3/critique.md`
 - **暂停点**：用户决策（修正 / 回炉 phase2 / 整体重来）
 
 ### Phase 4：成稿
-- **驱动命令**：`/dr-finalize`
-- **主导 agent**：dr-editor-in-chief（创作）→ `scripts/phase4_pipeline.py`（执行链路）
-- **执行链路**：translate → glossary(optional) → apply_glossary → polish → build_report
-- **产出**：`phase4/final_en.md` + `phase4/final_zh.md` + `phase4/final_zh_polished.md` + `phase4/*.pdf` + `phase4/*.docx`
+- **驱动命令**：`uv run python scripts/dr.py finalize <slug>`
+- **主导入口**：Python core 中文原生成稿；OpenCode/Codex/Claude Code 只调用 CLI
+- **默认链路**：final_zh.md → glossary/check(optional) → polish(optional) → citation_check → build_report
+- **兼容链路**：仅显式 `--legacy-translate` 时使用 final_en.md → translate → polish
+- **产出**：`phase4/final_zh.md` + `phase4/final_zh_polished.md`（可选）+ `phase4/*.pdf` + `phase4/*.docx`
 
 ---
 
@@ -132,119 +140,56 @@
 
 ---
 
-## 5. Agent 角色与职责（v0.5 重构）
+## 5. Python Role / Task 模型
 
-> 每个 agent 的详细定义见 `.opencode/agents/*.md`
+平台 agent 文件只保留兼容和展示意义；真实角色、任务类型、模型、温度、并发上限以 Python runtime 为准。
 
-| Agent | 类型 | 模型 | 职责 | 工作语言 |
-|---|---|---|---|---|
-| dr-plan | primary | Opus 4.7 | Phase 1 框架规划（访谈、标题提议、生成双语 framework） | 中文对话 + 英文框架内容 |
-| dr-pm | primary | Sonnet 4.6 | Phase 2 调度，批次间 context 压缩 | English |
-| dr-chief-editor | primary | Gemini 3.1 Pro Preview | **Phase 3 only**：只读审校，产出 critique.md | English |
-| **dr-editor-in-chief** | primary | **Opus 4.7** | **Phase 4 主导**：合并 final_en、写 Executive Summary/Abstract/Glossary、调度后续 | English |
-| dr-searcher | subagent | Haiku 4.5 | 轻量检索、信源发现 | English |
-| dr-analyst | subagent | Sonnet 4.6 | 章节深研（英文草稿 + 证据矩阵） | English |
-| dr-verifier | subagent | GPT-5.4 | 交叉模型反方验证（唯一非 Claude 位置） | English |
-| **dr-translator** | subagent | **Sonnet 4.6** | Phase 4 英译中，维护双语术语表 | 英→中 |
-| dr-polisher | subagent | Sonnet 4.6 | Phase 4 中文润色、humanizer-cn + output-hygiene | 中文 |
-| dr-reporter | subagent | Sonnet 4.6 | Phase 4 出稿（PDF+DOCX），**强制回填 citations** | 纯执行 |
+查看当前模型配置：
 
-**关键角色变化（v0.5）**：
-- dr-chief-editor 从"Phase 3/4 总编"收窄为"Phase 3 only 只读审校"
-- 新增 dr-editor-in-chief（Opus）接管 Phase 4 主导权（避免 Gemini 导致的风格断裂）
-- 新增 dr-translator 专职英译中（工作流改为英文工作 + 最后翻译）
+```bash
+uv run python scripts/dr.py models --profile medium
+uv run python scripts/dr.py models --profile medium --json
+uv run python scripts/dr.py methods list
+```
 
----
+核心任务类型：
 
-## 6. 模型 Slug 映射表（已确认，基于 zenmux `/api/v1/models` 实时返回，2026-04-20）
+| Task type | 默认角色 | 用途 |
+|---|---|---|
+| `source_discovery` | `dr_searcher` | 轻量信源发现 |
+| `evidence_packet` | `dr_analyst` | task card → evidence packet |
+| `chapter_assembly` | `dr_analyst` | chapter brief → 中文章节 |
+| `counter_verification` | `dr_verifier` | 反方证据与交叉模型验证 |
+| `phase3_review` | `dr_chief_editor` | 总编审校 |
+| `final_editorial` | `dr_editor_in_chief` | 中文终稿统稿 |
+| `report_render` | `dr_reporter` | PDF/DOCX 渲染 |
 
-> 任何时候要查真实可用列表：
-> ```bash
-> curl -sS "https://zenmux.ai/api/v1/models" -H "Authorization: Bearer $ZENMUX_API_KEY" | jq '.data[].id'
-> ```
+默认策略：
 
-### 6.1 Provider 架构
+- Codex/GPT 系列适合代码、schema、回归、review。
+- Claude/Opus/Sonnet 适合长文结构、中文表达、访谈增强。
+- Gemini 适合长上下文审校、多模态材料、替代框架评估。
+- ZenMux 混合模型仍由 `configs/models.yaml` 统一管理，平台当前会话模型不得覆盖 Python role/task 映射。
 
-OpenCode 的自定义 provider `npm` 字段**只支持 `@ai-sdk/openai-compatible`**，不支持 `@ai-sdk/anthropic`。因此所有模型统一走 `zenmux` 的 OpenAI 兼容端点（`https://zenmux.ai/api/v1`），slug 带 vendor 前缀。
+## 6. Platform Adapter 调用方式
 
-zenmux 的 OpenAI 兼容端点同样支持 `cache_control` 透传，由 zenmux 后端处理，cache 行为与官方 Anthropic API 一致。
+详见 `docs/platform-adapters.md`。摘要如下：
 
-### 6.2 Claude 系列（走 `zenmux`，slug 带 `anthropic/` 前缀）
+| Platform | 项目指令/命令位置 | 推荐调用 |
+|---|---|---|
+| OpenCode | `.opencode/commands/*.md` | `/dr-run <slug-or-topic>` |
+| Codex | `AGENTS.md` + `$CODEX_HOME` adapter（由 `scripts/deploy_adapters.py codex` 部署） | `uv run python scripts/dr.py ...` 或 `codex exec "$(uv run python scripts/dr.py prompt dr-run '<topic>')"` |
+| Claude Code | `.claude/skills/*/SKILL.md` | `/dr-run <slug-or-topic>` |
+| Gemini CLI | `GEMINI.md` + `.gemini/commands/dr/*.toml` | `/dr:run <slug-or-topic>` |
+| Antigravity | 打开仓库后由 Agent Manager 运行终端命令 | 要求 agent 运行 `uv run python scripts/dr.py ...` |
 
-| 角色 | 模型 | 完整 model 字段 | 上下文 |
-|---|---|---|---|
-| dr-plan | Claude Opus 4.7 | `zenmux-anthropic/claude-opus-4-7` | **1M** |
-| dr-pm | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | **1M** |
-| dr-analyst | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | 1M |
-| dr-polisher | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | 1M |
-| dr-reporter | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | 1M |
-| dr-searcher | Claude Haiku 4.5 | `zenmux-anthropic/claude-haiku-4-5` | 200K |
+跨平台硬规则：
 
-备用：Opus 4-7 → 4-6；Sonnet 4-6 → 4-5
-
-**注意**：zenmux Anthropic 端点模型名用连字符（`4-7`），不用点（`4.7`）。baseURL 为 `https://zenmux.ai/api/anthropic/v1`。
-
-### 6.3 非 Claude 系列（同样走 `zenmux`）
-
-| 角色 | 模型 | 完整 model 字段 | 上下文 | 备注 |
-|---|---|---|---|---|
-| dr-chief-editor | **Gemini 3.1 Pro Preview** | `zenmux/google/gemini-3.1-pro-preview` | 1M | 总编终审首选 |
-| dr-chief-editor（备用） | Gemini 2.5 Pro | `zenmux/google/gemini-2.5-pro` | 1M | |
-| dr-verifier（首选） | **GPT-5.4** | `zenmux/openai/gpt-5.4` | 1.05M | 交叉模型（非 Claude） |
-| dr-verifier（备用 A） | Qwen3.6 Plus | `zenmux/qwen/qwen3.6-plus` | 1M | 中文研究强 |
-| dr-verifier（备用 B） | MiniMax M2.7 | `zenmux/minimax/minimax-m2.7` | 204K | 低成本交叉 |
-| dr-verifier（备用 C） | Kimi K2.5 | `zenmux/moonshotai/kimi-k2.5` | 262K | 长上下文交叉 |
-| 可选（低成本推理） | DeepSeek V3.2 Thinking | `zenmux/deepseek/deepseek-reasoner` | 128K | 极低成本 |
-| 可选（国产强模型） | GLM 5.1 | `zenmux/z-ai/glm-5.1` | 200K | |
-
-### 6.4 Prompt Cache 使用要点（Claude 必读）
-
-ZenMux 的 Anthropic 端点完整支持 4 种 cache 模式：
-1. **系统提示缓存**（最常见）：在 system 的最后一段加 `cache_control: {"type": "ephemeral"}` 断点
-2. **工具定义缓存**：在 tools 数组最后一个工具上加断点，所有工具一起缓存
-3. **对话历史缓存**：在每轮最后一条消息加断点，自动找最长前缀匹配
-4. **多断点组合**：最多 4 个断点，用于工具/系统/RAG/对话分别缓存
-
-**最低 token 要求**：
-- Opus 4.x / Sonnet 4.x：≥ 1024 tokens 才会建缓存
-- Haiku 4.5：≥ 2048 tokens
-
-**TTL**：默认 5 分钟；可指定 `"ttl": "1h"` 延长到 1 小时（写入成本 2×，读取便宜 10%）。
-
-**OpenCode 行为**：`@ai-sdk/anthropic` 包会自动对长 system prompt / 工具定义打 cache_control 断点，**你不需要手动加参数**。验证方法：在 zenmux 后台 Logs 里看 `cache_creation_input_tokens` 和 `cache_read_input_tokens` 字段。
-
-**Opus 4.7 定价参考**（截至 2026-04-20）：
-- 输入：25 USD/M tokens
-- cache 写入（5min）：6.25 USD/M
-- cache 写入（1h）：10 USD/M
-- **cache 读取**：**0.5 USD/M**（只有原价 2%！）
-
-所以只要 cache 命中，成本可压到无 cache 的 5-10% 量级。
-
-### 6.5 如何验证 cache 生效
-
-1. 在 zenmux 后台 https://zenmux.ai/settings/logs 开启 **API Call Logging** 开关
-2. 启动 opencode，跑 `/dr-frame` 让 dr-plan 连续两次调用
-3. 第一次调用 Logs 应显示 `cache_creation_input_tokens > 0`
-4. 第二次调用（5 分钟内）应显示 `cache_read_input_tokens > 0`，费用大幅下降
-5. 如果 cache 字段始终为 0，说明没走 Anthropic 端点，回查 agent 的 `model:` 字段是否正确用了 `zenmux-anthropic/` 前缀
-6. 本项目提供 `scripts/verify-zenmux.sh` 一键自检
-
-### 6.6 模型白名单位置
-
-所有可用模型已列入 `.opencode/opencode.json` 的 `provider.zenmux.models` 和 `provider.zenmux-anthropic.models`。增删模型时**两处都要更新**：
-- opencode.json 决定 `/models` 下拉列表
-- AGENTS.md 本节决定角色→模型的分配逻辑
-
-### 6.7 模型升级流程
-
-zenmux 新模型上线后，更新顺序：
-1. `curl zenmux /api/v1/models` 确认 slug
-2. 更新 `.opencode/opencode.json` 的 models 段
-3. 更新 AGENTS.md §6.2 / §6.3 角色映射表
-4. 更新 `.opencode/agents/*.md` 的 `model:` 字段
-5. 运行 `bash scripts/verify-zenmux.sh` 验证
-6. 更新 PLAN.md §12 变更记录
+- 平台只做 surface adapter，不承载核心调度。
+- 不在平台 prompt 中手工并发写章节。
+- 不把平台 subagent 当默认并发机制。
+- 真实并发由 `scripts/runtime/workers.py` 的 worker pool 执行。
+- 真实模型选择由 `configs/models.yaml` 和 `scripts/runtime/roles.py` 执行。
 
 ---
 
@@ -264,18 +209,16 @@ zenmux 新模型上线后，更新顺序：
 
 ---
 
-## 9. 如何判断 subagent 是否真正被独立调度（验证锚点）
+## 9. 如何判断是否走了 Python Core
 
-用户提到过"多 agent 实际上是主模型跑到底"的坑。验证方法：
+不要用“平台是否 spawn subagent”作为成功标准。v0.20 的验证锚点是 Python runtime 产物：
 
-1. **TUI 内**：`<Leader>+Right` 能切入独立子会话，若没有说明没真正调度
-2. **日志**：`opencode --print-logs` 会显示每次 Task 工具调用，附带 agent 名和模型 ID
-3. **token 使用**：`/stats` 里可以看到按 agent 分的 token 消耗，Haiku 应远多于 Opus
-
-如果发现某个 agent 没有真正被调度，检查：
-- 命令 frontmatter 是否有 `subtask: true`
-- 主 agent 的 `permission.task` 是否允许目标 subagent
-- 目标 subagent 的 `mode` 是否是 `subagent`
+1. `uv run python scripts/dr.py status <slug>` 能看到 phase 状态。
+2. Phase 2 存在 `phase2/task_cards.json`。
+3. `--execute-packets` 后存在 `phase2/packets/*.json` 和必要时的 `phase2/packet_errors/*.json`。
+4. `--build-briefs` 后存在 `phase2/chapter_briefs/*.json`。
+5. `--assemble-chapters` 后存在 `phase2/drafts/chXX.md` 和必要时的 `phase2/chapter_errors/*.json`。
+6. `scripts/v020_regression.py` 输出 `v0.20 regression PASS`。
 
 ---