admin
5ad755116e
1) dsh-server-docs/ 从工作区（原 E:\...\aliyun-dsh-server\dsh-server-docs）**整体并入本仓**，
保留目录名 ⇒ 仓库内 dsh-server-docs/... 的相对引用天然继续有效；旧目录（含其 .git）已归档到
工作区 _中间产物_待清理/，未随本提交带入。
2) .gitattributes：新增 `dsh-server-docs/** -text` —— 原文档库是 `* -text` + autocrlf=false，
必须保持纯 LF，否则会被本仓的 CRLF 规则翻掉。
3) 活引用里的绝对路径已全部改到新位置（docs 的 INDEX / README / scripts / skills + 用户级 skills
+ ~/.workbuddy/settings.json 的 hooks）；历史档案（04-调整方案/、archive/）按「只增不改」未动。
⚠️ hooks 路径改动需「完全重启会话」才生效（配置是会话启动快照）。
4) 交接单/T08：新增 §16「生产整体切换执行记录」（形态 / 落地动作 / **4 个只有真上线才暴露的真 bug** /
验收证据 / 回滚命令 / 残留项）；台账 T08 行 → 已完成并归档；03-路线图 §二 登记 T08 收尾项。
5) 统一称谓：**「本机」只指跑 WorkBuddy 的开发机**，47 / 106 一律写「远程服务器」。
13 KiB
13 KiB
90-dsh 升级项目：0.1.2-rc.1 → 0.1.5-rc.1（2026-09-14 立项）
- 日期：2026-09-14 ｜ 状态：🔄 进行中（阶段 1 通过 / 阶段 2 进行中 / 阶段 3–4 未开始）
- 触发：用户原话 ——「先把项目的 dsh 升级到这个版本」→ 追加「确认执行 迟早要跟进官方的版本，不可能一直用现在这个版本」
- 依据流程：档案 07 §三（版本升级流程五阶段；其红线第一条 =「不得直接在现网执行升级」）
TL;DR 目标版本 =
0.1.5-rc.1（npmlatest；用户材料里插件 peer 也是^0.1.5-rc.1，三方自洽）。 已在 test106 隔离完成阶段 1（起 profile 成功、默认 53 个客户端插件）。 阶段 2 关键结论：0.1.2→0.1.5 在 profile 布局 / CLI / lib 形态上同构，破坏面比预期小（详见评估表）； 我们自己的 univer 0.2.28 在 0.1.5 上：装得上（pnpm peer 容忍）、启动无报错、客户端 inject 差集为空 ⇒ 运行时可用。 唯一结构性差异：__DSH_BOOT__由顶层数组改为{rev, entries[], batches[]}。 生产（bt-server）本次零改动。
一、版本判定（无需猜测，证据三方自洽）
| 证据 | 值 |
|---|---|
npm dist-tags |
latest = 0.1.5-rc.1（next = 0.1.5-rc.2、alpha = 0.1.5-alpha.2） |
| 用户材料里插件的 peer 范围 | ^0.1.5-rc.1（如 dsh-client-ui-sidebar-documentpreview 系） |
| test106 机器上已装 | /usr/lib/node_modules/@deepseek-ai/dsh = 0.1.5-rc.1 |
（版本时间线：0.1.2-rc.1 = 09-03 → 0.1.3-alpha.2 = 09-07 → 0.1.5-alpha.1/2 = 09-08/09 → 0.1.5-rc.1/2 = 09-10）
二、阶段 1 · 隔离升级测试（✅ 通过）
- 环境：test106（OpenCloudOS 9.6 / glibc 2.38 / node 22.23.2 / npm 10.9.8）；未跑平台（无
dshs、无/var/lib/dshs） - 隔离方式：
HOME=DSH_HOME=/opt/upgrade-smoke/home、--port 41999⇒ 不影响任何现有环境 - 结果：profile 启动成功；页面需 token 换 cookie（
dsh-auth-*）后 200（27.7 KB） - 记录与复跑命令：test106
/opt/upgrade-smoke/测试记录.md
三、阶段 2 · 影响评估（🔄 进行中）
3.1 同构项（风险低，实测）
| 面 | 0.1.2-rc.1（生产） | 0.1.5-rc.1 | 判定 |
|---|---|---|---|
profile/package.json 结构 |
dsh.profile.{bundles, patchReload} |
同 | ✅ 平台解析路径不变 |
| profile 位置 | <DSH_HOME>/profiles/web |
同 | ✅ |
cordis.patch.yml |
顶层数组 + - insert: - id/name |
同（注释仍写 "top-level YAML array… insert lists；!!js 允许"） |
✅ 我们的角色补丁 / bundle patch 写法兼容 |
lib 形态 |
带 hash 单文件（dump-config-*.js/plugin-*.js）+ lib/bin.js |
同 | ✅ 平台若按 lib/bin.js 调 CLI 不受影响 |
dsh 可执行 |
/usr/local/bin/dsh → …/lib/bin.js 软链 |
同（test106 在 /usr/lib） |
✅ 档案 88 的"解软链探测"继续有效 |
| CLI 顶层 | --profile / --patch / -V |
同，且新增 dsh plugin 子命令 |
✅ 新增不破坏既有 |
3.2 差异项（需处置，实测）
| # | 差异 | 影响 | 处置 |
|---|---|---|---|
| 1 | __DSH_BOOT__ 结构变更：0.1.2 顶层数组/modules → 0.1.5 {rev, entries[], batches[]} |
客户端消费方 + 我们的判据脚本（按旧结构解析会误判"行不存在" —— 本次就误判过一次） | 更新判据脚本解析；平台代码需核是否解析它 |
| 2 | dsh plugin add 在带 pnpm-workspace.yaml 的 profile 上失败（ERR_PNPM_ADDING_TO_ROOT） |
仅影响使用该新子命令的人；平台投放通道不受影响（平台自调 pnpm add -w） |
记录；必要时平台侧改调 -w |
| 3 | 包总数 213 → 240（+27）；默认客户端插件 46 → 53 | 新增能力（见 3.3）；也可能带来新的默认启用项与角色补丁冲突 | 逐项核角色补丁 6 个禁用项在 0.1.5 是否仍存在（ui-cordis/hmr 初查仍在 ✓） |
| 4 | 我们已装插件的 peer 精确锁 0.1.2-rc.1（univer fork ×7 包、@softspark/dsh-file-preview） |
平台兼容预检会判 incompatible（dep-range）而拒绝投放；但运行时实测可用（见 3.4） |
univer fork 放宽 peer 范围（0.1.2-rc.1 || 0.1.5-rc.1）后重编 → 新版本；file-preview 可直接退役 |
| 5 | 0.1.5 的 dsh-client-ui-sidebar-documentpreview 默认下发（inject 已满足） |
与已装的 @softspark/dsh-file-preview 功能重叠 |
退役后者（少一个第三方依赖） |
3.3 升级收益（实测）
| 收益 | 证据 |
|---|---|
| 原生侧栏文档预览（Markdown / 代码 / 纯文本 / PDF / HTML / 图片） | dsh-client-ui-sidebar-documentpreview 在 53 个默认客户端插件里，inject = api-gateway / api-workspace-files / sidebar-right / ui-layout / ui-session（全部满足） |
| Office 预览有官方扩展点 | documentPreviews 注册表存在于该包（ctx.documentPreviews.register(...)）⇒ 可自研注册 xlsx/docx 渲染器 |
| better-sidebar 那批插件变可用 | dsh-client-ui-sidebar-right ✅ 默认下发（0.1.2 无 ⇒ 之前是硬拦路虎） |
| 产出文件 chips 机制不变 | dsh-client-ui-deliverables ✅ 仍在（服务器上仍只能走"预览"，"用默认应用打开"依旧 nativeUnavailable） |
3.4 我们插件的实测装载（最关键的硬数据）
在 0.1.5-rc.1 隔离 profile 里装 [email protected]（pnpm add -w file:… + 写入 dsh.profile.bundles）：
| 检查 | 结果 |
|---|---|
| 安装 | ✅ 成功（pnpm 9 对 peer 冲突容忍，未失败） |
| 启动 | ✅ 无报错（日志仅 dsh web: …?token=…） |
| 客户端半边 | ✅ 页面清单出现 dsh-univer-office（相对干净 profile 的新增项就是它） |
| inject 差集（老坑判据） | ✅ 6 个 inject 全满足，差集为空 ⇒ 不会静默挂起 |
⇒ 结论：univer 在 0.1.5 上运行时可用；阻塞点只在平台兼容预检的 peer 范围（属可修的声明问题）。
四、阶段 3（差异修复）待办清单
- univer fork：放宽 7 个 peer 范围 → 重编 → 出 0.2.29（同时把
dsh.client.inject保持在"页面实测可满足"的集合内）； - 判据脚本 / 平台代码：适配
__DSH_BOOT__新结构（核平台是否有解析点）； - 角色补丁：逐项核 6 个禁用项包名在 0.1.5 的存在性（缺则补/改名）；
- 清理：
@softspark/dsh-file-preview退役（被原生取代）； - DB / sessions / 平台自研插件：尚未核（下一轮重点：
dshs.dbschema、session zstd 格式、@dsh-local/*的官方 API 依赖面）。
五、阶段 4（整体更新）—— 需用户确认
- 影响：全体用户（全局 dsh + 全部 profile + 全部实例重启）
- 前置：阶段 2 剩余项核完 + 阶段 3 修复完成 + 在 test106 跑通完整回归
- 回滚：
/opt/dsh/backups/+ profile 快照（档案 07 §三 阶段 5）
六、本次的纪律说明（生产零改动）
- 全程未触碰生产（bt-server）：只做只读比对 + 在 test106 隔离目录内操作；
- test106 上为测试装了 pnpm@9（测试机，与生产无关）；
- 冒烟进程均已停止；隔离目录保留（含测试记录）供下一轮继续。
追加（2026-09-14 20:0x · 阶段 2 收尾 + 阶段 3 首项完成 + 一处自我更正）
一、⚠️ 更正 3.2 差异项第 1 条（重要，防误导后续修复）
原文写的「__DSH_BOOT__ 结构变更：0.1.2 顶层数组 → 0.1.5 {rev, entries[], batches[]}」是错的。
实测证据：在生产（0.1.2-rc.1）页面上按 entries 解析成功——顶层键同样是 ['rev','entries','batches']，行数 47。
⇒ 两版的 boot 结构同构；我先前的"差异"来自我自己的解析正则过时（只在新结构上试通过），不是版本差异。
⇒ "结构性差异"归零：0.1.2 → 0.1.5 在 profile 布局 / patch / CLI / lib 形态 / boot 结构上全部同构。
二、阶段 2 收尾（剩余未知项已核完）
| 待核项 | 结论 |
|---|---|
| 角色补丁 6 个禁用项包名在 0.1.5 是否存在 | ✅ 6/6 全部存在（ui-settings-models / -settings-plugins / -settings-plugin-inventory / ui-cordis / dsh-client-hmr / dsh-host-directory-picker-auto）⇒ 角色补丁不用改 |
| 平台自研插件的 client inject 在 0.1.5 是否可满足 | ✅ business-plugins / portal-entry 只 inject dsh-client-ui-settings-general（在 ✓）、workspace-scoped-picker inject [] ⇒ 不会挂 |
dsh-plugin-mcn-suite |
⚠️ inject 含 @deepseek-ai/dsh-client-runtime（0.1.2 与 0.1.5 都没有）⇒ 它的浏览器半边本来就挂（既有问题，与升级无关） |
三、阶段 3 · 首项完成：univer fork 放宽 peer → 0.2.29（已投放）
- 改动：7 个
@deepseek-ai/dsh-*peer 由0.1.1-rc.2 || 0.1.2-rc.1追加|| 0.1.5-rc.1（原先不是精确锁 —— 早先被预检拒的是@huiliyi37/dsh-office，记混过一次）； - 构建：
pnpm pack→dsh-univer-office-0.2.29.tgz（md54f6ace5924649c86ff2c463c5d8b5264）； - 投放并验证：admin 导入候选池 ⇒
compat.level = ok（放宽后的范围被认可，将来 0.1.5 也会 ok）⇒ 停用/启用 ⇒ 实装 0.2.29 ⇒ 页面 univer 行 inject 差集 = 无 ⇒ 实例 active； - 对现有 0.1.2 生产零行为变化（只改声明）。
四、阶段 3 剩余待办
| # | 项 | 状态 |
|---|---|---|
| 1 | univer fork 放宽 peer → 0.2.29 | ✅ 完成并投放 |
| 2 | __DSH_BOOT__ 适配 |
✅ 无需适配（两版同构；更正后归零） |
| 3 | 角色补丁 6 项核对 | ✅ 无需改动（6/6 存在） |
| 4 | @softspark/dsh-file-preview 退役 |
⏳ 等阶段 4 之后（现在退役 = 生产失去预览能力，因为 0.1.2 无原生预览）—— 顺序纪律 |
| 5 | dshs.db schema / session zstd 格式 / @dsh-local/* host 侧 API 依赖面 |
⏳ 未核（下一轮） |
追加（2026-09-14 19:5x · 阶段 3 完成 + 阶段 4 执行成功 —— 项目收口）
一、阶段 3 完整隔离回归（✅ 全绿）
在 test106 隔离 profile 里装平台全部 5 个插件（business-plugins 0.3.13 / portal-entry 0.5.2 / workspace-scoped-picker 0.1.5 / @softspark/dsh-file-preview 2.0.0 / univer 0.2.28）+ 对齐生产角色补丁：
| 检查 | 结果 |
|---|---|
| 启动 | ✅ 0 错误行 |
| 页面 | ✅ 200（28.9 KB），客户端插件 57 |
| 5 个插件 inject 差集 | ✅ 全部为"无"（含 picker） |
⚠️ 过程中两次自我纠错（都是"我的配置不全"，不是 0.1.5 兼容问题）：
workspace-scoped-picker首轮不在页面清单 ⇒ 根因是它的cordis.patch.yml有意为空（注释写明「本包的行由 profile 层单点插入」，避免 duplicate id 崩溃循环），而我只写了bundles没写行；- 补行后启动失败：
service "directoryPicker" has been registered—— 我们的 picker 与官方dsh-host-directory-picker-auto/browse抢同名服务；生产是靠角色补丁把官方那条disabled: true避让的，而我的隔离 profile 漏了这条。 ⇒ 补齐后全绿；并因此验证了一条关键前提：0.1.5 里官方那个行id: directory-picker/ 包名与生产角色补丁一致，⇒ 平台重建补丁仍有效。
二、阶段 4 · 整体更新（✅ 执行成功）
前置全部就位：备份 400 MB（/opt/dsh/backups/upgrade-0.1.5-20260914/：全局 dsh 0.1.2-rc.1 + 2 个 profile 快照 + DB + 回滚.md）· 隔离回归全绿 · univer 0.2.29 peer 已放宽。
| 步骤 | 结果 |
|---|---|
| 升级全局 dsh | ✅ npm i -g @deepseek-ai/[email protected]（added 23 / removed 25 / changed 499），dsh --version = 0.1.5-rc.1 |
| 重启平台 | ✅ dshs active |
| 平台 API | ✅ /api/auth/me、/api/plugins/business、/api/me/model-providers、/api/dsh/status 全 200 |
| 实例 | ✅ scope active；实例内 dsh = 0.1.5-rc.1；实例页 200（62.9 KB） |
| 收益到位 | ✅ 客户端插件 47 → 54，含 dsh-client-ui-sidebar-documentpreview（原生侧栏预览）· sidebar-right · deliverables |
| 平台 5 插件 | ✅ 全部 inject 差集"无"（含 picker） |
三、遗留与观察项
| # | 项 | 处置 |
|---|---|---|
| 1 | @softspark/dsh-file-preview 退役 |
⏸ 暂不退役（与原生预览功能重叠但无害；同一窗口不做两件事，观察一天再定） |
| 2 | 备份目录 400 MB | 保留至观察期结束（确认稳定后可删） |
| 3 | test106 隔离环境 | 保留 /opt/upgrade-smoke/（含测试记录）+ 测试机装了 pnpm@9（与生产无关） |
| 4 | mcn-suite 浏览器半边pre-existing 挂起 | 既有问题，不在本次范围 |
| 5 | 回滚材料 | /opt/dsh/backups/upgrade-0.1.5-20260914/回滚.md（含逐条命令） |
四、项目状态
✅ 阶段 1–4 全部完成（档案 07 流程走完）；回滚预案仍在位；后续按官方节奏跟进（下次升级同样走这五阶段）。