┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   保存的目的是为了「恢复」，不是为了「总结」                      │
│                                                                 │
│   想象你是在为"失忆后的自己"写备忘录，                          │
│   要确保看到这份文档后能立即继续工作。                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

~/.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                 # 本文件

{
  "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"]
    }
  ]
}

---
id: "uuid"
title: "会话标题"
project: "项目名称"
project_path: "/path/to/project"
created_at: "ISO时间戳"
updated_at: "ISO时间戳"
tags: ["标签1", "标签2"]
summary: "一句话摘要"
type: "analysis"
version: 1
---

# 会话上下文：[标题]

## 📋 会话概述
[会话基本信息表格]

## 🎯 用户需求
[详细的用户需求描述]

## 📊 核心内容
[完整保留的分析/开发内容]

## 💡 关键决策
[技术决策及原因]

## ✅ 任务进度
[已完成/进行中/待开始的任务]

## 💻 重要代码/命令
[完整的代码片段和命令]

## ⚠️ 注意事项
[需要注意的点]

## 🚀 下次继续指南
[恢复工作的指南]

┌─────────────────────────────────────────────────────────────────┐
│ 必须提取（缺一不可）                                             │
├─────────────────────────────────────────────────────────────────┤
│ □ 用户的原始需求/问题                                           │
│ □ 最终的解决方案/结论                                           │
│ □ 关键技术决策及理由                                            │
│ □ 任务完成状态                                                  │
│ □ 下次继续的入口点                                              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 应该提取（有则保留）                                             │
├─────────────────────────────────────────────────────────────────┤
│ ○ 完整的分析报告/表格/架构图                                    │
│ ○ 重要的代码片段（完整版本）                                    │
│ ○ 执行的命令及输出                                              │
│ ○ 遇到的问题及解决方法                                          │
│ ○ 性能数据/测试结果                                             │
│ ○ 参考文档/链接                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 可以省略（减少冗余）                                             │
├─────────────────────────────────────────────────────────────────┤
│ △ 中间的试错过程（保留最终方案即可）                            │
│ △ 重复的确认对话                                                │
│ △ 工具执行的原始输出（保留关键部分）                            │
│ △ 临时性的调试信息                                              │
└─────────────────────────────────────────────────────────────────┘

规则：
1. 保留完整的代码实现，不要截断
2. 标注代码所在文件路径
3. 标注代码语言类型
4. 如果代码太长（>100行），提取核心部分并标注省略

格式：
### 文件：src/services/user.ts (第 50-120 行)
```typescript
// 完整代码内容

#### 4.3.2 架构图/表格处理

#### 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;
}

## 📊 核心内容

### 分析目标
[分析的目标和范围]

### 分析方法
[使用的分析方法和工具]

### 分析结果

#### 1. [分析维度1]
[详细分析内容，包括表格、数据、图表]

#### 2. [分析维度2]
[详细分析内容]

### 评分/评估
| 维度 | 得分 | 说明 |
|------|------|------|
| 维度1 | 8/10 | ... |

### 改进建议
1. **P0 级别**：[立即处理]
2. **P1 级别**：[近期处理]

## 📊 核心内容

### 需求描述
[功能需求的详细描述]

### 技术方案
[选择的技术方案及原因]

### 实现详情

#### 新增/修改的文件
- `path/to/file1.ts` - [修改说明]
- `path/to/file2.ts` - [修改说明]

#### 核心代码
```typescript
// 关键实现代码

### 6.3 调试型会话模板

```markdown
## 📊 核心内容

### 问题描述
- **现象**：[用户看到的问题]
- **错误信息**：[完整的错误日志]
- **复现步骤**：[如何复现]

### 排查过程
1. [排查步骤1] → 结果
2. [排查步骤2] → 结果

### 根本原因
[问题的根本原因分析]

### 解决方案
```diff
- 旧代码
+ 新代码

### 6.4 配置型会话模板

```markdown
## 📊 核心内容

### 配置目标
[要配置什么，达到什么效果]

### 配置步骤

#### 1. [步骤1]
```bash
# 命令

# 配置文件内容

---

## 7. 质量控制体系

### 7.1 内容完整性检查

在保存上下文前，执行以下检查：

### 7.2 可恢复性评估

评估标准：**看完这份文档后，能否立即继续工作？**

| 评分 | 标准 | 说明 |
|------|------|------|
| ⭐⭐⭐⭐⭐ | 完美恢复 | 无需任何额外信息即可继续 |
| ⭐⭐⭐⭐ | 良好恢复 | 需要少量回忆即可继续 |
| ⭐⭐⭐ | 基本恢复 | 需要重新阅读部分代码 |
| ⭐⭐ | 困难恢复 | 需要重新理解大量上下文 |
| ⭐ | 无法恢复 | 信息严重缺失，需重新开始 |

**目标**：每个保存的上下文应达到 ⭐⭐⭐⭐ 以上

### 7.3 最小信息量标准

| 会话类型 | 最小行数 | 必须包含的章节 |
|----------|----------|----------------|
| 分析型 | 150+ 行 | 分析结果、评分、建议 |
| 开发型 | 100+ 行 | 代码变更、测试结果 |
| 调试型 | 80+ 行 | 问题、原因、方案 |
| 配置型 | 60+ 行 | 步骤、配置文件、验证 |
| 学习型 | 50+ 行 | 概念、示例、参考 |

---

## 8. 错误处理与边界情况

### 8.1 文件冲突处理

### 8.2 索引损坏修复

### 8.3 大文件处理

### 8.4 特殊字符处理

---

## 9. 操作指南

### 9.1 保存上下文操作流程

### 9.2 加载上下文操作流程

### 9.3 搜索上下文操作流程

---

## 10. 最佳实践

### 10.1 何时保存上下文？

**推荐保存的场景**：

| 场景 | 原因 | 优先级 |
|------|------|--------|
| 完成一个功能开发 | 记录实现细节 | ⭐⭐⭐⭐⭐ |
| 完成架构分析 | 保留完整分析报告 | ⭐⭐⭐⭐⭐ |
| 解决一个复杂 bug | 记录排查过程 | ⭐⭐⭐⭐⭐ |
| 进行大量配置 | 便于复现和回滚 | ⭐⭐⭐⭐ |
| 会话即将结束 | 保存当前进度 | ⭐⭐⭐⭐ |
| 遇到 API 错误前 | 防止丢失上下文 | ⭐⭐⭐⭐⭐ |
| 做出重要技术决策 | 记录决策理由 | ⭐⭐⭐⭐ |

**不推荐保存的场景**：

- 简单的一问一答
- 纯粹的信息查询
- 临时的代码片段查看
- 未产生实质性工作成果

### 10.2 如何组织标签？

### 10.3 如何有效恢复上下文？

1. **使用 `/list-contexts` 查看最近的会话**
2. **使用 `/search-context` 搜索特定主题**
3. **使用 `/load-context` 加载后，阅读"下次继续指南"**
4. **告诉 Claude "请基于已加载的上下文继续 xxx"**

### 10.4 上下文维护建议

| 建议 | 说明 |
|------|------|
| 定期清理 | 每月归档 3 个月前的上下文 |
| 合并相关 | 同一功能的多次会话可以合并 |
| 更新标签 | 任务完成后更新状态标签 |
| 关联引用 | 相关的上下文互相引用 |

---

## 11. 与其他系统的集成

### 11.1 与项目 CLAUDE.md 的关系

### 11.2 与 Git 的集成建议

```bash
# 建议：将 conversations/ 加入 .gitignore
# 原因：会话上下文是个人工作记录，不应提交到仓库

# ~/.gitignore_global
.claude/conversations/

# 或者在项目 .gitignore 中
.claude/

// 在 index.json 中支持关联
{
  "id": "uuid-1",
  "relatedContexts": ["uuid-2", "uuid-3"],
  "crossProjectRefs": [
    {
      "project": "other-project",
      "contextId": "uuid-4",
      "relation": "依赖"
    }
  ]
}

用户：/save-context 用户管理功能分析

系统执行：
1. 识别会话类型：分析型
2. 提取完整分析报告（保留所有表格、架构图）
3. 生成标签：claude-code-hub, TypeScript, 架构分析, 用户管理, RBAC, 已完成
4. 保存文件：2024-12-24_用户管理功能分析.md
5. 更新索引
6. 报告：✅ 保存成功，共 350 行，8 个标签

用户：/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

系统加载并展示上下文内容，提示可以继续工作。