有没有人搞过升级 dsh 插件代码来支持新 dsh 版本的 skill？

[tianyicui]

我们考虑官方搞一个面向插件作者的（不是面向插件用户的），如何把自己插件 repo 里的代码，从 0.1.1 升级到 0.1.2 的 skill。

有没有人搞过，我们可以借鉴一下？会致谢的。

[zhu1090093659]

我们把 dsh-web 的约 20 个社区插件（@linxin666/dsh-*）从 0.1.1-rc.2 升到 0.1.2-alpha.1，又升到 0.1.2-alpha.2。大部分问题 typecheck 和测试都是绿的，跑起来才暴露。整理在这里，供写升级 skill 时参考。

0.1.2-alpha.1：cohort 还没发 npm

alpha.1 是有意不发 npm 的 preview，registry 的 latest/next 仍停在 0.1.1-rc.2，任何 0.1.2-alpha.1 包名都是 404。后面一半的坑由这一点派生。

1. 目标 cohort 装不了，只能自己构建。从官方 tag deepseek-harness@dsh-v0.1.2-alpha.1 构建一次，pnpm pack 出全部 tarball 放进 ~/.dsh-cohorts/0.1.2-alpha.1/，在 pnpm-workspace.yaml 用 overrides: 把 @deepseek-ai/dsh-* 钉到 file: tarball；manifest range 照写 ^0.1.2-alpha.1，正式发布后删掉 overrides 就回到 registry 解析。pnpm 版本很关键：11.9.0 解析 file: tarball 的传递 peer 会绕过 overrides 去 registry 找不存在的版本，钉到 packageManager: pnpm@11.24.0 才正常。

2. 两个 SDK 包被删：@deepseek-ai/dsh-host-apiproxy 和 @deepseek-ai/dsh-client-runtime，所有 import 都要迁。客户端侧：ClientContext 改成 cordis Context 的本地别名；settings scope 家族改从 dsh-client-ui-settings/client；快照 store 引擎改从 dsh-client-store；sessions、workspaces 改从 dsh-api-session-controller/client、dsh-api-workspace-controller；ctx.slots 合并点挪到 dsh-client-ui-renderer/client。host 侧执行改成注入的 TypertGateway + workspaceRegistry，business 调用 dispatch 成 { namespace, method, args: { request } }。

3. dsh-client-store 进了浏览器的冻结 module table。要同步更新 shared/web-platform.ts、对应测试和 scripts/inject-contract.test.mjs 的钉点，删掉旧的 RUNTIME_STORE_EXEMPTION。共享构建预设会 externalize 它，于是每个客户端 bundle 在求值期硬 require 它，在没有这个表项的宿主上直接 missed the module table。

4. 跨 cohort 共存是最大的坑。rc.2 宿主升不到未发布的 alpha.1，插件必须两边都能跑，有两处硬耦合：

   • store 引擎的 require 未命中模块表。我们保持每包只出一份客户端产物，在共享的 shared/tsdown.client.ts 里出 shim：求值期先解析平台模块 dsh-client-store，回退到旧的 @deepseek-ai/dsh-client-runtime/client。只转共享的值表面，notifySubscribers 是 cohort 独有的，转了会在 build 时报 missing-export；类型导入不动，继续用发布出去的 0.1.2 声明。
   • 注入服务漂移。某个入口的硬 inject 清单加了 'remote.agentPresets'，但这个服务只在 0.1.2 宿主注册，rc.2 宿主上入口永远停在 pending (waiting for service: remote.agentPresets)。改成使用点探测：注册了就走，否则回退 connection.api.agentPresets。注意 cordis 的 remote 代理对没注入的属性是 throw 而不是 undefined，探测要 try/catch。

   试过并否掉的方案：per-consumer try/catch（重复九次污染源码）、按宿主 cohort 出不同产物（重新引入有状态构建）、硬等 inject wait（低版本宿主上永久 pending）。

5. gateway 描述符是逐方法的 wire 布局，assertExactArguments 严格校验，而测试替身往往和调用点共享同一个错误假设，门禁全绿、路径是断的。实例：session/list 的单参 wire 名是 _request（strict codec、无 acceptsUndefined），传 {request} 直接 arguments-invalid；directoryPicker/list 只有一个扁平可选 path；business 错误码在 error.failure.code，TypertRemoteFailure 没有 .code，读 error.code 全部退化成 internal；agentPresets/list、session/modelCatalog 用 {}。做法：两个网关消费包里加 invokeWireArgs()，按描述符布局组参；测试 fakes 编码同一张描述符表，key 多了少了测试就红。不要在 runtime 读 SDK 包内的描述符表，那是生成产物，会把插件启动耦合到 inject 契约刻意隐藏的内部。stream 类（如 session/follow）走 TypertGateway.stream()，unary 载体上的 invoke() 会拒绝。

6. 启动竞态。0.1.2 宿主上 sessionController 等 9 个注入服务全部 resolve 才激活，宿主 service 的 start() 却在插件启动时立刻发第一次 roster poll，首查 session/list 报 service-unavailable。下一轮 poll 就恢复，但每次 boot 都打一条 stack trace。对 service-unavailable 做有限重试（约 5 次、2 秒退避，可注入覆盖），不要延迟首 poll，也不要把 sessionController 加回 inject wait。

7. 第三方预构建插件吃不到你的 shim。@morlay/ui-conversation-message-actions@0.0.11 以预构建内容进 profile，硬 require 旧说明符，alpha.1 宿主上同样 missed the module table。用 pnpm patch 把那条 require 改写成同样的双 cohort 探测；scripts/link-profile.mjs 会把链接重指回未打补丁实例，要手动指到 patch_hash=… 实例。

8. CI：overrides 用 file: tarball 后，frozen lockfile 记录的是机器相关绝对路径，runner 上 frozen install 全缺 store。加 scripts/build-cohort-tarballs.mjs 在任意机器 materialize（249 个包，已存在则跳过），用 pnpm-workspace.yaml hash 做 key 的 actions cache 供 5 个 pnpm job 共用。pnpm/action-setup 的 version 输入会和 packageManager 钉点冲突，删掉它让 packageManager 做唯一来源。

9. 发布：cohort 未发布时，tag 触发的发布会产出 @deepseek-ai/* range 无法从 registry 解析的包，且不可逆。release workflow 加 NPM_PUBLISH_ENABLED 开关：tag 照常跑门禁、release notes 和 aggregate mount smoke，只跳过 npm publish。

10. dsh-aionui-panel 靠被删的 dsh-client-runtime 才能构建，随迁移退役。「SDK 删包导致插件构建不了」要在迁移前盘点，不要边迁边发现。

固化成 skill 的话，这部分的核心是：先确认目标 cohort 是否已发布；把 SDK 删包/删面清单当迁移矩阵的输入；客户端产物保持单一，靠运行时解析 cohort 表面；注入服务漂移要么探测要么拿掉，别硬等；网关调用按描述符布局组参，fakes 编码同一张表。

0.1.2-alpha.2：已发布，坑换了方向

alpha.2 发到了 npm（alpha dist-tag），alpha.1 那套 tarball 机制（overrides、构建脚本、CI 缓存）当天全拆，manifest 直接写 ^0.1.2-alpha.2。它本来就只该是临时方案。新坑三个：

1. 拆 overrides 暴露出外部插件的存量绑定。这个块此前顺带强制解析了所有外部聚合插件的 peer，撤掉之后，两个硬 import 了 alpha.2 已删面的外部插件（dsh-better-sidebar@0.15.2、@mlgbnb/dsh-archive-manager@1.0.7）会让 dsh web 启动直接中止。只能先从 dsh-web-all 聚合排掉（aggregate 行、package.json deps 一起），等上游出 alpha.2 构建再回归。删钉点块之前，先盘点外部插件对已删 SDK 面的硬绑定。

2. cordis 双副本会静默拆掉服务增广。alpha.2 的 peer 优化把多数兄弟 peer 裁出发布清单：仓库自有 cordis 声明若还钉旧版（4.0.1，cohort 要求 ^4.0.2），pnpm 会解析出两份 cordis，所有 declare module '@deepseek-ai/cordis' 增广静默失效，typecheck 全过、注入服务全断。把自有声明抬到同版本，连带 cordis-plugin-loader 和 cordis-plugin-include。peer 裁剪还会切断类型图边：dsh-client-ui-session 从 dsh-client-ui-conversation 的 reach 里被裁掉，dsh-git-graph 类型断了，改成显式 devDependency 加 type-only import。

3. settings 从独立导出改成 service seam。dsh-settings 删掉了 installSettingsSection / settingsNamespace / deepEqualJson，换成 ctx.settings.installSection(ctx, ns, schema, entry, hooks)。我们 12 个 settings 消费者全部迁到官方 per-plugin 模式 ctx.inject(['settings'], (c) => c.settings.installSection(...))，hook 形状不变，namespace 常量写 'literal' as SettingsNamespace 保住 branded type，web-settings bridge 把它原样传给 provider 的 mutate。「独立导出函数改成注入服务」是这类升级的常见形态，按官方模式逐个迁，不要包共享 helper。

不变的部分：客户端产物仍是双 cohort 兼容，没消费 alpha.2 独有的运行时面，跑在 alpha.1 宿主上没问题；上一轮的 store shim 和 remote.agentPresets 探测原样有效；CI 反而简单了，frozen install 直接从 registry 解析。

给 skill 的建议：升级已发布的 cohort 时，重点不再是「怎么装进未发布 cohort」，而是 peer 裁剪、cordis 双副本、seam 迁移，和外部插件的存量绑定。

---

我们是 dsh-web 社区插件仓库（zhu1090093659/dsh-web）。每条的决策记录和验证细节在仓库的 .agents/notes/implemented 和 docs/archive，可以按需展开。

[t4wefan]

真的吗 https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill

[AdamPlatin123]

近期再琢磨一个形态互补的东西，流程随后整理出来参考，是个无人值守的迁移 bot（GitHub Action）：插件 repo 装一个 workflow，监听 dsh-v* release，自动完成迁移，树有变更才开 Issue + PR，稍后转public，reply会附上详细地址和信息

[renat3u]

https://github.com/renat3u/dsh-upgrade-skill 希望有所帮助。

[william-jin-cmu]

我们也做了一版，思路和 @t4wefan 贴的 oh-my-dsh 那份很接近（版本卡片 ≈ 我这里的 hops/），但把"生成事实"的过程也脚本化了，仓库在 https://github.com/william-jin-cmu/dsh-plugin-upgrade ，MIT，官方随便拿去改。

结构：方法在 SKILL.md（版本无关的 6 步：定范围 → bump 依赖 → 修 Host 导入 → 修浏览器半边 → 查 overlay → 真实加载验证），事实在 hops/0.1.1-to-0.1.2.md + .rules.json。三个脚本：scan.mjs（按 package.json 钉版自动选 hop 链，输出 file:line + 替换方案）、bump-deps.mjs、diff-api.sh（拉两版 npm tarball diff .d.ts 导出和 manifest；--remotes <v> 直接从生成的 typert.remote-client.d.ts 列出全部 ctx.remote 命名空间和方法）。下个版本出来只需 diff-api.sh 跑一遍 → 人工补语义变化 → 写几条规则。

事实表是怎么来的：不是读 changelog，是逐包 diff 了 0.1.1-rc.2 和 0.1.2-alpha.2 的发布 tarball，再拿两个真实插件升到 tsc 干净、能在 0.1.2 profile 里加载。评测用的是 dsh 自己的 headless（0.1.1-rc.2 + DeepSeek）跑 3 个用例有/无 skill 对比——结论坦白说是：模型自己去 diff npm 包也能做对大部分，skill 主要是省掉那一步（快 1.2–2.5×）和浏览器侧少走弯路。

几条可能对楼上几位也有用的核对结果：

1. session.rename 的 Remote 命名空间是 ctx.remote.session.rename，不是上游 Agent Note 里写的 sessionTitle/rename。oh-my-dsh 的 ALPHA1-01 表和我第一版都照抄了 note，是评测里 DeepSeek 读了生成的 d.ts 才纠出来的。agentPreset.remove 对应的也是 agentPresets.deletePreset。完整的 12 个命名空间 × 方法名表在 hop 文件 §9，都是从 typert.remote-client.d.ts 提的。
2. 生成的客户端方法返回 Promise<RemoteResult<T>>（{ok:true,value}|{ok:false,error:RemoteError}），不 throw；RemoteError 用 isDSHRemoteError 结构标记识别，跨 bundle 不要 instanceof。这和 @zhu1090093659 第 5 条 Host 侧 error.failure.code 是同一套码的两个面。
3. @zhu1090093659 alpha.1 确实没发 npm，但 alpha.2 发了（npm view @deepseek-ai/dsh-tools dist-tags → alpha: 0.1.2-alpha.2，dsh-web-app/dsh-base 也在），source-built tarball overrides 那套现在可以省了。不过新坑是 pnpm ≥ 11 默认 minimumReleaseAge 24h，刚发的 alpha 会静默解析不到，要在 pnpm-workspace.yaml 里设 minimumReleaseAge: 0 或加 exclude。
4. 一个 export diff 看不出来的静默变化：systemPrompt.section() 的内置 tool 段 order 从 100–199 挪到了 1000–2900（SDK 段 5000），PERSONA_ORDER 删了换成 getSectionOrder(name)。插件写死 order: 116 照样加载、不报错，只是提示词位置跑到所有内置工具前面了。
5. dsh-client-runtime 没有 0.1.2 版，逐 export 的去向表在 hop 文件 Part B（SlotRegistry → dsh-client-ui-renderer/client，SessionRuntime/createScope → dsh-api-session-controller/client，Conversation* → dsh-client-ui-conversation/chat，workspace → dsh-client-ui-workspace；SlotRegistry.register 签名没变，只是路径变了）。

@zhu1090093659 你那 10 条里 #4（cordis remote 代理对未注入属性是 throw 而不是 undefined）、#5（描述符逐方法有线布局 + _request 参数名）、#6（启动竞态）我这边都没覆盖，是真正跑过 20 个包才会撞到的，想合并进 hop 文件，可以吗？@AdamPlatin123 的 bot 需要的"事实层"应该就是 hop + rules 这种形态，欢迎直接用。

等 0.1.2 rc 出来我会跑 diff-api.sh 0.1.2-alpha.2 0.1.2-rc.N 把增量补上。

[lhh010]

DSH 0.1.1 → 0.1.2 插件迁移实录：6 个插件的升级过程与踩坑记录

适用于官方计划中的「0.1.1 → 0.1.2 插件升级 skill」参考。以下内容来自 6 个真实 Web UI 插件从 0.1.1-rc.1 升级到 dsh-v0.1.2-alpha.1 的完整迁移过程，全部经过实机 boot 验证 + 单测回归。

0. 迁移对象与结果

插件	迁移前 → 后版本	迁移量级	仓库（lhh010 公开镜像）
dsh-ui-whale（标题栏像素鲸鱼）	v0.3.4 → v0.3.5	中（快照 API + slot 注册）	https://github.com/lhh010/dsh-ui-whale
dsh-ui-progress（输入框进度条）	v0.9.3 → v0.9.4	中（同上 + turn 结束判定）	https://github.com/lhh010/dsh-ui-progress
dsh-input-history（Ctrl+↑↓ 输入历史）	v0.1.3 → v0.1.4	中（快照 API）	https://github.com/lhh010/dsh-input-history
dsh-minigames（浮动小游戏窗口，18 款）	v0.3.5 → v0.3.7	≈0（自包含 body portal，零 slot 依赖）	https://github.com/lhh010/dsh-minigames
dsh-paste-input（粘贴/拖拽输入）	v0.1.5 → v0.1.6	小（仅需清理 inject 声明）	https://github.com/lhh010/dsh-paste-input
dsh-file-trace（文件操作追踪+diff 浮窗）	直接基于 0.1.2-alpha.1 新写	—（可作为 0.1.2 新 API 的正面样例）	https://github.com/lhh010/dsh-file-trace

结论先行：真正的工作量集中在「读会话快照 + 注册 slot」这两类插件；纯 DOM/自包含插件几乎零成本。官方保留的 ChatSnapshot.legacy 兼容投影是迁移的最大功臣——旧字段数据都在，只是换了地方读。

1. 升级环境准备

# 0.1.2-alpha.1 不在 npm（npm latest 是 0.1.1-rc.2），需要源码构建：
git clone https://github.com/deepseek-ai/deepseek-harness
git checkout dsh-v0.1.2-alpha.1
pnpm install && pnpm run build
# 全局 dsh 指到源码构建产物；动手前先备份 ~/.dsh（profile/会话/凭据都在里面）

插件仓库的 devDependencies 用 link 指到 DSH 源码的包（如 link:../.dsh/source/current/packages/client/ui-renderer），.dsh/source/current 做成指向源码 checkout 的 junction，切换 DSH 版本时只动这一个链接。

2. 五个核心破坏性变更（附前后对照）

2.1 @deepseek-ai/dsh-client-runtime 包被移除

- import type { Context as ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+ import type { Context as ClientContext } from '@deepseek-ai/cordis'

同时 package.json 的 dsh.client.inject 里若声明了 dsh-client-runtime 必须删掉，否则启动直接报服务缺失（paste-input 的 v0.1.6 修的就是这个）。devDependencies 里的 link 也要换成新包位置。

2.2 ConversationSnapshot 重构为 views 架构

旧的平铺字段（nodes / partial / runningCalls / turnTimings / turnEnds）全部挪进兼容投影：

- const { nodes, partial, runningCalls } = conversationSnapshot
+ const chat = conversationSnapshot.views.get('chat')
+ const { nodes, partial, runningCalls } = chat?.legacy ?? emptyProjection
+ // 回合时间线在新位置：chat?.timeline

官方保留了 legacy 投影，先迁到 legacy 就能跑，等稳定后再逐字段迁到 views/timeline 新结构——这是最稳的两步走。

2.3 会话生命周期拆到 SessionSnapshot

running 等生命周期字段不在 Conversation 里了，改经 useSession 座读取；组件 props 用 useSession + useConversation 双座组合。

2.4 slot 注册方式变更

- ctx.slots.register({ name, id, order, locale }, Component)
+ ctx.slots.inject(name, () => ctx.slots.register({ name, id, order, locale }, Component))

ctx.slots 的类型来自 @deepseek-ai/dsh-client-ui-renderer/client——记得把这个包加进 devDeps（type-only import 也要），否则 ctx.slots 类型拉不到。

2.5 host 半段不受影响，但注意生效方式

webServer 服务注册（ctx.webServer.register({kind:'exact', path, handler})）、child_process、dsh-home-paths 等在 0.1.2 无破坏。但 host 半段改动必须重启 dsh 才生效，client 半段硬刷新即可——调试时很容易被这点迷惑。

3. 踩坑实录（按出现频率排序）

1. tsbuildinfo 假阳性：改完源码 typecheck 报八年前的老错误（如 MISSING_EXPORT resolveSessionPreset），或干脆骗过检查。解法：pnpm run clean 再 build。迁移期间建议每次验证前都 clean 一次。
2. 测试代码的 0.1.2 语法坑：fiber 上 dispose 变 readonly（测试里不能赋值模拟）；测试文件里的 as 断言在 JSX 解析路径上会炸，改用变量预收窄。
3. oxc/vite 解析器比 tsc 严格：未闭合的 <div>、跨行三元 + 箭头函数都会在构建期报「Did you mean {'>'}」这类诡异错——按解析器提示回炉重写，别跟它较劲。
4. dsh.client.inject 残留旧声明：见 2.1，报错信息不直接指向 package.json，容易排查半天。
5. pnpm 11 拦截构建脚本：新环境安装插件报 node-pty 构建被拒，pnpm approve-builds --all 放行即可（记得写进插件 README）。
6. 插件崩了别让用户黑屏：给 client apply 包一层兼容自诊断（检查 ctx.slots.inject / ctx.locale.register 等关键能力，缺了就渲染修复指引横幅而不是抛异常）。6 个插件都内置了这个 pattern，alpha 阶段救了无数次。
7. host 端点里的同步子进程会冻结整个 host（迁移后新增功能的坑）：execFileSync('git', ['ls-remote', …]) 无超时无缓存，断网时阻塞整个 dsh 事件循环——GUI 卡成幻灯片。一律改异步 execFile + 超时 + TTL 缓存 + inflight 去重。
8. 浏览器直连 GitHub 的 CORS/墙问题：版本检查走 host 同源端点（GET /dsh-<id>/latest 内部 git ls-remote），比浏览器 fetch api.github.com 可靠得多；fallback 记得加 AbortSignal.timeout 并并行发起，避免串行超时叠加。

4. 迁移步骤模板（可以直接进 skill）

1. 备份 ~/.dsh；DSH 切到 0.1.2 源码构建，.dsh/source/current junction 指过去。
2. 全仓搜索替换：dsh-client-runtime → @deepseek-ai/cordis 的类型导入；删 dsh.client.inject 与 devDeps 里的旧声明。
3. 快照读取改 views.get('chat')：先全部走 .legacy 投影保证能跑，再渐进迁移。
4. 生命周期字段改 useSession；slot 注册改 ctx.slots.inject(name, () => ...)。
5. pnpm run clean && pnpm run build && pnpm run typecheck && pnpm run test。
6. 实机验证：dsh --profile web 起来后硬刷新；host 半段有改动则重启 dsh。
7. 在插件 README/INSTALL 里声明兼容矩阵（旧版本行保留，标注对应 DSH 版本），发新 tag。

5. 给官方 skill 的两条建议

• 按插件类型分流：A 类「读快照/用 slot」是重灾区（对照第 2 节五条）；B 类「自包含 DOM」基本零成本（minigames 实测只重跑了 203 个单测）。skill 开头先让用户判断类型，能省一半人走冤枉路。
• 把 tsbuildinfo 假阳性和「client 硬刷新 vs host 重启」写进去：这两个不是 API 变更，但消耗的排查时间不亚于任何一条 API 迁移。

---

迁移时间线：08-28 完成 API 迁移（whale v0.3.5 / progress v0.9.4 / input-history v0.1.4 / minigames v0.3.7 / paste-input v0.1.6），均在同日实机 boot 验证；后续版本为新功能迭代。欢迎取用以上任何内容做 skill 素材。

[statem-li]

dsh-webui 是一个完全不修改 DSH 源码、
完全通过 profile 插件机制（dsh.bundle.patch + host/client 双半身）实现的
DeepSeek Harness 会话增强全家桶：约 311 个源文件、8.1 万行 TypeScript、
40+ 个可独立开关的功能模块，覆盖 9 大能力面。

投入到了哪里

维度	数字
源码规模	311 个文件 / 81,446 行 TypeScript（host + client 双半身）
功能模块	40+ 个，每个都可独立启停（webui-modules 配置命名空间，升级新增模块老配置自动兼容）
能力面	对话体验、模型与供应商、技能、AI 浏览器、自动化、团队编排、记忆、用量统计、文件与工作区、外观与系统
迭代	2026-08 一个月内从 DSH 0.1.1 契约适配到 0.1.2，期间完成一次「全家桶 → 独立插件拆分」再「部分融合」的架构演进（两种形态都真实跑通）

实际功能与价值

1. 对话体验（把「用起来舒服」做到极致）

• 图表化消息导航：视图图块 + 消息徽标/弹窗 + 弹窗内加载更早消息；
• 对话退回 v2：git 式内容寻址存储——文件内容按 SHA-1 入全局 blob 库（gzip），
  快照只落「路径 → 指纹」纯索引，体积降两个数量级；一键回退文件与该轮上下文；
• 会话产物卡片：host 端独立记账 Agent 写入产物（jsonl），重启后仍可开大卡片
  应用内预览（图片/markdown/代码/二进制兜底），不经系统打开；
• 对话截图：常驻无头浏览器渲染管线（markdown-it + Shiki），四主题、
  1080P/2K/4K、mermaid 围栏就地画成 SVG（语法错误降级源码块），空闲自动回收；
• 完成胶囊 + 提示音 + 语音播报：语音播报每回合念 35 字结论（本地提取零 token），
  带多会话话筒仲裁、静默释放、进程级静音；
• 审批提醒、会话平滑过渡、消息气泡宽度、中文思考开关、MOOD 自述等。

2. 模型与供应商（把模型能力用对）

• 供应商管理 + 模型能力开关：在官方「模型」页逐模型开识图/推理档位/生图/视频；
• 推理等级同步 / Developer Role 兼容性一键检测与修复；
• 网关伪装接入、供应商限流（按域名 RPM 令牌桶 + 并发信号量，从源头避免 429）。

3. 技能与工具

• 技能 slash 两级导航源（集合 → 技能）+ 技能开关（直接读写 SKILL.md frontmatter，
  含 Agent 预设层）；工具调用聚合（活动抽屉）；mermaid 图表按需引擎。

4. AI 浏览器

• CDP 直连 Chrome 的多标签会话隔离、browser_batch 一次调用最多 10 个动作
  （把逐动作 N 轮推理压成 1~2 轮，表单类任务从 ~6 分钟缩到 ~1 分钟）、
  元素选取、权限卡、无头内嵌。

5. 自动化与团队编排（最重的两块）

• 定时自动化任务引擎：cron 调度 → 绑定模型真实执行 → Agent 建议确认卡；
• 团队 Agent 编排器：多团队多角色接力、一句话生成团队、可拖拽关联画布、
  每角色工具/技能装配、对话框开关（按会话隔离）、执行 HUD 实时面板。

6. 本地记忆（把「长期记忆」做成产品）

• hybrid 检索（向量 + 关键词）、标签/作用域、置顶置灰、启用/禁用；
• Memory Dream：每日自动语义整理（合并去重/精炼重写/删除低价值/提升长期）；
• 用户可在面板里直接改记忆，重启不回滚。

7. 用量与统计

• 用量工作台：趋势、Token 活动热力（52 周 × 7 天）、供应商余额、预算；
• 跨天单点数据也绘制、铺满模式随窗口缩放实时跟随。

8. 文件与工作区

• 文件浏览器 + 修改历史对比（行级 LCS 对齐 diff）、应用内预览总线；
• 工作区文档卡片（AGENTS.md / CLAUDE.md 检测、预览、一键创建）；
• _tmp/ 临时垃圾清理器（调度、最小文件年龄、保护目录、落 jsonl 日志）。

9. 外观与系统

• 玻璃质感主题（半透明毛玻璃 + 高光细边 + 柔和投影）、悬浮侧边栏；
• 壳管理更新（一键更新 DSH 本体）、插件自更新（增量）：只下载两版之间
  diff 补丁（实测 336 KB vs 整包 4.7 MB），unified diff 应用 + git blob sha
  逐文件校验，写入用「临时文件 + rename」避开 pnpm 硬链接写穿全局 store，
  校验不过自动回退整包重装，绝不留半成品；
• 移动端适配（App Shell 底部 Tab、折叠菜单、极简视图、返回顶部）。

为什么这些对官方有参考价值

1. 证明插件机制可承载复杂产品：40+ 模块 / 8 万行代码，零 DSH 源码改动，
   全部经由 dsh.bundle.patch、host/client 双半身、client 模块表与槽位系统装配
   ——DSH 的插件架构是「真的能长出大插件」的。
2. 模块化装配的工程实践：每个模块独立 try/catch 挂载、可按配置裁剪、
   核心能力常驻（视图/导航/渲染）；合并与拆分插件两种方向都走通过
   （全家桶 → 单体：dsh-triad/dsh-done-pill/dsh-prompt-optimize；
   单体 → 聚合：dsh-provider-hub）。
3. 踩过的坑就是生态的下一步：100 亿 token 中相当比例花在了官方文档
   不会告诉你的地方——@deepseek-ai/* 只发源码不发产物导致的
   ERR_MODULE_NOT_FOUND、client 模块表与 dsh-client.inject 的运行时行、
   槽位声明冲突 already registered、pnpm ≥ 10 拦截 git 依赖构建脚本、
   安装后 fibers 热停用顺序等等。这些经验不应只留在一个插件作者的脑内。

给官方的礼物：DSH 版本号升级技能包

🔗 https://github.com/statem-li/dsh-version-upgrade-0.1.1-to-0.1.2

一个面向插件作者（不是插件用户）的 Agent 技能集合包：把插件 repo 从
DSH 0.1.1 升级到 0.1.2-alpha.1 的完整迁移路线。

• 4 个技能：主入口（五步路线 + 症状速查表 + 完成定义）、构建契约
  （bundle patch / 双 bundle / pnpm 分发）、host 半身（解析面 / vendor 化 /
  构建守卫）、client 半身（槽位声明制 / unary→Remote 全量对照表 / 模块表）；
• 内容全部可溯源：逐条核对官方 dsh-v0.1.1-rc.1 → dsh-v0.1.2-alpha.1
  git diff（1100+ commits）、docs/subsystems/、packages/client/AGENTS.md
  与 .agents/notes/ 架构笔记；迁移坑来自上述 100 亿 token 的真实实践；
• 为什么值得进官方：官方文档教作者「怎么写」，缺「怎么升级」——而升级
  故障大多是静默的（入口消失、槽位不渲染、装完启动失败但源码目录正常）。
  本包恰好补上这块，且命名即版本范围（dsh-version-upgrade-0.1.1-to-0.1.2），
  以后每次版本升级都能按同一套路生成新包。

开放信息

• 仓库均为公开，许可含 MIT / BSD-3-Clause，欢迎引用、拆解、讨论：
  • dsh-webui（全家桶，BSD-3-Clause）
  • dsh-triad（用量/技能/记忆三合一）
  • dsh-done-pill（完成胶囊）
  • dsh-prompt-optimize
  • dsh-provider-hub（供应商中心）
  • dsh-version-upgrade-0.1.1-to-0.1.2（本项目）

[Nothing1024]

我来抛砖引玉一下，结合自己的兼容经验做的，希望能帮上忙。

https://github.com/Nothing1024/dsh-upgrade-compat

覆盖个人痛点主要是：

1. 某些逻辑大改，导致插件当前依赖无法做调整，需要和用户交流开始进行部分重构
2. 对齐一些兼容性接口（放AI🏹）
3. 简单的检查和汇报

---

思路如下（AI辅助生成）

Phase 1: 版本差异检测
审计当前依赖 → 确定目标版本 → 获取上游变更（Release Notes + .agents/notes/ + Compare API）
↓
Phase 2: 接口扫描 + 交叉比对
收集插件耦合面 → 与上游变更做交集 → 深入检查受影响的包
↓
Phase 3: 兼容性报告 + 决策门控
L1/L2/L3 分级 → 生成结构化报告 → 三条路径（直接升级 / 讨论 / 大任务）
↓
Phase 4: 执行升级 + 预检验证
更新版本号 → 构建修复 → 预检清单（tsc / build / import / validate / 冒烟启动）

[yangyang0507]

一句话：我们认为官方升级 skill 应该是“稳定的升级框架 + 按版本加载的事实卡”，而不是一份很快过期的 0.1.1 → 0.1.2 搜索替换清单。

楼里已经有很好的具体 API 经验和扫描脚本；我们想补充的是一套能长期容纳这些事实的通用骨架。为此，我们用 oh-my-dsh 的 0.1.1-rc.2 → 0.1.2-alpha.2 迁移做了 forward test，并正式整理了 dsh-upgrade skill。

我们的结构

层	负责什么	为什么单独一层
主 skill	选择 plugin release、cohort migration、multi-cohort compatibility 或 assessment-only；定义授权边界和升级闭环	跨版本保持稳定，不写死某次 API 变化
Contract surfaces	检查 package graph、Cordis composition、services/events、配置默认值、lifecycle、runtime 和 distribution	避免只靠文本扫描或 typecheck 判断升级完成
Version cards	记录适用条件、旧假设、目标契约、证据来源、适配、回归和剩余风险	每个 DSH 版本独立更新，事实不会污染通用流程
Ecosystem cases	pnpm、TypeScript、monorepo、打包与具体产品经验	仅在仓库确实使用该生态时加载，不把偶然工具链当成 DSH 规则

实际执行链可以概括为：

确定兼容目标
→ 建立发布包与宿主 composition 的 contract graph
→ 保存 baseline 并使缓存失效
→ 只适配确认变化的公开契约
→ 验证真实 host mount、runtime 与候选分发物
→ 把可复用发现沉淀为 version card

我们特别想避免的四个误区

1. DSH 包逐个追 latest，最后得到一个混合 cohort。
2. rg 零命中或 typecheck 通过，就认为 lifecycle、配置优先级和 host mount 没问题。
3. monorepo 内 workspace link 全绿，就认为发布后的依赖图也相同。
4. 把 pnpm、TypeScript、某个宿主或某次 prerelease 的 workaround 写进所有插件都必须执行的主流程。

forward test 带来的实证

这次真实迁移命中了纯 API diff 之外的问题：Cordis 基础版本需要随 cohort 对齐；settings 从独立函数迁到 service seam；Profile 生命周期与异步边界变化；domain event ownership 移动；内置 preset root 改变 ID 优先级；warm compiler cache 会掩盖声明变化；workspace 成功会隐藏 tarball 中指向旧 sibling package 的依赖图。

当前 alpha 分支已经通过 install、cold typecheck、全部 workspace tests、build、真实入口 smoke、composition 和边界检查。empty-consumer 安装没有被虚报为通过：它发现两个产品包仍需先获得协调的 prerelease 版本，才能证明候选 tarball 不会回落到 registry 中旧的 sibling package。

可直接参考的材料

• 通用 dsh-upgrade skill
• skill 架构与分层提案
• 0.1.1-rc.2 → 0.1.2-alpha.2 实证迁移记录

如果官方开始制作 skill，欢迎直接拆用主流程、contract-surface 分类、validation matrix、evidence-card 模板和 prerelease version card；其中 prerelease 事实应继续针对最终 RC 发布包逐项复核。

[goatliamia]

我们这边是从「先声明、后验证」的角度做插件升级适配的，也结合 0.1.1 → 0.1.2 做了一次完整的实际升级，分享几条观察。

1. 挂点声明 + 树差检测。

把插件实际依赖的官方路径先声明成挂点（例如 packages/tools、packages/client 等），再按 GitHub tag 做文件树差异；只有命中实际挂点，才进入后续验证。这样不需要每次完整重读上游 diff。Alpha tag 和 npm registry 的发布节奏目前也需要分开看。

2. 规则与事实绑定。

目前的 check 规则同时保留「实测证据（源码 file:line）+ 上游挂点」。升级以后，可以直接根据命中的挂点定位需要重新验证的规则。

这和 hop + .rules.json 的形状比较接近：把已经确认的事实固化成规则，把上游挂点变化变成重新验证的触发器。

3. 一些「静态全绿、运行时才暴露」的情况。

• exports 缺少 ./package.json 时，客户端可能静默不装载，但 boot 本身仍然通过；
• host 入口虽然能在运行时归一化多种形态，但教程措辞与 loader 实际接受范围可能不完全一致；
• 某些 card 值可以静默 fallback，声明存在并不意味着当前 Web UI 一定会按预期渲染；
• 查挂载契约时，实际已安装插件的 client/service 契约有时比只看官方 slot 更接近真实运行路径。

所以目前升级验证里有一条经验比较重要：

能加载 ≠ 行为仍然正确。

4. 一个 DSH 比较特殊的安全问题。

在 DSH 上开发或升级 DSH 插件时，开发对象本身就是当前运行宿主。重启、终止 DSH、修改 harness 源码、删除当前 preset、卸载正在使用的插件，都可能直接影响正在进行的开发会话。

因此升级 skill 里也许值得明确一个前提：

动手前先确认：这个组件是否正在支撑当前运行环境？

如果是，最好把这类操作交回人工；涉及「停 → 启」的操作，也尽量保持原子性。

5. 一个已经实际跑通的例子。

我们维护了一个小型的 DSH 插件工程化工具 dsh-plugin-maker，目前主要提供 scaffold、contract check、impact analysis 和接盘体检。

这次 Maker 自身已经完成了从 0.1.1 → 0.1.2 的升级适配：

• 44 条测试全绿，其中新增 4 条挂靠建议断言（包引用 → 挂点、inject → 挂点、空文本零误报、去重）；
• 本次变更涉及 7 个文件，+73 / −10；
• registry 已更新到 v0.6.19。

到这里，我们实际跑通了一条完整的链：

upstream watch
→ check 点名
→ vet 给出改法 + 挂靠建议
→ 本插件按实际依赖完成适配
→ 测试重新验证

而且这套能力现在并不只服务 Maker 自己生成的插件，check / vet 也可以直接作用于其他插件目录。

所以目前更希望看到的，可能不是一个「官方自动升级所有第三方插件」的方案，而是更机器可读的 compatibility / impact surface，例如：

DSH version N
↓
changed surfaces
↓
affected paths
↓
migration notes

这样第三方生态可以各自决定怎么迁移、怎么测试、怎么修复。

另外也建议继续区分：

「插件还能加载」

和

「插件行为仍然正确」

因为这两件事在实际升级里并不总是一回事。

很好奇官方后续会不会考虑提供类似 upgrade impact / compatibility surface 的机制，或者目前更倾向于完全由插件作者自己维护这部分迁移？

[hikariming]

oh-my-dsh基于这份征集建了迁移 skill 仓库：
https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill

 刚在 Docker 里对你们的痛点 #4 做了一次全链路复现验证：

 - 按 0.1.1 写法（注入 apiProxy）写了个最小插件，挂上 0.1.2-alpha.2，
   完整复现了dsh爆炸症状——插件等服务导致整个宿主启动失败；同一插件放回 0.1.1-rc.2 则完全正常；
 - 按 skill 卡片迁移后（换注入 + 换调用 + 删被移除的 SDK 依赖），
   插件在 0.1.2 上激活成功、真实服务调用走通。

 验证报告（含新旧宿主对照表和复现指南）：
 https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill/blob/main/docs/validation-report-2026-08-30.md

[33moren33]

各位开发者们好，我也同意@yangyang0507 的观点，开发者们这一个月一直在追官方版本的更新，类似西西弗斯一样不停推着石头。

所以我盯的不是 0.1.2 这一版，是升级本身。skill 里我没放变两版本变更单，只放一种程序化的使用技巧：把每块插件单独放进空框架起一遍，缺谁由官方启动审计点名。判断不经过llm判断 ——同一版跑很多遍结果都一样，新版本dsh重跑新的清单。我的关注点：是落在一块块隔离测试，合法在cordis基座上程序化的跑。

然后这个skill就有了优雅的跨版本的能力。复用官方仓库已有函数和教程思路，看到@tianyicui 号召分享一下，也希望社区开发规范立起来，目前函数的适配性我还在更新完善，大家有兴趣可以看下：
https://github.com/33moren33/dsh-slice-bench

[Jstn-1g]

A concrete alpha.2 migration result from DSH Live Voice PR #51, now merged, adds two checks that may be useful in an official upgrade skill:

1. Widening peerDependencies was not sufficient. After alpha.2 peer trimming, dsh-client-ui-slots declarations reach dsh-client-store without declaring that edge. Without an explicit alpha.2 dsh-client-store development dependency, slot/component inference degraded to any even though the plugin runtime did not import the store. The development graph also had to move as one cohort to Cordis 4.0.2; retaining 4.0.1 risks duplicate Cordis copies and broken declaration augmentation. A deleted dsh-client-runtime test seam moved to its new owner, dsh-client-ui-renderer/client.

2. Some API changes cannot safely support both cohorts by search-and-replace. In a separate TUI audit, PermissionPresetService.current(events) on rc.2/alpha.1 became current(session) on alpha.2. Passing a Session breaks the older implementation at runtime; passing events fails alpha.2. Blindly appending alpha.2 to the peer range would therefore create a silent multi-cohort regression. The upgrade workflow should either narrow the new release to one exact cohort or require a public, version-aware adapter with tests against both cohorts.

The Live Voice gate used a frozen install, peer-graph check, 241 tests, Node 22.19/current hosted CI, the complete official alpha.2 source build, official CLI packed-plugin installation, and an authenticated Web workspace/Session plus deterministic one-turn fake-provider composition against exact upstream commit 0a53fb55. This caught package/type ownership problems that source typecheck alone would not establish.

That proof does not include credential-backed Qwen, physical audio devices, BFCache, or packaged Desktop. The broader lesson is to verify the published type graph and exact installed runtime composition, not only imports and unit tests.

[hikariming]

感谢 @tianyicui 发起征集！我们基于这个讨论建了一个社区 skill 仓库，并用 docker 容器做了插件升级全链路验证：oh-my-dsh/dsh-plugin-upgrade-skill

几个对官方整理 migration guide 可能有用的回馈：

1. 在容器里完整复现了痛点 #4：0.1.1 插件原样装到 0.1.2-alpha.2，启动即 pending (waiting for service: apiProxy)，整树 activate 失败、exit=1；迁移后同一插件 apply 正常执行。
2. 新旧宿主对照：同一插件在 0.1.1-rc.2 宿主上能正常 activate，说明破坏是 0.1.2 引入的，插件本身没坏。
3. 验证中发现一个官方文档没写清的点：宿主平面与客户端平面是两套门面。apiProxy 是宿主平面门面、ctx.remote 是客户端平面门面，注入名不能对号替换——宿主平面消费者应直接注入领域服务（如 inject: ["llm"] → ctx.llm.listProviders()），误换成 remote 会挂起在 waiting for service: remote。

完整验证报告（四幕过程、新旧宿主对照表、可复现的容器步骤、插件源码附录）：
https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill/blob/main/benchmark/validation-report-2026-08-30.md

这个 skill 的核心原则是"先判定平面再迁移"，平面判定错误是迁移失败的第一大原因。希望对官方有帮助 🙏

[william-jin-cmu]

一天之内楼里出现了 5 个独立 skill 仓库 + 3 份实战报告，方案已经不缺了，缺的是合流——0.1.2 rc 出来时每家各自再核一遍同样的 API，就是重复劳动了。

提议：以 oh-my-dsh/dsh-plugin-upgrade-skill 为社区合流点。 理由：组织仓库而非个人号（旁边就是 dsh-community-standard）；结构上大家已经收敛到同一形状——"稳定流程 + 按版本事实卡"（它的 version cards ≈ 我们的 hops ≈ @yangyang0507 的 version cards）；@hikariming 做了 Docker 全链路复现验证，是楼里验证最扎实的；README 本来就按共建合集设计，有卡片 schema 和校验脚本，PR 门槛清楚。

我先带头：PR #37 已提，把我们仓库里核对出的东西并进去了——

• 修正 A1-01/A2-02：session.rename 的命名空间是 ctx.remote.session 不是 sessionTitle（发布产物 typert.remote-client.d.ts 为准；agentPreset.remove 实为 agentPresets.deletePreset）；
• 新增实测的 16 命名空间 × 方法全量清单 + 新版本发布后的机械再生步骤；
• 补了 typecheck 面此前完全没卡的三张：CallId→ToolCallId + prompt 段带位静默挪动（A1-15）、PERSONA_ORDER→getSectionOrder（A2-07）、helper 迁入 dsh-util-values（A2-08）；
• rollup R-01 批注：alpha.2 完整 cohort 已在 npm + pnpm ≥ 11 minimumReleaseAge 24h 的静默旧线回退坑。

如果各位也愿意把互补的部分 PR 过去，这份东西很快就完整了：@zhu1090093659 的运行时坑单（跨 cohort shim、_request wire 名、启动竞态——正好是卡片形式最缺的"静态全绿运行时才炸"类）、@lhh010 的 ChatSnapshot.legacy 两步走投影、@Jstn-1g 的 PermissionPresetService.current 双 cohort 不可搜索替换案例、@goatliamia 的"升级对象可能就是当前运行宿主"安全前提。等 rc 发布，官方从一个收敛过的仓库收编（dsh 有 bundled skill 机制，dsh-badge-skill 有先例），比从十几楼里各挑各的要容易得多。

我们自己的仓库（william-jin-cmu/dsh-plugin-upgrade）保留 scripts 层继续维护：diff-api.sh（两版 tarball 导出 diff + --remotes 命名空间提取）和升级前后夹具，oh-my-dsh 那边要的话随时整体搬过去。

[bruc3van]

DSH Doctor 帮助 Agent 诊断和升级 DeepSeek Harness 插件：识别新旧版本之间的 API 变化，修改可以确定迁移的代码，提示需要开发者判断的语义变化，重新构建并验证插件。

基于doctor CLI升级而来，普通用户可以用来诊断DSH无法启动问题，开发者可以用来帮助自己升级插件。https://github.com/bruc3van/dsh-doctor

[FlytoMAYDAY80]

DSH 0.1.1 → 0.1.2 插件升级 Skill 官方设计建议

面向 DeepSeek Harness 维护者与插件生态建设者。本文基于 0.1.2-alpha.1/alpha.2 社区迁移实践、官方 Slot 契约，以及一次包含多个 Web UI 插件和外部客户端的真实升级与恢复验证。最终版本事实必须在 0.1.2 RC 精确 tag 与发布产物上重新核验。

1. 背景：一次真实的 0.1.1 → 0.1.2 兼容恢复

我们在把本地 DSH 及其扩展升级到 0.1.2-alpha.1 后，连续遇到了四类用户可见问题：Web 页面要求重新鉴权；页面恢复后不能正常新建会话；原有标签、定时任务、多模型对比和项目看板入口消失；依赖 DSH 会话与事件的桌面客户端离线。表面上像是多个独立故障，实际横跨 profile 配置、Web Client Slot、组件生命周期、HTTP/Remote、WebSocket 事件和鉴权六个契约面。

1.1 遇到的不兼容问题

用户症状	实际不兼容点	为什么普通检查没有发现
直接打开 Web 首页提示需要鉴权	0.1.2 Web/API 使用新的浏览器会话与 authority 约束；裸首页不能替代当前进程生成的鉴权入口	HTTP 服务和首页资源都能返回，不代表 API 会话已经建立
页面可打开但会话入口异常	profile 配置漂移与 Client 插件运行时崩溃共同影响会话 UI	服务进程仍在，静态资源和部分页面仍能加载
原有标签页和功能入口消失	升级重写活动 profile 的包清单和 patch 配置，部分插件不再挂载；项目看板此前只是独立页面，并非持久插件	用户数据仍在，因此容易误判为数据丢失或产品删除功能
多个侧栏插件点击后崩溃	0.1.2 为 Slot 标准输入增加 useSessionPendingInteraction，旧 wrapper 手工枚举 props 时没有转发	插件是已构建 JavaScript，typecheck/build 无法替运行时验证完整 props
补齐新 prop 后仍然崩溃	wrapper 在官方 WorkspaceBrowser 的 store 就绪前注册；useStore 来自 registration store，并非全局 hook	依赖存在且 slot 注册成功，但注册顺序和 owner 生命周期不满足运行条件
桌面客户端 HTTP 请求返回 401	旧客户端调用未鉴权接口；0.1.2 的 Cookie 与 authority、端口和浏览器会话绑定	端口可连接，容易把鉴权失败误判为服务离线
会话列表接口返回 404/参数错误	路径从旧调用形态迁移为 /api/session/list，Typert 请求需要正确的 _request wire 结构	手写 mock 与调用代码可能共享同一个错误假设，测试仍然通过
WebSocket 已连接但收不到会话事件	旧事件端点迁移到 /api/remote.mux，还需打开 $events 逻辑流并处理新的事件 envelope	物理 WebSocket open 不等于业务逻辑流已建立

1.2 我们如何解决

1. 先确认真实运行身份：核对 CLI 符号链接、实际 Node 入口、版本、LaunchAgent 参数、3080 端口、stderr、活动 profile 和插件挂载，排除“修改了一个目录，运行的却是另一个入口”。
2. 先证明数据仍在：分别核对会话、存储、定时任务、插件数据和外部客户端配置。确认问题主要是挂载与可见性，而不是先删除或重建用户目录。
3. 恢复 profile 组合：补回升级时丢失的包依赖和 patch 行，将独立项目看板补齐为真正的 Host 路由、Client 入口、侧栏入口和会话区页面。
4. 修复 Slot wrapper：为所有 wrapper 转发新增标准 prop；随后等待官方 sidebar.workspaces occupant 及其 store 就绪，再完成兼容注册，并继续转发目录选择子 Slot。
5. 适配外部客户端：补齐本地鉴权，迁移 HTTP 路径与 Typert payload，改用新的 Remote mux 和 $events 逻辑流；审批、提问等事件只观察并返回继续处理结果，避免外部客户端抢占人工交互。
6. 隔离验证后再切换：所有修改先放在工作区兼容副本中，以临时端口验证；正式切换前备份活动配置和插件，保留可执行回滚路径。

1.3 实际验收结果

恢复完成时，我们不仅检查了首页：还验证了新建会话与标准模式、四个侧栏入口无新增控制台错误、定时任务及运行历史可读、多模型页面能加载模型、项目看板能读取真实会话，以及外部客户端 HTTP 轮询和 WebSocket 均正常。任务数量、运行记录和数百个既有会话均与切换前基线一致；这些结果只用于证明本次数据保全，不是通用产品指标。

1.4 从案例中沉淀出的经验

现场结论	应沉淀为官方机制
插件“消失”可能是 profile 未挂载或 Client 崩溃，不等于数据被删除	升级前后自动比较组合结果、插件挂载和用户数据基线
新增标准 prop 会击穿手工 wrapper，静态检查不一定发现	发布机器可读的 Slot 标准 props，并为 replacement 插件提供运行时契约测试
Slot 可注册不代表 owner、store 和子 Slot 生命周期正确	将 Slot owner/lifecycle/store 纳入迁移检查与冷启动验证
HTTP 200、WebSocket open 和插件 activate 都可能是假成功	官方完成标准必须包含鉴权、业务调用、事件流和用户可见行为
手写路径、payload 和 mock 容易一起漂移	迁移事实应从生成声明和发布产物提取，测试替身复用同一契约源
在活动 DSH 上直接试错会同时影响开发会话和用户数据	默认使用临时 profile/端口、精确备份和 last-known-good 回滚

正因为一次升级可以同时改变“插件代码、组合配置、浏览器契约和外部协议”，我们希望把这套恢复经验上升为官方可持续维护的插件升级方法，而不是只记录本次补丁。

2. 核心建议

官方 Skill 不应是一份固定的 API 搜索替换清单，而应是一套“稳定迁移流程 + 按版本维护的事实卡 + 确定性检查工具 + 真实运行验收”。其目标不是让 Agent 尽可能多改代码，而是识别插件实际依赖的契约面，只修改被目标版本影响的部分，并证明迁移后行为仍然正确。

建议将两个任务明确拆开：

• 插件作者迁移 Skill：检查并迁移一个插件仓库，处理依赖、Host、Web Client、Slot、Remote、配置和发布产物。
• DSH 用户恢复 Skill：处理升级后无法启动、无法鉴权、插件消失、数据不可见和外部集成断连。恢复不应混入插件源码迁移的默认流程。

3. 推荐的 Skill 结构

层级	内容	维护方式
SKILL.md	模式选择、授权边界、风险分级、迁移闭环	跨版本保持稳定
references/<from>-to-<to>.md	删除包、接口迁移、语义变化、适用条件、验证方法	每个版本独立维护
scripts/scan	扫描插件依赖、导入、inject、slot、Remote、自建通道	确定性输出 file:line，不自动改语义
scripts/diff-contracts	比较发布包的 exports、类型声明、Remote 和 manifest	从精确发布产物生成事实候选
scripts/validate	校验 Skill、事实卡、插件构建和测试夹具	CI 强制执行
examples/fixtures	覆盖典型插件形态的最小迁移样例	同时在旧版和目标版验证

主 Skill 建议支持三种模式：只读影响评估、单一目标版本迁移、跨版本兼容。只读请求不得自动安装依赖或修改代码；进入迁移前应先输出命中文件、拟采用的版本事实卡、验证方案和回滚范围。

4. 插件风险分级

参考社区提出的“先按插件类型分流”，建议进一步按契约耦合程度分为四级：

等级	插件形态	默认策略	最低验证
L0	自包含 DOM、独立页面，不读取 DSH 会话状态	重新构建并冒烟	build + 页面加载
L1	使用公开 list/keyed slot、标准 hooks、Snapshot 或 Remote	按版本事实卡迁移	typecheck + 单测 + 真实行为
L2	替换 shipped single slot、包装官方组件、同时包含 Host/Client 半身	强制人工审查，不自动搜索替换	隔离 Web 冷启动 + 完整交互
L3	自建 HTTP/WS/RPC、外部客户端、持久事件或权限策略	默认只生成迁移计划	鉴权、安全边界、协议与数据回放测试

风险等级应由扫描结果决定，而不是由插件作者自报。一个插件命中多个类别时按最高等级处理。

5. 强制迁移流程

1. 确定身份：记录插件源码、安装来源、当前 DSH、目标 DSH、Node、包管理器和解析后的依赖版本，禁止形成混合 cohort。
2. 建立基线：在旧依赖状态运行 build、typecheck、tests，记录迁移前已存在的失败，避免将旧问题误判为迁移回归。
3. 扫描契约面：覆盖包依赖、Cordis 服务、事件、配置、Host 文件系统、Web Client slot/hooks、Remote、自建通道和发布产物。
4. 计算变化交集：只加载命中当前插件的版本事实卡；事实缺失时标记待确认，不依赖模型记忆猜测接口。
5. 输出迁移计划：按 Host、Client、配置、分发和验证分组，列出文件、变化原因、测试和回滚范围，获得确认后才修改。
6. 隔离实现：在独立分支或 worktree 中修改；测试宿主使用临时 profile、DSH_HOME 或端口，不与正式实例并发写同一数据。
7. 分层验证：依赖解析、静态检查、冷启动、真实挂载、核心行为、候选发布包逐层通过后，才能报告迁移完成。
8. 生成报告：分别列出已完成、未命中、迁移前问题、未验证边界、回滚步骤和最终兼容范围。

6. 0.1.2 必须覆盖的契约变化

Web Client 与 Slot

• 检查已删除或迁移的 Client 包、dsh.client.inject 和 type-only import；依赖安装成功不等于浏览器模块已进入目标 module table。
• 检查 Snapshot 与 Session 生命周期拆分，避免继续从旧 Conversation 平铺字段读取状态。
• 通过 ctx.slots.inject(name, callback) 跟随声明 owner 的生命周期；不要假设 Client 插件加载顺序。
• 对替换 shipped single slot 的插件强制人工审查。组件必须覆盖当前 Slot 契约的 owner props、标准 props、children、inject、locale 和 store 语义。
• 不能将某次运行中读取其他 occupant、复用其 store 或手工串联原组件的方案写成官方通用模板。这类做法只能作为迁移期风险案例。

本次实证中，旧 wrapper 未转发 0.1.2 新增的 useSessionPendingInteraction，导致多个侧栏插件运行时崩溃；补齐属性后，又暴露出 store 随注册生命周期就绪的问题。这说明“普通 slot 贡献”和“替换 shipped single slot”必须采用不同的迁移等级。官方 Slot 文档也明确将 single 定义为替换点，增量 UI 应优先使用 list id、key 或公开子 slot。

Host、Remote 与外部通道

• Host 与 Web Client 是两个运行平面；旧 Host 门面不能机械替换为 Client Remote，必须先确定调用所在平面和服务 owner。
• Remote 方法、参数布局和错误结构应以目标发布产物生成的类型/描述符为准，不能只依赖 release note 或手写假对象。
• 自建 HTTP/WS 客户端必须验证 origin、authority、Cookie、路由、payload、逻辑流和事件所有权。官方 Skill 应优先使用公开 Connection/Remote 客户端，不推荐读取签名秘密或手写内部 wire frame。
• Client 修改通常需要浏览器硬刷新，Host 修改需要重启 DSH；Skill 应根据变化所在平面给出验证动作。

7. 官方完成标准

验证层	必须证明的结果
依赖	所有 DSH/Cordis 包属于目标 cohort，无旧包、重复 Cordis 或意外 registry 回落
静态	clean build、typecheck、测试通过；迁移前失败被单独归因
挂载	目标 profile 实际加载目标插件，Host/Client entry 都已激活，无永久 pending 服务
Web	使用当前鉴权入口进入，页面刷新有效，浏览器控制台无新增错误
会话	能新建会话，并完成一次与插件相关的核心流程
插件	UI 可见只是第一步，还需验证关键行为、错误分支、取消和卸载/重挂生命周期
数据	会话、配置和插件数据没有因迁移被删除、重置或错误迁移
分发	对最终 tarball/registry 安装物重复验证，不能只验证 monorepo workspace link
回滚	可以恢复旧依赖、配置和入口，且回滚不会继续写入新版本不兼容的数据

“可以编译”“插件能 activate”“首页返回 200”都不能单独作为迁移完成证据。

8. 建议 Core 同步提供的能力

P0：随 0.1.2 RC 提供

• 机器可读兼容面：随版本发布 changed surfaces，至少包含删除/迁移的包、exports、服务 owner、Remote、slot 标准 props、配置和持久化变化。
• 插件兼容声明：manifest 支持 DSH 版本范围、使用的契约面、Host/Client 形态、迁移状态和验证证据。
• 官方迁移检查器：提供只读命令，输出插件命中的变更项、file:line、风险等级和建议验证层，不直接承诺自动修改语义代码。

P1：降低生态升级风险

• 增量侧栏扩展点：为常见侧栏栏目提供正式 list/keyed slot，减少第三方插件替换整个 sidebar.workspaces 的需求。
• 单插件故障隔离：一个插件加载或渲染失败时，保留其他插件和核心 Web UI，并展示具体失败插件、契约和恢复入口。
• 安全模式与最后可用版本：启动失败时允许禁用最近变更的插件组合，并恢复 last-known-good profile。

P2：持续维护

• 将兼容面 diff、版本事实卡生成和典型 fixture 矩阵接入发布 CI。
• 对最终 RC 的真实发布包执行空白 consumer、典型 Client 插件、Host 插件、single-slot replacement 和外部客户端五类验证。

9. 发布与维护原则

• 通用 Skill 只保留长期稳定的决策流程；alpha 未发布、临时 tarball override、某个 pnpm 版本等事实必须放入带适用范围的版本卡。
• 不建议官方文档默认执行 pnpm approve-builds --all；应列出需要脚本权限的依赖，并只批准经过审查的构建脚本。
• 每条版本事实至少包含适用对象、旧契约、目标契约、证据来源、迁移方法、验证方法和剩余风险。
• 最终 RC 发布后，以精确 tag、npm tarball、生成类型和真实宿主重新验证 alpha 阶段结论；无法复现的经验应降级为待确认，不进入强制规则。
• 官方版本建议采用 MIT 许可证，并在致谢中区分官方契约、社区迁移案例和独立复现结果。

10. 参考依据

• 官方征集：Discussion #5120
• 社区六插件迁移实录
• 官方 Web Client Slots 文档
• 官方浏览器鉴权实现
• 社区合流仓库：oh-my-dsh/dsh-plugin-upgrade-skill
• API 差异与扫描脚本参考

[TT-Wang]

楼里 17 条发言我逐条读完，连同自己插件从 0.1.1 直跳 alpha.2 的实测，整理成了一个可跑的 skill：https://github.com/TT-Wang/dsh-hop （MIT）。结构上没有新发明，就是大家已经收敛的「稳定流程 + 按版本事实」。里面有两块楼里还没有的。

一个是幽灵宿主体检脚本。源码检出原地升级后，跑着的老进程还在执行内存里的旧代码，磁盘上 git describe 已经是新版本。脚本比对进程启动时间（ps -o lstart）和检出最后变更时间（git log -1 --format=%ci），再朝端口发一个无鉴权探针，401 是新 wire、ok 是旧 wire，不读版本号。这坑这一跳至少三家独立撞上（@goatliamia、@FlytoMAYDAY80 和我们），值得做成每次升级的第 0 步。

另一个是外部客户端/bot 车道。启动 token 每个进程换，但换来的 cookie 用盘上密钥签名，宿主重启后照样能用，无人值守脚本兑换一次就够。agent 中途提问的 $events 代答我们把可运行实现发出来了：https://github.com/TT-Wang/dsh-cron/blob/main/src/wire.ts ，alpha.2 真机端到端验过（agent 提问 → 按 label 代答 → agent 按所选继续）。@FlytoMAYDAY80 那边选择只观察、不代答，避免抢人工交互；bot 场景两种都用得上。@AdamPlatin123 的迁移 bot 要是需要鉴权和代答这层，直接拿。

维护这块我的想法：

数字事实会过期，方法过期得慢得多。所以 skill 里把两者分开：幽灵体检、按面分行、验证阶梯是方法，跨版本不动；包裹键、schema 号、cookie 期限是数字，每条标出处——一手实测、本机核对、楼里实录，三档。别人接手时知道哪条能直接用，哪条得先复核。楼里 17 条发言每条进了哪、算哪档，references/community-map.md 里有全表，官方取材请向原作者致谢。

数字事实还要能重新生成。session/list 要 _request 这种事，抄成表下一版就得重抄；但网关报错会逐字点名（missing "_request"; unexpected "request"），发布产物的生成声明里有全量 API 表（@william-jin-cmu 的 diff-api.sh 干的就是这个），cohort 发没发 npm view dist-tags 就能查。所以每条事实卡都带一条「怎么重新得到它」的命令，下一跳维护就是重跑加对比。

有了这两条，新版本发布日的动作是固定的：全部数字事实先降档为「待复核」；跑再生命令拿新候选；每条候选有人在真宿主上撞过才升回「一手」，没人撞的留在待复核档；幽灵体检照旧第 0 步。这四步写在 skill 的「下一跳怎么维护」一节。

合流的事：幽灵体检脚本和 wire/bot 配方，合流仓要的话我直接 PR 过去。长期看最省事的还是 @goatliamia 和 @FlytoMAYDAY80 提过的，官方随版本发机器可读的 changed surfaces；发出来之前，社区能自己做的就是把再生命令维护住。