# Deep Research 系统方案（OpenCode 实现） > 本文件是整套方案的**单一真实源**，中断后续接时从此文件恢复上下文。 > 最后更新：2026-04-20 > 实施阶段：路径 2 — 最小可用先行（MVP） --- ## 0. 背景与目标 ### 0.1 用户画像 - 主业：生物医药行业的研发、工艺、管理、投资研究（非 coding） - 痛点：此前在 OpenClaw / Hermes 做 Deep Research 时 token 消耗大但效果差 - 预期：以麦肯锡、德勤等顶尖机构的方法论输出专业报告 ### 0.2 质量标准（硬性） - **字数**：综述类 ≥ 10,000 字；研究类 ≥ 30,000 字 - **证据**：每条结论至少 2 个独立 Tier 1-2 信源佐证，否则标注"观点待验证" - **结构**：8-15 章，每章下分 section / sub-section；每个标题即一个观点 - **信源**：优先论文、专利、权威研究报告；排除劣质纯新闻、自媒体 - **交付**：PDF（ReportLab）+ DOCX（Pandoc），格式专业、中文排版规范 --- ## 1. 关键决策（已与用户确认） | 维度 | 决策 | |---|---| | LLM 接入 | **zenmux 中转**（多模型混合） | | 项目位置 | **仅项目级** `.opencode/`，项目根目录为 `deep_research/` | | 搜索 API | **Tavily / Brave / Exa 走 MCP Server**；生物医药专业信源走 skill+bash | | PDF 方案 | **ReportLab**（中文字体一次注册，样式集中 StyleSheet） | | DOCX 方案 | **Pandoc + reference-doc** | | 字数落实 | 框架阶段分配配额 + 终稿校验双保险 | | 交互节奏 | Phase 1 末、Phase 3 末强制确认 | | 并发 subagent | 3-4 个（稳，避免 API 限流） | | 中文字体 | **思源宋体 + 思源黑体 + 霞鹜文楷**，通过 `download-fonts.sh` 自动拉取 | --- ## 2. 模型分配（zenmux 双 provider 架构） 详细 slug、cache 机制、升级流程见 `AGENTS.md` §6。关键要点： - **Claude 系列走 `zenmux-anthropic/...`（无 `anthropic/` 前缀的裸 slug）**，以便 prompt cache 原生生效 - 其他模型走 `zenmux//`，隐式缓存自动生效 - 真实可用模型清单通过 `curl zenmux /api/v1/models` 随时查询；不要依赖 zenmux 文档里的过期示例 | 角色 | 模型 | 完整 model 字段 | 上下文 | 温度 | top_p | |---|---|---|---|---|---| | dr-plan（框架规划） | Claude Opus 4.7 | `zenmux-anthropic/claude-opus-4.7` | 1M | **0.7** | **0.9** | | dr-pm（项目经理/调度） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.2 | 默认 | | dr-chief-editor（总编/终审） | Gemini 3.1 Pro Preview | `zenmux/google/gemini-3.1-pro-preview` | 1M | 0.3 | 默认 | | dr-searcher（轻量检索） | Claude Haiku 4.5 | `zenmux-anthropic/claude-haiku-4.5` | 200K | 0.1 | 默认 | | dr-analyst（章节深研） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.3 | 默认 | | dr-verifier（反方验证） | GPT-5.4 Pro（首选）/ Qwen3.6-Plus / MiniMax M2.7 | `zenmux/openai/gpt-5.4-pro` 等 | 1.05M | 0.2 | 默认 | | dr-polisher（去AI味+润色） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.4 | 默认 | | dr-reporter（出稿） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.1 | 默认 | **Cache 行为**：Claude 走 `@ai-sdk/anthropic` 会自动打 `cache_control` 断点，zenmux 的 Anthropic 端点完整支持 4 种 cache 模式。Opus 4.7 cache read 价格仅 0.5 USD/M tokens（对比输入价 25 USD/M，节省 98%）。验证方法见 `AGENTS.md` §6.5。 --- ## 3. 完整架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 用户 (TUI 入口) │ └─────────────────────┬───────────────────────────────────────────┘ │ Tab 切换主 agent ┌───────────┼────────────┐ ▼ ▼ ▼ ┌───────┐ ┌───────┐ ┌──────────┐ │ dr- │ │ dr- │ │ dr-chief │ (Primary) │ plan │ │ pm │ │ -editor │ │ (Opus)│ │(Sonnet)│ │ (Gemini) │ └───┬───┘ └───┬────┘ └─────┬────┘ │ │ Task 工具委派│ │ ▼ │ │ ┌─────────────┐ │ │ │ Subagents │ │ (并行 3-4 个) │ ├─────────────┤ │ │ │ dr-searcher │ │ Haiku 轻检索 │ │ dr-analyst │ │ Sonnet 深研 │ │ dr-verifier │ │ GPT-5/Qwen 交叉 │ │ dr-polisher │ │ Sonnet 润色 │ │ dr-reporter │ │ Sonnet 出稿 │ └─────────────┘ │ │ │ 调用 Skills ───────────────────┘ 调用 MCP Servers ``` --- ## 4. 目录结构 ``` deep_research/ ├── PLAN.md # 本文件 — 方案真实源 ├── AGENTS.md # 研究方法论与规则（OpenCode 自动读） ├── README.md # 使用指南 ├── .gitignore ├── secrets.env.example # 密钥模板 ├── secrets.env # 实际密钥（不入 git） │ ├── .opencode/ │ ├── opencode.json # MCP + 权限 + 默认模型 │ ├── agents/ │ │ ├── dr-plan.md # [MVP] Primary：框架规划 Opus temp 0.7 │ │ ├── dr-pm.md # [MVP] Primary：PM/调度 Sonnet temp 0.2 │ │ ├── dr-chief-editor.md # [待补] Primary：总编 Gemini │ │ ├── dr-searcher.md # [待补] Subagent：轻检索 Haiku │ │ ├── dr-analyst.md # [待补] Subagent：深研 Sonnet │ │ ├── dr-verifier.md # [待补] Subagent：交叉验证 GPT-5/Qwen │ │ ├── dr-polisher.md # [待补] Subagent：润色 Sonnet │ │ └── dr-reporter.md # [待补] Subagent：出稿 Sonnet │ ├── skills/ │ │ ├── search-strategy/SKILL.md # [MVP] 检索策略总纲 │ │ ├── source-quality/SKILL.md # [MVP] 信源评级与黑名单 │ │ ├── length-budget/SKILL.md # [MVP] 字数预算 │ │ ├── pdf-reportlab/SKILL.md # [MVP] ReportLab 中文模板 │ │ ├── biomed-pubmed/SKILL.md # [待补] │ │ ├── biomed-clinicaltrials/SKILL.md # [待补] │ │ ├── biomed-openfda/SKILL.md # [待补] │ │ ├── biomed-patents/SKILL.md # [待补] │ │ ├── biomed-finance/SKILL.md # [待补] │ │ ├── docx-pandoc/SKILL.md # [待补] │ │ ├── citation-manager/SKILL.md # [待补] │ │ ├── evidence-table/SKILL.md # [待补] │ │ ├── mckinsey-method/SKILL.md # [待补] │ │ └── report-template/SKILL.md # [待补] │ ├── commands/ │ │ ├── dr-init.md # [MVP] /dr-init │ │ ├── dr-frame.md # [MVP] /dr-frame │ │ ├── dr-research.md # [待补] /dr-research │ │ ├── dr-review.md # [待补] /dr-review │ │ ├── dr-finalize.md # [待补] /dr-finalize │ │ └── dr-status.md # [待补] /dr-status │ └── templates/ │ ├── report-template.py # [MVP] ReportLab PDF 模板 │ ├── report-template.docx # [待补] Pandoc reference-doc │ ├── report-template.md # [待补] Markdown 骨架 │ └── fonts/ │ ├── download-fonts.sh # [MVP] 字体自动下载 │ ├── README.md # 字体来源说明 │ ├── SourceHanSerifSC-Regular.otf (git 忽略) │ ├── SourceHanSerifSC-Bold.otf (git 忽略) │ ├── SourceHanSansSC-Light.otf (git 忽略) │ ├── SourceHanSansSC-Medium.otf (git 忽略) │ ├── SourceHanSansSC-Bold.otf (git 忽略) │ ├── SourceHanSansSC-Heavy.otf (git 忽略) │ └── LXGWWenKai-Regular.ttf (git 忽略) │ ├── projects/ # 每个研究主题一个子目录 │ └── / │ ├── manifest.json # 元信息 │ ├── phase1/ │ │ ├── initial-scan.md │ │ ├── framework.md │ │ └── interview.md │ ├── phase2/ │ │ ├── evidence/ │ │ ├── sources.jsonl │ │ └── drafts/ │ ├── phase3/ │ │ ├── critique.md │ │ └── revisions/ │ └── phase4/ │ ├── final.md │ ├── final.pdf │ ├── final.docx │ └── citations.bib │ └── archive/ # 历史研究归档 ``` --- ## 5. 字体方案（方案 A：思源 + 霞鹜文楷） | 用途 | 字体 | 字号 | 行高 | |---|---|---|---| | 正文 | 思源宋体 Regular | 10.5pt | 16pt | | 正文粗体/术语 | 思源宋体 Bold | 10.5pt | 16pt | | 一级标题（章） | 思源黑体 Bold | 18pt | 28pt | | 二级标题（section） | 思源黑体 Bold | 14pt | 22pt | | 三级标题（subsection） | 思源黑体 Medium | 12pt | 18pt | | 摘要/引文/批注 | 霞鹜文楷 Regular | 10.5pt | 16pt | | 图表标题 | 思源黑体 Medium | 9pt | 13pt | | 脚注/参考文献 | 思源宋体 Regular | 9pt | 13pt | | 页眉页脚 | 思源黑体 Light | 8pt | 12pt | | 封面主标题 | 思源黑体 Heavy | 32pt | 42pt | 所有字体均为 **SIL OFL** 许可，可自由商用、嵌入 PDF 分发。 **字体下载来源（download-fonts.sh）**： - 思源宋体：`https://github.com/adobe-fonts/source-han-serif/releases` - 思源黑体：`https://github.com/adobe-fonts/source-han-sans/releases` - 霞鹜文楷：`https://github.com/lxgw/LxgwWenKai/releases` --- ## 6. 工作流（四阶段） ### Phase 1：框架规划（dr-plan 主导） 1. `/dr-init ` 创建项目目录 + manifest.json，进行初轮对话访谈 2. `/dr-frame` 触发： - dr-plan 用 `skill:search-strategy` 指挥 3 个 dr-searcher 并行初扫 - 生成 8-15 章大纲 + 每章研究思路 + 字数配额（依据 `skill:length-budget`） - **【停】等用户确认** — 可迭代 ### Phase 2：深度研究（dr-pm 主导） 1. `/dr-research` 触发： - dr-pm 按章节分批并行调度 dr-analyst - 每章完成后自动调度 dr-verifier 做反方验证 - 每条结论自动填入 `evidence/chXX-evidence.md` 的"观点-证据-来源-置信度"表 - `skill:length-budget` 自检，不足则继续挖掘 ### Phase 3：总编审校（dr-chief-editor 主导） 1. `/dr-review` 触发： - Gemini 3.1 Pro 通读全部 drafts - 产出 `critique.md`：逻辑漏洞、证据不足、观点雷同、金字塔违反 - **【停】等用户决策**： - a) 直接修正 → 进入 finalize - b) 特定章节回炉 phase2 - c) 整体重来 → 回 phase1 ### Phase 4：成稿（dr-chief-editor 调度） 1. `/dr-finalize` 触发： - dr-polisher 去 AI 味、中文表达、术语统一 - dr-reporter 执行： - `python .opencode/templates/report-template.py final.md → final.pdf` - `pandoc final.md --reference-doc=... → final.docx` --- ## 7. 如何避免"多 agent 实际是一个主模型跑到底" OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"，实际还是主模型在跑，token 花了但没分工。 **三道保险**： 1. **命令级强制**：所有命令 frontmatter 设 `subtask: true`，强制走 Task 工具，真起子会话 2. **Agent 强绑模型**：每个 subagent 的 `model` 字段写死到具体模型，OpenCode 会真正起独立会话用那个模型 3. **任务权限白名单**：dr-pm 的 `permission.task` 精确限定只能调用 subagent，不能跨级调度 4. **可验证**：TUI 里 `+Right` 切入子会话，能看到真实在跑的模型名 --- ## 8. 完整实施清单（v0.4 全部完成） ### 基础设施 - [x] 目录结构 - [x] PLAN.md / AGENTS.md / README.md / .gitignore - [x] .opencode/opencode.json（双 provider + MCP + 权限） - [x] secrets.env.example - [x] scripts/setup.sh / activate.sh / verify-zenmux.sh - [x] requirements.txt / pyproject.toml（uv） ### Agents（8 个） - [x] dr-plan（Opus 4-7，temp 0.7） - [x] dr-pm（Sonnet 4-6，temp 0.2） - [x] dr-searcher（Haiku 4-5，temp 0.1） - [x] dr-analyst（Sonnet 4-6，temp 0.3） - [x] dr-verifier（GPT-5.4-pro，temp 0.2） - [x] dr-chief-editor（Gemini 3.1 Pro Preview，temp 0.3） - [x] dr-polisher（Sonnet 4-6，temp 0.4） - [x] dr-reporter（Sonnet 4-6，temp 0.1） ### Commands（6 个） - [x] /dr-init - [x] /dr-frame - [x] /dr-research - [x] /dr-review - [x] /dr-finalize - [x] /dr-status ### Skills（7 个） - [x] search-strategy - [x] source-quality - [x] length-budget - [x] pdf-reportlab - [x] evidence-table - [x] citation-manager - [x] mckinsey-method ### 报告模板 - [x] report-template.py（ReportLab PDF） - [x] fonts/download-fonts.sh ### 待补（后续优化） - [ ] docx-pandoc skill（Pandoc reference-doc 模板） - [ ] 生物医药专业信源 skill（PubMed / ClinicalTrials / openFDA / 专利 / 金融） - [ ] dr-reporter 的 DOCX 样式优化 --- ## 9. 后续路径 ### 优化项（实施阶段 5） ### 优化项（实施阶段 4） - 把稳定的 bash skill 封装成 MCP server - 引入 Exa /neural search 提升专业文献召回 - 支持图表自动生成（matplotlib 模板库） --- ## 10. 用户待办 1. [x] ~~模型 slug 映射~~（v0.3 已完成，基于 zenmux `/api/v1/models` 实时数据） 2. [ ] 准备 API keys（`secrets.env` 填写）： - ZENMUX_API_KEY（必填，格式 `sk-ai-v1-xxx`） - TAVILY_API_KEY / EXA_API_KEY / BRAVE_API_KEY - NCBI_API_KEY（可选，高频查 PubMed 时需要） 3. [ ] 环境初始化（跨 macOS/Debian，用 uv）： ```bash bash scripts/setup.sh ``` 会自动：装 uv（如缺失）→ `uv sync` 建 `.venv/` + 装依赖 → 检查系统二进制。 4. [ ] 系统二进制（setup.sh 会检测但不自动装）： - `pandoc`（DOCX 出稿阶段必须） - `opencode`（TUI 主程序） 5. [ ] 首次使用前： ```bash source scripts/activate.sh # 激活 venv + 载入 secrets bash .opencode/templates/fonts/download-fonts.sh # 下载字体 bash scripts/verify-zenmux.sh # 验证端点与 cache ``` 6. [ ] 用一个小主题跑通 MVP 流水线，验证： - subagent 是否真正被独立调度（TUI 可见子会话） - 字数配额是否正确落到 framework.md - 信源过滤是否生效（Tier 4 不会进 sources.jsonl） - zenmux 后台 Logs 能看到 `cache_read_input_tokens > 0` --- ## 11. 风险与缓解 | 风险 | 缓解 | |---|---| | zenmux 模型 slug 命名变动 | AGENTS.md §6 单点维护映射表，全部 agent 引用此表 | | Claude prompt cache 未生效 → 成本暴涨 | Claude 系列强制走 `zenmux-anthropic`（`@ai-sdk/anthropic` 通道），zenmux 后台 Logs 验证 `cache_creation_input_tokens` 字段 | | MCP server 首次启动慢 | 用 `opencode serve` 常驻；subagent 设合理 timeout | | 搜索 API 限流 | search-strategy 里规定每批 ≤3 个 searcher；失败重试 3 次带退避 | | Opus 成本高 | dr-plan 用 steps 限制迭代次数（见 length-budget） | | ReportLab 中文渲染慢 | matplotlib 预渲染 PNG，StyleSheet 缓存 | | 中断恢复 | 所有状态写 manifest.json + phase 文件，本 PLAN.md 是元控制文件 | --- ## 12. 变更记录 - 2026-04-20 v0.1：初版方案确定，MVP 路径 2 开始实施 - 2026-04-20 v0.2：**双 provider 架构**上线，解决 zenmux Claude prompt cache 问题 - 新增 `zenmux-anthropic` 自定义 provider（`@ai-sdk/anthropic` + `https://zenmux.ai/api/anthropic`） - Claude 系列迁移到裸 slug - 非 Claude 系列保留 `zenmux//` 走 OpenAI 兼容端点 - AGENTS.md §6 重写：cache 机制、验证锚点、最低 token、升级流程 - 2026-04-20 v0.3：**修正 v0.2 错误 + 切换到 uv** - **模型修正**：v0.2 用了 zenmux 文档里过期的模型列表（被用户指正），重新通过 `curl zenmux /api/v1/models` 拉真实清单 - Claude 恢复实际最新版：Opus **4.7** / Sonnet **4.6** / Haiku 4.5（Opus/Sonnet 都是 1M 上下文） - dr-chief-editor 升级为 Gemini **3.1 Pro Preview**（1M） - dr-verifier 恢复 GPT-5.4 Pro（1.05M）/ Qwen 3.6 Plus / MiniMax M2.7 / Kimi K2.5 - 新增 AGENTS.md §6.7 "模型升级流程"，**原则：模型 slug 以 zenmux `/api/v1/models` 实时返回为准** - **Python 环境切换到 uv**（v0.2 是 pip+venv，跨平台体验差） - 新增 `pyproject.toml` 作为依赖真源 - `scripts/setup.sh` 改为调 `uv sync`（自动装 uv、装 Python、建 venv、装依赖） - `scripts/activate.sh` 激活时自动找 uv 路径 - `requirements.txt` 降级为备用清单（无 uv 的沙盒环境兜底） - 2026-04-20 v0.4：**全流程完成** - 修复 zenmux-anthropic baseURL 缺 `/v1` 导致返回 HTML 页面的问题 - 修复 Anthropic 端点模型名用点号（`4.7`）应改为连字符（`4-7`） - 新增全部 subagent：dr-searcher / dr-analyst / dr-verifier / dr-chief-editor / dr-polisher / dr-reporter - 新增 Phase 2-4 命令：/dr-research / /dr-review / /dr-finalize / /dr-status - 新增 skills：evidence-table / citation-manager / mckinsey-method - Phase 1 已成功跑通（O-糖苷酶立项报告测试主题）