# Thesis Qc

> thesis-qc — 学术论文质控编排技能

- Skill: `skydooooog0221/thesis-qc` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add skydooooog0221/thesis-qc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/skydooooog0221/thesis-qc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Skydooooog0221 (https://skillmd.com/u/skydooooog0221)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/skydooooog0221/thesis-qc

---

# thesis-qc — 学术论文质控编排技能

> 版本：0.2.0-draft
> 创建日期：2026-04-13
> 最后更新：2026-04-13
> 来源：从真实论文项目的多版本MASTER_QC_STATUS、bug report、三层验证体系、critical review提炼
> 变更：v0.1→v0.2 架构从巨型skill改为编排器；M8拆出为独立skill；加入设计哲学；M4双模式；全人工切换
> 变更：v0.2→v0.3 六个机械模块全部实现并验证；加入脚本对照表

---

## 脚本对照表

| 模块 | 脚本 | 调用方式 | 必需输入 | 可选输入 |
|------|------|---------|---------|---------|
| M1 | `m1_ref_integrity.py` | `python m1_ref_integrity.py <txt> <bib> [-d deleted.json] [-o dir]` | thesis_full.txt, refs.bib | deleted_refs.json |
| M2 | `m2_modification_landing.py` | `python m2_modification_landing.py <txt> <guide.md> [-o dir]` | thesis_full.txt, modification_guide.md | |
| M3 | `m3_citation_cross_ref.py` | `python m3_citation_cross_ref.py <txt> [-o dir]` | thesis_full.txt | |
| M5 | `m5_cross_chapter_consistency.py` | `python m5_cross_chapter_consistency.py <txt> [-v vars.json] [-o dir]` | thesis_full.txt | variable_definitions.json |
| M6 | `m6_format_scan.py` | `python m6_format_scan.py <txt> [-o dir]` | thesis_full.txt | |
| M9 | `m9_bug_regression.py` | `python m9_bug_regression.py <txt> <bugs.md\|bugs.json> [-o dir]` | thesis_full.txt, old bug report | |
| M4 | 无脚本 | 编排层调用ref-verifier | citation_map.json (M3产出) | |
| M7 | 无脚本 | LLM+视觉运行时 | 图片文件 + thesis_full.txt | |
| M8 | 无脚本 | 调用thesis-critical-review | thesis_full.txt | |

所有脚本位于 `skills/thesis-qc/` 目录下。输出默认存到输入文件同目录，`-o` 指定输出目录。

---

## 设计哲学（不可违反）

**thesis-qc是monitor，不是executor。**

这个skill的本质是一个**带结构的人类质控放大器**。它追踪进度、提醒遗漏、结构化检查结果，但绝不替人做决定，不自动修改任何论文文件。质控对风险的容忍度为零——不做"大概率没问题就跳过"的优化。

四条不可违反的约束：

1. **全责在人。** skill的所有输出都是"供决策参考"，不是"已执行完毕"。用户为产出负全责，skill是尖刀和reminder，不是责任承担者
2. **不自动翻转状态。** MASTER_QC.md中的Phase完成标记只能由用户确认后翻转，不由skill自动翻转。即使所有检查都PASS，也必须用户说"确认Phase X完成"才标记✅
3. **任何模块、任何阶段可切换为全人工模式。** 用户随时可以说"这部分我手动做"。skill的职责变为：记录结果、更新MASTER、提供下一步提醒。不强制自动化路径
4. **每个发现附带原文证据。** 所有判定类输出必须附带原文上下文（引用前后各一句+章节+行号），用户可以回溯到docx原文进行人脑确认。不允许只报告结论不报告证据

**在"AI辅助下的论文"仍处于灰色地带的时期，这个skill的设计选择是宁可低效也不冒风险。**

---

## 触发条件

以下任一情况出现时触发：
- 用户提到"质控""QC""论文检查""送审前检查""thesis lint""跑一遍检查"
- 用户上传论文docx/txt + bib文件并要求审查
- 用户要求对论文做某个特定维度的审查（引用核查、跨章一致性等）
- 用户要求初始化一个新论文项目的QC框架

---

## 架构概览

thesis-qc 是一个**编排器（orchestrator）**，管理MASTER_QC.md并按阶段调用独立skill或执行内置轻量模块。

```
thesis-qc（编排层）
  │
  ├── 内置模块（轻量，thesis-qc自身实现）
  │   ├── M1 引用完整性（S3+S4+S5）      [机械]
  │   ├── M2 修改落地验证（S2）            [机械]
  │   ├── M3 跨章引用交叉（S7）            [机械提取 + LLM判断]
  │   ├── M5 跨章一致性                    [机械 + LLM]
  │   ├── M6 格式扫描 + AI痕迹检测         [机械]
  │   └── M9 Bug回归                       [机械 + LLM]
  │
  ├── 外部skill调用
  │   ├── M4 引用溯源 → 调用 ref-verifier（已有skill）
  │   │   thesis-qc负责：分层筛选目标、格式转换、backlog管理
  │   │   ref-verifier负责：核心claim-abstract判定逻辑
  │   │
  │   ├── M7 图表审查 → [未来可独立成skill]
  │   │
  │   └── M8 讨论层批判审查 → 调用 thesis-critical-review（独立skill）
  │
  └── MASTER_QC.md 管理
      ├── 状态追踪（人确认后才翻转）
      ├── Action Items汇总
      ├── 文件清单维护
      └── 交叉验证规则执行
```

核心理念：
1. **单一权威文件（SSOT）**——所有状态追踪在MASTER_QC.md中
2. **分层精度**——核心引用全文验证，一般引用摘要验证，装饰引用PMID存在性验证
3. **Backlog模式**——做不完的生成backlog文件，下轮接续
4. **交叉验证三规则**——严重结论换方法重跑、不可逆操作换路径确认、自相矛盾回溯确认
5. **JSON中间+MD报告**——结构化数据用JSON传递，人可读报告用Markdown
6. **原文上下文必附**——所有判定附带引用前后各一句原文，支持人脑回溯

---

## 运行模式

### 模式一：完整管线

按Phase顺序执行。每个Phase完成后更新MASTER_QC.md，报告结果，**等待用户确认**后进入下一Phase。

```
Phase 0: 初始化 → MASTER_QC.md创建 + 输入文件注册
Phase 1: M1 引用完整性
Phase 2: M2 修改落地验证 [可选]
Phase 3: M3 跨章引用交叉
Phase 4: M4 引用溯源（调用ref-verifier）
Phase 5: M5 跨章一致性
Phase 6: M6 格式扫描
Phase 7: M7 图表审查 [需图片文件]
Phase 8: M8 讨论层批判审查（调用thesis-critical-review）
Phase 9: M9 Bug回归 [需旧bug report]
```

### 模式二：单模块执行

用户指定运行某个模块。如"检查跨章一致性"→ 只执行M5。

### 模式三：增量回归

输入旧bug report + 新版docx → M9 + M1 + M5。

### 模式四：全人工模式

用户手动执行质控，skill只做：
- 维护MASTER_QC.md进度
- 记录用户报告的发现
- 提醒下一步该做什么
- 不执行任何自动检测

用户可以在任何Phase中途切换到全人工模式，也可以从全人工模式切回自动模式。

---

## 内置模块定义

### M1：引用完整性 `[机械]`

**输入：** `thesis_full.txt` + `refs.bib` + `deleted_refs.json`（可选）

**处理：**
1. bib解析 → bib_entries.json
2. Entrez批量验证（有PMID条目）→ 逐字段比对 → entrez_verification.json
3. 删除引用残留扫描（正则+上下文排除表格数字）→ residual_scan.json
4. 重复引用检测（DOI/标题/作者三层匹配）→ duplicates.json
5. 报告生成 → integrity_report.md

**输出格式（integrity_report.md）：**
每条发现必须包含：
```markdown
### [CRITICAL] 字段不匹配: [29] Smith 2015
**bib标题:** Primary outcome X in population Y...
**PubMed标题:** Secondary outcome X' in population Y...
**匹配度:** 0.72 (阈值0.85)
**原文上下文:**
> ......关键预测因子是唯一显著的危险因素（adj.OR=1.128, **[29]**），与Smith等......
> （Ch2, 约第215行）
```

**全人工模式：** 用户自己逐条检查bib。skill只维护检查进度表，记录每条的验证状态（✅/❌/⬜）。

**人类检查点：** MISMATCH条目。历史经验：约15%是误报（publisher-side DOI交叉）。不自动处理。

---

### M2：修改落地验证 `[机械]`

**输入：** `thesis_full.txt` + `modifications.json`

**处理：**
1. 搜索old_text → 如果找到=未落地(FLAG)
2. 搜索new_text → 如果找到=已修改(PASS)
3. 两者都找不到=不确定(UNCERTAIN)
4. 每条结果附带上下文（前后50字符）

**输出：** landing_report.md

**全人工模式：** 用户自行对照修改记录检查docx。skill记录检查结果。

---

### M3：跨章引用交叉 `[机械提取 + LLM判断]`

**输入：** `thesis_full.txt`

**处理：**
1. 正则提取所有[N]引用 + 上下文（前后各100字符）+ 章节位置 → citation_map.json
2. 频率统计 + 分层（≥5核心/3-4重点/2普通/1低频）→ citation_frequency.json
3. 对≥3次的引用，比较各处使用一致性 → CONSISTENT/DIFFERENT_ASPECT/CONTRADICTORY
4. 报告 → cross_ref_report.md

**覆盖率校验：** 输出"检测到N个唯一引用编号，bib有M条"。差异非零时告警——可能是提取遗漏或bib冗余。

**全人工模式：** skill只输出citation_map.json（引用在哪里出现的地图），用户自行检查高频引用的使用一致性。

---

### M4：引用溯源 `[调用ref-verifier]`

**这是全管线中最关键也最耗时的模块。支持三种操作粒度。**

**粒度A：逐句模式（最精细，用于承重引用）**
```
用户：粘贴一句含[N]的原文
skill：识别引用编号 → 查bib → 拉摘要 → 输出比对结果
用户：判定 → 下一句
```
skill在这个模式下是辅助工具——拉数据、格式化比对、记录结果。判定由用户在对话中完成。

**粒度B：batch模式（中等，用于框架引用）**
```
skill：从citation_map中按分层筛选目标 → 分批（≤10ref/≤30claim）
      → 调用ref-verifier核心判定逻辑 → 输出批次报告
用户：审核FAIL和PARTIAL-A条目 → 确认后skill处理下一批
```
batch间有人类检查窗口。用户可以在任何一批后切换到逐句模式或全人工模式。

**粒度C：全人工模式（用于用户想完全自控的部分）**
```
用户：自行逐句核查
skill：记录结果、更新MASTER、提醒未覆盖的引用
```

**推荐的分层策略：**
- 承重引用（10-20条）→ 粒度A
- 框架引用（50-70条）→ 粒度B
- 装饰引用（50-60条）→ 粒度B（lenient标准）或粒度C
- 用户随时可以调整任何引用的粒度

**输出格式要求：**
无论哪种粒度，每条判定都必须附带：
```markdown
**[29] Smith 2015, Ch2 约第215行**
> ......关键预测因子是唯一显著的危险因素（adj.OR=1.128, **[29]**），与Smith等......
**Claim:** 关键预测因子是主结局的独立危险因素
**Severity:** strict（引用了具体OR值）
**摘要关键段:** "...the key predictor was significantly associated with the primary outcome (OR=1.13, 95%CI 1.01-1.25)..."
**判定:** PASS (NUM_OK: 1.128 ≈ 1.13, 差异在四舍五入范围内)
```

**Backlog机制：** API失败、CrossRef无摘要、数值需全文验证的条目进入backlog.md，下一轮接续处理。

---

### M5：跨章一致性 `[机械 + LLM]`

**输入：** `thesis_full.txt` + `variable_definitions.json`（可选）

**检测维度：**
| 维度 | 方法 | 示例 |
|------|------|------|
| 公式方向 | 搜索公式定义，比对各章符号 | (T2-T1)/T1 vs (T1-T2)/T1（方向相反） |
| 分析单位 | 搜索"例""部位/位点"在各章方法段的使用 | 第一章"患者" vs 第二章"部位" |
| 样本量 | 提取各章N值，检测子集关系 | 示例嵌套：N1 → N2 → N3 |
| 术语 | 搜索核心术语变体 | 同一概念的中英/同义表述不统一（需按自己研究领域的概念族定制） |
| 阈值定义 | 搜索二分类阈值 | `>=X%` vs `>X%`（开闭区间不一致） |
| 处理/测量方法 | 比对各章方法描述 | AI自动处理 vs 手动处理 |

**输出：** consistency_report.md。每条不一致附带各章原文引用。

**全人工模式：** skill输出变量定义提取结果（"在Ch1中，变量X定义为...；在Ch2中，定义为..."），用户自行比对判断。

---

### M6：格式扫描 + AI痕迹检测 `[纯机械]`

**输入：** `thesis_full.txt`

**检测项：**
1. 图表编号连续性（跳号/重复）
2. 中英文编号对应（表2-1 ↔ Table 2-1）
3. 统计符号格式一致性（H值精度、p/P统一）
4. 引用编号连续性
5. 单位一致性（mm/mm³/MPa/kPa）
6. 缩写首次定义检测
7. **AI写作痕迹扫描**（可选子模块）：
   - 检测高频AI词汇："范式""值得注意的是""具有重要意义""在...方面发挥着关键作用"
   - 检测三段式结构过度使用
   - 检测否定式排比（"不仅...而且...更..."连续出现）
   - 输出：每个命中附带原文位置+上下文

**输出：** format_report.md

**全人工模式：** skill输出检测项清单作为手动检查的对照表。

---

### M9：Bug回归 `[机械 + LLM]`

**输入：** `old_bugs.json` + `thesis_full.txt`（新版）

**处理：**
1. 对每个旧bug，用关键短语在新版中定位
2. 提取新版上下文
3. 判定：FIXED / STILL_PRESENT / PARTIAL / LOCATION_SHIFTED / CANNOT_LOCATE
4. 报告 → regression_report.md

**全人工模式：** skill输出旧bug清单+新版对应位置的上下文，用户逐条人脑判定是否修复。

---

## 外部skill调用

### M7：图表审查

当前作为thesis-qc内置模块实现。如果复杂度增长，未来可独立。

**输入：** 图片文件 + `thesis_full.txt` + 数据表格（可选）

**4维度检查：**
1. 图注 ↔ 正文描述一致性
2. 图中数据标签 ↔ 对应表格数值匹配
3. 轴标签、图例、单位正确性
4. 图编号 ↔ 正文引用对应

**输出：** figure_audit_report.md

**全人工模式：** skill输出图表-正文引用对照表，用户逐图检查。

### M8：讨论层批判审查 → thesis-critical-review

独立skill，有自己的SKILL.md（见 `skills/thesis-critical-review/SKILL.md`）。

thesis-qc在Phase 8调用它。用户也可以随时独立触发（`/thesis-critical-review`）。

thesis-qc的职责限于：在MASTER中记录M8的执行状态和发现数。

---

## MASTER_QC.md 管理

### 初始化模板

```markdown
---
创建日期：YYYY-MM-DD
论文版本：[文件名]
bib版本：[文件名]
最后更新：YYYY-MM-DD
更新者：[人/Claude]
---

# MASTER_QC

## 当前状态
[一句话]

## 管线进度

| Phase | 模块 | 模式 | 状态 | 完成日期 | 报告文件 | CRITICAL | MAJOR | 用户确认 |
|-------|------|------|------|---------|---------|----------|-------|---------|
| 0 | 初始化 | — | ⬜ | | | | | ⬜ |
| 1 | M1 引用完整性 | auto/manual | ⬜ | | | | | ⬜ |
| 2 | M2 修改落地 | auto/manual | ⬜ | | | | | ⬜ |
| 3 | M3 跨章引用 | auto/manual | ⬜ | | | | | ⬜ |
| 4 | M4 引用溯源 | A/B/C | ⬜ | | | | | ⬜ |
| 5 | M5 跨章一致性 | auto/manual | ⬜ | | | | | ⬜ |
| 6 | M6 格式扫描 | auto/manual | ⬜ | | | | | ⬜ |
| 7 | M7 图表审查 | auto/manual | ⬜ | | | | | ⬜ |
| 8 | M8 批判审查 | — | ⬜ | | | | | ⬜ |
| 9 | M9 Bug回归 | auto/manual | ⬜ | | | | | ⬜ |

## 交叉验证规则
1. 脚本输出"严重问题" → 换方法重跑再信
2. 结论导致不可逆操作 → 换路径确认
3. 不同会话给出不同结论 → 回溯确认

## 已决事项
（人确认后记录，不再讨论）

## 已撤回/拒绝事项
（不再复活）

## Action Items
| 优先级 | 来源 | 问题 | 原文证据 | 处置 | 状态 | 用户确认 |
|--------|------|------|---------|------|------|---------|

## 文件清单
| 文件 | 类型 | 来源模块 | 说明 |
|------|------|---------|------|
```

### 状态翻转规则

- **Phase状态：** skill完成检测后标记为"待确认"(🔄)。用户审核报告后说"确认Phase X完成"，skill才标记✅
- **Action Items：** skill发现问题后创建条目。用户处理后说"关闭Action #N"，skill才标记完成
- **已决/已撤回：** 只有用户可以写入这两个section

---

## 数据格式规范

### 通用JSON头

```json
{
  "meta": {
    "skill": "thesis-qc",
    "module": "M1",
    "version": "0.2.0",
    "generated_at": "2026-04-13T14:00:00",
    "input_files": ["thesis_full.txt", "refs.bib"],
    "thesis_version": "v10.0"
  },
  "data": { ... }
}
```

### 报告通用头

```markdown
# [报告标题]
> 生成时间: YYYY-MM-DD HH:MM
> 技能版本: thesis-qc 0.2.0
> 模块: M[N]
> 运行模式: auto / manual / 混合
> 输入文件: [列表]
> 论文版本: [版本号]
```

### 原文上下文格式（强制）

所有判定类条目必须包含：
```markdown
**[引用编号] 作者 年份, 章节 约第N行**
> ......前一句。**包含引用标记的句子**。后一句......
```

---

## 可扩展性

未来新skill只需遵循三条约定即可被thesis-qc挂载：

1. **输入：** 接受 `thesis_full.txt` 或 thesis-qc的标准JSON中间文件
2. **输出：** 产出 `xxx_report.md`（人读） + `xxx.json`（管线读），遵循通用头
3. **发现分级：** CRITICAL / MAJOR / MINOR / COSMETIC

thesis-qc负责在MASTER进度表中加一行、在合适的Phase调用新skill。不需要预建adapter。

---

## 与现有skill的关系

| skill | 关系 |
|-------|------|
| ref-verifier | M4调用其核心判定逻辑。thesis-qc负责分层筛选和backlog管理 |
| thesis-critical-review | M8调用。独立skill，可单独触发 |
| literature-search-omfs | M4发现FAIL时，可能需要搜索替代引用。手动触发 |
| dr-reconstruct | 如果论文使用了DR产出，在M1之前应先跑dr-reconstruct |
| humanizer / humanizer-zh | 不在QC管线内。M8产出建议文字时，提醒用户写入论文前过humanizer |
| self-verify | M4交叉验证是其扩展版 |

---

## 已知局限

1. docx解析依赖纯文本提取，表格结构可能丢失
2. M7需要vision能力
3. M8完全依赖LLM判断
4. M4摘要级验证精度上限：PASS ≠ "原文完整证实"
5. 中文/英文论文正则pattern不同，当前基于中文经验

---

## 迭代计划

- **v0.2:** SKILL.md设计文档（当前）
- **v0.3:** M1+M6 机械模块实现 + MASTER模板
- **v0.4:** M3 引用交叉实现
- **v0.5:** M4 与ref-verifier的集成 + 逐句/batch双模式
- **v0.6:** M5+M9 实现
- **v0.7:** 在真实论文上端到端验证
- **v0.8:** thesis-critical-review 独立skill
- **v1.0:** 英文论文支持 + LaTeX/BibTeX原生支持