debug-log-analysis

模式：认知驱动／提示词驱动 — 不使用独立的实用脚本；通过 Agent 上下文使用。

调试日志分析

用于从 Claude Code 会话调试日志中提取可操作信号的结构化工作流。适用于反思周期、事件响应或诊断 Agent 故障。

适用场景

• 在会话中出现意外的 Agent 故障或停滞后
• 反思 Agent 需要遥测数据来了解任务完成情况时
• 调试任务输出中难以理解的钩子错误时
• 路由器报告“Agent 已完成，但没有调用 TaskUpdate”时

前提条件

如果未提供文件参数，scripts/reduce-debug-log.mjs 脚本会自动检测最新日志。该脚本会将日志复制到 .tmp/，并在其中生成精简版。

步骤 0：确定分析模式

有两种模式可用：

自动模式（推荐）： 让 pnpm debug:reduce 自动查找并处理最新日志。

手动模式： 提供特定的会话 UUID 或日志文件路径。

步骤 1：定位并精简调试日志

重要：始终动态查找最新日志。绝不要将会话 UUID 硬编码。

自动模式（首选）

# Auto-detect most recent log, copy to .tmp/, reduce in place
cd /c/dev/projects/agent-studio && node scripts/reduce-debug-log.mjs 2>&1

# The script prints:
# Auto-detected debug log: /home/user/.claude/debug/{session-uuid}.txt
# Copied to: .tmp/{session-uuid}.txt
# Original: N lines -> kept (issue-like): M -> ... -> after dedupe: K
# Output: .tmp/{session-uuid}-reduced.txt

从脚本输出中记录输出路径，以供后续步骤使用。

手动模式（需要指定会话时）

# List recent debug logs sorted by modification time (most recent first)
ls -t "$HOME/.claude/debug/"*.txt 2>/dev/null | head -5

# Or on Windows (Git Bash):
ls -t "$USERPROFILE/.claude/debug/"*.txt 2>/dev/null | head -5

选择目标日志路径，然后：

# Copy to temp (never operate on the original)
mkdir -p .claude/context/tmp
cp "$HOME/.claude/debug/{session-uuid}.txt" ".claude/context/tmp/debug-session-copy.txt"

# Run reducer with explicit output path
node scripts/reduce-debug-log.mjs \
  ".claude/context/tmp/debug-session-copy.txt" \
  --output ".claude/context/tmp/debug-session-reduced.txt"

验证精简是否成功

# Check sizes
wc -l ".claude/context/tmp/debug-session-copy.txt"
wc -l ".claude/context/tmp/debug-session-reduced.txt"

预期结果：精简后的文件行数为原始文件的 1%–5%（移除了 98% 以上的噪声）。

步骤 2：比较原始日志与精简日志

计算过滤掉的内容，以了解过滤效果：

ORIGINAL_LINES=$(wc -l < ".claude/context/tmp/debug-session-copy.txt")
REDUCED_LINES=$(wc -l < ".claude/context/tmp/debug-session-reduced.txt")
echo "Original: $ORIGINAL_LINES lines | Reduced: $REDUCED_LINES lines"
echo "Kept: $(echo "scale=1; $REDUCED_LINES * 100 / $ORIGINAL_LINES" | bc)%"

记录任何异常情况，例如精简比例低于 90%，说明该会话出现了异常多的错误。

步骤 3：读取精简日志

完整读取 .claude/context/tmp/debug-session-reduced.txt。

步骤 4：对精简日志中的错误模式分类

对精简日志中的每一行进行分类：

类别	信号模式	操作
钩子拦截（写入）	PreToolUse:Write + block	计数；查找触发该操作的 Agent 和文件路径
钩子拦截（TaskUpdate）	PreToolUse:TaskUpdate + burst	计数；查找陷入循环的 Agent
读取未命中	File does not exist 或占位文本	计数；列出缺失文件
令牌溢出	FileTooLargeError 或 token limit	计数；找出大文件
流式停滞	日志条目之间的间隔超过 60 秒	累计时长；记录停滞前的情况
Agent 中断	TaskUpdate not called 或 agent returned，但未完成	按任务 ID 列出
工具错误	EISDIR、ENOENT、sibling tool call errored	按工具分类

步骤 5：在完整日志中交叉查找主要错误

针对出现频率最高的 3 类错误：

1. 在完整（未精简）日志副本中使用 Grep 搜索错误特征
2. 找出每次出现位置前后各 10 行
3. 确定：哪个工具调用触发了错误、当时运行的是哪个 Agent、它试图执行什么操作

# Use the full copy (not the original, not the reduced)
grep -n "PreToolUse:Write" ".claude/context/tmp/debug-session-copy.txt" | head -30
grep -n "File does not exist" ".claude/context/tmp/debug-session-copy.txt" | head -30
grep -n "timeout" ".claude/context/tmp/debug-session-copy.txt" -i | head -30

步骤 6：清理临时文件

分析后，清理工作副本（如报告需要，可保留精简后的文件）：

rm -f ".claude/context/tmp/debug-session-copy.txt"
# Optionally keep the reduced file for reference; delete when done
# rm -f ".claude/context/tmp/debug-session-reduced.txt"

步骤 7：生成结构化报告

写入 .claude/context/reports/reflections/debug-log-analysis-{YYYY-MM-DD}.md：

# Debug Log Analysis — {YYYY-MM-DD}

**Source log:** {path to original log — auto-detected or provided}
**Session UUID:** {session-uuid extracted from filename}
**Log statistics:**

- Original: {N} lines / {bytes} bytes
- Reduced: {M} lines / {bytes} bytes
- Reduction ratio: {X}%
  **Analysis timestamp:** {ISO-8601}

## Error Summary

| Category           | Count | Severity | Root Cause |
| ------------------ | ----- | -------- | ---------- |
| Hook Block (Write) | N     | CRITICAL | ...        |
| Read Miss          | N     | HIGH     | ...        |
| ...                |       |          |            |

## Top 3 Deep Dives

### 1. {Most frequent error}

**Frequency:** N occurrences
**First occurrence:** line {N}, timestamp {T}
**Context:** {what the agent was doing}
**Root cause:** {why it happened}
**Fix:** {concrete recommendation}

### 2. ...

### 3. ...

## Observability Gaps Found

List any gaps where the log entry doesn't have enough info to diagnose the error.

## Recommendations

- [ ] Immediate P0: {fix}
- [ ] P1: {fix}
- [ ] P2: {fix}

已知的可观测性缺口（Agent-Studio v2026-02）

当前调试日志格式存在以下缺口：

1. 未记录钩子拒绝原因 — 当 unified-creator-guard.cjs 阻止 Write 时，拒绝原因不会记录到调试日志中。你只能看到 PreToolUse:Write blocked，却不知道原因。

   • 变通方法：单独检查 process.stderr 输出；或者阅读钩子源代码，推断触发了哪条规则。

2. 错误行缺少 Agent 身份信息 — 错误行不会指出是哪个生成的 Agent 导致了错误。

   • 变通方法：将时间戳与任务启动／完成记录关联起来。

3. Read 失败时未记录文件路径 — File does not exist 行不一定包含文件路径。

   • 变通方法：查看前一条工具调用记录，确定尝试访问的路径。

4. 流式处理停滞原因不明 — 超过 5 分钟的停滞只会显示为时间戳间隔，且没有上下文。

   • 变通方法：间隔前的工具调用很可能是原因。

5. 不记录成功操作 — 日志主要突出显示失败。成功的工具调用只会生成极少的日志条目。

   • 变通方法：根据任务摘要元数据统计工具使用总次数。

与 Reflection 的集成

Reflection Agent 遇到高优先级反思请求时，应调用此技能：

// In reflection agent, for high-priority triggers:
if (priority === 'high' && debugLogPath) {
  Skill({ skill: 'debug-log-analysis' });
  // Include findings in reflection report
}

铁律

1. 务必在进行任何分析前复制调试日志 — 切勿直接操作原始文件；原地操作会破坏取证材料。
2. 切勿仅根据一次 grep 匹配结果报告根本原因 — 务必阅读匹配项前后至少各 10 行上下文，了解 Agent 当时的实际操作。
3. 务必先运行缩减脚本（步骤 2），再尝试读取完整调试日志 — 未经过滤的调试日志中 98% 以上都是噪声，会掩盖真实信号。
4. 切勿跳过结构化错误报告（步骤 6）— 非正式口头摘要不算交付物；Reflection Agent 必须使用 Markdown 报告来纳入调查结果。
5. 务必将新的重复错误模式写入 .claude/context/memory/issues.md — 未写入记忆的模式会在后续会话中无声地重复出现。

反模式

反模式	失败原因	正确做法
直接对原始日志文件执行 grep	会修改时间戳、破坏取证材料，且无法回滚	务必先复制：cp debug.txt .claude/context/tmp/debug-{date}.txt
阅读未经缩减的完整日志	噪声与信号的比例超过 98%；分析耗时数小时，还会漏掉模式	先运行 reduce-debug-log.mjs；基于缩减后的输出进行分析
根据一次 grep 命中结果报告根本原因	单次匹配往往是无关工具调用造成的误报	得出结论前，先阅读每个匹配项前后 ±10 行的上下文
用非正式口头摘要代替报告	Reflection Agent 无法将非正式摘要解析为记忆条目	将完整的结构化 Markdown 报告写入 .claude/context/reports/reflections/
分析后跳过记忆写入	错误模式会无声地重复出现；无法积累组织经验	任务完成前，将每个新模式写入 issues.md 或 learnings.md

记忆协议（强制）

完成后：

• 发现新的错误模式 → .claude/context/memory/issues.md
• 发现新的可观测性缺口 → .claude/context/memory/issues.md
• 在多个会话中重复出现的模式 → .claude/context/memory/learnings.md

假定会发生中断：如果没有记录在记忆中，就等于没有发生。