/research-literature-review

name: research-literature-review
description: 当用户要求系统综述、文献综述、related work、相关工作或文献调研时使用；也支持明确的研究查新任务。兼容旧名 systematic-literature-review。仅检索候选论文、单条引文核查或既有正文润色不属于本 Skill。
metadata:
  author: Bensz Conan

Research Literature Review

目标

• 目标：在一个隔离工作目录内完成“检索 → 去重 → 评分 → 选文 → 写作 → 校验 → PDF/Word 导出”的完整综述流水线。
• 适用：用户明确要系统综述、文献综述、related work、文献调研，并希望得到 LaTeX + BibTeX + PDF/Word 产物。
• 不适用：只想补单条参考文献、只想润色已有正文、只想写普通摘要或与综述无关的文章。
• 最高原则：以最佳可用证据和写作质量完成综述；不确定时说明处理方式，不为赶进度牺牲可信度。
• `research-literature-search` 是阶段 1/2 的必需依赖（contract `rls.v1`）。review 只消费其 manifest、canonical candidates 和 provenance，不再内嵌 provider 或执行第二套 canonical 去重。
• 旧名 `systematic-literature-review` 仅作为 prompt 兼容别名保留；`.systematic-literature-review/` 仍是稳定历史工作区名。

流程

输入

最少需要：

1. `{主题}`：一句话主题。 2. 可选范围：时间、语言、研究类型、数据库偏好等。 3. 档位：`Premium` / `Standard` / `Basic`；未指定时读取 `config.yaml` 默认值。 4. 目标字数与参考文献范围：未指定时按 `config.yaml.scoring.default_*_range`。 5. 输出目录或安全化前缀：未指定时使用安全化主题名。 6. 查询输入：阶段 1 前必须提供符合公开 schema 的多查询 JSON；推荐用 `--query-file`，也可填写当前 run 的 `input/queries.json`。

明确叙述性进展综述、正式系统综述或 novelty-check。查询由 AI 按主题生成，不把内部 JSON 准备责任转嫁给用户；仅缺少会影响范围的关键信息时澄清。

执行步骤

• 当用户环境中出现因本 skill 设计缺陷导致的 bug 时，优先使用 `bensz-collect-bugs` 按规范记录到 `~/.bensz-skills/bugs/`，严禁直接修改用户本地 Claude Code / Codex 中已安装的 skill 源码。
• 若 AI 仍可通过 workaround 继续完成用户任务，应先记录 bug，再继续完成当前任务。
• 当用户明确要求“report bensz skills bugs”等公开上报动作时，调用本地 `gh` 与 `bensz-collect-bugs`，仅上传新增 bug 到 `huangwb8/bensz-bugs`；不要 pull / clone 整个 bug 仓库。

准备

• 记录主题、档位、字数/参考范围与输出目录。
• 读取 [正式交付规范](references/output-delivery.md)，确定文献、质检、正文资源和可选材料的目标位置。
• 先读取 `references/ai_query_generation_prompt.md`，生成查询 JSON。公开 schema 支持以下三种形态：
• `{"queries": [{"query": "...", "rationale": "..."}]}`
• `[{"query": "...", "rationale": "..."}]`
• `["query 1", "query 2"]`
• 剔除空查询后，有效数量必须满足 `config.yaml:query_input.min_queries/max_queries`（默认 5–25）。
• 已知工作目录时，直接将文件保存到 `<work-dir>/input/queries.json`，或用 `--query-file <path>` 让 runner 将显式输入复制到该位置。工作目录尚未建立时，先运行 `--prepare-only`，填充打印出的 `input/queries.json`，再以 `--resume ... --resume-from 1` 继续。
• 参考资料按阶段读取，入口与用途见 [README 的参考资料索引](README.md#参考资料与读取时机)；评分时读评分模板，写作时读写作指南与 TeX 模板，翻译资料仅在翻译任务中读取。

多查询检索（调用 research-literature-search）

• 查询来源优先级固定为：显式 `--query-file` → 当前 run 的 `input/queries.json` → `input/queries_{stem}.json` → `output/artifacts/queries_{stem}.json` → 当前 run 内唯一历史兼容文件。
• 自动发现多个候选时停止并报告冲突；发现文件但 schema/数量无效时停止并给出修复提示。不得跨 run 猜测查询路径。
• 启动阶段先发现并校验 `research-literature-search`（顺序：`--search-skill-root` → 项目内 `skills/research-literature-search` → 环境变量 → 用户 Skill 根目录）；缺失或 contract 不兼容时 fail-closed，并给出安装提示。
• 调用 search 的 `run` 入口生成 manifest bundle；review 将其作为只读输入包保存并记录 manifest/candidate hash、contract version 和 source path。
• Search Log 的 `search_mode/query_source/requested_query_count/accepted_query_count/fallback_reason` 由 manifest 单向生成；AI 不手写 provider 次数、候选数量或去重结论。
• 单查询只作为显式后备：传 `--allow-single-query-fallback`，可用 `--fallback-reason` 写明原因；日志必须标记 `search_mode=single_query` 和醒目警告。

去重（契约验证，不重复去重）

• 验证 manifest、artifact hash、`rls.paper.v1` 和 `candidates_deduped.jsonl`；保留 `2_dedupe` checkpoint 名称以兼容 resume。
• 新运行不得再次执行旧 `dedupe_papers.py` 或改变 canonical 顺序；旧文件/旧 checkpoint 仅通过显式 legacy adapter 读取，并标记 `legacy_adapted`。
• 所有后续流程只读取 search bundle 的 canonical 候选集。

AI 评分与数据抽取

• AI 按 `references/ai_scoring_prompt.md` 逐篇阅读标题与摘要，输出 `scored_papers.jsonl`。
• 每篇至少包含：`score`、`subtopic`、`rationale`、`alignment`、`extraction`。
• 评分范围为 `config.yaml:scoring.score_scale`（默认 1–10）；达到 `selection.minimum_score`（默认 5）才分配子主题，避免弱相关论文污染子主题规划。
• 评分依主题适配程度，不强制高/中/低分比例；相关性不是偏倚风险或证据强度。

选文与 Bib 生成

• `select_references.py` 按最低相关性、证据角色和软预算选出最终集合；`target_refs` 是预算目标，`max_refs` 是上限，不再用低分或无摘要条目填满旧 `min_refs`。
• 生成 `selected_papers.jsonl`、`references.bib`、`selection_rationale.yaml`。
• Bib 清洗必须保留：大小写无关去重 key、LaTeX 特殊字符转义、缺失字段警告。
• 证据角色使用 `direct-neighbor`、`supporting`、`methodological`、`contradictory`、`boundary`；直接近邻和反方证据优先于宽泛方法相似。
• 标准综述只把有摘要且达到相关性阈值的条目放入正式引用集合。合格论文少于软目标时照常交付较小集合，并在 rationale 写停止理由与证据缺口。
• 显式 `do_not_cite=true` 的条目不得进入标准综述的选文和 Bib；原始评分审计保留，查新模式仍可保留禁止引用的待核验线索。

Novelty check

当调用目的为 `--purpose novelty-check` 时，只运行到阶段 4，输出强近邻、反方/边界证据、未确认项与证据深度，不自动生成长篇正文、PDF 或 Word。只有标题的直接近邻可保留为待升级记录并标记 `do_not_cite`；预印本与正式论文使用同一相关性尺度，发表状态单列。

子主题与配额规划

• AI 基于评分结果规划 3-7 个子主题，并给出段落配额。
• 默认思路：引言约 1.5k、讨论/展望各约 1k、结论约 0.6k，其余分给子主题段。
• 结果写入工作条件与数据抽取表，作为写作锚点。

字数预算

• 用 `plan_word_budget.py` 生成 3 份预算 CSV，再汇总为 `word_budget_final.csv`。
• 引用段与无引用段预算均需覆盖；总字数误差必须控制在 `config.yaml.word_budget.tolerance` 内。
• 生成和验证预算必须传递同一档位与目标字数；独立校验可用 `--review-level` 或 `--target-words`。预算生成仅额外允许读取 Skill 自带的只读配置，其余输入和输出仍限于当前工作目录。

写作

• 默认章节为摘要、引言、主体、讨论、展望、结论。正文直接呈现领域认识、研究发现、争议与证据边界；摘要、引言、主体、讨论、展望和结论均不叙述本次综述写作前如何调研文献，也不把这些内容挪到脚注、图表或附录。
• 本次综述的数据库与平台、检索式、检索日期或更新截止日、追溯方式、纳排与筛选过程、文献数量、评分选文及 RoB/GRADE 是否实施等说明，统一写入工作条件、Search Log 或配套报告；不以“透明检索”“叙述性综述”或未实施某项方法的免责声明带回正文。主题、人群、疾病阶段等实质范围可在引言简要界定。
• 讨论原始研究的设计、偏倚、异质性、疗效及外推限制仍是正文任务；区分“被综述研究的方法”与“本次综述的制作过程”。仅用户或目标期刊明确要求方法报告（如 PRISMA）时，才按要求另设方法章节或补充材料；仅称“系统综述”不自动加入流程叙述，也不得虚构已完成的方法或据此宣称符合报告规范。
• 写作前读取 `word_budget_final.csv` 与完整证据资料，预算用于检查篇幅，不机械逐篇填空。关键主张核对人群、设计、终点、数值、不确定性及指南版本；证据深度在工作条件中如实说明。
• 证据卡保留完整摘要和已有提取字段；显式截断时依 source_id/source_record 回读原始选文。缺证据先补检或缩小主张，不靠语言扩写填满预算。
• 新稿用 `render_review_template.py --title ... --body ... --bib ... --output ...` 应用真实学术模板；已有完整 TeX 或指定版式保留。阅读 `references/review-tex-section-templates.md` 后再写导言区。
• 默认采用单篇引用优先；引用要紧跟所支撑的观点，避免段末堆砌。
• 如需详细写作规范，直接遵循：
• `references/expert-review-writing.md`
• `references/review-tex-section-templates.md`

有机扩写与验证

• 若字数不足，先判断是否遗漏问题、比较或证据；只有新增内容有实际解释价值时扩写。结构或主张需要改变时回到证据与规划阶段，不为凑字数重复边界声明。
• 交稿前逐段检查正文是否在回答“这篇综述是怎样做出来的”；若是，将过程信息移至配套材料，删去重复声明。该语义检查同时覆盖中文、英文、摘要、脚注、图表与附录，不能只凭流程关键词或数据库名判定，也不能据脚本通过宣称已完成。
• 依次运行：
• `validate_counts.py`
• `validate_review_tex.py`
• `validate_subtopic_count.py`（默认 3–7 个主体主题）
• `validate_word_budget.py`（已有预算时执行）
• `generate_validation_report.py`

导出与多语言

• 导出、发布和最终交付前必须读取 [正式交付规范](references/output-delivery.md)：标准根目录仅正文 DOCX/PDF/TeX，书目归 `references