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

> 本文件为跨平台项目级指令文件。Codex、OpenCode、Claude Code、Antigravity、Gemini CLI 均应以本文件为运行规则。
> 所有平台 adapter / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。

---

## 1. 项目使命

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

本项目**不涉及业务代码开发**，所有"代码"都是为**研究流水线**服务（如 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 与来源笔记中。

---

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

### 2.1 麦肯锡核心原则

1. **研究方法适配场景**：MECE 是常用方法之一，但 GMP/CMC/管理咨询/研发立项等场景必须选择匹配框架
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：框架规划
- **驱动命令**：`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 可作为表层访谈增强
- **产出**：`phase1/material_brief.md` + `phase1/framework.md` + `phase1/research_brief.md/json`
- **暂停点**：用户确认材料解读、研究方法、任务切分、检索策略和章节框架
- **硬规则**：clarification 不只是问范围；必须固化报告用途、基调、成功标准、任务拆分、每个任务轴的 prompt/skills/search route，让低成本 worker 也能独立执行

### Phase 2：深度研究
- **驱动命令**：`uv run python scripts/dr.py research <slug> --workers 6`
- **主导入口**：Python core 生成 task cards 并控制并发
- **产出**：`phase2/task_cards.json` + `packets/*.json` + `sources.jsonl` + `chapter_briefs/*.json` + `compressed_findings/*.json` + `drafts/chXX.md`
- **不暂停**：全自动跑完
- **防碎片化规则**：并发 worker 只写 evidence packet；`--build-briefs` 必须先收束为 chapter brief 和 compressed finding；章节正文必须从 compressed finding 写，不得把 packet 按顺序拼贴成报告

### Phase 3：总编审校
- **驱动命令**：`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：成稿
- **驱动命令**：`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`

---

## 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. Python Role / Task 模型

平台 agent 文件只保留兼容和展示意义；真实角色、任务类型、模型、温度、并发上限以 Python runtime 为准。

查看当前模型配置：

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

核心任务类型：

| 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 渲染 |

默认策略：

- Codex/GPT 系列适合代码、schema、回归、review。
- Claude/Opus/Sonnet 适合长文结构、中文表达、访谈增强。
- Gemini 适合长上下文审校、多模态材料、替代框架评估。
- ZenMux 混合模型仍由 `configs/models.yaml` 统一管理，平台当前会话模型不得覆盖 Python role/task 映射。

## 6. Platform Adapter 调用方式

详见 `docs/platform-adapters.md`。摘要如下：

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

跨平台硬规则：

- 平台只做 surface adapter，不承载核心调度。
- 不在平台 prompt 中手工并发写章节。
- 不把平台 subagent 当默认并发机制。
- 真实并发由 `scripts/runtime/workers.py` 的 worker pool 执行。
- 真实模型选择由 `configs/models.yaml` 和 `scripts/runtime/roles.py` 执行。
- 信息检索默认走 `scripts/search.py` / `SearchClient` / `search-gateway` skill；不得把 Tavily MCP、browser MCP 或平台 web search 作为默认路径，除非用户明确授权。
- 搜索路由必须按任务类型选择：`evidence`=Exa highlights 受控证据发现，`fda/scholar/patents/news`=专用信源路径，`general`=宽泛发现和兜底；Tavily Research 只能作为阶段性 scan/enrichment/rework 输入，不能直接替代 evidence packet 或章节正文。

---

## 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. 如何判断是否走了 Python Core

不要用“平台是否 spawn subagent”作为成功标准。v0.20 的验证锚点是 Python runtime 产物：

1. `uv run python scripts/dr.py status <slug>` 能看到 phase 状态。
2. Phase 2 存在 `phase2/task_cards.json`。
3. Phase 1 存在 `phase1/research_brief.md` 和 `phase1/research_brief.json`。
4. `--execute-packets` 后存在 `phase2/packets/*.json` 和必要时的 `phase2/packet_errors/*.json`。
5. `--build-briefs` 后存在 `phase2/chapter_briefs/*.json` 与 `phase2/compressed_findings/*.json`。
6. `--assemble-chapters` 后存在 `phase2/drafts/chXX.md` 和必要时的 `phase2/chapter_errors/*.json`。
7. `scripts/v020_regression.py` 输出 `v0.20 regression PASS`。

---

## 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 清单中标记完成状态