kai/deep_research

Fork 0

Files

T

kai 4a38f6bed1 snapshot before v0.5 refactor

2026-04-21 12:31:58 +08:00

18 KiB

Raw Blame History

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/<vendor>/<slug>，隐式缓存自动生效
真实可用模型清单通过 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 <topic>
│   │   ├── 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/                          # 每个研究主题一个子目录
│   └── <topic-slug>/
│       ├── 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 主导）

/dr-init <topic> 创建项目目录 + manifest.json，进行初轮对话访谈
/dr-frame 触发：
- dr-plan 用 skill:search-strategy 指挥 3 个 dr-searcher 并行初扫
- 生成 8-15 章大纲 + 每章研究思路 + 字数配额（依据 skill:length-budget）
- 【停】等用户确认 — 可迭代

Phase 2：深度研究（dr-pm 主导）

/dr-research 触发：
- dr-pm 按章节分批并行调度 dr-analyst
- 每章完成后自动调度 dr-verifier 做反方验证
- 每条结论自动填入 evidence/chXX-evidence.md 的"观点-证据-来源-置信度"表
- skill:length-budget 自检，不足则继续挖掘

Phase 3：总编审校（dr-chief-editor 主导）

/dr-review 触发：
- Gemini 3.1 Pro 通读全部 drafts
- 产出 critique.md：逻辑漏洞、证据不足、观点雷同、金字塔违反
- 【停】等用户决策：
  - a) 直接修正 → 进入 finalize
  - b) 特定章节回炉 phase2
  - c) 整体重来 → 回 phase1

Phase 4：成稿（dr-chief-editor 调度）

/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 花了但没分工。

三道保险：

命令级强制：所有命令 frontmatter 设 subtask: true，强制走 Task 工具，真起子会话
Agent 强绑模型：每个 subagent 的 model 字段写死到具体模型，OpenCode 会真正起独立会话用那个模型
任务权限白名单：dr-pm 的 permission.task 精确限定只能调用 subagent，不能跨级调度
可验证：TUI 里 <Leader>+Right 切入子会话，能看到真实在跑的模型名

8. 完整实施清单（v0.4 全部完成）

基础设施

目录结构
PLAN.md / AGENTS.md / README.md / .gitignore
.opencode/opencode.json（双 provider + MCP + 权限）
secrets.env.example
scripts/setup.sh / activate.sh / verify-zenmux.sh
requirements.txt / pyproject.toml（uv）

Agents（8 个）

dr-plan（Opus 4-7，temp 0.7）
dr-pm（Sonnet 4-6，temp 0.2）
dr-searcher（Haiku 4-5，temp 0.1）
dr-analyst（Sonnet 4-6，temp 0.3）
dr-verifier（GPT-5.4-pro，temp 0.2）
dr-chief-editor（Gemini 3.1 Pro Preview，temp 0.3）
dr-polisher（Sonnet 4-6，temp 0.4）
dr-reporter（Sonnet 4-6，temp 0.1）

Commands（6 个）

/dr-init
/dr-frame
/dr-research
/dr-review
/dr-finalize
/dr-status

Skills（7 个）

search-strategy
source-quality
length-budget
pdf-reportlab
evidence-table
citation-manager
mckinsey-method

报告模板

report-template.py（ReportLab PDF）
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. 用户待办

~~模型 slug 映射~~（v0.3 已完成，基于 zenmux /api/v1/models 实时数据）
准备 API keys（secrets.env 填写）：
- ZENMUX_API_KEY（必填，格式 sk-ai-v1-xxx）
- TAVILY_API_KEY / EXA_API_KEY / BRAVE_API_KEY
- NCBI_API_KEY（可选，高频查 PubMed 时需要）
环境初始化（跨 macOS/Debian，用 uv）：
```
bash scripts/setup.sh
```
会自动：装 uv（如缺失）→ uv sync 建 .venv/ + 装依赖 → 检查系统二进制。
系统二进制（setup.sh 会检测但不自动装）：
- pandoc（DOCX 出稿阶段必须）
- opencode（TUI 主程序）

首次使用前：

source scripts/activate.sh                           # 激活 venv + 载入 secrets
bash .opencode/templates/fonts/download-fonts.sh     # 下载字体
bash scripts/verify-zenmux.sh                        # 验证端点与 cache

用一个小主题跑通 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/<vendor>/<slug> 走 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-糖苷酶立项报告测试主题）

18 KiB Raw Blame History Unescape Escape