Files

Roe-xin a1a526bb98 feat:搭建本地存储会话历史的框架

- 将会话历史存储在C:\Users\admin\.iccoder文件下
- 在里面又会创建多个文件夹进行存储

2025-12-15 15:19:36 +08:00

8.1 KiB

Raw Permalink Blame History

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: 搜索会话

技术特点

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

使用示例

// 获取历史管理器实例
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

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

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

conversation_meta.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}

文件修改清单

新增文件

src/types/chatHistory.ts - 类型定义文件
src/utils/chatHistoryManager.ts - 会话历史管理器

修改文件

src/extension.ts - 导入 ChatHistoryManager
src/utils/messageHandler.ts - 集成历史记录功能
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()

后续开发建议

实现预留的会话管理命令
- 查看历史：展示任务列表和对话内容
- 新建会话：创建新任务并切换
- 导出会话：支持 Markdown、JSON 等格式
- 删除会话：删除指定任务目录
- 清空历史：清空所有会话数据
- 搜索会话：按关键词搜索对话内容
增强功能
- 添加会话统计和可视化面板
- 支持多任务并行管理
- 实现会话备份和恢复功能
- 添加会话标签和分类
- 支持会话合并和拆分
性能优化
- 实现会话数据的懒加载
- 添加缓存机制减少文件读写
- 优化大型会话的加载速度
用户体验
- 添加会话切换的快捷键
- 在状态栏显示当前任务信息
- 提供会话导入功能
- 支持会话模板

测试建议

单元测试
- 测试项目路径编码/解码
- 测试任务创建和切换
- 测试消息添加和读取
- 测试元数据更新
集成测试
- 测试完整的对话流程
- 测试文件操作的历史记录
- 测试跨会话切换
- 测试异常情况处理
性能测试
- 测试大量消息的读写性能
- 测试多任务并发访问
- 测试长时间运行的稳定性

注意事项

数据安全
- 会话数据存储在用户主目录，确保权限正确
- 敏感信息不应记录到历史中
- 定期清理过期会话数据
兼容性
- 确保跨平台路径处理正确
- 注意文件编码问题（统一使用 UTF-8）
- 保持与 LangChain4j 格式的兼容性
错误处理
- 文件系统操作都应有异常捕获
- 提供友好的错误提示
- 记录详细的错误日志

版本信息

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

8.1 KiB Raw Permalink Blame History Unescape Escape