kai/deep_research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ab502df917a3d4382b4773fd08176f9ced41b82
deep_research/AGENTS.md
T

13 KiB
Raw Blame History

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 为准。

查看当前模型配置：

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 .agents/agents.md + .agents/rules + .agents/skills + .agents/workflows 角色定义在 agents，强约束在 rules，技能在 skills，流程在 workflows

跨平台硬规则：

  • 除 Antigravity native 模式外，平台只做 surface adapter，不承载核心调度。
  • Antigravity 的角色定义放在 .agents/agents.md；不要把角色、技能和流程继续堆进本文件。
  • 不在平台 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”作为成功标准。Python-core 模式的验证锚点是 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。

Antigravity native 模式的验收锚点由 .agents/workflows/deep-research-native.md 定义。

10. 禁止事项（negative instructions）

所有 agent 均禁止：

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

11. 变更管理

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