#codebuddy-history-migrate-cli

历史记录迁移命令行工具 - 用于在不同品牌/用户/工作空间之间迁移历史记录。

功能特性

• ✅ 支持不同品牌之间的历史记录迁移
• ✅ 支持不同用户之间的历史记录迁移
• ✅ 支持不同工作空间之间的历史记录迁移
• ✅ 融合模式迁移 - 在原有历史记录上增加，而不是完全覆盖
• ✅ 完整数据迁移 - 自动迁移 history、file-tree、plan-task 等所有相关数据
• ✅ 智能去重 - 已存在的会话自动跳过
• ✅ 可选择是否删除源历史记录
• ✅ 交互式命令行界面
• ✅ 快速命令行参数模式
• ✅ 查看历史记录信息

迁移的数据类型

工具会自动迁移以下所有类型的数据：

1. history - 会话历史记录和消息
2. file-tree - 文件树数据
3. plan-task - 计划任务数据
4. checkpoint - 检查点数据 (如果存在)

所有数据都会根据会话 ID 进行关联迁移，确保数据完整性。

安装

全局安装

npm install -gcodebuddy-history-migrate-cli

本地开发

cd packages/history-migrate-cli
yarn install
yarn build

使用方法

1. 交互式迁移 (推荐)

最简单的方式,逐步引导输入所需信息:

history-migrate migrate

交互式界面会依次询问:

1. 源历史记录信息 (品牌名、用户ID、工作路径)
   • 品牌名默认为 CodeBuddyExtension，可直接回车使用默认值
2. 目标历史记录信息 (品牌名、用户ID、工作路径)
   • 品牌名默认为 CodeBuddyExtension，可直接回车使用默认值
3. 迁移选项 (是否覆盖、是否删除源)

2. 快速命令模式

通过命令行参数直接指定所有信息:

history-migrate quick \
  --source-user user123 \
  --source-workspace /Users/john/project \
  --target-user user456 \
  --target-workspace /Users/john/project

如果需要指定不同的品牌名:

history-migrate quick \
  --source-brand CodeBuddyExtension \
  --source-user user123 \
  --source-workspace /Users/john/project \
  --target-brand NewBrand \
  --target-user user456 \
  --target-workspace /Users/john/project \
  --overwrite \
  --delete-source

参数说明:

• --source-brand <brand>: (可选) 源品牌名，默认 CodeBuddyExtension
• --source-user <userId>: (必需) 源用户ID
• --source-workspace <workspace>: (必需) 源工作路径 (绝对路径)
• --target-brand <brand>: (可选) 目标品牌名，默认 CodeBuddyExtension
• --target-user <userId>: (必需) 目标用户ID
• --target-workspace <workspace>: (必需) 目标工作路径 (绝对路径)
• --overwrite: (可选) 覆盖目标历史记录,默认为合并模式
• --delete-source: (可选) 迁移后删除源历史记录

3. 查看历史记录信息

查看指定配置的历史记录详情:

history-migrate info \
  --user user123 \
  --workspace /Users/john/project

如果需要指定品牌名:

history-migrate info \
  --brand CodeBuddyExtension \
  --user user123 \
  --workspace /Users/john/project

参数说明:

• --brand <brand>: (可选) 品牌名，默认 CodeBuddyExtension
• --user <userId>: (必需) 用户ID
• --workspace <workspace>: (必需) 工作路径 (绝对路径)

输出信息包括:

• 历史记录存储路径
• 是否存在
• 会话数量
• 消息数量
• 占用空间

4. 查看帮助

# 查看所有命令
history-migrate --help

# 查看特定命令帮助
history-migrate migrate --help
history-migrate quick --help
history-migrate info --help

历史记录存储路径规则

工具会根据提供的配置自动计算历史记录的存储路径:

{缓存目录}/{品牌名}/{用户ID}/history/{工作路径MD5}/

不同操作系统的缓存目录

• macOS: ~/Library/Caches/
• Windows: ~/AppData/Local/
• Linux: ~/.local/share/

示例

对于配置:

• 品牌名: CodeBuddyExtension
• 用户ID: user123
• 工作路径: /Users/john/my-project

实际存储路径 (macOS):

~/Library/Caches/CodeBuddyExtension/user123/history/abc123def456/

其中 abc123def456 是工作路径的 MD5 哈希值。

使用场景

场景 1: 品牌升级迁移

从旧品牌迁移到新品牌:

history-migrate quick \
  --source-brand OldBrand \
  --source-user user123 \
  --source-workspace /Users/john/project \
  --target-brand NewBrand \
  --target-user user123 \
  --target-workspace /Users/john/project

场景 2: 用户账号切换

从一个用户账号迁移到另一个账号 (使用默认品牌名):

history-migrate quick \
  --source-user olduser \
  --source-workspace /Users/john/project \
  --target-user newuser \
  --target-workspace /Users/john/project

场景 3: 工作空间合并

将多个工作空间的历史记录合并到一个工作空间:

# 迁移第一个工作空间
history-migrate quick \
  --source-user user123 \
  --source-workspace /Users/john/project1 \
  --target-user user123 \
  --target-workspace /Users/john/main-project

# 迁移第二个工作空间 (合并模式,不覆盖)
history-migrate quick \
  --source-user user123 \
  --source-workspace /Users/john/project2 \
  --target-user user123 \
  --target-workspace /Users/john/main-project

场景 4: 测试环境迁移到生产环境

history-migrate quick \
  --source-brand TestBrand \
  --source-user testuser \
  --source-workspace /Users/john/test-project \
  --target-brand ProductionBrand \
  --target-user produser \
  --target-workspace /Users/john/production-project \
  --overwrite

迁移模式

融合模式 (默认，推荐)

重要： 工具采用融合模式迁移，即在原有历史记录上增加新数据，而不是完全覆盖。

特点：

• ✅ 保留目标现有的所有会话和数据
• ✅ 只添加源中不存在于目标的会话
• ✅ 按会话 ID 智能去重
• ✅ 自动跳过已存在的会话
• ✅ 按最后消息时间排序
• ✅ 迁移所有关联数据（history、file-tree、plan-task）

# 融合模式 (默认)
history-migrate quick \
  --source-user user123 \
  --source-workspace /path/to/workspace1 \
  --target-user user123 \
  --target-workspace /path/to/workspace2

示例场景：

假设目标已有 3 个会话（ID: A, B, C），源有 5 个会话（ID: B, C, D, E, F）：

• 会话 B 和 C 已存在，将被跳过
• 会话 D、E、F 将被复制到目标
• 最终目标有 6 个会话：A, B, C, D, E, F
• 每个会话的 file-tree 和 plan-task 也会相应迁移

⚠️ 注意事项

• --overwrite 参数已被移除，工具始终使用融合模式
• 如果需要完全替换目标数据，请先手动删除目标历史记录
• 已存在的会话不会被更新，只会跳过

安全性

• ✅ 默认不删除源历史记录,需要显式指定 --delete-source
• ✅ 合并模式默认不覆盖目标,需要显式指定 --overwrite
• ✅ 迁移前会显示源和目标信息,需要用户确认
• ✅ 支持查看历史记录信息,确认后再操作
• ✅ 完整的错误处理和详细日志

开发

构建

yarn build

测试

yarn test

监听模式

yarn watch

本地测试命令行工具

# 构建后,在项目根目录执行
node bin/history-migrate.js migrate

# 或者使用 npm link
npm link
history-migrate migrate

项目结构

history-migrate-cli/
├── bin/
│   └── history-migrate.js      # CLI 入口脚本
├── src/
│   ├── types.ts                # 类型定义
│   ├── utils.ts                # 工具函数
│   ├── utils.spec.ts           # 工具函数测试
│   ├── migrator.ts             # 迁移核心逻辑
│   ├── migrator.spec.ts        # 迁移逻辑测试
│   ├── cli.ts                  # 命令行界面
│   └── index.ts                # 导出入口
├── package.json
├── tsconfig.json
└── README.md

API 使用

除了命令行工具,也可以在代码中直接使用:

import { HistoryMigrator, MigrateConfig } from '@genie/history-migrate-cli';

const config: MigrateConfig = {
  source: {
    brand: 'OldBrand',
    userId: 'user123',
    workspace: '/path/to/workspace',
  },
  target: {
    brand: 'NewBrand',
    userId: 'user456',
    workspace: '/path/to/workspace',
  },
  overwrite: false,
  deleteSource: false,
};

const migrator = new HistoryMigrator(config);

// 验证配置
const validation = await migrator.validate();
if (!validation.valid) {
  console.error('配置错误:', validation.errors);
  return;
}

// 获取源信息
const sourceInfo = await migrator.getSourceInfo();
console.log('源会话数:', sourceInfo.conversationCount);

// 执行迁移
const result = await migrator.migrate();
if (result.success) {
  console.log('迁移成功!');
  console.log('已迁移会话:', result.conversationCount);
  console.log('已迁移消息:', result.messageCount);
} else {
  console.error('迁移失败:', result.error);
}

常见问题

Q: 迁移会影响正在运行的应用吗?

A: 建议在应用关闭时进行迁移,避免数据不一致。如果应用正在运行,建议先关闭应用,执行迁移,再重新启动。

Q: 迁移失败了怎么办?

A: 工具默认不删除源数据,迁移失败时源数据仍然完整。可以检查错误信息,修正问题后重新尝试。

Q: 如何查看历史记录的实际存储位置?

A: 使用 info 命令查看:

history-migrate info \
  --brand YourBrand \
  --user YourUserId \
  --workspace /your/workspace/path

Q: 可以迁移到相同的品牌/用户/工作空间吗?

A: 不可以。源和目标配置必须至少有一个不同(品牌、用户ID 或工作空间)。

Q: 迁移后原来的会话ID会改变吗?

A: 不会。会话ID和消息ID保持不变,只是存储位置改变了。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request!