DSH 0.1.2-alpha 系列升级踩坑全记录（3 次升级全挂的完整根因分析 + 官方源码佐证）

[LiuJunheng]

内容由 AI 归纳编写。踩坑记录源自我们对绿色便携版（DeepSeekHarnessGreen）的持续升级维护时得出。所有症状与根因均已通过官方源码交叉验证，本文档不代表官方立场，供社区插件作者和升级用户参考。

绿色版启动器已把所有故障点的修复逻辑内置为自动化自愈流程，升级后自动冒烟验证、自动补 peer 依赖、自动注入 core bundles、自动重建依赖树，当前版本已完全适应 0.1.2-alpha.3。

---

总览

0.1.2-alpha 系列迭代节奏较快，四次升级遇到四种不同类型的启动/功能故障。共性是：不是某个插件不兼容，而是框架自身的契约在变，且 changelog 未标注为破坏性变更。

#	升级路径	故障性质	纯官方用户也会中	必挂程度
1	rc.7 → 0.1.2-alpha.1	pnpm peer 策略收紧 + 信任围栏改严	✅	🔴 有第三方插件=秒退
2	alpha.1 → alpha.2	useSession 快照重构 + BrowserAuth 强制认证	✅	🔴 社区插件静默失效；裸地址必 401
3	alpha.2 → alpha.3	框架不再自动注入 core bundles	✅	🔴 旧 profile 升级=全插件等服务

以下按时间顺序倒出每次故障的症状、根因、官方源码佐证和解决方案。

---

升级 1：rc.7 → 0.1.2-alpha.1（症状：服务秒退，退出码 1）

现象：升级后启动立即退出，server.log 里反复出现：

request for '@deepseek-ai/cordis' is not in cache
ERR_VM_MODULE_LINK_FAILURE: Failed to resolve module specifier "@deepseek-ai/cordis"

或者 403 /api 拒绝、局域网文件浏览 pickDirectory 不工作、会话记录 UUID 生成报错等。

根因：pnpm 工作区策略 + client-connection 信任围栏，两处同时收紧。

改动 1 — autoInstallPeers: false 导致 peer 依赖不装

新版 pnpm-workspace.yaml 把 autoInstallPeers 从 true 改成了 false。这意味着 @deepseek-ai/dsh-session 等框架包声明的 peer 依赖（@deepseek-ai/cordis、@deepseek-ai/dsh-scope、@deepseek-ai/dsh-invariants）不会再自动安装到 profile 的 node_modules。

插件 import { ... } from '@deepseek-ai/cordis' 时找不到包 → 整个插件树秒退。

修复：在 profile 的 package.json → dependencies 里显式声明这些 peer，版本号对齐核心版本（如 cordis@4.0.2、dsh-scope@0.1.2-alpha.2、dsh-invariants@0.1.2-alpha.2），然后 pnpm install --force --no-frozen-lockfile 重建依赖树。

改动 2 — Chrome 150+ /api 403（hostname → host 精确比较）

client-connection 的 isTrustedApiRequest() 函数，信任比较从 origin.hostname === hostUrl.hostname 改成了 origin.host === hostUrl.host。

问题：浏览器 Origin 不带端口（http://127.0.0.1），但 hostUrl.host 带端口（127.0.0.1:3080），精确比较永远不相等 → 全 /api 403。

触发条件：Chrome 150+ + 局域网 IP 访问 / 非标准端口。127.0.0.1 + 默认端口下 Chrome 仍会放行 loopback，不一定命中。

修复：patch client-connection 的 isTrustedApiRequest()，把比较改回 hostname 级别（忽略端口差异）。

改动 3 — trustedHosts 白名单收紧

host.pickDirectory 等特权 API 的信任校验，从「loopback 白名单」收紧到了显式 trustedHosts 配置。不在 trustedHosts 里的局域网地址，即使是同机不同网卡 IP，也会被拒绝。

改动 4 — crypto.randomUUID 在 http + 非回环 IP 不可用

randomUUID() 浏览器 API 要求 secure context（https 或 localhost）。http + 非回环 IP 下调用会抛 TypeError。部分插件用它生成会话 ID / 工作区标识 → 静默出错。

修复：前端注入一个基于 crypto.getRandomValues() 的 polyfill。

---

升级 2：alpha.1 → alpha.2（症状：消息行空了 + 裸地址 401）

两个症状同时出现：

1. 启动后插件管理正常，但消息行的「本次 token」一行变成空白——undefined 或者直接不渲染；
2. 浏览器直接访问 http://127.0.0.1:3080/ 返回 401，提示 dsh web authentication required。

根因：两个独立的框架层改动撞一起了。

改动 1 — 会话快照重构（useSession → useChat）

0.1.2 把 useSession 的返回值从「整包会话」拆成了两层：

// rc.6 / alpha.1 之前
useSession(s => s.nodes)           // 直接拿 ConversationSnapshot
                                   // s.nodes = ConversationNode[]

// 0.1.2-alpha.2+
useSession(s => s)                 // 只返回 SessionSnapshot（生命周期字段：queue/running/openState/...）
                                   // 没有 nodes 了！
useChat(s => s.legacy.nodes)       // 聊天数据改由新 hook 提供
                                   // ChatSnapshot.legacy.nodes = ConversationNode[]

旧插件写 useSession(s => s.nodes) → 新版 s.nodes === undefined → 整个 UI 静默拿不到数据。不是报错，是悄悄空掉。排查时容易误以为是 token 计算或渲染逻辑的问题，实际是数据根本没传过来。

还有一个隐藏坑：聊天 UI 组件换包了。turnTail / assistant-actions / conversation.chat.node 这些插槽从 dsh-client-ui-conversation 迁到了 dsh-client-ui-chat。旧版 import 路径虽然还能 resolve（conversation 包没删），但里面的组件已经不导出了——同样不报错，静默没内容。

兼容写法（两端都能用）：

const data = useChat ? useChat(s => s) : useSession(s => s);
const nodes = data.legacy?.nodes     // 0.1.2+
           ?? data.nodes;            // rc.6 兜底

改动 2 — 强制浏览器认证（BrowserAuth）

alpha.2 新增了 BrowserAuth：首次访问需要启动时打印的一次性 ?token=<launchToken> 地址换 30 天 Cookie，裸地址直接 401。Config 里没有 enableAuth 开关——关掉只能 patch 源码的两个点：

• requestRejection()：去掉 browserAuth.isAuthenticated 检查；

• authorizeIndex()：提前 return true 跳过 token 校验。

注意：关掉的只是 401 那层，403 的 Host/Origin 围栏还在。局域网模式下 loopback 自动放行，所以 127.0.0.1 其实没差别；0.0.0.0 的话等于开了裸奔窗口——生产环境别关。

---

升级 3：alpha.2 → alpha.3（症状：全插件等 webServer）

现象：启动日志刷屏

plugin tree failed to load: dsh: 8 entries did not activate
  dsh-archive-purge waiting for services: webServer, llm
  dsh-sidebar-lite waiting for services: webServer, workspaceRegistry
  ... （所有插件都在等核心服务）

根因：框架不再自动注入 core bundles。

旧版本（包括 alpha.2）启动时，框架会自动把 @deepseek-ai/dsh-base（timer/llm/session 等基础服务）和 profile 层（dsh-web-app 提供 webServer、dsh-headless 提供 headless runner）隐式塞进 patch 栈。profile 的 dsh.profile.bundles 只写自己的插件就行。

alpha.3 起必须显式声明在 bundles 数组里。旧 profile 升级后 bundle 栈底层 = 空 → 所有插件依赖的核心服务不存在 → 全挂。

官方升级盲区（源码佐证）

官方 dsh-app-boot/lib/index.js 里有个 normalizeShippedProfile 函数试图自动兜底升级，但实际兜不住：

function normalizeShippedProfile(name, dir, manifest) {
    const bundles = manifest.dsh?.profile?.bundles;
    if (template === void 0 || bundles === void 0) return manifest;  // ① 直接跳过！
    
    const isRetiredTuple = installationOwned !== void 0 && sameBundles(bundles, installationOwned);
    if (!isRetiredTuple && !needsReloadDefault) return manifest;  // ② 也跳过！
    
    bundles: [...template.bundles]  // 只有命中才写回模板
}

三种旧版用户全被跳过：

旧版 profile 状态	normalize 行为	结果
bundles 字段不存在（undefined）	条件 ① 命中 → return	❌ core 缺失，全插件挂
bundles 是空数组 []	不是 retired tuple → return	❌ core 缺失，全插件挂
bundles = ["my-plugin"]（有自己装的插件）	不是 retired tuple → return	❌ core 缺失，全插件挂

全新安装不会中——PROFILE_TEMPLATES 正确声明了 core bundles（["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"]）。但升级用户 100% 中招，除非 bundles 恰好等于某个已退役元组。

修复方法

在 $DSH_HOME/profiles/web/package.json 的 dsh.profile.bundles 数组最前面加上 core bundle：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",      // ← 加在最前面（patch 栈底层）
        "@deepseek-ai/dsh-web-app",   // ← web profile 需要
        "dsh-my-awesome-plugin",
        // ... 你的其他插件
      ]
    }
  }
}

关键认知：core bundles 只需要在 dsh.profile.bundles 数组里出现即可，不需要写进 dependencies。它们在 runtime 的 node_modules 里已经装好了（框架自带），DSH 加载 bundle 时直接按名字在 runtime 的 @deepseek-ai/ 目录下找，不走 profile 的 node_modules。

---

给框架作者的建议

1. Changelog 请标注「需要用户改动的破坏性变更」。三次升级涉及的 peer 策略变化、useChat 重构、core bundle 显式声明，都是直接改插件/配置契约，但 changelog 只写了「refactored」「improved」，社区插件作者没感知，全部静默失效。

2. 自动注入 vs 显式声明最好给个过渡。alpha.3 从「自动注入」直接切到「必须显式」，中间没有 deprecated warning。如果框架能在启动时检测 bundles 缺失 core 并打印一个「你的 profile 缺少 XXX core bundle，将自动注入——但建议你显式声明」的 warning，就不会整挂一轮。

3. normalizeShippedProfile 的升级判断逻辑太窄。当前只处理 retired tuple 和 patchReload 缺省，没覆盖最常见的两种旧 profile（bundles undefined / 空数组）。建议加一条：如果 bundles 长度 < 模板 bundles 长度，自动补齐缺失项。

4. peer 依赖收紧最好有迁移提示。autoInstallPeers: false 后第一次启动时，框架可以扫描所有 @deepseek-ai/* 包的 peer 依赖，把缺失的列个 warning 打到 stderr，而不是等插件 import 时报 not in cache 后秒退。

---

社区插件作者快速自查清单（从 alpha.1 / rc.7 升上来的）

• peer 依赖补齐——profile dependencies 里有没有 cordis、dsh-scope、dsh-invariants？缺一个就秒退（alpha.1 起）

• 检查 useSession 返回值——还在读 s.nodes 吗？换成 useChat(s => s.legacy.nodes)（alpha.2 起）

• 检查 UI 组件 import——dsh-client-ui-conversation 里的 turnTail/assistant-actions 还能 resolve 吗？换 dsh-client-ui-chat（alpha.2 起）

• profile 的 dsh.profile.bundles 里有没有 @deepseek-ai/dsh-base？alpha.3+ 必须显式写

• 启动后裸地址 401？是 BrowserAuth，要么带 token 地址打开，要么 patch 关掉（不推荐）