# 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-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`

---

## 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 角色与职责（v0.5 重构）

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

| 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 专职英译中（工作流改为英文工作 + 最后翻译）

---

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

> 任何时候要查真实可用列表：
> ```bash
> 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 清单中标记完成状态