Nsfc Qc

NSFC 标书质量控制（nsfc-qc）

目标输出（契约）

• 只读：对标书内容完全只读（不修改任何 .tex/.bib/.cls/.sty）。
• 隔离（推荐）：使用“交付目录 + sidecar 工作区”组织产物，默认不污染标书根目录：
  • 交付目录（面向人读）：{deliver_dir}/
  • 工作区（面向复现/归档）：{deliver_dir}/.nsfc-qc/（包含 runs/snapshot/.parallel_vibe/artifacts/final）
• 兼容（legacy）：仍支持把工作区写入 project_root/.nsfc-qc/（旧用法）。
• 交付物（标准化）：
  • {run_dir}/final/nsfc-qc_report.md
  • {run_dir}/final/nsfc-qc_metrics.json
  • {run_dir}/final/nsfc-qc_findings.json
  • {run_dir}/final/validation.json（结构一致性校验结果）

输入参数（建议显式提供）

最少必须给：

• project_root：如 projects/NSFC_Young

建议同时给：

• main_tex：默认 main.tex
• threads：默认 5
• execution：默认 serial（串联）；用户明确要求并行时才改 parallel
• deliver_dir：推荐提供（例如 .../QC/vYYYYMMDDHHMMSS），用于“实例隔离”

参数默认值见 config.yaml。

硬约束（必须遵守）

• 禁止写入标书源文件：包括但不限于 *.tex/*.bib/*.cls/*.sty。
• 禁止”为了优化而直接改文”：本技能只产出 QC 报告与可执行建议；后续是否修改由人工复核或其它写作类 skill 执行。
• 不编造引用：任何”引用真伪/是否错引”的结论，必须给出证据链（bib 条目、论文题目/DOI、来源链接或检索失败说明）；不确定时标记为”需人工复核（uncertain）”。
• 元数据获取为必选项：文献真实性检查是 QC 的核心功能，必须通过联网获取并比对元数据（title/abstract/URL 可访问性）；预检脚本会自动执行，无需手动启用。

工作流（强制）

0) 定位输入与 run 目录

1. 校验 project_root 存在；main_tex 默认 main.tex。若该文件不存在，应优先在项目根目录自动探测主 tex（优先含 \documentclass / \begin{document} 的根目录文件，避免误选 extraTex/ 子文件）。
2. 生成 run_id = vYYYYMMDDHHMMSS（本地时间），并优先采用“实例隔离”布局：
   • deliver_dir = project_root/QC/{run_id}/（可由用户显式提供）
   • workspace_dir = {deliver_dir}/.nsfc-qc/
   • run_dir = {workspace_dir}/runs/{run_id}/

若用户明确要求 legacy（或不方便创建交付目录），才使用 project_root/.nsfc-qc/runs/{run_id}/。

可选：运行 scripts/nsfc_qc_precheck.py 生成确定性“预检指标”，供多线程 QC 参考。

1) 只读预检（确定性）

目标：先用脚本完成”不会错”的检查，减少 AI 幻觉与漏检。

最小预检清单：

• 引用 key 是否都能在 .bib 中找到（缺失即 P0）
• .bib 条目是否明显不完整（缺 title/author/year 等，或占位符，标 P1）
• 引用真伪/错引的”证据包”（硬编码抓取，必选项）：
  • 对每个被引用的 bibkey，通过 Crossref/arXiv/Unpaywall API 获取论文真实 metadata（title/abstract）
  • 检查 .bib 中 url 字段的可访问性（HTTP HEAD 请求）
  • 自动比对 bib title 与 API title（exact/fuzzy/mismatch）
  • 提取标书内的引用上下文，供后续 AI 做语义判断
  • 并发控制：每批次最多 max_concurrent 个并发请求（默认 5，可在 config.yaml 配置）
• 章节/文件级篇幅分布（字符数/粗略字数）
• 中文排版易错项（确定性）：检测直引号 ”免疫景观” 这类写法，并给出替换建议（推荐 TeX 引号 ``免疫景观''）

产物落点（示例）：

• .../artifacts/precheck.json
• .../artifacts/citations_index.csv
• .../artifacts/tex_lengths.csv
• .../artifacts/quote_issues.csv
• .../artifacts/abbreviation_issues.csv
• .../artifacts/abbreviation_issues_summary.json
• .../artifacts/abbreviation_registry.json
• .../artifacts/abbreviation_render_stream.jsonl
• .../artifacts/terminology_issues.csv
• .../artifacts/terminology_issues_summary.json
• .../artifacts/reference_evidence.jsonl（包含 url_check 和 title_comparison 字段）
• .../artifacts/reference_evidence_summary.json（包含 url_checked/url_accessible/title_match_exact/title_match_fuzzy/title_mismatch 统计）

2) 多线程独立 QC（parallel-vibe；默认 5 threads；默认串联）

你必须使用 parallel-vibe 来“多线程独立 QC”，但为了满足“所有中间文件都在 .nsfc-qc/”的约束：

• parallel-vibe --out-dir {run_dir}/
  • 这样 .parallel_vibe/ 会被创建在 run 内部（无论 legacy 还是 workspace 模式）
• parallel-vibe --src-dir {run_dir}/snapshot/
  • 每个 thread 的 workspace 都是 snapshot 的独立拷贝；snapshot 为“最小化副本”（通常仅 *.tex/*.bib + ./.nsfc-qc/input/ 证据包）

并行策略：

• 默认 serial（串联执行 threads）
• 用户明确要求“并行跑”时才启用 --parallel --max-parallel <k>

Thread 统一任务（每个 thread 做同样的 QC）

每个 thread 的 RESULT.md 必须覆盖同一份检查清单（允许发现点不同），至少包括：

1. 文风与可读性：生硬句、口语/堆砌、AI 味/模板味、冗长句；给”最小改写建议”（只写建议，不改文件）。
2. 引用真伪与错引风险：
   • P0：引用 key 缺失、明显虚构条目（无法检索且 bib 信息异常）、bib URL 不可访问（HTTP 4xx/5xx）
   • P1：可能错引（正文断言与论文题目/摘要方向明显不符）、元信息疑点（年份/期刊/作者异常）、title 不匹配（bib title 与 API title 相似度低）
   • 逐条给出证据锚点：bibkey、所在句子（原文片段 ≤ 50 字）、bib 条目、API 返回的 title/abstract、URL 检查结果、title 比对结果、可核验链接/检索关键词
   • 必须使用预检产物 reference_evidence.jsonl 中的 url_check 和 title_comparison 字段作为判断依据
3. 篇幅与结构分布：
   • 总体是否过短/过长（用字符数与章节分布做近似判断）
   • 各章节比例是否合理（例如：立项依据/研究内容/研究基础的分配是否失衡）
4. 逻辑与论证：论证链是否闭合（科学问题→假说→目标→方法→验证→预期），是否存在跳步、歧义、概念偷换、缺对照/缺指标。
5. 缩略语规范：
   • 读取预检产物 abbreviation_issues.csv / abbreviation_issues_summary.json / abbreviation_registry.json 作为起点
   • 首次出现必须按 abbreviation_render_stream.jsonl 的真实渲染顺序理解，不得自行按文件名/目录顺序重排
   • 对每条 P1 问题（bare_first_use / late_definition / missing_english_full / conflicting_english_full_name / conflicting_chinese_full）做语义判断：
     • 确认是否为真正的”重要专业术语”（领域常识词如 DNA/RNA 可豁免）
     • 确认首次出现位置是否确实缺少”中文全称（English Full Name, ABBR）”格式
     • 若为 late_definition：确认定义是否确实晚于首次出现
     • 若为 conflicting_*：确认全文是否真的存在不同英文全称/中文解释
   • 对 P2 问题（missing_chinese_full / repeated_same_definition）：确认是否确实缺中文全称/是否真的重复同一定义
   • 过滤误报：LaTeX 标签、图表编号、数学变量等不是缩写
   • 输出：按文件/行号定位的可执行建议（只写建议，不改文件）
6. 术语一致性：
   • 读取预检产物 terminology_issues_summary.json/terminology_issues.csv 作为起点
   • 每条 term_variant 问题列出了同一概念的多种英文写法（大小写/连字符差异），逐条判断：
     • 是否为真正的不一致（而非合理变体，如 “T cell” vs “T-cell” 在不同语境下均可接受）
     • 建议统一使用哪种形式（通常选出现次数最多的）
   • 过滤误报：句首大写、专有名词等合理的大小写差异不算不一致
   • 输出：按文件/行号定位的可执行建议（只写建议，不改文件）
7. 其它 QC（至少 2 项）：例如图表/公式编号与引用、风险与备选方案、创新点可验证性、夸大措辞等。

注意：thread 工作区内也禁止修改任何标书源文件；如需记录建议，写在 RESULT.md 或 thread 内新增的 notes/*.md（不改原文件）。

3) 汇总聚合（主线程）

你需要把 5 个 threads 的 RESULT.md 汇总为一份最终 QC 报告，并确保：

• 去重合并：同类问题合并，证据保留最强的 1-2 条
• 冲突处理：如果 threads 结论冲突，报告中明确指出并给出“为何选择/为何不确定”
• 优先级分级：P0（必须修复）/ P1（重要建议）/ P2（可选优化）
• 输出“可执行修改建议清单”：按文件/章节定位 + 建议改法 + 预计收益

4) 输出标准化报告（强制格式）

最终报告写入：

• {run_dir}/final/nsfc-qc_report.md（脚本会生成“底线版”报告骨架 + 确定性 findings）

报告必须包含以下固定章节（标题名保持一致）：

1. 执行摘要
2. 范围与只读声明
3. 硬性问题（P0）
4. 重要建议（P1）
5. 可选优化（P2）
6. 引用核查清单
7. 篇幅与结构分布
8. 建议的最小修改路线图
9. 附录：复现信息（命令/路径/产物索引）

同时输出两份 JSON（用于后续人工复核/自动化处理）：

• nsfc-qc_metrics.json：字符数、章节分布、引用数量、缺失引用数量、预检信号聚合等
• nsfc-qc_findings.json：结构化问题列表（id/severity/location/evidence/recommendation/status）

你可以使用 templates/ 下的模板文件（可选，但推荐）：

• templates/REPORT_TEMPLATE.md
• templates/FINDINGS_SCHEMA.json

5) 非目标：编译检查

nsfc-qc 的定位是“内容质量 QC”（标书写得怎么样）。PDF 能否编译成功属于环境/工程质量，不在本技能范围内；请你在自己的 TeX/Overleaf 环境自行验证。

快捷脚本（可选，但推荐）

若希望可追溯与少出错，推荐优先使用“一键实例隔离”脚本：

0. 一键运行（推荐：交付目录 + sidecar 工作区）

python3 skills/nsfc-qc/scripts/nsfc_qc_run.py \
  --project-root projects/NSFC_Young \
  --main-tex main.tex \
  --deliver-dir projects/NSFC_Young/QC/vYYYYMMDDHHMMSS \
  --threads 5 \
  --execution serial

输出：交付目录内会有 nsfc-qc_report.md/nsfc-qc_metrics.json/nsfc-qc_findings.json/validation.json + artifacts/（选取的确定性证据）。

也支持 legacy/拆分式调用（只写入 project_root/.nsfc-qc/）：

1. 预检（引用/篇幅/章节分布 + 引用证据包）

python3 skills/nsfc-qc/scripts/nsfc_qc_precheck.py \
  --project-root projects/NSFC_Young \
  --main-tex main.tex \
  --out projects/NSFC_Young/.nsfc-qc/runs/vYYYYMMDDHHMMSS/artifacts \
  --resolve-refs

2. 生成 parallel-vibe plan 并运行（默认串联 5 threads）

python3 skills/nsfc-qc/scripts/run_parallel_qc.py \
  --project-root projects/NSFC_Young \
  --run-id vYYYYMMDDHHMMSS \
  --threads 5 \
  --execution serial

3. 生成标准化 final 输出骨架（即使 threads 尚未运行也可执行）

python3 skills/nsfc-qc/scripts/materialize_final_outputs.py \
  --project-root projects/NSFC_Young \
  --run-id vYYYYMMDDHHMMSS

降级策略（必须提供）

若 parallel-vibe 不可用（脚本缺失或 runner CLI 不可用），仍需完成 QC：

• 用单线程完成同一份 QC 清单
• 仍然输出同样的标准化报告与 JSON
• 并在 附录：复现信息 中写明：未启用 parallel-vibe 的原因与环境限制