ssci-subagent-skills 1.0.0

package/skills/performing-axial-coding/references/_BACKUP_troubleshooting.md

@@ -0,0 +1,627 @@
+# 轴心编码故障排除指南
+
+> **渐进式披露**：本文档提供常见问题的快速诊断和解决方案。理论基础见`paradigm-theory.md`，完整案例见`category-examples.md`。
+
+## 快速诊断表
+
+| 症状 | 可能问题 | 解决方案 | 参考章节 |
+|-----|---------|---------|---------|
+| 范畴过于宽泛 | 聚类数量太少 | 增加聚类数量，细化范畴 | 问题1 |
+| 概念归属不明确 | 范畴边界模糊 | 重新定义范畴，明确区分标准 | 问题2 |
+| 关系论证不充分 | 数据支持不足 | 回到原始数据，寻找更多证据 | 问题3 |
+| Paradigm不完整 | 缺少关键组件 | 系统检查六个组件，补充缺失部分 | 问题4 |
+| 工具输出不合理 | 参数设置不当 | 调整工具参数，结合人工判断 | 问题5 |
+| 范畴命名不当 | 缺乏理论敏感性 | 参考理论文献，使用行动导向命名 | 问题6 |
+
+## 问题1：范畴过于宽泛
+
+### 症状识别
+
+**表现**：
+- 单个范畴包含10个以上概念
+- 范畴内的概念差异很大
+- 范畴定义过于笼统（如"学习行为"）
+- 难以为范畴提供清晰的典型案例
+
+**案例**：
+```
+范畴：学习相关行为
+包含概念：上课、复习、预习、做作业、考试、讨论、提问、记笔记、查资料、思考...（15个）
+```
+
+**问题**：这个范畴过于宽泛，缺乏理论意义。
+
+### 诊断方法
+
+**1. 检查范畴内部一致性**：
+```bash
+# 使用工具检查范畴质量
+python scripts/validate_categories.py --input categories.json --output validation.json
+```
+
+查看`internal_consistency`分数：
+- < 0.6：范畴过于宽泛，需要拆分
+- 0.6-0.8：可以接受，但可以优化
+- > 0.8：内部一致性良好
+
+**2. 人工检查**：
+- 范畴内的概念是否都指向同一个理论概念？
+- 能否用一句话清晰地定义这个范畴？
+- 范畴内的概念是否有明显的子类？
+
+### 解决方案
+
+**方案A：增加聚类数量**
+
+```bash
+# 重新运行聚类，增加范畴数量
+python scripts/identify_categories.py \
+  --input codes.json \
+  --output categories_v2.json \
+  --n_categories 8  # 从5增加到8
+```
+
+**方案B：手动拆分范畴**
+
+将"学习相关行为"拆分为：
+1. **课堂学习行为**：上课、记笔记、提问
+2. **课后学习行为**：复习、预习、做作业
+3. **深度学习行为**：查资料、思考、讨论
+
+**方案C：提升抽象层次**
+
+如果概念确实相关，考虑提升到更抽象的理论层次：
+- 不是"学习相关行为"（过于具体）
+- 而是"主动学习策略"（有理论意义）
+
+### 验证
+
+拆分后，检查：
+- ✅ 每个范畴包含3-8个概念
+- ✅ 范畴内概念高度相关
+- ✅ 范畴定义清晰具体
+- ✅ 能提供典型案例
+
+## 问题2：概念归属不明确
+
+### 症状识别
+
+**表现**：
+- 某些概念可以归入多个范畴
+- 工具将同一概念在不同运行中归入不同范畴
+- 研究者难以判断概念应该归入哪个范畴
+
+**案例**：
+```
+概念："向同学请教问题"
+
+可能归属：
+- 范畴A：主动寻求学业支持（强调"寻求帮助"）
+- 范畴B：建立社会支持网络（强调"与同学互动"）
+```
+
+### 诊断方法
+
+**1. 使用工具识别模糊概念**：
+
+```bash
+python scripts/compare_codes.py \
+  --input concepts.json \
+  --output comparison.json \
+  --threshold 0.5  # 与多个范畴相似度>0.5的概念
+```
+
+查看`ambiguous_concepts`字段：
+```json
+{
+  "ambiguous_concepts": [
+    {
+      "concept": "向同学请教问题",
+      "similar_categories": [
+        {"category": "主动寻求学业支持", "similarity": 0.72},
+        {"category": "建立社会支持网络", "similarity": 0.68}
+      ]
+    }
+  ]
+}
+```
+
+**2. 人工检查**：
+- 这个概念的核心意义是什么？
+- 在访谈中，这个概念主要用来说明什么？
+- 这个概念与哪个范畴的其他概念最相关？
+
+### 解决方案
+
+**方案A：明确范畴边界**
+
+重新定义范畴，明确区分标准：
+
+```
+范畴A：主动寻求学业支持
+定义：以获得学业帮助为主要目的的行为
+关键特征：目的是解决学习问题、获得知识
+
+范畴B：建立社会支持网络
+定义：以建立和维护社会关系为主要目的的行为
+关键特征：目的是建立友谊、获得情感支持
+```
+
+**判断**："向同学请教问题"的主要目的是解决学习问题，归入范畴A。
+
+**方案B：创建桥接概念**
+
+如果概念确实同时具有两个范畴的特征，考虑：
+1. 将其作为连接两个范畴的"桥接概念"
+2. 在关系分析中，标注这个概念连接了两个范畴
+
+**方案C：拆分概念**
+
+如果概念包含多个维度，考虑拆分：
+- "向同学请教学习问题" → 范畴A
+- "与同学建立学习伙伴关系" → 范畴B
+
+### 验证
+
+解决后，检查：
+- ✅ 每个概念只归入一个范畴
+- ✅ 范畴边界清晰
+- ✅ 归属判断有明确的理由
+
+## 问题3：关系论证不充分
+
+### 症状识别
+
+**表现**：
+- 关系的数据支持少于3个片段
+- 关系的逻辑不清晰
+- 关系的强度评分低（<0.5）
+- 审稿人质疑关系的证据
+
+**案例**：
+```
+关系：个人性格 → 学业成绩
+证据：只有1个受访者提到"我性格内向，成绩不太好"
+强度：0.3（弱）
+```
+
+**问题**：证据不足，逻辑不清晰（性格如何影响成绩？）
+
+### 诊断方法
+
+**1. 使用工具检查关系强度**：
+
+```bash
+python scripts/build_relationships.py \
+  --input categories.json \
+  --output relationships.json \
+  --min_strength 0.5  # 只保留强度>0.5的关系
+```
+
+查看`weak_relations`字段（强度<0.5的关系）：
+```json
+{
+  "weak_relations": [
+    {
+      "source": "个人性格",
+      "target": "学业成绩",
+      "strength": 0.3,
+      "evidence_count": 1,
+      "issue": "证据不足"
+    }
+  ]
+}
+```
+
+**2. 人工检查**：
+- 这个关系有多少数据支持？
+- 关系的逻辑链条是否清晰？
+- 是否有反例（关系不成立的情况）？
+
+### 解决方案
+
+**方案A：回到原始数据寻找证据**
+
+重新阅读访谈记录，寻找支持这个关系的更多证据：
+
+```
+搜索关键词："性格" + "成绩" / "学习"
+搜索关键词："内向" / "外向" + "适应" / "困难"
+```
+
+**发现**：
+- 学生A："我性格内向，不敢问老师，所以很多问题没解决，成绩不好。"
+- 学生B："我比较外向，遇到问题就问，成绩提高很快。"
+- 学生C："我虽然内向，但我会自己查资料，成绩也不错。"
+
+**修正关系**：
+```
+原关系：个人性格 → 学业成绩（直接因果，证据不足）
+
+修正后：
+个人性格 → 寻求帮助行为 → 学业成绩（间接因果，证据充分）
+- 内向者较少寻求帮助，但可能通过其他方式（如自学）弥补
+- 外向者更多寻求帮助，获得支持后成绩提升
+```
+
+**方案B：降低关系的强度声明**
+
+如果证据确实不足，诚实报告：
+```
+"数据显示个人性格可能影响学业成绩（强度：0.3，弱关系），但证据有限，需要进一步研究。"
+```
+
+**方案C：删除证据不足的关系**
+
+如果关系的证据少于3个片段，且逻辑不清晰，考虑删除：
+```bash
+# 使用工具过滤弱关系
+python scripts/build_relationships.py \
+  --input categories.json \
+  --output relationships_filtered.json \
+  --min_strength 0.5 \
+  --min_evidence 3
+```
+
+### 验证
+
+解决后，检查：
+- ✅ 每个关系至少有3个数据片段支持
+- ✅ 关系的逻辑链条清晰
+- ✅ 关系强度≥0.5
+- ✅ 考虑了反例和例外情况
+
+## 问题4：Paradigm模型不完整
+
+### 症状识别
+
+**表现**：
+- Paradigm的某些组件缺失（如缺少"结果"）
+- 逻辑链条不连贯（条件→现象→行动→结果）
+- 模型无法解释大部分数据
+
+**案例**：
+```
+Paradigm模型：
+- 现象：学业适应困难 ✅
+- 因果条件：学习方法差异 ✅
+- 语境：重点大学环境 ✅
+- 行动策略：寻求帮助、调整方法 ✅
+- 中介条件：？ ❌ 缺失
+- 结果：？ ❌ 缺失
+```
+
+### 诊断方法
+
+**1. 使用工具检查完整性**：
+
+```bash
+python scripts/construct_paradigm.py \
+  --input relationships.json \
+  --output paradigm.json \
+  --validate
+```
+
+查看`validation`字段：
+```json
+{
+  "validation": {
+    "is_complete": false,
+    "missing_components": ["intervening_conditions", "consequences"],
+    "completeness_score": 0.67
+  }
+}
+```
+
+**2. 人工检查**：
+使用Paradigm检查清单：
+- [ ] 现象：核心研究现象是什么？
+- [ ] 因果条件：为什么会出现这个现象？
+- [ ] 语境：在什么情境下出现？
+- [ ] 中介条件：什么因素影响行动的效果？
+- [ ] 行动策略：人们做了什么来应对？
+- [ ] 结果：行动的结果是什么？
+
+### 解决方案
+
+**方案A：系统补充缺失组件**
+
+**补充中介条件**：
+- 回到数据，询问："为什么同样的策略，有的人有效，有的人无效？"
+- 识别促进或限制因素：个人性格、社会支持、学校资源
+
+**补充结果**：
+- 回到数据，询问："采取这些行动后，发生了什么？"
+- 识别短期结果（成绩提升）和长期结果（学习能力提升）
+- 识别预期结果和非预期结果
+
+**方案B：调整Paradigm模型**
+
+如果某些组件确实缺失，考虑：
+1. 是否选错了核心现象？
+2. 是否需要收集更多数据？
+3. 是否可以使用简化的Paradigm（如只包含条件-行动-结果）？
+
+**方案C：使用工具辅助识别**
+
+```bash
+# 使用工具自动识别缺失组件
+python scripts/construct_paradigm.py \
+  --input relationships.json \
+  --output paradigm_complete.json \
+  --auto_complete  # 自动补充缺失组件
+```
+
+工具会基于现有关系，推荐可能的中介条件和结果。
+
+### 验证
+
+补充后，检查：
+- ✅ 所有六个组件都存在
+- ✅ 逻辑链条连贯（条件→现象→行动→结果）
+- ✅ 每个组件都有充分的数据支持
+- ✅ 模型能够解释大部分数据
+
+## 问题5：工具输出不合理
+
+### 症状识别
+
+**表现**：
+- 工具将明显不相关的概念聚类到一起
+- 工具识别的关系不符合逻辑
+- 工具的参数设置不知道如何调整
+
+**案例**：
+```
+工具输出：
+范畴1包含：["寻求帮助", "感到焦虑", "制定计划"]
+```
+
+**问题**：这三个概念不应该在同一个范畴。
+
+### 诊断方法
+
+**1. 检查工具参数**：
+
+```bash
+# 查看当前参数设置
+python scripts/identify_categories.py --help
+```
+
+关键参数：
+- `--n_categories`：聚类数量（默认5，可调整为3-10）
+- `--min_codes`：每个范畴最少概念数（默认3）
+- `--method`：聚类方法（kmeans/hierarchical）
+
+**2. 检查输入数据质量**：
+
+工具依赖高质量的输入数据：
+- 概念命名是否规范？
+- 概念定义是否清晰？
+- 是否有明显的拼写错误或重复？
+
+### 解决方案
+
+**方案A：调整工具参数**
+
+**增加聚类数量**：
+```bash
+python scripts/identify_categories.py \
+  --input codes.json \
+  --output categories.json \
+  --n_categories 8  # 从5增加到8
+```
+
+**更换聚类方法**：
+```bash
+python scripts/identify_categories.py \
+  --input codes.json \
+  --output categories.json \
+  --method hierarchical  # 从kmeans改为层次聚类
+```
+
+**调整最小概念数**：
+```bash
+python scripts/identify_categories.py \
+  --input codes.json \
+  --output categories.json \
+  --min_codes 2  # 从3降低到2，允许更小的范畴
+```
+
+**方案B：清理输入数据**
+
+在运行工具前：
+1. 检查概念命名是否规范
+2. 合并明显重复的概念
+3. 删除质量差的概念
+
+```bash
+# 使用验证工具检查输入质量
+python scripts/validate_codes.py --input codes.json --output validation.json
+```
+
+**方案C：结合人工判断**
+
+工具只是辅助，最终判断需要研究者：
+1. 使用工具生成初步聚类
+2. 人工检查和调整
+3. 重新定义范畴边界
+4. 手动移动概念
+
+### 验证
+
+调整后，检查：
+- ✅ 工具输出合理
+- ✅ 范畴内概念相关
+- ✅ 范畴间区分明确
+
+## 问题6：范畴命名不当
+
+### 症状识别
+
+**表现**：
+- 范畴名称过于具体（如"去图书馆学习"）
+- 范畴名称过于抽象（如"行为"）
+- 范畴名称是名词而非动词短语（如"帮助"）
+- 范畴名称缺乏理论意义
+
+**案例**：
+```
+❌ 不好的命名：
+- "帮助"（名词，过于简单）
+- "学生的学习行为"（过于宽泛）
+- "去图书馆学习"（过于具体）
+
+✅ 好的命名：
+- "主动寻求学业支持"（动词短语，行动导向）
+- "调整学习策略"（有理论意义）
+- "建立社会支持网络"（清晰具体）
+```
+
+### 解决方案
+
+**方案A：遵循命名原则**
+
+**1. 行动导向**：使用动词开头
+- "寻求"、"调整"、"建立"、"应对"
+
+**2. 适度抽象**：不过具体，不过抽象
+- 过具体："去图书馆复习高数"
+- 适度："调整学习方法"
+- 过抽象："学习"
+
+**3. 理论意义**：体现理论概念
+- 不仅是"帮助"，而是"主动寻求学业支持"（体现主动性）
+- 不仅是"方法"，而是"调整学习策略"（体现适应过程）
+
+**方案B：参考理论文献**
+
+查阅相关理论文献，借鉴理论术语：
+- 社会支持理论 → "社会支持网络"
+- 自我调节理论 → "自我监控和调整"
+- 应对理论 → "应对策略"
+
+**方案C：使用工具建议**
+
+```bash
+python scripts/identify_categories.py \
+  --input codes.json \
+  --output categories.json \
+  --suggest_names  # 工具会建议范畴名称
+```
+
+工具基于范畴内最高频的概念建议名称，但需要人工精炼。
+
+### 验证
+
+命名后，检查：
+- ✅ 使用动词短语
+- ✅ 抽象层次适当
+- ✅ 有理论意义
+- ✅ 清晰易懂
+
+## 技术问题排查
+
+### 问题7：工具运行报错
+
+**常见错误1**：`FileNotFoundError`
+```
+解决：检查输入文件路径是否正确
+python scripts/identify_categories.py --input codes.json  # 确保codes.json存在
+```
+
+**常见错误2**：`KeyError: 'concept'`
+```
+解决：检查输入JSON格式是否正确
+输入文件应该包含：
+{
+  "details": {
+    "concepts": [
+      {"concept": "...", "frequency": 10, "definition": "..."},
+      ...
+    ]
+  }
+}
+```
+
+**常见错误3**：`ModuleNotFoundError: No module named 'jieba'`
+```
+解决：安装依赖
+uv pip install jieba pandas scikit-learn networkx
+```
+
+**常见错误4**：工具运行很慢
+```
+解决：
+1. 减少概念数量（<100个）
+2. 使用更快的聚类方法（kmeans而非hierarchical）
+3. 减少聚类数量
+```
+
+### 问题8：输出文件格式问题
+
+**症状**：输出的JSON文件无法被下一个工具读取
+
+**解决**：
+```bash
+# 使用工具验证输出格式
+python scripts/validate_output.py --input categories.json
+
+# 转换格式
+python scripts/convert_format.py --input old_format.json --output new_format.json
+```
+
+## 预防性最佳实践
+
+### 1. 定期备份
+
+在每次重大修改前备份：
+```bash
+cp categories.json categories_backup_20251219.json
+```
+
+### 2. 版本控制
+
+使用版本号追踪修改：
+```
+categories_v1.json  # 工具初步输出
+categories_v2.json  # 人工精炼后
+categories_v3.json  # 调整范畴边界后
+categories_final.json  # 最终版本
+```
+
+### 3. 撰写备忘录
+
+记录每次重要决策：
+```
+备忘录：为什么将"向同学请教"归入"寻求学业支持"而非"建立社会网络"？
+理由：访谈中学生强调的是"解决学习问题"而非"建立友谊"。
+日期：2025-12-19
+```
+
+### 4. 定期验证
+
+每完成一个阶段，运行验证：
+```bash
+# 验证范畴质量
+python scripts/validate_categories.py --input categories.json
+
+# 验证关系质量
+python scripts/validate_relationships.py --input relationships.json
+
+# 验证Paradigm完整性
+python scripts/construct_paradigm.py --input relationships.json --validate
+```
+
+## 寻求帮助
+
+如果以上方案都无法解决问题：
+
+1. **查阅理论文献**：Strauss & Corbin (1998), 陈向明 (2000)
+2. **咨询导师或同行**：讨论理论判断
+3. **回到原始数据**：重新阅读访谈记录
+4. **考虑收集更多数据**：如果数据不足以支持理论构建
+
+---
+
+*本指南基于真实研究中遇到的问题编写，提供实用的诊断和解决方案。*