401 lines
11 KiB
Markdown
401 lines
11 KiB
Markdown
---
|
||
allowed-tools: Read, Write, Bash, Grep, Glob
|
||
description: 总结并保存当前会话到本地存储
|
||
---
|
||
|
||
智能分析当前会话内容，提取关键信息（项目进度、实施方案、关键决策、文件变更），并保存到分层存储结构中。
|
||
|
||
**核心特性**:
|
||
- 📊 **智能提取**: 自动识别 TodoWrite、AskUserQuestion、文件操作等关键信息
|
||
- 💾 **分层存储**: 摘要文件 + 完整日志，兼顾查询效率和数据完整性
|
||
- 🔍 **防失真**: 保留完整对话记录，避免压缩导致信息丢失
|
||
- 🌐 **跨平台**: 完全兼容 Windows / macOS / Linux
|
||
|
||
---
|
||
|
||
## 执行步骤
|
||
|
||
### 1. 定位当前会话文件
|
||
|
||
找到 Claude Code 当前会话的 JSONL 文件。
|
||
|
||
**位置**：`~/.claude/projects/` 目录下
|
||
|
||
**匹配规则**：
|
||
- 项目目录名包含当前工作目录的路径信息
|
||
- 例如：项目在 `/Users/user/my-project`
|
||
- 对应目录可能是：`-Users-user-my-project/`
|
||
- 文件名格式：`{session-uuid}.jsonl`
|
||
- 排除 `agent-` 开头的文件
|
||
- 选择最新的文件（按修改时间）
|
||
|
||
**如果找不到**：
|
||
- 输出错误信息
|
||
- 说明可能原因：
|
||
- 当前不在 Claude Code 会话中
|
||
- 会话数据已被清理
|
||
- 项目路径不匹配
|
||
|
||
**提取信息**：
|
||
- 会话文件的完整路径
|
||
- 会话 UUID（文件名不含扩展名）
|
||
|
||
### 2. 读取并解析会话数据
|
||
|
||
a. 使用 Read 工具读取整个 JSONL 文件
|
||
```bash
|
||
# 读取会话文件
|
||
Read tool: $CURRENT_SESSION
|
||
```
|
||
|
||
b. 解析 JSONL 数据并提取关键信息
|
||
- 使用 Python 脚本处理 JSON 数据（跨平台兼容）
|
||
- 提取以下信息：
|
||
* 第一条用户消息（作为会话标题）
|
||
* 所有用户消息和 AI 响应
|
||
* TodoWrite 工具调用（进度信息）
|
||
* AskUserQuestion 工具调用（关键决策）
|
||
* Write/Edit 工具调用（文件变更）
|
||
* 消息时间戳（开始和结束时间）
|
||
|
||
c. 解析脚本实现
|
||
```python
|
||
import json
|
||
import sys
|
||
from datetime import datetime
|
||
|
||
# 读取 JSONL 并解析
|
||
messages = []
|
||
todos = []
|
||
decisions = []
|
||
file_changes = []
|
||
|
||
for line in sys.stdin:
|
||
msg = json.loads(line.strip())
|
||
messages.append(msg)
|
||
|
||
# 提取 TodoWrite
|
||
if msg.get('type') == 'tool_use' and msg.get('name') == 'TodoWrite':
|
||
todos.append(msg.get('input', {}).get('todos', []))
|
||
|
||
# 提取 AskUserQuestion
|
||
if msg.get('type') == 'tool_use' and msg.get('name') == 'AskUserQuestion':
|
||
decisions.append({
|
||
'timestamp': msg.get('timestamp'),
|
||
'questions': msg.get('input', {}).get('questions', []),
|
||
'answers': msg.get('input', {}).get('answers', {})
|
||
})
|
||
|
||
# 提取文件操作
|
||
if msg.get('type') == 'tool_use' and msg.get('name') in ['Write', 'Edit']:
|
||
file_changes.append({
|
||
'operation': 'created' if msg.get('name') == 'Write' else 'modified',
|
||
'path': msg.get('input', {}).get('file_path', ''),
|
||
'timestamp': msg.get('timestamp')
|
||
})
|
||
|
||
# 输出结果
|
||
print(json.dumps({
|
||
'messages': messages,
|
||
'todos': todos,
|
||
'decisions': decisions,
|
||
'file_changes': file_changes
|
||
}))
|
||
```
|
||
|
||
### 3. 生成会话摘要
|
||
|
||
a. 提取会话元数据
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"sessionId": "{SESSION_UUID}",
|
||
"projectPath": "{CURRENT_DIR}",
|
||
"projectName": "{从路径提取最后一部分}",
|
||
"savedAt": "{当前时间 ISO 8601}",
|
||
"startTime": "{第一条消息时间}",
|
||
"endTime": "{最后一条消息时间}",
|
||
"messageCount": {总消息数},
|
||
"userMessageCount": {用户消息数},
|
||
"assistantMessageCount": {AI 响应数}
|
||
}
|
||
```
|
||
|
||
b. 生成会话概览
|
||
- 标题：使用第一条用户消息（限制 100 字符）
|
||
- 描述：简要总结会话内容（AI 生成，100-200 字）
|
||
- 关键词：从标题和主要操作中提取（3-5 个）
|
||
|
||
c. 整理进度信息
|
||
- 从最后一次 TodoWrite 调用中提取任务列表
|
||
- 统计已完成/进行中/待办任务数量
|
||
- 保留任务的 content、status、activeForm
|
||
|
||
d. 整理关键决策
|
||
- 记录所有 AskUserQuestion 交互
|
||
- 包含问题、选项、用户答案
|
||
- 记录时间戳
|
||
|
||
e. 整理文件变更
|
||
- 列出所有文件操作
|
||
- 记录操作类型（创建/修改/删除）
|
||
- 记录相对路径和时间戳
|
||
|
||
f. 检测实施方案文档
|
||
- 搜索 docs/todo/ 目录下的方案文档
|
||
- 如果找到，提取文件路径
|
||
- 提取方案要点（前 3-5 个要点）
|
||
|
||
### 4. 保存到分层存储
|
||
|
||
a. 创建存储目录（项目本地）
|
||
```bash
|
||
# 存储目录结构（相对路径，跨平台兼容）
|
||
SUMMARY_DIR="./.claude-sessions/summaries/$SESSION_UUID"
|
||
mkdir -p "$SUMMARY_DIR"
|
||
|
||
# 创建导出目录
|
||
EXPORT_DIR="./.claude-sessions/exports"
|
||
mkdir -p "$EXPORT_DIR"
|
||
```
|
||
|
||
b. 写入 summary.json
|
||
- 使用 Write 工具写入摘要文件
|
||
- 包含所有元数据、概览、进度、决策、文件变更信息
|
||
- 格式化 JSON（便于阅读）
|
||
|
||
c. 复制完整 JSONL（使用 Bash cp 命令或 Read+Write 工具）
|
||
- 将找到的会话文件复制到存储目录
|
||
- 目标：`$SUMMARY_DIR/details.jsonl`
|
||
- 确保完整复制，不修改内容
|
||
|
||
d. 验证保存成功
|
||
- 检查文件是否存在
|
||
- 验证文件大小 > 0
|
||
- 如果失败，输出错误信息
|
||
|
||
### 5. 输出确认信息
|
||
|
||
输出格式化的成功信息：
|
||
|
||
```
|
||
✅ 会话已成功保存！
|
||
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📄 保存位置（项目本地）
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
存储目录: ./.claude-sessions/summaries/{session-uuid}/
|
||
├── summary.json ({文件大小})
|
||
└── details.jsonl ({文件大小})
|
||
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📊 会话信息
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
会话标题: {标题}
|
||
项目名称: {项目名}
|
||
会话时间: {开始时间} - {结束时间}
|
||
消息总数: {数量} ({用户消息数} 用户 + {AI消息数} 助手)
|
||
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📈 工作进度
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
✅ 已完成: {数量}
|
||
🔄 进行中: {数量}
|
||
📋 待办: {数量}
|
||
总计: {总数}
|
||
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📂 文件变更
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
{列出前5个文件变更，格式：}
|
||
✨ 已创建: path/to/file1
|
||
📝 已修改: path/to/file2
|
||
...
|
||
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
💡 下一步
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
使用以下命令在新会话中继续工作：
|
||
/session-manager:continue
|
||
|
||
🤖 Generated by session-manager plugin
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 场景 1: 会话文件不存在
|
||
|
||
```
|
||
❌ 错误：找不到当前会话文件
|
||
|
||
可能原因：
|
||
1. 当前不在有效的 Claude Code 会话中
|
||
2. 会话数据已被清理
|
||
3. 项目路径编码错误
|
||
|
||
建议：
|
||
- 确保在 Claude Code 会话中执行此命令
|
||
- 检查 ~/.claude/projects/ 目录是否存在
|
||
- 尝试在新会话中重试
|
||
```
|
||
|
||
### 场景 2: 存储目录创建失败
|
||
|
||
```
|
||
❌ 错误：无法创建存储目录
|
||
|
||
目标目录: {目录路径}
|
||
|
||
可能原因：
|
||
1. 磁盘空间不足
|
||
2. 权限不足
|
||
3. 目录路径无效
|
||
|
||
建议：
|
||
- 检查磁盘空间：df -h
|
||
- 检查目录权限：ls -ld ~/.claude
|
||
- 手动创建目录：mkdir -p {目录路径}
|
||
```
|
||
|
||
### 场景 3: JSONL 解析失败
|
||
|
||
```
|
||
❌ 错误：会话数据解析失败
|
||
|
||
文件: {文件路径}
|
||
错误: {错误信息}
|
||
|
||
可能原因：
|
||
1. JSONL 文件格式损坏
|
||
2. 文件编码问题
|
||
3. 不完整的 JSON 行
|
||
|
||
建议：
|
||
- 检查文件完整性
|
||
- 尝试使用文本编辑器查看文件
|
||
- 联系支持获取帮助
|
||
```
|
||
|
||
### 场景 4: 文件写入失败
|
||
|
||
```
|
||
❌ 错误：无法写入摘要文件
|
||
|
||
目标文件: {文件路径}
|
||
错误: {错误信息}
|
||
|
||
可能原因：
|
||
1. 磁盘空间不足
|
||
2. 文件权限问题
|
||
3. 目标目录不存在
|
||
|
||
建议：
|
||
- 检查磁盘空间：df -h
|
||
- 检查文件权限
|
||
- 确保存储目录存在
|
||
```
|
||
|
||
---
|
||
|
||
## 跨平台兼容性
|
||
|
||
### 路径处理
|
||
- ✅ 使用 `$HOME` 而非 `~`
|
||
- ✅ 使用 `pwd` 获取绝对路径
|
||
- ✅ 使用 `sed` 进行路径编码（标准工具）
|
||
|
||
### JSON 处理
|
||
- ✅ 优先使用 Python 3（系统自带）
|
||
- ✅ 备选：使用 jq（如果可用）
|
||
- ✅ 使用标准 JSON 格式
|
||
|
||
### 时间处理
|
||
- ✅ 使用 `date -u` 生成 UTC 时间
|
||
- ✅ 使用 ISO 8601 格式（跨平台标准）
|
||
|
||
### 文件操作
|
||
- ✅ 使用 `cp` 复制文件
|
||
- ✅ 使用 `mkdir -p` 创建目录
|
||
- ✅ 使用 `ls -t` 排序文件
|
||
|
||
---
|
||
|
||
## 性能考虑
|
||
|
||
### 大文件处理
|
||
- 会话文件 < 1MB：直接处理
|
||
- 会话文件 1MB - 10MB：正常处理，提示可能需要等待
|
||
- 会话文件 > 10MB：警告用户，建议分批保存
|
||
|
||
### 内存使用
|
||
- 一次性读取整个 JSONL 文件到内存
|
||
- 对于大文件，可考虑流式处理（未来优化）
|
||
|
||
### 存储空间
|
||
- 每个会话约占用 100KB - 2MB
|
||
- 建议定期清理旧会话（手动或自动）
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 基本使用
|
||
```bash
|
||
# 在工作一段时间后保存会话
|
||
/session-manager:save
|
||
|
||
# 输出：
|
||
# ✅ 会话已成功保存！
|
||
# 会话标题: 实现用户认证功能
|
||
# 进度: 5/8 已完成
|
||
# ...
|
||
```
|
||
|
||
### 长期项目
|
||
```bash
|
||
# 每天结束工作前保存
|
||
/session-manager:save
|
||
|
||
# 第二天开始工作时恢复
|
||
/session-manager:continue
|
||
```
|
||
|
||
### 任务切换
|
||
```bash
|
||
# 项目 A - 保存当前进度
|
||
/session-manager:save
|
||
|
||
# 切换到项目 B
|
||
cd ~/project-b
|
||
|
||
# 项目 B - 保存进度
|
||
/session-manager:save
|
||
|
||
# 稍后回到项目 A
|
||
cd ~/project-a
|
||
/session-manager:continue
|
||
```
|
||
|
||
---
|
||
|
||
**最佳实践**:
|
||
1. 🕐 定期保存：建议每完成一个重要阶段就保存一次
|
||
2. 📝 清晰命名：第一条消息尽量描述清楚要做什么
|
||
3. 📋 使用 TodoWrite：便于跟踪和恢复进度
|
||
4. 💬 记录决策：重要选择使用 AskUserQuestion 记录
|
||
5. 🗂️ 整理文件：重要方案保存到 docs/todo/ 目录
|
||
|
||
---
|
||
|
||
**注意事项**:
|
||
- ⚠️ 此命令不会修改原始会话数据
|
||
- ⚠️ 保存的数据仅在本地存储
|
||
- ⚠️ 建议定期备份 ~/.claude/session-summary/ 目录
|
||
- ⚠️ 敏感信息（API 密钥、密码）也会被保存，注意安全
|
||
|
||
---
|
||
|
||
🤖 Generated with Claude Code
|