workspace-groups-remote/vendor/dsh-remote-ssh/MAINTENANCE.md

1026 lines
114 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.

# dsh-remote-ssh 维护与发布手册(Maintainer Playbook)
> 本手册由维护会话于 2026-09-10 从 DSH 归档历史会话中提炼(session d5dc5130 主会话、
> 996c0822 工程师子会话等),并逐项在当前机器上验证通过。不含任何密钥。
## 0. 当前状态(已验证)
| 项目 | 状态 |
| --- | --- |
| 本地版本 / npm latest / GitHub main | **2.4.44**(2026-11-03 发布,内容:**2.4.43 复测收尾 —— 取消 / `remote_ssh_kill` 会终止远端进程组(issue #35)**)—— 复测确认 2.4.43 的停止键已秒级生效(`sleep 60` 6.06 s,旧版 60.05 s),但**只断开了本地 ssh**:远端命令继续跑完(`END` 在 turn 结束后才写日志、`ps` 里有孤儿),`timeoutMs` 超时同样只放弃等待。修法:池化会话建连先写探针 `printf '\002RSSHPID%s\002\n' "$$"`(先于任何排队命令),解析后**剥离标记**并记下远端 shell PID(真机确认 `PID=PGID=SID`);取消与 kill 用独立一次性通道 `kill -HUP -<pgid>`(4s 短超时、**不复用已取消的 signal**、与本地停稳并行);用 HUP 而非 TERM(`nohup`/`setsid` 存活);超时 / 断连不杀远端并写进文档。前序:2.4.43 协作式取消 + askpass ASCII、2.4.42 `git.history`、2.4.41 settings 代际(#34)、2.4.40 密码认证(PR #33)。npm `dist-tags.latest` / tag `v2.4.44` / GitHub Release(Latest)三者一致,commit `8dc37b8`(父 `d955025`)。npm tarball 2.4.44 shasum `463af7a60989caa04742521c00f1cfd1d505671d`(8 个文件 / 312,267 B / 解开 899,434 B);仓库 `lib/index.js` SHA256 `B6A6EC24EDC9BA078A3E783115B2DB088DAF3BF10274666691EDCE446D2AACEA`,客户端未改动(`lib/client.js` 仍为 `CE1770869AD5AFC9DD53A9F08F986F4742CBAE92B808C644D648AC1FF2289363`)。**桌面 profile 已 `pnpm add` 到 2.4.44**(装上的 `lib/index.js` 与仓库 SHA256 逐字节一致),**宿主仍未重启 → 运行中的进程仍是 2.4.41** |
| 仓库 | https://github.com/ZhangFengshun/dsh-remote-ssh(HTTPS,分支 main) |
| npm 账号 | `npm whoami` → `zhangfengshun` ✅ |
| gh CLI | v2.97.0,已登录 `ZhangFengshun`(keyring),scopes: admin:public_key, gist, read:org, repo |
| 发布可见性 | package.json `publishConfig.access = "public"` |
| GitHub Release | **v2.4.44 = Latest**。(2026-11-03 核对)有 tag 的 **42 个版本全部有 Release**(含 v2.4.35 – v2.4.44)。2026-10-16 补了 `v2.4.18`(当时只发了 npm、没打 tag):tag 指向 `3e65aa0`,产物 blob 与 npm 上 2.4.18 完全相同。npm 上另有 50 个更早版本从未打过 tag —— 不打算批量补(噪音大于价值),要补按 §3 的 `# 0c.` 走 |
| 文档(issue #21) | `~/.ssh/config` 的继承语义已按**代码**逐条写进两份 README 的故障排查表:导入 = 把 Host 块抄进连接配置;连接时以 profile 为准(总是 `-p <端口>` + `user@host`),只有 `keyPath` / `proxyJump` 留空才用 config 的值;导入侧只解析 `Host` 块(`Include` 递归)、含 `*`/`?` 的名字跳过、`Match` 块不解析 |
### 2.4.44 发布实据(2026-11-03,issue #35 复测收尾:取消 = 终止远端进程组)
**来源**:#35 报告者 `2026-11-03T05:38:26Z` 的复测:2.4.43 的取消已秒级生效(`sleep 60` → 6.06 s、`sleep 120` → 6.69 s;
取消后本地 ssh 无残留、下一条命令 0.9 s、远端没有重跑),但发现两点 ① **远端命令继续跑完**(`START`→`END` 跨 turn、
`ps` 可见孤儿,而本地 ssh 已消失)② **`timeoutMs` 被文档写成「超时=终止」**,实测超时后远端进程仍存活(`PPID=1`)。
**修法**:
- `CommandSession`:建连后先往 stdin 写 `printf '\002RSSHPID%s\002\n' "$$"`(早于任何排队命令);stdout 到达时 `_absorbPid()` 解析并
**从缓冲剥离标记**记进 `remotePid`;重连清空重探(防 pid 复用误杀)、远端非 bash 时缓冲 >8 KiB 即放弃;
标记用 `\002…\002` 包裹,不会和普通输出混淆。
- `hupRemoteGroup(p, pgid)`:`Number.isInteger` 严格校验(1 < pid ≤ `0x7fffffff`),走 `runRemote` 的**独立一次性连接**
执行 `kill -HUP -<pid> 2>/dev/null; true`,4 s 短超时、**不传 signal**、异常吞掉返回 false(best-effort)。
- `runPooled`:abort 分支 `Promise.all([settleWithin(execP, 3000), hupRemoteGroup(p, remotePgid)])` —— 两件事并行,
取消返回不被多等一个 RTT;PGID 在 `dropSession()` **之前**从会话对象取(`withTimeout` 的 `onTimeout` 已经关过一次会话);
超时分支**不加** HUP。
- `remote_ssh_kill`:单连接与 `all` 两个分支都在 `close` / `delete` 之前发起 HUP 并 await(内部 4 s 上限兜底)。
- 文档:`remote_ssh_exec` / `remote_ssh_kill` / `timeoutMs` 的工具描述 + 两份 README 三处(超时章节、工具表、排错表);
CHANGELOG 2.4.44。
**验证**:
- `tests/remote-hup.test.mjs`(**42 条**):探针逐字节断言(含双美元符)、标记解析/剥离、只探一次、重连重置、
超长缓冲放弃;`hupRemoteGroup` 短路/独立通道/短超时/不传 signal/失败吞掉;runPooled 与 kill 的接线顺序、
超时分支无 HUP;两份 README 语义断言;4 条变异负向控制。`tests/cancel.test.mjs` +8 条(94 条)。
- 真机 E2E `scripts/verify-remote-hup-group.mjs`(参数化、不含真实主机;真实 sshd + 真 bash):**7/7 通过** ——
`PID=PGID=SID`、断本地 ssh 后远端 `sleep` 存活、`kill -HUP -<pgid>` 后前台 `sleep` 消失、`nohup` 后台任务存活。
- 全量 **42 文件 / 2276 断言 / 0 失败**(本机)。
**发布三件套核对**:npm `latest` = 2.4.44(shasum `463af7a60989caa04742521c00f1cfd1d505671d`,8 文件 / 312,267 B / 解开 899,434 B);
tag `v2.4.44` → `8dc37b8`;GitHub Release `v2.4.44` = **Latest**(`2026-11-03T08:30:17Z`)。issue 回帖 `issuecomment-6598951735`。
**CI 插曲(记一笔)**:发布提交 `8dc37b8` 的 `tests` run `41603691475` **报红** —— 新测试把仓库根写死成 `F:/MyAIProject/...`,
在 Actions 上直接 **CRASH**(汇总显示 `[CRASH]`、**不计入「失败」计数**,只看「结果: 0 失败」会漏掉)。修复提交 `4f013c3`
改成 `fileURLToPath(new URL('..', import.meta.url))`,run `41604152468` **success**。npm 上的 2.4.44 产物不受影响(只改测试文件,`lib/` 未变)。
**桌面 profile**:已 `pnpm add @zhangfengshun/dsh-remote-ssh@2.4.44`,profile 内 `lib/index.js` SHA256 与仓库一致;
**宿主未重启,运行中的仍是 2.4.41**(重启要 GUI 里点「立即重启」;非 UI 的 restart 接口返回 401)。
**未做(诚实记录)**:① 没有在 GUI 里真按一次停止键(需要运行中宿主 + 真实 profile);② `remote_ssh_sync` / `remote_ssh_push`
的远端 `tar` 未单独发 HUP(管道两端终止后远端 tar 会因 EPIPE 自行退出);③ 没有中文用户名的 Windows 机器做 GUI E2E(#36 仍用 `ssh-keygen` 通路)。
### 2.4.43 发布实据(2026-11-03,issue #35 取消 + issue #36 askpass)
**两项修复同版本发布**(2.4.43 此前未发布过任何正式产物):
**A. issue #35 —— 协作式取消(停止键生效)**
现象/根因:DSH 的取消是**协作式**的(注册表不与工具 promise 竞速,工具必须自己观察 `exec.signal` 并在自有工作停稳后返回);2.4.42 及以前全文件
`exec.signal` 出现 **0 次** → 停止键只把 turn 标成取消,远端命令照跑;`timeoutMs: 0`(长任务推荐用法)时等待无上限,而兜底
`remote_ssh_kill` 本身也是一次工具调用,同一 turn 卡住时按不到。报告者用 `sleep 60` 实测:连按 4 次停止键仍耗 60.053 s。
修法:`withTimeout(promise, ms, label, onTimeout, signal)`(取消 → `isAbort`;**先 reject 再 onTimeout**);`runRemote` / `runPooled`
增尾参 `signal`(预取消**不建连**;取消后丢弃会话/`terminate` 并等 ≤3 s 停稳;**绝不回退一次性连接重跑**);`runTarPipe`(sync/push)
支持取消;`toolContext.signal` + `signalRunner` 覆盖 11 个走 SSH 的工具;`isAbort` 经 `normExec` / `stripAbort` 净化。
验证:`tests/cancel.test.mjs` **86 条**(含 3 条变异负向控制:删 abort 分支 / 把 ls 改回裸 runner 必须变红)。
**B. issue #36 —— Windows 密码认证 askpass 落点**
真机复现(本机 `OpenSSH_for_Windows_9.5p2`,与报告者同版本,不需要远端 sshd):`ssh-keygen -p` 改口令时由 OpenSSH 亲自调用 askpass,
同一份**字节完全相同**的助手脚本、只改 `SSH_ASKPASS` 路径 —— 中文目录 → `CreateProcessW failed error:2` +
`ssh_askpass: posix_spawnp: No such file or directory`;纯 ASCII 目录 → exit 0 `Your identification has been saved with the new passphrase.`。
修法:`ensureWindowsAskpass()` 按 `ProgramData\dsh-remote-ssh` → `Public\dsh-remote-ssh` → 用户目录(仅整条路径 ASCII 时)回退,
落盘前 `/^[\x20-\x7E]+$/` 校验,文件名取 `sha256(home)` 前 12 位;`DSH_REMOTE_SSH_ASKPASS` 可覆盖(非 ASCII 值忽略并回退);
全失败时 `sshArgv()` **抛明确错误**;`sshErrorHint(text, p)` 按认证方式归因(先识别 `ssh_askpass` 证据,密码连接不再输出 keyPath 清单,
key 连接行为不变)。
验证:`tests/askpass-ascii.test.mjs` **39 条**(含真机 E2E 三条:中文路径必失败 → 同字节 ASCII 成功 → 插件落点被真实 `ssh-keygen` 接受);
`tests/password-auth.test.mjs` 改为新落点(**29 条**)。
**发布三件套核对**:npm `latest` = **2.4.43**(shasum `8ed2a94f82f69b40902ec17281e930cd3b1dff23`,8 文件 / 308,845 B / 解开 890,493 B);
tag `v2.4.43` → `7713cbe`;GitHub Release `v2.4.43` = **Latest**(`2026-11-03T01:27:13Z`)。CI:`tests` run `41559514943` success
(`headSha 7713cbe`,41 文件 / 2226 断言);`upstream-drift` 本周无新跑(未改端点)。issue 回帖:#35 `issuecomment-6593032666`、#36 `issuecomment-6593033147`。
**桌面 profile**:`pnpm add @zhangfengshun/dsh-remote-ssh@2.4.43` 成功(`minimumReleaseAgeExclude` 里已有本包,不受 24 h 窗口限制),
`node_modules/.../lib/index.js` SHA256 与仓库一致;**宿主未重启 → 运行中的进程仍是 2.4.41**(重启必须在 GUI 里点「立即重启」;非 UI 的 restart 接口返回 401)。
**未做(诚实记录)**:① GUI 里真按停止键的端到端验证未做(需真实 profile + 运行中的宿主),当前证据是「真实函数 + 可编排假会话/假管道」的沙箱;
② 手头没有中文用户名的 Windows 机器,「设置 → 远程连接 → 测试连接」的真实 GUI 流程未做,`ssh-keygen` 走的是 OpenSSH 内部同一条 askpass 通路。
### 2.4.42 发布实据(2026-11-02,upstream-drift 报红)
**现象**:`upstream-drift`(每周一用 `dsh-better-sidebar@latest` 跑全量对拍)2026-11-02 的定时跑(run `41430536595`,main `68e4b95`)报红:
`sidebar-0250-endpoints.test.mjs` 的 C9 断言 `缺: git.history`(该文件 104 通过 / 1 失败;全量 38 文件 / 1985 通过 / 1 失败)。
本机装上 0.28.2 后逐条复现一致 —— 这正是该流水线的设计目的:**它红了就是上游发了新端点**。
**根因**:上游 **0.28.2**(2026-10-27 发布)新增端点 `git.history` —— 提交图分支数超过上限(`graph-limit`)时,
客户端会**回落到它继续翻页**。本插件此前只接管到 0.28.0 的 `git.graph`,该端点未注册 → 请求落到上游实现,
而远程工作区里上游用的是会话 cwd(**本地镜像**)目录:翻出来的历史来自镜像仓库(通常为空或滞后)。
与 2.4.18 / 2.4.28 / 2.4.32 同源的静默失效:不报错,只是结果不对。
**修法与验证**:
- `lib/index.js`:`GIT_METHODS` 追加 `history`、`interceptGitHandler` 加 `case "history"`、新增 `gitHistoryPage`
+ `historyLocalIo` / `historyRemoteIo`(远端一次 SSH 往返取「快照 + log + 快照」,用 `@@DSH_GH@@` 标记分段)。
- 口径逐条对齐上游:`count` 安全整数且 ≥1(内部上限 200);游标 `base64url(JSON{version:1,fingerprint,offset})`,offset 1..10000;
`log --branches --remotes HEAD --topo-order --no-decorate --no-show-signature --encoding=UTF-8 --max-count=limit+1 --skip=offset --format=%H%x00…%B%x00 --`;
**指纹与 `git.graph` 分开算**(全量 `for-each-ref` 不限 heads/remotes + HEAD + shallow 边界文件的 sha256);
`graph-stale` 409 / `graph-limit` 400;条目 `refs` 恒为 `[]`(上游 history 不做引用装饰)。
- 本地全量:**39 文件 / 2098 断言 / 0 失败**。新增 `tests/sidebar-0282-history.test.mjs`(75 条,A 契约/参数/指纹/游标/8 类错误码、
B 远端脚本标记与每页 2 次往返、C 真实临时仓库分页闭环 + 真过期、D 接线与上游键集合对拍 + 两向对照);
另加 `scripts/verify-remote-history-script.mjs`(25 条,WSL 真 sh + 真 git,覆盖标记分段、`--skip` 真分页、NOREPO、
**浅克隆的 shallow 边界文件**、多分支与中文 `%B`)。
- CI:发布提交 `26ec265` 的 `upstream-drift` **全绿**(run `41480731429`:39 文件 / 2060 通过 / 0 失败,unicode-names 整文件跳过)。
`tests.yml` 首跑红过一次(`2059 通过 / 1 失败`),**原因不在实现**:`tests.yml` 钉的对拍版本是 0.26.1(没有 `git.history`),
而新测试把「上游确实有 history」写成了硬断言。已改为「**上游有而本插件没接管**才判红」(钉旧版打印 SKIP 而不是失败)+
两向对照 D7/D8(旧上游不要求接管 / 上游多出未知端点必须精确报缺)。
`tests.yml` 的钉版 0.26.1 → 0.28.2 **暂缓**:本机 gh token 没有 `workflow` scope,改 workflow 文件会被 GitHub 拒绝
(`refusing to allow an OAuth App to create or update workflow`);判据改后钉旧版不会误红,要升先 `gh auth refresh -s workflow`。
**未做(诚实记录)**:① 本机桌面 profile **仍是 2.4.41**(未升级、未重启),所以「远程工作区里点开提交图、翻到第二页」的真机验证还没做;
② 没有真实远程仓库做端到端(远端分支由 faked SSH 与 WSL 真 sh 双覆盖,但不等于真机)。
### 2.4.41 发布实据(2026-10-27,issue #34)
**现象与根因**:DSH 0.1.5-rc.3 上「连接列表永远为空、导入与保存都没反应」。0.1.5 / 0.1.6 的 `settings`
同时有 `register()` 与 `configure/describe/update`,但那一代没有把 loader 行的 Config 注册成 settings
命名空间 —— 判据只看接口存在性 → 误走 0.1.7+ 新分支 → 读恒空、写抛 `namespace not registered`。
这是 #16 的镜像(0.1.7 拿掉 `register` 那一侧)。
**修法与验证**:`settingsApiMode(svc, entryId)` 三态判定;两套都在时以「`describe({redactSecrets:false})`
能否看到本插件命名空间」为准,探测抛错按 legacy;`register()` 抛错退只读 config + warn。
新增 `tests/settings-api-mode.test.mjs`(25 条,含变异负向控制);全量 **38 文件 / 2022 断言 / 0 失败**;
0.2.x 路径零行为变化(运行中宿主的 `dsh-settings` 里 `register(` 出现 0 次)。
**未做(诚实记录)**:本机只有 0.2.1-rc.3,0.1.5 安装包已不在,无法真机复现;按报告者给出的现场语义做等价仿真。
### 2.4.40 发布实据(2026-10-25,密码通道逐环离线验证)
**合并与 CI**:PR #33(外部贡献者 LPLS1zhang,`fix/password-auth-runtime`)以 merge commit `c1ace56` 合入 main,
合并前维护者在其分支上补了一个提交 `d985895`(env 命名、fs 拦截兜底、三处测试桩、文案文档);
PR 工作流对首次贡献者默认 `action_required`,由维护者放行后 **full-suite pass**(2m18s);发布提交 `8db3e6b` 的 push CI 同样绿。
全量本地:**37 文件 / 1997 断言 / 0 失败**。
**四环离线验证**(缺真实密码 sshd,逐环单验而不是端到端):
1. `dsh-settings` 的 `describe()`:`value: options?.redactSecrets ? redacted.value : value` —— 传 `false` 才拿得到 `.role("secret")` 字段的明文,这条既是根因也是修法的依据。
2. `dsh-subprocess-local` 的 `childEnv()`:"先清洗父环境、再合并调用方显式 `env`"(win32 走大小写不敏感覆盖),只拒绝控制通道变量 —— 所以 `SSH_ASKPASS` / `SSH_ASKPASS_REQUIRE` / 口令变量都能到达 `ssh.exe`。
3. 本机客户端 OpenSSH_for_Windows **9.5p2** 支持 `SSH_ASKPASS_REQUIRE=force`(需 8.4+)。
4. `askpass.cmd` 元字符保真:照实现的两行写法单独生成脚本,12 组口令(含 `&` `^` `!` `%` 双引号 空格 `|` `<` `>`)经 `cmd /c` 逐字节比对 **12/12 全对**,尾换行正确、无 BOM。
**未做(诚实记录)**:本机 `<profile>` 的 2 条连接都是密钥认证、**没有存密码**,因此没有「真实 sshd + 密码」的端到端实据;
等有密码测试机时按 §「2.4.39 真机四步」的方法补一轮(连接测试 + 文件面板 + 池化会话 stdout/stderr 分离)。
### 2.4.37 – 2.4.39 真机验证实据(2026-10-24 / 10-25,运行中宿主,DSH 0.2.1-rc.3)
方法同上:HTTP 打运行中宿主(`x-requested-with` 头 + 读 `value` 信封),端口以 GUI URL 为准(每次启动都变)。
- **2.4.37(issue #31)**:地球角标改按壳层行键认行;真机 `window.__dshRemoteSshGlobeStats(true)` 报 `matchedBy: "rowKey"`,与远程工作区**同名**的本地项目不再被误标。
- **2.4.38**:壳层 `workspace.json` 会在重启后丢掉新建工作区的原生注册 → `listWorkspaces` 从「缺了才补」升级为「每次核对」:id 变了跟上、实体没了清空、反查抛错保持原值、结果一致不写盘;重启后角标恢复。
- **2.4.39(issue #32)真机四步**:
1. `getPrefs` 回 `deleteSync: true` —— 说明 `workspaceRegistry.delete` 的联动钩子确实挂上了(服务实例可写、cordis 未冻结实例)。
2. **侧边栏删除工作区** → 设置条目**自动消失**、镜像目录被 rm 掉、壳层行消失(验证前 2 条 → 1 条)。这是 #32 第 1 条症状的正向证据。
3. 删完再添加同一「连接 + 远程路径」→ 只新增 **1 条**(修复前会变成两条一样);再添加一次 → `reused: true`、条目数不变。这是 #32 第 2 条的根治证据。
4. 同远程路径 + **不同连接** → 各自一条(预期行为);走本插件 API 删除时壳层行与镜像目录一并清干净。验证结束环境与验证前一致(1 个远程工作区 / 1 个镜像目录 / 4 个壳层行)。
- **DSH 0.2.1-rc.3 兼容抽查**:peer 门禁通过;`webServer.register` / `webStartup.trustedHosts` / `settings.describe|update|configure` / `workspaceRegistry.resolveByPath|create|delete|get|list` / `ctx.fs` 的 `readText|streamText|writeText|editText|stat|lstat|resolve` / `fileReferences` / `subprocess` / `tools.register` / `loader.await` / `profileContext` 全部在位;客户端 slot 名(`conversation.hero.workspace.directoryFlow`、`sidebar.workspaces.directoryFlow`)与壳层行标记(`div.projectRow[data-row-key="workspace:<id>"]`)未变,无需改代码即可升级。
### 2.4.35 / 2.4.36 真机验证实据(2026-10-21 重启后,运行中宿主)
方法:同下(HTTP 打运行中宿主,`x-requested-with` 头 + 读 `value` 信封);本轮端口 **62882**(每次启动都变,以 GUI URL 为准)。
重启实据:DSH 主进程启动 **09:24:21**,`<DSH>/remote-ssh/dsh-remote-shell.cmd` 写入 **09:24:30**(2.4.36 的 `apply()`)。
(2.4.35 那轮的实据:主进程 2026-10-20 21:16:05 启动、21:16:15 写 wrapper。)
**① #29 读影子层(2.4.35 主线):远端有、镜像没有的文件能读到**
用一个**镜像里完全没有该文件**的工作区(镜像顶层只有占位 `README.md` + `.remote-ssh.json`,远端同路径确有文件):
- 走**进程内 `ctx.fs`**(与内置预览同一条通道:本会话的文件读工具)读 `<mirror>/scripts/submit_gpu.sbatch` → **返回 27 行脚本正文**(远端内容);
- 换一个镜像里不存在的文件 `<mirror>/scripts/compare_periodic_hill_all.sh` → 返回 **52 行正文**;
- **负向控制**:`<mirror>/scripts/__no_such_2436__.sbatch` → `not found`(远端也没有时不伪造存在);
- **本地优先**:镜像里已有的 `<mirror>/README.md` 仍读本地那份(内容为占位说明)。
**② #30 回归:2.4.35 下技能全灭,2.4.36 恢复(含现场复现)**
- **复现(2.4.35 运行中,同一台机器)**:`~/.dsh/skills` 有 12 个技能目录、`~/.agents/skills` 有 1 个;会话 cwd **没有** `.dsh/skills` / `.agents/skills` →
`skill image-gen` 报 `skill "image-gen" is unknown or no longer available`,系统提示里没有技能目录。与 issue #30 描述逐条一致。
- **修复后(2.4.36 运行中)**:系统提示出现完整技能目录(14 条),`skill image-gen` **正常返回技能正文**;`getPrefs` / `listWorkspaces` 正常(3 个工作区),
`~/.dsh/skills` 全程未改动。
- **根因链(已写进回归测试)**:本地 not-found → 读影子层回落 → 路径不在任何镜像里 → 旧代码抛中文 `FS_IO_ERROR` →
`dsh-skill-filesystem` 只认 `FS_NOT_FOUND / ENOENT / FS_NOT_DIRECTORY` → provider 崩 → `dsh-tool-skill` 的 `if (!snapshot.complete) return decision;` 把整份技能目录丢弃。
修法:读取器新增 `NO_MIRROR` 专有码 + 包装层 `localFirst()`(远端也拿不到就抛**本地原始错误**;`FS_NOT_TEXT` / `FS_TOO_LARGE` / `FS_ABORTED` 仍透出)。
- **测试**:`tests/fs-read-bridge.test.mjs` 由 87 条扩到 **110 条**(新增 23 条覆盖无镜像 / 连接失败 / 语义错误 / 合成 target);全量 **33 文件 / 1874 通过 / 0 失败**。
**③ 顺带完成的插件全量更新(同一天,pnpm 正装)**
| 插件 | 变化 | 结果 |
| --- | --- | --- |
| `@zhangfengshun/dsh-remote-ssh` | 2.4.34 → 2.4.35 → 2.4.36 | 两次 `pnpm add`;8 文件与 npm tarball 逐字节一致 |
| `dsh-skill-mcp-panel` | **2.3.1 → 2.3.5** | 修「禁用任一 MCP 工具后宿主卡死」(上游 #59/#62);pnpm 自动把 `dsh-skill-mcp-panel@2.3.1 \|\| 2.3.5` 加进 `minimumReleaseAgeExclude`(2.3.5 发布仅 8.5 h,24 h 冷静期绕过是显式记录) |
| `dsh-better-sidebar` / `dsh-usage-panel` / `dsh-web-search-account` | 0.28.0 / 0.2.3 / 1.0.0 | 均已是 npm 最新(后两者是本地 tgz,npm 无对应包),无需动作 |
备份:`_hotfix-backup\plugins-update-20261020214335\`(package.json / pnpm-lock.yaml / pnpm-workspace.yaml / cordis.patch.yml / 旧 2.3.1 目录)、
`_hotfix-backup\profile-desktop-2.4.34-20261020191424\`(2.4.35 热替换前的 2.4.34 安装)。
**踩坑记录(新增)**
- **本轮回归的教训**:#29 的读影子层只测了「镜像内 / 远端有」两条路径,漏了「**既不在镜像、也没有任何镜像**」这条最常见的本地路径 —— 而这正是所有普通本地项目(技能根、普通文件读)每天都会走的路径。
以后凡是**全局包装 `ctx.fs`** 的改动,必须补一条「路径与远端无关时必须与旧版行为逐字段一致」的断言(现在 `localFirst` 与 `NO_MIRROR` 就是这条护栏)。
- **`read` 类负向控制要选对路径**:在 2.4.35 下用「不在镜像里的不存在文件」测 `read` 时,`resolve` 会把本地原错抛出来,看起来"没问题";
真正炸的是 `listDir` 一类**不做 resolve 直接列目录**的调用(技能 provider 就是这种)。探针要按消费者的真实调用形态选。
### 2.4.34 真机验证实据(2026-10-20 重启后,运行中宿主)
方法:直接打运行中宿主的 HTTP(本轮端口 **62225** —— 端口每次启动都会变,以 GUI URL 为准;必须带 `x-requested-with: XMLHttpRequest`)。
重启实据:DSH 主进程启动 **09:22:48**,`<DSH>/remote-ssh/dsh-remote-shell.cmd` 与 `.js` 写入 **09:22:57**(2.4.34 的 `apply()`)。
⚠️ 本轮新踩的两个探针坑:
- **`curl.exe` 在 PowerShell 下 `-d '{"id":"…"}'` 会被吞引号**,服务端回 `request body is not valid JSON`(不是接口问题);
改用 `--data-binary "@<UTF-8 无 BOM 文件>"`。
- **方法级回包是 `{"ok":true,"value":{…}}` 信封**:判断成败要读 `value.ok` / `value.error`,只读外层 `ok` 会把
「未找到远程工作区」误判成成功(与 §0 已记录的"直接读 body.workspaces 得到 0 个工作区"同源)。
1. **新字段上线(#28)**:`getPrefs` 返回 `defaultSyncPaths` / `defaultSyncExclude` / `defaultSyncMaxBytes`
(升级前同一接口只有 `nodePath` / `writeBackFailure` / `writeBackFreshness` 三个字段 —— 这是区分新旧构建最干脆的判据)。
2. **工作区同步范围写入且落盘**:对 `wmvcf2fqxqjr9` 发
`updateWorkspaceGuards {writeBack:true, writeBackExclude:["_patch/"], syncPaths:[".dsh","docs"," .dsh "], syncExclude:["data/","*.log",""], syncMaxBytes:"1 GiB"}`
→ 回读 `syncPaths:[".dsh","docs"]`(`" .dsh "` 被 trim 且**去重**)、`syncExclude:["data/","*.log"]`(**空串被丢**)、
`syncMaxBytes: 1073741824`(`"1 GiB"` 解析);`listWorkspaces` 二次请求同值(不是回显入参);
`cordis.patch.yml` 的 workspaces 段同步出现 `syncPaths:` / `syncExclude:` / `syncMaxBytes: 1073741824`。验证后已还原 `[] / [] / 0`。
3. **全局默认往返**:`savePrefs {defaultSyncPaths:[".dsh","docs"], defaultSyncExclude:["data/"], defaultSyncMaxBytes:"512MB"}`
→ 回读 `512000000`;`getPrefs` 独立回读一致;磁盘出现 `defaultSyncPaths` / `defaultSyncExclude` / `defaultSyncMaxBytes` 三行。验证后还原为空。
4. **新工作区继承默认(#28 第 2/3 条)**:默认非空时 `createRemoteWorkspace {profileId, remotePath}` **不传** sync 参数
→ 新工作区拿到 `.dsh,docs / data/ / 512000000`;随后 `deleteWorkspace` 清理干净(镜像目录一并消失,工作区数回到 3)。
5. **显式参数优先于默认**:同一默认下 `createRemoteWorkspace {…, syncPaths:["only-this"], syncMaxBytes:1048576}`
→ 新工作区 `["only-this"] / 1048576`(未被默认覆盖);已删除。
6. **负向控制**:未知工作区 → `value.ok:false`「未找到远程工作区」;`savePrefs {whatever:1}` → `value.ok:false`「没有可保存的字段」;
`syncMaxBytes:"乱填"` → 归 **0**(不是 NaN,也不报错)。
7. **最终状态**:3 个工作区全部 `syncPaths: []` / `syncExclude: []` / `syncMaxBytes: 0` / `writeBack: true`(与验证前逐字段一致),
磁盘 `defaultSyncPaths: []` / `defaultSyncExclude: []` / `defaultSyncMaxBytes: 0`。
有意**未做**的两项:① 没有真跑 `syncDown` / `syncUp` —— 那会把远端内容覆盖进镜像、可能冲掉本地未推送的改动,而同步端点本身是
2.4.20 起的既有能力(`tests/sync-safety.test.mjs` 覆盖);② 没有截图 UI —— GUI 需要 `dsh web` 打印的带 token URL,但客户端 bundle
与 npm 包**逐字节一致**,且 `tests/settings-sync-scope-ui.test.mjs` 断言了控件、弹窗、按钮与中英文案。
### 2.4.33 真机验证实据(2026-10-17 重启后,运行中宿主)
方法同上(直接打 `http://127.0.0.1:50311/sidebar/api/*`,`x-requested-with` 头 + 计时)。重启实据:`dsh-remote-shell.cmd` mtime **19:58:17**(2.4.33 的 `apply()`)。
远程工作区 = 超算登录节点(高延迟公网链路)+ 大仓库(两个自带 `.git` 的 Julia 检出,zfs 网络盘)。对照基线是 2.4.32 同机同仓的测量:
1. **git.status(主要痛点)**:同仓库立即重取 **20-23ms**(5s TTL 缓存命中,0 SSH 往返)—— 原来每次 1.6~3.7s;真仓库(`XCALibre-latest`)TTL 过期重算 **1.2~3.0s**(zfs 负载波动;脚本已不再做两次全仓 numstat 扫描)。仓库根非 git 仓库 → 正确返回 `isRepo:false`(其 1.8~3.3s 耗时是 git 在网络盘上向上走查 `.git` 的固有成本,非脚本开销)。
2. **文件通道不再被 git 阻塞**:git.status 计算期间并发探测 `fs.trees`/`fs.read` 全部 1~30ms 返回(专用 `profileKey|git` 会话生效;2.4.32 时文件请求要排在慢 git 后面)。
3. **fs.read**:热缓存 29ms;TTL 过期后真实传输(压缩通道)**126~286ms**(~10-50KB 文本,2.4.32 同文件 ~150-173ms)。
4. **fs.trees**:冷列举(treeCache 未命中的深目录)108ms/层,热 1ms。
5. **非仓库/不存在的目录 → `isRepo:false`**(2.4.32 已修,回归确认仍在)。
### 2.4.31 真机验证实据(2026-10-16 重启后,运行中宿主)
方法:直接向运行中的宿主打 HTTP(`http://127.0.0.1:19387`),不采信插件自身的任何"已完成"输出;
远端证据用**我自己的 ssh 客户端**(凭据只从 `<profile>` 工作区的 `.remote-ssh.json` 读,不外显)。
1. **#27 修复**:`fs.tree {sessionId:"",path:""}` → **200**,`value.path` = 主目录、137 个条目(升级前同请求 → 400 `path 为必填项`)。
2. **反向控制**(放行面没被放大):`fs.read` 空 path → 400、`fs.write` 空 path → 400、`fs.tree` 相对路径且无会话 → 400 `无法解析相对路径`。
3. **本地 `fs.readPage`**:159,934 字节文件 → 2 页(追踪 0→130783→159934),拼接后与原文件**逐字节相同**;`offset=size` → 空页 + `eof` + `nextOffset=size`;目录 → 400 `is a directory`;空 path → 400(未照搬 `fs.tree` 的空路径语义);不存在 → 400 `cannot read`。
4. **接管身份判定**:`sessionId` 为空时上游实现会先因 `sessionId` 缺失报错 —— 上述请求返回 200,即证明处理者是本插件的分支,而不是上游。
5. **远端 `fs.readPage`(决定性证据)**:临时注册一个工作区指向远端 396,000 字节文件(**本地镜像里没有这个文件**)→ 4 页(0→130977→261954→392931→396000),拼接后 sha256 与远端原件一致(`a48c5a36…`),`size`/`mtimeMs` 来自远端 stat;**只在本地镜像存在的文件 → 400**(证明没有回落读镜像)。验证后临时工作区已用 `deleteWorkspace` 删除、远端临时目录已 rm、注册工作区数回到验证前的 2 个。
6. **顺带验证孤儿镜像守卫(2.4.29)仍在生效**:手工把未注册目录放进镜像根,请求被明确拒绝("位于远程工作区镜像目录下,但它不属于任何已注册的远程工作区…"),没有在镜像上执行任何操作。
探针写法注记(踩过一次):`/remote-ssh/api/*` 必须带 `x-requested-with` 头;其 HTTP 返回是 `{"ok":true,"value":{…}}` **信封**,
直接读 `body.workspaces` 会得到 undefined 并误判成"0 个工作区"(`fs.*` 同样是 `value` 信封)。
### 端点接管清单(截至 2.4.44)
- **2.4.43 无新增/变更路由**:两项修复都在工具层与连接层(取消信号、askpass 落点),HTTP 端点与 output schema 均未变,路由数仍为 **32**。
- **2.4.37 – 2.4.39 期间无新增/变更路由**:三版只改内部逻辑与客户端渲染(角标认行方式、id 漂移自愈、壳层删区联动);2.4.39 的联动挂在 `workspaceRegistry.delete` 服务方法上,不是 HTTP 端点,`getPrefs` 只是多回一个 `deleteSync` 字段。
- **2.4.42 接 better-sidebar 0.28.2 的 `git.history`**(提交图分支数超上限时的分页历史兜底):上游 0.28.2 在 `git.graph` 之外又加了一个碰仓库的端点,未接管时远程工作区会拿本地镜像列历史 —— `upstream-drift` 2026-11-02 报红报的就是这一项(`sidebar-0250` 的 C9 对拍 `缺: git.history`)。实现与 `git.graph` 同形但指纹口径不同:**全量 `for-each-ref`(不限 heads/remotes)+ HEAD + shallow 边界文件**的 sha256,`graph-stale` 409 / `graph-limit` 400 复用同一组错误码。远端那段 sh 有独立验证:`node scripts/verify-remote-history-script.mjs`(WSL 真 sh + 真 git,25 条;与 `verify-remote-status-script.mjs` 同套路 —— 假 SSH 出口只能验数据流,验不了 POSIX 正确性)。
- 本插件以 `kind: "exact"` 接管 **32** 条路由(`/sidebar/api/fs.*` + `/sidebar/file` + `git.*`):2.4.28 接 better-sidebar 0.25.0 的 6 个,2.4.31 接 0.26.1 的 `fs.readPage`,2.4.32 接 0.28.0 的 `git.graph`,2.4.42 接 0.28.2 的 `git.history`。**2.4.35 / 2.4.36 无变化**(#29 的读影子层是**进程内**包装 `ctx.fs`,不是 HTTP 路由;2.4.34 的 #28 只给已有端点 `updateWorkspaceGuards` / `createRemoteWorkspace` / `getPrefs` / `savePrefs` 加了字段并复用 `syncDown` / `syncUp`,同样没有新增路由)。
- `fs.readPage`:5 MiB 以上文件的只读分页预览,**128 KiB/页、页尾回退到最后一个换行**、整页无换行时原样返回,返回 `{kind,text,offset,nextOffset,eof,size,mtimeMs,encoding}`(字段名取自上游,消费方是上游预览面板,不能自创)。远端分支一次 SSH 往返取 `size/mtime` + 该页字节(`tail -c +N | head -c 131072 | base64 -w0`),**回退与解码在本地做**;失败映射成上游同款 `400 fs-error`。`path` 必填。
- 上游升级后先跑 `tests/sidebar-0250-endpoints.test.mjs`:它会列出「本插件未接管的上游端点」并对拍文件名校验等纯函数语义。上游重构(如 0.26.1 把单段名检查拆成 `assertSingleSegmentName`)会让上游沙箱抽取失败 —— 此时补抽对应函数即可,**不要**把对拍降级成「跳过」或放宽比较。
### 容易踩的坑
1. **行尾**:本仓 `core.autocrlf=true`,`git stash`/`git checkout`/`git show >` 都可能把 `lib/index.js` 变成 CRLF;而多个测试用含 `\n` 的标记切片源码,换行被改写会**整文件抛错**(不是断言失败,是异常,会掩盖同一文件里其它断言)。改完 `lib/` 下的文件后核一下「CRLF 行数应为 0」,或后续加 `.gitattributes`(`*.js text eol=lf`)一次性消除。注意 `README.md`/`README_EN.md` 本身就是 CRLF,改这两个文件要按它们自己的行尾写。
2. **断言要能在坏状态下报红、而不是抛错**:`r.body.value.xxx` 这种直接解引用在失败路径上会抛 `TypeError`,把后面所有断言一起吞掉(只有变异控制才暴露得出来)。统一写 `!!r.body.value && r.body.value.xxx === …`。
3. **不要往仓库里提交日期命名的目录/会话产物**(2026-10-17 用户明确要求):一次性审计/验证脚本若值得保留,进 `scripts/` 并用描述性文件名(如 `scripts/verify-remote-status-script.mjs`),CHANGELOG 引用规范路径;不值得保留的留在仓库外。2.4.33 曾把 `audit-2026-10-17/` 提交进仓库,同日整改挪到 `scripts/`。
4. **插件设置只落在 `cordis.patch.yml`,且宿主会整份重写**:远程工作区条目/连接配置/全局默认同步范围都在 `<DSH_HOME>/profiles/<profile>/cordis.patch.yml`(**不是** `settings.json`)。宿主重启时常把整份文件重写一遍,所以手改文件很可能下次启动就被覆盖;要改走插件 API / 设置面板。排查"设置到底写没写进去"必须读这个文件。
5. **壳层删除工作区不经过插件 API**:壳层「删除工作区」只调 `workspaceRegistry.delete(id)`(`dsh-api-workspace-controller`),任何"只在自己 API 里删条目"的实现都会留孤儿条目(issue #32)。2.4.39 起靠挂接该方法联动清理,自检位是 `getPrefs` 返回的 `deleteSync`;若某天宿主把服务实例冻结或换实现,该字段会变 `false` 并打 warn,那时删区要手动清条目(宁可退化也不要静默丢配置)。
6. **`role("secret")` 的字段在运行时读不到(2026-10-25,PR #33 的根因)**:settings schema 里标了 `.role("secret")` 的字段,
`settings.describe({ redactSecrets: true })` 读出来就是空串 —— 而插件拼 `sshpass -p …` 正是从这次读的结果取 `p.password`,
于是"密码认证"从 v1 起就没有任何可用路径,表现是连接挂到 120 s 超时、**没有任何报错指向口令**。纪律:
**运行时取明文用 `redactSecrets: false`,对外出口(HTTP API / 模型工具)必须自己剥**;2.4.40 起 `listProfiles` / `saveProfile` /
`deleteProfile` / `remote_ssh_profiles` 一律只回 `passwordConfigured: true|false`。新增字段/出口时照此办理,
别把"脱敏"责任留给读取侧。
7. **「接口存不存在」不能当 API 代际判据(2026-10-27,issue #34)**:settings 在 0.1.5 / 0.1.6 上
**两套接口同时在**(`register()` + `configure/describe/update`),但 entry 命名空间尚未注册。
只看接口存在性 → 误判成新版 → 读恒空、写抛错,功能整块静默失效(用户只看到「列表是空的」)。
纪律:**判据要问「这条路现在真的能用吗」,而不是「这个方法存在吗」** —— 我们能探测就探测
(`describe()` 里有没有本插件命名空间),探测失败时退到保守的旧路径;迁移期两条路都保留、都带
兜底(`register()` 抛错退只读 config + 一行 warn,而不是让 `apply()` 抛错导致插件不加载)。
### 路径归属规则(2.4.30 起,issue #26)
fs 处理器**不再用会话 cwd 决定"这次请求走不走远端"**,而是逐条判每个请求路径(`payload.path` 与 `payload.paths[]`)的归属:
| 请求路径形态 | 归属 | 走向 |
| --- | --- | --- |
| 已注册远程工作区镜像成员 | `mirror` | 远端;剥镜像前缀拼**工作区根**(`remoteBase` 必须是根,不能是更深路径) |
| 目录自带 `.remote-ssh.json`(未注册但自描述) | `self-described` | 远端;基准就是该目录(2.4.x 旧行为) |
| `/...`(posix 绝对路径,且不是镜像成员) | `remote-abs` | 远端且**原样下发**(唯独这条会排除镜像成员 —— DSH 跑在 Linux 上时镜像路径本身就是 `/...` 形态) |
| 盘符 / UNC,含 `C:foo` 这种盘符相对 | `local` | **本地**,即使会话在远程工作区 |
| 相对路径 | `relative` | 按会话 cwd(远程会话 = 镜像根) |
| `~` 开头 / 空 | `tilde` / `empty` | 保持原有明确报错(不给 `~` 做展开) |
两条附加守卫:镜像根之下、但不属于任何已注册工作区的路径 → `400`(2.4.29 起,绝不在镜像上读写);同一次请求里混用本机路径与镜像/远端路径 → `400`(猜一侧会让另一侧被静默忽略)。
**刻意保留、需要知道的两点**:① **本地会话**打开镜像成员路径仍走**远端**(镜像不是事实来源);② 远端会话里的**相对路径**是**工作区相对**(相对镜像根),不是本机进程 cwd 相对。`localToRemote()` 的契约是"入参必须是本地镜像路径",兜底命中会打 `warn`(2.4.30 起)—— 命中即说明上游分类漏了,别再调回 `debug`。
8. **`withTimeout` 必须「先 reject 再 onTimeout」;取消绝不回退重跑(2026-11-03,issue #35 的测试抓出的真 bug)**:`onTimeout` 会
`terminate` 子进程 / `close` 会话,被它顺带 settle 的 `done` / `exec` 可能抢在 race 之前落地,把「超时/取消」误报成「命令自己失败了」
(`tests/cancel.test.mjs` 的 F2/F8 就是抓这个的)。另外**取消绝不能回退一次性连接**:那条回退是「会话挂了」的自动重连,
用它处理取消等于把用户刚停掉的命令再执行一遍(与 issue #5「超时不重试」同一条不变量)。
9. **Windows OpenSSH 用窄字符路径启动 askpass(2026-11-03,issue #36)**:`SSH_ASKPASS` 路径含非 ASCII(中文用户名 → `%USERPROFILE%`
与 `%TEMP%` 都非 ASCII)时助手根本不会执行,ssh 发**空口令**、服务端只回 `Permission denied`。复现不需要 sshd:
`ssh-keygen -t ed25519 -N pass1 -f key` 之后用 `SSH_ASKPASS=<路径> SSH_ASKPASS_REQUIRE=force RSSH_ASKPASS_PW=pass1 ssh-keygen -p -f key -N pass2`
—— 失败时就是 `CreateProcessW failed error:2` + `ssh_askpass: posix_spawnp`。纪律:**任何交给外部进程的可执行路径都要先校验纯 ASCII**
(2.4.43 的 `isAsciiAskpassPath()`),并给出 `DSH_REMOTE_SSH_ASKPASS` 这样的显式覆盖口;落点写不进去时要**抛明确错误**,
不能让下游用一个空凭证去撞 `Permission denied` 再把用户引向错误方向。
10. **测试里不要写死仓库绝对路径(2026-11-03,2.4.44 的 CI 报红)**:本机全绿 ≠ CI 全绿 —— 把仓库根写成
`F:/MyAIProject/...` 后,GitHub Actions 上该文件直接 **CRASH**,而 `tests/run-all.mjs` 的汇总把它记成
「1 个文件有问题」,**「结果: N 通过, 0 失败」仍然显示 0 失败**,只看最后一行会以为通过。纪律:仓库根一律
`fileURLToPath(new URL('..', import.meta.url))`(或至少 `new URL('..', import.meta.url).pathname`),
推送后扫一眼 run 日志里的「有问题的文件 / [CRASH]」段。
## 1. GitHub 连接机制(如何工作的)
**认证链路**:`git push origin main` → git 调 credential helper → gh CLI 提供 token。
- `~/.gitconfig` 中由 `gh auth setup-git` 写入:
```
[credential "https://github.com"]
helper = !'C:\Program Files\GitHub CLI\gh.exe' auth git-credential
```
(gist.github.com 同理)
- 系统级兜底:`E:/Program Files/Git/etc/gitconfig` 的 `credential.helper=manager`
(Git Credential Manager)。
- 令牌本体存于 Windows 凭据管理器(keyring),**永远不要**打印/复制到明文文件。
- 验证命令:`gh auth status`(应显示 ✓ Logged in,Active account: true,
Git operations protocol: https)。
**git 身份**:
- 全局:`user.name=zhangfengshun`、`user.email=zhangfsh2020@163.com`
- 本仓库覆盖:`user.name=ZhangFengshun`、`user.email=zhangfengshun21@mails.ucas.ac.cn`
(提交前用 `git config user.name / user.email` 确认走的是仓库级配置)
**gh 附加能力(历史会话已实际用过)**:
- `gh repo fork --clone=false` + `gh pr create`:向 awesome-dsh-plugin 投稿
(PR #4268,条目 `data/plugins/zhangfengshun__dsh-remote-ssh.yml`,category: remote)
- `gh repo edit --add-topic dsh-plugin`:仓库已加 `dsh-plugin` topic
- `gh api` 可用(token 含 admin:public_key,可临时注册测试 SSH 公钥,用完即删)
**故障排查**:若 push 突然要求输密码 → `gh auth status` 看登录是否失效;
重登录用 `gh auth login`(浏览器 OAuth 或粘贴 gho_ token),然后 `gh auth setup-git`。
## 2. npm 发布机制
- 认证:`%USERPROFILE%\.npmrc` 中的
`//registry.npmjs.org/:_authToken=npm_***`(值不外泄)。
- 校验:`npm whoami` → `zhangfengshun`;失效表现为发布时 **401**。
- **token 更新流程(历史做法)**:用户在聊天里给出新 token →
用 PowerShell 正则替换 `.npmrc` 中该行 → `npm whoami` 验证。
```powershell
$npmrc = "$env:USERPROFILE\.npmrc"
$lines = Get-Content $npmrc
$lines = $lines -replace '^//registry\.npmjs\.org/:_authToken=.*$', '//registry.npmjs.org/:_authToken=<新token>'
Set-Content -Path $npmrc -Value $lines -Encoding ascii
npm whoami
```
## 3. 标准发布流程(历史会话沉淀,每条线都验证过)
```powershell
cd F:\MyAIProject\RemoteSSH\dsh-remote-ssh # 2026-10-17 从桌面 temp\ChatGPTProProject 迁移到此
# 0. 改前先跑基线、改后再跑一次:npm test(= node tests/run-all.mjs 聚合运行器)
# 本机基线:28 文件 / 1469 通过 / 0 失败,约 7~14 秒。判定口径要看清:
# FAIL / CRASH → 红;而**整文件跳过(0 断言)单列为 SKIP 并打印原因** —— 只看一个绿勾会被骗,
# 例如 CI 上没有 WSL:unicode-names 整文件跳过(31 条)+ wrapper-terminal 少 5 条 → 1433。
# 0b. push 之后 GitHub Actions 自动再跑一遍(已上线,2026-10-16 起为绿):
# · workflows/tests.yml —— windows-latest + Node 22 + 钉版上游 0.26.1(升 0.28.2 需 gh token 有 workflow scope)
# + 运行时依赖 yaml/schemastery;
# · workflows/upstream-drift.yml —— 每周一 03:00 UTC 用 @latest 跑:**它红了就是上游发了新端点**,
# 按「升级 better-sidebar 后必做对拍」接管,别改断言让它变绿。
# 两个坑(都踩过,已写进工作流注释):
# ⓐ 改 .github/workflows/* 不能用 origin —— 它是 OAuth App token,没有 workflow scope,
# GitHub 直接拒收(refusing to allow an OAuth App to create or update workflow ...)。
# 改用 SSH 推:git push git@github.com:ZhangFengshun/dsh-remote-ssh.git main
# (或先 gh auth refresh -h github.com -s workflow 解锁 token)。
# ⓑ CI 上没有 DSH_PROFILE_DIR,而测试是按目录去找真实依赖的 → 缺 yaml / schemastery 时
# module-load 6 条红、settings-compat 直接抛「找不到依赖: yaml」,**看着像代码回归**。
# 工作流里已显式装齐。本地要复现 CI 环境必须先 Remove-Item Env:DSH_PROFILE_DIR,
# 否则会被本会话的 DSH_PROFILE_DIR 兜底,永远复现不出来。
# 0c. 历史 tag / Release 补档(2026-10-16 补 v2.4.18 时走通的路径):
# ⓐ 先找**发布提交**:git log --all -S'## [<版本>]' -- CHANGELOG.md
# (2.4.18 → 3e65aa0。注意 -S 搜 package.json 的 "version": "<版本>" 这次**没搜到**,
# 所以别只信一种找法 —— 提交信息 + CHANGELOG 段 + 时间线一起看)
# ⓑ **先核对再打 tag**:下载 npm 上那一版(registry 的 <版本> 级 URL 取 dist.tarball),
# 用 git hash-object <解包后的 lib/index.js> 与 git rev-parse <提交>:lib/index.js 比 blob,
# 相同才说明这个提交就是当初发出去的那份(package.json 的 version 也要一致)。
# ⓒ git tag -a <版本> <提交> && git push origin <tag>(tag 走 origin 即可,不碰工作流文件)
# gh release create <tag> --notes-file <正文> **--latest=false**
# ← 少这个参数会把 Latest 抢到旧版本上;建完必须独立核对:
# gh api repos/<owner>/<repo>/releases/latest --jq .tag_name 仍是新版本。
# 1. 改代码 + 升 package.json version + 更新 CHANGELOG.md(版本段 + 修复/性能数据)
# 2. 提交 + 推送 + 发布(一条命令串行):
git add -A
git commit -m "2.3.x: <一句话说明>"
git push origin main
npm publish # 注意坑 6:本账号的发布会走 registry 侧 staged publish,"输出成功"≠"已公开"
# 2b. 发布后确认(必做,不要只看 npm view version —— packument 有缓存、会滞后几分钟):
# 版本级 URL 返回 200 才算真的公开 → curl https://registry.npmjs.org/<scope>%2F<pkg>/<版本>
# 再核对 dist-tags:npm view <pkg> dist-tags (latest 应指向新版本)
# 最后回下载对比:npm pack <pkg>@<版本> 的 sha1 应等于 npm publish 输出里的 npm notice shasum
# 3. (可选)校验 npm 包内容:npm publish --dry-run
# 4. (可选)本地 pack 与 registry shasum 一致性核对(npm pack --dry-run --json vs
# registry dist.shasum)
# 5. 装入 desktop profile:
dsh plugin --profile desktop add @zhangfengshun/dsh-remote-ssh@<版本>
```
### 已知坑(全部在历史会话中踩过并解决)
1. **`minimumReleaseAge` 供应链策略(2026-10-04 实测:窗口 = 24 小时,不是几分钟)**:
刚发布的新版本走**应用内插件管理器**安装会被 pnpm 拦下:
`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION <pkg>@<ver> was published at <ISO>, within the
minimumReleaseAge cutoff (<ISO>)`。两处证据与结论:
- 策略窗口从日志里的 cutoff 反推 = **发布时刻 − cutoff = 24h**(导出 2.4.19 时读
`<profile>/.plugin-manager/logs/<operation>/pnpm.log` 看到 cutoff 恰为检查时刻前 24 小时;
历史上 2.4.16 也在同一窗口内被拦);
- 它验证的是 **lockfile 里所有 entries**("Verifying lockfile against supply-chain policies
(N entries)"),所以不是"只挡新包",而是"锁文件里出现未满 24h 的版本就整体拒绝";
- **桌面 profile 是 pnpm 工程**(`<profile>/package.json` + `pnpm-lock.yaml` + `pnpm-workspace.yaml`,
`nodeLinker: hoisted`,`autoInstallPeers: false`),应用内插件管理器其实就是在这个目录跑
`pnpm add <pkg>@<ver>`(日志可见);它用的是 **pnpm 11.8.0 + store
`%LOCALAPPDATA%\pnpm\store\v11`**,与本机 CLI 的 pnpm(10.x / store v10)**store 不同** ——
拿 CLI pnpm 直接 install 会要求"清空并重建 node_modules"
(`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`,非 TTY 下被拒),**不要照做**(会牵连 profile 里
其它插件)。
- 想立刻用上新版本:**就地更新**(把 registry 上该版本 tgz 解出的 `package/*` 覆盖到
`<profile>/node_modules/<pkg>/`,并同步 `<profile>/package.json` 的依赖号)。这条路径不经过 pnpm,
因此不受 24h 窗口限制;代价是 `pnpm-lock.yaml` 会暂时落后一版 —— 等窗口过去后由管理器安装自动收敛。
备份放 `%USERPROFILE%\.dsh\packages\_hotfix-backup\profile-desktop-<时间戳>\`。
2. **npm notice 打到 stderr**:PowerShell 会把它包成 NativeCommandError 红字,
但发布实际成功——以输出里 `+ @zhangfengshun/dsh-remote-ssh@x.y.z` 和
`npm whoami` 为准,不要被红字吓到。判断成功可
`npm publish 2>&1 | Select-String -Pattern "version:|\+ @zhangfengshun"`。
3. **LF→CRLF 警告**:`warning: in the working copy of '...', LF will be replaced by
CRLF` 无害,忽略。
4. **发布前必查 `files` 字段**:package.json 的 `files` 白名单决定 tarball 内容,
历史上有一次漏了 README_EN.md(2.1.7 补上)。发布后用 dry-run 输出核对文件清单。
5. **版本号一致性纪律**:commit message 以版本号开头(如 `2.3.9: pin ssh to
System32 OpenSSH...`),CHANGELOG 顶部同步加同版本条目;npm 与 git 必须同时
走到同一版本,否则后续排查对不上。
6. **registry 侧 staged publish(2026-09-29 发布 2.4.18 时踩到,会误判"发布失败")**:
本账号(2FA 开启、token 为 `npm_…` 细粒度令牌)的 `npm publish` 由 registry **暂存**受理,
npm 照常打印 `npm notice version: x.y.z` 与 `+ @scope/pkg@x.y.z` 并以 0 退出,但版本**不会立刻公开**:
- 立刻查会看到旧版本(`npm view version` 仍是上一个版本,packument 缓存 + 暂存未推广),
于是很容易以为发布失败;
- 重发同一个版本会得到 `npm error code E409 409 Conflict - PUT … Cannot publish over
previously staged version "x.y.z"`(**不是**权限问题,也不是版本号被占用);
- `GET https://registry.npmjs.org/-/stage` 与 `npm stage list` 在本机可能显示为空(本地 npm 11.10.0
**没有** `stage` 子命令;`npm stage list/view/approve/reject/download` 属于 **npm 12+**,
可用 `npx -y npm@12 stage …`,注意会打 `EBADENGINE` 警告:npm 12 要求 node ^24.15.0,本机 24.13.0)。
实测(2.4.18):第一次 `npm publish` 报成功但 registry 无此版本;重发报 E409;**约 8 分钟后
`https://registry.npmjs.org/@scope%2Fpkg/2.4.18` 返回 200、`dist-tags.latest` 跟上** —— 即暂存件被
推广为正式版本,**无需重新发布**。结论:**发布后先用"版本级 URL"确认,别急着重发**;
重发只会得到 409。真正需要人工介入(OTP/网页批准)时,npm 会明确要求 one-time password。
- **2026-10-16 发布 2.4.31 复现同一现象,并定位到"误判来源"**:`npm publish` 报成功(`+ @scope/pkg@2.4.31`)后
**`npm view <pkg>@2.4.31` 连续 11 次(约 3.5 分钟)都返回 E404,`npm view version` 也仍是上一版** —— 因为 `npm view` 读的是
**本地 packument 缓存**。同一时刻 `curl.exe -s -o body -w "%{http_code}" -H "Cache-Control: no-cache"
https://registry.npmjs.org/<scope>%2F<pkg>/2.4.31` 已返回 **200**、`dist-tags.latest` 已指向 2.4.31(发布到可见约 4 分钟)。
结论:**核对一律用带 `Cache-Control: no-cache` 的 curl 直连注册表,不要用 `npm view`**(它会让你以为发布失败而重发,重发只会得到 409)。
7. **改文档/版本号一律用编辑器工具,不要用 PowerShell 做文本往返(2026-10-11 踩到,一次废掉两个 README)**:
本机 DSH 的 `pwsh` 工具实际是 **Windows PowerShell 5.1**(`5.1.26100.9568`),它的
`Get-Content -Raw` **对没有 BOM 的文件按 ANSI 代码页(中文机器 = GBK)解码** —— 仓库里所有
`.md`/`.json` 都是 **UTF-8 无 BOM**,于是 `Get-Content -Raw` → `-replace` → `Set-Content -Encoding utf8`
这条"顺手改个版本号"的链路会把整篇中文读成乱码再写回:README.md / README_EN.md 全篇变
`锛?鈥?馃`,还额外带上 BOM(BOM 对 npm 无害,但**对裸 `JSON.parse` 的宿主是致命的**)。
纪律:
- 改文件用编辑器工具(`edit`/`write`,它们按 UTF-8 处理且有版本守卫);**需要脚本批量替换时,
显式指定编码**(`Get-Content -Encoding UTF8` / `Set-Content -Encoding UTF8NoBOM`,PS 5.1 写
无 BOM 得用 `[System.IO.File]::WriteAllText($p,$t,(New-Object System.Text.UTF8Encoding($false)))`)。
- **改完必须核验**:① `git diff --stat` 看改动行数是否离谱(整篇重写 = 编码事故的信号);
② 文件头 3 字节不是 `EF BB BF`;③ 抽查是否出现 `锛|鈥|馃` 这类乱码样本。
- 出事后**不要手工修补**:`git checkout -- <文件>` 回到 HEAD,再用编辑器重做那几行改动
(本次 README 的两行改动就是这么重做的,实测 30 秒恢复干净)。
## 4. 归档会话的读取方法(以后还想翻历史)
```powershell
# 会话存于 <DSH_HOME>\sessions\<工作区目录>\<session-id>\session.jsonl.zstd
# DSH_HOME = C:\Users\Administrator\.dsh
zstd -d -f <file>.zstd -o out.jsonl # zstd 位于 E:\ProgramData\anaconda3\Library\bin
```
- 本项目相关会话的目录名由**当时的 cwd** 派生(`C:\...\ChatGPTProProject` → `--C-Users-Administrator-Desktop-temp-ChatGPTProProject--`)。
历史会话仍在该目录下:`session-d5dc5130`(主维护会话,2.1.7→2.3.9 全部发布史)、
`session-996c0822`(AgentTeams 工程师子会话,含 awesome 投稿全过程)。
**2026-10-17 仓库迁移到 `F:\MyAIProject\RemoteSSH\dsh-remote-ssh`**,此后从新路径起的会话会落在
新的目录名(`--F-MyAIProject-RemoteSSH-dsh-remote-ssh--`)下;查老会话仍去老目录找。
- 每条 JSONL 行是一个事件;`assistant/message` 里的 reasoning 字段含当时的决策过程。
## 5. 维护备忘
- **📦 「在开发机上能解析」≠「官方打包形态能解析」(2026-10-12,issue #23 第二轮,最值得记的一条)**:
2.4.24 用 `process.execPath` / 同目录 node 等五条候选修 wrapper 的 node 解析,本机实测通过、测试也过,
但**官方打包版上五条全落空** —— 举报人对着产物逐条核对:主进程 `execPath` 是 `DeepSeek Harness.exe`、
`DSH_DESKTOP_NODE_EXECUTABLE` 不在子进程环境里、同目录无 node。教训有两条:
(a)**验收要造出目标形态的进程画像**,而不是只跑本机的真实值 —— `tests/wrapper-terminal.test.mjs`
场景 11 现在就是这样:伪造 packaged Desktop 的 `execPath` + 清掉环境变量 + 无同目录 node,
再断言兜底候选能解析到**真实存在**的文件,并留一条负向控制(全都不可用 → 空串 + 回退 PATH)。
(b)**结论的措辞要跟代码能交付的范围对齐**:2.4.24 的 CHANGELOG/README 写了"不再依赖 PATH",
这对打包版是过强的 —— 2.4.25 把话收回来,并明确"在官方给出稳定 runtime 入口之前,插件侧到此为止"。
CHANGELOG 里已经写下的过强结论,**要在下一版显式更正**,不能悄悄改文档了事。
(c)2.4.25 加的两条兜底(⑥ `%DSH_HOME%\dsh-runtimes\*`、⑦ `<安装目录>\resources\runtime\*`)在
**两台机器上都命中⑦、不是⑥** —— 插件所在进程的环境里**没有** `DSH_HOME`,所以⑥落空(DSH_HOME 是给
子进程/终端设的,不是宿主主进程的)。⑦ 依赖"进程可执行文件旁边就是运行时"这个**安装期事实**,比环境变量稳,
排序不该反过来。举报人还实测了:`…\resources\runtime\` 下有 `bin`/`cli`/`office-skills`/`pnpm`/`primary-runtime`
**五个目录,只有 `primary-runtime` 含 node** —— 所以"探测该层 + 逐候选 `existsSync` 验证 + 实例名不写死"
是必需的,硬编码任何实例名都会在下一次改名时脆掉。
- **⚖️ 覆盖类护栏的默认值:按代价不对称来定,并且必须留"作废"通道(2026-10-12,issue #24 护栏 B)**:
写回前检查远端是否被改过(记录 `size:mtime`,不一致就不推、只报告)。定这条护栏时的几个判断可复用:
① **默认开** —— 漏报一次 = 远端内容被静默覆盖(不可逆),误报一次 = 模型多走一步 `remote_ssh_push`(可恢复);
② **只在远端自己的时间轴上自比**,绝不与本地 mtime 比(跨机时钟偏移、tar/base64 重写让两边不可比);
③ **"读不到"必须放行**(`stat` 失败/ssh 抖动归为"状态未知",只留日志)—— 否则 flaky 连接就变成了拦截器;
④ **记录要能被显式操作作废**(`remote_ssh_push` / `remote_ssh_sync` 成功、以及显式写远端之后清记录),
否则护栏会从"保护"变成"永久封锁";⑤ 判据抽成纯函数(`freshnessVerdict`)单独测三态,而不是埋在 `apply()` 里。
- **🔌 新设置字段的"可达性"清单(2026-10-12,issue #24 第二轮举报人指出)**:加了设置字段但没进设置面板,
对普通用户等于不存在(#23 的场景恰恰是"终端打不开、最需要自救"的那批人)。加字段时逐项过:
`PrefsSchema`/`WorkspaceSchema` → **三个 settings face 的 `read()` 都要回它** → 写入口(`updatePrefs` 在三个
face 都实现)→ 宿主端点(白名单字段)→ 客户端控件(`lib/client.js`)→ zh/en 双语键 → 测试
(`tests/settings-ui-reachability.test.mjs` 就是这条清单的沉淀)。
这里踩到的隐性 bug 值得单独记:`settingsFace.read()` 此前只回 `profiles`/`workspaces`,
于是 `read().writeBackFailure` 永远是 `undefined` —— **用户把设置写成 `"log"` 也不生效,只有环境变量管用,
而且不报任何错**。标量偏好要用 `prefsScalar`(注意 `false` 是合法取值,不能用 `||` 回退)。
- **🧾 包装脚本的每条分支都要有"实测"证据,而不是只有源码形状断言(2026-10-12,关 #23 前补测)**:
举报人复测通过但如实标注"本轮**没有**重跑负向控制",我这边补了三条分支的实测(PATH 里只留
`System32` + `WindowsPowerShell\v1.0`,先确认 `where node` 退出码 1):
| 场景 | 期望 | 实测 |
| --- | --- | --- |
| 写死路径有效、PATH 无 node(正例) | 越过往后正常起步 | 退出码 **0**,真的开出了 `Windows PowerShell` |
| 写死路径失效、PATH 无 node(负向控制) | 127 + 可操作提示 | 退出码 **127** + 那三行 `node not found` 提示 |
| 写死路径失效、PATH 有 node(回退) | 回退成立 | 退出码 **0** |
**踩到的坑(很容易被误读成产品 bug)**:造"写死路径失效"的副本时,我用
`-replace 'set "DSH_NODE=.*?"'` 一次替换了**三处** —— 连 `set "DSH_NODE="`(清空那行)和
`for /f … set "DSH_NODE=%%N"`(PATH 回退那行)也被换成了坏路径,于是脚本直接 `goto :run`
去执行不存在的文件,得到 cmd 的 `The system cannot find the path specified` + 退出码 **3**。
正确的做法是**只改那一行非空赋值**(按原编码读入 → `[string]::Replace` 精确替换那一行 → 按原编码写回;
该文件是 **UTF-8 无 BOM + CRLF**)。教训:**对照实验的"注入"本身要先验证注入成功**(打印改后的文件),
否则会把测量装置的故障当成被测对象的行为。
- **📋 尚未被"行为"覆盖的清单(据实登记,别当成已验证)**:① ~~写回桥 `writeBackFailure: "log"` 的写路径端到端~~
—— **2026-10-12 已补(2.4.26)**:把护栏 B 的判定与处置抽成三个可注入的纯函数
(`freshnessGuardPlan` / `applyFreshnessPlan` / `freshnessGuardCheck`),于是"log 模式被拦 → 不推送、不抛
(工具返回成功)"从**源码形状**变成了 `applyFreshnessPlan` 的**返回值**,测试里直接断言(`fs-write-bridge`
的 E5 段,98 → 121 条)。教训值得复用:**凡是"分支存在性"只能靠正则断言的地方,多半是这段逻辑埋在闭包里
了 —— 把它抽成纯函数(依赖从参数进、结果从返回值出),行为断言自然就有了**;抽完接线只剩三行。
抽的时候顺带发现一处实质缺陷:log 模式此前只记一行短提示,那份带补救步骤的长报告**只存在于被抛出的
错误里** —— 也就是说"只报告、不推送"在该模式下退化成"连报告都没有"(改成长报告也写进日志)。
② 暂无。
- **🚦 DSH 0.2.0-rc.1 起的「插件兼容性门」(2026-09-28,最重要)**:harness 用插件自己声明的
**DSH peer 版本范围**判定能否安装/激活;范围覆盖不到运行时版本时 `dsh plugin add` 直接拒绝
(`Plugin <name>@<v> is incompatible with dsh <runtime>: peerDependencies …`),已装的 bundle 也
**不会激活**(宿主里查不到该插件的 entry/tool),只能 `dsh plugin allow-version <pkg@ver> --dsh-version
<runtime> --accept-risk` 逐版本豁免(官方警告可能崩溃/丢数据)。判定是**严格 npm semver**:预发布
版本只被"元组相同且自身带预发布"的比较器接受 → **每条已验证版本线都要显式列出**,例如
`"^0.1.0-rc.6 || ^0.1.5-rc.1 || ^0.1.7-rc.2 || ^0.2.0-rc.1"`(`dsh-cron` 用同样的写法)。
`tests/manifest-compat.test.mjs` 用内置严格比较器守住这一点(`DSH_RUNTIME_VERSION` 可覆盖目标版本)。
另外:运行时不再提供的客户端包要从 `dsh.client.inject` 移除(0.2.0-rc.1 起没有
`@deepseek-ai/dsh-client-runtime`),否则客户端半边会去解析不存在的包。
- **🧪 升级前沙箱(2026-09-29 起已自动化,替代手工配方)**:内核升版前先在工作区跑
`dsh-preupdate-sandbox\preupdate-sandbox.ps1`(默认取 `npm dist-tags.next`,并与桌面端
nightly feed 的版本号对照)。它在**独立 `DSH_HOME`**
(`C:\Users\Administrator\dsh-sandbox\<版本>\home`)里装候选内核 + 当前插件栈,逐个插件过
兼容门禁、再真实启动一次自检,产出 `reports\<版本>\report.md`(PASS/BLOCKED + 逐插件结论 +
准确的修复命令)。**豁免只写沙箱 profile,绝不写主 profile。**
`-Upgrade <pkg@ver>` 用来验证「升级插件」这条治本路径;`-AllowRisk` 用来验证「豁免之后能不能
起来」。**升级前还要跑 `-Stage grant`**:把目标内核需要的豁免写进主 profile 的
`compatibility.json`(= 应用里点「接受风险」,但不需要应用能启动,带备份且幂等)——
必须在升级**前**做,否则应用因门禁起不来时那个按钮也点不到(死锁)。该 JSON **必须 UTF-8
无 BOM**(应用是裸 `JSON.parse`),所以用 `lib\grant-exemption.mjs` 写而不要手写/`Out-File`。
实测结论(0.2.0-rc.2):本插件 2.4.17 直接 OK(peer 已含 `^0.2.0-rc.1`);
被挡的是 better-sidebar 0.22.1(升到 0.24.1 即可,其 peer 已是 `^0.2.0-rc.1`)、
agent-teams 0.1.21、skill-mcp-panel 2.1.2(peer 明确 `<0.2.0-0`)、dsh-cron 0.14.3。
- **🚫 cordis 的 `inject` 没有 optional:第三方 bundle 提供的服务绝不要写进 `exports.inject`(2026-09-29,issue #18)**:
`Inject<M>` 只有两种形态 —— 字符串数组,或 `{ [K]: config|null }`(对象形态的 `null` 表示**拦截配置**,
**不是**"可选",`Inject.resolve()` 只产出 `{serviceName: config|null}`)。`Fiber._refresh()`(cordis 4.0.4
`lib/index.js` L1317-1329)里 `for (const name of Object.keys(this.inject)) { if (!this._store[name]) { epoch = INACTIVE; break } }`
—— **任何一个 inject 键对应的服务没注册,整个 fiber 就永久 pending**。前端 boot 会把 pending 的条目列出来并抛错:
`web boot: N entr… did not activate` + `<插件>: pending (waiting for service: <服务>)`,桌面端还会弹「插件恢复」。
实例:客户端半边曾写 `exports.inject = ["betterSidebar", "slots", "locale"]`,而 `betterSidebar` 只由
`dsh-better-sidebar` 这个**可选** bundle 提供 → 没装它的用户整块前端起不来(宿主照旧只是打一条
`patch: entry "better-sidebar" not found` 的 warn,很容易看漏)。**正确写法是子 fiber 软注入**:
`ctx.inject(["betterSidebar"], (bsCtx) => { … bsCtx.effect(() => bs.registerTab(…)) })`(前端自身用
`e.inject(["uiRenderer"], o => {…})`,本插件宿主半边软注入 `webRuntime` 同理);`exports.inject` 只留内核**一定**
提供的服务(`slots`/`locale`)。软注入回调在服务注册时执行,装与不装都安全。
- **🔬 复现「插件让前端起不来」这类问题的验证配方(2026-09-29 建,A/B/C 三例已跑通)**:
① 沙箱 profile 里按需增删依赖:`dsh plugin --profile sandbox remove <pkg>` / `add <pkg>@<ver>`(`dsh plugin`
就是 pnpm 直通,`remove` 可用);② 启动 `node <core>\lib\bin.js --profile sandbox --port <端口> --no-open`,
从 stdout 抓 `dsh web: http://127.0.0.1:<端口>/?token=…`;③ **用无头 Chrome + CDP 读前端真实状态**,
不要用 `--dump-dom --virtual-time-budget`(页面有长连接/定时器时**会挂死**,脚本卡到超时):
`chrome --headless=new --remote-debugging-port=9223 --user-data-dir=<空目录> about:blank`,再
`http://127.0.0.1:9223/json/version` 取 `webSocketDebuggerUrl`,Playwright MCP `browser_connect_roxy` 连上去后
`page.context().newCDPSession(page)` + `Network.setCacheDisabled` 再 `goto`(否则可能吃到旧 bundle),
然后 `page.evaluate` 读 `document.body.innerText`(失败时整屏就是 `Failed to load plugins` + 原因)与插件自己设的全局。
**判据别用 `window.__DSH_BOOT_READY__`:失败的场景里它同样是 `true`**(实测);可靠判据是 ① DOM 里有没有
`did not activate` 错误屏 ② 插件自己在 `apply` 里设的全局(如 `__dshRemoteSshGlobeStats`)在不在
③ 设置页里本插件的小节(如「远程连接」)出没出现。三例结论:已发布 2.4.17 + 无 better-sidebar = 整屏报错;
修复版 + 无 better-sidebar = 干净引导 + 设置页有「远程连接」;修复版 + better-sidebar 0.24.1 = 行为不变。
- **🧷 better-sidebar 的 `fs.*` 契约是「逐端点」的:上游新增/改名端点必须同步注册 exact 路由(2026-09-29 实例,issue 现象=「远程项目的侧边栏文件打开是本地目录」)**:
本插件靠注册 `/sidebar/api/fs.*` 的 **exact 路由**抢在 better-sidebar 的 `/sidebar/api` prefix 之前拦截,
**没注册的端点不会报错,而是静默回落到它自己的宿主实现(读本地 fs)** —— 表现就是"远程项目里看到本地目录"。
实例:`dsh-better-sidebar` **0.23+ 把文件树从「逐层 `fs.tree`」改成「一次 `fs.trees` 批量列举可见集」**
(工作区根 + 所有已展开目录,≤64 条;客户端按返回的 `level.path` 落缓存),0.24 又新增 `fs.mkdir`(新建目录)。
2.4.17 只注册了 `fs.tree` → 0.24 的整棵树绕过拦截、读本地镜像;新建目录也只建在本地镜像里。2.4.18 已适配 9 端点。
**同一个坑在「打开方式」上重演**:`open.external`(0.24 新增)宿主侧用本机打开器执行
(`explorer.exe /select,<路径>` / `rundll32 url.dll,FileProtocolHandler <url>`),客户端传的仍是**镜像路径** →
「在文件管理器中显示」打开本地镜像、「用 VS Code 打开」打开 `vscode://file/C:\…镜像…`。2.4.18 起拦截该端点,
远程工作区改开 `vscode://vscode-remote/ssh-remote+<别名><远端路径>`(`reveal` = 打开所在远端目录)。
别名必须**端口一致**才可用(非 22 端口 / 跳板机只能靠别名复用 ssh config 的 Port/User/IdentityFile/ProxyJump),
匹配逻辑是纯函数 `remoteEditorAuthority()`;拿不到别名就回退本机行为 + warn。**注意 `openWith.sshHost` 是反例**:
用户填了它,客户端会自行打开(宿主看不到),路径却仍是镜像路径 —— 文档里明确让人留空。
**每次升级 better-sidebar 后必做对拍(1 分钟)**:把它的宿主 handler 键集合与我们的注册数组逐项比对 ——
`node -e "const s=require('fs').readFileSync(process.argv[1],'utf8');console.log([...new Set([...s.matchAll(/\"(fs\.[a-zA-Z]+)\"/g)].map(m=>m[1]))].join(' '))" "<profile>\node_modules\dsh-better-sidebar\lib\index.js"`
(客户端真实调用侧看同一包的 `lib/client.js` 里的 `call(\"fs.*\")`;`fs.tree` 仍要保留 —— 旧版客户端与编辑器侧栏都在用)。
两条分支**都必须实现**:exact 路由会连本地会话一起抢占,只在远程分支处理会让本地工作区的该端点 404、反而弄坏原本正常的功能。
**接管的不只是端点,还有路径语义**(2026-10-13 issue #25,实测复现)—— 被接管的原实现按**会话 cwd / worktree 根**
解析相对路径(`ensureWorkspacePath(activeWorktreeRootOf(ctx, sessionId, sessionCwd), raw)`),本插件早期版本把
`payload.path` 原样交给 `fs`,Node 于是按**插件宿主进程的 `process.cwd()`**(pnpm profile 目录)解析。在运行中的
宿主上实测(2.4.26,只发只读请求):
① `GET /sidebar/file?sessionId=<假>&path=tools/check_file_size.py` → `400 cannot read: ENOENT … stat '<profile>\tools\check_file_size.py'`(与举报人给的一字不差);
② `POST /sidebar/api/fs.read {path:"package.json"}` → **200,返回的是 profile 自己的 `package.json`**(比 ENOENT 更坏:静默读到错文件,用户毫无察觉);
③ `fs.tree {path:"."}` → 列出 profile 目录(`.plugin-manager`、`node_modules`…);④ 同一文件换**绝对路径** → 200(所以"只有相对路径坏",极难自查)。
写操作同理:`fs.write` / `fs.remove` 拿到相对路径会在**插件宿主目录**里写/删(能覆盖 profile 里的同名文件)。
**修法(2.4.27)**:模块级纯函数 `resolveSessionPath(raw, base)` + `unresolvedPathMessage()`,**每一处落点都过它**
(`/sidebar/file`、`fs.read/tree/trees/write/rename/remove/mkdir/search` 的本地与远程分支、`git.*` 本地分支、`open.external`);
取不到会话 cwd 时**一律报错,绝不回退 `process.cwd()`** —— 那个兜底正是 bug 本身。`fs.trees` 逐条报错(一条坏路径不拖垮整棵树)。
**测法(可直接复用)**:切片真实 handler + 假 `ctx/req/res`,把 `process.chdir()` 到一个"插件宿主目录"并放 **canary 文件**,
断言相对路径落在会话 cwd 下、canary **既读不到也删不掉**、拿不到会话 cwd 时必须报错。
并做**变异负向控制**(把修复点改回旧行为,确认测试真的会红):本处两处变异分别让 12 条 / 2 条断言变红 ✓。
**2026-10-14 实例:0.25.0 升级后对拍查出 6 个端点未接管(不是用户报的 issue)** —— 桌面 profile 被应用升到
`dsh-better-sidebar@0.25.0`(0.24.1 → 0.25.0),照上面的规则比对「宿主 handler 键集合 vs 本插件注册集合」:
fs 由 8 变 9(新增 `fs.createFile`),git 由 14 变 21(新增 `git.blame` / `commit-model` / `diff-head` / `models` /
`pull` / `push` / `suggest-message`),而本插件只注册了 fs 8 / git 13。**判据是「这个端点碰不碰路径或仓库」**:
必须接管的 6 个 —— `fs.createFile`(`cwdOf` + `createWorkspaceFile({cwd,path,name})`;不接管就只在镜像里建空文件,
远端永远没有)、`git.blame` / `git.diff-head`(`ensureWorkspacePath` + `runGit(repoRoot(cwd))`)、
`git.worktrees`(0.24.1 就有、此前也漏了)、`git.pull` / `git.push`(`runGit(repoRoot, ["pull","--ff-only"] /
["push"])`,会在镜像那个跟远端无关的仓库上动);**不必接管**的 3 个 —— `git.models` 走 `ctx.get("llm")` 列
provider、`git.commit-model` 只出现在客户端、`git.suggest-message` 虽然读 `status(cwd)` 但只用于生成提交信息
(已知小瑕疵:它取的是镜像状态)。
2.4.28 已接管这 6 个,并把对拍**自动化**:`tests/sidebar-0250-endpoints.test.mjs` 的 C8/C9 会读本机
`~/.dsh/profiles/*/node_modules/dsh-better-sidebar/lib/index.js`(没装则 SKIP、不算失败),把宿主键集合与本插件
注册集合逐项比对 —— **升级 better-sidebar 之后跑一次全量测试即可**,不必再手抄键名。同一个文件的 D 段还做
**语义差分对拍**:把上游的 `assertCreatableFileName` / `isoWithOffset` / `parseBlamePorcelain` / `parseWorktreeList`
用 `grabFn` 式切片抽出来,与本插件实现喂同一批输入、逐条比较(含拒绝文案)—— 注册齐了但语义走样同样会红。
该测试还钉住三条容易重犯的事:
① 模型类端点**不许**进 `GIT_METHODS`(它们不碰路径,注册反而剥夺上游能力);② `git.worktrees` 这类"每个条目各有
自己的根"的端点必须用**条目自己的目录**跑命令(复用会话 cwd 的 `run` 会把 status 跑错目录)—— 断言 `runGitRemote`
收到的是 `/remote/wt2` 而不是会话/镜像目录;③ "已存在"=409、"形状不对"=400+`bad-request`(本地分支曾一律给
400 + `fs-error`,连自己的远程分支都不一致)。
**远端建空文件用 `(set -C; : > <path>)`(noclobber)**:探测与创建之间若有人抢先建了同名文件,这里只会失败,
不会清空别人的文件(对齐上游 `writeFile(…, {flag:"wx"})` 的语义);本地分支用 `writeFile(dest, "", {flag:"wx"})`。
`git.pull` 成功后要做两件事:整棵远端列举缓存失效(工作树可能变了)+ 清掉写回桥的**远端指纹**记录
(`freshnessForgetProfile`)—— 那些记录描述的是 pull 之前的远端内容,留着会让下一次写回被误判成"远端已改动"而拒写。
**🧭 真机验证 2.4.28 的实据(2026-10-14,宿主重启后进程全为 10:18:45 启动)**:直接对
`POST http://127.0.0.1:<port>/sidebar/api/<method>` 发请求(body `{sessionId, cwd|path}`,与本插件注册的 exact 路由同形):
① `git.worktrees`(真实 sessionId)→ `/data/run01/<user>/zfs/codex/DFS-Dev`、`current: true`、`changes: 27` ——
**远端绝对路径**只可能来自远端分支(镜像里没有 `.git`,上游实现只会给 `[]`),这是"新端点已接管且跑在远端"的硬证据;
② `git.blame Project.toml 1-5` → 真实作者/时间(`+08:00` 偏移)/中文 summary,且同一 commit 的后 4 行复用首块信息
(porcelain 语义在真实数据上成立);③ `git.diff-head` 返回 `{diff:"\n"}` —— 与**既有** `git.diff` 对同一干净文件的返回
完全一致,说明多出的那个换行是远端运行器的既有归一,不是 0.25.0 新端点引入的;④ `fs.createFile` 非法名 → 400 +
`bad-request`(上游文案);正常创建 → 200,文件**真的在远端**(SSH `stat` 0 字节)且**本地镜像里没有**(只写远端);
同名再建 → 409;⑤ `changes` 27→28→27 与**我用自己 SSH 数出来的 27/28/27 完全一致**(`countStatusEntries` 口径正确);
⑥ `fs.remove` 往返后远端文件消失、镜像干净、git HEAD/分支/worktree 列表未动。
**验证纪律**:插件报告 ≠ 事实 —— 写完必须用**自己的 SSH**独立核对,核对完清理到原状(远端 status 计数与
`git rev-parse HEAD` 都要回到初始值)。
**找"活的" sessionId 的办法**:`<DSH_HOME>\sessions\--<workspace-slug>--\` 下的目录名即历史 sessionId,
但只有**宿主注册表里仍在的**才可用 —— 探测方式是发一次只读的 `git.worktrees`:能解析的返回远端路径,不能解析的
**如实报错**("无法确定会话工作目录…"),这本身也是 2.4.27"绝不猜 `process.cwd()`"的行为。
**⚠️ 远端判定只认"正好放着 `.remote-ssh.json` 的那一级目录"(实测,未来加固的候选)**:
`readRemoteInfoSync(p)` 的实现就是 `JSON.parse(readFileSync(join(p, ".remote-ssh.json")))` —— **不向上遍历**。
真实客户端总带有效 `sessionId`,而会话 cwd 就是**镜像根**,所以永远命中;但**回退路径**(取不到会话 cwd 时改用
`payload.path` 判定)只有当客户端给的正好是**工作区根**(或某个自带 `.remote-ssh.json` 的目录)时才命中。
实测:假 sessionId + 绝对**文件**路径 → `fs.remove` 落进**本地分支**,报 `400 ENOENT … lstat '<镜像路径>'`
(远端什么都没动 —— 是"删不掉",不是"删错地方");换成真实 sessionId 后同一请求 → 200 且远端文件消失。
风险点:若客户端带着**过期/未知** sessionId 发来镜像根**之下**的绝对路径,`fs.write` / `fs.remove` 会**静默作用于镜像**
而不是报错 —— 与 2.4.27 修的那类"落到错误位置"同源。加固方向二选一:向上遍历找到工作区根,或在"绝对路径 + 无法确定
会话 cwd + 该路径可能属于某个镜像"时**明确报错**;两者都要新的小版本 + 一轮真机回归。
**✅ 2.4.29 已按"两个都做"加固(2026-10-14)**:新增 `remoteWorkspaceForPath(absPath)` —— 复用本来就有、
只是没被 fs 判定用上的 `matchRemoteWorkspace`(它是**前缀**匹配)把任意绝对路径匹配到已注册工作区,再取该根下的
`.remote-ssh.json`;fs 判定的两条路(会话 cwd / `payload.path`)与 `@` 引用补全都改走它。加上 `isUnderMirrorBase()`
的明确报错分支(镜像根之下却不属于任何已注册工作区 → 读写都 400,绝不在镜像上动手)。**顺带修掉一个此前没被注意的
映射 bug**:命中时必须以**工作区根**当 `remoteBase`,拿传进来那条更深的路径当基准会让 `localToRemote()` 少一段
路径段(子目录会话 + 相对路径必然踩到)。教训有两条值得记住:①**同一件事有两套判定方式时,弱的那个迟早会被走到**
(`gitContextOf` 一直用前缀匹配,fs 判定却用精确匹配,于是只有 fs 出问题);②**"能命中"和"命中后基准对不对"是两件事**
——后者不会报错,只会静默把文件放到错位置,只能靠断言"远端命令里的完整远端路径"抓。测试见
`tests/remote-workspace-root.test.mjs`(39 条断言 + 7 个变异全部被抓),判定相关的函数一律用**真实源码**、不 stub。
**重构会让老的形状断言失效**:`fs-trees-contract` / `open-external-contract` 里 5 条断言指向被改掉的代码文本 ——
这时要先判断"它保护的**契约**变了没有"(本次都没变,只是变量名/新增了归一这一步),再改断言指向新代码,
**不要直接删**,也不要为了让测试变绿而放宽契约。
**上游的路径阶梯要照抄语义**(2026-10-13 从装好的 `dsh-better-sidebar/lib/index.js` 里读出来的事实,
举报人在 #25 的评论里也提供了同一事实):
`buildApi` 的 `cwdOf(payload)` 用 `requireString(payload, "sessionId")` —— **sessionId 是必填**,且把 `payload.cwd`
当 `clientCwd` 传给 `sessionCwdOf(ctx, sessionId, clientCwd)`;阶梯是
**会话注册表 `ctx.sessions.get(sessionId)?.header.cwd` → 客户端 cwd(`requireAbsolute()`,非绝对即 400)→
`sessionPersistence` 持久化元数据 → `process.cwd()`**。`gitCwdOf = cwdOf + resolveWorktree(worktree)`(`worktree` 同样"从不直接采信");
`ensureWorkspacePath(cwd, target)` 就是 `resolveTarget(cwd, target)`;**git 的 pathspec(`add/reset/checkout -- <path>`、
`show <rev>:<path>`)是仓库相对路径,不按会话 cwd 归一**,别顺手"修"它们。
两条可操作的结论:① 真实面板流量**一定带 sessionId**,所以"取不到会话 cwd 就报错"这条兜底不会影响正常客户端
(它替换掉的 `process.cwd()` 尾级实际是死代码);② **客户端给的 cwd / worktree 必须自己校验绝对性** ——
`join(相对 base, 相对 path)` 拼出来仍是相对路径,fs 又会按 `process.cwd()` 解析,等于把 #25 放回来。
本插件没有引入 `sessionPersistence` 那一级(需要上游内部 API),如实记为已知差异。
`fs.trees` 的响应形状必须对齐上游:`{ levels: [{ path(回显客户端传入的路径,客户端拿它当缓存键), entries, truncated, error? }] }`,
单层失败**不**让整批失败;远端批量列举用 `remoteListDirsBatch()`(`__DSH_LVL__` 标记分段,**一次 SSH 往返**列举 N 个目录,
别退化成 N 次 SSH),命中 `treeCache` 的层 0 RTT。
`open.external` 的宿主命令形状(三平台)与上游 `revealCommand`/`urlCommand` 逐字一致(纯函数 `openerCommand()`,
argv 数组、不经 shell、`detached`+`unref`);自动化验证用 **`DSH_REMOTE_SSH_NO_LAUNCH=1`** 干跑,避免测试真的弹出
VS Code / 资源管理器窗口。远程打开要过三关:工作区归属(`matchRemoteWorkspace`,该端点**没有** sessionId/cwd)→
ssh 别名(端口一致才可用)→ `~` 展开(URL 不过 shell;`printf %s "$HOME"` + 10 分钟缓存),任何一关不过都**回退本机 + warn**。
- **🧪 沙箱里装本地 tgz 做验证时:同版本 + 同路径不会重装(2026-09-29 踩到)**:`dsh plugin --profile sandbox add file:…tgz`
对**已装的同一版本号**直接跳过(pnpm 认为已满足),于是"验证通过"其实是旧包在跑 —— 必须先断言包内确实有新代码,
例如 `Select-String <profile>\node_modules\<pkg>\lib\index.js -Pattern '<新增函数名>'` 或把 tgz **换个文件名**(新的
`file:` spec)再装。煞尾:改动后重打包 → 换名 → 装 → 断言符号存在 → 再启动实例验证。
- **🖥 desktop profile 只能由应用内插件管理器改(2026-09-28 起)**:`dsh plugin --profile desktop …`
会被无条件拒绝(`profile "desktop" is managed exclusively by the Electron application`,
`rejectElectronProfile` 无开关)。想手工升级只会遇到两个护栏:① profile 的 node_modules 由**特定
版本**的 pnpm 建(`.modules.yaml` 里记 `packageManager`/`storeDir` 是 `store\v11`),换版本就
`ERR_PNPM_UNEXPECTED_STORE`;② harness 给 pnpm 传了 `minimumReleaseAge` 供应链策略,**刚发布的版本
在时限内会被拒**(`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`)。所以:让用户去应用的插件管理器更新,
不要手工 pnpm / 直接改 package.json。用户自己装的版本若被兼容性门挡住,可让他点"接受风险"豁免(前提是
该版本代码本身已适配,例如 2.4.15 与 2.4.16 的代码相同、只差 peer 声明)。
- **🔎 用运行中的宿主做接口对拍**:`cordis_inspect_list` → host `Service.listService`(不带参数出目录,
带 `{service}` 出该服务契约)、`Config.listConfigs`(`{name: <包名>}` 查自己的 entry;`{entry}` 取投影
schema)、`Tool.listTools`(插件是否真的注册了工具)、client `Slots.listSubTree`(客户端槽位是否存在)。
0.2.0-rc.1 里 Config 目录用 `include:<patchId>` 命名,但 **patch 仍按 `patchId` 命中**(我们的
`terminal-controller` patch 因此照旧生效);`settings.describe()` 的 `ns` 也仍是 `remote-ssh` 这类 patchId。
`webRuntime`(信任围栏的信任源)在 0.2.0-rc.1 已被移除 → 2.4.32 起改读 **`ctx.webStartup.trustedHosts`**
(宿主 `dsh-web-app/lib/startup.js` 里 `ctx.provide("webStartup", …)`,"ordinary Cordis service"、无
`isolate`,插件 entry 可注入;宿主自己的 `connection`/`webserver` 行也是 `inject: [webStartup]`)。
两个服务都**软注入**:新宿主走 `webStartup`、老宿主走 `webRuntime`、都没有则退回 loopback-only
(桌面端本身 `networkExposure: loopback`,功能无损失)。**注意**:宿主 0.2.1-rc.1 起 `/api` 围栏还多认
"监听绑定 IP 字面量"(`webStartup.host`)这一例外,而本插件只认 loopback + trustedHosts ——
这是**有意更严**(本插件的路由在宿主浏览器令牌认证栅栏之外,放宽会把远端的文件/终端能力暴露给同网段),
需要远程访问时用 `--trusted-host` 显式授权。
- **🧩 DSH 0.1.7-rc.2 起的 settings 模型(2026-09-28 适配,issue #16)**:`settings` 服务
**没有** `register(ns, schema)`,改为 `configure / describe / update / replace / mutate`;
用户偏好存放在**本插件 loader 行的 Config**(命名空间 = **entry id / patchId**,我们 bundle 里是
`remote-ssh`;而旧 settings 的 section 键是**包名** `dsh-remote-ssh` —— 这导致旧数据不会自动迁移)。
三条硬约束:
1. Config 字段必须 `.volatile()`,且**必须用 `@deepseek-ai/schemastery`**(公共 `schemastery`
没有该实现 → Loader 的 volatile-commit 路径不提交 → 写入"报成功但值不变");
2. 读:`describe({ redactSecrets: true }).find(d => d.ns === entryId).value`(实测 value 里是
**已解析的普通数组**);`apply(ctx, config)` 里同名字段是**带 `.get()` 的引用对象**,两者都要兼容;
3. 写:`settings.update(entryId, patch, revision)`(revision 取自同一次 describe)。
旧数据迁移:读 `$DSH_HOME/settings.yaml.imported`(退 `settings.yaml`)里旧 section,
**仅当该 entry 用户层为空**时 `update` 导入;并把导入值放内存兜底,让升级后**第一次启动**就能看到。
- **🧪 兼容性验证配方(不打扰用户正在用的会话)**:把**目标版本的官方 CLI**装到临时目录
(`npm i --prefix <tmp> @deepseek-ai/dsh@<版本>`;注意 PATH 上的 `dsh` 可能是很久以前装的全局版本,
别用它,否则测的不是目标版本),用 shipped 模板建一次性 profile(复制 `profiles/web` 的
`package.json`/`cordis.yml`/`cordis.patch.yml`/`pnpm-workspace.yaml`),
`node <tmp>/node_modules/@deepseek-ai/dsh/lib/bin.js plugin --profile <one-shot> add file:<tgz>`,
再 `node <tmp>/…/bin.js --profile <one-shot> --port <spare> --no-open`(后台跑),最后 curl 插件 API:
`POST http://127.0.0.1:<spare>/remote-ssh/api/listProfiles` 带 `x-requested-with: XMLHttpRequest`。
**注意响应是 `{ok, value:{…}}` 信封**(曾因只读顶层字段而误判"全空")。验证完删掉该 profile 与临时
CLI 目录。`DSH_REMOTE_SSH_DEBUG_SHAPE=1` 会让插件把 settings 形状探针写到 `$DSH_HOME`。
- **🚫 禁用状态记在 `desktopDeselectedBundles`**:profile 的 `package.json` 里
`dsh.desktopDeselectedBundles` 列出的包即使仍在 dependencies 也不会挂载;
`dsh plugin add` **不会**替你清掉它 —— 恢复启用要把它从该数组移除、并确认包在
`dsh.profile.bundles` 里(顺序:本插件应在 `dsh-better-sidebar` 之后)。
- **🔒 公开产物里绝不出现真实主机 / 账号 / 项目 / 路径 / 镜像 ID(2026-09-20 用户明令)**:
issue 回复、README、CHANGELOG、代码注释、测试夹具**一律用通用占位符**。曾把真实项目名、
HPC 主机名、内网 IP、真实远程路径、镜像目录 ID 写进 issue 回复与仓库文档,属于信息泄露
(本文件早先的版本甚至把这些真实名字当"例子"列了出来 —— 记录规则时也不要写具体值)。
占位符约定:`proj-a` / `my-project` / `project-b`(项目)、`~/proj`、`~/work/my-project`(路径)、
`hpc-a.example.com`(主机)、`192.0.2.10`(内网 IP,TEST-NET-1 文档网段)、
`wmirror1`…(镜像 ID)、`solver`(查询词示例)。
**发布前必查**(`gh-fix/scan-private.mjs` 同款逻辑,或直接 grep):
```powershell
node <scratch>\scan-private.mjs <repo> # 枚举镜像 ID / 主机名 / 账号 / 真实路径 / 项目名 / 内网 IP
```
唯一允许保留的私人字样是 README 七夕段落里的署名 `zhangyi`(刻意保留的私人寄语,见下条)。
发布后若发现泄露:先改 issue 评论(`gh api -X PATCH .../issues/comments/<id> --input <payload.json>`)
与仓库文件,再处理 npm 产物(`npm unpublish <pkg>@<ver>` 后重新发布同一版本,或发新补丁版)。
- **🚨 改完 `lib/index.js` 必须跑模块加载冒烟(2026-09-20 血的教训)**:曾把
`const REMOTE_SEARCH_SKIP_DIRS = new Set([...REF_EXCLUDED_DIRS, …])` 写在
`REF_EXCLUDED_DIRS` 定义**之前** —— 模块级 `const` 的展开会在模块求值期立即读取该绑定,
于是抛 `ReferenceError: Cannot access 'REF_EXCLUDED_DIRS' before initialization`,
整个插件树加载失败(`dsh-plugin-desktop: plugin tree failed to load`),
**用户连桌面都进不去,只能卸载插件**。
当时的测试全都只从源码里「提取函数/常量文本」再单独求值,所以完全测不出来。
现在有 `tests/module-load.test.mjs` 兜底(两层:① 真实 `import()` 模块;
② 带花括号深度的静态扫描,只查模块级引用顺序),并且可以指定目标文件做上机前冒烟:
```powershell
node tests/module-load.test.mjs # 检查仓库源码
$env:DSH_TEST_MODULE="$env:USERPROFILE\.dsh\profiles\desktop\node_modules\@zhangfengshun\dsh-remote-ssh\lib\index.js"
node tests/module-load.test.mjs # 检查「DSH 将要加载的那个文件」
```
发布前请把上面两条都跑一遍(第二条是上机前最后一道闸)。
- **本地装包要用新文件名**:pnpm 会按 tarball 路径缓存 —— 用同一个文件名重复
`dsh plugin --profile desktop add file:…tgz` 时可能**沿用旧内容**(现象:装完发现包内没有新代码)。
重新打包后换个文件名(如 `-tdzfix.tgz`)或先 remove 再 add。
- **🚫 README 的「## ❤️ 七夕快乐」段落是固定内容,任何文档改版都不得删除、改写或移位**
(`README.md` 中文版 + `README_EN.md` 的 `## ❤️ Happy Qixi` 对应段落,含
「本项目是送给 **zhangyi** 的七夕礼物。」三行与落款日期 2026 年 8 月 18 日)。
这是仓库作者对所有者的私人寄语,不是可裁剪的营销文案——新增章节一律插在它**上方**
(「更新日志 / 许可证 / Star 引导」等尾部内容保持在其下方)。改动 README 后用
`grep -n 七夕 README.md` 与 `grep -n Qixi README_EN.md` 自检,并确认 GitHub main
与 npm 产物内均在。
- 桌面 profile 中插件顺序要求:`dsh-better-sidebar` 在
`@zhangfengshun/dsh-remote-ssh` 之前(README 的先后要求),不要打乱。
- awesome-dsh-plugin 投稿已合并 PR #4268(2026-09-04);列表 README 是自动生成的,
后续若要改条目,改的是 `data/plugins/zhangfengshun__dsh-remote-ssh.yml`。
- DSH Market 评分(实用五维,权重 维护 30 / 实用 25 / 热度 20 / 便捷 15 / 信号 10):
- **信号质量**五项完备度 = description / license / topics / **homepage** / README
——GitHub 仓库 homepage 曾为空(2026-09-12 已补为 npm 页面),改仓库设置时不要清空;
- **实用度**看 README 结构:安装 / 使用 / **代码示例** / 功能说明——新增功能时同步补示例;
- **便捷度**要求「一条命令可装 + 无需 token/API Key」,不要引入需要额外配置的依赖;
- **热度**由真实 star / fork 决定,无法通过文档操作提升。
- `screenshots.json`(storefront 展示图清单)与 `assets/` 截图在仓库里,发布
README 变更时记得同步。
- **报错文案的第一性:掩埋一手证据等于把用户引向错误方向(issue #19,2026-10-04)**:
腾讯云那台机器的失败原因其实只有一行 —— `Warning: Identity file … not accessible`(配置的私钥
文件根本不存在),但它 ① 不是 `debug1:` 行,正好被 `testConnection` 的 `-v` 诊断过滤器漏掉;
② `/etc/ssh/banner.txt` 的**预认证登录横幅**(扫码二维码 ASCII 画)塞满了「原始信息」的 300 字
截断窗口 —— 用户于是判断成"是扫码导致的连接失败",把维护者也带偏。现在固化成五条纪律
(实现:`stripLoginBanner` / `findMissingIdentityFile` / `offeredAuthMethods` / `sshExcerpt`):
1. **一手证据优先**:stderr 里能直接读出的确定事实(哪个私钥文件不存在、哪个端口被占)放在提示
第一条,并**原样回显路径/端口**;泛泛的"公钥认证失败"必须让位。
2. **诊断行白名单**:任何降噪都要先放行 `debug\d+:` / `Warning:` / `Permission denied` /
`Authentications that can continue` / `Identity file` / `Connection …`,短行也保留。
3. **截断按诊断取,不按位置取**:`slice(0, N)` 会被装饰性输出(横幅、二维码)吃光。
4. **能力边界写进报错**:远端"允许"交互式认证 ≠ 插件"能用"—— 文件/工具能力是
`BatchMode=yes` + `PreferredAuthentications=publickey` 的非交互通道,扫码/动态口令只能走内置
「终端」页签(`ssh -tt`,wrapper 里不设 BatchMode)。凡"用户容易以为是 bug、其实是设计"的地方,
都要在文案里点明并给替代路径。
5. **回归 fixture 用举报人的真实 stderr(脱敏后)**:`tests/auth-error-diagnostics.test.mjs` 直接把
#19 贴出的那段(二维码 + Warning + `Permission denied(…)`)喂进 `sshErrorHint`,比自造样例更能
防住回归;并配一条"远端只提供公钥"的负向控制,防止提示越写越长。
- **🗑️ 「先删后取」+「静默失败 × 唯一通道」= 数据丢失(issue #20,2026-10-11;纪律级)**:
`remoteSyncDown` 曾把顺序写成 `rm -rf 镜像 → tar 拉取`,于是**删除发生在任何成功证据之前**。
单独看这只是"失败后镜像空了、重跑一次就好";真正致命的是它旁边的**静默失败**:agent 的 `write`
超过 `MAX_BYTES`(4 MiB)时**本地镜像写入已成功**、`remoteWriteFile` 拒绝推送,宿主侧只打一行
`warn`(模型与用户都看不到)—— 于是镜像里躺着一份**只存在于本地**的成果,下一次 sync(哪怕随后
失败)就把它永久删掉,而且全程没有任何提示。issue #20 的作者用一个 46 G 的"代码 + 数据集"混合根
把这条路径讲透了(他还特意区分"真实函数 + 真实进程的实测"与"46 G 规模的推断")。固化成六条纪律
(实现:`probeRemoteBytes` / `swapMirrorDir` / `scanMirrorOnly` / `sweepStaleSyncDirs` / `runTarPipe`):
1. **破坏性操作排在最后**:删除/替换之前必须已经拿到了成功证据。这里的顺序是
*体积哨兵 → 解包到临时目录 → 比对 → 原子替换*;任何一步失败都保留旧状态,错误信息里明说
"本地镜像未改动"。**测试断言的是「rm 调用序列为空」**,不是"报错文案里有某句话"。
2. **静默失败要有出口**:只在日志里 `warn` 的失败,必须在**模型可见**的地方留下痕迹(工具描述、
下一次同工具调用的返回值、或写进镜像的说明文件)。"副作用已落地但调用方不知道"是最危险的状态。
3. **唯一通道要当心**:镜像自 2.0.0 起是**单向出站缓冲区**(没有其它 remote→local 通道),
于是 `sync` 成了唯一回拉手段,也成了唯一的删除入口 —— 唯一入口上的破坏性语义必须自带护栏。
4. **量了再删**:`du -sb -c -- <本次范围>`(带预算)→ 超限/超时/不可解析一律拒绝 + `force` 逃生门。
保守方向永远是"多要一个参数",而不是"替用户决定删掉什么"。⚠️ 探测范围要**跟着 paths 走**,
否则"我只想同步 src"会被整根的 46 G 误伤。
5. **"本地独有"要能被识别**:整树替换前比对镜像与拉取结果,命中就拒绝并回传清单(`onlyMirror`),
同时排除插件自有文件(`.remote-ssh.json` + 按**首行指纹**识别的占位 README)—— 否则每次同步都
误报,护栏很快会被用户当成噪音而绕过。
6. **回滚路径也要写清楚**:`swapMirrorDir` 失败会先删掉半成品再把旧目录 rename 回来,若连回滚都
失败,错误信息必须给出旧目录的**绝对路径**(数据还在,只是挪了地方),不能只说"替换失败"。
7. 附带一条实现经验的坑:**超时定时器不要 `unref()`** —— 这个 bug 是新测试抓到的:`unref` 过的
定时器在事件循环空转时会被跳过,而"两端进程都卡住、没有其它句柄"恰恰是最需要它触发的场景
(旧实现连墙钟预算都没有,46 G 拉取只能杀进程)。
8. 举报人自己做了一版本地补丁(四个入口统一 deny-by-default + 环境变量放行)。回复时明确说明
正式修复**不需要**那套环境变量(默认就有哨兵),并把他的思路(临时目录 + 原子替换、体积哨兵、
范围下推、push 白名单)落进实现 —— 举报人给出可用方案时,优先评估并入而不是另起一套。
- **🧩 argv 是有语法的:`-o` 与它的取值之间不能插任何东西(issue #21,2026-10-11;纪律级)**:
终端 wrapper 曾用**位置插入**给 ssh 加 ProxyJump ——
`args.splice(2, 0, '-J', j.proxyJump)`,而索引 2 正好是 `-o`(索引 1)的下一个位置,于是命令行成了
`ssh -tt -o -J jump-host StrictHostKeyChecking=no …`:ssh 把 `-J` 当成 `-o` 的关键字(关键字比较前
小写化 → 报文里显示 `-j`)→ `command-line line 0: no argument after keyword "-j"` → **退出 255**,
只要连接填了 ProxyJump,内置终端就永远打不开(2.4.18 起就坏了,一路发到 2.4.20)。四条纪律:
1. **顺序构造,不要位置插入**:`push` 出一段一段的"选项 + 取值"(或 `[opt, val]` 数组再摊平),
永远不要用 `splice(固定索引, …)` 往别人的对子里塞东西 —— 索引会随上下文漂移,而报错发生在
ssh 那边、离现场很远(用户只看到 255 与一句让人摸不着头脑的 `no argument after keyword "-j"`)。
2. **每个选项都要有配对断言**:`for (i) if (args[i] === '-o') assert(args[i+1] 含 '=' 且不以 '-' 开头)`。
这类不变式写一次就能守住后续所有新增选项(本次同时覆盖了 `-J` / `-p` / `-i`)。
3. **让真实工具当判据,而不是自己解释规则**:`ssh -G <argv>` 只解析命令行与 config、**不建立连接**,
于是"这串 argv 合不合法、ProxyJump 有没有真的生效"可以在离线、无凭据、无网络的情况下由 ssh 自己回答
—— 断言 `ssh -G` 的 exit 0 与转储里的 `proxyjump jump-host`;再配一条负向控制(把 `-J` 插回坏位置,
同一判据必须失败并复现原报文),证明判据本身有牙齿。本机 `OpenSSH_for_Windows_9.5p2` 与举报人同版本,
复现出的报文**逐字节相同**。
4. **测试断言了文件 ≠ 覆盖了分支**:`tests/wrapper-terminal.test.mjs` 早就把 wrapper 的 argv 断言得
很细(`-tt`、端口、密钥、`user@host`、远程命令),但**没有任何场景设置 `proxyJump`** —— 分支没被
走过,坏形状就一路绿灯。凡"由输入组合决定的 argv",每种组合都要有场景;缺哪种组合,就在测试里
显式列出来(本次补了 3 个 proxyJump 场景 + 1 条结构不变式 + 1 条 ssh 离线判据)。
5. 找同类问题的手法:`Select-String -Pattern "splice\(|'-o'|StrictHostKeyChecking"` 把全仓 argv
拼接点列出来逐个核对 —— 本次确认插件自己的 `sshArgv()`(`opts.push("-o","ProxyJump="+…)`)写法正确,
只有 wrapper 这一处坏了,这也正好解释了举报人"模型工具正常、只有终端不行"的观察。
- **🧷 同一个 helper 不能跨 shell 边界(issue #22,2026-10-11;纪律级,issue #21 的第二天又犯一次同类错)**:
`syncTarExcludes()` 用 `shellQuote()` 把排除模式包成 POSIX 单引号。**sync 方向**这是对的(结果被拼进
**远端命令字符串**,要由远端 shell 解释);**push 方向**同样的字符串作为 **argv 元素**交给本地 tar,
argv 不经 shell —— 引号成了模式的**字面字符**,于是 `--exclude='./x'` 匹配不到 `./x`,
**所有排除静默失效**:`.remote-ssh.json`(含 host/user/keyPath/remotePath)与占位 `README.md`
真被解到了用户远端根,2.4.20 CHANGELOG 里"连接信息绝不推到远端"的承诺当时是假的。
举报人(SundaeYAGO)用真实 bsdtar + 插件生成的精确 argv 复现,还给了 A/B 对照与修法。六条纪律:
1. **按语境分叉,不要"顺手复用"**:同一个逻辑产出物要喂给「shell 命令字符串」和「argv 数组」时,
必须显式区分(`forShell` 开关之类),并在注释里写清哪边是哪边 —— 这是 issue #21(argv 位置)
与 #22(argv 引号)连着两天踩到的同一类边界。
2. **静默失效比报错危险得多**:`GNU tar` / `bsdtar` 对"不匹配任何成员"的 `--exclude` 都 **exit 0**、
无任何提示;`ssh` 那边则是 255 + 一句看不懂的报文。凡"外部程序按自己的语法解释我们的字符串"的地方,
都要有**真实工具端到端**的断言,而不是只断言我们拼出来的字符串。
3. **冒烟测试必须消费"生成出来的 argv"**:2.4.20 我自己做过 tar 冒烟,但 argv 是**手打**的(正好写成
正确形态),于是假阴性放行 —— 正确做法是捕获真实 spawn 的 argv 再喂给真实 tar(本次 H-A 段)。
4. **断言产物 ≠ 断言行为(两天内第二次)**:#21 是"测试覆盖了文件却没覆盖分支",#22 是"测试把 bug
的形状一起断言了"(D/F 段原本断言 `--exclude='./x'` 带引号)。新写的断言要问一句:**如果这段代码
坏了,这条断言会不会照样通过?** 会的话它就不是回归测试。
5. **泄漏类缺陷必须配负向控制**:不仅要断言"现在不漏",还要证明"判据能抓到漏"——把模式重新加引号,
同一判据必须判失败并复现旧行为(本次实测 bsdtar 3.8.8 确实漏)。
6. **善后要写进 release 与回复**:已经泄漏到用户远端根的文件不会自己消失,发布说明里要给"自查自清"
步骤(对比 size、删掉多出来的两个文件),别只写"已修复"。
- **🔤 「同一份字节流,两端对名字该怎么解码」的默认假设不同(issue #22,2026-10-11;与上面那条互为姊妹篇)**:
Windows 上的 `remote_ssh_sync` 把 `报告_2026Q1.csv` 拉成 `鎶ュ憡_2026Q1.csv` —— **内容完好、exit 0、
stderr 为空**,七天后才被用户发现。三方各自都没写错代码:远端 GNU tar 对较短的非 ASCII 名写的是
**纯 ustar 头**(`typeflag='0'`、GNU magic `"ustar \0"`、名字字段直接放裸 UTF-8 字节,无 PAX、
无字符集声明),Windows 自带的 bsdtar 3.8.8 按**本地 ANSI 代码页**(CP936)解码该字段,而那个构建
**不支持 `--hdrcharset`**。修法是让远端改输出 PAX(`path=` 记录携带 UTF-8 名,bsdtar 会优先采用),
并用**能力探针**(`tar <我们的参数> -cf /dev/null /dev/null`,exit 0 = 支持,不遍历任何目录、按 profile 缓存)
而不是猜版本号。五条纪律:
1. **"静默的字节级差异"只能靠真实工具链路复现**:这类 bug 不会报错、不会改变文件内容、本地
tar↔tar 往返也测不出来(两边都用同一个"错"的假设就自洽了)。必须让**真实的两个版本的工具**
各站一端(本次:WSL 里的 GNU tar 1.35 当远端、Windows 的 bsdtar 3.8.8 当本地),中间跑**真实实现**。
2. **合成 fixture 可能是错的,真工具才是 oracle**:我先手搓过一个 PAX 头,记录长度算错(写成
`recBytes + digits + 2`,正确是 `digits + 1 + recBytes`)导致 bsdtar 报错;改用**真 GNU tar 产出的
归档**当素材后才得到可信结论。凡"我想验证某个格式"的场合,先问一句"能不能让真工具生成它"。
3. **能力探测优于版本判断**:`--format=pax` 与 `--pax-option=...` 是两个独立能力(macOS 的 bsdtar
有前者没有后者),所以探针是两级阶梯,逐级降级并缓存;探测失败时**明确告知后果**
(Windows 上会乱码、请升级远端 GNU tar),而不是静默退回旧行为。
4. **优化项要量,不要猜**:`--format=pax` 默认给每个文件都写 `mtime`/`atime` 记录(301 个 200 B 文件的
树 +97%),但加上 `delete=atime,delete=ctime,delete=mtime` 后 GNU tar 只为**真正需要**的条目写扩展头
—— 实测体积与 ustar 逐字节相同。没有这组测量,就会在"修乱码"与"膨胀一倍"之间做无谓取舍。
同理,"只在 Windows 启用"这个门控也是**量出来的**而不是猜的:WSL 里 `LC_ALL=C tar xf` 解同一个
GNU-magic 归档,名字字节仍是 `e6 8a a5 …`(原样透传),说明 Linux 的 GNU tar 不看 locale 转换字节 ——
乱码需要一个**主动往遗留代码页转换的读者**(Windows 的 bsdtar),所以门控是 `process.platform === "win32"`
而不是"非 UTF-8 locale 就启用"。想当然地按 locale 判断会白白给所有 Linux 用户改成 PAX。
5. **旧数据要给出路,但不能借"修复"之名删东西**:乱码名是**已经存在**的镜像内容,识别它需要把
"正确名 → GBK 改写"反过来配对(Node 没有 GBK 编码器,所以是**正向**算 `mojibake(新树名)` 再去镜像里找),
且只在**本来就要拒绝**的那条路径上扫描(日常同步零成本)。删改必须显式(`repairNames: true`),
且**只有全部**镜像独有文件都被证明是乱码名时才放行 —— 混着真·本地独有文件时依旧拒绝。
另外:乱码名里可能出现**私用区字符**(本次实测 `\uE0BC`),别指望用户能手打或复制粘贴去改名,
插件必须给出自动通道。
6. **改了长期存在的命令形状要顺手纠正不规范处**:`tar cf -` 的"无横线旧式选项"只在**首参**生效,
前面一旦有长选项(`--format=pax`),`cf` 会被当成文件名并报
`You must specify one of the '-Acdtrux'…`(实测 1.35)。带横线的 `-cf` 才同时满足"可组合"与 POSIX 风格。
- **🪟 「宿主是进程内服务,不代表它的契约对我们透明」(issue #23 / #24,2026-10-11;同一个举报人连报两条)**:
#23 是 wrapper 裸调 `node`(桌面端按设计不给子进程 PATH 装 node,于是集成终端 100% 打不开);
#24 是写回桥推送失败只有一行宿主日志(模型以为远端已有文件)。两条都不是"我们代码写错了",
而是**对宿主契约的假设没被验证**。五条纪律:
1. **"裸名"就是隐含的 PATH 依赖,能换成绝对路径就换**:同一份 wrapper 里 `ssh` 早就用
`sysSsh` 绝对路径 + 回退(理由是"避免解析到 MSYS2 的 ssh"),`node` 却一直裸名 —— 同类问题
在同一文件里共存了十几个版本。`process.execPath`(**正在运行本插件的那个解释器**)是最可靠的
来源,不需要任何宿主耦合;只在文件名形如 `node`/`node.exe` 时采用(Electron 主进程的 execPath
指向 app 本体,拿它拉起只会再开一个 DSH 实例)。
2. **不要猜宿主的私有目录**:举报人明确不建议"直接探测 DSH 自带 runtime 的绝对路径"(那要官方点头),
正确形状是"用户显式给的路径 > 我们自己的解释器 > PATH",再加一条**可操作的错误**(说明是本插件的
终端、为什么桌面端没有 node、怎么配)与 127 退出码,而不是把 cmd 的原文糊给用户。
3. **模型可见性是宿主契约问题,先查打包产物再设计修法**:举报人建议"在 `ctx.fs.writeText` 的返回值上
附加字段",听起来最干净 —— 但 `write` 工具的 output schema 是 `additionalProperties: false` 且只声明
`path`/`operation`/`before`/`after`,`execute` 自己重建返回对象,成功渲染还是固定信封
(`<path>/<type>/<content>`)。**结论:成功结果里塞不进任何警告**,本版唯一可用的通道就是工具报错。
查法(不需要源码仓库):`app.asar` 是文件不是目录,按 asar 格式读头部 JSON + 按 offset 切片即可
(本次脚本在 `%TEMP%\asar-tool.mjs`);`remediateFsError` / `sandbox.mapError` 对非 `FsError`
**原样透传**,所以自定义 `Error` 的消息能一字不差地到模型。
4. **确定性失败优先"消灭",而不是"上报"**:`MAX_BYTES`(4 MiB)让写回桥在大文件上必然失败 ——
与其把失败报给模型,不如按 3 MiB 分块(3 的倍数 → 非末块 base64 无 padding,可直接拼接;
**先编码成 Buffer 再切字节**,按 JS 码元切会劈开代理对)追加 + `wc -c` 校验完事。
上报留给真正不可预测的失败(断连、权限、配额)。
5. **验收判据用"失败点后移"这类可判定的现象**:本次两条都好用 —— 终端那条是"给一个干净 PATH 直接跑
**真实生成的产物**,失败点必须从『找不到 node』后移到 ssh(退出码 255)",且配一条**负向控制**
(把旧形状放回同一环境,必须复现 `'node' is not recognized`);写回那条是"旧路径对 7 MiB 必须是
确定性失败、新路径必须成功且拼接字节逐字节相同"。**别用"我构造的错误文本里有没有某个词"当断言** ——
那只能证明测试写得对,证明不了实现(本次先犯了一次,改成断言源码里的真实文案)。
6. **测试环境的两个坑,顺手记下**:`PATH=/nonexistent` 时 `#!/usr/bin/env bash` 自己就起不来
(`env` 要靠 PATH 找 bash),所以验证"薄壳不依赖 PATH"要显式 `PATH=/nonexistent /bin/bash 脚本`;
Windows 的 `ssh.exe` 在 stderr 是管道时会把报文写到**控制台**,`spawnSync` 捕获不到(真实终端是 pty,
用户照常可见)—— 这类"测量方式造成的假象"要写在注释里,免得以后有人"顺手修好"。
- **📦 装给自己用也要走一遍沙箱(2026-10-11,2.4.24 发布后当场更新本机 desktop profile)**:
发布 ≠ 能装。DSH Desktop 的插件管理器用自带 pnpm(本机 11.7.0)跑 profile 内的安装,且带
**24 小时** `minimumReleaseAge` 供应链策略 —— 刚发布的版本必然被拒。四条纪律:
1. **先沙箱,再动真 profile**:在 `~/.dsh/profiles/<临时名>` 里放一个只有该依赖的 `package.json`
+ `pnpm-workspace.yaml`,用自带 node 跑 `runtime\pnpm\bin\pnpm.cjs install`(本机 787 ms 装完),
确认版本、文件清单、以及**与仓库 HEAD 逐文件 SHA256 一致**,再动真 profile;事后删掉沙箱目录。
2. **A/B 两组都要跑**:"不加放行 → 必须被拒(`ERR_PNPM_NO_MATURE_MATCHING_VERSION`)"+"加放行 → 必须装成",
否则无法区分"策略真的生效"与"策略根本没被应用"。本次 A 组的拒绝报文里的发布时间戳
(`2026-10-11T15:05:29.155Z`)还顺手校对了 npm 的发布时刻。
3. **`minimumReleaseAgeExclude` 的两种写法语义不同(pnpm 11.7 实测)**:`名@版本` 只被 **lockfile 校验**
匹配(所以 profile 里那条 `…@2.4.19` 能通过启动校验),而**解析新版本**这条路径只认**纯包名**
—— 钉住版本时,卸载旧版装新版会直接失败,日志看起来像"放行没写"。要么用纯包名(本次采用,
代价是该包不再受 24 小时窗口保护),要么安装时用 `--config.minimumReleaseAge=0` 临时关掉策略。
4. **收尾要按宿主的真实口径复验**:更新完再跑一次
`pnpm install --frozen-lockfile --config.minimumReleaseAge=1440`(等价于 DSH 每次启动的校验),
必须 `Already up to date` + 退出码 0,否则下次启动会被策略拦下、插件直接不加载。
另外:`resources\runtime\bin\node.cmd` 的内容就是 `"%DSH_DESKTOP_NODE_EXECUTABLE%"` ——
那个环境变量在子进程里缺席时它展开成一对空引号(`'""' is not recognized`),
这是 issue #23 的现场实证,也说明"用自己的 `process.execPath`"是唯一不依赖宿主私有约定的来源。
- **🕵️ 「本机绿」和「CI 绿」都可能是假象(2026-10-16,给本仓加 CI 的当天连踩两次)**:
第一次流水线红在「找不到依赖: yaml」而**不是**断言失败 —— 根因是这两个测试按目录去找真实依赖,
而**我这个会话的环境里有 `DSH_PROFILE_DIR` 兜底**,所以本机怎么"模拟 CI"都绿;把它清掉、
同时把 `USERPROFILE` 指向空目录,才复现出与 CI 日志逐条一致的红。第二次绿了但断言数是 **1433**
而不是本机的 1469 —— 差的 36 条全来自**需要 WSL 的场景**:`unicode-names` 整文件跳过(31 条)、
`wrapper-terminal` 的 WSL 场景少 5 条。三条可复用的教训:
(a)**"换个 HOME"不等于"换个环境"** —— 会话里的 `DSH_*` 变量会把真实机器状态悄悄带进模拟,
模拟 CI 时必须显式清掉;
(b)**聚合器不能把"跳过"算成"通过"** —— `tests/run-all.mjs` 现在把 0 断言的整文件跳过单列为
`SKIP` 并打印测试自己给的原因,局部跳过标注条数;判定标准写成"失败为 0 **且** 跳过项都被解释",
而不是一个绿勾;
(c)**断言数要逐文件对拍,别只看总数** —— 总数一致也可能此消彼长,总数变小更要问清少在哪。