企业官网建设流程全解析

• AI Agent
• 代码智能体
• 人工智能
• 大模型
• CLI

Kimi Code CLI 从 Python/uv 底层全面迁移至 Node.js 后，@moonshot-ai/migration-legacy包承担了将旧版 kimi-cli 数据（配置、MCP、技能与会话历史）无损导入新版的重任。本文基于 CHANGELOG.md 与官方迁移指南，结合 migration-legacy 源码 逐层拆解其检测、迁移、幂等与容错机制，帮助你理解kimi migrate背后发生了什么，以及在多主目录、损坏数据等边界场景下如何安全迁移。

迁移的背景：为什么要迁移

Kimi Code CLI 已完成一次重大底层升级：从 Python/uv 技术栈整体迁移到 Node.js，带来更简单的安装方式（无需配置 Python 环境）、更快的启动速度和全新的终端界面。旧版 kimi-cli 将逐渐停止维护，因此官方建议尽快升级，并将旧数据一并迁入新版。

迁移包的目标非常聚焦：把~/.kimi/下的 kimi-cli 数据迁移到~/.kimi-code/（见 package.json 的 description 字段）。旧数据与新版数据分属两个独立目录，迁移过程不会改动或删除~/.kimi/下的任何旧数据，kimi-cli 仍可照常使用，两者互不影响。

两种迁移方式

首次启动自动检测

装好 kimi-code 之后第一次运行kimi时，它会自动检测~/.kimi/下是否存在 kimi-cli 的数据。一旦检测到，就会弹出迁移提示，你可以选择：

• 立即迁移
• 稍后再说
• 不再提示（写入跳过标记，后续不再打扰）

手动运行迁移命令

你也可以随时手动运行迁移：

kimi migrate

执行后会弹出交互式范围选择，你可以选择是否同时迁移聊天会话：

• Config only：只迁移配置，不迁移历史会话；
• Config + N sessions：配置与全部本地会话一并迁移。

迁移结束后会显示结果摘要，你可以从摘要中直观看到各数据项的迁移数量与需要手动处理的告警。

迁移流程的完整编排

runMigration()是迁移的执行入口（run-migration.ts），它会按照MigrationScope决定的范围，依序执行 6 个独立步骤：

迁移开始与结束时都会记录 ISO 时间戳（startedAt/completedAt），并在每步完成后通过onProgress回调输出进度信息（config done、mcp done等）。

迁移报告与错误日志

每次迁移完成后，系统会：

1. 将完整报告序列化写入~/.kimi-code/migration-report.json（对应 types.ts 中的MigrationReport）；
2. 以追加方式把本次运行的会话失败明细写入migration-errors.log——这是一个跨多次运行的追加式记录，即使用户重试多次，也能用一份日志覆盖全部重试尝试，方便排查与分享。

迁移的检测机制

detectMigration()（detect.ts）在迁移前扫描源目录，产出MigrationPlan，它决定了迁移提示如何呈现、能迁移什么：

• 配置检测：读取源目录的config.toml（支持 TOML 与 JSON 两种旧格式），判断是否存在；
• MCP 检测：检查mcp.json是否存在，并额外扫描其中的mcpServers，识别使用auth === 'oauth'的服务器，列入"迁移后需重新授权"清单；
• OAuth 凭证检测：扫描~/.kimi/credentials/*.json，结合旧配置中 providers 的oauth引用，推导出迁移后需要重新执行/login的登录名列表；
• 技能与计划检测：检查~/.kimi/skills/与~/.kimi/plans/是否含条目；
• 插件检测：列出~/.kimi/plugins/下的插件名（kimi-cli 插件不在迁移范围内，仅作提示）；
• 会话检测：读取kimi.json中的work_dirs，通过 oldMd5BucketName 反向映射出每个 MD5 会话桶对应的真实工作目录，再对每个桶内的会话执行classifyLegacySession分类。

会话分类

每个旧会话都会被分类（sessions/classify.ts）：

• real：真实可迁移的会话，进入候选列表；
• placeholder/empty：占位或空会话，直接跳过并计数；
• malformed：上下文缺失或不可读的会话，不会被静默跳过，而是被记录为sessionScanFailures，在迁移结果中明确报告。

从源码结构看（detect.ts），<kaos>_<md5>形式的非本地 kaos 桶无法被本地 Kimi Code 运行时表示，会被跳过并计入bucketsSkippedNonlocalKaos；而其他任何无法映射的桶都被视为用户数据丢失风险，必须保持可见并报告，这正是 CHANGELOG 0.1.16 所强调的"报告损坏或无法映射的会话而非静默跳过"。

配置迁移的精细处理

配置迁移是最复杂的一步，涉及旧格式到新 schema 的逐字段转换（steps/config.ts）。

目标文件的三态处理

迁移器读取目标config.toml后决定采用哪种写入模式：

• overwrite（覆盖）：目标文件不存在或内容等于默认模板（通过 stub-detect.ts 的isTuiStubOrMissing判断）时，直接写入迁移结果；
• merge（合并）：目标已有用户配置且可解析时，采用增量合并——只补充目标缺少的键/provider/model，若同名条目双方值不同则保留目标值并记录冲突（configConflicts），目标值永远不会被覆盖（mergeConfig）；
• sibling（旁路文件）：目标文件存在但无法解析时，迁移结果写入config.migrated-from-kimi-cli.toml旁路文件，避免破坏用户现有配置，并在结果界面提示用户手动合并。

关键字段映射

配置迁移中有一批映射与过滤规则，其中 CHANGELOG 明确记录了两项修复：

default_yolo→default_permission_mode（0.1.4 修复）：旧版 kimi-cli 的default_yolo键曾被错误映射到已废弃的yolo字段，现已修正为映射到新版正确的default_permission_mode。当default_yolo = true时，迁移结果写入default_permission_mode = 'yolo'（config.ts）。

废弃 flag 不再带入（0.1.13 修复）：迁移时不再把过时的 legacyloop、background、plan、yolo等实验性 flag 带入迁移后的配置文件。源码中对应TOP_LEVEL_KEYS_TO_DROP = new Set(['plan_mode', 'yolo'])，且loop_control与background仅保留reserved_context_size、max_running_tasks、keep_alive_on_exit等有效字段（config.ts）；experimental块也只保留在新版 flag 注册表 中登记的布尔 flag。

Provider 与 Model 的类型迁移

• 旧 provider 类型映射：openai_legacy → openai、google_genai → google-genai、gemini → google-genai（LEGACY_PROVIDER_TYPE_MAP）；
• Schema 校验：每个 provider 必须通过新版 ProviderConfigSchema 校验，且type必须属于支持集合（anthropic、openai、kimi、google-genai、openai_responses、vertexai）；每个 model 须通过ModelRecordSchema，否则计入droppedProviders/droppedModels；
• 引用完整性：model 的 provider 若被丢弃、或与目标 config 中同名 provider 冲突，该 model 也会被丢弃——避免迁移后 model 静默跑在错误端点/凭证上；
• reasoning_key 下推：provider 上的reasoning_key会被删除并注入到引用该 provider 且未显式设置reasoning_key的 model 上；
• default_model 校验：default_model若指向迁移后不存在的 model（被丢弃、陈旧或从未存在），则一并丢弃，防止下次创建会话时因悬空别名而失败。

tui.toml 拆分与 hooks 处理

• 旧配置中的theme与default_editor属于 TUI 配置，会被拆分写入tui.toml（theme仅接受dark/light/auto枚举，其余值丢弃以防整文件校验失败）；若目标tui.toml已被用户修改，则写入tui.migrated-from-kimi-cli.toml旁路文件；
• hooks 按新版 HookDefSchema 逐条校验，合法条目直接通过（新旧 hook 结构一致），非法条目计入droppedHooks；
• device_id（遥测身份标识）仅在目标目录没有自己的device_id时从旧目录复制，目标已启动过一次则保留其自身标识（copyDeviceId）。

会话迁移：幂等、自愈与故障报告

迁移顺序与进度

会话迁移按wire_mtime（合并状态中的wire_mtime，缺省时回退到wire.jsonl或 context 文件的 mtime）从新到旧排序，让用户最常看的最新会话先完成迁移；每处理一个会话都会通过onSessionProgress(done, total)回调更新进度（sessions/index.ts）。

幂等与自愈

迁移支持重复运行，已经迁移过的会话不会被重复导入。其实现机制是：

1. 单会话迁移器migrateOneSession检测目标会话目录是否已存在，返回migrated或already-migrated；
2. ensureSessionIndexEntry是幂等的——即使目标目录被删除后残留了过期的索引行，重新迁移同一会话也不会追加第二行（sessions/index.ts）；
3. 若上一次运行在写入会话目录后、追加索引前崩溃，重跑会通过幂等的索引补写实现自愈——会话恢复可被按 id 打开的能力（sessions/index.ts）。

多主目录支持与标记文件

CHANGELOG 0.1.16 的核心变更：保持 legacy 迁移在多个 Kimi home 之间幂等。迁移器通过migratedMarker标记文件（marker.ts）记录已完成迁移的目标路径：

• 首次成功迁移写入标记，包含version: 1、first_migrated_at、last_migrated_at、migrator_version、target_path与target_paths数组；
• 后续迁移同一源目录到不同目标目录（例如不同的KIMI_CODE_HOME）时，通过appendMarkerRun把新目标路径追加进target_paths，shouldSuppressMigration据此判断"这个源 + 这个目标"是否已完成迁移，避免对已迁移组合反复弹窗；
• 目标目录的路径比较在 Windows 上做了大小写归一化与绝对路径解析（sameTargetPath）；
• 标记写入是尽力而为的：数据与报告已落盘完整，标记写入失败不会导致迁移失败，也不会中断健康的重复迁移（run-migration.ts）。

故障报告而非静默跳过

0.1.16 的另一核心变更：对损坏或无法映射的会话报告而非静默跳过。会话汇总SessionsSummary（types.ts）提供了一组完整计数器与明细：

• sessionsFailed：迁移失败的会话及其原因（如桶不可读、会话上下文缺失、索引追加失败等）；
• sessionsConflicts：目标目录已存在同名会话导致的冲突列表；
• sessionsSkippedPlaceholder/sessionsSkippedEmpty：占位与空会话计数；
• bucketsSkippedNonlocalKaos/bucketsSkippedNoWorkdirFound：无法映射的桶计数。

重要：只要所选范围内还有未解决项——未迁移/不可检查的会话、目标冲突、或存在但无法解析的旧配置/MCP 文件——迁移器就不会写"完成"标记，从而保留后续重试机会（run-migration.ts）。失败的会话会写入migration-errors.log并在结果界面呈现，用户可以据此决定手动处理还是重跑。

不会被迁移的内容（重要边界）

迁移范围是经过刻意设计的，以下内容不会被迁移，迁移完成后需要在新版中手动处理：

技能迁移

0.1.2 引入的技能迁移会将用户技能从~/.kimi/skills/迁移到~/.kimi-code/skills/（首次启动迁移时执行），已存在的目标技能会被保留（即目标优先、不覆盖）。MigrationPlan.skillsSourceHome允许调用方自定义技能源目录，默认指向~/.kimi/skills/。

计划文件的说明

~/.kimi/plans/下的计划文件会被纯复制到目标plans目录（copied/skippedExisting计数），但复制结果不接入新版 plan mode，仅作为普通文件保留，供用户自行复用或删除——迁移完成界面会给出明确提示（run-migration.ts）。

迁移后会话标识

从 kimi-cli 导入的会话会带上[imported]标记，方便你与新建会话区分；每个导入会话还会通过ensureSessionIndexEntry写入会话索引，确保可按ses_<uuid>恢复打开。

版本演进一览

CHANGELOG 记录了该包从 0.1.2 到 0.1.16 的关键行为演进：

• 0.1.2：新增用户技能迁移（~/.kimi/skills/→~/.kimi-code/skills/，保留已存在目标技能）；
• 0.1.4：修复default_yolo映射目标，从废弃的yolo字段改为default_permission_mode；
• 0.1.13：迁移后的配置不再携带过时的 legacy loop、background、plan、yolo 与未知实验性 flag；
• 0.1.16：迁移在多个 Kimi home 之间保持幂等；损坏或无法映射的会话被明确报告而非静默跳过。

其余版本（0.1.3～0.1.15）均为依赖@moonshot-ai/agent-core的同步更新，不涉及迁移逻辑本身的变更。

相关测试与验证

仓库为迁移逻辑提供了完整的测试覆盖（test/），包括：

• integration.test.ts：端到端迁移集成测试；
• resume.integration.test.ts：重复迁移/恢复场景（幂等性验证）；
• golden.test.ts：金样本对比测试；
• detect.test.ts、marker.test.ts：检测与标记文件行为验证；
• kimi-cli-schema.test.ts：旧kimi.jsonschema 解析验证；
• paths.test.ts：源/目标路径解析验证；
• sessions/ 目录下针对会话分类、转换与迁移的专项测试。

如需深入理解迁移实现细节，可从 migration-legacy 源码入口 开始，依次阅读 detect.ts、run-migration.ts、steps/config.ts 与 sessions/index.ts。官方迁移指南参见 docs/zh/guides/migration.md 与 docs/en/guides/migration.md。

• AI Agent
• 代码智能体
• 人工智能
• 大模型
• CLI