质性研究主题分析 Skill

⚠️ 启动前必检清单

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

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

提问模板（当信息不全时使用）：

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

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

阶段一：熟悉资料（Familiarisation）

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

阶段二：生成初始编码（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：完整六阶段，强制编码表输出，耗时较长

qualitative-thematic-analysis

Installation