name: session-inspector description: > 此技能应用于检查、分析或查询 Claude Code 会话日志。当用户询问会话历史、想要查找会话、分析上下文使用情况、提取工具调用模式、调试代理执行，或理解之前会话中发生了什么时使用。对于理解 Claude Code 的 ~/.claude/projects/ 结构、JSONL 会话格式和 erk 提取管道至关重要。

会话检查器

概述

会话检查器提供全面工具用于检查存储在 ~/.claude/projects/ 中的 Claude Code 会话日志。该技能使能：

发现和列出任何项目/工作树的会话
预处理会话为可读的 XML 格式
分析上下文窗口消耗
从会话中提取计划
从会话内容创建 GitHub 问题
调试代理子进程执行
理解两阶段提取管道

何时使用

在以下情况调用此技能：

询问项目或工作树存在哪些会话
想要通过 ID 或内容查找特定会话
需要分析上下文窗口消耗
询问工具调用模式或频率
需要调试代理子进程失败
想要从会话中提取计划
询问会话历史或之前对话
需要理解会话预处理或提取

快速参考：CLI 命令

所有命令通过 erk exec <command> 调用：

命令	目的
`list-sessions`	为当前工作树列出带元数据的会话
`preprocess-session`	将 JSONL 转换为压缩的 XML
`extract-latest-plan`	从会话中提取最新计划
`create-issue-from-session`	从会话计划创建 GitHub 问题
`extract-session-from-issue`	从 GitHub 问题提取会话内容

斜杠命令

命令	目的
`/erk:sessions-list`	显示格式化的会话列表表格
`/local:analyze-context`	跨会话分析上下文窗口使用

核心能力

1. 列出会话

erk exec list-sessions [--limit N] [--min-size BYTES]

选项：

--limit: 最大返回会话数（默认：10）
--min-size: 过滤小会话的最小文件大小字节数（默认：0）

输出包括：

分支上下文（current_branch, trunk_branch, is_on_trunk）
来自 SESSION_CONTEXT 环境变量的当前会话 ID
会话数组包含：session_id, mtime_display, mtime_relative, size_bytes, summary, is_current
项目目录路径和过滤计数

2. 预处理会话为 XML

erk exec preprocess-session <log-path> [OPTIONS]

选项：

--session-id: 过滤条目到特定会话 ID
--include-agents/--no-include-agents: 包含代理日志（默认：True）
--no-filtering: 禁用过滤优化
--stdout: 输出到 stdout 而不是临时文件

应用的优化：

空/热身会话过滤
文档去重（哈希标记）
工具参数截断（>200 字符）
工具结果修剪（前 30 行，保留错误）
日志发现操作过滤

3. 从会话中提取计划

erk exec extract-latest-plan [--session-id SESSION_ID]

从会话中提取最新计划。使用通过 slug 字段的会话范围查找，如果没有找到会话特定计划，则回退到基于 mtime 的查找。

4. 从会话创建 GitHub 问题

erk exec create-issue-from-session [--session-id SESSION_ID]

提取计划并从会话内容创建 GitHub 问题。返回带有 issue_number 和 issue_url 的 JSON。

5. 为 GitHub 渲染会话

erk exec render-session-content --session-file <path> [--session-label LABEL] [--extraction-hints HINTS]

将会话 XML 渲染为 GitHub 评论块，大内容自动分块。

6. 从 GitHub 问题提取会话

erk exec extract-session-from-issue <issue-number> [--output PATH] [--session-id ID]

从 GitHub 问题评论中提取并合并分块会话内容。

目录结构

~/.claude/projects/
├── -Users-foo-code-myapp/           ← 编码的项目路径
│   ├── abc123-def456.jsonl          ← 主要会话日志
│   ├── xyz789-ghi012.jsonl          ← 另一个会话
│   ├── agent-17cfd3f4.jsonl         ← 代理子进程日志
│   └── agent-2a3b4c5d.jsonl         ← 另一个代理日志

路径编码： 前缀 -，替换 / 和 . 为 -

示例：/Users/foo/code/myapp → -Users-foo-code-myapp

会话 ID

会话 ID 通过 --session-id 选项显式传递给 CLI 命令。典型流程：

钩子通过 Claude Code 的 stdin JSON 接收会话上下文
钩子输出 📌 session: <id> 提醒到对话
代理从提醒文本提取会话 ID
代理作为显式 CLI 参数传递会话 ID

示例：

erk exec list-sessions --session-id abc123-def456

两阶段提取管道

提取系统使用两阶段管道：

第一阶段：机械缩减（确定性）

丢弃文件历史快照条目
剥离使用元数据
移除空文本块
压缩空白（3+ 换行符 → 1）
去重带有 tool_use 的助手消息
输出：压缩的 XML

第二阶段：俳句蒸馏（可选，语义）

移除噪声（日志发现、热身内容）
去重语义相似块
修剪冗长输出
保留错误、堆栈跟踪、警告
输出：语义精炼的 XML

会话选择逻辑

auto_select_sessions() 函数使用智能规则：

在主干上： 仅使用当前会话
当前会话微不足道（<1KB）+ 存在实质性会话： 自动选择实质性
当前会话实质性（>=1KB）： 单独使用它
无实质性会话： 即使微不足道也返回当前

临时存储

会话范围的文件存储在 .erk/scratch/sessions/<session-id>/：

from erk_shared.scratch import get_scratch_dir, write_scratch_file

scratch_dir = get_scratch_dir(session_id)
file_path = write_scratch_file(content, session_id=session_id, suffix=".xml")

常见任务

查找会话中发生了什么

列出会话：erk exec list-sessions
通过摘要或时间查找
预处理：erk exec preprocess-session <file> --stdout | head -500

调试上下文溢出

运行 /local:analyze-context
检查按类别的令牌细分
查找重复读取或大型工具结果

提取计划用于实施

erk exec extract-latest-plan --session-id <id>

从会话计划创建问题

erk exec create-issue-from-session --session-id <id>

查找代理子进程日志

PROJECT_DIR=$(erk find-project-dir | jq -r '.project_dir')
ls -lt "$PROJECT_DIR"/agent-*.jsonl | head -10

检查代理中错误

cat agent-<id>.jsonl | jq 'select(.message.is_error == true)'

资源

references/

tools.md - 完整的 CLI 命令和 jq 分析指南
format.md - JSONL 格式规范及条目类型
extraction.md - erk_shared 提取模块 API 参考

当用户需要详细命令语法、格式文档或编程访问提取能力时，加载参考资料。

代码依赖

此技能记录的能力主要存在于：

CLI 命令： packages/erk-cli/src/erk_cli/commands/
共享库： packages/erk-shared/src/erk_shared/extraction/
GitHub 元数据： packages/erk-shared/src/erk_shared/github/metadata.py
临时存储： packages/erk-shared/src/erk_shared/scratch/