# Qualitative Thematic Analysis

> 质性研究主题分析（Thematic Analysis）工具。基于 Braun & Clarke 经典六阶段方法，对本地存储的质性资料（访谈记录、观察笔记、文本资料等）进行系统性主题分析，生成编码表、主题树和分析报告。

- Skill: `dvcrn/qualitative-thematic-analysis` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add dvcrn/qualitative-thematic-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/qualitative-thematic-analysis/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/qualitative-thematic-analysis

---


# 质性研究主题分析 Skill

## ⚠️ 启动前必检清单

在开始分析前，**必须**向用户确认以下信息（如未提供则主动询问）：

```
1. 📁 文件路径：资料存放在哪里？（完整路径，如 ~/Desktop/访谈资料/）
2. 📄 文件格式：TXT / DOCX / PDF / 其他？
3. 🗂️ 资料数量：共几份文件？
4. 📋 资料类型：访谈记录 / 观察笔记 / 焦点小组 / 文本语料 / 混合？
5. 🎯 研究问题：本次分析的核心研究问题是什么？
6. 📊 分析取向：归纳式（从资料中发现主题）还是演绎式（验证既有理论框架）？
```

**提问模板**（当信息不全时使用）：
> "我需要了解几个信息才能开始分析：
> 1. 资料文件存放在哪个路径？
> 2. 是什么类型的资料（访谈/观察/文本）？
> 3. 你的研究问题是什么？
> 告诉我这些，我就可以开始系统性的主题分析了。"

---

## 分析流程：Braun & Clarke 六阶段主题分析法

### 阶段一：熟悉资料（Familiarisation）

1. 读取所有文件（用 `scripts/extract_text.py` 提取文本）
2. 通读全部资料，记录初步印象
3. 向用户呈现：
   - 资料总字数 / 总条目数
   - 初步观察到的数据特征
   - 确认资料是否符合研究问题

### 阶段二：生成初始编码（Initial Coding）

- 系统性标注有意义的片段（语义单元）
- 每个编码：`[编码标签] → 原文引用`
- 编码原则：
  - 贴近资料语言（In vivo 编码优先）
  - 保留语境，不过早概括
  - 同一片段可多重编码
- 输出：初始编码列表（按出现顺序）

### 阶段三：归纳潜在主题（Theme Search）

- 将相关编码聚合为候选主题
- 构建初步主题地图（树状结构）
- 区分：主主题（Theme）vs 子主题（Sub-theme）
- 输出：候选主题树 + 每个主题下的编码列表

### 阶段四：审查主题（Theme Review）

对照以下标准审查每个主题：
- ✅ 主题内部编码一致（内聚性）
- ✅ 主题之间界限清晰（区分性）
- ✅ 主题能回应研究问题（相关性）
- ✅ 有足够的资料支撑（饱和性）

调整：合并过于相似的主题 / 拆分过于宽泛的主题 / 删除游离主题

### 阶段五：命名与定义主题（Defining & Naming）

为每个主题：
1. 写出清晰的主题名称（简洁、有实质内容）
2. 写出主题定义（2-3句话，说明该主题捕捉了什么）
3. 选取 2-3 条最具代表性的原文佐证（引用）

### 阶段六：撰写分析报告（Writing Up）

生成结构化分析报告，包含：
- 研究问题与资料概述
- 主题分析结果（主题树 + 各主题详述）
- 代表性引文
- 分析发现小结
- 研究局限与反思

---

## 输出格式

### 编码表（Excel 格式，用 scripts/export_coding.py 生成）

| 编码 | 子编码 | 原文片段 | 来源文件 | 行号 | 备注 |
|------|--------|----------|----------|------|------|

### 主题树（Markdown 树状图）

```
主题一：[名称]
├── 子主题 1.1：[名称]
│   ├── 编码：XXX
│   └── 编码：XXX
└── 子主题 1.2：[名称]
    └── 编码：XXX
主题二：[名称]
...
```

### 分析报告（DOCX，用 scripts/export_report.py 生成）

---

## 参考资源

- 详细方法论说明：`references/thematic-analysis-method.md`
- 编码操作指南：`references/coding-guide.md`
- 研究伦理提示：`references/ethics-note.md`

---

## ⚠️ 已知问题与迭代 TODO（v1 → v2）

> 来源：2026-03-10 真实演示复盘，一平反馈

### 问题1：分析深度不足 / 速度过快
- **现状**：当前实现在上下文窗口限制下仅读取文件摘录，未逐字通读全部材料
- **后果**：输出主题基于"感知归纳"而非系统编码，缺乏严谨性
- **迭代方向**：
  - 强制使用 `scripts/extract_text.py` 全量提取文本
  - 每份文件逐段打标签（初始码），不能跳过
  - 编码完成后才能归并子主题 → 主主题

### 问题2：跳过了 Braun & Clarke 中间阶段
- **现状**：直接从"读材料"跳到"输出主题"，跳过了初始编码、编码汇总、主题审查
- **迭代方向**：
  - 新增强制中间输出：初始码列表 → 子主题归并树 → 主题定义表
  - 每个主题必须附 ≥3条原文引证（带文件名+行号）

### 问题3：未输出编码表
- **现状**：`export_coding.py` 脚本存在但演示中未调用
- **迭代方向**：P1 完成时必须生成 Excel 编码表，作为强制输出物

### 问题4：无饱和度检验
- **迭代方向**：增加 P1.5 饱和度确认步骤——对比最后3份文件与前期编码，确认无新码出现

### 问题5：需要区分演示模式与研究模式
- **迭代方向**：增加 `mode` 参数
  - `demo`：快速出主题，明确标注"仅供展示，深度不足"
  - `research`：完整六阶段，强制编码表输出，耗时较长