The rc.1 adapter first went out as 0.21.0-rc.1, but DSH 0.1.7-rc.1 is upstream's release batch, so the plugin that targets it must not sit on a prerelease channel. Re-cut it as v0.21.1: the version is now free of `-`, so release.yml publishes it under npm's `latest` instead of `alpha`. Version literals only — package.json, dsh.plugin.json and SIDEBAR_SERVICE_VERSION (tests/service.spec.ts still pins the last two together). No code change: the peer floor stays ^0.1.7-rc.1 and the support line stays "DSH 0.1.7-rc.1 and later". Docs follow the channel move: README/README_EN/guide drop the "alpha channel" framing, the install command becomes @latest, and every older DSH line now gets an explicitly pinned command in the version table (@0.19.1 and so on) because `latest` no longer covers them. The rc.1 design record keeps its history and gains a §8 for the re-cut.
20 KiB
DSH 0.1.7-alpha.1 适配记录
适配对象:
dsh-better-sidebarv0.20.0 开发线(支持 DSH 0.1.6-alpha.2)→ v0.21.0-alpha.1(仅支持 DSH 0.1.7-alpha.1+)。 基线标签:dsh-v0.1.6-alpha.2(ddefc45fbc)→dsh-v0.1.7-alpha.1(c36a83ff6b),相隔 1299 个 commit / 4754 个文件变更。 本文记录为什么这么改与改完的证据;规则性结论沉淀在仓库根AGENTS.md§3。⚠️ 后续:
v0.21.0-alpha.1从未发布到 npm——这条开发线随后又适配到 0.1.7-rc.1,peer 下限收到^0.1.7-rc.1,整个 0.21 线的变更一并随 v0.21.1 出货。本文保留为 alpha.1 阶段的原始记录(结论仍然有效),最新状态见 2026-09-23-dsh-0.1.7-rc.1-adaptation.md。
1. 怎么做的(方法与边界)
先用一次 8 路 workflow 侦察把 1299 个 commit 收敛到「与本插件相交的 surface」:sidebar-right 契约、ui-chat 槽、ui-primitives 导出面、boot/plugin-manager、宿主内置侧栏能力盘点、peer 依赖图、会话格式与 sidechat 依赖面、插件触点全量清单;随后一个独立的交叉验证子代理逐条复核,证伪了 8 条(例如「ui-primitives 只需补 2 个 devDep」被推翻为 4 个,「聊天正文里的 http 链接什么都不开」被推翻为会回落 window.open)。
三条纪律贯穿全程:
- 结论必须带证据:每条破坏都给出
git show <tag>:<path>/ 实测命令与行号,不采信记忆。 - 区分「硬报错」与「静默失效」:后者的代价高得多——本版一共 6 处静默失效(见 §3)。
- 不采信子代理报告:所有关键结论由主代理独立复跑命令核对后才进入实现。
没有做的事:不改 DSH 源码;不写 0.1.6/0.1.7 双基线兼容层;不接入 ctx.documentPreviews;不恢复终端。
2. 硬破坏与适配(不修就崩)
2.1 dsh-settings 整体重写 —— 本版最大的一处
0.1.6 的 SettingsProvider.register(ns, schema) 给出 {get, watch, update, replace};0.1.7 只剩 SettingsForms 的 describe/update/replace/mutate/configure,且表单按插件 Loader 行的 entry.options.id 寻址,schema 取自 entry.fiber.runtime.Config。
后果链条(全部实测):register 不存在 → 插件 ctx.inject(['settings']) 回调体内 TypeError → 被 cordis 吞掉 → settingsFace 恒 undefined → 侧边卡片设置页回落到 schema 默认值、agentOpenTools 永远打不开、aionui-panel 互斥失效。
适配:
src/config.ts把用户偏好并入导出的Config(原先只是 4 个部署限额),每个偏好字段标为 volatile,并且 schemastery 必须换成 DSH 自己的@deepseek-ai/schemastery。这一点是计划里标记为「未验证」的风险,真机上被证实为必须:meta.volatile只是标记,DSH 的构建额外在解析期把 volatile 字段包成 cosmokitVolatile引用,而 Loader 的_commitVolatile正是提交那些引用。用公开包时settings.update返回 200、revision也递增,但有效值永远不变——设置写入被静默丢弃(--dsh-e2e-marker为空、title-bar 方案不生效就是它的症状)。另有第二个坑:.volatile()经extra()返回副本而非原地修改,写成for (const f of ...) f.volatile()会把标记丢掉,宿主随后报Plugin entry "better-sidebar" has no volatile fields。src/index.ts新增ownEntryId(ctx)运行时自发现行 id:按options.name === 'dsh-better-sidebar'+entry.fiber === ctx.fiber匹配,回退到第一个启用的同名行。硬编码better-sidebar会在聚合包(web-ui-better-sidebar之类)下静默失配。viewOf()=describe({redactSecrets:true}).find(d => d.ns === ns);写入update(ns, patch, expectedRevision)(SettingsConflictError仍导出、构造签名未变,409 分支保留)。configure({ auto: false }, ctx.fiber)关掉 DSH 的自动表单,避免同一批字段渲染两遍。- 一次性 legacy 导入(见 §2.2)。
- 放弃
settings/document-updated监听:cordis 的事件只向上冒泡到该 ctx 的祖先,而 settings 服务是在它自己的 context 上emit,插件的 fiber 是兄弟,监听必然不触发。改用「客户端每次重新读取表单时重新求值」覆盖同样的触发点。
2.2 用户设置会静默丢失 —— 已定位并修复
0.1.7 删除了 file-backed settings provider。迁移时它把 $DSH_HOME/settings.yaml 先改名成 .imported,再逐段导入,导入键是「同名 section → 同名 entry id」。插件的 section 键是包名 dsh-better-sidebar,而它的行 id 是 better-sidebar,LEGACY_SECTION_ENTRIES 里也没有这个例外——导入必然 warn 失败,section 只留在被改名的文件里。
这不是理论问题:本机 ~/.dsh/settings.yaml(63 KB)里就有一份真实的 dsh-better-sidebar 段,含 tabsEnabled(关掉了三个第三方 tab)、viewersEnabled、titleBarScheme、titleBarStripPx、editorExplorer 等。
修复:插件自己在 ctx.inject(['settings','profileContext']) 里读 join(profileContext.home, 'settings.yaml.imported')(退化再读 settings.yaml),取出该段,按当前 Config 声明的字段过滤(段里还留着 terminalFontSize / browserInterceptHttp / defaultWidthPercent 等已删字段,原样转发会让整个 patch 校验失败),再 update(entryId, section)。只在行的用户层为空时执行,所以幂等,且永不覆盖升级后的新值。
2.3 ui-primitives 图标整族改名
Icon<Name><14|16> → Icon<Name>Regular(1px)/ Icon<Name>Medium(1.3px)。具名导出 81 → 184,旧尺寸后缀名一个不剩。插件 26 个具名导入消失、17 个文件受影响、107 处替换。
两处容易踩空的地方:
- 不能全局替换:
src/client/icons.tsx里有 13 个插件自绘的同风格 glyph(IconImageOutline16/IconVscode16…)。改名集合是从「import ... from '@deepseek-ai/dsh-client-ui-primitives'的具名列表 ∩ 已不存在于该包」算出来的,机械替换 26 个符号,13 个自绘 glyph 原样保留。 - 失败模式是 render 期:插件 client bundle 是 CJS + external,产物是裸属性读,缺导出 =
undefined→ React 抛Element type is invalid,不是 ESM link error;而pnpm typecheck会直接报no exported member,所以类型检查是这一层唯一的守护(此前测试对图标名零断言,本次补了tests/primitives-exports.spec.ts)。
静默尺寸回归:0.1.6 的 IconXxx14 默认 size = 14,0.1.7 的 XxxRegular 一律默认 16。5 处原先依赖默认值的调用点(TabBar.tsx / Sidebar.tsx / FileTree.tsx 的 IconCloseFillRegular、SubagentView.tsx 两处 IconRefreshOutlineRegular)已显式传 size={14},否则会静默变大 2px。另有 StateDot 的 ongoing 态被整图重画(10px 像素矩阵 → 14px 圆环 spinner,默认尺寸 10 → 14),插件选择跟随宿主观感。
2.4 会话格式 v3 → v4
source.kind === 'plugin' 被硬拒(format v4 message requires a producer-owned source kind),而插件的 sidechat 边界注入正是那个形状。改用 plugin:dsh-better-sidebar——这不是随手取的字符串:DSH 自己的 v3→v4 迁移对未知插件名产出的正是 `plugin:${plugin}`,用同一个值意味着新写的数据与迁移后的历史数据形状统一,assertV4MessageSources 通过,历史 sidechat 会话也不会丢。类型层面另需一条 declare module '@deepseek-ai/dsh-llm' 的 MessageSourceMap 增强(0.1.7 把它改成合并可扩展的封闭联合,没有共享 catch-all)。
tool 结果消息重写:role: 'user' + 嵌套 type: 'tool-result' → role: 'tool' + 顶层 content / isError / toolCallId。插件 4 个解析器原先靠 candidate.type === 'tool-result' 命中,在新形状下会 continue 到底、恒返回空串——工具输出、jobs 回放、转录、文件变动四处一起静默空白。现在四处都同时接受新旧形状(旧分支必须保留:历史日志里就是旧形状)。
2.5 客户端会话快照换字段
SessionListState.subagentsByParent / jobsBySession → projectionsBySession。并且 setSubagentCatalogOpen 这个按需观察 API 被整体删除——0.1.7 在连接建立时一次性加载所有 Session 的 projection,所以那套 observe/unobserve 机制应当删除而不是改名;这是本版唯一一处「适配反而简化了代码」。
- 子代理目录改读
projectionsBySession[sid]?.values.subagentCatalog({id, createdAt, mode: 'one-shot'|'continuable'|'unknown', label?})。旧 catalog 条目带的activity/hasChildren不在新投影里:hasChildren由「该子会话自己的投影是否有非空 catalog」推导,activity由已有的 live 通道(subagents.live)提供。mode: 'unknown'是新值,凡穷举 mode 处都要容纳。 - 后台任务列表没有替代字段,新增插件路由
jobs.list(读ctx.jobs.list(sessionId))。这比旧的推送镜像更权威:镜像是 last-wins 的帧折叠,注册表是状态本身。 - 同一版里
ctx.jobs.list/get/read/kill的 caller 从Agent变成SessionId,插件因此可以彻底不碰ctx.agents来调注册表(src/jobs-routes.ts删掉了整个agents查找)。
2.6 依赖与测试 harness
- peer 下限
^0.1.6-alpha.2→^0.1.7-alpha.1(semver 预发布规则:前者数学上不含任何0.1.7-*);@deepseek-ai/cordispeer^4.0.2→^4.0.3。 - devDependencies 补 4 个:
@deepseek-ai/dsh-client-store、@deepseek-ai/dsh-util-workspace-path(ui-primitives@0.1.7产物新裸 import 的两个包)、以及这两个包自己裸 import 的zustand@~4.4.7与immer@^10.1.1(它们同样不声明dependencies)。只补前两个,vitest 一加载就Cannot find package 'zustand'。反过来没有预加dsh-workspace/dsh-agent-preset-registry:实测dsh-subagent@0.1.7的 28 个lib/*.js从不 import 它们。 tests/browser-globals.ts的假window补addEventListener/removeEventListener/dispatchEvent/matchMedia。0.1.7 的ui-primitives在模块求值期就window.addEventListener('scroll'|'resize'|'blur'),缺它会让任何 importservice.ts的 spec 一个用例都跑不起来(TypeError: window.addEventListener is not a function)——用 HEAD 干净 worktree 复现过,确认不是本次删除造成的。package.json.files补lib/client-locale.js(chunk 名在 8 处镜像,files一直漏这一个,locale chunk 从来没进过 npm tarball)。
3. 静默失效清单(本版的真实风险面)
| # | 症状 | 根因 | 守护 |
|---|---|---|---|
| 1 | 侧边卡片设置页只剩默认值、agentOpenTools 打不开 |
settings.register 抛错被 cordis 吞 |
smoke.spec.ts 的 settings 段 + configure({auto:false}) |
| 2 | 用户既有设置全部丢失 | legacy 段键名与行 id 不一致,导入静默 warn 失败 | 新增两条 legacy 迁移用例(含「已有用户值时不动」) |
| 3 | 工具输出 / jobs 回放 / 转录 / 文件变动四处空白 | type === 'tool-result' 在新形状下不再命中 |
4 个解析器各有真实生产者 round-trip 用例 |
| 4 | 任务管理页空列表 | subagentsByParent / jobsBySession 被删且读处全带 ?. |
新 spec 断言从投影推导拓扑 + jobs 基线 |
| 5 | 5 处图标静默变大 2px | 图标默认尺寸 14 → 16 | 显式 size={14} |
| 6 | 插件自绘 markdown 里 http 链接点了没反应 | 上一版交还浏览器时兜底仍指向已不存在的 'browser' 类型 |
link-intercept.spec.ts 新增 12 例 |
| 7 | 文件树一直陈旧 | 插件接管 files kind,宿主自己的 watch 覆盖不到 |
fs-watch.spec.ts 5 例 |
第 6 条是上一轮自己引入的回归,本次一并修掉:openInSidebar 只认领声明了 urlTarget 的链接,其余一律放行给宿主(DSH 0.1.7 起目的地由用户设置 linkOpening + 宿主决定),认领成功但目标不可用时 window.open(..., 'noopener,noreferrer') 兜底。
4. 取舍(用户拍板,逐条记录)
| 议题 | 选择 | 代价 |
|---|---|---|
| 支持线 | 只支持 ^0.1.7-alpha.1,不写兼容层 |
0.1.6 及更早用户停在 v0.19.1 |
| 发版 | 0.21.0-alpha.1,dist-tag alpha |
npm latest 仍是 0.19.1,新用户默认装不到 |
| 设置架构 | 迁到 entry-config 模型 + 自己做 legacy 导入 | 约 60 行新增,换回「用户设置不丢」 |
| 只读预览 | 让出 image / pdf / 电子表格 / Office 给内置 | 插件设置页少 3 行 viewer 开关;换来宿主的 Office→PDF、表格 worker、缩放 |
| 文件树 | 继续接管 + 本次实现目录 watch | 新增宿主 WS 路由 + 客户端订阅(约 300 行) |
| 外链 | 收敛为「只认领 urlTarget」 | 删掉 3 个偏好键(含 20 份词典 key) |
| 视觉 | 尺寸钉回 14,StateDot 跟随宿主新观感 |
与宿主其他进行中状态一致,少一处硬编码 |
保留在插件侧的三件(内置做不了的):Markdown 自带渲染器、HTML 沙箱预览(htmlViewerNoSandbox / htmlViewerDefaultUnsafe 宿主没有)、以及 code catch-all 的可编辑 + 保存能力。未知二进制(.zip / .wasm)仍走 code 认领 → 宿主 fsRead 判 binary → head 重匹配无 sniffer → EditorHost.tsx 的 binary 兜底渲染下载面板,功能不回归(builtins.spec.ts 用 planFsReadOutcome 把这条链钉住)。
5. 落地偏差(与计划的差异,逐条说明)
MessageSourceMap模块增强是计划外的必需品。计划只写了「改 kind 值」,实测仅改值会留下TS2322:0.1.7 把消息 source 改成合并可扩展的封闭联合,没有共享 catch-all。按上游dsh-time-context/dsh-tmux-context的同款接缝在src/sidechat-routes.ts里加了declare module '@deepseek-ai/dsh-llm'。- 图标改名范围比侦察报告小:报告说 39 个值符号里 26 个消失,实际要做改名的是 26 个(
IconProps是类型,13 个是插件自绘 glyph)。 ui-primitives的裸 import 闭包比报告深一层:报告给的是 2 个@deepseek-ai包,实际还要补zustand/immer(第二层)。这是交叉验证阶段证伪的 8 条之一。setSubagentCatalogOpen是「删除」而不是「替代」:计划预期有替代 API,实际 0.1.7 改成全量加载投影,那套机制整体不需要了。jobs.list是计划外的新路由:计划里只写了「改数据源」,实际旧的 jobs 镜像在 0.1.7 没有任何替代,只能自己开路由。exchangeLaunchCookie换成 Playwright request context:计划里列为「已知 e2e 阻塞」,落地时确认宿主静态 fallback 对纯 Node 的 GET 回 空体 405 且无Set-Cookie(0.1.5-rc.2 与 0.1.7-alpha.1 都复现),改用request.newContext()+maxRedirects: 0。- schemastery 必须换成 DSH 的构建(计划里标为「未验证」的风险,真机证实为必须):原计划认为「宿主只鸭子判定
meta.volatile,不必换依赖」。真机上settings.update返回 200、revision递增,但describe().value仍是旧值——写入被静默丢弃。根因在 DSH 的 schemastery 构建:它在解析期把 volatile 字段包成 cosmokitVolatile引用,Loader 的_commitVolatile提交的正是那些引用;公开的schemastery包只设标记、产普通值,于是「提交」无事可做。附带第二个坑:.volatile()经extra()返回副本,写成for (const f of ...) f.volatile()会丢掉标记,宿主随即报Plugin entry "better-sidebar" has no volatile fields。 tests/browser-globals.ts的修复不在原计划里:这是「跑起来才发现」的阻塞,由执行子代理用 HEAD 干净 worktree 复现归因后修的。- README/AGENTS 里「v0.20.0 已是 npm latest」的表述是错的:实测 npm
latest是0.19.1,0.20.0 从未发布。文档已按事实改写。
6. 验证证据
门禁(见本仓库 CI:plugin-mount 用真实 0.1.7-alpha.1 scratch profile 跑 Playwright 无头渲染):
pnpm peers check干净;pnpm typecheck/pnpm lint/pnpm check:consumer-types通过。pnpm test全绿(含本次新增的fs-watch.spec.ts、primitives-exports.spec.ts,以及smoke.spec.ts的两条 legacy 迁移用例)。pnpm build只产出client-editor.js/client-mermaid.js/client-locale.js。pnpm test:mount在真实@deepseek-ai/dsh@0.1.7-alpha.1上通过。
子代理的三处反证(比正向通过更有说服力):
- tool 结果解析:把新形状分支改回旧行为 → 16 failed / 88 passed,4 条真实生产者 round-trip 全挂、jobs 回放 5 条挂;恢复后 104 全绿。
- 让出的预览格式:
builtins.spec.ts用 26 个扩展名逐条断言editor不认领,同时断言md/html/ 代码扩展名仍然认领。 - 链接接管:新增用例断言「未命中
urlTarget时defaultPrevented === false且不调用任何打开函数」,以及「命中但被禁用时走window.open兜底」。
7. 真机升级经验(把 3080 的 web 实例从 0.1.5-rc.2 升到 0.1.7-alpha.1)
这段是本仓库「下一次升 DSH 时先读这里」的部分——四条都不是插件代码的问题,但都会让升级看起来像插件坏了。
- profile 的解析层会留着上一代的痕迹。
$DSH_HOME/profiles/node_modules/@deepseek-ai/下曾有 240 个指向旧 npx 缓存(~/.npm/_npx/c40503fdf38a82ea,即 0.1.5-rc.2)的符号链接——那是 0.1.5 的 fallback 机制,而 0.1.7 已把它换成进程内 runtime interception,既不更新也不清理这些链接。结果是 0.1.5 的包在世界里占着名字,settings插件直接TypeError: this.load is not a function起不来。清掉该目录即可(已留profiles/node_modules.bak-<stamp>-legacy-links.txt记录每条链接的原目标)。 - profile 里会有一个陈旧的
@deepseek-ai/dsh-settings@0.0.1-rc.1影子包:一个早已被禁用的第三方插件声明了^0.0.1-rc.1peer,pnpm 就把整张图解析到那个远古版本,而它会盖住宿主的 settings 服务。修法是在profiles/web/pnpm-workspace.yaml加overrides:把它钉到宿主版本(pnpm 11 已不再读 package.json 的pnpm.overrides,写了会静默忽略并只打一行 WARN)。 dsh plugin --profile web install会短路:即使node_modules已被删掉、tarball 内容已变,它仍报 "Already up to date" 而什么都不装(--force也一样)。改依赖后请直接在 profile 目录跑pnpm install。disabled-plugins.json在 0.1.7 是死文件(全树git grep disabled-plugins零命中)。禁用 bundle 现在只能改dsh.profile.bundles;保留dependencies里的声明,重新启用就是一行的事。
顺带修掉一个真实的升级阻塞:pm2 的 dsh-web 曾经重启 22321 次——一个上一轮会话遗留的游离进程占着 3080,pm2 的实例每次启动都 EADDRINUSE(错误日志涨到 121 MB)。定向 kill 掉占端口那个进程、改完版本再 pm2 restart 即恢复。
插件侧在真机上暴露的一个真 bug(已修,见 99892b2):一次性 legacy 设置迁移从没跑过。它在 ctx.inject(['settings'], …) 回调里启动,而那个回调在 settings 服务出现的瞬间就触发——此时 Loader 还在挂载各行,describe() 里还没有本插件那一行,于是查找返回 undefined、迁移以「no form」静默收场。上游自己的迁移会等 loader.await(),现在照做。这也是为什么所有早退分支都必须可观测:迁移现在返回具名 outcome 并由调用方记录,否则这类「什么都不发生」永远查不出来。