[0.1.5-alpha.1] 升级既有 profile 后 client combo 缺失新增 bundle 模块（ui-sidebar-* 404 / loaded without registering），全部 client 插件失效

[lhh010]

TL;DR (EN): after upgrading an existing npm-global profile from 0.1.3-alpha.2 to 0.1.5-alpha.1 on Windows, the client combo served by /plugins/??… omits the four NEW ui-sidebar-* bundle modules although the boot roster lists them — every client plugin fails with "loaded without registering", and chat file links throw sidebarRight: no registered tab type claims. Rollback to 0.1.3-alpha.2 restores everything. Full forensics below (Chinese).

---

环境 / Environment

项	值
OS	Windows 11（x64，非 WSL 内）
安装方式	npm i -g @deepseek-ai/dsh@0.1.5-alpha.1（npm 全局，非源码构建）
dsh 版本	0.1.5-alpha.1（dsh --version 确认）
升级前版本	0.1.3-alpha.2（npm 全局）
profile	既有 web profile（0.1.2/0.1.3 时代创建），含 6 个外部 client 插件（junction 直链仓库工作树）+ 1 个本地插件
Node	v24.14.1

现象 / Symptoms

升级到 0.1.5-alpha.1 并重启 dsh web 后：

1. 浏览器报 Failed to load plugins — failed to import loader entry 5d0bcba2 (@deepseek-ai/dsh-client-hmr): client-modules: bundle /plugins/??… loaded without registering "@deepseek-ai/dsh-client-hmr"，全部 60 个 client 插件不加载（含此前一直正常的外部插件）；
2. 点击聊天中的文件链接另弹 无法打开文件：sidebarRight: no registered tab type claims "dsh-resource://file/…"。

取证 / Evidence

在 0.1.5-alpha.1 运行中的宿主上按顺序做了如下只读取证：

1. boot roster 包含 sidebar 条目：__DSH_BOOT__ 清单（60 条）中有
   @deepseek-ai/dsh-client-ui-sidebar-right / -textpreview / -files / dsh-client-ui-sidebar；

2. npm 树内产物存在：
   …\npm\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai\dsh-client-ui-sidebar-right\lib\client.js（129 KB）、
   …dsh-client-ui-sidebar-textpreview\lib\client.js（29 KB）均在；

3. dsh-web-app bundle 声明完整：已安装的 dsh-web-app\cordis.patch.yml（L220–235）包含 4 个 ui-sidebar-* insert 行，package.json dependencies 亦声明这 4 个包；

4. 但 combo 路由对 sidebar 模块 404：

   GET /plugins/??@deepseek-ai/dsh-api-gateway/client.js&rev=<boot rev>          → 200（73 616 字节）
   GET /plugins/??@deepseek-ai/dsh-client-ui-sidebar-right/client.js&rev=<同 rev> → 404
   GET /plugins/??@deepseek-ai/dsh-client-ui-sidebar-textpreview/client.js&rev=<同 rev> → 404
   

5. 浏览器按完整清单请求 combo（60 个模块逗号拼接），响应字节中不含 sidebar 模块的注册代码 →
   __ModuleLoader__.load 从未为清单中靠后的条目调用 → 首个未注册条目（此处为 dsh-client-hmr，无辜）
   报 "loaded without registering"，整个 combo 的插件全部失效；

6. 附带效应：文件链接点击统一路由进 sidebarRight.openResource（0.1.5 移除了 Detail 面板），而
   ui-sidebar-textpreview 的 text 类型从未注册，于是所有文件链接点击都抛
   no registered tab type claims——符合源码注释 "an address no type will open is a wiring mistake" 的定位。

结论（怀疑方向）

boot roster 与 artifact/rev 注册表不一致：组合（compose）阶段把 0.1.5 新增的 web-app bundle insert 行
（4 个 ui-sidebar-*，均为本版新增模块）纳入了 roster，但 npm 发行树的 client artifact/rev 集里没有对应字节：

• 可能 A：构建期记录的 client artifact 集（234 artifacts）早于/漏于这 4 行；
• 可能 B：升级既有 profile 时，bundle 新增 insert 行未被并入组合或产物对账（npm 全局安装路径）。

无论哪种，roster 与可服务字节的差异目前是静默的——表现为无辜条目（hmr）背锅 + 全插件失效，而不是启动时 fail loud。

复现 / Reproduce

1. 在 0.1.2/0.1.3 时代的既有 web profile（npm 全局安装）上，npm i -g @deepseek-ai/dsh@0.1.5-alpha.1；
2. dsh web 重启，浏览器打开；
3. 观察 combo 加载失败；再点任意聊天文件链接观察第二个弹窗。

（同一 profile 上回退 npm i -g @deepseek-ai/dsh@0.1.3-alpha.2 后一切恢复正常。）

期望 / Expected

• boot roster 与可服务的 combo 字节一致：roster 声称存在的模块必须可服务；
• 不一致时启动阶段 fail loud（指名缺失的包），而不是浏览器端首个无辜条目背锅；
• 升级既有 profile 时，bundle 新增 insert 行的依赖应可被解析（或给出明确的迁移指引）。

临时缓解 / Workaround

回退 npm i -g @deepseek-ai/dsh@0.1.3-alpha.2 后恢复正常（六插件与宿主均正常）。

备注

• 另发现 @deepseek-ai/dsh-client-ui-open-in-app（同样是 0.1.5 新增行）在 combo 中是否可服务未单独验证；若同样缺失，说明是「新增行」级别的系统性遗漏而非 sidebar 特有；
• ui-sidebar-textpreview 的 text 类型定义（patterns: ['dsh-resource://file/**']、canOpen 基于 parseFileAddress）对 Windows 盘符 absolute/E:/… 地址解析正确，已单独验证，排除该因素。

[lhh010]

追加证据（0.1.5-alpha.2 实测，同一升级 profile）

升级到 0.1.5-alpha.2（npm 全局）并重启后，现象有变化，指向同一类根因（boot roster 与实际加载/服务不一致）：

1. ui-sidebar-right 已进入 boot roster（alpha.1 首启时缺失，重启后曾自愈；alpha.2 首启即在）；
2. ui-sidebar-textpreview 已被更名为 ui-sidebar-documentpreview（新包覆盖 Markdown/代码/HTML/PDF/图片预览）——roster 中旧名消失属正常；
3. documentpreview 的侧栏标签能正常打开（说明该模块已加载、text 类型的 claim 已通过——session 作用域地址）；
4. 但标签内容显示「文件资源服务不可用。」（meta.status === 'none'：useResource('file', …) 的元数据从未到达）——即 @deepseek-ai/dsh-api-workspace-files 的 client 资源提供方未注册或其 workspaceFiles.stat RPC 未送达；
5. 逐模块探针（62 个条目逐一 GET）：全部 200，零缺失——与 alpha.1 时的"部分模块 404"不同，alpha.2 的静态产物服务是完整的；
6. 其余全部插件（含 6 个外部插件）工作正常。

指向的结论

静态产物服务已恢复，但 api-workspace-files 的 client 资源提供方在浏览器端未生效（或其 stat RPC 未送达），
即"组合里存在但运行时未接管"的另一半问题。疑似升级 profile 的 client 组装/激活链仍有缺口
（对照：全新安装的 profile 预期正常——未测，无全新 profile 可对照）。

复现要点

• Windows 11，npm 全局 0.1.5-alpha.2，0.1.2/0.1.3 时代创建的既有 profile（含 6 个外部 client 插件 junction）；
• 点击会话工作区内文件的聊天链接 → 右侧 Sidebar 标签打开，内容区「文件资源服务不可用。」；
• 文件追踪插件的自身 RPC 读取同文件正常（对照）；
• F12 Console 无 documentpreview 相关红色报错（仅 paste-input fold skip 警告，属另一插件）。

[lhh010]

追加证据（0.1.5-rc.1 实测，同一升级 profile）

升级到 0.1.5-rc.1（npm 全局，0.1.5 系列首个候选版本）并重启后，文件资源读取仍然失败——问题跨越 alpha.1 → alpha.2 → rc.1 三个版本持续存在，不是升级一次性问题。

rc.1 轮次的增量排除

• 组合缺失已排除：web-app bundle 的 cordis.patch.yml 已包含 workspace-files 宿主行；曾尝试在 profile patch 手动 insert 同一 id，结果 Cordis 抛出 fatal boot crash（duplicate loader entry id），确认 bundle 层已提供、组合并不缺这个插件。
• 静态产物已排除：逐模块探针 62/62 HTTP 200（alpha.2 轮次已测，rc.1 轮次重启后同样正常）。
• 宿主端文件可读已排除：file-trace 插件自身的 RPC 读取同一文件正常（对照）。
• documentpreview 未加载已排除：标签能打开，claim/注册层工作正常。
• 结论仍指向：宿主端 WorkspaceFiles 服务的 RPC 端点在运行时未注册（或 Typert 网关未路由到它）——宿主进程内部的组合/注册缺口，插件侧无法触及。

对上游的建议

这个问题跨越三个版本持续存在，且「升级 profile」场景下必现。建议宿主在启动时加入 roster-vs-served-combo 一致性检查，或者在 RPC 端点未注册时提供具名错误（而非浏览器端显示笼统的「文件资源服务不可用」），避免插件侧误诊。

[lhh010]

跟进（0.1.6-alpha.2 复测）：文件预览整链仍失效，且全新 profile 也复现 —— 问题不止"升级既有 profile"

今天在 0.1.6-alpha.2 上做了与楼上同口径的取证，结论需要修正/加重：

现象：侧边栏文件树列目录正常（POST /api/workspaceFiles/list 200），但点击任意文件 → 预览面板「文件资源服务不可用」（resourceUnavailable 兜底），Network 无任何 workspaceFiles/stat / workspaceFiles.changes 请求；聊天文件链接同样打不开。

关键差异：这次不是升级态问题 —— dsh --profile webtest --from-default-profile web 建的全新干净 profile（零插件、零 junction、零历史 node_modules）同样复现。#623 时代"回退版本恢复/仅升级态损坏"的结论在 alpha.2 上不再成立，退化面更深了。

与 #623 取证口径的对照：

检查项	#623（0.1.5-alpha.1）	本次（0.1.6-alpha.2）
boot roster 含目标模块	有	有（dsh-api-workspace-files 等，inject 正确）
combo/单模块字节	404（roster 有、字节无）	200，15539 字节，含 resources.register 与 protocol: "file"
运行时实际激活	全部 client 插件失效（loud）	provider 静默未注册（无声报错，仅兜底文案）
表现	loaded without registering	useResource store status none →「文件资源服务不可用」

即：字节层面已经修好/对齐了，但 dsh-api-workspace-files client half 的 ctx.effect(() => ctx.resources.register({protocol:"file",...})) 在运行时从未执行。status none 在 dsh-client-resources 的 ResourceRegistry 里唯一来源就是 providerOf("file") === undefined，激活失败只进 snapshot.failures（页面诊断内部状态），控制台零输出。

附带线索：同构建 GET /api/changes.summary?sessionId=… → 404（dsh-client-ui-deliverables 的 changes 命名空间在网关无路由），疑似同一批 client half 激活/装配缺陷。

诉求（同楼上，加重）：roster 声称的 client half 若激活/apply 失败，必须指名包 fail loud；本次是"roster、字节、依赖图三对但激活不动"的第三种形态，建议官方在 client half 激活审计里补这一格。

（已同步评论到 dsh-external/issues#640 关联取证；两案合并归档均可。）

[lhh010]

跟进：0.1.6-alpha.2「文件资源服务不可用」的确切根因（非特殊 scheme 的 URL hostname 解析差异）

此前在本讨论反馈的 0.1.6-alpha.2 侧边栏文件预览「文件资源服务不可用」（dsh-external/issues#640 已有完整取证），现已定位到确切根因并本地验证修复，同步到这里供交叉归并：

根因：dsh-client-resources 的 protocolOf() 依赖 new URL(address).hostname 提取 dsh-resource://<protocol>/... 的协议段。dsh-resource: 是非特殊 scheme，其 authority/host 解析是实现相关行为——实测同一地址 dsh-resource://file/session/<id>/AGENTS.md：Node 24 与 Chrome 153 的 hostname 为 "file"，而 Edge 131 返回空串。受影响浏览器上 protocolOf 返回 undefined → provider 永远匹配不上 → 资源 store 停在 status:'none' → 预览落「文件资源服务不可用」，且 workspaceFiles/stat 请求都不发。

关键证据（插桩 ResourceRegistry.create()）：addr="dsh-resource://file/session/.../AGENTS.md" parsedProto=dsh-resource: parsedHost="" protocolOf=undefined providers=["subagentchat","plan","file"] —— provider 注册与模块激活全部正常，败在地址→协议解析。

最小修复：protocolOf 改为字符串解析（截 dsh-resource:// 后至 /?# 的段并小写化），不再依赖 URL.hostname。本地打补丁后原必现环境 E2E 验证通过（stat/read 正常发出、内容渲染）。

同模式缺陷：dsh-client-ui-subagent 的 parseSubagentChatAddress() 用 url.hostname 判别 dsh-resource://subagentchat/ 地址，同类浏览器上同样失效，建议一并修。

完整分析见 dsh-external/issues#640 最新评论（含三环境对照表与修复代码）。