nsfc-ref-alignment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NSFC Ref Alignment

与 bensz-collect-bugs 的协作约定

Collaboration Agreement with bensz-collect-bugs

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

When a bug caused by the design flaw of this skill occurs in the user's environment, prioritize using
```
bensz-collect-bugs
```
to record it in
```
~/.bensz-skills/bugs/
```
according to specifications. It is strictly forbidden to directly modify the source code of the skill installed in the user's local Claude Code / Codex.
If the AI can still complete the user's task through a workaround, it should first record the bug, then continue to complete the current task.
When the user explicitly requests actions such as "report bensz skills bugs", call the local
```
gh
```
and
```
bensz-collect-bugs
```
to upload only new bugs to
```
huangwb8/bensz-bugs
```
; do not pull / clone the entire bug repository.

适用场景

Applicable Scenarios

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

You have an NSFC proposal (LaTeX project) and want to check:
- Whether all bibkeys cited in
```
.tex
```
  files via
```
\cite{...}
```
  /
```
\citep{...}
```
  /
```
\citet{...}
```
  etc. exist in
```
.bib
```
  files
- Whether the basic fields of
```
.bib
```
  entries are complete and the format is obviously incorrect (such as invalid DOI, missing year)
- Whether the "semantic claim" of the sentence where the citation is located matches the literature (at least from metadata such as title/author/year/venue/DOI), and whether there are risks of incorrect citation/overclaiming/misattribution
You want to only get a report for manual review first (modifying
```
.bib
```
/ revising the text is a major matter).

不适用

Inapplicable Scenarios

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

You want to "automatically replace bibkeys / automatically rewrite the text" — this skill prohibits direct modification by default (unless you explicitly request it).
You just want to complete BibTeX entries: prioritize using
```
nsfc-bib-manager
```
.

输入

Input

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

```
project_root
```
: Root directory of the proposal project (e.g.,
```
projects/NSFC_General
```
)
Optional:
```
main_tex
```
: Main entry tex file (default
```
main.tex
```
)
Optional:
```
report_dir
```
: Report output directory (default
```
./references
```
, relative to the current directory where you run the skill)
Optional:
```
verify_online
```
: Whether to perform online verification (default false; only deterministic queries are performed, and it degrades on failure)

输出（只读 + 可复现）

Output (Read-only + Reproducible)

中间产物（强制）

Intermediate Products (Mandatory)

所有中间文件必须托管在：

{project_root}/.nsfc-ref-alignment/run_{YYYYMMDDHHMMSS}/

其中

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 清单（被引用条目与问题标注）

All intermediate files must be hosted in:

{project_root}/.nsfc-ref-alignment/run_{YYYYMMDDHHMMSS}/

Where

run_{YYYYMMDDHHMMSS}

is a timestamp; if the skill is run repeatedly in the same second, the script will append

-2/-3/...

to ensure multiple analyses do not conflict.

This directory must contain at least:

```
ai_ref_alignment_input.json
```
: Structured input (citation location + sentence context + literature metadata + verification results) for the host AI to make semantic judgments
```
ref_integrity_report.md
```
: Deterministic report (missing bibkey, duplicate entries, missing fields, DOI format issues, etc.)
```
citations.csv
```
: Itemized citation list (file/line/bibkey/sentence)
```
bib_inventory.json
```
: BibTeX inventory (cited entries and issue annotations)

最终交付（默认）

Final Delivery (Default)

仅输出一份供用户审核的报告（默认写入

./references/

；用户可指定其他目录）：

```
NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md
```
（如同秒重复运行，脚本会追加
```
-2/-3/...
```
避免覆盖）

该报告必须是“只读审查报告”，不得直接修改标书正文或

.bib

。

Only output a report for user review (default written to

./references/

; users can specify other directories):

```
NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md
```
(if run repeatedly in the same second, the script will append
```
-2/-3/...
```
to avoid overwriting)

This report must be a "read-only review report" and must not directly modify the proposal text or

.bib

files.

工作流（推荐）

Workflow (Recommended)

步骤 1：预检与定位

Step 1: Pre-check and Localization

确认
```
project_root
```
存在且包含
```
main_tex
```
。
自动解析
```
main_tex
```
的
```
\input{}
```
/
```
\include{}
```
依赖树，收集所有涉及的
```
.tex
```
文件。
自动发现
```
\bibliography{...}
```
/
```
\addbibresource{...}
```
指向的
```
.bib
```
文件；若发现 0 个
```
.bib
```
，则回退为在
```
project_root
```
下搜索
```
*.bib
```
并给出 warning。

Confirm that
```
project_root
```
exists and contains
```
main_tex
```
.
Automatically parse the
```
\input{}
```
/
```
\include{}
```
dependency tree of
```
main_tex
```
and collect all involved
```
.tex
```
files.
Automatically discover
```
.bib
```
files pointed to by
```
\bibliography{...}
```
/
```
\addbibresource{...}
```
; if 0
```
.bib
```
files are found, fall back to searching for
```
*.bib
```
under
```
project_root
```
and issue a warning.

步骤 2：确定性抽取（脚本执行）

Step 2: Deterministic Extraction (Script Execution)

运行脚本生成结构化输入与确定性报告：

bash

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

如需在线核验（建议只对最终稿/重点条目开启）：

bash

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

Run the script to generate structured input and deterministic reports:

bash

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

For online verification (recommended only for final drafts/key entries):

bash

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 的核心）

Step 3: Host AI Semantic Verification (Core of This Skill)

宿主 AI 在读取

{run_dir}/ai_ref_alignment_input.json

后，逐条核查：

真实性/存在性（P0）
- bibkey 缺失：正文引用了不存在的条目
- DOI/URL 明显无效或在线核验失败且元信息严重不一致
语义不匹配风险（P0/P1）
- P0：句子对文献作出了“强断言”，但从元信息看高度不可能（如年份矛盾、领域完全不相关、明显张冠李戴）
- P1：可疑但证据不足（元信息不足、缺少 DOI/缺少 title/作者信息不全）
过度主张/弱支撑（P1）
- 例如“首次/唯一/最优/显著优于”但缺乏足够支撑或疑似需要更强引用

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

After reading

{run_dir}/ai_ref_alignment_input.json

, the host AI verifies item-by-item:

Authenticity/Existence (P0)
- Missing bibkey: The text cites a non-existent entry
- DOI/URL is obviously invalid or online verification fails with severely inconsistent metadata
Semantic Mismatch Risk (P0/P1)
- P0: The sentence makes a "strong assertion" about the literature, but it is highly unlikely based on metadata (e.g., year contradiction, completely unrelated field, obvious misattribution)
- P1: Suspicious but insufficient evidence (insufficient metadata, missing DOI/missing title/incomplete author information)
Overclaiming/Weak Support (P1)
- For example, "first/only/best/significantly better than" but lacks sufficient support or seems to require stronger citations

Evidence Priority (Mandatory): Online verification results (if enabled) > BibTeX title/abstract > Inference only from sentences (lowest priority).

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

Step 4: Generate Final Report (Read-only)

在

report_dir

写入最终报告

NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md

，必须包含：

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

Write the final report

NSFC-REF-ALIGNMENT-vYYYYMMDDHHMMSS.md

report_dir

, which must include:

Summary: Total number of citations, number of unique bibkeys, number of missing entries, number of duplicate entries, number of P0/P1 issues
P0 (Must be handled): Missing bibkey, obviously forged/incorrect metadata, serious semantic mismatch
P1 (Recommended to be handled): Incomplete fields (missing DOI/missing year), weak support/overclaiming, need manual review
Appendix: Itemized citation details (at least including file/line, original sentence, key fields of the bib entry, risk judgment and reasons)

修改边界（强制）

Modification Boundaries (Mandatory)

默认不修改任何标书内容与配置：
- 禁止修改：
```
**/*.tex
```
  、
```
**/*.bib
```
  、
```
**/*.cls
```
  、
```
**/*.sty
```
允许写入：
- ```
{project_root}/.nsfc-ref-alignment/**
```
  （中间产物）
- ```
./references/**
```
  （最终报告；可由用户改到别处）
若用户明确要求“修复引用/修复 bib”，必须先在报告里给出修改计划与影响面，再执行最小化修改（默认不做）。

By default, do not modify any proposal content or configuration:
- Prohibited modifications:
```
**/*.tex
```
  ,
```
**/*.bib
```
  ,
```
**/*.cls
```
  ,
```
**/*.sty
```
Allowed writes:
- ```
{project_root}/.nsfc-ref-alignment/**
```
  (intermediate products)
- ```
./references/**
```
  (final report; can be changed to other locations by the user)
If the user explicitly requests "fix citations/fix bib", a modification plan and impact scope must be provided in the report first, then minimal modifications are performed (not done by default).

与 check-review-alignment 的关系（经验复用）

Relationship with check-review-alignment (Experience Reuse)

共同点：脚本只做确定性抽取；“语义是否匹配”的判断由宿主 AI 完成；输出可追溯的结构化输入与报告。
不同点：本 skill 面向标书项目（多文件
```
\input{}
```
结构），且默认不做任何自动改写（只输出审查报告）。

Common points: The script only performs deterministic extraction; the judgment of "whether semantics match" is completed by the host AI; outputs traceable structured input and reports.
Differences: This skill targets proposal projects (multi-file
```
\input{}
```
structure) and defaults to no automatic rewriting (only outputs review reports).

验证清单（静态自检）

Verification Checklist (Static Self-check)

```
{project_root}/.nsfc-ref-alignment/run_{timestamp}/
```
存在且包含 4 个核心产物（json/md/csv/json）。
最终报告写入
```
report_dir
```
，且没有任何
```
.tex/.bib
```
文件被修改。
报告对每个 P0/P1 给出：定位（file/line）+ 原句 + 依据 + 建议动作。

```
{project_root}/.nsfc-ref-alignment/run_{timestamp}/
```
exists and contains 4 core products (json/md/csv/json).
The final report is written to
```
report_dir
```
, and no
```
.tex/.bib
```
files are modified.
The report provides for each P0/P1 issue: location (file/line) + original sentence + basis + recommended action.