Files
apes-sidebar/docs/plans/2026-09-22-dsh-0.1.7-alpha.1-adaptation.md
T
Menghuan1918 ab2246da47 chore(release): cut v0.21.1 as the stable adapter for DSH 0.1.7-rc.1
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.
2026-09-23 23:58:59 +08:00

20 KiB
Raw Blame History

DSH 0.1.7-alpha.1 适配记录

适配对象:dsh-better-sidebar v0.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)。

三条纪律贯穿全程:

  1. 结论必须带证据:每条破坏都给出 git show <tag>:<path> / 实测命令与行号,不采信记忆。
  2. 区分「硬报错」与「静默失效」:后者的代价高得多——本版一共 6 处静默失效(见 §3)。
  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 字段包成 cosmokit Volatile 引用,而 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 处替换。

两处容易踩空的地方:

  1. 不能全局替换:src/client/icons.tsx 里有 13 个插件自绘的同风格 glyph(IconImageOutline16 / IconVscode16 …)。改名集合是从「import ... from '@deepseek-ai/dsh-client-ui-primitives' 的具名列表 ∩ 已不存在于该包」算出来的,机械替换 26 个符号,13 个自绘 glyph 原样保留。
  2. 失败模式是 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/cordis peer ^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'),缺它会让任何 import service.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. 落地偏差(与计划的差异,逐条说明)

  1. 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'。
  2. 图标改名范围比侦察报告小:报告说 39 个值符号里 26 个消失,实际要做改名的是 26 个(IconProps 是类型,13 个是插件自绘 glyph)。
  3. ui-primitives 的裸 import 闭包比报告深一层:报告给的是 2 个 @deepseek-ai 包,实际还要补 zustand / immer(第二层)。这是交叉验证阶段证伪的 8 条之一。
  4. setSubagentCatalogOpen 是「删除」而不是「替代」:计划预期有替代 API,实际 0.1.7 改成全量加载投影,那套机制整体不需要了。
  5. jobs.list 是计划外的新路由:计划里只写了「改数据源」,实际旧的 jobs 镜像在 0.1.7 没有任何替代,只能自己开路由。
  6. 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。
  7. schemastery 必须换成 DSH 的构建(计划里标为「未验证」的风险,真机证实为必须):原计划认为「宿主只鸭子判定 meta.volatile,不必换依赖」。真机上 settings.update 返回 200、revision 递增,但 describe().value 仍是旧值——写入被静默丢弃。根因在 DSH 的 schemastery 构建:它在解析期把 volatile 字段包成 cosmokit Volatile 引用,Loader 的 _commitVolatile 提交的正是那些引用;公开的 schemastery 包只设标记、产普通值,于是「提交」无事可做。附带第二个坑:.volatile() 经 extra() 返回副本,写成 for (const f of ...) f.volatile() 会丢掉标记,宿主随即报 Plugin entry "better-sidebar" has no volatile fields。
  8. tests/browser-globals.ts 的修复不在原计划里:这是「跑起来才发现」的阻塞,由执行子代理用 HEAD 干净 worktree 复现归因后修的。
  9. 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 上通过。

子代理的三处反证(比正向通过更有说服力):

  1. tool 结果解析:把新形状分支改回旧行为 → 16 failed / 88 passed,4 条真实生产者 round-trip 全挂、jobs 回放 5 条挂;恢复后 104 全绿。
  2. 让出的预览格式:builtins.spec.ts 用 26 个扩展名逐条断言 editor 不认领,同时断言 md / html / 代码扩展名仍然认领。
  3. 链接接管:新增用例断言「未命中 urlTarget 时 defaultPrevented === false 且不调用任何打开函数」,以及「命中但被禁用时走 window.open 兜底」。

7. 真机升级经验(把 3080 的 web 实例从 0.1.5-rc.2 升到 0.1.7-alpha.1)

这段是本仓库「下一次升 DSH 时先读这里」的部分——四条都不是插件代码的问题,但都会让升级看起来像插件坏了。

  1. 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 记录每条链接的原目标)。
  2. profile 里会有一个陈旧的 @deepseek-ai/dsh-settings@0.0.1-rc.1 影子包:一个早已被禁用的第三方插件声明了 ^0.0.1-rc.1 peer,pnpm 就把整张图解析到那个远古版本,而它会盖住宿主的 settings 服务。修法是在 profiles/web/pnpm-workspace.yaml 加 overrides: 把它钉到宿主版本(pnpm 11 已不再读 package.json 的 pnpm.overrides,写了会静默忽略并只打一行 WARN)。
  3. dsh plugin --profile web install 会短路:即使 node_modules 已被删掉、tarball 内容已变,它仍报 "Already up to date" 而什么都不装(--force 也一样)。改依赖后请直接在 profile 目录跑 pnpm install。
  4. 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 并由调用方记录,否则这类「什么都不发生」永远查不出来。