# Gaoziman Claude Context Manager Claude Context Manager > Context Manager Skill - Skill: `tomevault-io/gaoziman-claude-context-manager-claude-context-manager` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/gaoziman-claude-context-manager-claude-context-manager` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/gaoziman-claude-context-manager-claude-context-manager/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/gaoziman-claude-context-manager-claude-context-manager --- # 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) ```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 会话文件结构 ```markdown --- 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 架构图/表格处理 ``` 规则： 1. ASCII 架构图必须完整保留 2. Markdown 表格必须完整保留 3. 不要将表格转换为列表 4. 保持原始格式和对齐 ``` #### 4.3.3 命令/输出处理 ``` 规则： 1. 保留执行的命令 2. 关键输出完整保留 3. 冗长的输出可以截取关键部分，标注 [输出已截断] 4. 错误信息必须完整保留 ``` --- ## 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 分析型会话模板 ```markdown ## 📊 核心内容 ### 分析目标 [分析的目标和范围] ### 分析方法 [使用的分析方法和工具] ### 分析结果 #### 1. [分析维度1] [详细分析内容，包括表格、数据、图表] #### 2. [分析维度2] [详细分析内容] ### 评分/评估 | 维度 | 得分 | 说明 | |------|------|------| | 维度1 | 8/10 | ... | ### 改进建议 1. **P0 级别**：[立即处理] 2. **P1 级别**：[近期处理] ``` ### 6.2 开发型会话模板 ```markdown ## 📊 核心内容 ### 需求描述 [功能需求的详细描述] ### 技术方案 [选择的技术方案及原因] ### 实现详情 #### 新增/修改的文件 - `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] ```yaml # 配置文件内容 ``` ### 配置文件清单 | 文件 | 路径 | 说明 | |------|------|------| | 文件1 | /path | 用途 | ### 验证方法 [如何验证配置是否成功] ### 回滚方案 [如果出问题如何回滚] ``` --- ## 7. 质量控制体系 ### 7.1 内容完整性检查 在保存上下文前，执行以下检查： ``` ┌─────────────────────────────────────────────────────────────────┐ │ 质量检查清单 Pass? │ ├─────────────────────────────────────────────────────────────────┤ │ □ 背景描述是否足够详细（>50字）？ [ ] │ │ □ 核心内容是否完整保留（非摘要）？ [ ] │ │ □ 代码示例是否完整（不是片段）？ [ ] │ │ □ 表格和架构图是否保留？ [ ] │ │ □ 关键决策是否记录了原因？ [ ] │ │ □ 任务进度是否清晰？ [ ] │ │ □ 下次继续指南是否可操作？ [ ] │ │ □ 标签是否准确且充分（≥3个）？ [ ] │ └─────────────────────────────────────────────────────────────────┘ ``` ### 7.2 可恢复性评估 评估标准：**看完这份文档后，能否立即继续工作？** | 评分 | 标准 | 说明 | |------|------|------| | ⭐⭐⭐⭐⭐ | 完美恢复 | 无需任何额外信息即可继续 | | ⭐⭐⭐⭐ | 良好恢复 | 需要少量回忆即可继续 | | ⭐⭐⭐ | 基本恢复 | 需要重新阅读部分代码 | | ⭐⭐ | 困难恢复 | 需要重新理解大量上下文 | | ⭐ | 无法恢复 | 信息严重缺失，需重新开始 | **目标**：每个保存的上下文应达到 ⭐⭐⭐⭐ 以上 ### 7.3 最小信息量标准 | 会话类型 | 最小行数 | 必须包含的章节 | |----------|----------|----------------| | 分析型 | 150+ 行 | 分析结果、评分、建议 | | 开发型 | 100+ 行 | 代码变更、测试结果 | | 调试型 | 80+ 行 | 问题、原因、方案 | | 配置型 | 60+ 行 | 步骤、配置文件、验证 | | 学习型 | 50+ 行 | 概念、示例、参考 | --- ## 8. 错误处理与边界情况 ### 8.1 文件冲突处理 ``` 场景：同一天保存多个同名会话 处理策略： 1. 自动添加序号后缀：2024-12-24_git-config_2.md 2. 或询问用户是否覆盖/重命名 3. 记录冲突日志 ``` ### 8.2 索引损坏修复 ``` 场景：index.json 损坏或不一致 处理策略： 1. 扫描 conversations/ 目录下所有 .md 文件 2. 从 YAML frontmatter 重建索引 3. 报告修复结果 4. 备份损坏的索引文件 ``` ### 8.3 大文件处理 ``` 场景：会话内容超过 500 行或 50KB 处理策略： 1. 保持核心内容完整 2. 大段重复输出可截断 3. 提供原始内容的引用路径 4. 警告用户文件较大 ``` ### 8.4 特殊字符处理 ``` 场景：文件名包含特殊字符 处理策略： 1. 替换特殊字符为下划线 2. 移除 emoji 3. 限制文件名长度 ≤ 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 跨项目上下文关联 ```json // 在 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](https://github.com/gaoziman/claude-context-manager) — distributed by [TomeVault](https://tomevault.io).