extracting-session-data

提取会话数据技能

核心职责

提供对存储在 ~/.claude/projects/{project-dir}/{session-id}.jsonl 中的 Claude Code 会话日志的原始访问权限。

关键原则：此技能仅提取数据——将原始数据返回给调用技能进行分析。不要在此技能中分析或解读数据。

可用脚本

所有脚本均位于此技能相对路径下的 scripts/ 子目录中。

1. locate-logs.sh

查找日志目录或特定会话文件路径。

# Get logs directory for current working directory
scripts/locate-logs.sh

# Get logs directory for specific project
scripts/locate-logs.sh /path/to/project

# Get specific session log file path
scripts/locate-logs.sh /path/to/project abc123-session-id

适用场景：构建动态路径、在处理前确认日志是否存在。

2. list-sessions.sh

列出所有会话及其元数据（ID、大小、行数、日期、分支）。

# List all sessions (table format)
scripts/list-sessions.sh

# JSON output
scripts/list-sessions.sh --format json

# Sort by size or lines
scripts/list-sessions.sh --sort size
scripts/list-sessions.sh --sort lines

# Specific project
scripts/list-sessions.sh /path/to/project

输出格式：table、json、csv 排序选项：date、size、lines

适用场景：开始回顾、向用户展示可用会话、检查最近的会话。

3. extract-data.sh

解析 JSONL 日志并提取特定类型的数据。

可用的提取类型：

• metadata - 会话信息（ID、时间戳、分支、工作目录）
• user-prompts - 所有用户消息
• tool-usage - 工具调用统计
• errors - 带时间戳的失败工具调用
• thinking - 思考区块（如果已启用扩展思考）
• text-responses - 仅限助手文本回复
• statistics - 会话指标（消息数、工具调用数、错误数）
• all - 组合提取

# Extract from specific session
scripts/extract-data.sh --type statistics --session SESSION_ID
scripts/extract-data.sh --type errors --session SESSION_ID
scripts/extract-data.sh --type tool-usage --session SESSION_ID

# Extract from all sessions (omit --session)
scripts/extract-data.sh --type statistics

# Limit output
scripts/extract-data.sh --type user-prompts --limit 10

# Different project
scripts/extract-data.sh --type metadata --project /path/to/project

适用场景：无需加载整个日志即可获取特定数据、生成指标、识别错误。

4. filter-sessions.sh

查找符合条件的会话。

筛选选项：

• --since DATE - 自指定日期以来修改的会话（“2 days ago”、“2025-10-20”）
• --until DATE - 截至指定日期修改的会话
• --branch NAME - 位于特定 git 分支上的会话
• --min-size SIZE - 最小文件大小（“1M”、“500K”）
• --max-size SIZE - 最大文件大小
• --min-lines N - 最小行数
• --max-lines N - 最大行数
• --has-errors - 仅包含有失败工具调用的会话
• --keyword WORD - 包含关键词的会话

输出格式：list、paths、json

# Recent sessions
scripts/filter-sessions.sh --since "2 days ago"

# Large sessions with errors
scripts/filter-sessions.sh --min-lines 500 --has-errors

# Sessions on main branch in last week
scripts/filter-sessions.sh --branch main --since "7 days ago"

# Sessions containing keyword
scripts/filter-sessions.sh --keyword "authentication"

# Get paths only (for piping)
scripts/filter-sessions.sh --since "1 day ago" --format paths

适用场景：用户要求分析最近的会话、查找特定功能或分支对应的会话、识别存在问题的会话。

工作流程

单会话分析

# 1. Verify session exists and get metadata
scripts/extract-data.sh --type metadata --session SESSION_ID

# 2. Get session statistics (to determine size)
scripts/extract-data.sh --type statistics --session SESSION_ID

# 3. Extract specific data as needed
scripts/extract-data.sh --type errors --session SESSION_ID
scripts/extract-data.sh --type tool-usage --session SESSION_ID

多会话分析

# 1. Filter to find relevant sessions
scripts/filter-sessions.sh --since "7 days ago" --branch main

# 2. Extract data from all filtered sessions
scripts/extract-data.sh --type statistics

# 3. Or iterate through filtered subset
SESSIONS=$(scripts/filter-sessions.sh --has-errors --format paths)
for session in $SESSIONS; do
    SESSION_ID=$(basename "$session" .jsonl)
    scripts/extract-data.sh --type errors --session $SESSION_ID
done

调用技能的集成模式

当其他技能（如回顾技能）需要会话数据时：

1. 发现：使用 list-sessions.sh 或 filter-sessions.sh 查找相关会话
2. 大小检查：使用 extract-data.sh --type statistics 确定会话复杂度
3. 定向提取：使用 extract-data.sh 和特定类型提取所需数据
4. 返回原始数据：将提取的数据返回给调用方进行分析

示例：

# Get latest session ID
LATEST=$(scripts/list-sessions.sh --format json --sort date | jq -r '.[0].sessionId')

# Check size before processing
STATS=$(scripts/extract-data.sh --type statistics --session $LATEST)
LINE_COUNT=$(echo "$STATS" | grep "Total Lines:" | awk '{print $3}')

# Extract based on size
if [ "$LINE_COUNT" -lt 500 ]; then
    # Small session: extract detail
    scripts/extract-data.sh --type errors --session $LATEST
    scripts/extract-data.sh --type tool-usage --session $LATEST
else
    # Large session: summary only
    scripts/extract-data.sh --type statistics --session $LATEST
fi

上下文预算管理

重要：此技能旨在提高上下文使用效率

使用 Bash 处理，而不是 Read 工具

# GOOD: Extract via bash, stays in bash context
STATS=$(scripts/extract-data.sh --type statistics)
# Process $STATS in bash

# BAD: Reading full log files
Read ~/.claude/projects/-path/session.jsonl
# Loads entire file into context unnecessarily

加载前检查会话大小

务必先检查大小，再将完整会话日志加载到上下文中。

# Always check statistics first
scripts/extract-data.sh --type statistics --session SESSION_ID
# Shows total lines, message counts, etc.

# Decision rules:
# - Small (<500 lines): Can extract detail safely
# - Medium (500-2000 lines): Use selective extraction
# - Large (>2000 lines): Statistics only, offer targeted deep-dives

将原始数据返回给调用方

此技能应：

• 执行 bash 脚本以提取数据
• 将原始文本输出返回给调用技能
• 让调用技能管理用于分析的上下文
• 避免在此技能中解读或分析数据

输出格式

以最少的格式处理返回原始提取数据：

# Statistics output
Session: abc123-def456-ghi789
  Total Lines: 450
  User Messages: 12
  Assistant Messages: 23
  Tool Calls: 45
  Errors: 2

# Tool usage output
=== Tool Usage: abc123-def456-ghi789 ===
Read                          15
Bash                          12
Edit                          8
Grep                          5
Write                         3

不做分析，不做解读——只提取数据。

错误处理

所有脚本在发生错误时会以非零状态码退出，并将错误输出到 stderr。

处理前请检查退出状态：

if ! scripts/locate-logs.sh /path/to/project &>/dev/null; then
    # Handle: logs directory doesn't exist
    echo "Project has no session logs yet"
fi

if ! scripts/extract-data.sh --type metadata --session abc123 &>/dev/null; then
    # Handle: session doesn't exist
    echo "Session not found"
fi

常见错误消息：

• Error: Logs directory not found: ~/.claude/projects/-path
• Error: Session file not found: ~/.claude/projects/-path/session-id.jsonl
• Error: --type is required
• Error: jq is required but not installed. Install with: brew install jq

路径计算

Claude Code 使用以下模式存储会话：

~/.claude/projects/{project-identifier}/{session-id}.jsonl

其中，{project-identifier} 的计算方式是将绝对工作目录路径中的所有 / 替换为 -：

# Example: /Users/user/project → -Users-user-project
PROJECT_ID=$(echo "${PWD}" | sed 's/\//\-/g')
LOGS_DIR="${HOME}/.claude/projects/${PROJECT_ID}"

所有脚本都会在内部使用 locate-logs.sh，以保持路径计算一致。

应避免的反模式

不要：

• 不检查大小就将完整会话日志加载到上下文中
• 手动解析 JSONL——请使用 extract-data.sh
• 将日志路径硬编码——请使用 locate-logs.sh
• 分析或解读数据——向调用方返回原始数据
• 未告知用户就同步处理大型日志

应该：

• 在处理前使用 --type statistics 检查会话大小
• 根据具体需求使用合适的提取类型
• 提取前筛选会话，以提高效率
• 处理多个会话时使用流式处理或管道
• 返回原始数据供调用方分析

成功标准

有效使用此技能意味着：

1. 高效发现：无需手动搜索即可快速找到相关会话
2. 有针对性地提取：只获取所需数据，不多不少
3. 保留上下文：避免将不必要的数据加载到上下文中
4. 聚焦原始数据：返回未经处理的数据供调用方分析
5. 支持多会话：高效处理跨时间范围或分支的分析

依赖项

必需：

• bash（v4.0+）
• jq（JSON 解析器）

如果缺少 jq，脚本会检查并提供安装说明：

Error: jq is required but not installed. Install with: brew install jq