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 + 可观测） 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` 能否正确从插件表层隐藏） 推荐命令： ```bash 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 隐藏策略） - [ ] 文档已同步更新 - [ ] 测试通过