From 1222d0cea82ef69bf539bda2b95ba7a959561bea Mon Sep 17 00:00:00 2001 From: QQ Date: Wed, 11 Nov 2026 22:36:09 +0800 Subject: [PATCH] Import vendor/dsh-remote-ssh/MAINTENANCE.md --- vendor/dsh-remote-ssh/MAINTENANCE.md | 1025 ++++++++++++++++++++++++++ 1 file changed, 1025 insertions(+) create mode 100644 vendor/dsh-remote-ssh/MAINTENANCE.md diff --git a/vendor/dsh-remote-ssh/MAINTENANCE.md b/vendor/dsh-remote-ssh/MAINTENANCE.md new file mode 100644 index 0000000..d4bd167 --- /dev/null +++ b/vendor/dsh-remote-ssh/MAINTENANCE.md @@ -0,0 +1,1025 @@ +# 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 -`(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 - 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 -` 后前台 `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。 + +**未做(诚实记录)**:本机 `` 的 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:"]`)未变,无需改代码即可升级。 + +### 2.4.35 / 2.4.36 真机验证实据(2026-10-21 重启后,运行中宿主) + +方法:同下(HTTP 打运行中宿主,`x-requested-with` 头 + 读 `value` 信封);本轮端口 **62882**(每次启动都变,以 GUI URL 为准)。 +重启实据:DSH 主进程启动 **09:24:21**,`/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`**(与内置预览同一条通道:本会话的文件读工具)读 `/scripts/submit_gpu.sbatch` → **返回 27 行脚本正文**(远端内容); +- 换一个镜像里不存在的文件 `/scripts/compare_periodic_hill_all.sh` → 返回 **52 行正文**; +- **负向控制**:`/scripts/__no_such_2436__.sbatch` → `not found`(远端也没有时不伪造存在); +- **本地优先**:镜像里已有的 `/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**,`/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 "@"`。 +- **方法级回包是 `{"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 客户端**(凭据只从 `` 工作区的 `.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`,且宿主会整份重写**:远程工作区条目/连接配置/全局默认同步范围都在 `/profiles//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 走 origin 即可,不碰工作流文件) +# gh release create --notes-file <正文> **--latest=false** +# ← 少这个参数会把 Latest 抢到旧版本上;建完必须独立核对: +# gh api repos///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/%2F/<版本> +# 再核对 dist-tags:npm view dist-tags (latest 应指向新版本) +# 最后回下载对比:npm pack @<版本> 的 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 @ was published at , within the + minimumReleaseAge cutoff ()`。两处证据与结论: + - 策略窗口从日志里的 cutoff 反推 = **发布时刻 − cutoff = 24h**(导出 2.4.19 时读 + `/.plugin-manager/logs//pnpm.log` 看到 cutoff 恰为检查时刻前 24 小时; + 历史上 2.4.16 也在同一窗口内被拦); + - 它验证的是 **lockfile 里所有 entries**("Verifying lockfile against supply-chain policies + (N entries)"),所以不是"只挡新包",而是"锁文件里出现未满 24h 的版本就整体拒绝"; + - **桌面 profile 是 pnpm 工程**(`/package.json` + `pnpm-lock.yaml` + `pnpm-workspace.yaml`, + `nodeLinker: hoisted`,`autoInstallPeers: false`),应用内插件管理器其实就是在这个目录跑 + `pnpm add @`(日志可见);它用的是 **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/*` 覆盖到 + `/node_modules//`,并同步 `/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 @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/%2F/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 +# 会话存于 \sessions\<工作区目录>\\session.jsonl.zstd +# DSH_HOME = C:\Users\Administrator\.dsh +zstd -d -f .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 @ is incompatible with dsh : peerDependencies …`),已装的 bundle 也 + **不会激活**(宿主里查不到该插件的 entry/tool),只能 `dsh plugin allow-version --dsh-version + --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 ` 用来验证「升级插件」这条治本路径;`-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` 只有两种形态 —— 字符串数组,或 `{ [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 ` / `add @`(`dsh plugin` + 就是 pnpm 直通,`remove` 可用);② 启动 `node \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 `),客户端传的仍是**镜像路径** → + 「在文件管理器中显示」打开本地镜像、「用 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(' '))" "\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 '\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; : > )`(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:/sidebar/api/` 发请求(body `{sessionId, cwd|path}`,与本插件注册的 exact 路由同形): + ① `git.worktrees`(真实 sessionId)→ `/data/run01//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 的办法**:`\sessions\----\` 下的目录名即历史 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 -- `、 + `show :`)是仓库相对路径,不按会话 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 \node_modules\\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:` 命名,但 **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 @deepseek-ai/dsh@<版本>`;注意 PATH 上的 `dsh` 可能是很久以前装的全局版本, + 别用它,否则测的不是目标版本),用 shipped 模板建一次性 profile(复制 `profiles/web` 的 + `package.json`/`cordis.yml`/`cordis.patch.yml`/`pnpm-workspace.yaml`), + `node /node_modules/@deepseek-ai/dsh/lib/bin.js plugin --profile add file:`, + 再 `node /…/bin.js --profile --port --no-open`(后台跑),最后 curl 插件 API: + `POST http://127.0.0.1:/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 \scan-private.mjs # 枚举镜像 ID / 主机名 / 账号 / 真实路径 / 项目名 / 内网 IP + ``` + + 唯一允许保留的私人字样是 README 七夕段落里的署名 `zhangyi`(刻意保留的私人寄语,见下条)。 + 发布后若发现泄露:先改 issue 评论(`gh api -X PATCH .../issues/comments/ --input `) + 与仓库文件,再处理 npm 产物(`npm unpublish @` 后重新发布同一版本,或发新补丁版)。 +- **🚨 改完 `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 ` 只解析命令行与 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` 自己重建返回对象,成功渲染还是固定信封 + (`//`)。**结论:成功结果里塞不进任何警告**,本版唯一可用的通道就是工具报错。 + 查法(不需要源码仓库):`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)**断言数要逐文件对拍,别只看总数** —— 总数一致也可能此消彼长,总数变小更要问清少在哪。