Research Literature Review

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。

流程

输入

按用户请求和配置文件提供必要输入；缺失信息应明确列出并停止依赖该输入的步骤。

执行步骤

• 当用户环境中出现因本 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/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 继续。
• 开始前优先阅读：
  • references/ai_query_generation_prompt.md
  • references/ai_scoring_prompt.md
  • references/expert-review-writing.md
  • references/review-tex-section-templates.md
  • 涉及翻译时再读 references/multilingual-guide.md

多查询检索（调用 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。
• 评分范围固定为 1-10 分；仅对 >=5 分文献分配子主题，避免弱相关论文污染子主题规划。
• 自检分布是否健康：高分约 20-40%，中分 40-60%，低分 10-30%。

选文与 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 写停止理由与证据缺口。

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 内。

写作

• 正文章节固定为：摘要、引言、子主题段、讨论、展望、结论。
• 写作前读取 word_budget_final.csv，按文献综/述预算组织证据。
• 默认采用单篇引用优先；引用要紧跟所支撑的观点，避免段末堆砌。
• 如需详细写作规范，直接遵循：
  • references/expert-review-writing.md
  • references/review-tex-section-templates.md

有机扩写与验证

• 若字数不足，只允许在最短或证据不足的子主题段内做增量扩写，不新增子主题，不改原主张和引用。
• 依次运行：
  • validate_counts.py
  • validate_review_tex.py
  • 可选 validate_word_budget.py
  • generate_validation_report.py