research-literature-review

name research-literature-review description 当用户明确要求"做系统综述/文献综述/related work/相关工作/文献调研"，或要求使用旧名 systematic-literature-review skill 时使用。AI 先生成并显式保存 5–25 条检索查询，再执行多源检索、去重、逐篇语义评分、选文、字数预算和专家写作，强制校验引用并导出 PDF 与 Word；查询缺失或无效时默认停止，不静默降级为单查询。支持 en/zh/ja/de/fr/es。 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/ 仍是稳定历史工作区名。 输入 最少需要： {主题} ：一句话主题。 可选范围：时间、语言、研究类型、数据库偏好等。 档位： Premium / Standard / Basic ；未指定时读取 config.yaml 默认值。 目标字数与参考文献范围：未指定时按 config.yaml.scoring.default_*_range 。 输出目录或安全化前缀：未指定时使用安全化主题名。 查询输入：阶段 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 按目标参考范围和高分优先比例选出最终集合。 生成 selected_papers.jsonl 、 references.bib 、 selection_rationale.yaml 。 Bib 清洗必须保留：大小写无关去重 key、LaTeX 特殊字符转义、缺失字段警告。 摘要缺失或过短的条目标记 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 导出与多语言 通过 compile_latex_with_bibtex.py 生成 PDF。 通过 convert_latex_to_word.py 生成 Word。 如用户要求多语言版本，使用 multi_language.py 翻译正文并智能编译；失败时保留错误报告与 broken 文件，并优先支持恢复备份。 # 查询文件已准备好：推荐主入口 python3 scripts/run_pipeline.py --topic "{主题}" --query-file ./queries.json --publish-dir ./review-deliverables # 两步式：先生成模板，再填充 input/queries.json 并恢复阶段 1 python3 scripts/pipeline_runner.py --topic "{主题}" --work-dir <work-dir> --prepare-only python3 scripts/pipeline_runner.py --resume <work-dir> --resume-from 1 --publish-dir ./review-deliverables # 临时兼容外部编排器：显式、可审计的单查询后备 python3 scripts/run_pipeline.py --topic "{主题}" --allow-single-query-fallback --fallback-reason "外部编排器暂未提供查询文件" # 旧入口 / resume python3 scripts/pipeline_runner.py --topic "{主题}" --domain general --query-file ./queries.json --publish-dir ./review-deliverables # 显式指定 search Skill（独立安装环境） python3 scripts/pipeline_runner.py --topic "{主题}" --query-file ./queries.json \ --search-skill-root /path/to/research-literature-search python3 scripts/pipeline_runner.py --resume .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/research-literature-review/{run-id} --publish-dir ./review-deliverables # 阶段 3 评分后，从第 4 阶段继续 python3 scripts/pipeline_runner.py --resume .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/research-literature-review/{run-id} --resume-from 4 --resume-from 只决定继续执行的阶段，不会绕过已有 pipeline_state.json 。状态文件损坏时先备份或修复，禁止用空 state 覆盖历史 checkpoint。 运行环境：Python 3.9+、LaTeX（ xelatex / bibtex ）、pandoc。 关键脚本： 检索： multi_query_search.py 、 openalex_search.py 去重： dedupe_papers.py 选文： select_references.py 、 build_reference_bib_from_papers.py 数据抽取： update_working_conditions_data_extraction.py 字数预算： plan_word_budget.py 、 validate_word_budget.py 校验： validate_counts.py 、 validate_review_tex.py 、 generate_validation_report.py 导出： compile_latex_with_bibtex.py 、 convert_latex_to_word.py 初始化： python3 research-literature-review/scripts/pipeline_cost.py init 抓取定价： python3 research-literature-review/scripts/pipeline_cost.py fetch-prices 记录 token： pipeline_cost.py log ... 汇总： pipeline_cost.py summary 所有成本数据写到内部 output/cost/ （旧运行仍可显式使用 legacy 目录）。 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 references/development-validation-guide.md 输出 默认发布以下核心文件（通过 --publish-dir 指定正式目录时复制）： {主题}_review.pdf {主题}_review.docx 可选支持性文件（使用 --include-supporting 发布）包括 {主题}_工作条件.md 、 {主题}_review.tex 、 {主题}_参考文献.bib 和 {主题}_验证报告.md 。字数预算、候选文献、评分、选文、摘要补齐和证据卡始终属于内部中间产物，不进入正式发布目录。 必要中间产物包括： papers*.jsonl scored_papers.jsonl selected_papers.jsonl selection_rationale.yaml 可选 evidence_cards_{主题}.jsonl 输出管理 本 Skill 的新任务中间文件统一写入 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/ 。同一任务复用一个任务根目录；多 Skill 协作才创建 shared/ 。正式交付物不写入该目录，历史隐藏目录只允许显式兼容读取、迁移或清理。 默认 run_pipeline.py 将运行目录放在 .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/research-literature-review/<run-id>/ ；查询输入位于 input/ ，内部状态和产物位于 output/ 下的 artifacts/ 、 reference/ 、 cache/ 、 scripts/ 、 deliverables/ （支持性文件单独位于 deliverables/supporting/ ）。 正式交付目录必须通过 --publish-dir 显式指定，并且只接收 PDF/Word（或显式开启的支持性文件）。不要把正式目录作为 --work-dir 。 AI 临时脚本必须放到内部 output/scripts/ ；不要把临时文件写到运行目录根部，不要使用绝对路径写 /tmp/* ，也不要读写其他 run 目录。 以环境变量 SYSTEMATIC_LITERATURE_REVIEW_SCOPE_ROOT 和 SYSTEMATIC_LITERATURE_REVIEW_SCRIPTS_DIR 为准。 search bundle 位于当前 review run 的 output/artifacts/search_bundle_{stem}/ ，review 只读消费其 manifest 指向的相对路径；不得跨 run 猜测或直接信任外部绝对 artifact 路径。 校验 完成后执行 Skill 已有的静态检查、脚本验证或人工复核，并记录通过标准。 失败与恢复 保留错误证据和已完成产物；仅在输入、环境或外部依赖恢复后从最近的失败步骤重试。 约束 强制导出 PDF 与 Word；只有明确失败并记录原因时才允许缺失。 正文字数与参考文献数必须落在当前档位范围内；可由用户覆盖，默认值以 config.yaml 为准。 正文固定包含：摘要、引言、至少 1 个子主题段、讨论、展望、结论。 \cite{key} 必须与 BibTeX key 一致；缺失即报错。 正文禁止泄露 AI 工作流，例如“检索/去重/评分/选文/字数预算”等元叙事只能写入 {主题}_工作条件.md 。 摘要必须为单段，避免方法学流水账；表格宽度与样式约束见 references/review-tex-section-templates.md 。 不为凑引用而堆砌低分文献；无法确认时优先不改、不引。 多查询 JSON 缺失、冲突、不可解析、有效查询少于配置下限或超过上限时，阶段 1 必须 fail-closed；不得以成功退出码伪装成多查询完成。 只有调用方显式传入 --allow-single-query-fallback 时才允许执行一次单查询，并在 state 与 Search Log 中记录模式、来源、原因和警告。 公共硬约束 任务需要落盘时，使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录；共享材料放入 shared/ ，Skill 专属材料放入该 Skill 的 input/ 、 output/ 、 log/ 。 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。 Skill 版本唯一记录在自身 config.yaml:skill_info.version ；公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md 。 仅将 Skill 或 Bensz 基础设施本身的设计缺陷交给 bensz-collect-bugs ；先脱敏写入 ~/.bensz-skills/bugs/ ，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。 Skill 专属约束 不得超出本 Skill description 和上方流程所声明的范围；不将未验证的信息伪装成确定结论。