会话分析器技能

用于根据 SKILL.md 规范验证 Claude Code 会话行为的事后分析工具。

目的

分析已完成的会话以验证：

1. 预期与实际行为 – 技能是否遵循了 SKILL.md 工作流？
2. 组件调用 – 子智能体、钩子和工具是否被正确调用？
3. 产物 – 预期文件是否被创建/删除？
4. 缺陷检测 – 是否存在任何意外错误或偏差？

输入要求

阶段 1：定位会话文件

步骤 1.1：查找会话文件

会话文件位于 ~/.claude/ 中：

# 主会话日志
~/.claude/projects/-{编码后的工作目录}/{会话ID}.jsonl

# 调试日志（详细）
~/.claude/debug/{会话ID}.txt

# 智能体记录（如果使用了子智能体）
~/.claude/projects/-{编码后的工作目录}/agent-{智能体ID}.jsonl

使用脚本定位文件：

${baseDir}/scripts/find-session-files.sh {会话ID}

步骤 1.2：验证文件存在

在继续之前检查所有必需文件是否存在。如果调试日志缺失，分析将受限。

阶段 2：解析目标 SKILL.md

步骤 2.1：提取预期组件

读取目标 SKILL.md 并识别：

从 YAML 前置元数据中：

• hooks.PreToolUse – 预期的 PreToolUse 钩子及其匹配器
• hooks.PostToolUse – 预期的 PostToolUse 钩子
• hooks.Stop – 预期的 Stop 钩子
• hooks.SubagentStop – 预期的 SubagentStop 钩子
• allowed-tools – 技能允许使用的工具

从 Markdown 正文中：

• 提及的子智能体（Task(subagent_type="...")）
• 调用的技能（Skill("...")）
• 创建的产物（.dev-flow/drafts/、.dev-flow/plans/ 等）
• 工作流步骤和条件

步骤 2.2：构建预期行为检查清单

从 SKILL.md 分析中创建检查清单：

## 预期行为

### 子智能体
- [ ] 调用了探索智能体（并行，后台运行）
- [ ] 在计划生成前调用了差距分析器
- [ ] 在计划创建后调用了审查员

### 钩子
- [ ] PreToolUse[Edit|Write] 触发了 plan-guard.sh
- [ ] Stop 钩子验证了审查员批准

### 产物
- [ ] 在 .dev-flow/drafts/{名称}.md 创建了草稿文件
- [ ] 在 .dev-flow/plans/{名称}.md 创建了计划文件
- [ ] 在确认后草稿文件被删除

### 工作流
- [ ] 在计划生成前进入访谈模式
- [ ] 用户明确请求触发了计划生成
- [ ] 审查员拒绝导致修订循环

阶段 3：分析调试日志

调试日志（~/.claude/debug/{会话ID}.txt）包含详细的执行跟踪。

步骤 3.1：提取子智能体调用

搜索模式：

SubagentStart with query: {智能体名称}
SubagentStop with query: {智能体ID}

使用脚本：

${baseDir}/scripts/extract-subagent-calls.sh {调试日志路径}

步骤 3.2：提取钩子事件

搜索模式：

Getting matching hook commands for {钩子事件} with query: {工具名称}
Matched {N} unique hooks for query "{查询}"
Hooks: Processing prompt hook with prompt: {提示}
Hooks: Prompt hook condition was met/not met
permissionDecision: allow/deny

使用脚本：

${baseDir}/scripts/extract-hook-events.sh {调试日志路径}

步骤 3.3：提取工具调用

搜索模式：

executePreToolHooks called for tool: {工具名称}
File {路径} written atomically

步骤 3.4：提取钩子结果

对于基于提示的钩子，找到模型响应：

Hooks: Model response: {
  "ok": true/false,
  "reason": "..."
}

阶段 4：验证产物

步骤 4.1：检查文件创建

对于每个预期的产物：

1. 在调试日志中搜索 FileHistory: Tracked file modification for {路径}
2. 搜索 File {路径} written atomically
3. 验证当前文件系统状态

步骤 4.2：检查文件删除

对于应该被删除的文件：

1. 在 Bash 调用中搜索 rm 命令
2. 验证文件在文件系统中已不存在

阶段 5：比较预期与实际

步骤 5.1：构建对比表

| 组件 | 预期 | 实际 | 状态 |
|-----------|----------|--------|--------|
| 探索智能体 | 2 次并行调用 | 在 09:39:26 有 2 次调用 | ✅ |
| 差距分析器 | 计划前调用 | 在 09:43:08 调用 | ✅ |
| 审查员 | 计划后调用 | 2 次调用 (拒绝→确认) | ✅ |
| PreToolUse 钩子 | Edit\|Write 匹配器 | 为 Write 触发 | ✅ |
| Stop 钩子 | 验证批准 | 返回 ok:true | ✅ |
| 草稿文件 | 创建后删除 | 创建→已删除 | ✅ |
| 计划文件 | 已创建 | 存在 (10KB) | ✅ |

步骤 5.2：识别偏差

标记任何不匹配项：

• 缺失的组件调用
• 错误的操作顺序
• 钩子失败
• 缺失的产物
• 意外错误

阶段 6：生成报告

报告模板

# 会话分析报告

## 会话信息
- **会话 ID**: {会话ID}
- **目标技能**: {技能路径}
- **分析日期**: {日期}

---

## 1. 预期行为 (来自 SKILL.md)

[预期工作流摘要]

---

## 2. 技能/子智能体/钩子验证

### 子智能体
| 子智能体 | 预期 | 实际 | 时间 | 结果 |
|----------|----------|--------|------|--------|
| ... | ... | ... | ... | ✅/❌ |

### 钩子
| 钩子 | 匹配器 | 是否触发 | 结果 |
|------|---------|-----------|--------|
| ... | ... | ... | ✅/❌ |

---

## 3. 产物验证

| 产物 | 路径 | 预期状态 | 实际状态 |
|----------|------|----------------|--------------|
| ... | ... | ... | ✅/❌ |

---

## 4. 问题/缺陷

| 严重程度 | 描述 | 位置 |
|----------|-------------|----------|
| ... | ... | ... |

---

## 5. 总体结果

**结论**: ✅ 通过 / ❌ 失败

**总结**: [1-2 句总结]

脚本参考

使用示例

用户：“分析会话 3cc71c9f-d27a-4233-9dbc-c4f07ea6ec5b 是否符合 .claude/skills/specify/SKILL.md”

1. 查找会话文件
2. 解析 SKILL.md → 预期：探索智能体、差距分析器、审查员、钩子
3. 分析调试日志 → 提取实际调用
4. 验证产物 → 检查 .dev-flow/
5. 比较 → 构建验证表
6. 生成报告 → 通过/失败，附带详情

附加资源

参考文件

• references/analysis-patterns.md – 用于日志分析的详细 grep 模式
• references/common-issues.md – 已知问题和故障排除

脚本

• scripts/find-session-files.sh – 会话文件定位器
• scripts/extract-subagent-calls.sh – 子智能体调用提取器
• scripts/extract-hook-events.sh – 钩子事件提取器