学术调研报告生成
从真实文献产出可核验的深度研究报告，而非凭记忆写作。核心是六段流水线 + 三道闸门：检索必须有出处、筛选必须可解释、成稿必须自校验。
何时使用
- 用户要求"用学术模式调研 X 主题近 N 年主要研究进展，生成 HTML 深度研究报告"
- 要求调研文献并标注来源链接、含技术发展脉络 / 典型成果 / 研究空白
- 要求把文献数据存为 CSV 并与报告 HTML 联动
- 需要写文献述评、系统性综述、领域现状扫描
不适用：单篇论文解读、纯事实查询、新闻综述（无文献检索需求）。
流水线
六段，每段有明确的输入输出。不要跳过 fetch 直接写报告——报告里的每个数字都必须能追溯到 data/papers.json 中的一条记录。
0. 确认参数 主题 + 时间窗 → config.py
1. 抓取 pipeline.py fetch --config config.py → data/raw_pool.json
2. 校验纯度 人工看标题清单，调 TITLE_MUST_MATCH / DROP_TITLE
3. 筛选 pipeline.py curate --config config.py → data/papers.json + *.csv
4. 读文献 读 papers.json 摘要，摘出可直接引用的数字
5. 成稿 cp assets/report_template.html report.html，填写章节
6. 构建+校验 pipeline.py build ... → validate.py ...
脚本位于本技能 scripts/，运行时用绝对路径调用：
python <skill>/scripts/pipeline.py fetch --config config.py
阶段 0：确认参数
主题和时间跨度若未明确，先问用户，不要自行假定。确认后把 assets/config_template.py 复制为项目内 config.py 填写。换主题只改这一个文件，不改代码。
阶段 1：抓取
按学科选数据源：
| 学科 | SOURCES | 说明 |
|---|---|---|
| 生命科学 / 医学 | ("epmc", "arxiv") |
Europe PMC 覆盖 PubMed/PMC，带被引数 |
| 计算机 / 物理 / 工程 / 社科 | ("openalex", "arxiv") |
OpenAlex 全学科覆盖，无需 key |
| 交叉领域 | ("epmc", "openalex", "arxiv") |
三源合并自动去重 |
检索式写法与字段见 references/epmc_query.md。必须使用字段限定（如 TITLE_ABS:"..."），裸关键词会在全文命中，直接把跑题文献拉进池子。
阶段 2：校验纯度（最容易跳过，也最致命）
fetch 完成后必须通读候选池标题：
python <skill>/scripts/pipeline.py stats --config config.py
判断标准：随机看 20 条，若超过 2 条明显跑题，说明检索式或过滤条件有问题，回到配置修正后重跑。下游任何配额算法都无法把跑题文献洗干净——候选池污染是唯一不可逆的错误。
阶段 3：筛选
curate 按「等级 3.0/2.4/1.7/0.9 + 0.55×ln(1+被引) + 0.16×年距 + 1.2×主题锚词命中」评分，再按 QUOTA 逐主题取前 N，并强制每主题保留近年文献（MIN_RECENT_PER_TOPIC），最后按 LANDMARKS 把自动筛选漏掉的关键论文强制补入。
输出 CSV 为 UTF-8 BOM，表头固定：编号、论文标题、作者、期刊、等级、摘要、访问链接、发表日期、主题分类、被引次数、文献类型。
阶段 4：读文献再写
逐一读 papers.json 摘要，摘出可引用的事实（样本量、效应量、P 值、队列规模、随访年限）。报告里每个数字都必须来自某条摘要，拿不准的数值宁可不写。分两批读，避免单次输出过长被截断。
阶段 5：成稿
复制 assets/report_template.html 为项目内 report.html 作为源文件，只替换正文文字与章节内容，保留 style 与 script 区块。正文引用写 {{P014}}，构建时自动转为可点击上标角标。
章节结构与写作规范见 references/report_outline.md，组件（时间轴、机制卡、证据表、空白卡、图表）用法同在该文件。
阶段 6：构建与校验
python <skill>/scripts/pipeline.py build --config config.py --src report.html --out 最终报告.html
python <skill>/scripts/validate.py --html 最终报告.html --csv <OUT_STEM>.csv --data data/papers.json
build 负责注入数据、解析引用、改写 CSV 下载链接。validate 是交付闸门，退出码非 0 必须修掉再交付，不能用肉眼截图代替。
校验通过后用无头浏览器渲染截图，确认首屏、图表、时间轴、文献表四处视觉正常（校验脚本管不了排版），再交付。
三道闸门
| 闸门 | 检查内容 | 失败后果 |
|---|---|---|
| 纯度 | 候选池随机抽样是否跑题 | 报告主题涣散，无法补救 |
| 引用覆盖 | 是否存在"只在表格出现、正文从未引用"的文献 | 凑数条目，损害可信度 |
| 一致性 | HTML 内嵌数据 = CSV = papers.json；JS 引用的 DOM id 是否存在 | 图表空白、下载失效 |
必须向用户声明的三点
交付时主动说明，不要等用户质疑：
- 样本性质：这是高影响力抽样，不是 PRISMA 级穷尽综述，未做双人独立筛查与偏倚评估。
- 时效偏差：时间窗末段文献因引用积累不足而系统性偏少，越新的工作越可能被低估。
- 分级含义：T0–T3 是期刊影响力代理，不等于单项研究内部效度；正文已另行标注研究类型（RCT/队列/机制研究）。
文件索引
scripts/journal_tiers.py 期刊分级（T0/T1 全学科映射 + 防子串误匹配）
scripts/pipeline.py fetch / curate / build / stats 单入口
scripts/validate.py 交付前质量闸门
assets/report_template.html 报告骨架：设计系统 + SVG 图表 + 联动文献表 + 弹窗
assets/config_template.py 配置模板（复制后填写）
references/pitfalls.md 已验证的失效模式与对策 —— 动手前先读
references/epmc_query.md 三个数据源的检索语法与字段速查
references/report_outline.md 章节结构、写作规范、组件用法
references/config_examples.md 可直接复用的完整配置
重要约束
- 文献元数据只能来自 API 实际返回，禁止编造标题、作者、DOI 或摘要。
- 不引入 CDN 或外部字体，报告须能离线打开与打印。
report.html（源）与最终 HTML（产物）必须是不同文件，否则数据注入会污染模板。- 修改检索式后必须重跑 fetch → curate → build 全链；只重跑 build 会得到与数据不一致的旧稿。
