ln-002-session-analyzer

**路径：**文件路径（references/、../ln-*）相对于此技能目录。

会话分析器（独立工具）

**类型：**独立工具 **类别：**0XX Shared

分析会话中的错误、低效之处和改进机会。为技能、工具、钩子和沟通风格提出可操作的修复建议。

**范围：**单次会话深度分析（10 个维度）。范围比协议自审更广，比 /audit-sessions 批量分析更窄。 技能自审：references/meta_analysis_protocol.md §7。多日模式：/audit-sessions。

---

何时使用此技能

• 完成任务后——找出哪里出了问题，以及如何改进
• 定期使用——审查近期会话中的模式
• 技能运行后——分析技能指令的效果
• 调试工具／钩子问题时——从会话数据中找出根本原因

---

输入

$ARGUMENTS：

• （空）——分析当前会话（对话上下文）
• recent——扫描每个 Agent（Claude、Codex）的最新 JSONL 会话
• {skill-name}——聚焦分析该技能在会话中的执行情况

hex-line 是用于处理大型本地会话日志和仓库文件的可选加速工具。如果 MCP 不可用，请继续使用内置的 Read/Grep/Glob/Bash；此技能绝不能因 MCP 连接问题而阻塞。

---

维度

#	维度	扫描内容	改进目标
D1	工具错误	NOOP_EDIT、TEXT_NOT_FOUND、哈希不匹配、超出范围	SKILL.md 步骤——添加路径、锚点
D2	工具浪费	未先查看大纲就完整读取、重复读取、回退到 bash	SKILL.md——“先查看大纲”，注明 MCP 工具名称
D3	流程问题	工具循环 3 次以上、重试风暴、陷入僵局、目标错误	SKILL.md 阶段——分解任务
D4	脚本提取	每次运行都编写临时 bash/python 脚本	references/scripts/
D5	钩子与权限	钩子拦截、权限拒绝、使用内置工具而非 MCP	钩子配置、allowed-tools
D6	沟通	过度解释、缺少状态更新、不必要的确认	CLAUDE.md 偏好设置、技能输出说明
D7	决策质量	转向前陷入僵局、反复试错、错误检测缓慢	SKILL.md 决策树、步骤清晰度
D8	上下文压力	反复读取相同文件、重复询问已解决的问题、线程丢失	缓存说明、精简指令
D9	子 Agent 质量	结果为空、超时、提示词范围过宽	Agent 提示词、超时设置
D10	范围偏移	偏离目标、意外扩大范围、无故转向	范围约束、目标关卡

---

阶段 1：收集会话数据

根据 $ARGUMENTS 确定来源：

当前会话（参数为空）

直接扫描对话上下文。你可以访问所有工具调用结果、错误和消息。

近期会话（参数为 recent）

查找每个 Agent 的最新会话：

echo "=== LATEST SESSIONS ==="

echo "## Claude"
CLAUDE_LATEST=$(stat -c '%Y %n' ~/.claude/projects/*/*.jsonl 2>/dev/null | sort -rn | head -1 | cut -d' ' -f2-)
[ -n "$CLAUDE_LATEST" ] && echo "  $CLAUDE_LATEST ($(wc -l < "$CLAUDE_LATEST") lines)" || echo "  No sessions found"

echo "## Claude Active Sessions"
for f in "$HOME/.claude/sessions"/*.json; do
  [ -f "$f" ] || continue
  PID=$(basename "$f" .json)
  kill -0 "$PID" 2>/dev/null && echo "  ACTIVE: $(cat "$f")" || echo "  STALE: PID=$PID"
done

echo "## Codex"
CODEX_LATEST=$(stat -c '%Y %n' ~/.codex/sessions/????/??/??/rollout-*.jsonl 2>/dev/null | sort -rn | head -1 | cut -d' ' -f2-)
[ -n "$CODEX_LATEST" ] && echo "  $CODEX_LATEST ($(wc -l < "$CODEX_LATEST") lines)" || echo "  No sessions found"

从 JSONL 会话中提取原始数据

对找到的每个会话文件（$F）运行：

echo "=== TOOL CALLS ==="
grep -oE '"name"\s*:\s*"[^"]*"' "$F" 2>/dev/null | sed 's/"name"\s*:\s*"//;s/"//' | sort | uniq -c | sort -rn | head -30

echo "=== ERRORS ==="
grep -oE 'NOOP_EDIT|TEXT_NOT_FOUND|FILE_NOT_FOUND|HASH_HINT|DANGEROUS|out of range|mismatch|tool_use_error|permission denied' "$F" 2>/dev/null | sort | uniq -c | sort -rn

echo "=== TOOL LOOPS (3+ consecutive) ==="
grep -oE '"name"\s*:\s*"[^"]*"' "$F" 2>/dev/null | sed 's/"name"\s*:\s*"//;s/"//' | uniq -c | sort -rn | awk '$1 >= 3'

echo "=== BUILT-IN vs MCP ==="
grep -oE '"name"\s*:\s*"(Read|Edit|Write|Grep|mcp__hex-line__\w+)"' "$F" 2>/dev/null | sed 's/.*"name"\s*:\s*"//;s/"//' | sort | uniq -c | sort -rn

echo "=== HOOK EVENTS ==="
grep -oE 'hook_progress|blocking error|PreToolUse|PostToolUse|hex-confirmed|Obligatory use|Use mcp__hex-line' "$F" 2>/dev/null | sort | uniq -c | sort -rn

echo "=== SKILL/COMMAND INVOCATIONS ==="
grep -oE '"display":\s*"/[a-z-]+' "$F" 2>/dev/null | sed 's/"display":\s*"//' | sort | uniq -c | sort -rn

基于关键词的错误计数仅作为启发式参考。 确认报告的匹配项来自实际的工具失败／结果事件，而非包含相同字符串的提示词、模板或引用文档。

从 Claude JSONL 中提取令牌统计信息

对 Claude 会话文件（$F）运行，以获取真实的令牌用量：

echo "=== TOKEN STATS ==="
TOTAL_IN=$(grep -oE '"input_tokens":[0-9]+' "$F" | grep -oE '[0-9]+' | paste -sd+ | bc 2>/dev/null)
TOTAL_OUT=$(grep -oE '"output_tokens":[0-9]+' "$F" | grep -oE '[0-9]+' | paste -sd+ | bc 2>/dev/null)
CACHE_CREATE=$(grep -oE '"cache_creation_input_tokens":[0-9]+' "$F" | grep -oE '[0-9]+' | paste -sd+ | bc 2>/dev/null)
CACHE_READ=$(grep -oE '"cache_read_input_tokens":[0-9]+' "$F" | grep -oE '[0-9]+' | paste -sd+ | bc 2>/dev/null)
echo "in=${TOTAL_IN:-0} out=${TOTAL_OUT:-0} cache_create=${CACHE_CREATE:-0} cache_read=${CACHE_READ:-0}"

---

阶段 2：按维度分析

对收集的数据应用 D1-D10。对每项发现进行分类：

严重程度	维度	含义
错误	D1、D5	出现故障——工具失败、权限被拒绝
浪费	D2、D4、D8	不必要的工作——重复读取、临时脚本、重复收集
模式	D3、D6、D7、D9、D10	可改进的行为——循环、沟通、决策

D1：工具错误

按类型计数：NOOP_EDIT、TEXT_NOT_FOUND、哈希不匹配、超出范围、FILE_NOT_FOUND。对每项错误，找出导致问题的步骤／阶段。

D2：工具浪费

• 未先查看大纲就读取文件（文件 >100 行）
• 同一文件读取 3 次以上
• 存在 MCP 等效工具时，仍使用 Bash cat/grep/head/sed

D3：流程问题

• 工具循环：对同一文件调用同一工具 3 次以上，但没有进展
• 重试风暴：使用不同参数尝试 3 次以上
• 死胡同：探索某种方法后又放弃
• 目标错误：需要查看文件 Y 时却查看了文件 X

D4：脚本提取

• 会话期间编写的 Bash/Python 脚本
• 如果技能每次运行都需要该脚本 → 可考虑放入 references/scripts/

D5：钩子与权限

• 钩子阻止（PreToolUse/PostToolUse 阻止错误）
• MCP 强制启用时仍使用内置 Read/Edit/Write/Grep
• hex-confirmed 绕过——是否合理？

D6：沟通

• 消息长度分布（过度解释还是过于简短）
• 不必要的确认（“要我继续吗？”）
• 关键节点缺少状态更新
• 多余的总结

D7：决策质量

• 检测错误并调整方向所需的时间（错误与纠正之间的工具调用次数）
• 反复试错序列，而非有针对性的方法
• 工具选择推理（是否先用了错误的工具）

D8：上下文压力

• 不同阶段重复读取同一文件
• 重新收集已掌握的信息
• 上下文丢失迹象（重复询问已解决的问题）

D9：子 Agent 质量

• Agent 工具调用结果为空或价值较低
• Agent 超时
• 提示词范围过宽（Agent 做得过多或过少）

D10：范围偏移

• 初始目标与实际交付内容——是否有偏差？
• 执行期间的计划外增加项
• 没有明确理由的方向调整

---

第 3 阶段：对应修复方案

对于每项发现，确定具体目标和修复方案：

目标类型	示例
SKILL.md 步骤	“ln-400 第 2 步：添加文件路径 src/config.ts”
SKILL.md 阶段	“ln-300 第 3 阶段：拆分为 3a-3c 子步骤”
allowed-tools	“ln-400：添加 mcp__hex-line__edit_file”
钩子配置	“settings.json：为 npm test 添加例外”
references/scripts/	“ln-520：将 test_harness.sh 移至 references/scripts/”
CLAUDE.md	“添加偏好：回复简洁，不要附加总结”
MCP 工具	“hex-line edit_file：并发编辑时哈希不匹配”
Agent 提示词	“ln-310 Agent A：将范围缩小到仅处理安全问题”
范围控制	“ln-400：在第 1 阶段添加目标阐述关卡”

---

第 4 阶段：报告

按照 references/meta_analysis_protocol.md 的格式在聊天中输出。

### Session Analysis: {session identifier}

#### Improvements
| # | Dim | Finding | Target | Fix |
|---|-----|---------|--------|-----|
| 1 | D1 | 3 edit failures Phase 4 | ln-400 Step 2 | Add file path |
| 2 | D4 | test.sh written ad-hoc | ln-520 | Move to references/scripts/ |
| 3 | D6 | Over-explained 5 times | CLAUDE.md | Add "terse" pref |
| 4 | D5 | Hook blocked Read 4x | settings.json | Add MCP permission |

#### Session Errors
| Problem Type | Count | Examples |
|-------------|-------|---------|
| Retry storm | 4 | 3x edit_file on config.ts |
| Wrong target | 2 | Read utils.ts not helpers.ts |

#### Subagent Errors: {Agent Name}  (per agent, if any)
| Problem Type | Count | Examples |
|-------------|-------|---------|
| {type} | {N} | {brief} |

IF no findings AND no errors: "Session analysis: clean run."

---

反模式

不要	应改为
自行定义输出模板	参考协议格式
分析本次会话中未使用的文件	仅分析实际使用的内容
给出泛泛的建议	每项修复都关联具体文件和位置
报告无问题的维度	仅报告存在问题的发现

---

第 5 阶段：元分析

可选参考：仅当用户要求运行后元分析或按协议格式进行运行反思时，才加载 references/meta_analysis_protocol.md。

收到请求后，按照协议 §7 分析本次会话。按协议格式输出。

---

完成定义

• 已检查 D1-D10 维度
• JSONL 扫描可用（recent 模式）
• 每项发现均包含具体目标 + 修复方案
• 按协议格式输出（仅包含改进项）
• 未重复定义模板
• 已运行元分析

---

版本： 1.1.0 最后更新： 2026-04-05