admin/dsh_shenxian
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
c25609c4c1b3755cdd297d3349d7ceb203b34e10
dsh_shenxian/dsh-server-docs/04-调整方案/90-dsh升级项目-0.1.2-rc.1到0.1.5-rc.1.md
T
admin 5ad755116e chore(docs): 文档库并入代码仓（R4 选 a）+ 索引/台账跟进 
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 一律写「远程服务器」。
2026-09-15 18:47:13 +08:00

182 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`**（npm `latest`；用户材料里插件 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（差异修复）待办清单
1. **univer fork**：放宽 7 个 peer 范围 → 重编 → 出 0.2.29（同时把 `dsh.client.inject` 保持在"页面实测可满足"的集合内）；
2. **判据脚本 / 平台代码**：适配 `__DSH_BOOT__` 新结构（核平台是否有解析点）；
3. **角色补丁**：逐项核 6 个禁用项包名在 0.1.5 的存在性（缺则补/改名）；
4. **清理**：`@softspark/dsh-file-preview` 退役（被原生取代）；
5. **DB / sessions / 平台自研插件**：尚未核（下一轮重点：`dshs.db` schema、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`（md5 `4f6ace5924649c86ff2c463c5d8b5264`）；
- **投放并验证**：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 兼容问题）**：
1. `workspace-scoped-picker` 首轮**不在页面清单** ⇒ 根因是它的 `cordis.patch.yml` **有意为空**（注释写明「本包的行由 **profile 层单点插入**」，避免 duplicate id 崩溃循环），而我只写了 `bundles` 没写行；
2. 补行后**启动失败**：`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 流程走完）；**回滚预案仍在位**；后续按官方节奏跟进（下次升级同样走这五阶段）。
Reference in new issue View Git Blame Copy Permalink