- name
- qualitative-thematic-analysis
- description
- 质性研究主题分析（Thematic Analysis）工具。基于 Braun & Clarke 经典六阶段方法，对本地存储的质性资料（访谈记录、观察笔记、文本资料等）进行系统性主题分析，生成编码表、主题树和分析报告。
质性研究主题分析 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）
为每个主题：
- 写出清晰的主题名称（简洁、有实质内容）
- 写出主题定义（2-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：完整六阶段，强制编码表输出，耗时较长