评估：官方 0809 覆盖度 vs plugin-registry

August 10, 2026 · View on GitHub

状态：已决策（2026-08-10 拍板转向「薄控制台」）。本文为转向前的覆盖度评估记录。目的：以官方 0809 快照（snapshot-20260809T140917Z-a6bb5a95ba）的插件机制为基准，逐能力评估 plugin-registry 是否还有存在必要，作为路线转向/归档的依据。本文只讨论 plugin-registry 与官方的关系；dsh-mygo 等第三方方案不在范围内。

背景：官方 0809 引入了仓库插件格式

官方 0809 新增 repository-plugin（仓库插件） 格式与安装通道，是官方对「插件打包/安装/分发」的正式回答：

  • 打包：.dsh-plugin/ 目录 + package.json#dsh.skills/mcpServers/entry + scripts.prepack（必须调用 dsh-plugin-prepare）→ prepack 生成固定 dsh-plugin.mjs wrapper + dsh-plugin-assets/。dsh.entry 是完整 Cordis 插件（官方明确保留 name/inject/Config/注册/启动失败/effect 清理的完整语义）
  • 安装：$DSH_HOME/cordis.patch.yml（home 级用户 patch 层）的 repository-plugins 行 repositories 列表，github:owner/repo#<ref> 精确 ref 锁定，可 &path: 选子目录
  • 分发：GitHub 仓库即插件（克隆 + pnpm 准备 + prepack），无发布流程
  • 生命周期：RepositoryCache（bundled pnpm 原子准备，不可变 generation）+ loadPreparedRepository 挂载 + 事务性换代（HMR watcher 盯 patch 文件，失败保留旧代）
  • 官方明确拒绝：install 命令、注册表/安装数据库、市场/发现索引（config-only-repository-plugins 的 Alternatives 原文：Add a dsh plugin install command and installation database. Rejected）

官方 0809 的 dsh plugin 命令仍是 profile/bundle 组合管理（pnpm forwarder + dsh.profile.bundles 层栈），与仓库插件通道并存：通道 1（$DSH_HOME/cordis.patch.yml）服务「独立用户装仓库插件」，通道 2（bundle）服务「组合里的产品服务」。

用户配置层：cordis.patch.yml → cordis.patch.yml（官方演进）

官方 0805 的 profile-plugin-bundles 架构决策弃用 $DSH_HOME/cordis.patch.yml（原文：$DSH_HOME/cordis.patch.yml is simply no longer read），个人 overlay 机制从 loadPersonalPatches + cordis.patch.yml 改为 loadOptionalPatches + watchUserPatches 读取 cordis.patch.yml 两层：

层文件属主用途
bundle 层packages/bundle/*/cordis.patch.yml产品开发者（bundle 包内）定义组合行
profile 层$DSH_HOME/profiles/<name>/cordis.patch.yml用户（每 profile）覆盖该 profile
home 层$DSH_HOME/cordis.patch.yml用户（机器级）跨 profile 个人偏好——repository 插件装这里（homePatchPath()）

同名 cordis.patch.yml 出现在三个层，属主不同；薄控制台的读/写目标是 home 层（机器级用户配置），不是 profile 层（只覆盖单 profile），更不是 bundle 包内层（产品层，不该动）。07-30 的 config-only 决策笔记仍写 cordis.patch.yml 是过时表述，以 08-05 的 profile-plugin-bundles 为准。

覆盖度评估（逐能力）

plugin-registry 能力官方 0809 对应覆盖？
打包格式（dsh.plugin.json）.dsh-plugin 格式（含 skill/mcp/code）✅ 官方已定标准，registry 自造格式冗余
安装（dsh registry install <dir/tarball>）cordis.patch.yml 声明式 + pnpm 准备✅ 官方可替代（且官方更干净）
分发（tarball/目录 + deps-link）GitHub ref + pnpm 依赖解析✅ 官方可替代
启停/装卸（CLI + 面板）cordis.patch.yml 增删 repositories 行✅ 语义等价（官方无「保留安装但停用」中间态，但增删行覆盖用例）
HMR 热更新（浏览器 UI 启停不刷新）官方事务性换代 + HMR watcher✅ 官方更强（事务性失败回滚）
管理控制台（设置页「插件」面板）官方无（config 文件无 UI）❌ 官方空白——registry 剩余价值之一
UI 插件（client half）动态进出浏览器见下「实证」⚠️ 已被推翻——UI 不依赖 client half

实证：UI 插件不需要 client half 机制

早期假设「官方 repository-plugin 不支持 client half，所以带 UI 的插件 registry 才有价值」——实测推翻：

  • 带 UI 的 .dsh-plugin 包用 dsh.entry 注入 httpServer 注册路由，浏览器 fetch 渲染——完整官方链路，无任何 client-half 机制
  • 实测（纯净 0809 worktree，/tmp/dsh-0809-pure）：tsdown 编译 entry → dsh-plugin-prepare 生成 wrapper → RepositoryCache 安装 → loadPreparedRepository 挂载 → entry 激活（fiber ACTIVE）→ 注册 /api/ui-verify 路由 → 真实 HTTP GET 返回 200 {"ok":true,"source":"repository-plugin-entry","ui":"<div data-ui-verify>..."}
  • 结论：支持浏览器 UI ≠ 需要 client half。UI 插件可经官方 entry 自渲染（路径：httpServer 路由 + 浏览器 fetch/iframe/DOM），或经官方 dsh.client 包 + Loader 树静态加载。registry 的 registerExternal（client half 动态登记）只对「坚持官方 dsh.client 格式 + 想运行时动态进出官方 __DSH_BOOT__」的窄场景有价值——官方静态通道可替代

剩余价值评估

能力官方 0809plugin-registry剩余价值
Node 插件（工具/skill/MCP）✅ .dsh-plugin自造格式无（让给官方）
带 UI 插件✅ entry 自渲染（实证）client half无（让给官方）
启停/装卸✅ cordis.patch.ymlCLI/面板无（让给官方）
HMR✅ 事务性换代浏览器 diff无（让给官方）
管理控制台❌ 官方空白设置页面板窄（官方无 UI）
动态 client half 补充⚠️ 官方静态可替代registerExternal可选（非必需）

结论：plugin-registry 作为「独立插件机制」的 ~95% 能力被官方 0809 覆盖，剩余价值收敛为「管理 .dsh-plugin 包的控制台」+「可选动态 client half 补充缝」——不支撑一个完整独立机制。

转向/归档建议

  1. 打包/安装/分发：全面靠拢官方 .dsh-plugin + cordis.patch.yml，registry 不再自造格式与命令
  2. 管理面：保留一个「浏览/启停已装 .dsh-plugin 包」的控制台（且其自身应为官方 dsh.client 格式的普通插件）
  3. client half：registerExternal 降级为可选补充缝（官方静态通道可替代，不优先投入）
  4. patch 瘦身：既有 49→26 瘦身自然收尾，不再投入新机制
  5. 归档候选：若控制台价值不成立（官方后续补 UI），整个仓库转为归档状态

决策（2026-08-10 拍板，转向「薄控制台」）

  • ✅ 控制台保留，形态 = 写 config 触发重载：薄控制台读官方 $DSH_HOME/cordis.patch.yml 的 repository-plugins.repositories，写操作直接编辑该列表 → 官方 HMR watcher 事务性换代生效。控制台需要写文件能力（经官方 entry 注入 httpServer 的自建路由，或官方配置写入面）
  • ✅ registerExternal 完全移除：依赖官方静态 dsh.client 通道，不保留可选缝
  • ✅ patch 倾向删除：转向后不再维护 0808/0809 patch，机制件冻结或删除

转向「薄控制台」——spike 验证（2026-08-10）

纯净 0809 快照实测（/tmp/dsh-0809-spike）：

验证点结果
entry 经 httpServer 自渲染 UI✅ 真实 HTTP 200 返回 UI 数据（/tmp/dsh-0809-pure 实证）
写 $DSH_HOME/cordis.patch.yml → 官方消费 repository 行✅ 启动加载 → 官方 repository-plugin git 准备插件（web4/web6 实证）
运行中写 config → 即时 HMR 换代❌ 0809 web 默认 hmr disabled（web-app bundle 显式 hmr: disabled: true，官方 TODO「Re-enable shared HMR for Web after its reload lifecycle is tested」）——watcher 未注册
0 patch 可行性✅ 全部官方机制（config 文件 + repository-plugin + dsh.client 面板）

关键发现（影响形态）：

  • 写入目标 = $DSH_HOME/cordis.patch.yml（home 级用户 patch 层，homePatchPath()）——07-30 决策笔记所称 cordis.patch.yml 已被 08-05 的 profile-plugin-bundles 取代，官方实现只读 cordis.patch.yml（web4/web6 实证）
  • web 默认无运行中换代：薄控制台写 config 后需提示重启（或触发整站 reload）；官方若启用 web hmr（TODO），运行中换代自动成立——控制台设计应兼容两种

转向规划（4 阶段）

阶段内容验证标准
1 冻结patch 瘦身收尾；CLI/ctx.plugins/registerExternal 标 deprecated，不再投入CHANGELOG 标注
2 spike薄控制台最小原型（读/写 cordis.patch.yml + dsh.client 面板）0 patch；能列出/启停 .dsh-plugin 包
3 转型新建薄控制台包替代 ui-plugin-manager；移除机制分发包与 patch旧机制可整体移除不影响控制台
4 发布控制台独立发版；旧 v0.1.0 标 legacy发布流程验证

阶段 2 spike 结果（2026-08-10，原型已实证）

纯净 0809 + 独立控制台 bundle（/tmp/dsh-console，Node half 读写 $DSH_HOME/cordis.patch.yml）：

验证点结果
控制台 bundle 挂载（dsh plugin --profile web add）✅ 0 patch 进 profile（base + web-app + plugin-console）
Node half 读路由（GET /api/plugin-console/repositories）✅ 返回当前 repositories 列表
Node half 写路由（POST → 写 cordis.patch.yml）✅ config 正确写入（修复字符串引号序列化 bug）
读写闭环✅ 写后读回一致
写完 → 官方消费✅ 重启后官方 repository-plugin git 拉取 + 准备插件（web5 实证：Failed to prepare ... Path "/.dsh-plugin" is not a directory——失败因 test-vlln 无 .dsh-plugin，机制本身完整工作）
0 patch✅ 全官方机制（bundle + httpServer 路由 + cordis.patch.yml + repository-plugin）

结论：薄控制台「写 config 触发官方换代」0 patch 可行——阶段 2 核心不确定性消除。client half（面板 UI）因需官方 clientBundle preset 构建暂缓，Node half 读写已独立验证；阶段 3 补 client 面板 + 完整 UI。

相关

  • 官方机制：.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md（config 安装）、2026-08-08-trusted-repository-package-code.md（dsh.entry 可信代码）、2026-07-30-static-repository-plugin-format.md（打包格式）
  • 实测：/tmp/dsh-0809-pure/verify-ui-repo-plugin.ts（UI 自渲染实证）
  • 本仓库：patch 瘦身设计（转向前的机制收敛）