research-literature-review

研究文献レビュー

目標

• 目標：隔離された作業ディレクトリ内で、「検索 → 重複排除 → スコアリング → 文献選定 → 執筆 → 検証 → PDF/Word エクスポート」の完全なレビューのパイプラインを実行します。
• 対象：ユーザーがシステマティックレビュー、文献レビュー、関連研究、文献調査を明確に依頼し、LaTeX + BibTeX + PDF/Word の成果物を希望する場合。
• 対象外：参考文献を1件だけ補いたい場合、既存の本文だけを推敲したい場合、一般的な要約だけを書きたい場合、またはレビューとは無関係な記事を書きたい場合。
• 最優先の原則：利用可能な最良のエビデンスと執筆品質に基づいてレビューを完成させます。不確かな場合は対応方法を説明し、急ぐために信頼性を犠牲にしません。
• research-literature-search はフェーズ1/2の必須依存関係です（contract rls.v1）。review はその manifest、canonical candidates、provenance のみを使用し、provider を内包したり、2つ目の canonical 重複排除を実行したりしません。
• 旧名 systematic-literature-review は、prompt との互換性を保つ別名としてのみ残します。.systematic-literature-review/ は、引き続き安定した旧作業ディレクトリ名です。

入力の概要

最低限必要なもの：

1. {テーマ}：1文で表したテーマ。
2. 任意の範囲：期間、言語、研究の種類、データベースの優先設定など。
3. プラン：Premium / Standard / Basic。指定がない場合は config.yaml のデフォルト値を読み込みます。
4. 目標文字数と参考文献の範囲：指定がない場合は config.yaml.scoring.default_*_range に従います。
5. 出力ディレクトリまたはサニタイズ済みのプレフィックス：指定がない場合は、サニタイズしたテーマ名を使用します。
6. クエリ入力：フェーズ1の前に、公開スキーマに準拠した複数クエリの JSON を用意する必要があります。--query-file の使用を推奨します。または、現在の run の input/queries.json に記入することもできます。

フロー

入力

ユーザーの依頼と設定ファイルに従って必要な入力を用意します。不足している情報があれば明示し、その入力に依存するステップを停止します。

実行手順

• ユーザー環境で、この skill の設計上の欠陥に起因するバグが発生した場合は、規定に従って bensz-collect-bugs を使い、~/.bensz-skills/bugs/ に記録することを優先します。ユーザーのローカル Claude Code / Codex にインストール済みの skill のソースコードを直接変更してはいけません。
• AI が回避策を使ってユーザーのタスクを続行できる場合は、まずバグを記録してから、現在のタスクを続行します。
• ユーザーが「report bensz skills bugs」などの公開報告を明確に依頼した場合は、ローカルの gh と bensz-collect-bugs を呼び出し、新規バグのみを huangwb8/bensz-bugs にアップロードします。バグリポジトリ全体を pull / clone してはいけません。

準備

• テーマ、プラン、文字数/参考文献の範囲、出力ディレクトリを記録します。
• まず references/ai_query_generation_prompt.md を読み、クエリ JSON を生成します。公開スキーマでは、次の3つの形式をサポートしています。
  • {"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 内にある一意の旧互換ファイル。
• 候補が複数自動検出された場合は停止して、競合を報告します。ファイルが検出されてもスキーマ/件数が無効な場合は停止し、修正方法を提示します。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 を検証します。resume との互換性を保つため、2_dedupe checkpoint 名は維持します。
• 新しい run で旧 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 のクリーニングでは、次の項目を必ず保持します：大文字小文字を区別しない重複排除キー、LaTeX の特殊文字のエスケープ、フィールド不足の警告。
• エビデンス上の役割には direct-neighbor、supporting、methodological、contradictory、boundary を使用します。幅広い手法の類似性よりも、直接の近接研究と反証エビデンスを優先します。
• 標準的なレビューでは、要旨があり、関連性のしきい値を満たす項目のみを正式な引用セットに含めます。適格な論文がソフト目標を下回る場合は、より小さなセットでそのまま納品し、停止理由とエビデンスの不足を rationale に記載します。

新規性チェック

呼び出し目的が --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

导出与多语言

• 通过 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 和上方流程所声明的范围；不将未验证的信息伪装成确定结论。