nsfc-ref-alignment

NSFC 文献引用对齐

适用场景

• NSFC 申請書（LaTeX プロジェクト）があり、次の点を確認したい場合：
  • .tex 内のすべての \cite{...}／\citep{...}／\citet{...} などの引用キーが .bib に存在するか
  • .bib の各エントリーに必須項目がそろっているか、明らかな書式エラーがないか（DOI が不正、年が欠落しているなど）
  • 引用を含む文の「意味上の主張」が、該当文献（少なくとも title／author／year／venue／DOI などのメタデータ）と一致しているか、誤引用・過剰な主張・取り違えのリスクがないか
• まずはレポートだけを受け取り、人手で確認したい場合（.bib や本文の修正は重大な作業です）。

不適用

• 「引用キーの自動置換／本文の自動書き換え」を希望する場合。このスキルでは、明示的な依頼がない限り、直接の変更を禁止しています。
• BibTeX エントリーの補完だけが必要な場合は、nsfc-bib-manager を優先して使用してください。

入力

• project_root：申請書プロジェクトのルートディレクトリ（例：projects/NSFC_General）
• 任意：main_tex：メインの入口となる tex ファイル（既定値は main.tex）
• 任意：report_dir：レポートの出力先ディレクトリ（既定値は ./references。スキルを実行する現在のディレクトリからの相対パス）
• 任意：verify_online：オンライン検証を行うかどうか（既定値は false。確定的な照会のみ行い、失敗時は処理を縮退）

ワークフロー

入力

ユーザーの依頼と設定ファイルに基づいて必要な入力を受け取ります。不足情報がある場合は明示して列挙し、その入力に依存する手順を中止します。

実行手順

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

ステップ 1：事前確認と特定

1. project_root が存在し、main_tex が含まれていることを確認します。
2. main_tex の \input{}／\include{} 依存ツリーを自動解析し、関連するすべての .tex ファイルを収集します。
3. \bibliography{...}／\addbibresource{...} が指定する .bib ファイルを自動検出します。.bib が 0 件の場合は、project_root 配下で *.bib を検索し、warning を出します。

ステップ 2：確定的な抽出（スクリプト実行）

スクリプトを実行し、構造化入力と確定的なレポートを生成します。

cd /path/to/ChineseResearchLaTeX
python3 skills/nsfc-ref-alignment/scripts/run_ref_alignment.py \
  --project-root "projects/NSFC_General" \
  --main-tex "main.tex" \
  --report-dir "references" \
  --prepare

オンライン検証が必要な場合（最終稿や重要なエントリーにのみ有効化することを推奨）：

python3 skills/nsfc-ref-alignment/scripts/run_ref_alignment.py \
  --project-root "projects/NSFC_General" \
  --main-tex "main.tex" \
  --report-dir "references" \
  --prepare \
  --verify-online

ステップ 3：ホスト AI による意味の確認（本スキルの中核）

ホスト AI は {run_dir}/ai_ref_alignment_input.json を読み込み、各項目を次のとおり確認します。

1. 真正性／存在確認（P0）

   • 引用キーの欠落：本文が存在しないエントリーを引用している
   • DOI／URL が明らかに無効、またはオンライン検証に失敗し、メタデータに重大な不一致がある

2. 意味の不一致リスク（P0/P1）

   • P0：文が文献について「強い断定」をしているが、メタデータを見る限り、その可能性が極めて低い（年の矛盾、分野がまったく無関係、明らかな取り違えなど）
   • P1：疑わしいものの、証拠が不十分（メタデータ不足、DOI がない、title がない、著者情報が不完全）

3. 過剰な主張／根拠の弱さ（P1）

   • 例：「初めて／唯一／最適／大幅に優れている」と主張しているが、十分な根拠がない、またはより強い引用が必要と思われる場合

証拠の優先順位（必須）： オンライン検証結果（有効化されている場合） > BibTeX の title／abstract > 文だけからの推論（優先度が最も低い）。

ステップ 4：最終レポートの生成（読み取り専用）

report_dir に最終レポート NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md を出力します。必ず次の内容を含めます。

• Summary：引用総数、一意な引用キー数、欠落エントリー数、重複エントリー数、P0／P1 の数

• P0（必ず対応）：引用キーの欠落、明らかな捏造／誤ったメタデータ、重大な意味の不一致

• P1（対応を推奨）：項目の不足（DOI／year の欠落）、根拠の弱さ／過剰な主張、人手による確認が必要な項目

• 付録：引用ごとの詳細（少なくとも file／line、原文、Bib エントリーの主要項目、リスク判定と理由を含む）

• 共通点：スクリプトは確定的な抽出のみを行います。「意味が一致しているか」の判定はホスト AI が行い、追跡可能な構造化入力とレポートを出力します。

• 相違点：本スキルは申請書プロジェクト（複数ファイルの \input{} 構造）を対象とし、既定では自動書き換えを一切行いません（審査レポートのみ出力します）。

出力

中間成果物（必須）

すべての中間ファイルは、次の場所に保管する必要があります。

{project_root}/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/nsfc-ref-alignment/{yyyy-mm-dd-hh-mm}/

このうち run_{YYYYMMDDHHMMSS} はタイムスタンプです。同じ秒に複数回実行した場合、スクリプトは -2/-3/... を追加し、分析が重複しないようにします。

このディレクトリには、少なくとも次のファイルを含めます。

• ai_ref_alignment_input.json：構造化入力（引用位置 + 文のコンテキスト + 文献メタデータ + 検証結果）。ホスト AI が意味を判定するために使用します
• ref_integrity_report.md：確定的なレポート（引用キーの欠落、重複エントリー、項目の欠落、DOI の書式上の問題など）
• citations.csv：引用ごとの一覧（file／line／bibkey／sentence）
• bib_inventory.json：BibTeX の一覧（引用されたエントリーと問題の注記）

最終成果物（既定）

ユーザー確認用のレポートのみを出力します（既定では ./references/ に保存。ユーザーは別のディレクトリを指定できます）。

• NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md（同じ秒に複数回実行した場合、上書きを防ぐためスクリプトが -2/-3/... を追加します）

このレポートは「読み取り専用の審査レポート」でなければならず、申請書本文や .bib を直接変更してはいけません。

出力管理

本 Skill の新しいタスクの中間ファイルは、すべて ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/ に出力します。同じタスクでは同じタスクルートディレクトリを再利用します。複数の Skill が連携する場合にのみ shared/ を作成します。正式な成果物はこのディレクトリに出力しません。過去の隠しディレクトリは、明示的な互換読み込み、移行、またはクリーンアップの場合に限り使用できます。

検証

• {project_root}/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/nsfc-ref-alignment/{yyyy-mm-dd-hh-mm}/ が存在し、4 つの主要成果物（json／md／csv／json）が含まれていること。
• 最終レポートが report_dir に出力され、.tex／.bib ファイルが一切変更されていないこと。
• 各 P0／P1 について、場所（file／line）+ 原文 + 根拠 + 推奨アクションがレポートに記載されていること。

失敗と復旧

エラーの証拠と完了済みの成果物を保持します。入力、環境、または外部依存関係が復旧した後に限り、直近の失敗ステップから再試行します。

制約

• 既定では、申請書の内容と設定を変更しません。
  • 変更禁止：**/*.tex、**/*.bib、**/*.cls、**/*.sty
• 書き込み可能：
  • {project_root}/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/nsfc-ref-alignment/**（中間成果物）
  • ./references/**（最終レポート。ユーザーは別の場所を指定できます）
• ユーザーが「引用の修正／bib の修正」を明示的に依頼した場合は、実行前にレポートで変更計画と影響範囲を示し、最小限の変更のみ行います（既定では実施しません）。

公共硬约束

• 任务需要落盘时，使用唯一的 ./.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 和上方流程所声明的范围；不将未验证的信息伪装成确定结论。