质性主题分析

基于Braun & Clarke六阶段法，对本地质性资料（访谈、观察、文本）进行系统性主题归纳、编码及报告生成。

质性研究主题分析 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：完整六阶段，强制编码表输出，耗时较长