kai/deep_research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a38f6bed12a8fe4409265bfce7460ad8f2dd3a9
deep_research/AGENTS.md
T
kai 4a38f6bed1 snapshot before v0.5 refactor
2026-04-21 12:31:58 +08:00

13 KiB
Raw Blame History

AGENTS.md — 生物医药 Deep Research 系统规则

本文件为 OpenCode 会自动读取的项目级指令文件。 所有 agent / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。

1. 项目使命

本项目通过多 agent 协作，以麦肯锡、德勤等顶尖机构的研究方法，对生物医药领域（研发、工艺、管理、投资）的指定主题进行深度研究，输出专业级报告（PDF + DOCX）。

本项目不涉及代码开发，所有"代码"都是为研究流水线服务（如 ReportLab 模板、下载脚本、信源 API 调用）。

2. 研究方法论（所有 agent 必须遵循）

2.1 麦肯锡核心原则

  1. MECE（Mutually Exclusive, Collectively Exhaustive）：章节划分互斥且穷尽
  2. SCQA 叙事（Situation → Complication → Question → Answer）：每章节开头用此结构引入
  3. 金字塔原理：结论先行，论据支撑，纵向深入，横向 MECE
  4. "每个标题即一个观点"：标题不能是"概述""现状"这类模糊词，必须包含判断
  5. So What? 自检：每写完一段问自己"所以呢？"，若无则删

2.2 证据铁律

  • 每条结论至少 2 个独立 Tier 1-2 信源佐证（见 §4 信源分级）
  • 达不到则必须在正文注明"该观点仅有 X 个来源支持，待进一步验证"
  • 反方证据优先：每个 chapter 的研究必须主动搜索证伪性论点，不能只找支持证据
  • 数据可追溯：所有数字、百分比、日期必须有来源 ID（如 [src_042]）

2.3 字数配额（硬要求）

报告类型 最小字数 建议章节数
综述类 10,000 字 8-10 章
研究类 30,000 字 10-12 章
投资报告 20,000 字 10-12 章
管理/工艺类 15,000-25,000 字 9-11 章

字数分配原则：

  • 每章字数差距不超过 ±30%（避免头重脚轻）
  • 每 section 最少 800 字（不够则合并）
  • 结论章不少于全文 10%

2.4 报告不能只谈结论

  • 每个观点后必须紧跟数据/事实/案例佐证
  • 禁止空洞形容词（"巨大""快速""显著"）不带数据
  • 趋势判断必须给量化依据（年复合增长率、市场规模、成功率等）

3. Phase 工作流（4 阶段）

Phase 1：框架规划

  • 驱动命令：/dr-init <topic> → /dr-frame
  • 主导 agent：dr-plan
  • 产出：projects/<slug>/phase1/framework.md（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
  • 不暂停：全自动跑完

Phase 3：总编审校

  • 驱动命令：/dr-review
  • 主导 agent：dr-chief-editor（Gemini 3.1 Pro 1M 上下文通读）
  • 产出：projects/<slug>/phase3/critique.md
  • 暂停点：用户决策（修正 / 回炉 phase2 / 整体重来）

Phase 4：成稿

  • 驱动命令：/dr-finalize
  • 主导 agent：dr-chief-editor → dr-polisher → dr-reporter
  • 产出：final.md + final.pdf（ReportLab）+ final.docx（Pandoc）

4. 信源分级（Tier 系统）

Tier 1 — 一级信源（优先使用，评分权重 × 1.2）

  • 一手学术文献：PubMed、Cochrane、顶刊原文（NEJM / Lancet / Nature / Science / Cell / JAMA）
  • 监管机构公告：FDA、EMA、NMPA、PMDA 官网及 openFDA
  • 临床试验注册：ClinicalTrials.gov、ChiCTR
  • 专利原文：USPTO、EPO、CNIPA、Google Patents
  • 上市公司披露：SEC 10-K/10-Q、招股书、交易所年报

Tier 2 — 二级信源（可用，标准权重）

  • 权威咨询报告：麦肯锡、BCG、德勤、IQVIA、EvaluatePharma、弗若斯特沙利文
  • 学术综述：系统综述（Systematic Review）、Meta 分析
  • 行业协会：PhRMA、BIO、中国医药工业协会
  • 专业数据库：Wind、东方财富、同花顺（金融侧）
  • 专业媒体：BioSpace、Endpoints News、FiercePharma、医药魔方、Insight 数据库

Tier 3 — 三级信源（辅助，不得作为唯一支撑）

  • 预印本：bioRxiv、medRxiv（需标注"未经同行评审"）
  • 券商研报：中金、中信、高盛生物医药团队（需注意利益冲突）
  • 会议摘要：AACR、ASCO、ASH 会议摘要（数据可能未完整发表）
  • 企业白皮书（注明来源，降权使用）

Tier 4 — 四级信源（仅做发现入口）

  • Tavily / Brave / Exa 通用搜索返回的普通网页
  • 一般新闻报道
  • Wikipedia（只做术语理解入口，结论不得引用）

黑名单（禁用）

  • 纯新闻聚合站（百家号、头条号、部分自媒体公众号）
  • 未署名作者的行业博客
  • 被 Retraction Watch 标记为撤稿的论文
  • 明显软文/PR 稿（如"某某 CEO 表示..."而无实质数据）
  • 超过 5 年的综述（除机制类研究可放宽）

信源评分（0-10）

每个进入 sources.jsonl 的信源必须打分，维度：

  • 权威性（期刊 IF、机构排名）0-3
  • 时效性（≤3 年满分，每老 1 年 -0.5） 0-2
  • 一手性（一手 > 综述 > 二次解读） 0-2
  • 可验证性（有 DOI / URL / 原始数据） 0-2
  • 利益冲突（厂商自发 -1） 0-1

硬规则：评分 < 5 的信源不得作为结论唯一支撑。

5. Agent 角色与职责

每个 agent 的详细定义见 .opencode/agents/*.md

Agent 类型 模型类别 职责
dr-plan primary Opus 框架规划、Phase 1/3 发散与复盘
dr-pm primary Sonnet Phase 2 调度与汇总
dr-chief-editor primary Gemini Pro Phase 3/4 总编终审
dr-searcher subagent Haiku 轻量检索、信源发现
dr-analyst subagent Sonnet 章节深度研究
dr-verifier subagent GPT-5 / Qwen 交叉模型反方验证
dr-polisher subagent Sonnet 去 AI 味、中文润色
dr-reporter subagent Sonnet PDF / DOCX 出稿

6. 模型 Slug 映射表（已确认，基于 zenmux /api/v1/models 实时返回，2026-04-20）

任何时候要查真实可用列表：

curl -sS "https://zenmux.ai/api/v1/models" -H "Authorization: Bearer $ZENMUX_API_KEY" | jq '.data[].id'

6.1 Provider 架构

OpenCode 的自定义 provider npm 字段只支持 @ai-sdk/openai-compatible，不支持 @ai-sdk/anthropic。因此所有模型统一走 zenmux 的 OpenAI 兼容端点（https://zenmux.ai/api/v1），slug 带 vendor 前缀。

zenmux 的 OpenAI 兼容端点同样支持 cache_control 透传，由 zenmux 后端处理，cache 行为与官方 Anthropic API 一致。

6.2 Claude 系列（走 zenmux，slug 带 anthropic/ 前缀）

角色 模型 完整 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 变更记录

7. 目录约定

  • 每个研究主题放在 projects/<topic-slug>/，slug 用小写+连字符，如 glp1-r-agonist-market-2026
  • 所有中间产物（drafts、evidence、sources.jsonl）均为 Markdown 或 JSONL，便于 diff 与版本控制
  • archive/ 存放已完成或废弃的研究，不再主动维护

8. 安全与权限

  • API 密钥只存 secrets.env（已入 gitignore），禁止硬编码到任何 agent/skill/command
  • 字体文件（~140MB）不入 git，通过 download-fonts.sh 获取
  • bash 权限默认 ask，仅允许 python * / pandoc * / ls * / cat * / curl * 自动执行

9. 如何判断 subagent 是否真正被独立调度（验证锚点）

用户提到过"多 agent 实际上是主模型跑到底"的坑。验证方法：

  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

10. 禁止事项（negative instructions）

所有 agent 均禁止：

  1. ❌ 引用 Wikipedia 作为结论支撑（仅做术语理解）
  2. ❌ 在缺乏 2 个独立信源时仍给出绝对化结论
  3. ❌ 使用"据报道""有专家认为"等未指明来源的表述
  4. ❌ 编造或虚构数据、URL、DOI
  5. ❌ 写空洞的套话（"随着科技的发展""在大数据时代"）
  6. ❌ 忽略反方观点，只收集支持证据
  7. ❌ 对输出字数"打折"（综述 <10000 字、研究 <30000 字必须返工）
  8. ❌ 在正文中使用未在术语表中定义的专业缩写（首次出现需全称+缩写）

11. 变更管理

  • 本文件与 PLAN.md 是双核：PLAN.md 管实施进度与架构，AGENTS.md 管运行时规则
  • 修改本文件需同步更新 PLAN.md 的"变更记录"段
  • 所有 agent/skill 新增或重大调整必须在 PLAN.md §8 清单中标记完成状态
Reference in New Issue View Git Blame Copy Permalink