#codebuddy-history-migrate-cli

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

功能特性

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

迁移的数据类型

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

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

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

安装

$3

``bash
npm install -gcodebuddy-history-migrate-cli
`

$3

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

使用方法

$3

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

`bash
history-migrate migrate
`

交互式界面会依次询问:
1. 源历史记录信息 (品牌名、用户ID、工作路径)
- 品牌名默认为 CodeBuddyExtension，可直接回车使用默认值
2. 目标历史记录信息 (品牌名、用户ID、工作路径)
- 品牌名默认为 CodeBuddyExtension，可直接回车使用默认值
3. 迁移选项 (是否覆盖、是否删除源)

$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: (可选) 迁移后删除源历史记录

$3

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

`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 : (必需) 工作路径 (绝对路径)

输出信息包括:
- 历史记录存储路径
- 是否存在
- 会话数量
- 消息数量
- 占用空间

$3

`bash


查看所有命令

history-migrate --help

查看特定命令帮助

history-migrate migrate --help
history-migrate quick --help
history-migrate info --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
``

$3

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

$3

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

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request!