plugin-core-builtin-migration

name	plugin-core-builtin-migration
description	将 MindOS 渲染器插件从“可选插件”升级为“完全内置能力（core builtin）”的通用流程。 当用户要求“把某插件改成内置/核心”“插件不应可关闭”“插件主程序化”或需要将旧入口迁移到 新主流程并保留兼容迁移能力时触发。

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 + 可观测）

4. 验证视角
   • 最少通过：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 一致隐藏
• 新主流程页面补齐筛选、空状态、加载、已读等基本交互

Step 6) 文档与知识同步

至少同步：

• wiki/plugins/README.md
• wiki/60-stage-plugins.md
• 相关 spec / pitfalls / refs（若行为模型发生变化）

并记录迁移决策：

• 为什么从插件入口转主程序能力
• 旧入口如何兼容、何时清理

Step 7) 测试与回归

最低测试集合：

• core 层迁移测试（旧格式 -> 新格式）
• API 层筛选/查询测试（若有 changes/feed 类接口）
• UI 基础 smoke（插件列表非空、核心按钮可用）
• 分类测试（appBuiltinFeature 能否正确从插件表层隐藏）

推荐命令：

npm --prefix app run test -- __tests__/core/content-changes.test.ts __tests__/api/changes.test.ts

---

AgentDiff -> Built-in 的参考映射

这次迁移可作为样板：

• 旧：Agent-Diff.md + agent-diff renderer
• 新：.mindos/change-log.json + /api/changes + /changes 主页面 + 全局提醒
• 兼容：读取旧 block 自动导入；导入后删除 Agent-Diff.md
• 治理：删除 diff-viewer renderer 与文档旧入口，保留结构化审计链路

---

常见坑位清单

1. 只删插件没迁移旧数据 -> 用户历史丢失
2. 注册入口分散/仅服务端注册 -> 客户端插件面板出现 0/0
3. 文档未同步 -> 用户看到过时入口
4. core/builtin/appBuiltinFeature 语义混淆 -> 本应“应用内建”的能力仍出现在插件面板
5. 迁移不幂等 -> 每次读取重复导入同一批旧数据

---

交付 Checklist（可复制）

• manifest 层完成 builtin/core 定义
• 如需“非插件化”，manifest 增加 appBuiltinFeature: true
• 全局注册单点化（客户端根入口统一引入）
• 旧入口迁移逻辑已实现且幂等
• 迁移后旧文件可清理
• 提供一次性迁移脚本
• 插件页/设置页状态正确（含 appBuiltinFeature 隐藏策略）
• 文档已同步更新
• 测试通过