plugin-core-builtin-migration

Plugin Core Built-in Migration

把单个插件改造成“稳定、默认、不可缺席”的产品能力，并沉淀可复用迁移步骤。

适用场景：

• 某插件已经成为核心体验（例如 TODO、CSV、配置、变更中心）
• 旧插件入口要退役，但历史数据要可迁移
• 需要避免“某页面漏 import 导致插件空列表”这类注册漂移

---

目标定义（先对齐）

在本项目中，“完全内置”建议同时满足：

1. 注册稳定：渲染器注册有且仅有一个客户端根入口（推荐 SidebarLayout / ShellLayout）
2. 默认可用：manifest.builtin = true
3. 不可禁用（如需真正 core）：manifest.core = true（registry 会强制启用）
4. 可观测可维护：插件页、设置页、文档、测试一致
5. 历史兼容：旧入口数据有迁移方案，不丢内容
6. 表层语义清晰：区分“插件（可管理）”和“应用内建能力（不在插件面板展示）”

---

质量闸门（必走）

每次执行本 Skill 时，默认同时应用以下质量视角（按顺序）：

1. 产品设计视角（product-designer）

   • 检查信息层级、任务路径、主次操作、反馈时机
   • 明确“主路径 3 步内可完成”，避免迁移后流程变长

2. UI/UX 视角（ui-design-patterns）

   • 检查按钮层级、交互一致性、空状态/错误状态/加载状态
   • 禁止无意义下划线链接滥用；主 CTA 与次级 CTA 视觉层级明确
   • 深色模式可读性必须通过（按钮文字对比、tag 对比、focus 可见）

3. 实现质量视角

• 迁移逻辑幂等（重复执行不重复导入）
• 注册机制单点化（禁止多处散落 import 造成漂移）
• 避免仅服务端注册导致客户端 0/0 空列表
  • 兼容代码失败不阻断主流程（best-effort + 可观测）

1. 验证视角
   • 最少通过：core/API 回归测试 + lint
   • UI 变更至少进行一次人工检查（亮色/暗色）

若任一步不满足，迁移不得判定完成。

---

执行流程（通用）

Step 1) 盘点现状与边界

先确认插件的四类事实来源：

• 代码入口：packages/web/components/renderers/<plugin>/manifest.ts
• 注册入口：packages/web/lib/renderers/index.ts（自动生成）
• 使用入口：resolveRenderer() 调用链（如 ViewPageClient）
• 展示入口：插件面板/设置页（优先使用 getPluginRenderers()）

并回答：

• 该插件是否应 core（不可关闭）？
• 是否存在旧文件协议/旧入口（如 Agent-Diff.md）需要迁移？

Step 2) 升级插件声明

在 manifest 中设置：

• builtin: true（内置）
• core: true（若要完全内置且不可关闭）
• appBuiltinFeature: true（若是“应用内建能力”且不应出现在插件管理面板）
• match 保持明确，避免误匹配

如果插件要被替换/下线：

• 删除旧 renderer 文件
• 重新生成 packages/web/lib/renderers/index.ts

Step 3) 统一注册机制（防漂移）

必须收敛为单点初始化（客户端）：

• 在客户端根组件（推荐 SidebarLayout）引入 @/lib/renderers/index
• 移除其他页面/组件分散 import（避免重复与遗漏并存）

验收标准：

• 任意路由进入插件页，插件列表不应出现 0/0 的假空状态
• 在“应用内建能力”模式下，被标记能力应从插件面板消失但渲染仍正常

Step 4) 历史兼容迁移（关键）

如果旧插件依赖旧文件格式：

1. 在核心数据层实现“懒迁移”：
   • 首次读取时自动导入旧格式
   • 写入新格式（结构化 JSON）
2. 迁移后清理旧入口文件（防止双写和重复导入）
3. 提供一次性脚本（离线/手动修复）：
   • scripts/migrate-*.js

Step 5) UI/UX 对齐

• 插件页：状态、可开关策略与 core 语义一致
• 设置页：显示 builtin/core 标签逻辑一致
• 若设为 appBuiltinFeature：在插件页/设置页/首页 Extensions 一致隐藏
• 新主流程页面补齐筛选、空状态、加载、已读等基本交互