history-insight

历史洞察

分析 Claude Code 会话历史并提取洞察。

---

数据位置

~/.claude/projects/<encoded-cwd>/*.jsonl

路径编码： /Users/foo/project → -Users-foo-project

详细文件格式：${baseDir}/references/session-file-format.md

---

执行算法

步骤 1：询问范围 [MANDATORY]

确定范围：

1. 已明确指定（可省略 AskUserQuestion）：

   • “仅当前项目” / “此项目” → current_project
   • “所有会话” / “全部” → all_sessions

2. 未明确指定 - 调用 AskUserQuestion：

   question: "세션 검색 범위를 선택하세요"
   options:
     - "현재 프로젝트만" → ~/.claude/projects/<encoded-cwd>/*.jsonl
     - "모든 Claude Code 세션" → ~/.claude/projects/**/*.jsonl
   

---

步骤 2：查找会话文件

# Current project only
find ~/.claude/projects/<encoded-cwd> -name "*.jsonl" -type f

# All sessions (모든 프로젝트)
find ~/.claude/projects -name "*.jsonl" -type f

日期筛选：检查文件的 mtime（修改时间）后进行筛选。不同操作系统的 stat 选项不同：

• macOS：stat -f "%Sm" -t "%Y-%m-%d" <file>
• Linux：stat -c "%y" <file>

---

步骤 3：处理会话

决策树

Session files found?
├─ No → Error: "No sessions found"
└─ Yes → How many files?
    ├─ 1-3 files → Direct Read + parse
    └─ 4+ files → Batch Extract Pipeline

1-3 个文件

直接使用 Read 解析 JSONL。文件较大（≥5000 tokens）时使用 extract-session.sh：

${baseDir}/scripts/extract-session.sh <session.jsonl>

4 个及以上文件：批量提取流水线

1. 创建缓存目录（/tmp/cc-cache/<analysis-name>/）
2. 保存会话列表（sessions.txt）
3. 使用 jq 批量提取消息（user_messages.txt）
4. 清理并筛选（clean_messages.txt）
5. 使用 Task(opus) 进行综合分析

文件过大时：并行批量分析

如果 clean_messages.txt 过大而导致 Read 失败：

1. 拆分文件：

   split -l 2000 clean_messages.txt /tmp/cc-cache/<name>/batch_
   

2. 并行调用 Task(opus)：

   Task(subagent_type="general-purpose", model="opus", run_in_background=true)
   prompt: "batch_XX 파일을 읽고 주제/패턴 요약해줘"
   

3. 合并结果：使用 Task(opus) 进行综合分析

---

步骤 4：报告结果

## Session Capture Complete

- **Sessions:** N files processed
- **Messages:** X total, Y after filter

### Extracted Insights
[분석 결과]

---

错误处理

场景	响应
未找到会话文件	“No session files found for this project.”
文件过大	使用 extract-session.sh 自动预处理
未安装 jq	“Error: jq is required. Install with: brew install jq”
Task 失败	“Warning: Could not process [file]. Skipping.”
没有相关会话	“No sessions matched your criteria.”

---

安全说明

• 禁止在输出中暴露完整路径（使用 ~ 前缀）

---

相关资源

• ${baseDir}/scripts/extract-session.sh - 压缩 JSONL（移除 thinking、tool_use）
• ${baseDir}/references/session-file-format.md - JSONL 结构及解析