feat:搭建本地存储会话历史的框架

- 将会话历史存储在C:\Users\admin\.iccoder文件下 - 在里面又会创建多个文件夹进行存储
2025-12-15 15:19:36 +08:00
parent ab6d257df2
commit a1a526bb98
6 changed files with 1004 additions and 4 deletions
--- a/docs/会话历史管理功能文档.md
+++ b/docs/会话历史管理功能文档.md
@ -0,0 +1,279 @@
+# 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/)