القائمة
NaiveTab 浏览器扩展的配置迁移开发指南。当用户要修改持久化配置结构（新增/重命名/删除字段、修改类型）时使用。强制走 handleAppUpdate 迁移流程，防止破坏老用户数据。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | config-migration |
| description | NaiveTab 浏览器扩展的配置迁移开发指南。当用户要修改持久化配置结构（新增/重命名/删除字段、修改类型）时使用。强制走 handleAppUpdate 迁移流程，防止破坏老用户数据。 |
任何持久化配置结构修改都不能破坏老用户数据。本技能确保迁移流程正确执行。
在 src/logic/config/state.ts 的 defaultConfig 或 defaultState 中添加/修改字段。
修改 package.json 的 version 字段（由用户手动操作）。
在 src/logic/config/update.ts 的 handleAppUpdate 函数中添加迁移分支：
// 使用 if 而非 if-else，确保跨版本用户依次执行所有迁移
if (compareLeftVersionLessThanRightVersions('2.6.0', localVersion)) {
// 迁移逻辑
localConfig.value.newField = 'defaultValue'
// 或使用 mergeState 合并
mergeState(defaultConfig, localConfig.value)
}
| 场景 | 正确做法 | 错误做法 |
|---|---|---|
| 新增扁平字段 | 在 handleAppUpdate 中赋值 | 只改 defaultConfig |
| 新增嵌套对象 | 整体赋值 defaultConfig.xxx | 只依赖浅合并 |
| 重命名字段 | 新字段=旧字段值 → delete 旧字段 | 直接改字段名 |
| 删除字段 | 先 delete 旧值 → 再删 defaultConfig | 直接从 defaultConfig 删 |
| 修改类型 | 新增替代字段 + 迁移 | 直接改类型 |
handleAppUpdate 使用 if 而非 if-else，确保跨越多个版本的旧用户能依次执行所有迁移mergeState 以默认配置为模板过滤废弃字段；keymap 和数组直接替换不深合并src/background/config/cache.tsNaiveTab 浏览器扩展的 Widget 开发指南。当用户要在 newtab-naivetab 项目中新增 Widget 组件、添加新功能组件时使用。涵盖需要修改的完整文件清单、配置规范、类型注册等，防止遗漏关键步骤。
NaiveTab 浏览器扩展的 i18n 国际化开发指南。当用户要新增/修改翻译文本、添加多语言 key 时使用。涵盖中英文同步更新规则、变量替换模式等，防止遗漏或格式错误。
NaiveTab 浏览器扩展的 Setting 面板开发指南。当用户要新增 Setting 设置面板、添加新的设置页时使用。涵盖需要修改的完整文件清单、注册规范等，防止遗漏关键步骤。
NaiveTab 浏览器扩展的全局命令快捷键开发指南。当用户要新增/修改命令快捷键（如新增 tab 操作、页面滚动、窗口操作等命令）时使用。涵盖需要修改的完整文件清单、执行环境分类、类型注册等，防止遗漏关键步骤。