280 lines
8.1 KiB
Markdown
280 lines
8.1 KiB
Markdown
# 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/)
|