nsfc-justification-writer by huangwb8

---
name: nsfc-justification-writer
description: 当用户明确要求"写/改 NSFC 立项依据""立项依据写作/重构"时使用。基于最小信息表输出价值与必要性、现状不足、科学问题/假说与项目切入点，并保持模板结构不被破坏。适用于 NSFC 及各类科研基金申请书的立项依据写作场景。
author: Bensz Conan
metadata:
  author: Bensz Conan
  short-description: 科研立项依据写作/重构
  keywords:
    - nsfc-justification-writer
    - 立项依据
    - 科学问题
    - 假说
    - 国内外现状
    - LaTeX
  triggers:
    - nsfc-justification-writer
    - 立项依据
    - 研究意义
    - 为什么要做
    - 国内外现状
    - 现有不足
    - 切入点
references: references/
config: config.yaml
---

# 科研立项依据写作器

## 目标输出（契约）

- **唯一写入落点**：`extraTex/1.1.立项依据.tex`
- **禁止改动**：`main.tex`、`extraTex/@config.tex`、任何 `.cls/.sty`
- **写作目标**：把"为什么要做"讲清楚，并为 `（二）研究内容` 铺垫"科学问题/假说与切入点"。
- **AI 依赖**：默认使用运行环境提供的 Claude Code / Codex 原生智能（无需配置任何外部 API Key，AI 不可用会自动回退到硬编码能力）
- **理论创新导向（默认）**：优先关注科学问题/假说的可证伪性、理论贡献的清晰性、验证维度的完备性（详见 [theoretical_innovation_guidelines.md](references/theoretical_innovation_guidelines.md)）
- **写作导向可配置**：在 `config.yaml` 中用 `style.mode=theoretical|mixed|engineering` 切换（默认 `theoretical`）

## 必需输入（最小信息表）

- 若用户未提供，请先收集/补全：[references/info_form.md](references/info_form.md)
- 科学问题与科学假设的写作要点（用于统一口径与自检）：
  - [scientific_question_guidelines.md](references/scientific_question_guidelines.md)
  - [scientific_hypothesis_guidelines.md](references/scientific_hypothesis_guidelines.md)

> 推荐：用脚本快速生成信息表（并可交互填写），见 `scripts/run.py init`。

## 工作流（按顺序执行）

1. **定位项目与目标文件**：确认 `project_root`，读取并仅编辑 `extraTex/1.1.立项依据.tex`。
2. **抽取现有骨架**：若文件已有 `\subsubsection` 等小标题，优先保留骨架，仅替换正文段落（除非用户要求重构层级）。默认不强制标题精确匹配（`strict_title_match=false`），更关注“内容维度是否覆盖”。
3. **渐进式写作引导（主推）**：先骨架→再段落→再修订→再润色→再验收（避免一步到位压力）
   - 使用 `scripts/run.py coach --stage auto` 自动判断当前阶段并给出“本轮只做三件事 + 需要你补充的问题 + 可复制提示词”
   - 每轮只改一个 `\subsubsection` 的正文，配合 `apply-section` 安全写入并自动备份
4. **生成“立项依据”主叙事**（建议 4 段闭环，AI 会检查内容维度覆盖而非死盯标题）：
   - 价值与必要性：痛点→影响范围/成本→为何现在必须做。
   - 现状与不足：主流路线/代表性工作→2–4 个明确不足（尽量可量化/可验证）。
   - 科学问题/科学假设：1–3 个科学问题（疑问句，非研究目标，约束与瓶颈一一映射）+ 1 句科学假设（陈述句，预测性结果，不写验证方式；覆盖关键约束并给出应对策略）。
   - 本项目切入点与贡献：本项目相对现有工作的“差异化切口”，并用 1 句过渡到研究内容。
5. **可核验性与引用守护**：
   - AI 语义识别“可能引起评审不适的表述”（绝对化/填补空白/无依据夸大/自我定性），并给出改写建议；硬编码高风险词仅作提示，不做机械阻断。
   - 不写“国际领先/国内首次”等不可证明表述；需要对外部工作举证时，先让用户提供 DOI/链接（或可核验题录信息），补齐 `references/*.bib` 后再写 `\cite{...}`。
6. **跨章节一致性检查**：检查术语/缩写/指标口径是否能与 `2.1 研究内容` 对齐；必要时列出需用户确认的 3–5 个关键名词与指标。
7. **目标字数解析**：优先解析用户意图/信息表中的“字数”/“±范围”/区间描述；无显式指示时再使用配置兜底。
8. **第三方约束预警（瘦身提质）**：在 `diagnose/review/coach` 输出中提示：
   - 立项依据建议 **6-10 页**（推荐 **6-8 页**，仅做经验估算预警）
   - 建议 **8000-10000** 中文字符（与页数联动的兜底区间）
   - 建议 **30-50** 篇核心文献（按去重 `\cite{}` keys 统计，避免凑数堆砌）
   - 开篇约 **300 字** 尽量直击核心（卡点/局限 → 为什么难 → 本项目突破式切入；启发式检查）

## 配置校验与大文件支持（可选）

- 配置校验：`python scripts/run.py validate-config`
- 大文件 Tier2：`diagnose/review --tier2 --chunk-size 12000 --max-chunks 20`（支持 `tests/_artifacts/cache/ai` 缓存；超大文件会优先使用流式分块以降低峰值内存；用 `--fresh` 强制重算）
- 说明：本仓库脚本层不会“默认直连外部大模型”；AI 能力是否可用取决于运行环境是否注入 responder（不可用会自动回退到硬编码能力）
- 相关设计说明：
  - 内容维度覆盖检查：`references/dimension_coverage_design.md`
  - "可能引起评审不适的表述"判别与改写：`references/boastful_expression_guidelines.md`
  - **理论创新导向写作指南**：`references/theoretical_innovation_guidelines.md`（含方法学术语误用警示）
  - **方法学术语误用对比示例**：`references/methodology_term_examples.md`

## Prompt 模板可配置化（可选）

`config.yaml` / `preset.yaml` / `override.yaml` 的 `prompts.*` 支持两种形式：

- **文件路径**：如 `assets/prompts/tier2_diagnostic.txt`（兼容旧路径 `prompts/`）
- **直接写多行 Prompt**：在 YAML 中用 `|` 写入多行文本（适合不同领域改侧重点）

也支持按 preset 变体覆盖：例如当 `--preset medical` 时，可提供 `prompts.tier2_diagnostic_medical`。

## 推荐 `\\subsubsection` 标题与内容映射

说明：模板与 `config.yaml` 默认推荐 4 个 `\\subsubsection` 标题（`structure.recommended_subsubsections`），而“4 段闭环”是内容叙事逻辑。为避免用户困惑，推荐按下表映射写作：

| `\\subsubsection` 标题 | 对应叙事段落 | 核心写作要素（理论创新导向默认） |
|---|---|---|
| 研究背景 | 价值与必要性 | 理论空白/认知缺失→为何现在必须做（理论驱动） |
| 国内外研究现状 | 现状与不足 | 主流路线→**理论局限性**（假设过强/框架不统一/因果缺失/界不紧） |
| 现有研究的局限性 | 科学问题/科学假设 | 关键瓶颈→科学问题（疑问句，约束映射）→科学假设（陈述句，预测性结果）→验证维度（理论证明/定理/数值验证） |
| 研究切入点 | 本项目切入点与贡献 | **理论差异化切口**（新表征/方法学/统一框架）→承上启下到 2.1 研究内容 |

如用户确需改小标题：建议仍保持 4 段结构，并先统一标题骨架（见 `assets/templates/structure_template.tex`）；结构检查不再机械匹配标题，但仍要求至少 4 个小节。

## 关键能力

用于“先诊断→再生成→再安全写入→再验收”的闭环：

### AI 功能清单（可选增强）

| 功能 | 是否需要 AI | Fallback 行为 |
|------|-----------|--------------|
| Tier1 诊断（结构/引用/字数/高风险示例/危险命令） | ❌ | N/A |
| 内容维度覆盖检查 | ✅ | 启发式关键词检测（兜底） |
| 吹牛式表述识别（语义） | ✅ | 不阻断；仅依赖 Tier1 高风险示例提示 |
| 术语一致性（语义） | ✅ | 仅输出硬编码矩阵（`terminology.dimensions`） |
| AI 示例推荐（带理由） | ✅ | 关键词/类别启发式匹配 |
| AI 阶段判断（coach --stage auto） | ✅ | 硬编码阈值规则 |
| Tier2 深度诊断（diagnose --tier2） | ✅ | 跳过（仅输出 Tier1） |

> AI 是否可用取决于运行环境是否注入 responder；可用 `scripts/run.py check-ai` 自检。

- **Tier1 硬编码诊断**：结构（≥4 个 `\subsubsection`）/引用键是否存在于 `.bib`/DOI 缺失与格式异常提示/字数统计/高风险表述提示与危险命令扫描
- **第三方约束预警（硬编码）**：预估页数（经验估算）/核心文献数量（去重 cite keys）/开篇 300 字“卡点+突破”信号检查（启发式，默认不阻断写入）
- **内容维度覆盖检查（AI）**：不依赖标题用词，检查“价值与必要性/现状与不足/科学问题/切入点”是否被覆盖
- **吹牛式表述识别（AI）**：识别绝对化/填补空白式/无依据夸大/自我定性，输出改写建议
- **跨章节一致性矩阵**：基于 `config.yaml` 的 `terminology.dimensions`（研究对象/指标/术语）做跨章节一致性提示
- **AI 术语一致性（可选）**：当 AI 可用且 `terminology.mode=auto/ai` 时，额外给出语义视角的“同义词/缩写混用”检查与修改建议（不可用则仅输出矩阵）
- **安全写入工具**：按 `\subsubsection{...}` 精确定位并替换正文，写入白名单文件 + 备份（产物放在 `tests/_artifacts/runs/`，由 `config.yaml:workspace.runs_dir` 控制）
- **写入前质量闸门（可选）**：`apply-section --strict-quality` 仅对“本次新增正文”做高风险词/危险命令扫描；若 AI 可用则叠加“吹牛式表述”语义阻断，避免被历史遗留内容卡死
- **评审建议生成器**：基于 DoD + 诊断结果输出“评审人会问什么 + 怎么改”（`scripts/run.py review`）
- **可视化 HTML 诊断报告**：快速定位问题（`scripts/run.py diagnose --html-report auto`）
- **版本 diff/回滚**：基于 runs 备份做差异查看与一键回滚（`scripts/run.py diff/rollback`）
- **示例推荐**：从 `assets/examples/` 读取 `*.metadata.yaml` 关键词，辅助按主题匹配参考骨架（`scripts/run.py coach --topic ...` / `scripts/run.py examples`）
- **AI 示例推荐（可选）**：当 AI 可用时，优先进行语义匹配并给出“推荐理由”（不可用则回退到关键词/类别启发式）
- **AI 阶段判断（可选）**：coach 在 `--stage auto` 时，可用 AI 综合字数/结构/质量状态推断“skeleton/draft/revise/polish/final”，AI 不可用时回退到硬编码阈值
- **配置覆盖与预设**：支持 `--preset medical/engineering` 与 `~/.config/nsfc-justification-writer/override.yaml` 覆盖术语维度等参数（需要时可用 `--no-user-override` 关闭）

脚本入口：`scripts/run.py`（用法见 `scripts/README.md`）。

## systematic-literature-review 集成（可选）

本技能支持只读访问 `systematic-literature-review` 生成的文献综述目录，便于引用已有的研究现状内容。

### 识别标准

目录满足以下任一条件时，自动识别为 systematic-literature-review 生成的目录：
1. 存在隐藏文件夹 `.systematic-literature-review`，且包含 `{主题}_review.tex` 和 `{主题}_参考文献.bib`/`references.bib` 文件（运行中的 pipeline）
2. 存在典型的文件组合：`{主题}_review.tex` + `{主题}_参考文献.bib`/`references.bib` + `{主题}_工作条件.md`（已完成的输出目录）
3. 存在同名的 `{主题}_review.tex` 和 `{主题}_参考文献.bib` 文件（基于文件名前缀匹配）

### 只读访问约束

对 systematic-literature-review 生成的目录：
- **只读模式**：仅读取 `.tex` 和 `.bib` 文件内容
- **禁止写入**：不会修改目录中的任何文件
- **引用验证**：自动验证 `.tex` 中的引用与 `.bib` 中的定义是否一致

### 使用场景

- 用户要求引用已有的文献综述内容
- 需要从系统综述中提取研究现状信息
- 想要确保引用的一致性

### 核心功能

- 目录检测：`detect_slr_directory(path)` 判断是否为 systematic-literature-review 目录
- 目录分析：`analyze_review_directory(path)` 返回目录结构信息
- 引用验证：`validate_citation_consistency(tex_path, bib_path)` 检查引用一致性
- 内容提取：从 `.tex` 和 `.bib` 文件中提取关键信息

实现见：`scripts/core/review_integration.py`

## 验收标准（Definition of Done）

- 见：[references/dod_checklist.md](references/dod_checklist.md)

## 变更记录

- 本技能不在本文档内维护变更历史；变更记录见：
  - 技能级：`skills/nsfc-justification-writer/CHANGELOG.md`
  - 项目级（强制同步）：仓库根目录 `CHANGELOG.md`
- 版本号以 `config.yaml`（`skill_info.version`）为唯一真相来源，避免口径分散。