gh-chamherry-claude-code-third-party-plugins-plugins-session-manager/commands/save-session.md at 6a4a4644313108be52407872907745ad3dd9e749

zhongwei/gh-chamherry-claude-code-third-party-plugins-plugins-session-manager

Files

Zhongwei Li 6a4a464431 Initial commit

2025-11-29 18:08:43 +08:00

11 KiB

Raw Blame History

allowed-tools, description

allowed-tools	description
Read, Write, Bash, Grep, Glob	总结并保存当前会话到本地存储

智能分析当前会话内容，提取关键信息（项目进度、实施方案、关键决策、文件变更），并保存到分层存储结构中。

核心特性:

📊 智能提取: 自动识别 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 文件

# 读取会话文件
Read tool: $CURRENT_SESSION

b. 解析 JSONL 数据并提取关键信息

使用 Python 脚本处理 JSON 数据（跨平台兼容）
提取以下信息：
- 第一条用户消息（作为会话标题）
- 所有用户消息和 AI 响应
- TodoWrite 工具调用（进度信息）
- AskUserQuestion 工具调用（关键决策）
- Write/Edit 工具调用（文件变更）
- 消息时间戳（开始和结束时间）

c. 解析脚本实现

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. 提取会话元数据

{
  "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. 创建存储目录（项目本地）

# 存储目录结构（相对路径，跨平台兼容）
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
建议定期清理旧会话（手动或自动）

使用示例

基本使用

# 在工作一段时间后保存会话
/session-manager:save

# 输出：
# ✅ 会话已成功保存！
# 会话标题: 实现用户认证功能
# 进度: 5/8 已完成
# ...

长期项目

# 每天结束工作前保存
/session-manager:save

# 第二天开始工作时恢复
/session-manager:continue

任务切换

# 项目 A - 保存当前进度
/session-manager:save

# 切换到项目 B
cd ~/project-b

# 项目 B - 保存进度
/session-manager:save

# 稍后回到项目 A
cd ~/project-a
/session-manager:continue

最佳实践:

🕐 定期保存：建议每完成一个重要阶段就保存一次
📝 清晰命名：第一条消息尽量描述清楚要做什么
📋 使用 TodoWrite：便于跟踪和恢复进度
💬 记录决策：重要选择使用 AskUserQuestion 记录
🗂️ 整理文件：重要方案保存到 docs/todo/ 目录

注意事项:

⚠️ 此命令不会修改原始会话数据
⚠️ 保存的数据仅在本地存储
⚠️ 建议定期备份 ~/.claude/session-summary/ 目录
⚠️ 敏感信息（API 密钥、密码）也会被保存，注意安全

🤖 Generated with Claude Code

11 KiB Raw Blame History Unescape Escape