Nsfc Justification Writer

category: biology
keywords:
  - 生物学
  - 组学
  - 单细胞
  - 通路
  - 因果验证
  - 外部验证
difficulty: starter
word_count: 150
structure_version: nsfc2026
description: 生物学方向：机制/通路研究的立项依据结构骨架示例（引用需自行核验后替换）

% 示例（生物）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）围绕某疾病机制/关键通路，先用“临床或生物学重大问题→现有证据不足→迫切需要可验证的新机制/新靶点”说明必要性。

\subsubsection{国内外研究现状}
\indent
（示例）按主流技术路线（组学测量/模型系统/因果验证）分 2–3 类概括，强调代表性结论与证据类型；引用需先核验再写 \cite{...}。

\subsubsection{现有研究的局限性}
\indent
（示例）用 2–4 条可验证不足收束：例如样本异质性导致结论不稳、因果链条缺关键节点验证、跨尺度整合不足、可重复性与外部验证缺失等。

\subsubsection{研究切入点}
\indent
（示例）用“差异化切口（因果验证 + 外部验证 + 可复现实验方案）+ 量化指标 + 过渡到研究内容”结束。

category: chemistry
keywords:
  - 化学
  - 催化
  - 反应选择性
  - 机理
  - 动力学
  - 稳定性
difficulty: starter
word_count: 140
structure_version: nsfc2026
description: 化学方向：反应/催化立项依据的结构与语气骨架示例（引用需自行核验后替换）

% 示例（化学）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）围绕某关键反应/催化体系，先说明“应用需求→性能瓶颈→现有路线难以兼顾”的必要性与紧迫性。

\subsubsection{国内外研究现状}
\indent
（示例）按主流路线（催化剂设计/反应条件/机理解析）分 2–3 类概括，避免堆砌作者年份；确需引用时先核验 DOI/链接再写 \cite{...}。

\subsubsection{现有研究的局限性}
\indent
（示例）用 2–4 条可量化不足收束：例如活性-选择性权衡、稳定性衰减、放大可重复性不足、机理证据链不闭合等。

\subsubsection{研究切入点}
\indent
（示例）用“差异化切口（结构-性能-机理一体化）+ 可验证指标 + 过渡到研究内容”结束。

category: cs
keywords:
  - 隐私
  - 联邦学习
  - 差分隐私
  - 大模型
  - 推理
  - 可审计
  - 威胁模型
difficulty: intermediate
word_count: 620
structure_version: nsfc2026
description: 计算机/信息方向：隐私保护与系统落地的立项依据示例（不含可直接引用条目）

% 示例（计算机）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）面向真实业务系统的安全与隐私需求，数据共享受限导致模型难以获得足够多样的分布；同时在线推理与运维约束（时延、成本、可审计）使得“只追求离线精度”的方案难以落地。

\subsubsection{国内外研究现状}
\indent
（示例）现有工作主要集中在三类：其一，隐私保护学习（如联邦学习/差分隐私）缓解数据孤岛；其二，大模型与知识增强提升泛化；其三，系统侧的训练/推理优化提升效率与可用性。上述路线在跨域迁移、端侧约束与可审计性方面仍存在明显差距。

\subsubsection{现有研究的局限性}
\indent
（示例）现有方案往往在“隐私-性能-效率”三者间难以兼顾：隐私增强带来性能衰减，系统优化依赖特定硬件/框架，且缺乏面向真实故障与攻击面的稳健性评估。由此需要提出一个可证伪假说：在明确威胁模型与资源约束下，通过“算法-系统-评估”一体化设计，可在给定指标上实现可量化改进。

\subsubsection{研究切入点}
\indent
（示例）本项目拟从可审计的威胁模型出发，构建可复现基准与评测协议，提出面向资源约束的训练/推理协同方法，并以端到端指标（隐私预算、精度、时延/成本、稳健性）验证有效性，最后自然过渡到后续“研究内容与技术路线”。

category: engineering
keywords:
  - 算法工程化
  - 系统部署
  - 边缘计算
  - 时延
  - 吞吐
  - 鲁棒性
  - 资源约束
difficulty: starter
word_count: 120
structure_version: nsfc2026
description: 工程/系统场景：结构与语气骨架示例（强调可复现对比维度）

% 示例（工程）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）从应用需求/系统约束出发，明确任务边界、关键指标与工程代价。

\subsubsection{国内外研究现状}
\indent
（示例）按“传统方法/学习方法/系统方法”分层；强调评审可复现的对比维度（数据、指标、算力、部署）。

\subsubsection{现有研究的局限性}
\indent
（示例）聚焦 2–4 条瓶颈：端到端误差来源、鲁棒性、时延/吞吐、跨域迁移等。

\subsubsection{研究切入点}
\indent
（示例）写清“拟解决什么 + 怎么验证 + 产出什么”，并自然引出后续研究内容。

category: materials
keywords:
  - 电池
  - 催化
  - 表界面
  - 缺陷工程
  - 原位表征
  - 相变
  - 循环寿命
difficulty: intermediate
word_count: 640
structure_version: nsfc2026
description: 材料方向：结构-界面-性能闭环的立项依据示例（强调可验证对照与指标）

% 示例（材料）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）面向高能量密度与长寿命储能器件的需求，关键材料体系在循环稳定性与界面失效方面仍是瓶颈；现有工艺在成本、可规模化与一致性方面也存在约束，因此亟需在材料设计与机理表征上形成可验证的改进路径。

\subsubsection{国内外研究现状}
\indent
（示例）国内外研究主要围绕：成分/结构调控提升本征性能，表界面工程改善副反应，原位/多尺度表征解析失效机理，以及计算辅助筛选加速材料发现。尽管进展显著，但在“结构-界面-性能”因果链的可验证性、复杂工况下的可重复性与可放大工艺方面仍存在不足。

\subsubsection{现有研究的局限性}
\indent
（示例）现有工作常见局限包括：对缺陷/相变的动态演化缺少定量表征，对界面副反应与传质耦合的机制认识不足，样品制备差异导致结果可比性不强。基于此，本项目提出可证伪假说：通过可控缺陷工程与界面调控的协同设计，并配套统一的表征与评价协议，可在关键性能指标上获得可量化提升。

\subsubsection{研究切入点}
\indent
（示例）本项目将以“可控结构单元 + 可追踪界面过程”为切入点，构建材料设计-制备-表征-性能验证闭环，明确对照组与评价指标（容量保持率/倍率/循环寿命/一致性等），并以可交付的材料配方与评价基准支撑后续研究内容展开。

category: math
keywords:
  - 数学
  - 优化
  - 收敛
  - 复杂度
  - 数值方法
  - 误差界
difficulty: starter
word_count: 150
structure_version: nsfc2026
description: 数学/优化方向：理论与方法并重的立项依据结构骨架示例（引用需自行核验后替换）

% 示例（数学/优化）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）围绕某类优化/方程问题，先说明“应用或理论驱动→现有理论无法覆盖关键情形→需要新的可证明结果/可计算方法”的必要性。

\subsubsection{国内外研究现状}
\indent
（示例）按主流路线（理论收敛/复杂度分析/数值算法）分 2–3 类概括，强调核心假设与结论边界；确需引用时先核验再写 \cite{...}。

\subsubsection{现有研究的局限性}
\indent
（示例）用 2–4 条可验证不足收束：例如依赖过强假设、缺少统一框架、最坏情形界不紧、数值稳定性与误差控制不足等。

\subsubsection{研究切入点}
\indent
（示例）用“差异化切口（可证明性 + 可计算性）+ 可验收指标（定理/界/算法）+ 过渡到研究内容”结束。

category: medical
keywords:
  - 深度学习
  - 医学影像
  - 临床决策
  - 真实世界
  - 队列
  - 泛化
  - 可解释性
difficulty: starter
word_count: 120
structure_version: nsfc2026
description: 医学/临床场景：结构与语气骨架示例（引用需自行核验后替换）

% 示例（医学）：仅供结构与措辞参考

\subsubsection{研究背景}
\justifying\indent
（示例）围绕某临床决策场景，先用“疾病负担/诊疗痛点/现有路径不足”说明必要性与紧迫性。

\subsubsection{国内外研究现状}
\indent
（示例）按主流路线分 2–3 类描述，避免堆砌作者年份；确需引用时先核验 DOI/链接再写 \cite{...}。

\subsubsection{现有研究的局限性}
\indent
（示例）用 2–4 条可量化不足收束：例如泛化差、标注成本、可解释性不足、真实世界落地受限等。

\subsubsection{研究切入点}
\indent
（示例）用“差异化切口 + 可验证指标 + 过渡到研究内容”结束。

terminology:
  dimensions:
    研究对象:
      系统/平台: ["系统", "平台", "框架", "架构", "pipeline"]
      数据集: ["数据集", "数据", "dataset", "benchmark"]
      基线方法: ["基线", "baseline", "对照方法", "对照组"]
    指标:
      时延: ["时延", "延迟", "latency", "响应时间"]
      吞吐: ["吞吐", "吞吐量", "throughput", "QPS", "TPS"]
      资源约束: ["算力", "计算预算", "资源约束", "compute budget", "显存", "内存"]
      能耗: ["能耗", "功耗", "energy", "power"]
      鲁棒性: ["鲁棒性", "robustness", "稳定性"]
    术语:
      消融: ["消融", "ablation", "消融实验"]
      泛化: ["泛化", "generalization", "泛化能力"]
      可扩展性: ["可扩展性", "scalability", "扩展性"]

terminology:
  dimensions:
    研究对象:
      研究对象: ["患者", "病例", "受试者", "队列", "样本", "就诊者", "入组者"]
      纳排标准: ["纳入标准", "入组标准", "排除标准", "纳排标准"]
      对照组: ["对照组", "对照", "对照人群", "对照队列"]
      干预: ["干预", "治疗", "处理", "用药", "术式"]
    指标:
      结局指标: ["结局", "终点", "主要终点", "次要终点", "预后", "预后结局"]
      诊断性能: ["敏感度", "特异度", "准确率", "精确度", "召回率", "precision", "recall"]
      AUC: ["AUC", "ROC-AUC", "auc"]
      风险分层: ["风险分层", "风险评分", "风险评估", "分层"]
    术语:
      回顾性: ["回顾性", "回顾性研究"]
      前瞻性: ["前瞻性", "前瞻性研究"]
      随机对照: ["随机对照", "随机", "RCT", "randomized controlled trial"]

你是 NSFC 立项依据的“评审人视角质疑生成器”。

输入：
- dod_checklist: 验收清单（要点）
- tier1: 硬编码诊断结果（结构/引用/字数/不可核验表述）
- tex: 立项依据正文（可截断）

任务：输出 markdown（不要写 LaTeX），包含两部分：
1) 评审人可能会问的 8-12 个问题（每条可直接用于修改）
2) 对应的 8-12 条可执行修改建议（尽量给到“改哪里/怎么改/验证标准”）

约束：
- {style_preamble}
- 不要杜撰引用与 DOI；如需要引用，用“需用户提供 DOI/链接（或可核验题录信息），并先补齐 references/*.bib”
- 避免绝对化表述（国际领先/国内首次等）
- 关注“瓶颈→科学问题约束→科学假设→研究切入点”的逻辑闭环：是否存在漏配/凭空新增/自相矛盾

dod_checklist:
{dod_checklist}

tier1(json):
{tier1_json}

tex:
{tex}

你是 NSFC 立项依据“语义诊断器”。请基于以下 LaTeX 文本，输出诊断要点（JSON）：

字段：
- logic: 逻辑连贯性问题（列表）
- terminology: 术语/缩写不一致问题（列表）
- evidence: 证据不足/不可量化陈述（列表）
- suggestions: 3-6 条可执行修改建议（列表）

要求：
- 只输出 JSON
- 不生成新的引用；若需要引用，请提示“需用户提供 DOI/链接（或可核验题录信息），并先补齐 references/*.bib”
- 重点关注“瓶颈/局限性 → 科学问题约束（疑问句） → 科学假设（陈述句） → 切入点 → 研究内容”的闭环是否存在：漏配、凭空新增约束、把研究目标当科学问题、把验证方式写进假设

LaTeX 文本：
{tex}

你是 NSFC 立项依据的"渐进式写作教练"。

目标：帮助用户用最小压力完成 1.1 立项依据，从"骨架 → 段落 → 逻辑闭环 → 润色 → 验收"逐步推进。

{style_preamble}

输入：
- stage: skeleton|draft|revise|polish|final（或 auto）
- info_form: 用户已提供的信息（可能不完整）
- tier1: 结构/引用/字数/质量硬编码诊断
- term_matrix: 跨章节术语一致性矩阵（可为空）
- tex: 当前立项依据（可为空）

输出：markdown，格式固定为：
## 当前阶段判断
一句话说明当前处于哪个阶段以及原因。

## 本轮只做三件事
1) ...
2) ...
3) ...

## 需要你补充/确认的问题（不超过 8 个）
- ...

## 下一步可直接复制的写作提示词
给出 1 段可复制的提示词，用于让写作助手生成/修改某个 \\subsubsection 的正文（必须强调：不新增引用/引用先核验）。

约束：
- 永远先保证结构不被破坏
- 永远优先可核验性与术语一致性
- 遵循"写作导向"要求，并把要求落到可验证锚点/对照维度
- 科学问题必须是“疑问句”（追问认知缺口），避免写成“能否构建/开发/实现...”的研究目标
- 科学假设必须是“陈述句”（预测性结果），避免写“在...验证中/通过...验证”等验证方式

方法学术语使用规范（重要）：
- 立项依据的核心驱动力是"科学问题与假说"，方法学术语仅作为验证手段的背景说明
- 禁止用方法术语撑段落主线：每段主句的主语应为"科学问题/假说/理论空白"而非"方法/技术/平台"
- 方法术语的合理位置：
  - ✅ 在"现状与不足"中简述主流方法路线（为指出理论局限性做铺垫）
  - ✅ 在"验证方式"中提及验证手段（理论证明/数值验证/对照实验）
  - ❌ 不作为段落主句的主语
- 检查方法：每段主句的主语/核心驱动力是否为"科学问题/假说/理论空白"而非"方法/技术/平台"

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>$title</title>
    <style>
      :root {
        --bg: #0b1020;
        --panel: #111936;
        --text: #e7ecff;
        --muted: #a7b1d6;
        --ok: #5eead4;
        --warn: #fbbf24;
        --bad: #fb7185;
        --codebg: #0a0f22;
        --line: rgba(255, 255, 255, 0.08);
        --hl: rgba(251, 191, 36, 0.22);
        --hlbad: rgba(251, 113, 133, 0.26);
      }
      body {
        margin: 0;
        font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "PingFang SC",
          "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
        background: radial-gradient(1200px 700px at 10% 0%, rgba(94, 234, 212, 0.12), transparent),
          radial-gradient(1200px 700px at 90% 20%, rgba(251, 191, 36, 0.10), transparent), var(--bg);
        color: var(--text);
        line-height: 1.5;
      }
      a { color: inherit; text-decoration: none; }
      .wrap { max-width: 1080px; margin: 0 auto; padding: 18px 16px 36px; }
      .top { display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
      h1 { margin: 0; font-size: 20px; letter-spacing: 0.3px; }
      .meta { color: var(--muted); font-size: 12px; }
      .grid { display: grid; grid-template-columns: 1fr; gap: 12px; margin-top: 12px; }
      @media (min-width: 980px) { .grid { grid-template-columns: 1fr 1fr; } }
      .card {
        background: linear-gradient(180deg, rgba(255,255,255,0.06), rgba(255,255,255,0.02));
        border: 1px solid rgba(255,255,255,0.10);
        border-radius: 12px;
        padding: 12px 12px 10px;
        backdrop-filter: blur(8px);
      }
      .card h2 { margin: 0 0 8px; font-size: 14px; color: #d8deff; }
      .kvs { display: grid; grid-template-columns: 1fr; gap: 6px; }
      .kv { display: flex; gap: 8px; align-items: baseline; }
      .k { color: var(--muted); font-size: 12px; min-width: 120px; }
      .v { font-size: 13px; }
      .ok { color: var(--ok); }
      .warn { color: var(--warn); }
      .bad { color: var(--bad); }
      .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; }
      .code {
        background: var(--codebg);
        border: 1px solid rgba(255,255,255,0.10);
        border-radius: 12px;
        overflow: hidden;
      }
      .codehdr {
        display: flex; justify-content: space-between; align-items: center;
        padding: 10px 12px;
        background: rgba(255,255,255,0.04);
        border-bottom: 1px solid var(--line);
        color: var(--muted);
        font-size: 12px;
      }
      .actions { display: flex; align-items: center; gap: 10px; }
      .hint { color: rgba(167, 177, 214, 0.85); }
      .btn {
        border: 1px solid rgba(255,255,255,0.14);
        background: rgba(255,255,255,0.06);
        color: var(--text);
        padding: 4px 10px;
        border-radius: 10px;
        cursor: pointer;
        font-size: 12px;
      }
      .btn:hover { background: rgba(255,255,255,0.10); }
      .codelines { margin: 0; padding: 0; list-style: none; }
      .line {
        display: grid;
        grid-template-columns: 72px 1fr;
        gap: 12px;
        padding: 0 12px;
        border-bottom: 1px solid rgba(255,255,255,0.04);
      }
      .ln {
        color: rgba(167, 177, 214, 0.75);
        border-right: 1px solid rgba(255,255,255,0.06);
        padding: 4px 0;
        text-align: right;
        padding-right: 12px;
      }
      .src {
        padding: 4px 0;
        white-space: pre-wrap;
        word-break: break-word;
      }
      .tag { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 12px; margin-left: 6px; }
      .tag.ok { background: rgba(94, 234, 212, 0.14); border: 1px solid rgba(94, 234, 212, 0.35); }
      .tag.warn { background: rgba(251, 191, 36, 0.14); border: 1px solid rgba(251, 191, 36, 0.35); }
      .tag.bad { background: rgba(251, 113, 133, 0.14); border: 1px solid rgba(251, 113, 133, 0.35); }
      .hl { background: var(--hl); border-radius: 4px; padding: 0 2px; }
      .hlbad { background: var(--hlbad); border-radius: 4px; padding: 0 2px; }
      .sec { margin-top: 12px; }
      .md { color: #d9def8; font-size: 13px; }
      .md ul { margin: 8px 0 0 18px; padding: 0; }
      .md li { margin: 4px 0; }
      table { width: 100%; border-collapse: collapse; overflow: hidden; border-radius: 10px; }
      th, td { border-bottom: 1px solid var(--line); padding: 6px 8px; font-size: 12px; }
      th { text-align: left; color: var(--muted); }
      tr:hover td { background: rgba(255,255,255,0.03); }
      .toast {
        position: fixed;
        left: 50%;
        bottom: 18px;
        transform: translateX(-50%);
        background: rgba(17, 25, 54, 0.92);
        border: 1px solid rgba(255,255,255,0.14);
        color: var(--text);
        padding: 8px 12px;
        border-radius: 999px;
        font-size: 12px;
        z-index: 9999;
      }
    </style>
  </head>
  <body>
    <div class="wrap">
      <div class="top">
        <h1>$headline</h1>
        <div class="meta">$meta</div>
      </div>

      <div class="grid">
        <div class="card">
          <h2>Tier1 诊断摘要</h2>
          $tier1_summary_html
        </div>
        <div class="card">
          <h2>下一步建议</h2>
          $next_steps_html
        </div>
      </div>

      <div class="sec">
        <div class="card">
          <h2>Tier2（可选）</h2>
          $tier2_html
        </div>
      </div>

      <div class="sec">
        <div class="card">
          <h2>跨章节术语一致性</h2>
          $terms_html
        </div>
      </div>

	      <div class="sec">
	        <div class="code">
	          <div class="codehdr">
	            <div>文件：<span class="mono">$target_relpath</span></div>
	            <div class="actions">
	              <span class="hint">点击行号：跳转并复制行号；Shift+点击：复制链接</span>
	              <button class="btn" id="copy-page-link" type="button">复制页面链接</button>
	            </div>
	          </div>
	          <ol class="codelines">$code_lines_html</ol>
	        </div>
	      </div>
	    </div>
	    <div id="toast" class="toast" style="display:none;"></div>
	    <script>
	      const toast = document.getElementById("toast");
	      const showToast = (msg) => {
	        if (!toast) return;
	        toast.textContent = msg;
	        toast.style.display = "block";
	        clearTimeout(window.__toastTimer);
	        window.__toastTimer = setTimeout(() => { toast.style.display = "none"; }, 1200);
	      };
	      const copyText = async (text) => {
	        try {
	          await navigator.clipboard.writeText(text);
	          showToast("已复制：" + text);
	        } catch (e) {
	          showToast("复制失败（浏览器权限限制）");
	        }
	      };
	      document.addEventListener("click", (ev) => {
	        const ln = ev.target && ev.target.closest ? ev.target.closest("a.ln") : null;
	        if (!ln) return;
	        const id = (ln.getAttribute("id") || "").trim();
	        if (!id) return;
	        const base = window.location.href.split("#")[0];
	        const text = ev.shiftKey ? (base + "#" + id) : id;
	        copyText(text);
	      });
	      const btn = document.getElementById("copy-page-link");
	      if (btn) {
	        btn.addEventListener("click", () => copyText(window.location.href));
	      }
	    </script>
	  </body>
	</html>
	

% 立项依据结构模板（与 projects/NSFC_Young/extraTex/1.1.立项依据.tex 对齐）

\subsubsection{研究背景}
\justifying\indent
% 建议写作要点：痛点/需求→影响范围或成本→为何现在必须做（1–2 段即可）

\subsubsection{国内外研究现状}
\indent
% 建议写作要点：主流路线与代表性工作→2–4 条明确不足（尽量可量化/可验证，避免口号）

\subsubsection{现有研究的局限性}
\indent
% 建议写作要点：2–4 条关键瓶颈→1–3 个科学问题（疑问句，非研究目标；约束与瓶颈一一映射）→一句科学假设（陈述句，预测性结果，不写验证方式）→验证维度（数据/指标/对照/消融）

\subsubsection{研究切入点}
\indent
% 建议写作要点：差异化切口→可交付成果与指标→最后 1 句承上启下引到 2.1 研究内容

# ═══════════════════════════════════════════════════════════════════════
# nsfc-justification-writer 配置文件
# ═══════════════════════════════════════════════════════════════════════
# 本文件是 nsfc-justification-writer 的配置单一真相来源（Single Source of Truth）
# 修改配置时，请优先编辑本文件，而非 scripts/core/config_loader.py
# ═══════════════════════════════════════════════════════════════════════

skill_info:
  name: nsfc-justification-writer
  version: 1.0.0
  category: writing
  author: "Bensz Conan"

# 写作导向（可配置）
# - theoretical：理论创新导向（默认）
# - mixed：理论 + 应用混合导向
# - engineering：工程/应用导向
style:
  mode: theoretical

parameters:
  project_root:
    type: string
    required: true
    description: 项目根目录（如 projects/NSFC_Young 或你的标书项目路径）
  output_mode:
    type: string
    required: false
    default: apply
    allowed_values: [preview, apply]
    description: preview 仅输出建议文本；apply 则写入目标 .tex 文件（如由平台/工具支持）
  word_count_target:
    type: integer
    required: false
    default: 9000
    description: 目标字数（中文字符数，不含 LaTeX 命令/注释；兜底值，优先从用户意图/信息表/学科预设解析）
  word_count_tolerance:
    type: integer
    required: false
    default: 800
    description: 允许偏差范围（兜底值；若用户给出区间/±范围则优先使用）

targets:
  justification_tex: extraTex/1.1.立项依据.tex
  related_tex:
    research_content: extraTex/2.1.研究内容.tex
    research_foundation: extraTex/3.1.研究基础.tex
  bib_globs:
    - references/*.bib
    - references/**/*.bib

workspace:
  # runs/ 属于运行时产物：统一放在 tests/_artifacts/ 下（测试/运行产物集中收口）
  runs_dir: tests/_artifacts/runs

limits:
  # 文件大小限制（用于决定是否启用“流式分块”读取；避免一次性加载超大文件造成峰值内存）
  max_file_size_mb: 5

  # AI 输入字符限制（用于语义分析、术语一致性等）
  ai_max_input_chars: 20000

  # 写作教练预览字符数（用于快速展示当前状态/阶段判定）
  writing_coach_preview_chars: 3000

  # 字数目标范围限制（用于解析用户意图/信息表时的安全夹紧）
  word_target:
    min: 100
    max: 20000

ai:
  enabled: true
  tier2_chunk_size: 12000
  tier2_max_chunks: 20
  # 运行时缓存统一放在 tests/_artifacts/ 下（测试/运行产物集中收口）
  cache_dir: tests/_artifacts/cache/ai

prompts:
  tier2_diagnostic: assets/prompts/tier2_diagnostic.txt
  review_suggestions: assets/prompts/review_suggestions.txt
  writing_coach: assets/prompts/writing_coach.txt

references:
  # 默认严格：发现缺失 bibkey 的 \\cite{...} 直接拒绝写入（防止幻觉引用）
  allow_missing_citations: false

structure:
  # 仅作为"推荐模板"，不再用作严格标题匹配的硬性规则（标题是形式，内容维度是本质）
  recommended_subsubsections:
    - 研究背景
    - 国内外研究现状
    - 现有研究的局限性
    - 研究切入点
  # 默认 false：允许用户改写标题用词（结构检查不再机械匹配标题字符串）
  strict_title_match: false
  # strict_title_match=false 时启用"模糊标题匹配"（必要时会调用 AI 在候选标题中做语义匹配）
  min_title_similarity: 0.6
  min_subsubsection_count: 4
  # 启用"内容维度覆盖检查"（不依赖标题用词；AI 不可用时回退启发式）
  enable_dimension_coverage_check: true

guardrails:
  allowed_write_files:
    - extraTex/1.1.立项依据.tex
  forbidden_write_files:
    - main.tex
    - extraTex/@config.tex
  forbidden_write_globs:
    - "**/*.cls"
    - "**/*.sty"

quality:
  # 高风险示例（用于快速提示；不穷举同义词变体）
  high_risk_examples:
    - 国际领先
    - 国内首次
    - 世界领先
    - 填补空白
  # 默认 false：示例词命中仅警告，不作为阻断（避免"玩文字游戏"）
  strict_mode: false
  # 启用 AI 语义判断（识别"可能引起评审不适的表述"）
  enable_ai_judgment: true
  ai_judgment_mode: semantic  # semantic | keyword（兜底）
  avoid_commands:
    - "\\section"
    - "\\subsection"
    - "\\input"
    - "\\include"

# 第三方约束（“瘦身提质”写作指标）：
# - 目标场景：NSFC 正文原则不超过 30 页，其中立项依据建议 6-10 页（推荐 6-8 页）
# - 本处仅做“诊断+预警”，不作为写入阻断（避免被历史遗留内容卡死）
constraints:
  page_limit:
    min: 6
    max: 10
    recommended: [6, 8]
    warning_threshold: 9
    # 经验估算：小四/1.5 倍行距下，约 1000 个中文字符 ≈ 1 页（仅用于预警，不代表最终排版）
    chars_per_page: 1000
  word_count:
    min: 8000
    max: 10000
  references:
    min: 30
    max: 50
  opening:
    cjk_chars: 300
    _note: "开篇 300 字尽量直击核心：领域卡点/局限 -> 为什么难 -> 本项目的突破式切入（仅做启发式检查）"

word_count:
  target: 9000
  tolerance: 800
  _note: "9000 字为兜底值；实际目标字数优先从用户意图/信息表/学科预设动态解析"
  # cjk_only: 仅剔除注释后统计 CJK 字符数（默认）
  # cjk_strip_commands: 粗剔除命令/数学环境/类代码环境后统计（更接近"正文字符数"的估计）
  mode: cjk_only

terminology:
  # auto: AI 可用则叠加 AI 语义检查，否则仅 legacy 规则矩阵
  # ai:   强制尝试 AI（不可用则回退）
  # legacy: 仅使用硬编码维度/别名组
  mode: auto
  enable_ai_semantic_check: true
  ai_mode: auto  # auto | semantic_only | legacy_only
  ai:
    enabled: true
    max_chars: 20000
  dimensions:
    研究对象:
      研究对象: ["患者", "病例", "受试者", "样本"]
    指标:
      准确率: ["准确率", "精确度"]
    术语:
      深度学习: ["深度学习", "DL"]

writing_coach:
  # 默认启用 AI 阶段推断（AI 不可用时自动回退到硬编码规则）
  enable_ai_stage_inference: true
  ai_inference_mode: auto  # auto | ai_only | fallback
  fallback_rules:
    draft_threshold_ratio: 0.4
    draft_min_chars: 600

# research-literature-review 集成配置（历史目录名仍为 .systematic-literature-review）
slr_integration:
  # 启用 research-literature-review 目录检测
  enabled: true

  # 标记文件夹名称（用于识别 research-literature-review 生成的历史工作区目录）
  marker_folder: ".systematic-literature-review"

  # 只读访问保护（禁止写入 research-literature-review 生成的目录）
  read_only: true

  # 自动验证引用一致性
  validate_citations: true

  # 允许的文件模式（用于过滤 .tex 和 .bib 文件）
  tex_patterns:
    - "*.tex"
    - "*_review.tex"
  bib_patterns:
    - "*.bib"
    - "*_参考文献.bib"
    - "references.bib"

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

"""
内部 Python 模块入口（非稳定对外 API）。

说明：
- scripts/run.py 会直接从各模块导入实现；本文件仅提供“方便交互/调试”的聚合导出。
- 若你需要稳定接口，请优先通过 scripts/run.py 的子命令调用。
"""

from .ai_integration import AIIntegration
from .config_loader import get_runs_dir, load_config, validate_config
from .diagnostic import DiagnosticReport
from .editor import ApplyResult
from .errors import SkillError
from .hybrid_coordinator import HybridCoordinator
from .review_integration import (
    ReviewDirectoryInfo,
    analyze_review_directory,
    detect_slr_directory,
    extract_citation_keys_from_bib,
    extract_citations_from_tex,
    format_review_directory_summary,
    validate_citation_consistency,
    validate_read_access,
)

__all__ = [
    "AIIntegration",
    "ApplyResult",
    "DiagnosticReport",
    "HybridCoordinator",
    "ReviewDirectoryInfo",
    "SkillError",
    "analyze_review_directory",
    "detect_slr_directory",
    "extract_citation_keys_from_bib",
    "extract_citations_from_tex",
    "format_review_directory_summary",
    "get_runs_dir",
    "load_config",
    "validate_citation_consistency",
    "validate_config",
    "validate_read_access",
]

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from __future__ import annotations

import hashlib
import json
import logging
from pathlib import Path
from typing import Any, Awaitable, Callable, Dict, List, Optional, Union

JsonDict = Dict[str, Any]
Responder = Callable[[str, str, str], Union[str, JsonDict, None, Awaitable[Union[str, JsonDict, None]]]]


class AIIntegration:
    """
    AI 集成层（优雅降级）

    说明：
    - 本仓库内的 Python 脚本默认不假设"可直接调用宿主 AI"。
    - 若未提供 responder（或 enable_ai=False），将自动回退到 fallback。
    - 该接口为后续真正的 AI 调用预留扩展点，同时保证当前功能可用。
    """

    def __init__(
        self,
        *,
        enable_ai: bool = True,
        config: Optional[Dict[str, Any]] = None,
        responder: Optional[Responder] = None,
    ) -> None:
        self.enable_ai = bool(enable_ai)
        self.config = config or {}
        self.responder = responder

        self.fallback_mode = False
        self.request_count = 0
        self.success_count = 0

    def is_available(self) -> bool:
        return bool(self.enable_ai and (not self.fallback_mode) and (self.responder is not None))

    def get_stats(self) -> Dict[str, Any]:
        return {
            "enabled": self.enable_ai,
            "fallback_mode": self.fallback_mode,
            "request_count": self.request_count,
            "success_count": self.success_count,
            "success_rate": self.success_count / max(self.request_count, 1),
        }

    async def process_request(
        self,
        *,
        task: str,
        prompt: str,
        fallback: Callable[[], Any],
        output_format: str = "json",
        cache_dir: Optional[Path] = None,
        fresh: bool = False,
    ) -> Any:
        self.request_count += 1

        cache_path: Optional[Path] = None
        if cache_dir is not None:
            cache_dir = Path(cache_dir).resolve()
            cache_key = hashlib.sha256(f"{task}\n{output_format}\n{prompt}".encode("utf-8", errors="ignore")).hexdigest()
            safe_task = "".join([c if (c.isalnum() or c in {"-", "_"}) else "_" for c in str(task)])[:64] or "task"
            suffix = ".json" if output_format == "json" else ".txt"
            cache_path = (cache_dir / f"{safe_task}_{cache_key}{suffix}").resolve()
            if (not fresh) and cache_path.exists():
                try:
                    if output_format == "json":
                        obj = json.loads(cache_path.read_text(encoding="utf-8", errors="ignore"))
                        if isinstance(obj, dict):
                            self.success_count += 1
                            return obj
                    elif output_format == "text":
                        self.success_count += 1
                        return cache_path.read_text(encoding="utf-8", errors="ignore").strip()
                except (OSError, UnicodeError, json.JSONDecodeError, ValueError):
                    logging.getLogger(__name__).debug("[AIIntegration] ignore broken cache: %s", str(cache_path))

        if not self.enable_ai:
            self.fallback_mode = True
            self._log_fallback(task, reason="AI disabled")
            return fallback()

        if self.responder is None:
            self.fallback_mode = True
            self._log_fallback(task, reason="No responder configured")
            return fallback()

        try:
            raw = self.responder(task, prompt, output_format)
            if hasattr(raw, "__await__"):
                raw = await raw  # type: ignore[misc]

            if raw is None:
                raise ValueError("Empty AI response")

            if output_format == "json":
                if isinstance(raw, dict):
                    self.success_count += 1
                    if cache_path is not None:
                        cache_path.parent.mkdir(parents=True, exist_ok=True)
                        cache_path.write_text(json.dumps(raw, ensure_ascii=False, indent=2), encoding="utf-8")
                    return raw
                parsed = self._parse_json_response(str(raw))
                if parsed is None:
                    raise ValueError("Failed to parse JSON response")
                self.success_count += 1
                if cache_path is not None:
                    cache_path.parent.mkdir(parents=True, exist_ok=True)
                    cache_path.write_text(json.dumps(parsed, ensure_ascii=False, indent=2), encoding="utf-8")
                return parsed

            if output_format == "text":
                text = str(raw).strip()
                self.success_count += 1
                if cache_path is not None:
                    cache_path.parent.mkdir(parents=True, exist_ok=True)
                    cache_path.write_text(text, encoding="utf-8")
                return text

            raise ValueError(f"Unsupported output_format: {output_format}")
        except Exception as e:
            self.fallback_mode = True
            logging.getLogger(__name__).warning(
                "[AIIntegration] fallback task=%s reason=%s",
                task,
                str(e),
                exc_info=True,
            )
            return fallback()

    @staticmethod
    def _parse_json_response(response_text: str) -> Optional[JsonDict]:
        # 1) fenced code block
        if "```json" in response_text:
            start = response_text.find("```json") + 7
            end = response_text.find("```", start)
            if end != -1:
                candidate = response_text[start:end].strip()
                try:
                    obj = json.loads(candidate)
                    return obj if isinstance(obj, dict) else None
                except json.JSONDecodeError:
                    return None

        # 2) first balanced {...}
        start = response_text.find("{")
        if start == -1:
            return None

        depth = 0
        for i in range(start, len(response_text)):
            ch = response_text[i]
            if ch == "{":
                depth += 1
            elif ch == "}":
                depth -= 1
                if depth == 0:
                    candidate = response_text[start : i + 1]
                    try:
                        obj = json.loads(candidate)
                        return obj if isinstance(obj, dict) else None
                    except json.JSONDecodeError:
                        return None

        return None

    @staticmethod
    def _log_fallback(task: str, reason: str) -> None:
        logger = logging.getLogger(__name__)
        if reason in {"AI disabled", "No responder configured"}:
            logger.info("[AIIntegration] fallback task=%s reason=%s", task, reason)
        else:
            logger.warning("[AIIntegration] fallback task=%s reason=%s", task, reason)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from __future__ import annotations

from dataclasses import dataclass
from typing import List


@dataclass(frozen=True)
class BibFixSuggestion:
    missing_bibkeys: List[str]
    missing_doi_keys: List[str]
    invalid_doi_keys: List[str]

    def to_markdown(self, *, project_root: str) -> str:
        lines = [
            "# 引用核验建议（手动补齐 BibTeX）",
            "",
            "说明：本工具不会自动联网补齐引用，但会生成一段“可直接复制”的提示词，帮助你（或任意 BibTeX 工具/助手）完成核验与补齐。",
            "",
        ]
        if self.missing_bibkeys:
            lines += [
                "## 缺失的 bibkey（LaTeX 中引用了，但 .bib 没有）",
                "",
            ] + [f"- {k}" for k in self.missing_bibkeys]
        if self.missing_doi_keys:
            lines += [
                "",
                "## DOI 缺失的条目（.bib 有该 key，但缺 doi 字段，建议补齐以便可核验）",
                "",
            ] + [f"- {k}" for k in self.missing_doi_keys]
        if self.invalid_doi_keys:
            lines += [
                "",
                "## DOI 疑似不合法的条目（.bib 有 doi 字段，但格式看起来不对，建议核验）",
                "",
            ] + [f"- {k}" for k in self.invalid_doi_keys]

        lines += [
            "",
            "## 可直接复制的提示词（用于核验与补齐）",
            "```",
            "请帮我核验并补齐参考文献条目：",
            f"目标项目：{project_root}",
            "任务：核验并补齐参考文献条目，确保不出现幻觉引用。",
        ]
        if self.missing_bibkeys:
            lines += [
                "需要新增/补齐的 bibkey：",
                ", ".join(self.missing_bibkeys),
                "说明：这些 key 在 tex 里被 \\cite{...} 使用，但当前 .bib 未找到。请让我提供 DOI/链接/题录信息后再写入，或提示我补充缺失信息。",
            ]
        if self.missing_doi_keys:
            lines += [
                "需要补 DOI 的 bibkey：",
                ", ".join(self.missing_doi_keys),
                "说明：这些 key 在 .bib 存在，但缺 doi 字段；请在不杜撰的前提下补齐 doi（如无法确定，请明确提示需要我提供 DOI/链接）。",
            ]
        if self.invalid_doi_keys:
            lines += [
                "需要核验/修正 DOI 的 bibkey：",
                ", ".join(self.invalid_doi_keys),
                "说明：这些 key 的 doi 字段疑似不合规（例如写成 URL/带多余字符/缺 10.x 前缀等）；请核验后修正为标准 DOI 格式（如无法确定，请明确提示需要我提供 DOI/链接）。",
            ]
        lines += [
            "输出：更新项目 references/*.bib（或你认为合适的 .bib），并给出每条的题目/作者/年份/期刊/DOI 核验结果；无法核验的条目请标注“待核验”。",
            "```",
        ]
        return "\n".join(lines).strip() + "\n"

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from __future__ import annotations

from typing import Any, Dict, Optional

from .ai_integration import AIIntegration
from .latex_parser import strip_comments


class BoastfulExpressionAI:
    """
    AI 主导的“可能引起评审不适的表述”识别。

    说明：
    - 不依赖禁词表，而是基于语义判断是否存在无对照/无证据的自我夸大
    - AI 不可用时返回空 issues（不阻断），由硬编码高风险示例做快速提示
    """

    def __init__(self, ai: AIIntegration) -> None:
        self.ai = ai

    async def check(
        self,
        *,
        tex_text: str,
        max_chars: int,
        cache_dir: Optional[Any] = None,
        fresh: bool = False,
    ) -> Dict[str, Any]:
        prompt = """
请分析以下立项依据文本，识别“可能引起评审专家不适的表述”。

评审专家通常反感的表述类型：
1) 绝对化表述：无对照的“最/首/唯一/领先/首创”
2) 填补空白式：“填补空白”“开创性”无具体指标
3) 无依据夸大：“重大/重要/关键”无数据/对比支撑
4) 自我定性：用绝对形容词自我评价（无第三方引用）

请注意区分：
- 有数据/引用支撑的结论是 OK 的（如“相比 X 方法提升 30%”“引用自 Y 期刊”）
- 无依据的自我夸大需要标记

要求：
- 只输出 JSON，不要解释
- 原文片段请截取不超过 50 字
- 不要杜撰文献引用与 DOI

返回 JSON：
{
  "issues": [
    {
      "category": "绝对化表述|填补空白|无依据夸大|自我定性",
      "text": "原文片段（不超过 50 字）",
      "reason": "为何会引起评审不适",
      "suggestion": "如何改为可验证/可对照的表述"
    }
  ],
  "summary": {
    "total_issues": 3,
    "by_category": {"绝对化表述": 2, "无依据夸大": 1}
  }
}
""".strip()

        max_chars = max(int(max_chars), 1000)
        cleaned = strip_comments(tex_text or "")[:max_chars]
        prompt = prompt + f"\n\n文本内容（去注释后，最多 {max_chars} 字符）：\n" + cleaned

        def _fallback() -> Dict[str, Any]:
            return {"issues": [], "summary": {"total_issues": 0, "by_category": {}}, "_mode": "fallback"}

        obj = await self.ai.process_request(
            task="boastful_expression_check",
            prompt=prompt,
            fallback=_fallback,
            output_format="json",
            cache_dir=cache_dir,
            fresh=fresh,
        )
        if not isinstance(obj, dict):
            return _fallback()
        obj.setdefault("_mode", "ai" if self.ai.is_available() else "fallback")
        return obj

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from __future__ import annotations

from typing import Any, Mapping, MutableMapping, Sequence


def get_mapping(cfg: Mapping[str, Any], key: str) -> Mapping[str, Any]:
    v = cfg.get(key)
    return v if isinstance(v, Mapping) else {}


def get_mutable_mapping(cfg: Mapping[str, Any], key: str) -> MutableMapping[str, Any]:
    v = cfg.get(key)
    return v if isinstance(v, MutableMapping) else {}


def get_nested_mapping(cfg: Mapping[str, Any], *keys: str) -> Mapping[str, Any]:
    cur: Mapping[str, Any] = cfg
    for k in keys:
        cur = get_mapping(cur, k)
    return cur


def get_str(cfg: Mapping[str, Any], key: str, default: str = "") -> str:
    v = cfg.get(key, default)
    return str(v) if v is not None else str(default)


def get_bool(cfg: Mapping[str, Any], key: str, default: bool = False) -> bool:
    v = cfg.get(key, default)
    return bool(v)


def get_int(cfg: Mapping[str, Any], key: str, default: int) -> int:
    v = cfg.get(key, default)
    try:
        return int(v)
    except (TypeError, ValueError):
        return int(default)


def get_seq_str(cfg: Mapping[str, Any], key: str) -> Sequence[str]:
    v = cfg.get(key)
    if isinstance(v, list):
        return [str(x) for x in v if str(x).strip()]
    return []

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from __future__ import annotations

import os
from pathlib import Path
from typing import Any, Dict, List, Optional, Sequence


# ═══════════════════════════════════════════════════════════════════════
# 配置单一真相来源（Single Source of Truth）说明：
# config.yaml 是权威配置文件，DEFAULT_CONFIG 仅作为"兜底值"
# 修改配置时，请优先编辑 config.yaml，而非此文件
# ═══════════════════════════════════════════════════════════════════════

DEFAULT_CONFIG: Dict[str, Any] = {
    # 安全关键项：即使 YAML 缺失也必须生效的默认值（避免"空策略"导致任意写入）
    "guardrails": {
        "allowed_write_files": ["extraTex/1.1.立项依据.tex"],
        "forbidden_write_files": ["main.tex", "extraTex/@config.tex"],
        "forbidden_write_globs": ["**/*.cls", "**/*.sty"],
    },
}


def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
    merged: Dict[str, Any] = dict(base)
    for key, value in (override or {}).items():
        if isinstance(value, dict) and isinstance(merged.get(key), dict):
            merged[key] = _deep_merge(merged[key], value)
        else:
            merged[key] = value
    return merged


def _load_yaml_dict_with_warning(path: Path) -> tuple[Dict[str, Any], str]:
    try:
        import yaml  # type: ignore
    except (ModuleNotFoundError, ImportError):
        return {}, "未安装 PyYAML，已跳过 YAML 配置加载（建议 `pip install pyyaml`）"
    try:
        raw = yaml.safe_load(path.read_text(encoding="utf-8", errors="ignore")) or {}
        if not isinstance(raw, dict):
            return {}, "YAML 顶层不是 mapping（dict），已忽略"
        return raw, ""
    except (OSError, UnicodeError, ValueError, yaml.YAMLError) as e:  # type: ignore[attr-defined]
        return {}, f"YAML 解析失败（{type(e).__name__}: {e}），已忽略（请检查语法）"


def _default_user_override_path() -> Optional[Path]:
    home = Path.home()
    candidates = [
        home / ".config" / "nsfc-justification-writer" / "override.yaml",
        home / ".config" / "nsfc-justification-writer" / "override.yml",
    ]
    return next((p for p in candidates if p.exists() and p.is_file()), None)


def _is_seq_str(x: Any) -> bool:
    return isinstance(x, list) and all(isinstance(it, str) for it in x)


def _is_alias_groups(x: Any) -> bool:
    if not isinstance(x, dict):
        return False
    for k, v in x.items():
        if not isinstance(k, str):
            return False
        if not _is_seq_str(v):
            return False
    return True


def _is_nonempty_seq_str(x: Any) -> bool:
    return isinstance(x, list) and all(isinstance(it, str) and str(it).strip() for it in x) and len(x) > 0


def _looks_like_path(s: str) -> bool:
    t = (s or "").strip()
    if not t:
        return False
    if "\n" in t or "\r" in t:
        return False
    if t.endswith((".txt", ".md", ".yaml", ".yml")):
        return True
    return ("/" in t) or ("\\" in t)


def _resolve_prompt_path(skill_root: Path, value: str) -> Optional[Path]:
    v = str(value or "").strip()
    if not v or (not _looks_like_path(v)):
        return None
    p = Path(v).expanduser()
    if not p.is_absolute():
        p = (Path(skill_root).resolve() / p).resolve()
    return p.resolve()


def _collect_config_warnings(*, skill_root: Path, config: Dict[str, Any]) -> List[str]:
    warnings: List[str] = []
    prompts = config.get("prompts", {})
    if isinstance(prompts, dict):
        for k, v in prompts.items():
            if not isinstance(k, str):
                continue
            if not isinstance(v, str) or (not v.strip()):
                continue
            p = _resolve_prompt_path(skill_root, v)
            if p is None:
                continue
            # 仅做风险提示：外部路径内容可能被拼入 prompt（若上层注入 responder）
            if Path(v).expanduser().is_absolute():
                warnings.append(f"prompts.{k} 使用绝对路径：{v}（注意：该文件内容可能被拼入 prompt）")
            try:
                p.relative_to(Path(skill_root).resolve())
            except ValueError:
                warnings.append(f"prompts.{k} 指向 skill_root 之外：{v} -> {p}（注意：该文件内容可能被拼入 prompt）")
    return warnings


def _harden_guardrails(*, config: Dict[str, Any], meta: Dict[str, Any]) -> None:
    """
    安全关键项加固：
    - guardrails 必须存在且为 dict
    - allowed_write_files 不允许为空；若无效则回退到 DEFAULT_CONFIG（并给出 warning）
    - forbidden_write_files/forbidden_write_globs 若无效也回退到 DEFAULT_CONFIG（避免误放开 .cls/.sty 等）
    """
    default_guard = DEFAULT_CONFIG.get("guardrails", {})
    if not isinstance(default_guard, dict):
        default_guard = {}

    guard = config.get("guardrails")
    if not isinstance(guard, dict):
        config["guardrails"] = dict(default_guard)
        meta.setdefault("warnings", []).append("guardrails 非 dict（或被置空），已回退到安全默认值（白名单写入保持启用）")
        return

    allowed = guard.get("allowed_write_files")
    if not _is_nonempty_seq_str(allowed):
        guard["allowed_write_files"] = list(default_guard.get("allowed_write_files", ["extraTex/1.1.立项依据.tex"]))
        meta.setdefault("warnings", []).append(
            "guardrails.allowed_write_files 为空/无效，已回退到安全默认值（避免白名单失效）"
        )

    forbidden_files = guard.get("forbidden_write_files")
    if not _is_seq_str(forbidden_files):
        guard["forbidden_write_files"] = list(default_guard.get("forbidden_write_files", []))
        meta.setdefault("warnings", []).append("guardrails.forbidden_write_files 无效，已回退到安全默认值")

    forbidden_globs = guard.get("forbidden_write_globs")
    if not _is_seq_str(forbidden_globs):
        guard["forbidden_write_globs"] = list(default_guard.get("forbidden_write_globs", []))
        meta.setdefault("warnings", []).append("guardrails.forbidden_write_globs 无效，已回退到安全默认值")


def validate_config(*, skill_root: Path, config: Dict[str, Any]) -> List[str]:
    """
    轻量配置校验：只校验关键字段与类型，不阻止用户加入额外键。
    返回错误列表（空列表表示通过）。
    """
    errors: List[str] = []

    def err(msg: str) -> None:
        errors.append(msg)

    skill_info = config.get("skill_info")
    if not isinstance(skill_info, dict):
        err("skill_info 必须是 dict")
    else:
        if not isinstance(skill_info.get("name"), str) or not str(skill_info.get("name")).strip():
            err("skill_info.name 必须是非空字符串")
        if not isinstance(skill_info.get("version"), str) or not str(skill_info.get("version")).strip():
            err("skill_info.version 必须是非空字符串")

    style = config.get("style", {})
    if style is not None and not isinstance(style, dict):
        err("style 必须是 dict")
    elif isinstance(style, dict) and style:
        mode = str(style.get("mode", "theoretical")).strip().lower()
        if mode not in {"theoretical", "mixed", "engineering"}:
            err("style.mode 必须是 theoretical|mixed|engineering")

    targets = config.get("targets")
    if not isinstance(targets, dict):
        err("targets 必须是 dict")
    else:
        if not isinstance(targets.get("justification_tex"), str) or not str(targets.get("justification_tex")).strip():
            err("targets.justification_tex 必须是非空字符串")
        bib_globs = targets.get("bib_globs", [])
        if not _is_seq_str(bib_globs):
            err("targets.bib_globs 必须是字符串列表")

    structure = config.get("structure")
    if not isinstance(structure, dict):
        err("structure 必须是 dict")
    else:
        expected = structure.get("expected_subsubsections", None)
        recommended = structure.get("recommended_subsubsections", None)
        if (expected is None) and (recommended is None):
            err("structure.expected_subsubsections 或 structure.recommended_subsubsections 必须至少存在一个")
        else:
            seq = recommended if recommended is not None else expected
            if not _is_seq_str(seq) or not seq:
                err("structure.(expected_subsubsections|recommended_subsubsections) 必须是非空字符串列表")
        m = structure.get("min_subsubsection_count")
        if not isinstance(m, int) or m <= 0:
            err("structure.min_subsubsection_count 必须是正整数")

    quality = config.get("quality")
    if not isinstance(quality, dict):
        err("quality 必须是 dict")
    else:
        if "forbidden_phrases" in quality and not _is_seq_str(quality.get("forbidden_phrases", [])):
            err("quality.forbidden_phrases 必须是字符串列表")
        if "high_risk_examples" in quality and not _is_seq_str(quality.get("high_risk_examples", [])):
            err("quality.high_risk_examples 必须是字符串列表")
        if not _is_seq_str(quality.get("avoid_commands", [])):
            err("quality.avoid_commands 必须是字符串列表")
        if "strict_mode" in quality and not isinstance(quality.get("strict_mode"), bool):
            err("quality.strict_mode 必须是 bool")
        if "enable_ai_judgment" in quality and not isinstance(quality.get("enable_ai_judgment"), bool):
            err("quality.enable_ai_judgment 必须是 bool")
        if "ai_judgment_mode" in quality and not isinstance(quality.get("ai_judgment_mode"), str):
            err("quality.ai_judgment_mode 必须是 str")

    wc = config.get("word_count", {})
    if not isinstance(wc, dict):
        err("word_count 必须是 dict")
    else:
        if not isinstance(wc.get("target", 4000), int):
            err("word_count.target 必须是整数")
        if not isinstance(wc.get("tolerance", 200), int):
            err("word_count.tolerance 必须是整数")

    ai = config.get("ai", {})
    if not isinstance(ai, dict):
        err("ai 必须是 dict")
    else:
        if not isinstance(ai.get("enabled", True), bool):
            err("ai.enabled 必须是 bool")
        if "tier2_chunk_size" in ai and not isinstance(ai.get("tier2_chunk_size"), int):
            err("ai.tier2_chunk_size 必须是 int")
        if "tier2_max_chunks" in ai and not isinstance(ai.get("tier2_max_chunks"), int):
            err("ai.tier2_max_chunks 必须是 int")
        if "cache_dir" in ai and not isinstance(ai.get("cache_dir"), str):
            err("ai.cache_dir 必须是 str")

    limits = config.get("limits", {})
    if limits is not None and not isinstance(limits, dict):
        err("limits 必须是 dict")
    elif isinstance(limits, dict):
        if "max_file_size_mb" in limits and not isinstance(limits.get("max_file_size_mb"), int):
            err("limits.max_file_size_mb 必须是 int")
        if "ai_max_input_chars" in limits and not isinstance(limits.get("ai_max_input_chars"), int):
            err("limits.ai_max_input_chars 必须是 int")
        if "writing_coach_preview_chars" in limits and not isinstance(limits.get("writing_coach_preview_chars"), int):
            err("limits.writing_coach_preview_chars 必须是 int")
        if "word_target" in limits:
            wt = limits.get("word_target")
            if wt is not None and not isinstance(wt, dict):
                err("limits.word_target 必须是 dict")
            elif isinstance(wt, dict):
                if "min" in wt and not isinstance(wt.get("min"), int):
                    err("limits.word_target.min 必须是 int")
                if "max" in wt and not isinstance(wt.get("max"), int):
                    err("limits.word_target.max 必须是 int")

    prompts = config.get("prompts", {})
    if prompts is not None and not isinstance(prompts, dict):
        err("prompts 必须是 dict")
    elif isinstance(prompts, dict):
        for k, v in prompts.items():
            if not isinstance(v, str) or not v.strip():
                err(f"prompts.{k} 必须是非空字符串")
                continue
            # 允许：1) 文件路径；2) 直接写多行 prompt（用于 override/preset）
            if _looks_like_path(v):
                p = Path(v)
                if not p.is_absolute():
                    maybe = (Path(skill_root).resolve() / p).resolve()
                    if not maybe.exists():
                        err(f"prompts.{k} 路径不存在：{v}")

    guardrails = config.get("guardrails")
    if not isinstance(guardrails, dict):
        err("guardrails 必须是 dict（安全关键项）")
    else:
        if not _is_nonempty_seq_str(guardrails.get("allowed_write_files")):
            err("guardrails.allowed_write_files 必须是非空字符串列表（安全关键项：写入白名单不可为空）")
        if not _is_seq_str(guardrails.get("forbidden_write_files", [])):
            err("guardrails.forbidden_write_files 必须是字符串列表")
        if not _is_seq_str(guardrails.get("forbidden_write_globs", [])):
            err("guardrails.forbidden_write_globs 必须是字符串列表")

    terminology = config.get("terminology", {})
    if terminology is not None and not isinstance(terminology, dict):
        err("terminology 必须是 dict")
    elif isinstance(terminology, dict):
        mode = str(terminology.get("mode", "auto")).strip().lower()
        if mode not in {"auto", "ai", "legacy", "semantic_only", "legacy_only"}:
            err("terminology.mode 必须是 auto|ai|legacy|semantic_only|legacy_only")
        if "enable_ai_semantic_check" in terminology and not isinstance(terminology.get("enable_ai_semantic_check"), bool):
            err("terminology.enable_ai_semantic_check 必须是 bool")
        if "ai_mode" in terminology and not isinstance(terminology.get("ai_mode"), str):
            err("terminology.ai_mode 必须是 str")
        ai_cfg = terminology.get("ai", {})
        if ai_cfg is not None and not isinstance(ai_cfg, dict):
            err("terminology.ai 必须是 dict")
        elif isinstance(ai_cfg, dict):
            if "enabled" in ai_cfg and not isinstance(ai_cfg.get("enabled"), bool):
                err("terminology.ai.enabled 必须是 bool")
            if "max_chars" in ai_cfg and not isinstance(ai_cfg.get("max_chars"), int):
                err("terminology.ai.max_chars 必须是 int")
        if "dimensions" in terminology:
            dims = terminology.get("dimensions")
            if not isinstance(dims, dict):
                err("terminology.dimensions 必须是 dict")
            elif dims:
                for dim_name, groups in dims.items():
                    if not isinstance(dim_name, str) or not dim_name.strip():
                        err("terminology.dimensions 的 key 必须是非空字符串")
                        continue
                    if not _is_alias_groups(groups):
                        err(f"terminology.dimensions.{dim_name} 必须是 dict[str, list[str]]")
        elif "alias_groups" in terminology:
            if not _is_alias_groups(terminology.get("alias_groups")):
                err("terminology.alias_groups 必须是 dict[str, list[str]]")

    writing_coach = config.get("writing_coach")
    if writing_coach is not None and not isinstance(writing_coach, dict):
        err("writing_coach 必须是 dict")
    elif isinstance(writing_coach, dict):
        if "enable_ai_stage_inference" in writing_coach and not isinstance(writing_coach.get("enable_ai_stage_inference"), bool):
            err("writing_coach.enable_ai_stage_inference 必须是 bool")
        if "ai_inference_mode" in writing_coach and not isinstance(writing_coach.get("ai_inference_mode"), str):
            err("writing_coach.ai_inference_mode 必须是 str")
        if "fallback_rules" in writing_coach and not isinstance(writing_coach.get("fallback_rules"), dict):
            err("writing_coach.fallback_rules 必须是 dict")

    # 第三方约束：仅做类型校验（不要求必须存在）
    constraints = config.get("constraints")
    if constraints is not None and not isinstance(constraints, dict):
        err("constraints 必须是 dict")
    elif isinstance(constraints, dict):
        page = constraints.get("page_limit")
        if page is not None and not isinstance(page, dict):
            err("constraints.page_limit 必须是 dict")
        elif isinstance(page, dict):
            for k in ["min", "max", "warning_threshold", "chars_per_page"]:
                if k in page and not isinstance(page.get(k), int):
                    err(f"constraints.page_limit.{k} 必须是 int")
            if "recommended" in page:
                rec = page.get("recommended")
                if not (isinstance(rec, list) and len(rec) >= 2 and all(isinstance(x, int) for x in rec[:2])):
                    err("constraints.page_limit.recommended 必须是 [int, int]")

        wc = constraints.get("word_count")
        if wc is not None and not isinstance(wc, dict):
            err("constraints.word_count 必须是 dict")
        elif isinstance(wc, dict):
            for k in ["min", "max"]:
                if k in wc and not isinstance(wc.get(k), int):
                    err(f"constraints.word_count.{k} 必须是 int")

        refs = constraints.get("references")
        if refs is not None and not isinstance(refs, dict):
            err("constraints.references 必须是 dict")
        elif isinstance(refs, dict):
            for k in ["min", "max"]:
                if k in refs and not isinstance(refs.get(k), int):
                    err(f"constraints.references.{k} 必须是 int")

        opening = constraints.get("opening")
        if opening is not None and not isinstance(opening, dict):
            err("constraints.opening 必须是 dict")
        elif isinstance(opening, dict):
            if "cjk_chars" in opening and not isinstance(opening.get("cjk_chars"), int):
                err("constraints.opening.cjk_chars 必须是 int")

    return errors


def load_config(
    skill_root: Path,
    *,
    preset: Optional[str] = None,
    override_path: Optional[str] = None,
    load_user_override: bool = True,
) -> Dict[str, Any]:
    skill_root = Path(skill_root).resolve()
    config: Dict[str, Any] = dict(DEFAULT_CONFIG)
    meta: Dict[str, Any] = {"yaml_available": True, "loaded_files": [], "warnings": []}

    def _merge_yaml(path: Path, *, label: str) -> None:
        nonlocal config, meta
        if not path.exists():
            return
        data, warn = _load_yaml_dict_with_warning(path)
        if warn:
            meta["warnings"].append(f"{label}: {warn} -> {path}")
            if "未安装 PyYAML" in warn:
                meta["yaml_available"] = False
            return
        config = _deep_merge(config, data)
        meta["loaded_files"].append(str(path))

    config_path = (skill_root / "config.yaml").resolve()
    _merge_yaml(config_path, label="repo config.yaml")

    if preset:
        # 新规范：assets/presets/<name>.yaml（优先）
        # 兼容旧路径：config/presets/<name>.yaml
        preset_name = str(preset).strip()
        preset_candidates = [
            (skill_root / "assets" / "presets" / f"{preset_name}.yaml").resolve(),
            (skill_root / "config" / "presets" / f"{preset_name}.yaml").resolve(),
        ]
        preset_path = next((p for p in preset_candidates if p.exists()), preset_candidates[0])
        _merge_yaml(preset_path, label=f"preset={preset_name}")
        config["active_preset"] = str(preset)
    else:
        config["active_preset"] = ""

    disable_user_override = str(os.environ.get("NSFC_JUSTIFICATION_WRITER_DISABLE_USER_OVERRIDE", "")).strip().lower() in {
        "1",
        "true",
        "yes",
    }
    if load_user_override and (not disable_user_override):
        env_override = os.environ.get("NSFC_JUSTIFICATION_WRITER_OVERRIDE_PATH")
        user_path = Path(env_override).expanduser().resolve() if env_override else _default_user_override_path()
        if user_path and user_path.exists():
            _merge_yaml(Path(user_path), label="user override")

    if override_path:
        p = Path(override_path).expanduser()
        if not p.is_absolute():
            p = (Path.cwd() / p).resolve()
        _merge_yaml(p, label="--override")

    meta["warnings"].extend(_collect_config_warnings(skill_root=skill_root, config=config))
    config["_config_loader"] = meta

    disable_validation = str(os.environ.get("NSFC_JUSTIFICATION_WRITER_DISABLE_CONFIG_VALIDATION", "")).strip().lower() in {
        "1",
        "true",
        "yes",
    }
    # 无 PyYAML：只能运行 DEFAULT_CONFIG（至少保证 guardrails 生效），跳过强校验避免“承诺降级但实际失败”
    if not bool(meta.get("yaml_available", True)):
        disable_validation = True
        meta["warnings"].append("未安装 PyYAML：已跳过配置强校验（当前仅保证 guardrails 等安全兜底生效）")

    if not disable_validation:
        errs = validate_config(skill_root=skill_root, config=config)
        if errs:
            raise ValueError("配置校验失败：\n- " + "\n- ".join(errs))

    # 即使用户显式关闭校验，也不允许安全关键项被“置空/移除”
    _harden_guardrails(config=config, meta=meta)

    return config


def get_runs_dir(skill_root: Path, config: Dict[str, Any]) -> Path:
    env_override = os.environ.get("NSFC_JUSTIFICATION_WRITER_RUNS_DIR")
    if env_override:
        p = Path(env_override)
        if not p.is_absolute():
            p = (Path(skill_root) / p).resolve()
        return p.resolve()
    workspace = config.get("workspace", {})
    workspace = workspace if isinstance(workspace, dict) else {}
    runs_dir = workspace.get("runs_dir", "tests/_artifacts/runs")
    return (Path(skill_root) / str(runs_dir)).resolve()