docs(plans): add the DSH 0.1.5-rc.2 adaptation and CI-failure plan
This commit is contained in:
Menghuan1918
@@ -0,0 +1,95 @@
|
||||
# DSH 0.1.5-rc.2 适配（v0.19.1 基线）+ CI 三类失败修复
|
||||
|
||||
日期：2026-09-10（复核 2026-09-11） 分支：`feat/dsh-0.1.5-rc.2`
|
||||
|
||||
## 背景
|
||||
|
||||
DSH `dsh-v0.1.5-rc.1..dsh-v0.1.5-rc.2`（上游 4 个 commit / 300 个变更文件，npm 发布 2026-09-10T14:57Z，dist-tag **`next`**；`latest` 仍是 rc.1）是 0.1.5 线的第二个候选版。本计划记录该 delta、插件对它的结论（**无需任何运行时/类型层适配**，只推进钉版），以及同一时间窗内 `ci-windows` / `plugin-mount` 两个车道真实存在的三类 CI 失败与修法。上一版（rc.1）记录见 [2026-09-10-dsh-0.1.5-rc.1-adaptation.md](./2026-09-10-dsh-0.1.5-rc.1-adaptation.md)；仓库级适配要点同步到 [AGENTS.md](../../AGENTS.md) §2/§3。
|
||||
|
||||
## 上游 delta（rc.1 → rc.2，影响本插件的部分：无）
|
||||
|
||||
300 个文件里绝大多数是各包 `package.json` 的 `version` 单行改动（`1+1-`）。逐文件过完后的真实代码改动只有四处：
|
||||
|
||||
| # | 上游变更 | 文件 | 对插件的影响 |
|
||||
|---|---|---|---|
|
||||
| 1 | 消息反馈改为对称提交（弹窗、动作按钮、控制器、槽位、i18n） | `packages/client/ui-message-feedback/src/client/*` | 无——插件不注册反馈槽、不读该控制器 |
|
||||
| 2 | 产物卡片内边距与呈现微调 | `packages/client/ui-deliverables/src/client/*`、`ui-chat/src/client/chat/TurnTailNodeView.module.css` | 无——插件不消费这两个包的组件，也不做会话尾迹布局 |
|
||||
| 3 | `CodeFileIcon` 的 477 行内联 SVG 拆进新增的 `code-file-icon-artwork.ts`（另有 `.manifest.json` 记录设计导出摘要） | `packages/client/ui-primitives/src/CodeFileIcon.tsx` | 无——`CodeFileIcon` 的导出面与 props 未变，且插件**本来就不用它**（插件文件树用 `IconCodeOutline16`；`#611` 的文件图标主题还在 PR #594，未进 main） |
|
||||
| 4 | 其余全部为版本号 | 各 `package.json` | 无 |
|
||||
|
||||
**明确未变（不必再核）**：
|
||||
|
||||
- `packages/api/*`（session-controller / workspace-controller / gateway / remotes）、`packages/host/*`、`packages/session/*`、`packages/agent/*`——**零**变更；除 `packages/feedback/message-feedback/src/types.ts`（1 行）外**零**类型文件变更。
|
||||
- 斜杠 RPC 方言、一次性 token 鉴权、会话事件模型、`sidebarRight` / `sidebarRightTabs` 承载面、`SidebarRightGuideEntry.description` 的 ≤4 渲染规则：全部沿用 rc.1 结论。
|
||||
- `@deepseek-ai/dsh-client-ui-primitives` 仍不声明 `dependencies`（bundle 仍裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex`）——提升进 devDependencies 的那组包继续不得回退。
|
||||
|
||||
## 决策
|
||||
|
||||
- **peer 下限保持 `^0.1.5-rc.1` 不动**：rc.2 无契约变化，`^0.1.5-rc.1` 天然容纳它，rc.1 用户无需升级即可用新版插件。因此本版是**纯 patch 的 0.19.1**，只推进 devDependency 钉版、CI 挂载钉版与 `SIDEBAR_SERVICE_VERSION`。
|
||||
- **`engines.dsh` 保持 `>=0.1.5-rc.1`**：与 peer 下限同源（同一个支持范围，两处不能分叉）。
|
||||
- **CI 挂载车道钉 rc.2**：真机证据要落在最新版上；`latest` 仍是 rc.1 只是上游的发布节奏，与本插件支持范围无关。
|
||||
- **不为此版写运行时兼容层**：上游 delta 里没有本插件触达的面，写兼容层就是无据的复杂度。
|
||||
|
||||
## CI 三类失败（2026-09-09/10 窗口，60 次已完成 run 的取证）
|
||||
|
||||
窗口内 `ci-windows|Test` 失败 8 次、`plugin-mount|Install dsh CLI (pinned)` 失败 4 次。逐条读日志后归为三类，其中两类是**真实缺陷**、一类是**运维噪音**：
|
||||
|
||||
### A. Windows 真实超时（6/8 次 `ci-windows` 失败，主因）
|
||||
|
||||
- 证据：run `34494370187`、`34490215638`、`34459499945`（**3 次 attempt 全红**）、`34372999975`、`34322271074`、`34319666611` 均为 `Error: Test timed out in 5000ms`，位置 `tests/agent-pty.spec.ts:71:3` / `:106:3`；`tests/install-powershell.spec.ts:105:41` 的 `powershell.exe` 单测自身耗时 **12151ms** 后才超时。
|
||||
- 根因：`vitest.config.ts` 没有任何 `testTimeout` 配置（默认 5000ms），而这些 spec 每个用例都要真起一个 `PowerShell + ConPTY` 对；`tests/agent-pty.spec.ts` 的 `waitForTranscript` 默认预算**也**是 5000ms——内层轮询吃掉整个对外预算，结构上必然超时。
|
||||
- 修法（`tests/*.spec.ts` 两处）：`AgentPtyRegistry` 与 `PowerShell installer entry points` 两个 describe 显式 `{ timeout: 30_000 }`（vitest 4 支持的 describe 级选项，已实测生效）；`waitForTranscript` 默认降到 15s，**内层预算必须严格小于外层**。
|
||||
|
||||
### B. Windows worker 静默死亡（2 次，非确定性）
|
||||
|
||||
- 证据：run `34500290681`(295615abb)、`34448911025`(bbf953b8a) 报 `[vitest-pool]: Worker forks emitted error / Caused by: Error: Worker exited unexpectedly`（`Errors 1 error`），同一份日志里 `0 FAIL`、125 个文件全过；后者静默吞掉一个文件的 10 条结果。同一 commit `8ae527170` 的另一次 run 里 `ci-windows` 是**绿的** → 该步骤可证伪地非确定。
|
||||
- 归因（**推断，非确证**）：真起进程的 spec 有 5 个（`agent-pty` / `pty-deps` / `pty-helpers` / `install-powershell` / `smoke`），node-pty 的 ConPTY 辅助进程与冷启 `powershell.exe` 都绑定控制台，在默认**无界 fork 池**下并行抢占；本地 macOS 无法复现该模式，因此不做无证据的猜测性改动（不加 `retry`，不改默认 pool）。
|
||||
- 修法：`package.json` 新增 `test:windows`（`vitest run --maxWorkers=2`），`ci-windows` 的 `Test` 步骤改跑它——**只在 Windows CI 收敛并发，`pnpm test` 的本地语义不变**。若真实 Windows 结果仍复现，按"升级而非掩盖"的原则继续收敛（同 PR 内串行化这些 spec，仍不加 retry），并在 PR 中如实标注。
|
||||
|
||||
### C. `plugin-mount` 的 npm 安装失败（4 次：2× ETARGET + 2× OOM）
|
||||
|
||||
- 证据：run `34492160123` / `34491256626` 报 `npm error notarget No matching version found for @deepseek-ai/dsh-tool-bash-persistent@^0.1.5-rc.2` / `@deepseek-ai/dsh-sandbox-windows-acl@^0.1.5-rc.2`；run `34490912649` 先刷 **3062 条 ERESOLVE**、9 分钟后 `FATAL ERROR: Ineffective mark-compacts near heap limit` exit 134。同一机制在 2026-09-09 的 alpha 线也复现过一次（run `34363627184`，1808 条 ERESOLVE → OOM）；同期成功的安装是 `added 521 packages in 19s`、**0 条 ERESOLVE**。
|
||||
- 根因：**钉版并没有真的钉住**。`@deepseek-ai/dsh@0.1.5-rc.1` 的传递依赖声明为浮动 `^0.1.5-rc.1`，会被上游**分阶段发布**中的 rc.2 满足（rc.2 的 14:43–14:57 逐个包上线），于是 npm 组出 rc.1/rc.2 混合 peer 图 → 解析器爆炸（OOM），或对尚未发布的兄弟包硬报 ETARGET（两个 ETARGET 分别在该包上线前 5.5 分钟与 25 秒）。
|
||||
- 修法（`.github/workflows/ci.yml`）：钉一个**已完整发布**的 rc.2，并给 `npm install -g --legacy-peer-deps` + `NODE_OPTIONS=--max-old-space-size=4096`——跳过 peer 协商使安装与上游发布窗口解耦，堆给足覆盖 npm 在这个 ~520 包树上的最坏情况。**挂错版本树不会静默**：同车道的真机挂载冒烟会 boot 真实外壳，装错就红。
|
||||
- 顺带修掉一处过时注释（原文断言「rc.1 同时是 `latest` 与 `next`」——现在 `latest=rc.1`、`next=rc.2`）；这条注释正是浮动范围隐患长期不可见的来源。
|
||||
|
||||
## 改动清单（子系统级）
|
||||
|
||||
| 子系统 | 文件 | 变更 |
|
||||
|---|---|---|
|
||||
| 基线 | `package.json` | `version` → `0.19.1`；dsh-* **devDependencies** 全部钉 `0.1.5-rc.2`（含 `dsh-client-locale`，上游仍与 DSH 同 tuple 发版）；**peerDependencies 一律保持 `^0.1.5-rc.1`** |
|
||||
| 基线 | `pnpm-lock.yaml` | 锁文件对齐 rc.2 |
|
||||
| 基线 | `dsh.plugin.json` | `version` → `0.19.1`；`engines.dsh` 保持 `>=0.1.5-rc.1`（与 peer 下限同源） |
|
||||
| 基线 | `src/client/service.ts` | `SIDEBAR_SERVICE_VERSION` → `0.19.1`（`tests/service.spec.ts` 断言它 === `package.json` 的 version） |
|
||||
| CI | `.github/workflows/ci.yml` | mount 车道钉 `@deepseek-ai/dsh@0.1.5-rc.2` + `--legacy-peer-deps` + `NODE_OPTIONS`（C 类）；`ci-windows` 的 `Test` 改跑 `pnpm test:windows`（B 类）；注释同步事实 |
|
||||
| CI | `package.json` | 新增 `scripts.test:windows`（`vitest run --maxWorkers=2`） |
|
||||
| CI | `tests/agent-pty.spec.ts` | `AgentPtyRegistry` describe 显式 `{ timeout: 30_000 }`；`waitForTranscript` 默认预算 5000 → 15_000（A 类） |
|
||||
| CI | `tests/install-powershell.spec.ts` | `PowerShell installer entry points` describe 显式 `{ timeout: 30_000 }`（A 类） |
|
||||
| 文档 | `docs/plans/2026-09-10-dsh-0.1.5-rc.2-adaptation.md` | 本计划 |
|
||||
| 文档 | `AGENTS.md` | §2 CI 基线戳与 mount 车道说明、§3 标题/基线段（rc.2 仍无契约变化，只推进钉版） |
|
||||
| 文档 | `README.md` / `README_EN.md` | 支持版本徽章与说明、新增 `### v0.19.1` 段 |
|
||||
| 文档 | `docs/external-plugin-guide.md` | 顶部基线行 → v0.19.1 / DSH 0.1.5-rc.1+（已在 rc.2 上验证） |
|
||||
| 文档 | `tests/native-surface.spec.ts`、`tests/builtins.spec.ts`、`tests/e2e/mount.e2e.ts`、`src/client/service.ts`、`src/client/native/index.ts` | 注释里的 `DSH 0.1.5-rc.1` → `0.1.5-rc.1+`（同一行为在 rc.2 未变） |
|
||||
|
||||
## 验证
|
||||
|
||||
- **未执行**的门禁与真机步骤都留空，由主代理实施后回填（本文件不预填未经执行的结论）。
|
||||
|
||||
### 回填（主代理实测）
|
||||
|
||||
- **门禁（rc.2 钉版，macOS arm64）**：`pnpm install` 成功且锁文件对齐 rc.2；`pnpm peers check` = `No peer dependency issues found`；`pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 全绿；`pnpm test` = **126 files / 1312 passed / 9 skipped**（与 rc.1 基线同数，无新增 skip）。
|
||||
- **真机挂载冒烟（rc.2）**：`DSH_CMD` 指向 `npx -y --package @deepseek-ai/dsh@0.1.5-rc.2 dsh`；见"落地"节的实测计数。
|
||||
- **真实 Windows 收敛**：推分支后对 `ci-windows` 反复 `workflow_dispatch`，连续两次全绿为准；见"落地"节。
|
||||
- **本地 3080 真机**（DSH 0.1.5-rc.2 + 插件 0.19.1）：由用户人工验证；见"落地"节。
|
||||
|
||||
## 不做
|
||||
|
||||
- 不为 rc.2 写任何运行时/类型层兼容层（上游 delta 未触及本插件的面）。
|
||||
- 不把 peer 下限抬到 `^0.1.5-rc.2`（会无谓地把 rc.1 用户挡在上一版）。
|
||||
- 不为 B 类做无证据的猜测性改动：不加 vitest `retry`、不改默认 pool、不关掉真实 pty 测试。
|
||||
- 不改 DSH 源码（仓库硬约束 §1）；不改 `release.yml`（0.19.1 无 prerelease 后缀 → 自动发 `latest`，符合 patch 语义）。
|
||||
|
||||
## 落地
|
||||
|
||||
- PR：[#625](https://github.com/omdsh-dev/DSH-better-sidebar/pull/625)（`feat/dsh-0.1.5-rc.2`）。
|
||||
- 待回填：PR 三个 check 的结论、`test:mount` / `test:mount:aggregate` 通过数、3080 人工验证结果、发版情况。
|
||||
Reference in New Issue
Block a user