CLI tool for migrating history records between different brands/users/workspaces
npm install codebuddy-history-migrate-cli#codebuddy-history-migrate-cli
历史记录迁移命令行工具 - 用于在不同品牌/用户/工作空间之间迁移历史记录。
- ✅ 支持不同品牌之间的历史记录迁移
- ✅ 支持不同用户之间的历史记录迁移
- ✅ 支持不同工作空间之间的历史记录迁移
- ✅ 融合模式迁移 - 在原有历史记录上增加,而不是完全覆盖
- ✅ 完整数据迁移 - 自动迁移 history、file-tree、plan-task 等所有相关数据
- ✅ 智能去重 - 已存在的会话自动跳过
- ✅ 可选择是否删除源历史记录
- ✅ 交互式命令行界面
- ✅ 快速命令行参数模式
- ✅ 查看历史记录信息
工具会自动迁移以下所有类型的数据:
1. history - 会话历史记录和消息
2. file-tree - 文件树数据
3. plan-task - 计划任务数据
4. checkpoint - 检查点数据 (如果存在)
所有数据都会根据会话 ID 进行关联迁移,确保数据完整性。
``bash`
npm install -gcodebuddy-history-migrate-cli
`bash`
cd packages/history-migrate-cli
yarn install
yarn build
最简单的方式,逐步引导输入所需信息:
`bash`
history-migrate migrate
交互式界面会依次询问:
1. 源历史记录信息 (品牌名、用户ID、工作路径)
- 品牌名默认为 CodeBuddyExtension,可直接回车使用默认值CodeBuddyExtension
2. 目标历史记录信息 (品牌名、用户ID、工作路径)
- 品牌名默认为 ,可直接回车使用默认值
3. 迁移选项 (是否覆盖、是否删除源)
通过命令行参数直接指定所有信息:
`bash`
history-migrate quick \
--source-user user123 \
--source-workspace /Users/john/project \
--target-user user456 \
--target-workspace /Users/john/project
如果需要指定不同的品牌名:
`bash`
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 : (可选) 源品牌名,默认 CodeBuddyExtension--source-user
- : (必需) 源用户ID--source-workspace
- : (必需) 源工作路径 (绝对路径)--target-brand
- : (可选) 目标品牌名,默认 CodeBuddyExtension--target-user
- : (必需) 目标用户ID--target-workspace
- : (必需) 目标工作路径 (绝对路径)--overwrite
- : (可选) 覆盖目标历史记录,默认为合并模式--delete-source
- : (可选) 迁移后删除源历史记录
查看指定配置的历史记录详情:
`bash`
history-migrate info \
--user user123 \
--workspace /Users/john/project
如果需要指定品牌名:
`bash`
history-migrate info \
--brand CodeBuddyExtension \
--user user123 \
--workspace /Users/john/project
参数说明:
- --brand : (可选) 品牌名,默认 CodeBuddyExtension--user
- : (必需) 用户ID--workspace
- : (必需) 工作路径 (绝对路径)
输出信息包括:
- 历史记录存储路径
- 是否存在
- 会话数量
- 消息数量
- 占用空间
`bash查看所有命令
history-migrate --help
历史记录存储路径规则
工具会根据提供的配置自动计算历史记录的存储路径:
`
{缓存目录}/{品牌名}/{用户ID}/history/{工作路径MD5}/
`$3
- macOS:
~/Library/Caches/
- Windows: ~/AppData/Local/
- Linux: ~/.local/share/$3
对于配置:
- 品牌名:
CodeBuddyExtension
- 用户ID: user123
- 工作路径: /Users/john/my-project实际存储路径 (macOS):
`
~/Library/Caches/CodeBuddyExtension/user123/history/abc123def456/
`其中
abc123def456 是工作路径的 MD5 哈希值。使用场景
$3
从旧品牌迁移到新品牌:
`bash
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
`$3
从一个用户账号迁移到另一个账号 (使用默认品牌名):
`bash
history-migrate quick \
--source-user olduser \
--source-workspace /Users/john/project \
--target-user newuser \
--target-workspace /Users/john/project
`$3
将多个工作空间的历史记录合并到一个工作空间:
`bash
迁移第一个工作空间
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
`$3
`bash
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
`迁移模式
$3
重要: 工具采用融合模式迁移,即在原有历史记录上增加新数据,而不是完全覆盖。
特点:
- ✅ 保留目标现有的所有会话和数据
- ✅ 只添加源中不存在于目标的会话
- ✅ 按会话 ID 智能去重
- ✅ 自动跳过已存在的会话
- ✅ 按最后消息时间排序
- ✅ 迁移所有关联数据(history、file-tree、plan-task)
`bash
融合模式 (默认)
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 也会相应迁移
$3
-
--overwrite 参数已被移除,工具始终使用融合模式
- 如果需要完全替换目标数据,请先手动删除目标历史记录
- 已存在的会话不会被更新,只会跳过安全性
- ✅ 默认不删除源历史记录,需要显式指定
--delete-source
- ✅ 合并模式默认不覆盖目标,需要显式指定 --overwrite
- ✅ 迁移前会显示源和目标信息,需要用户确认
- ✅ 支持查看历史记录信息,确认后再操作
- ✅ 完整的错误处理和详细日志开发
$3
`bash
yarn build
`$3
`bash
yarn test
`$3
`bash
yarn watch
`$3
`bash
构建后,在项目根目录执行
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 使用
除了命令行工具,也可以在代码中直接使用:
`typescript
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);
}
`常见问题
$3
A: 建议在应用关闭时进行迁移,避免数据不一致。如果应用正在运行,建议先关闭应用,执行迁移,再重新启动。
$3
A: 工具默认不删除源数据,迁移失败时源数据仍然完整。可以检查错误信息,修正问题后重新尝试。
$3
A: 使用
info 命令查看:`bash
history-migrate info \
--brand YourBrand \
--user YourUserId \
--workspace /your/workspace/path
``A: 不可以。源和目标配置必须至少有一个不同(品牌、用户ID 或工作空间)。
A: 不会。会话ID和消息ID保持不变,只是存储位置改变了。
MIT
欢迎提交 Issue 和 Pull Request!