/nsfc-ref-alignment

name: nsfc-ref-alignment
description: 检查 NSFC 标书正文引用与参考文献的一致性与真实性风险（只读）：核查 bibkey 是否存在、BibTeX 字段与 DOI 等格式问题，并生成结构化输入供宿主 AI 逐条评估“正文表述是否真的在引用该文献”；默认仅输出审核报告，不直接修改标书或 .bib（除非用户明确要求）。
metadata:
  author: Bensz Conan

NSFC Ref Alignment

适用场景

• 你有一份 NSFC 标书（LaTeX 项目），希望检查：
• `.tex` 里所有 `\cite{...}` / `\citep{...}` / `\citet{...}` 等引用的 bibkey 是否都存在于 `.bib`
• `.bib` 条目的基础字段是否完备、格式是否明显错误（如 DOI 非法、年份缺失）
• 引用所在句子的“语义主张”是否与该文献（至少从 title/author/year/venue/DOI 等元信息）相匹配，是否存在乱引/过度主张/张冠李戴风险
• 你希望**只得到一份报告**先人工审核（改 `.bib` / 改正文属于大事）。

不适用

• 你希望“自动替换 bibkey / 自动改写正文”——本 skill 默认禁止直接修改（除非你明确要求）。
• 你只是想补齐 BibTeX 条目：优先使用 `nsfc-bib-manager`。

输入

• `project_root`：标书项目根目录（如 `projects/NSFC_General`）
• 可选：`main_tex`：主入口 tex（默认 `main.tex`）
• 可选：`report_dir`：报告输出目录（默认 `./references`，相对你运行 skill 的当前目录）
• 可选：`verify_online`：是否进行在线核验（默认 false；仅做确定性查询，失败降级）

流程

输入

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

执行步骤

• 当用户环境中出现因本 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 仓库。

步骤 1：预检与定位

1) 确认 `project_root` 存在且包含 `main_tex`。 2) 自动解析 `main_tex` 的 `\input{}` / `\include{}` 依赖树，收集所有涉及的 `.tex` 文件。 3) 自动发现 `\bibliography{...}` / `\addbibresource{...}` 指向的 `.bib` 文件；若发现 0 个 `.bib`，则回退为在 `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 语义核查（本 skill 的核心）

宿主 AI 在读取 `{run_dir}/ai_ref_alignment_input.json` 后，逐条核查：

1) **真实性/存在性**（P0）

• bibkey 缺失：正文引用了不存在的条目
• DOI/URL 明显无效或在线核验失败且元信息严重不一致

2) **语义不匹配风险**（P0/P1）

• P0：句子对文献作出了“强断言”，但从元信息看高度不可能（如年份矛盾、领域完全不相关、明显张冠李戴）
• P1：可疑但证据不足（元信息不足、缺少 DOI/缺少 title/作者信息不全）

3) **过度主张/弱支撑**（P1）

• 例如“首次/唯一/最优/显著优于”但缺乏足够支撑或疑似需要更强引用

> 证据优先级（强制）： > 在线核验结果（若开启） > BibTeX 的 title/abstract > 仅从句子推断（最低优先级）。

步骤 4：生成最终报告（只读）

在 `report_dir` 写入最终报告 `NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md`，必须包含：

• Summary：总引用数、唯一 bibkey 数、缺失条目数、重复条目数、P0/P1 数
• P0（必须处理）：缺失 bibkey、明显伪造/错误元信息、严重语义错配
• P1（建议处理）：字段不全（缺 DOI/缺 year）、弱支撑/过度主张、需要人工复核
• 附录：逐条引用明细（至少包含 file/line、原句、bib 条目关键字段、风险判断与理由）

• 共同点：脚本只做确定性抽取；“语义是否匹配”的判断由宿主 AI 完成；输出可追溯的结构化输入与报告。
• 不同点：本 skill 面向**标书项目**（多文件 `\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`：确定性报告（缺失 bibkey、重复条目、字段缺失、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 源码。

<!-- End of canonical common constraints. -->

Skill 专属约束

不得超出本 Skill description 和上方流程所声明的范围；不将未验证的信息伪装成确定结论。