tomevault-io Context Manager Skill
会话上下文管理器 - 智能保存、管理和恢复 Claude Code 会话上下文
1. 设计理念
1.1 为什么需要上下文管理？
用户痛点：
- Claude Code 遇到 API 错误（如 400 参数错误）时，被迫开启新窗口
- 新会话中完全丢失之前的工作上下文
- 需要重复解释项目背景、技术决策、进度状态
- 复杂任务的连续性被打断，效率大幅降低
解决方案：
- 提供结构化的会话上下文保存机制
- 支持在新会话中快速恢复工作状态
- 建立会话知识库，便于回顾和搜索
1.2 核心设计哲学
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 保存的目的是为了「恢复」，不是为了「总结」 │
│ │
│ 想象你是在为"失忆后的自己"写备忘录， │
│ 要确保看到这份文档后能立即继续工作。 │
│ │
└─────────────────────────────────────────────────────────────────┘
1.3 设计原则
| 原则 | 描述 | 实践 |
|---|---|---|
| 完整性 | 保留足够详细的信息 | 保留完整的分析报告、代码、架构图 |
| 可恢复性 | 能够无缝继续工作 | 提供"下次继续指南"章节 |
| 可搜索性 | 便于查找历史会话 | 智能标签、全文搜索支持 |
| 结构化 | 统一的格式标准 | Markdown + YAML frontmatter |
| 渐进式 | 支持增量更新 | 可更新已保存的上下文 |
2. 功能矩阵
2.1 核心功能
| 功能 | 命令 | 描述 | 优先级 |
|---|---|---|---|
| 保存上下文 | /save-context [标题] |
保存当前会话的完整上下文 | P0 |
| 加载上下文 | /load-context [ID/序号/关键词] |
加载指定的历史上下文 | P0 |
| 列出上下文 | /list-contexts |
显示所有保存的会话列表 | P0 |
| 搜索上下文 | /search-context [关键词] |
搜索匹配的会话 | P0 |
2.2 扩展功能（规划中）
| 功能 | 命令 | 描述 | 状态 |
|---|---|---|---|
| 更新上下文 | /update-context [ID] |
更新已保存的上下文 | 待实现 |
| 删除上下文 | /delete-context [ID] |
删除指定的上下文 | 待实现 |
| 归档上下文 | /archive-context [ID] |
归档旧的上下文 | 待实现 |
| 导出上下文 | /export-context [ID] [格式] |
导出为其他格式 | 待实现 |
| 合并上下文 | /merge-contexts [ID1] [ID2] |
合并多个相关上下文 | 待实现 |
| 统计分析 | /context-stats |
显示上下文统计信息 | 待实现 |
3. 存储架构
3.1 目录结构
~/.claude/
├── conversations/ # 会话存储目录
│ ├── index.json # 会话索引文件
│ ├── 2024-12-24_git-config.md # 会话文件
│ ├── 2024-12-24_架构分析.md # 会话文件
│ └── archive/ # 归档目录（规划）
│ └── 2024-Q3/ # 按季度归档
├── commands/ # 命令定义目录
│ ├── save-context.md
│ ├── load-context.md
│ ├── list-contexts.md
│ └── search-context.md
└── skills/
└── context-manager/
└── SKILL.md # 本文件
3.2 索引文件结构 (index.json)
{
"version": "1.0.0",
"description": "Claude Code 会话上下文索引文件",
"lastUpdated": "2024-12-24T12:00:00+08:00",
"statistics": {
"totalConversations": 10,
"totalTags": 25,
"oldestConversation": "2024-01-01",
"newestConversation": "2024-12-24"
},
"conversations": [
{
"id": "uuid-string",
"title": "会话标题",
"file": "2024-12-24_标题.md",
"project": "项目名称",
"project_path": "/path/to/project",
"created_at": "ISO时间戳",
"updated_at": "ISO时间戳",
"tags": ["标签1", "标签2"],
"summary": "一句话摘要",
"type": "analysis|development|debug|config",
"status": "active|archived",
"lineCount": 200,
"relatedContexts": ["other-uuid"]
}
]
}
3.3 会话文件结构
---
id: "uuid"
title: "会话标题"
project: "项目名称"
project_path: "/path/to/project"
created_at: "ISO时间戳"
updated_at: "ISO时间戳"
tags: ["标签1", "标签2"]
summary: "一句话摘要"
type: "analysis"
version: 1
---
# 会话上下文：[标题]
## 📋 会话概述
[会话基本信息表格]
## 🎯 用户需求
[详细的用户需求描述]
## 📊 核心内容
[完整保留的分析/开发内容]
## 💡 关键决策
[技术决策及原因]
## ✅ 任务进度
[已完成/进行中/待开始的任务]
## 💻 重要代码/命令
[完整的代码片段和命令]
## ⚠️ 注意事项
[需要注意的点]
## 🚀 下次继续指南
[恢复工作的指南]
4. 智能上下文提取策略
4.1 会话类型识别
系统应自动识别会话类型，并采用对应的提取策略：
| 会话类型 | 识别特征 | 重点提取内容 |
|---|---|---|
| 分析型 (analysis) | /analysis、"分析"、"架构"、"评估" |
完整分析报告、评分、建议 |
| 开发型 (development) | "实现"、"开发"、"功能"、代码修改 | 代码变更、设计决策、测试结果 |
| 调试型 (debug) | "bug"、"错误"、"修复"、"问题" | 错误信息、排查过程、解决方案 |
| 配置型 (config) | "配置"、"部署"、"环境"、"设置" | 配置文件、命令、环境变量 |
| 学习型 (learning) | "怎么"、"什么是"、"如何" | 概念解释、示例代码、参考链接 |
| 重构型 (refactor) | "重构"、"优化"、"改进" | 前后对比、性能数据、设计模式 |
4.2 关键信息提取规则
4.2.1 必须提取的信息
┌─────────────────────────────────────────────────────────────────┐
│ 必须提取（缺一不可） │
├─────────────────────────────────────────────────────────────────┤
│ □ 用户的原始需求/问题 │
│ □ 最终的解决方案/结论 │
│ □ 关键技术决策及理由 │
│ □ 任务完成状态 │
│ □ 下次继续的入口点 │
└─────────────────────────────────────────────────────────────────┘
4.2.2 应该提取的信息
┌─────────────────────────────────────────────────────────────────┐
│ 应该提取（有则保留） │
├─────────────────────────────────────────────────────────────────┤
│ ○ 完整的分析报告/表格/架构图 │
│ ○ 重要的代码片段（完整版本） │
│ ○ 执行的命令及输出 │
│ ○ 遇到的问题及解决方法 │
│ ○ 性能数据/测试结果 │
│ ○ 参考文档/链接 │
└─────────────────────────────────────────────────────────────────┘
4.2.3 可以省略的信息
┌─────────────────────────────────────────────────────────────────┐
│ 可以省略（减少冗余） │
├─────────────────────────────────────────────────────────────────┤
│ △ 中间的试错过程（保留最终方案即可） │
│ △ 重复的确认对话 │
│ △ 工具执行的原始输出（保留关键部分） │
│ △ 临时性的调试信息 │
└─────────────────────────────────────────────────────────────────┘
4.3 特殊内容处理
4.3.1 代码块处理
规则：
1. 保留完整的代码实现，不要截断
2. 标注代码所在文件路径
3. 标注代码语言类型
4. 如果代码太长（>100行），提取核心部分并标注省略
格式：
### 文件：src/services/user.ts (第 50-120 行)
```typescript
// 完整代码内容
#### 4.3.2 架构图/表格处理
规则：
- ASCII 架构图必须完整保留
- Markdown 表格必须完整保留
- 不要将表格转换为列表
- 保持原始格式和对齐
#### 4.3.3 命令/输出处理
规则：
- 保留执行的命令
- 关键输出完整保留
- 冗长的输出可以截取关键部分，标注 [输出已截断]
- 错误信息必须完整保留
---
## 5. 智能标签系统
### 5.1 标签分类
| 类别 | 示例 | 生成规则 |
|------|------|----------|
| **技术栈** | `Java`, `Spring Boot`, `React` | 从代码/配置中自动识别 |
| **任务类型** | `架构分析`, `bug修复`, `功能开发` | 从会话类型推断 |
| **项目标签** | `ikun`, `claude-code-hub` | 从项目名称提取 |
| **状态标签** | `已完成`, `进行中`, `待处理` | 从任务进度推断 |
| **优先级** | `P0`, `P1`, `P2` | 用户指定或自动判断 |
| **主题标签** | `用户管理`, `认证系统`, `支付` | 从内容关键词提取 |
### 5.2 自动标签生成规则
```javascript
// 伪代码示例
function generateTags(session) {
const tags = [];
// 1. 技术栈检测
if (session.hasCode('java')) tags.push('Java');
if (session.hasConfig('spring')) tags.push('Spring Boot');
if (session.hasFile('.tsx')) tags.push('React');
// 2. 任务类型检测
if (session.hasKeyword('分析', '评估', '架构')) tags.push('架构分析');
if (session.hasKeyword('bug', '修复', '错误')) tags.push('bug修复');
if (session.hasKeyword('实现', '开发', '功能')) tags.push('功能开发');
// 3. 项目标签
tags.push(session.projectName);
// 4. 状态标签
if (session.allTasksCompleted()) tags.push('已完成');
else if (session.hasInProgressTasks()) tags.push('进行中');
return tags;
}
5.3 标签数量建议
- 最少：3 个标签（项目 + 类型 + 主题）
- 推荐：5-8 个标签
- 最多：10 个标签（避免过度标签化）
6. 会话类型模板
6.1 分析型会话模板
## 📊 核心内容
### 分析目标
[分析的目标和范围]
### 分析方法
[使用的分析方法和工具]
### 分析结果
#### 1. [分析维度1]
[详细分析内容，包括表格、数据、图表]
#### 2. [分析维度2]
[详细分析内容]
### 评分/评估
| 维度 | 得分 | 说明 |
|------|------|------|
| 维度1 | 8/10 | ... |
### 改进建议
1. **P0 级别**：[立即处理]
2. **P1 级别**：[近期处理]
6.2 开发型会话模板
## 📊 核心内容
### 需求描述
[功能需求的详细描述]
### 技术方案
[选择的技术方案及原因]
### 实现详情
#### 新增/修改的文件
- `path/to/file1.ts` - [修改说明]
- `path/to/file2.ts` - [修改说明]
#### 核心代码
```typescript
// 关键实现代码
测试结果
[测试命令、结果、覆盖率等]
部署说明
[如何部署、环境要求等]
### 6.3 调试型会话模板
```markdown
## 📊 核心内容
### 问题描述
- **现象**：[用户看到的问题]
- **错误信息**：[完整的错误日志]
- **复现步骤**：[如何复现]
### 排查过程
1. [排查步骤1] → 结果
2. [排查步骤2] → 结果
### 根本原因
[问题的根本原因分析]
### 解决方案
```diff
- 旧代码
+ 新代码
预防措施
[如何避免类似问题]
### 6.4 配置型会话模板
```markdown
## 📊 核心内容
### 配置目标
[要配置什么，达到什么效果]
### 配置步骤
#### 1. [步骤1]
```bash
# 命令
2. [步骤2]
# 配置文件内容
配置文件清单
| 文件 | 路径 | 说明 |
|---|---|---|
| 文件1 | /path | 用途 |
验证方法
[如何验证配置是否成功]
回滚方案
[如果出问题如何回滚]
---
## 7. 质量控制体系
### 7.1 内容完整性检查
在保存上下文前，执行以下检查：
┌─────────────────────────────────────────────────────────────────┐ │ 质量检查清单 Pass? │ ├─────────────────────────────────────────────────────────────────┤ │ □ 背景描述是否足够详细（>50字）？ [ ] │ │ □ 核心内容是否完整保留（非摘要）？ [ ] │ │ □ 代码示例是否完整（不是片段）？ [ ] │ │ □ 表格和架构图是否保留？ [ ] │ │ □ 关键决策是否记录了原因？ [ ] │ │ □ 任务进度是否清晰？ [ ] │ │ □ 下次继续指南是否可操作？ [ ] │ │ □ 标签是否准确且充分（≥3个）？ [ ] │ └─────────────────────────────────────────────────────────────────┘
### 7.2 可恢复性评估
评估标准：**看完这份文档后，能否立即继续工作？**
| 评分 | 标准 | 说明 |
|------|------|------|
| ⭐⭐⭐⭐⭐ | 完美恢复 | 无需任何额外信息即可继续 |
| ⭐⭐⭐⭐ | 良好恢复 | 需要少量回忆即可继续 |
| ⭐⭐⭐ | 基本恢复 | 需要重新阅读部分代码 |
| ⭐⭐ | 困难恢复 | 需要重新理解大量上下文 |
| ⭐ | 无法恢复 | 信息严重缺失，需重新开始 |
**目标**：每个保存的上下文应达到 ⭐⭐⭐⭐ 以上
### 7.3 最小信息量标准
| 会话类型 | 最小行数 | 必须包含的章节 |
|----------|----------|----------------|
| 分析型 | 150+ 行 | 分析结果、评分、建议 |
| 开发型 | 100+ 行 | 代码变更、测试结果 |
| 调试型 | 80+ 行 | 问题、原因、方案 |
| 配置型 | 60+ 行 | 步骤、配置文件、验证 |
| 学习型 | 50+ 行 | 概念、示例、参考 |
---
## 8. 错误处理与边界情况
### 8.1 文件冲突处理
场景：同一天保存多个同名会话
处理策略：
- 自动添加序号后缀：2024-12-24_git-config_2.md
- 或询问用户是否覆盖/重命名
- 记录冲突日志
### 8.2 索引损坏修复
场景：index.json 损坏或不一致
处理策略：
- 扫描 conversations/ 目录下所有 .md 文件
- 从 YAML frontmatter 重建索引
- 报告修复结果
- 备份损坏的索引文件
### 8.3 大文件处理
场景：会话内容超过 500 行或 50KB
处理策略：
- 保持核心内容完整
- 大段重复输出可截断
- 提供原始内容的引用路径
- 警告用户文件较大
### 8.4 特殊字符处理
场景：文件名包含特殊字符
处理策略：
- 替换特殊字符为下划线
- 移除 emoji
- 限制文件名长度 ≤ 100 字符
---
## 9. 操作指南
### 9.1 保存上下文操作流程
┌──────────────────┐ │ 用户执行命令 │ /save-context [可选标题] └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 1. 获取元信息 │ 日期、UUID、项目路径 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 2. 分析会话 │ 识别类型、提取关键信息 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 3. 生成标签 │ 自动 + 手动标签 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 4. 构建文档 │ 按模板生成 Markdown └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 5. 质量检查 │ 执行检查清单 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 6. 保存文件 │ 写入 .md 文件 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 7. 更新索引 │ 更新 index.json └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 8. 报告结果 │ 显示保存状态和统计 └──────────────────┘
### 9.2 加载上下文操作流程
┌──────────────────┐ │ 用户执行命令 │ /load-context [ID/序号/关键词] └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 1. 解析参数 │ 数字→序号，UUID→ID，文本→搜索 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 2. 查找会话 │ 从索引中查找匹配记录 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 3. 读取文件 │ 加载对应的 .md 文件 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 4. 格式化展示 │ 清晰地显示上下文内容 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 5. 提示恢复 │ 告知用户如何继续工作 └──────────────────┘
### 9.3 搜索上下文操作流程
┌──────────────────┐ │ 用户执行命令 │ /search-context [关键词] └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 1. 解析关键词 │ 分词、识别标签搜索(#) └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 2. 索引搜索 │ 标题、摘要、标签快速匹配 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 3. 全文搜索 │ 需要时读取文件内容搜索 │ (可选) │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 4. 相关度排序 │ 按匹配度排序结果 └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 5. 展示结果 │ 高亮匹配、显示摘要 └──────────────────┘
---
## 10. 最佳实践
### 10.1 何时保存上下文？
**推荐保存的场景**：
| 场景 | 原因 | 优先级 |
|------|------|--------|
| 完成一个功能开发 | 记录实现细节 | ⭐⭐⭐⭐⭐ |
| 完成架构分析 | 保留完整分析报告 | ⭐⭐⭐⭐⭐ |
| 解决一个复杂 bug | 记录排查过程 | ⭐⭐⭐⭐⭐ |
| 进行大量配置 | 便于复现和回滚 | ⭐⭐⭐⭐ |
| 会话即将结束 | 保存当前进度 | ⭐⭐⭐⭐ |
| 遇到 API 错误前 | 防止丢失上下文 | ⭐⭐⭐⭐⭐ |
| 做出重要技术决策 | 记录决策理由 | ⭐⭐⭐⭐ |
**不推荐保存的场景**：
- 简单的一问一答
- 纯粹的信息查询
- 临时的代码片段查看
- 未产生实质性工作成果
### 10.2 如何组织标签？
推荐的标签结构：
[项目名] + [技术栈] + [任务类型] + [主题] + [状态]
示例： claude-code-hub, TypeScript, 功能开发, 用户管理, 已完成 ikun, Java, bug修复, OAuth认证, 进行中
### 10.3 如何有效恢复上下文？
1. **使用 `/list-contexts` 查看最近的会话**
2. **使用 `/search-context` 搜索特定主题**
3. **使用 `/load-context` 加载后，阅读"下次继续指南"**
4. **告诉 Claude "请基于已加载的上下文继续 xxx"**
### 10.4 上下文维护建议
| 建议 | 说明 |
|------|------|
| 定期清理 | 每月归档 3 个月前的上下文 |
| 合并相关 | 同一功能的多次会话可以合并 |
| 更新标签 | 任务完成后更新状态标签 |
| 关联引用 | 相关的上下文互相引用 |
---
## 11. 与其他系统的集成
### 11.1 与项目 CLAUDE.md 的关系
CLAUDE.md (项目级) ├── 项目整体说明 ├── 开发规范 ├── 技术栈说明 └── 全局配置
conversations/*.md (会话级) ├── 单次会话的详细记录 ├── 具体任务的实现细节 ├── 临时性的工作上下文 └── 可恢复的工作状态
关系：
- CLAUDE.md 提供项目背景
- conversations/ 记录具体工作
- 两者互补，不重复
### 11.2 与 Git 的集成建议
```bash
# 建议：将 conversations/ 加入 .gitignore
# 原因：会话上下文是个人工作记录，不应提交到仓库
# ~/.gitignore_global
.claude/conversations/
# 或者在项目 .gitignore 中
.claude/
11.3 跨项目上下文关联
// 在 index.json 中支持关联
{
"id": "uuid-1",
"relatedContexts": ["uuid-2", "uuid-3"],
"crossProjectRefs": [
{
"project": "other-project",
"contextId": "uuid-4",
"relation": "依赖"
}
]
}
12. 版本历史
| 版本 | 日期 | 更新内容 |
|---|---|---|
| 1.0.0 | 2024-12-24 | 初始版本，基础功能 |
| 2.0.0 | 2024-12-24 | 全面重构，增加智能提取、质量控制、会话模板等 |
13. 使用示例
示例 1：保存分析型会话
用户：/save-context 用户管理功能分析
系统执行：
1. 识别会话类型：分析型
2. 提取完整分析报告（保留所有表格、架构图）
3. 生成标签：claude-code-hub, TypeScript, 架构分析, 用户管理, RBAC, 已完成
4. 保存文件：2024-12-24_用户管理功能分析.md
5. 更新索引
6. 报告：✅ 保存成功，共 350 行，8 个标签
示例 2：搜索并加载上下文
用户：/search-context git
系统返回：
🔍 搜索结果：「git」
找到 2 个匹配的会话：
[1] Git 仓库配置与文档拆分
📁 ikun-main | 🕐 2024-12-24 | 🏷️ #git #配置
[2] Git 工作流优化
📁 claude-code-hub | 🕐 2024-12-20 | 🏷️ #git #CI/CD
用户：/load-context 1
系统加载并展示上下文内容，提示可以继续工作。
14. 常见问题
Q1: 保存的内容太简略怎么办？
A: 检查 save-context.md 命令是否是最新版本，确保遵循"恢复而非总结"的原则。
Q2: 如何恢复损坏的索引？
A: 手动删除 index.json，系统会在下次操作时重建。或执行索引修复命令。
Q3: 可以修改已保存的上下文吗？
A: 可以直接编辑 .md 文件，但需要同步更新 index.json 中的 updated_at。
Q4: 上下文文件可以备份吗？
A: 可以将 ~/.claude/conversations/ 目录备份到云存储或其他位置。
Skill 版本：2.0.0 | 最后更新：2025-12-24
Source: gaoziman/claude-context-manager — distributed by TomeVault.