introspect

用途

Introspect 用于从 Claude Code 会话日志中提取可操作的智能信息，帮助分析会话过程并发现生产力改进点。它面向希望复盘 AI 辅助编码过程的开发者，通过分析日志来优化工作流。

主要能力

该技能提供一个名为 cc-session 的命令行工具，零依赖（仅需 jq + bash），可自动解析当前项目和最近一次会话。

提供的命令包括：

cc-session overview：条目数量、时间、工具/思考总数
cc-session tools：工具使用频率（排序）
cc-session tool-chain：带输入摘要的顺序工具调用轨迹
cc-session thinking：完整的思考/推理块
cc-session thinking-summary：每个思考块前 200 字符
cc-session errors：包含错误模式的工具结果
cc-session conversation：重建的用户/助手轮次
cc-session files：读取、编辑、写入的文件（含计数）
cc-session turns：逐轮次明细（时长、使用的工具）
cc-session agents：子代理生成，含类型和提示预览
cc-session cost：粗略的 token/成本估算
cc-session timeline：带时间戳的事件时间线
cc-session summary：会话摘要（压缩边界）
cc-session search <pattern>：跨会话搜索（文本内容）

使用方式

将脚本复制到 PATH 以全局访问：

# Copy to PATH for global access
cp skills/introspect/scripts/cc-session ~/.local/bin/
# Or on Windows (Git Bash)
cp skills/introspect/scripts/cc-session ~/bin/

选项包括：

--project, -p <name>：按项目过滤（部分匹配）
--dir, -d <pattern>：按项目路径中的目录模式过滤
--all：搜索所有项目（配合 search 命令）
--recent <n>：使用第 n 最近会话（默认：1）
--json：以 JSON 而非文本输出

示例：

cc-session overview                              # Current project, latest session
cc-session tools --recent 2                      # Tools from second-latest session
cc-session tool-chain                            # Full tool call sequence
cc-session errors -p claude-mods                 # Errors in claude-mods project
cc-session thinking | grep -i "decision"         # Search reasoning
cc-session search "auth" --all                   # Search all projects
cc-session turns --json | jq '.[] | select(.tools > 5)'  # Complex turns
cc-session files --json | jq '.edited[:5]'       # Top 5 edited files
cc-session overview --json                       # Pipe to other tools

分析决策树

该技能提供决策树帮助选择命令：

“某会话发生了什么？”：overview、conversation、timeline、summary
“我如何使用工具？”：tools、tool-chain、files
“我当时在想什么？”：thinking、thinking-summary、thinking | grep
“哪里出错了？”：errors、tool-chain
“比较会话”：tools --recent 1 vs --recent 2、cost
“跨会话搜索”：search "pattern"、search "pattern" --all

会话日志结构

日志文件位于 ~/.claude/：

~/.claude/
|- projects/
|   |- {project-path}/                        # e.g., X--Forge-claude-mods/
|       |- sessions-index.json                # Session metadata index
|       |- {session-uuid}.jsonl               # Full session transcript
|       |- agent-{short-id}.jsonl             # Subagent transcripts

项目路径使用双短横线编码：C:\Projects\my-repo -> C--Projects-my-repo。

条目类型包括 user、assistant、system、progress、file-history-snapshot、queue-operation、last-prompt、summary。内容块类型包括 text、tool_use、tool_result、thinking。

会话日志保留

默认情况下，Claude Code 会删除 30 天不活跃的会话（启动时）。可通过修改设置延长：

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 90
}

说明中当前设置为 90 天，可根据磁盘使用情况调整。

jq 快速参考

# Pipe through cat on Windows (jq file args can fail)
cat session.jsonl | jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name'

# Two-stage for large files
rg '"tool_use"' session.jsonl | jq -r '.message.content[]? | select(.type == "tool_use") | .name'

会话洞察

运行分析后，应生成“Session Insights”部分，包含可操作建议，语气友好且具指导性。需扫描的模式包括：

工具使用改进：如用 Bash(grep/cat) 代替专用工具、重复失败调用、未使用并行调用等
工作流模式：如长会话无提交、未使用 /save、重复上下文重读、调试螺旋等
技能和命令意识：如未使用 /review、/testgen、/atomise，或对技能可处理的任务生成代理
会话效率：如超长会话、高错误率、读取与编辑比例过高
权限建议：扫描成功且重复使用的 Bash 命令，生成可粘贴到 .claude/settings.local.json 的 permissions.allow 片段，并按类别分组。仅推荐实际成功使用的命令，不推荐笼统的 Bash(*)，鼓励使用通配符模式如 Bash(git:*)、mcp__server-name__* 等。

输出格式示例：

## Session Insights

Here are a few things I noticed that might help next time:

**[Category]**
- [Observation]: [What was seen in the data]
- [Suggestion]: [Friendly, specific recommendation]

建议数量应与会话规模匹配，仅提及数据中明确存在的模式。

参考文件

scripts/cc-session：CLI 工具，14 个命令，JSON 输出，项目过滤
references/session-analysis.md：自定义分析的原始 jq 配方

技能介绍

用途