# IC Coder 插件 - 会话历史管理功能实现文档

## 概述

本次更新为 IC Coder 插件添加了完整的会话历史管理功能，实现了基于任务（Task）的对话历史持久化存储，采用 LangChain4j 兼容的消息格式。

## 核心功能

### 1. 会话历史管理系统

#### 存储架构
- **存储位置**: `~/.iccoder/projects/{项目路径编码}/{taskId}/`
- **项目路径编码规则**:
  - 移除冒号 `:`
  - 将斜杠 `/` 和反斜杠 `\` 替换为 `--`
  - 示例: `C:\Users\admin\Documents\Project` → `C--Users-admin-Documents-Project`

#### 文件结构
每个任务目录包含三个文件：
```
~/.iccoder/projects/{编码后的项目路径}/{taskId}/
├── meta.json                    # 任务元数据
├── conversation.json            # 对话历史
└── conversation_meta.jsonl      # 对话轮次元数据（JSONL格式）
```

### 2. 新增类型定义 (`src/types/chatHistory.ts`)

#### 消息类型
- **MessageType 枚举**: `SYSTEM`, `USER`, `AI`, `TOOL_EXECUTION_RESULT`
- **消息接口**:
  - `SystemMessage`: 系统消息
  - `UserMessage`: 用户消息（支持多内容块）
  - `AiMessage`: AI 回复（支持工具调用和思考过程）
  - `ToolExecutionResultMessage`: 工具执行结果

#### 元数据结构
- **TaskMeta**: 任务元数据
  - 任务 ID、名称、项目路径
  - 创建/更新时间
  - Token 使用统计

- **ConversationMeta**: 对话轮次元数据
  - 轮次 ID、时间戳
  - Token 使用量
  - 模型信息、响应耗时

### 3. ChatHistoryManager 单例类 (`src/utils/chatHistoryManager.ts`)

#### 核心方法

**任务管理**:
- `createTask(projectPath, taskName)`: 创建新任务
- `switchTask(projectPath, taskId)`: 切换到指定任务
- `listProjectTasks(projectPath)`: 列出项目所有任务
- `getCurrentTaskSession()`: 获取当前任务完整会话

**消息记录**:
- `addUserMessage(text)`: 添加用户消息
- `addAiMessage(text, toolRequests?)`: 添加 AI 消息
- `addSystemMessage(text)`: 添加系统消息
- `recordTurnMeta(turnId, usage, model, duration)`: 记录对话轮次元数据

**自动化功能**:
- 自动创建存储目录
- 首次使用时自动创建默认任务
- 自动更新任务时间戳和 Token 统计

### 4. 集成到消息处理流程 (`src/utils/messageHandler.ts`)

#### 修改点
- 在 `handleUserMessage()` 中自动记录用户消息
- 在所有 AI 回复点自动记录 AI 消息
- 支持文件操作、VCD 生成等场景的历史记录

#### 记录场景
- 普通对话消息
- 文件操作（创建、删除、读取、更新、重命名、替换）
- VCD 文件生成流程
- 错误消息

### 5. 插件初始化 (`src/extension.ts`)

- 导入 `ChatHistoryManager`
- 插件激活时自动初始化历史管理器
- 为后续命令实现预留接口（已在 `package.json` 中定义）

## 预留命令（待实现）

在 `package.json` 中已定义以下命令，但在 `extension.ts` 中暂时注释：
- `ic-coder.viewHistory`: 查看会话历史
- `ic-coder.newSession`: 新建会话
- `ic-coder.exportSession`: 导出当前会话
- `ic-coder.deleteSession`: 删除会话
- `ic-coder.clearHistory`: 清空会话历史
- `ic-coder.searchSession`: 搜索会话

## 技术特点

1. **单例模式**: 确保全局唯一的历史管理器实例
2. **自动初始化**: 首次使用时自动创建必要的目录和文件
3. **LangChain4j 兼容**: 消息格式与 LangChain4j 保持一致
4. **跨平台支持**: 使用 VSCode API 处理文件系统，支持 Windows/Linux/macOS
5. **错误处理**: 完善的异常捕获和错误提示
6. **增量更新**: 使用 JSONL 格式追加对话元数据，避免重写整个文件

## 使用示例

```typescript
// 获取历史管理器实例
const historyManager = ChatHistoryManager.getInstance();

// 创建新任务
await historyManager.createTask('/path/to/project', '实现计数器模块');

// 记录对话
await historyManager.addUserMessage('帮我创建一个计数器');
await historyManager.addAiMessage('好的，我来帮你创建计数器模块...');

// 记录轮次元数据
await historyManager.recordTurnMeta(1, {
  inputTokens: 100,
  outputTokens: 200,
  totalTokens: 300
}, 'gpt-4', 2.5);

// 获取当前会话
const session = await historyManager.getCurrentTaskSession();
```

## 数据格式示例

### meta.json
```json
{
  "taskId": "task_20231215_abc123",
  "taskName": "实现计数器模块",
  "projectPath": "D:\\ICCoderPlugin\\ic-coder",
  "createdAt": "2023-12-15T10:30:00.000Z",
  "updatedAt": "2023-12-15T11:45:00.000Z",
  "stats": {
    "credits": 0,
    "totalTokens": 5000,
    "inputTokens": 2000,
    "outputTokens": 3000
  }
}
```

### conversation.json
```json
[
  {
    "type": "USER",
    "contents": [
      {
        "type": "TEXT",
        "text": "帮我创建一个计数器"
      }
    ]
  },
  {
    "type": "AI",
    "text": "好的，我来帮你创建计数器模块..."
  }
]
```

### conversation_meta.jsonl
```jsonl
{"turnId":1,"timestamp":"2023-12-15T10:30:00.000Z","usage":{"inputTokens":100,"outputTokens":200,"totalTokens":300},"model":"gpt-4","duration":2.5}
{"turnId":2,"timestamp":"2023-12-15T10:32:00.000Z","usage":{"inputTokens":150,"outputTokens":250,"totalTokens":400},"model":"gpt-4","duration":3.2}
```

## 文件修改清单

### 新增文件
1. `src/types/chatHistory.ts` - 类型定义文件
2. `src/utils/chatHistoryManager.ts` - 会话历史管理器

### 修改文件
1. `src/extension.ts` - 导入 ChatHistoryManager
2. `src/utils/messageHandler.ts` - 集成历史记录功能
3. `package.json` - 定义会话管理相关命令

## 关键代码位置

### 用户消息记录
- 文件: `src/utils/messageHandler.ts:29-30`
- 代码: `await historyManager.addUserMessage(text);`

### AI 消息记录
- 文件: `src/utils/messageHandler.ts:54`
- 代码: `await historyManager.addAiMessage(reply);`

### 文件操作历史记录
- 文件: `src/utils/messageHandler.ts:194, 207, 217, 227, 243, 263`
- 各种文件操作后都会记录 AI 消息

### 任务自动创建
- 文件: `src/utils/chatHistoryManager.ts:269-279`
- 方法: `ensureCurrentTask()`

## 后续开发建议

1. **实现预留的会话管理命令**
   - 查看历史：展示任务列表和对话内容
   - 新建会话：创建新任务并切换
   - 导出会话：支持 Markdown、JSON 等格式
   - 删除会话：删除指定任务目录
   - 清空历史：清空所有会话数据
   - 搜索会话：按关键词搜索对话内容

2. **增强功能**
   - 添加会话统计和可视化面板
   - 支持多任务并行管理
   - 实现会话备份和恢复功能
   - 添加会话标签和分类
   - 支持会话合并和拆分

3. **性能优化**
   - 实现会话数据的懒加载
   - 添加缓存机制减少文件读写
   - 优化大型会话的加载速度

4. **用户体验**
   - 添加会话切换的快捷键
   - 在状态栏显示当前任务信息
   - 提供会话导入功能
   - 支持会话模板

## 测试建议

1. **单元测试**
   - 测试项目路径编码/解码
   - 测试任务创建和切换
   - 测试消息添加和读取
   - 测试元数据更新

2. **集成测试**
   - 测试完整的对话流程
   - 测试文件操作的历史记录
   - 测试跨会话切换
   - 测试异常情况处理

3. **性能测试**
   - 测试大量消息的读写性能
   - 测试多任务并发访问
   - 测试长时间运行的稳定性

## 注意事项

1. **数据安全**
   - 会话数据存储在用户主目录，确保权限正确
   - 敏感信息不应记录到历史中
   - 定期清理过期会话数据

2. **兼容性**
   - 确保跨平台路径处理正确
   - 注意文件编码问题（统一使用 UTF-8）
   - 保持与 LangChain4j 格式的兼容性

3. **错误处理**
   - 文件系统操作都应有异常捕获
   - 提供友好的错误提示
   - 记录详细的错误日志

## 版本信息

- **功能版本**: v1.0.0
- **实现日期**: 2025-12-15
- **兼容版本**: VSCode ^1.107.0
- **依赖**: 无额外依赖，仅使用 VSCode API

## 参考资料

- [LangChain4j 消息格式](https://docs.langchain4j.dev/)
- [VSCode 文件系统 API](https://code.visualstudio.com/api/references/vscode-api#FileSystem)
- [JSONL 格式规范](http://jsonlines.org/)