Initial commit

This commit is contained in:
Zhongwei Li
2025-11-29 18:08:43 +08:00
commit 6a4a464431
5 changed files with 1321 additions and 0 deletions

View File

@@ -0,0 +1,12 @@
{
"name": "session-manager",
"description": "会话管理插件 - 智能保存和恢复 Claude Code 会话,支持进度跟踪和工作连续性",
"version": "1.0.0",
"author": {
"name": "Wang Xuecheng",
"email": "ahut17353766123@gmail.com"
},
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# session-manager
会话管理插件 - 智能保存和恢复 Claude Code 会话,支持进度跟踪和工作连续性

View File

@@ -0,0 +1,857 @@
---
allowed-tools: Read, Write, AskUserQuestion, Bash, Grep, Glob
description: 搜索并继续之前保存的会话
---
智能搜索已保存的会话,支持按项目、时间、关键词过滤,选择后生成 Markdown 格式的会话摘要供在新会话中继续工作。
**核心特性**:
- 🔍 **智能搜索**: 支持按项目、时间范围、关键词搜索
- 📋 **可视化列表**: 清晰展示会话信息(标题、时间、进度)
- 📝 **完整导出**: 生成包含进度、方案、决策的 Markdown 文档
- 💡 **行动建议**: 自动生成后续工作建议
---
## 执行步骤
### 1. 扫描已保存的会话
a. 检查存储目录是否存在(项目本地)
```bash
SUMMARY_BASE="./.claude-sessions/summaries"
if [ ! -d "$SUMMARY_BASE" ]; then
echo "❌ 错误:未找到已保存的会话"
echo "提示:使用 /session-manager:save 保存当前会话"
echo "📁 会话将保存在项目目录: ./.claude-sessions/"
exit 1
fi
```
b. 查找所有摘要文件(项目本地)
```bash
# 查找当前项目的所有会话摘要
find "$SUMMARY_BASE" -maxdepth 2 -name "summary.json" -type f
```
c. 读取并解析所有摘要文件
- 使用 Read 工具读取每个 summary.json
- 提取关键信息用于展示:
* 会话标题
* 项目名称
* 保存时间
* 进度信息(已完成/总数)
* 会话 ID 和存储路径
d. 按保存时间排序(最新的在前)
```bash
# 使用 Python 脚本读取和排序
python3 << 'EOF'
import json
import glob
import os
from datetime import datetime
summary_files = glob.glob(os.path.expanduser("~/.claude/session-summary/**/summary.json"), recursive=True)
sessions = []
for file_path in summary_files:
with open(file_path, 'r', encoding='utf-8') as f:
data = json.load(f)
data['_file_path'] = file_path
sessions.append(data)
# 按 savedAt 时间排序
sessions.sort(key=lambda x: x.get('savedAt', ''), reverse=True)
# 输出 JSON
print(json.dumps(sessions, ensure_ascii=False))
EOF
```
### 2. 首次展示(最近 10 个)
a. 提取最近 10 个会话信息
b. 格式化展示选项
```
每个选项格式:
label: "[时间] 项目名 - 会话标题"
description: "进度X/Y 已完成 | 文件变更Z 个"
```
c. 使用 AskUserQuestion 展示列表
```yaml
question: "选择要继续的会话(显示最近 10 个):"
header: "会话列表"
multiSelect: false
options:
- label: "🔍 搜索和过滤"
description: "按项目、时间或关键词搜索会话"
- label: "[2025-11-03 16:00] claude-code-init - 添加会话管理插件"
description: "进度4/6 已完成 | 文件变更3 个"
- label: "[2025-11-03 14:30] my-project - 实现用户认证"
description: "进度5/8 已完成 | 文件变更12 个"
... (最多 10 个)
- label: "📚 查看更多..."
description: "显示更多会话(第 11-20 个)"
```
### 3. 搜索和过滤功能
#### 如果用户选择"搜索和过滤"
a. 提供搜索选项
```yaml
使用 AskUserQuestion:
question: "选择搜索条件:"
header: "搜索选项"
multiSelect: false
options:
- label: "按项目过滤"
description: "只显示特定项目的会话"
- label: "按时间范围"
description: "选择时间范围(今天、本周、本月、自定义)"
- label: "按关键词搜索"
description: "在标题和描述中搜索关键词"
- label: "返回会话列表"
description: "返回主列表"
```
#### 场景 A: 按项目过滤
1. 提取所有唯一的项目名称
```python
projects = list(set(s['projectName'] for s in sessions))
projects.sort()
```
2. 展示项目列表供选择
```yaml
question: "选择项目:"
header: "项目过滤"
multiSelect: false
options:
- label: "项目名称 1"
description: "{该项目的会话数} 个会话"
- label: "项目名称 2"
description: "{该项目的会话数} 个会话"
...
```
3. 过滤并展示该项目的会话列表
#### 场景 B: 按时间范围
1. 提供时间范围选项
```yaml
question: "选择时间范围:"
header: "时间过滤"
multiSelect: false
options:
- label: "今天"
description: "只显示今天保存的会话"
- label: "本周"
description: "显示本周保存的会话"
- label: "本月"
description: "显示本月保存的会话"
- label: "最近 7 天"
description: "显示最近 7 天的会话"
- label: "最近 30 天"
description: "显示最近 30 天的会话"
```
2. 根据选择过滤会话
```python
from datetime import datetime, timedelta
now = datetime.now()
# 根据选择计算时间范围
if choice == "今天":
start = now.replace(hour=0, minute=0, second=0)
elif choice == "本周":
start = now - timedelta(days=now.weekday())
elif choice == "本月":
start = now.replace(day=1, hour=0, minute=0, second=0)
# ...
# 过滤会话
filtered = [s for s in sessions if datetime.fromisoformat(s['savedAt']) >= start]
```
3. 展示过滤后的会话列表
#### 场景 C: 按关键词搜索
1. 询问用户输入关键词
```yaml
question: "请输入搜索关键词:"
header: "关键词搜索"
multiSelect: false
options:
- label: "输入关键词"
description: "在标题、描述、关键词中搜索"
```
2. 从用户输入中提取关键词(使用 Other 选项)
3. 在会话数据中搜索
```python
keyword = user_input.lower()
filtered = []
for session in sessions:
# 搜索标题
if keyword in session['overview']['title'].lower():
filtered.append(session)
continue
# 搜索描述
if keyword in session['overview'].get('description', '').lower():
filtered.append(session)
continue
# 搜索关键词列表
if any(keyword in kw.lower() for kw in session['overview'].get('keywords', [])):
filtered.append(session)
continue
```
4. 展示搜索结果
- 如果找到 0 个:提示未找到,返回主列表
- 如果找到 1-10 个:直接展示
- 如果找到 >10 个:展示前 10 个 + "查看更多"
### 4. 用户选择会话
#### 提取会话数据
1. 根据用户选择,定位到对应的 summary.json
2. 读取完整的摘要数据
```bash
# 读取 summary.json
Read tool: {SESSION_DIR}/summary.json
```
3. 可选:读取详细日志(如果需要提取更多上下文)
```bash
# 读取 details.jsonl可选
Read tool: {SESSION_DIR}/details.jsonl
```
### 5. 生成导出文件
#### 创建导出目录(项目本地)
```bash
EXPORT_DIR="./.claude-sessions/exports"
mkdir -p "$EXPORT_DIR"
# 生成文件名
TIMESTAMP=$(date +"%Y-%m-%d-%H-%M")
EXPORT_FILE="$EXPORT_DIR/${TIMESTAMP}-${SESSION_UUID}.md"
```
#### 生成 Markdown 内容
使用以下模板生成导出文件:
```markdown
# 会话恢复:{会话标题}
> **会话 ID**: {uuid}
> **项目**: {项目名称} (`{项目路径}`)
> **会话时间**: {开始时间} - {结束时间}
> **保存时间**: {保存时间}
> **消息总数**: {消息数} ({用户消息数} 用户 + {AI消息数} 助手)
---
## 📋 工作概述
{从 summary.json 提取的描述}
**关键词**: {关键词1}, {关键词2}, {关键词3}
---
## 📈 项目进度
### ✅ 已完成任务 ({已完成数量})
{遍历 todos筛选 status === "completed"}
- [x] {任务1内容}
- [x] {任务2内容}
...
### 🔄 进行中任务 ({进行中数量})
{遍历 todos筛选 status === "in_progress"}
- [ ] {任务内容} - 🔄 {activeForm}
### 📋 待办任务 ({待办数量})
{遍历 todos筛选 status === "pending"}
- [ ] {任务内容}
**进度总览**: {已完成}/{总数} 已完成 ({完成百分比}%)
---
## 📐 实施方案
{如果 implementation.hasDesignDoc === true}
**方案文档**: `{implementation.designDocPath}`
### 主要变更点
{遍历 implementation.mainChanges}
1. {变更点1}
2. {变更点2}
...
{如果没有方案文档}
_本会话未包含正式的实施方案文档_
---
## 💡 关键决策
{遍历 keyDecisions}
### 决策 {序号} - {格式化时间}
**问题**: {decision.question}
**选择**: {decision.answer}
{如果有多个选项,展示所有选项}
_可选项_:
- {选项1描述}
- {选项2描述}
...
---
{如果没有关键决策}
_本会话未记录关键决策_
---
## 📂 文件变更记录
{遍历 filesModified按类型分组}
### ✨ 已创建文件 ({创建文件数量})
{筛选 operation === "created"}
- `{相对路径1}` - {格式化时间}
- `{相对路径2}` - {格式化时间}
...
### 📝 已修改文件 ({修改文件数量})
{筛选 operation === "modified"}
- `{相对路径1}` - {格式化时间}
- `{相对路径2}` - {格式化时间}
...
### 🗑️ 已删除文件 ({删除文件数量})
{筛选 operation === "deleted"}
- `{相对路径1}` - {格式化时间}
...
{如果没有文件变更}
_本会话未修改任何文件_
---
## 🎯 后续行动建议
根据当前进度和待办任务,建议:
{自动生成建议,基于:}
1. 继续完成进行中的任务:
{如果有 in_progress 任务}
- {任务内容} - 当前状态:{activeForm}
2. 开始下一个待办任务:
{取第一个 pending 任务}
- {任务内容}
3. 验证已完成功能:
{基于已完成的任务生成验证建议}
- 测试 {相关功能}
- 验证 {相关文件} 的正确性
4. 更新文档:
{如果有文档相关的待办}
- 完善 {文档名称}
{如果所有任务都已完成}
🎉 **恭喜!所有任务已完成!**
建议:
- 进行全面测试
- 更新项目文档
- 准备提交代码
---
## 📚 详细对话记录
完整的对话记录已保存在:
```
{SESSION_DIR}/details.jsonl
```
如需查看完整上下文,可以:
1. 使用文本编辑器打开上述文件
2. 使用 `cat` 命令查看:`cat {SESSION_DIR}/details.jsonl`
3. 使用 `jq` 格式化查看:`jq -r '.content' {SESSION_DIR}/details.jsonl`
---
<!--
═══════════════════════════════════════════════════════════════
🤖 FOR AI ASSISTANT ONLY - 仅供 AI 助手参考
═══════════════════════════════════════════════════════════════
本部分专门提供给 AI 助手,用户通常不需要查看此内容。
## 📁 完整对话数据源
**文件路径**: `{SESSION_DIR}/details.jsonl`
**数据格式**: JSONL (每行一个 JSON 对象)
**包含内容**:
- 所有用户消息 (type: "user")
- 所有 AI 响应 (type: "assistant")
- 所有工具调用 (type: "tool_use")
- 时间戳和元数据
## 🎯 何时读取完整对话
**建议读取的场景**:
1. ✅ 用户要求了解详细的讨论过程
2. ✅ 需要理解某个决策的完整背景
3. ✅ 任务涉及之前讨论的具体技术细节
4. ✅ 当前摘要信息不足以完成任务
5. ✅ 需要验证之前的某个结论或约定
**无需读取的场景**:
1. ❌ 只需要了解当前进度状态
2. ❌ 只需要知道下一步做什么
3. ❌ 摘要信息已经足够清晰
4. ❌ 任务是全新的,不依赖历史细节
## 📖 如何读取
使用 Read 工具读取完整文件:
```
Read tool: {SESSION_DIR}/details.jsonl
```
**注意事项**:
- 文件可能较大 (50KB - 10MB),建议只在必要时读取
- 可以使用 Grep 工具搜索特定内容而非读取全部
- 如果只需要某类消息,可以用 Python 过滤
## 💡 智能决策建议
**第一步**: 评估摘要信息是否充足
- 如果摘要中的进度、决策、文件变更信息足够 → 直接使用摘要
- 如果用户询问"为什么这样决定"、"当时怎么讨论的" → 读取完整对话
**第二步**: 按需读取
- 如果决定读取,使用 Read 工具读取 details.jsonl
- 可以结合 Grep 搜索关键词,避免读取全部
**第三步**: 向用户解释
- 如果读取了完整对话,告知用户:"我查看了完整的对话记录..."
- 这样用户知道你的决策基于完整信息
═══════════════════════════════════════════════════════════════
END OF AI ASSISTANT SECTION
═══════════════════════════════════════════════════════════════
-->
---
## 🔗 如何继续工作
### 方式 1粘贴到新会话推荐
1. 复制上述内容(从"工作概述"到"后续行动建议"
2. 在新 Claude Code 会话中粘贴
3. 添加你的新请求,例如:
```
继续之前的工作,{描述你要做什么}
```
### 方式 2引用导出文件
在新会话中输入:
```
@./.claude-sessions/exports/{timestamp}-{uuid}.md
继续之前的工作,{描述你要做什么}
```
### 方式 3手动选择性恢复
只复制你需要的部分:
- 如果只需要恢复进度:复制"项目进度"部分
- 如果需要方案细节:复制"实施方案"部分
- 如果需要决策上下文:复制"关键决策"部分
---
**导出时间**: {当前时间}
**导出工具**: session-manager v1.0.0
🤖 Generated by session-manager plugin
```
#### 写入导出文件
```bash
# 使用 Write 工具写入
Write tool: $EXPORT_FILE
```
### 6. 展示结果
输出格式化的成功信息:
```
✅ 会话已成功导出!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 导出信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
会话标题: {标题}
项目名称: {项目名}
会话时间: {开始时间} - {结束时间}
进度状态: {已完成}/{总数} 已完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 文件位置(项目本地)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
导出文件: ./.claude-sessions/exports/{timestamp}-{uuid}.md
文件大小: {文件大小}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 如何继续工作
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
方式 1推荐: 在新会话中输入
继续之前的工作:{会话标题}
@~/.claude/session-exports/{timestamp}-{uuid}.md
{描述你要继续做的具体工作}
方式 2: 打开导出文件并复制相关内容
cat ~/.claude/session-exports/{timestamp}-{uuid}.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 后续建议行动
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{列出 2-3 个具体的后续行动建议}
1. {建议1}
2. {建议2}
3. {建议3}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 Generated by session-manager plugin
```
---
## 错误处理
### 场景 1: 没有已保存的会话
```
❌ 错误:未找到已保存的会话
存储目录: ~/.claude/session-summary/
可能原因:
1. 还没有保存过任何会话
2. 存储目录被删除或移动
3. 权限问题导致无法访问
建议:
- 使用 /session-manager:save 保存当前会话
- 检查存储目录是否存在ls -la ~/.claude/session-summary/
- 检查目录权限
```
### 场景 2: 摘要文件读取失败
```
❌ 错误:无法读取会话摘要文件
文件: {文件路径}
错误: {错误信息}
可能原因:
1. 文件已损坏
2. 文件权限问题
3. JSON 格式错误
建议:
- 尝试读取其他会话
- 检查文件完整性cat {文件路径}
- 如果多个文件都无法读取,可能需要重新保存会话
```
### 场景 3: 搜索无结果
```
未找到匹配的会话
搜索条件: {条件描述}
建议:
- 尝试使用不同的关键词
- 检查时间范围是否过窄
- 查看所有会话:选择"返回会话列表"
```
### 场景 4: 导出文件创建失败
```
❌ 错误:无法创建导出文件
目标文件: {文件路径}
错误: {错误信息}
可能原因:
1. 磁盘空间不足
2. 导出目录不存在或无写入权限
3. 文件名包含非法字符
建议:
- 检查磁盘空间df -h
- 创建导出目录mkdir -p ~/.claude/session-exports
- 检查目录权限ls -ld ~/.claude/session-exports
```
---
## 交互流程示例
### 示例 1: 快速选择最近的会话
```
用户: /session-manager:continue
系统: 显示最近 10 个会话列表
用户: 选择第二个会话
系统: ✅ 会话已成功导出!
导出文件: ~/.claude/session-exports/2025-11-03-16-30-abc123.md
```
### 示例 2: 按项目搜索
```
用户: /session-manager:continue
系统: 显示最近 10 个会话列表
用户: 选择"搜索和过滤"
系统: 显示搜索选项
用户: 选择"按项目过滤"
系统: 显示所有项目列表
- my-app (3 个会话)
- another-project (5 个会话)
用户: 选择"my-app"
系统: 显示 my-app 的 3 个会话
用户: 选择第一个
系统: ✅ 会话已成功导出!
```
### 示例 3: 按关键词搜索
```
用户: /session-manager:continue
系统: 显示最近 10 个会话列表
用户: 选择"搜索和过滤"
系统: 显示搜索选项
用户: 选择"按关键词搜索"
系统: 请输入搜索关键词
用户: 输入"认证"(通过 Other 选项)
系统: 找到 2 个匹配的会话
- [2025-11-03] my-app - 实现用户认证功能
- [2025-11-02] api-service - 添加 JWT 认证
用户: 选择第一个
系统: ✅ 会话已成功导出!
```
---
## 跨平台兼容性
### 路径处理
- ✅ 使用 `$HOME` 而非 `~`
- ✅ 使用绝对路径
- ✅ 使用 `find` 命令递归搜索(标准工具)
### JSON 处理
- ✅ 优先使用 Python 3系统自带
- ✅ 处理 UTF-8 编码
- ✅ 使用 `ensure_ascii=False` 保留中文
### 时间处理
- ✅ 解析 ISO 8601 格式
- ✅ 格式化为本地可读格式
- ✅ 计算时间范围(今天、本周等)
### 文件操作
- ✅ 使用 `mkdir -p` 创建目录
- ✅ 使用 `date` 生成时间戳
- ✅ 使用 `cat` 展示文件内容
---
## 性能优化
### 会话列表加载
- 只读取 summary.json不读取 details.jsonl
- 默认只展示最近 10 个(减少交互负担)
- 按需加载更多("查看更多"选项)
### 搜索性能
- 在内存中进行搜索Python 脚本)
- 不使用磁盘索引(保持简单)
- 对于大量会话(>100可能需要 2-3 秒
### 导出文件生成
- 一次性生成完整内容
- 不进行额外的文件读取
- 使用模板字符串拼接
---
## 使用技巧
### 最佳实践
1. **定期保存会话**
- 完成重要阶段后立即保存
- 结束工作前保存当天进度
2. **使用清晰的标题**
- 第一条消息描述清楚要做什么
- 便于后续搜索和识别
3. **利用搜索功能**
- 项目较多时,先按项目过滤
- 记不清时间时,使用关键词搜索
4. **选择性恢复**
- 不一定要恢复全部内容
- 只复制需要的部分到新会话
5. **保持存储整洁**
- 定期清理旧会话(手动)
- 备份重要会话
### 高级用法
**多项目管理**:
```bash
# 在不同项目间快速切换
cd ~/project-a
/session-manager:continue # 恢复 project-a 的工作
cd ~/project-b
/session-manager:continue # 恢复 project-b 的工作
```
**长期项目跟踪**:
```bash
# 每周五保存
/session-manager:save
# 下周一恢复,按时间过滤"本周"
/session-manager:continue
→ 选择"按时间范围" → "本周"
```
**任务切换**:
```bash
# 紧急任务插入时
/session-manager:save # 保存当前任务
# 完成紧急任务后
/session-manager:continue # 恢复之前的任务
```
---
## 注意事项
- ⚠️ 搜索只在摘要数据中进行(不搜索详细日志)
- ⚠️ 导出文件不会自动清理,需要手动管理
- ⚠️ 大量会话(>50列表加载可能稍慢
- ⚠️ 导出文件可能包含敏感信息,注意安全
---
## 未来增强
以下功能计划在未来版本中添加:
- [ ] 会话标签功能
- [ ] 会话笔记添加
- [ ] 自动清理旧会话
- [ ] 导出格式自定义
- [ ] 会话对比功能
- [ ] 团队共享支持
---
🤖 Generated with Claude Code

400
commands/save-session.md Normal file
View File

@@ -0,0 +1,400 @@
---
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

49
plugin.lock.json Normal file
View File

@@ -0,0 +1,49 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:ChamHerry/claude-code-third-party-plugins:plugins/session-manager",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "1d4c1cd23672bc042be0c0e11a733d17c7ca0f02",
"treeHash": "1daddc83113d087d7ff028e98b8077dbd163e38dbb2e41034064cbfab61c5214",
"generatedAt": "2025-11-28T10:10:02.053542Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "session-manager",
"description": "会话管理插件 - 智能保存和恢复 Claude Code 会话,支持进度跟踪和工作连续性",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "a32a6ada04439fcf8acd030c4f64df0d598a920bcac358cfd48dd54c97b2438a"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "17a31f0c06e0473d6e099b2e4efa1b82a363854bd6e1c2826d99fa4dbfb657af"
},
{
"path": "commands/save-session.md",
"sha256": "aa62129be236dd0b2d4905a6df30d11b621de36fa7d7e2542cd11618bc00857e"
},
{
"path": "commands/continue-session.md",
"sha256": "16cd433b9c48fbe883cd07b55661187a0f70eff9ebfe147330f719a4d79692d4"
}
],
"dirSha256": "1daddc83113d087d7ff028e98b8077dbd163e38dbb2e41034064cbfab61c5214"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}