session-replay

会话回放技能

用途

此技能会分析 claude-trace JSONL 文件，深入了解 Claude Code 会话健康状况、令牌使用模式、错误频率和 Agent 效能。它通过聚焦 API 级别的跟踪数据而非对话记录，对 /transcripts 命令进行补充。

何时使用此技能

• 会话调试：诊断会话变慢或失败的原因
• 令牌分析：了解令牌消耗模式
• 错误模式：识别多个会话中反复出现的故障
• 性能优化：查找工具使用中的瓶颈
• Agent 效能：衡量哪些 Agent/工具效率最高

快速开始

分析最新会话

User: Analyze my latest session health

我将分析最近的跟踪文件：

# Read latest trace file from .claude-trace/
trace_dir = Path(".claude-trace")
trace_files = sorted(trace_dir.glob("*.jsonl"), key=lambda f: f.stat().st_mtime)
latest = trace_files[-1] if trace_files else None

# Parse and analyze
if latest:
    analysis = analyze_trace_file(latest)
    print(format_session_report(analysis))

比较多个会话

User: Compare token usage across my last 5 sessions

我将汇总多个会话的指标：

trace_files = sorted(Path(".claude-trace").glob("*.jsonl"))[-5:]
comparison = compare_sessions(trace_files)
print(format_comparison_table(comparison))

操作

操作：health

分析跟踪文件中的会话健康指标。

操作步骤：

1. 读取跟踪文件（JSONL 格式）
2. 提取 API 请求和响应
3. 计算指标：
   • 令牌总数（输入/输出）
   • 请求数量和耗时
   • 错误率
   • 工具使用分布
4. 生成健康报告

要提取的指标：

# From each JSONL line containing a request/response pair:
{
    "timestamp": "...",
    "request": {
        "method": "POST",
        "url": "https://api.anthropic.com/v1/messages",
        "body": {
            "model": "claude-...",
            "messages": [...],
            "tools": [...]
        }
    },
    "response": {
        "usage": {
            "input_tokens": N,
            "output_tokens": N
        },
        "content": [...],
        "stop_reason": "..."
    }
}

输出格式：

Session Health Report
=====================
File: log-2025-11-23-19-32-36.jsonl
Duration: 45 minutes

Token Usage:
- Input: 125,432 tokens
- Output: 34,521 tokens
- Total: 159,953 tokens
- Efficiency: 27.5% output ratio

Request Stats:
- Total requests: 23
- Average latency: 2.3s
- Errors: 2 (8.7%)

Tool Usage:
- Read: 45 calls
- Edit: 12 calls
- Bash: 8 calls
- Grep: 15 calls

Health Score: 82/100 (Good)
- Minor issue: 2 errors detected

操作：errors

识别多个会话中的错误模式。

操作步骤：

1. 扫描跟踪文件中的错误响应
2. 按类型对错误进行分类
3. 识别反复出现的模式
4. 提出修复建议

要检测的错误类别：

• 速率限制错误（429）
• 超出令牌限制
• 工具执行失败
• 超时错误
• API 错误

输出格式：

Error Analysis
==============
Sessions analyzed: 5
Total errors: 12

Error Categories:
1. Rate limit (429): 5 occurrences
   - Recommendation: Add delays between requests

2. Token limit: 3 occurrences
   - Recommendation: Use context management skill

3. Tool failures: 4 occurrences
   - Bash timeout: 2
   - File not found: 2
   - Recommendation: Check paths before operations

操作：compare

比较多个会话的指标。

操作步骤：

1. 加载多个跟踪文件
2. 提取可比较的指标
3. 计算趋势
4. 识别异常

输出格式：

Session Comparison
==================
                    Session 1   Session 2   Session 3   Trend
Tokens (total)      150K        180K        120K        -17%
Requests            25          30          18          -28%
Errors              2           0           1           stable
Duration (min)      45          60          30          -33%
Efficiency          0.27        0.32        0.35        +7%

操作：tools

分析工具使用模式。

操作步骤：

1. 从跟踪文件中提取工具调用
2. 计算调用频率和耗时
3. 识别低效模式
4. 提出优化建议

要检测的模式：

• 可以并行执行的顺序调用
• 对同一文件的重复读取
• 过多的 grep/glob 调用
• 未使用的工具结果

输出格式：

Tool Usage Analysis
===================
Tool          Calls   Avg Time   Success Rate
Read          45      0.1s       100%
Edit          12      0.3s       92%
Bash          8       1.2s       75%
Grep          15      0.2s       100%
Task          3       45s        100%

Optimization Opportunities:
1. 5 Read calls to same file within 2 minutes
   - Consider caching strategy

2. 3 sequential Bash calls could be parallelized
   - Use multiple Bash calls in single message

实现说明

解析 JSONL 跟踪文件

Claude-trace 文件采用 JSONL 格式，包含请求/响应对：

import json
from pathlib import Path
from typing import Dict, List, Any

def parse_trace_file(path: Path) -> List[Dict[str, Any]]:
    """Parse a claude-trace JSONL file."""
    entries = []
    with open(path) as f:
        for line in f:
            if line.strip():
                try:
                    entry = json.loads(line)
                    entries.append(entry)
                except json.JSONDecodeError:
                    continue
    return entries

def extract_metrics(entries: List[Dict]) -> Dict[str, Any]:
    """Extract session metrics from trace entries."""
    metrics = {
        "total_input_tokens": 0,
        "total_output_tokens": 0,
        "request_count": 0,
        "error_count": 0,
        "tool_usage": {},
        "timestamps": [],
    }

    for entry in entries:
        if "request" in entry:
            metrics["request_count"] += 1
            metrics["timestamps"].append(entry.get("timestamp", 0))

        if "response" in entry:
            usage = entry["response"].get("usage", {})
            metrics["total_input_tokens"] += usage.get("input_tokens", 0)
            metrics["total_output_tokens"] += usage.get("output_tokens", 0)

            # Check for errors
            if entry["response"].get("error"):
                metrics["error_count"] += 1

        # Extract tool usage from request body
        if "request" in entry and "body" in entry["request"]:
            body = entry["request"]["body"]
            if isinstance(body, dict) and "tools" in body:
                for tool in body["tools"]:
                    name = tool.get("name", "unknown")
                    metrics["tool_usage"][name] = metrics["tool_usage"].get(name, 0) + 1

    return metrics

查找跟踪文件

def find_trace_files(trace_dir: str = ".claude-trace") -> List[Path]:
    """Find all trace files, sorted by modification time."""
    trace_path = Path(trace_dir)
    if not trace_path.exists():
        return []
    return sorted(
        trace_path.glob("*.jsonl"),
        key=lambda f: f.stat().st_mtime,
        reverse=True  # Most recent first
    )

错误处理

妥善处理常见错误情况：

def safe_parse_trace_file(path: Path) -> Tuple[List[Dict], List[str]]:
    """Parse trace file with error collection for malformed lines.

    Returns:
        Tuple of (valid_entries, error_messages)
    """
    entries = []
    errors = []

    if not path.exists():
        return [], [f"Trace file not found: {path}"]

    try:
        with open(path) as f:
            for line_num, line in enumerate(f, 1):
                if not line.strip():
                    continue
                try:
                    entry = json.loads(line)
                    entries.append(entry)
                except json.JSONDecodeError as e:
                    errors.append(f"Line {line_num}: Invalid JSON - {e}")
    except PermissionError:
        return [], [f"Permission denied: {path}"]
    except UnicodeDecodeError:
        return [], [f"Encoding error: {path} (expected UTF-8)"]

    return entries, errors


def format_error_report(errors: List[str], path: Path) -> str:
    """Format error report for user display."""
    if not errors:
        return ""

    report = f"""
Trace File Issues
=================
File: {path.name}
Issues found: {len(errors)}

"""
    for error in errors[:10]:  # Limit to first 10
        report += f"- {error}\n"

    if len(errors) > 10:
        report += f"\n... and {len(errors) - 10} more issues"

    return report

常见错误情况：

情况	原因	处理方式
空文件	会话没有 API 调用	报告“没有可分析的数据”
JSON 格式错误	跟踪文件损坏或写入中断	跳过该行，并在错误报告中计数
缺少字段	较旧的跟踪文件格式	使用带默认值的 .get()
权限被拒绝	文件被另一个进程锁定	显示清晰的错误消息，建议重试
编码错误	存在非 UTF-8 字符	报告编码问题

与现有工具集成

工具选择矩阵

需求	使用此工具	原因
“为什么我的会话很慢？”	session-replay	API 延迟和令牌指标
“上个会话讨论了什么？”	/transcripts	对话内容
“从会话中提取经验”	CodexTranscriptsBuilder	知识提取
“减少令牌用量”	session-replay + context_management	指标 + 优化
“恢复被中断的工作”	/transcripts	上下文恢复

与 /transcripts 命令的区别

/transcripts（对话管理）：

• 关注对话内容
• 恢复会话上下文
• 用于保留上下文
• 触发词：“恢复会话”、“继续工作”、“我刚才在做什么”

session-replay 技能（API 级分析）：

• 关注 API 指标
• 分析性能和错误
• 用于调试和优化
• 触发词：“会话健康状况”、“令牌用量”、“为什么很慢”、“调试会话”

与 CodexTranscriptsBuilder 的区别

CodexTranscriptsBuilder（知识提取）：

• 从对话中提取模式
• 构建学习语料
• 以知识为重点
• 触发词：“提取模式”、“构建知识库”、“从会话中学习”

session-replay 技能（指标分析）：

• 提取性能指标
• 识别技术问题
• 以运维为重点
• 触发词：“性能指标”、“错误模式”、“工具效率”

组合工作流

工作流 1：诊断并修复令牌问题

1. session-replay: Analyze token usage patterns (health action)
2. Identify high-token operations
3. context_management skill: Apply proactive trimming
4. session-replay: Compare before/after sessions (compare action)

工作流 2：事件后分析

1. session-replay: Identify error patterns (errors action)
2. /transcripts: Review conversation context around errors
3. session-replay: Check tool usage around failures (tools action)
4. Document findings in DISCOVERIES.md

工作流 3：性能基线

1. session-replay: Analyze 5-10 recent sessions (compare action)
2. Establish baseline metrics (tokens, latency, errors)
3. Track deviations from baseline over time

存储位置

• 跟踪文件：.claude-trace/*.jsonl
• 会话日志：~/.amplihack/.claude/runtime/logs/<session_id>/
• 生成的报告：直接输出（无需持久化存储）

理念一致性

极致简洁

• 单一用途：仅分析跟踪文件，不管理会话，也不编辑转录内容
• 无外部依赖：仅使用 Python 标准库（json、pathlib、datetime）
• 直接解析文件：无 ORM、无数据库、无复杂抽象
• 关注当下：分析当前已有的内容，不做面向未来的设计

杜绝废话的实现

• 所有函数均可完整运行：此技能中的每个代码示例都能直接运行，无需修改
• 真实解析、真实指标：无模拟数据，也无占位计算
• 无存根或占位符：文档中描述的功能均可使用
• 出错时快速失败：错误消息清晰，不会静默失败

砖块理念

• 自包含分析：所有功能都在这一个技能中
• 输入（跟踪文件）和输出（报告）明确：无隐藏状态或副作用
• 可根据此规范重新生成：此 SKILL.md 是完整的事实来源
• 职责隔离：仅分析会话，不修改文件或触发操作

限制

此技能无法：

• 修改跟踪文件：仅进行只读分析，不编辑或删除文件
• 生成跟踪记录：使用 claude-trace npm 包创建跟踪文件
• 恢复会话：使用 /transcripts 命令恢复会话
• 实时监控：分析已完成的会话，不跟踪实时活动
• 跨项目分析：仅分析当前项目中的跟踪记录
• 解析非 JSONL 格式：仅支持 claude-trace JSONL 格式
• 访问远程跟踪记录：仅限本地文件系统，不支持云存储

高效分析技巧

1. 先进行健康检查：首先运行 health 操作
2. 查找模式：使用 errors 查找反复出现的问题
3. 优化热点：使用 tools 查找低效之处
4. 追踪趋势：跨会话使用 compare
5. 结合转录记录：使用 /transcripts 获取上下文

常见模式

模式 1：调试缓慢的会话

User: My last session was really slow, analyze it

1. Run health action on latest trace
2. Check request latencies
3. Identify tool bottlenecks
4. Report findings with recommendations

模式 2：降低令牌用量

User: I'm hitting token limits, help me understand usage

1. Compare token usage across sessions
2. Identify high-token operations
3. Suggest context management strategies
4. Recommend workflow optimizations

模式 3：修复反复出现的错误

User: I keep getting errors, find the pattern

1. Run errors action across last 10 sessions
2. Categorize and count error types
3. Identify root causes
4. Provide targeted fixes

资源

• 追踪目录：.claude-trace/
• 转录记录命令：/transcripts
• 上下文管理技能：context-management
• 理念：~/.amplihack/.claude/context/PHILOSOPHY.md

故障排除

未找到追踪文件

现象："No trace files in .claude-trace/"

原因和解决方法：

1. 未启用 claude-trace：在开始会话前设置 AMPLIHACK_USE_TRACE=1
2. 目录错误：检查当前是否位于包含 .claude-trace/ 目录的项目根目录
3. 新项目：先运行一个启用了追踪的会话

指标不完整

现象：缺少令牌计数或数值为零

原因和解决方法：

1. 会话中断：如果会话崩溃，追踪记录可能不完整
2. 流式响应：某些流式模式无法捕获完整指标
3. 较旧的追踪格式：将 claude-trace 升级到最新版本

健康评分似乎不正确

现象：评分与会话体验不符

评分说明：

• 90-100：优秀——错误少，效率高
• 70-89：良好——检测到轻微问题
• 50-69：一般——存在值得调查的重大问题
• 低于 50：较差——可能存在错误或效率低下

健康评分的影响因素：

• 错误率（权重 40%）
• 令牌效率比（权重 30%）
• 请求成功率（权重 20%）
• 工具成功率（权重 10%）

追踪文件过大

现象：分析速度慢或占用大量内存

解决方案：

1. 分析特定时间范围，而不是整个文件
2. 使用 tools 操作进行有针对性的分析
3. 归档旧追踪记录：mv .claude-trace/old-*.jsonl .claude-trace/archive/

请记住

此技能提供会话级别的调试和优化见解。它通过 API 级别的可见性补充转录记录管理。使用它来诊断问题、优化工作流，并了解 Claude Code 的行为模式。

关键要点：追踪文件包含有关会话性能的原始真实数据。此技能会从中提取可执行的见解。