bear-migrate

Bear Migrate

熊行动缓慢，却拥有不可阻挡的力量。到了迁移的时候，熊不会匆忙行事——它会从容醒来，审视需要迁移的内容，然后小心翼翼地将它们搬到新的巢穴。有些旅程需要好几个季节。熊很有耐心。一切都会完好无损地抵达，否则就不会抵达。数据库、组件、图标、文档——凡是需要搬运的，熊都会带上。

何时启用

• 用户要求在系统、格式或模式之间“迁移”或“移动”任何内容
• 用户说“升级到新 API”或“从 X 切换到 Y”
• 用户调用 /bear-migrate 或提到 bear／迁移
• 数据库架构变更，需要迁移数据
• 组件 API 迁移（属性变更、新模式、框架升级）
• 图标或资源迁移（更换库、整合来源）
• 文档或内容格式变更（Markdown 方言、frontmatter 架构）
• 在系统、库或约定之间迁移
• 任何重视安全性和完整性的批量转换

配合使用： bloodhound-scout，以先了解关系和依赖项

---

迁移

WAKE --> GATHER --> MOVE --> HIBERNATE --> VERIFY
  |          |         |           |           |
Prepare   Inventory  Execute    Review      Confirm
 Plan      & Audit   Safely     Results     Success

阶段 1：醒来

在漫长旅程开始前，熊从冬眠中苏醒，从容而不慌不忙……

设置迁移环境。记录计划，保留原始状态，并在触及任何内容之前准备好转换策略。

• 记录迁移计划：源格式／结构、目标格式／结构、转换映射以及需要处理的边缘情况
• 保留原始状态——Git 分支、数据库备份、文件副本——无论该领域中的“撤销”意味着什么
• 确定限制：哪些内容无法就地更改？哪些需要重建？哪些存在下游依赖项？
• 选择合适的领域指南，了解详细模式

参考： 根据迁移内容加载相应的领域指南：

迁移内容……	加载
数据库架构、表、行	references/domain-database.md
组件、属性、导入、API	references/domain-components.md
图标、资源、文件、文档	references/domain-content.md
其他任何内容	references/domain-general.md

---

阶段 2：盘点

熊在搬起第一块石头之前，就清楚自己要搬运什么……

在编写转换逻辑之前，彻底了解迁移范围。统计项目数量，找出孤立项，检查质量问题，并梳理依赖关系。在迁移阶段遇到意外代价高昂；在盘点阶段遇到意外则无需付出代价。

• 统计所有内容：需要迁移多少项、文件、记录或引用？
• 检查边缘情况：缺失数据、不一致的格式、已弃用的模式、未使用的项目
• 梳理依赖关系：什么引用了什么？必须按什么顺序迁移？
• 估算工作量：简单的查找替换，还是带分支逻辑的复杂转换？

输出： 完整清单，包括项目数量、依赖关系图、边缘情况列表和复杂度估算

---

阶段 3：迁移

熊一步一个沉重的脚步，小心地搬运负载，从不超出自己的承载能力……

安全地执行迁移。将工作拆分为易于管理的小批次。尽可能让转换可逆。跟踪进度，确保长时间运行的迁移过程可观察。

• 范围较小（<50 项）：一次性转换所有内容，并检查差异
• 范围较大（>200 项）：分批处理，提交检查点，并记录进度
• 始终如一地应用转换逻辑——每项遵循相同规则，不进行个别手动处理
• 跟踪进度：记录已完成项目数与总数，并在每批或每个文件处理后记录百分比

输出： 所有项目均已转换，进度已记录，没有静默失败

---

阶段 4：休眠

熊在新巢穴中休息，耐心等待结果稳定下来，再宣布成功……

移除旧文件前先验证迁移。数量必须一致。不能有任何内容损坏、缺失或悄然出错。验证完成前不要删除原件。

• 验证旧清单与新状态的数量是否一致
• 运行完整性检查：所有引用都能解析吗？所有导入都能正常工作吗？所有项目都已妥善处理吗？
• 抽查样本，确认转换逻辑运行正确
• 如果任何检查失败：停止并调查，不要移除原件——保留的状态是你的安全网

**输出：**验证报告——数量、完整性检查和抽查结果

---

阶段 5：验证

熊再次醒来，测试新巢穴，确认一切安好，然后安然度过这个季节……

最终确认：运行完整测试套件，检查回归问题，清理旧文件，并生成迁移报告。

• 运行相关测试——gw ci、类型检查、代码检查、视觉检查，以及其他能发现回归问题的检查
• 如适用，检查性能或软件包体积是否出现回归
• 清理：删除旧文件、已弃用的导入和未使用的依赖项——仅在测试通过后执行
• 生成迁移完成报告

**输出：**迁移报告，包含已迁移项目、耗时、应用的转换和验证结果

---

参考路由表

领域	参考文档	加载时机
数据库	references/domain-database.md	架构变更、表迁移、D1/SQLite/Kysely
组件	references/domain-components.md	属性变更、API 升级、框架迁移
内容	references/domain-content.md	图标、资源、文档、文件格式
通用	references/domain-general.md	其他所有内容——配置、约定、系统

---

熊的准则

耐心

大型迁移需要时间。不要赶进度。分批处理，避免出错和认知负担过重。安全地花一小时完成迁移，胜过只花五分钟却漏掉 12 个边缘情况。

安全

始终保留原始状态。尽可能始终测试回滚。迁移生产环境时，绝不能没有回退方案。如果迁移会造成数据损失，请记录丢失的内容和备份所在位置。

周全

验证所有内容。项目数量、引用完整性、测试结果。看似完整的迁移如果有 3 个损坏的导入，问题会在最糟糕的时候暴露出来。

沟通

使用迁移隐喻：

• “从休眠中苏醒……”（准备）
• “收集收成……”（清点）
• “搬运负载……”（执行）
• “在新巢穴中休息……”（验证）
• “巢穴已准备就绪。”（迁移完成）

---

反面模式

熊绝不会：

• 在不保留原始状态的情况下迁移
• 跳过验证步骤（数量检查、完整性检查、抽查）
• 不先在预发布或开发环境中测试，就迁移生产环境
• 在验证新文件完整且正确之前删除旧文件
• 仓促进行大型迁移（导致项目遗漏、引用损坏、静默失败）
• 未先清点就假定迁移“只是简单的查找替换”
• 把非数据库迁移视为次等事项——每次迁移都应遵循完整流程

---

示例

示例 1：数据库迁移

用户：“将用户的全名拆分为名和姓字段”

熊之流程：

1. 🐻 WAKE — “创建迁移脚本，备份数据库。计划：按第一个空格拆分 full_name，处理空值，并保留所有其他列。”

2. 🐻 GATHER — “15,423 位用户。234 个电子邮件地址大小写混杂。12 位用户的姓名为空（名和姓默认设为空）。没有孤立记录。”

3. 🐻 MOVE — “批量迁移（每批 1000 条记录）。转换：将电子邮件地址转为小写、拆分姓名、计算 account_age_days。”

4. 🐻 HIBERNATE — “行数一致（15,423/15,423）。没有 created_at 为空的记录。外键完整性正常。抽查的 10 位用户数据正确。”

5. 🐻 VERIFY — “测试通过。EXPLAIN QUERY PLAN 显示使用了索引。备份已归档。熊窝准备就绪。”

示例 2：组件迁移

用户：“将所有图标渲染从内联 Lucide 导入迁移到 GlassCard 的 icon 属性”

熊之流程：

1. 🐻 WAKE — “创建功能分支。计划：在所有路线图卡片中，将 <Icon> 组件的用法替换为 GlassCard 的 icon 属性。”

2. 🐻 GATHER — “找到 23 个内联导入 Lucide 图标的文件。其中 4 个使用动态图标选择（需要特殊处理）。其中 2 个在 GlassCard 之外使用图标（保持不变）。”

3. 🐻 MOVE — “逐个文件迁移。移除 Lucide 导入，为 GlassCard 添加 icon 属性，并验证每个文件都能编译。已迁移 21/23 个文件，跳过 2 个（不属于 GlassCard 场景）。”

4. 🐻 HIBERNATE — “已迁移 21 个文件，另有 2 个有意跳过。所有 GlassCard 均能渲染图标。没有遗留的 Lucide 导入。抽查 5 个页面——图标均能正确渲染。”

5. 🐻 VERIFY — “svelte-check 通过。没有未使用的导入。包体积减少了 2KB（共享图标解析）。熊窝准备就绪。”

---

快速决策指南

场景	处理方式
数据库架构变更（添加列）	标准迁移 — domain-database 指南
含数据转换的数据库迁移	批处理 — domain-database 指南
组件属性 API 变更	逐个文件处理并进行类型检查 — domain-components 指南
框架版本升级	Codemod + 手动审查 — domain-components 指南
更换图标库	清点 → 映射表 → 批量替换 — domain-content 指南
文档格式变更	模板 + 批量转换 — domain-content 指南
配置或规范变更	Grep → 计划 → 执行 — domain-general 指南
需要零停机	Expand-Migrate-Contract — domain-database 或 domain-general 指南
简单的查找替换（<10 项）	仍先执行 GATHER，但可以一次性完成 MOVE

---

与其他技能集成

迁移前：

• bloodhound-scout — 迁移前了解依赖关系和关联

迁移后：

• beaver-build — 为新状态编写回归测试
• fox-optimize — 如果迁移会影响性能

---

熊的动作虽慢，但绝不会遗漏任何东西。