dsh-crwu-workbench 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -7,6 +7,34 @@
 `cordis_define` + `cordis_run` 装配，版本号用 DSH 的 `pkg-N`）；它已在本仓收尾时删除
 （见 `0.0.1` 一节），下面 `legacy · pkg-43` 及更早的记录是它的历史。
 
+## package · 0.0.14 · 2026-09-28
+
+**兼容 DSH `0.2.0-rc.1`：peer 区间从「一条线」改成「两条线并列」。**
+0.0.13 及更早的版本在 DSH `0.2.0-rc.1` 上会被整体判为不兼容 —— 插件管理器的原文是
+「`dsh-crwu-workbench@0.0.13` 与 DSH `0.2.0-rc.1` 不兼容（要求 `@deepseek-ai/dsh-tools@^0.1.7-rc.2`…），
+运行它可能导致崩溃或数据丢失。请安装与当前 DSH 兼容的插件版本。」，装上了也会被禁用。
+
+- **根因**：`^0.1.7-rc.2` 的语义是 `>=0.1.7-rc.2 <0.2.0-0`，**不含** `0.2.0-rc.1`。DSH 从 0.1.7 起把
+  peer 当**硬门禁**：加载 profile 的 bundle 层时拿 `getDshRuntimeVersion()` 与每个
+  `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*` 的**区间**比对（预发布参与匹配），不匹配的整行被跳过；
+  插件管理器在安装前还会拿候选包自己的 `peerDependencies` 先判一次。
+- **peer 改成 `^0.1.7-rc.2 || ^0.2.0-rc.1`**（7 个 `@deepseek-ai/dsh-*` 与 `engines.dsh` 一致）。
+  **一条线一个 `^` 区间并列，不用 `>=0.1.7-rc.2 <0.3.0`** —— 后者会顺带放行还没验证过的 0.3 线。
+- **加线之前逐包比对过 API**，比对结论（`npm pack` 两条线的全部 `@deepseek-ai/dsh-*` 后逐文件 diff）：
+  7 个 peer 里 `dsh-tools` / `dsh-plugin-manager` / `dsh-host-webserver` / `dsh-client-ui-renderer` /
+  `dsh-skill-filesystem` **字节相同**；`dsh-client-ui-sidebar` 只多了 1 行埋点调用与 1 行文档注释；
+  `dsh-client-ui-layout` 只多了一段 Windows 标题栏的 CSS 变量。插件用到的类型与运行时契约没有变化，
+  0.1.7-rc.2 上的一切行为不变。
+- **`devDependencies` 补全为全部 7 个 peer**（原先只有 4 个）：npm 的 peer 自动安装会为「只有 peer、
+  树里没有具体实例」的包去解析**最新**匹配版本，于是 `@deepseek-ai/dsh-skill-filesystem@0.2.0-rc.1`
+  的精确 peer（`@deepseek-ai/dsh-fs@0.2.0-rc.1`）会和开发树里的 `0.1.7-rc.2` 撞成 `ERESOLVE`。
+  列出实例即把开发树钉在我们开发所对的那条线上。**接收方不受影响**：profile 的 pnpm 配了
+  `autoInstallPeers: false`，`@deepseek-ai/dsh-*` 从来不由包管理器安装（DSH 运行时自己提供）。
+- **新的回归测试**（`host-package.test.mjs`）：按 DSH 自己的判据
+  （`semver.satisfies(runtime, range, { includePrerelease: true })`）断言 7 个 peer 覆盖
+  `0.1.7-rc.2` / `0.1.7` / `0.2.0-rc.1`，并反向断言**没有**顺带放行 `0.3.0-rc.1`，同时要求
+  `engines.dsh` 与 peer 口径一致。这条测试在旧区间上会直接红（已用注入缺陷证伪）。
+
 ## package · 0.0.13 · 2026-09-28
 
 **修复 Windows 上的平台方言：命令串按 PowerShell 拼，不再按 `cmd.exe` 拼。**
@@ -35,6 +63,144 @@ UnexpectedToken`），相关按钮点下去也不会有结果；macOS 上完全
   （一条静态守卫，钉死「模板以 `${shellQuote(` 开头」与「`argv.map(…shellQuote…).join(' ')`」
   这两种会复发的写法）、`host-crwu-h3yun.test.mjs`（按员工报的原文断言 Windows 命令形状）。
 
+### Windows 全面适配（同一版本的第二批，2026-09-28）
+
+0.0.13 只修好了「最直接的那一类」PowerShell 调用（命令位置与参数引用）。这一批把剩下的四个
+风险层一起收掉：安装兼容、命令方言不统一、本地路径按 POSIX 规则处理、CI 与发布门禁没有真的
+模拟 DSH 的 Windows 语义。**一个版本的完整说明必须能回答「Windows 上到底能不能用」**，
+所以下面按风险层分组。
+
+#### 安装兼容
+
+- `22b31b9` 的 peer 双线区间之外，新增 `scripts/check-dsh-compat.mjs`（`npm run compat:dsh`）：
+  在干净临时工程里**真的**装齐 DSH `0.1.7-rc.2` 与 `0.2.0-rc.1` 的完整 peer 集（依赖表由
+  peer + dependencies + devDependencies + `src/` 里真实 import 的 `@deepseek-ai/*` 共同生成，
+  逐个钉版本），把 `npm pack` 出的 tarball 装进去，再调用 DSH 自己的
+  `evaluatePluginCompatibility()` 断言**不会被 skip / disable**，并用**该版本**的 DSH 类型跑
+  一次 `tsc --noEmit`。显式关掉 `legacy-peer-deps`，并反向断言 `0.3.0-rc.1` 会被判不兼容。
+- 补上漏声明的 `@deepseek-ai/dsh-util-values`（`src/` 里 5 处 `import type { JsonValue }`，
+  此前只能靠传递依赖拿类型）。
+
+#### 命令方言（Shell）
+
+- 新增 `src/host/platform/shell.ts`：**唯一**的方言适配器 —— `shellDialect` / `shellQuote` /
+  `shellInvoke` / `mkdirCommand` / `removeFileCommand` / `openExternalCommand` /
+  `clipboardCommand` / `homeProbeCommand` / `privateFileCommand` / `privateFileMechanism`。
+  NUL 明确拒绝，换行等控制字符由单引号安全表示；平台一律由调用方注入。
+- 迁移全部调用点：`tools/case-files.ts`、`system/ops.ts`、`oss/ops.ts`、`ifind/store.ts`、
+  `platform/home.ts`、`audit/root.ts`、`environment/probe.ts`，以及 `dws`/`crwu`/`oss`/Python/
+  身份查询的执行入口。**删除** `environment/manifest.ts` 的 `quoteArg` 与 `ifind/store.ts` 的
+  本地 `shellQuote`（第二、第三个引用实现就是绕过 Windows 的后门）。
+- 不再出现 `cmd /c …`、`Start-Process` 与建目录/删除/权限命令的手工拼接（有静态门禁）。
+  Windows 打开文件改用 `Start-Process -FilePath`；删除改用
+  `if (Test-Path -LiteralPath …) { Remove-Item … -ErrorAction Stop }` —— **不再用
+  `SilentlyContinue` 把真实失败吞成成功**。
+- `tools/case-files.ts` 不再吞错：只把「目标已经是我们要的状态」视为成功，并用 `ctx.fs.stat`
+  **回读后置条件**（命令返回 0 不等于目录真的在 / 文件真的没了）。
+- `oss.probeCommand` 模板降级为 deprecated 兼容路径：结构化 `executable/args` 是默认形状，
+  模板的每个占位符**逐个按平台引用**，未知占位符 / 换行 / 空可执行文件一律拒绝。
+- `platform/home.ts` 按平台只跑一条探测：Windows 只问 PowerShell 的 `$env:USERPROFILE`，
+  不再先试 `python3` / `printf`（那两条在 Windows 上只是两次 command-not-found）。
+
+#### 本地路径
+
+- 新增 `src/shared/utils/local-path.ts`（不引用 Node 模块，Client 也能用）：
+  `isWindowsStylePath` / `isAbsoluteLocalPath` / `trimTrailingSeparators` / `localSeparator` /
+  `joinLocalPath` / `basenameLocalPath`，另有仅供展示层前缀匹配的 `isLocalPathUnder`
+  （**明确标注不是安全边界**）。`joinLocalPath` 对绝对片段与 `..` 片段**抛错而不是静默清洗**。
+- `shared/utils/case-dir.ts` 的 `caseDirOf` 改走它（Windows 上给出 `C:\Work\<流水号>`），
+  新增 `caseDirName`；`host/audit/case.ts` 的 `caseNameOf` 改走 `basenameLocalPath`
+  （旧实现 `split('/')` 在 Windows 上把整条路径当目录名）。
+- `host/report/files.ts` 的拼接走 `joinLocalPath`，工作空间**包含判断从字符串前缀改为
+  `ctx.fs.contains`**；`host/workspace/resolve.ts` 的最长前缀匹配改 `isLocalPathUnder`。
+- **本地路径与 OSS object key 分开命名**：`host/oss/ops.ts` 里 `localPath` 随平台、
+  `objectKey` 永远 `/`。
+- **UNC 策略**：不自行判死 —— 交给底层 `fs` 解析（DSH 在 Windows 上原生支持 `\\server\share`），
+  解析不了时回稳定的「案例目录不可解析：…（原因）」，**不生成损坏路径**。
+
+#### audit 预检与凭据权限
+
+- 审核根预检的提示词不再写死「用 bash 执行 `pwd`」（Windows 上 DSH 挂的是 PowerShell，
+  宿主自检全绿而 Agent 预检必然失败）：改为按平台生成（Windows `Get-Location`、POSIX `pwd`），
+  并把平台事实逐层传到 `probeMessage` / `preflight`。
+- 技能正文与公共层里的 ```bash 代码块改为 ```text；`crwu-audit` 增加 §1.1「命令块按当前平台
+  shell 执行」。vendored `skills/dws/**` 不动（上游正文，由 `dws:check` 按 provenance 守）。
+- **凭据权限结论结构化**（协议 16 → 17）：`chmodOk: boolean` / `chmodError: string` 换成
+  `permission: CredentialPermission`（`status: verified|inherited|failed` + `mechanism` +
+  `message`）。Windows 上没有 POSIX 权限位、也没有 `chmod`，跳过之后旧字段只能报 `true`，
+  字段名读起来是「chmod 成功了」—— 现在如实报 `inherited / windows-acl`
+  （「使用当前 Windows 账户 ACL；POSIX 0600 不适用」）。**本轮不调用 `icacls`**。
+
+#### 构建与发布门禁
+
+- `scripts/prepare.mjs` 不再 `spawnSync('tsdown', { shell: process.platform === 'win32' })`：
+  新增 `scripts/lib/cli-entry.mjs`（解析包的 JS 入口，命中 `.cmd`/`.ps1` shim 时明确报错、
+  **不退回 shell**），用 `process.execPath` 直接执行。**过 shell 会让项目路径里的空格与单引号
+  被第二套规则改写** —— 这是安装链路的第一跳。`scripts/lib/cli-entry.mjs` 随包发布
+  （`files` + `pack:assert` 的 REQUIRED 都钉住了）。
+- `tests/windows/powershell-contract.test.mjs`：把适配器生成的命令真的交给 shell 执行
+  （与 DSH 同形：整串命令作为**一个** argv 元素给 `pwsh -Command`），覆盖命令位置（可执行文件
+  路径含空格/引号/`$`/方括号/中文）、参数原样往返（含 `;` 与 `$(…)` 注入金丝雀）、
+  mkdir/remove 幂等与后置条件、**真实失败必须非零退出**。POSIX 侧本机跑，Windows 侧在 CI 跑。
+- `scripts/smoke-windows-binaries.mjs`（`npm run bin:smoke`）：在 Windows runner 上把
+  `crwu.exe` / `ossutil.exe` / `dws.exe` 真的启动一次（核对 manifest 与 SHA-256、
+  断言发布树无运行残留、对未声明平台明确失败）。
+- CI：新增 `windows-powershell` job（**不设 job 级 `shell: bash`**，runner 默认 pwsh，
+  先断言 PowerShell 7，再跑静态门禁 + 原生合同 + build + smoke + 全量 `npm test`）；
+  plugin 矩阵的 Node 22 上跑 `npm run compat:dsh`；`release.yml` 新增
+  `windows-binary-smoke`，`publish` 改为 `needs: [binaries, windows-binary-smoke]`。
+
+#### 已知限制
+
+- **`win32-arm64` 明确不支持**：随包二进制只有 `darwin-arm64` 与 `win32-x64`。arm64 Windows 上
+  插件如实回 capability gap，**不会**静默用 x64 顶上（有单测钉住文案与「不发任何命令」）。
+- **UNC 未在真实共享上做过端到端验收**：策略是「交给底层 fs 解析，失败给可读错误」，
+  真实 `\\server\share` 的读写仍未在 CI 或真机覆盖。
+- **没有 `icacls` 收紧 ACL**：Windows 上凭据文件的权限继承自当前账户 ACL，插件不擅自重写
+  （企业域策略下这不该由插件决定）。真要「收紧 ACL」需要另做设计与域环境测试。
+- **干净 Windows 用户配置的端到端验收（装插件 → 选工作空间 → 建案例 → 跑审核 → 回传）
+  尚未执行**：本机是 macOS，可机器验证的部分已交给上面的三个 Windows job；
+  人工验收按 `docs/windows-acceptance.md` 的清单逐项记录。
+
+#### 复查修复（同一版本的第三批，2026-09-28）
+
+分支合并前的一次定向复查发现了三个阻塞项与三个中等问题，全部已修，并各自配了会变红的用例。
+
+- **[P1] 发布工作流会稳定失败**：`release.yml` 里「未声明平台必须报错」那一步**故意**让
+  `node` 返回非零，但 GitHub 的 pwsh 壳在脚本末尾用 `$LASTEXITCODE` 作为步骤退出码，
+  `Write-Host` 不会把它重置成 0 —— 于是这一步真的判红，依赖它的 `publish` 永远起不来。
+  现在写成「存退出码 → 断言 → 末尾显式 `exit 0`」；`windows-powershell` job 里那条
+  `npm test` 也改成同样的形状。新增 `tests/unit/host-ci-workflows.test.mjs`：用 `yaml` 解析两个
+  工作流，**任何引用 `$LASTEXITCODE` 的 `run` 块都必须以显式 `exit` 收尾**，并钉住
+  「原生 pwsh job 不得设 job 级 shell / 必须先断言 PowerShell 7 / publish 必须 needs Windows 冒烟」。
+- **[P1] 裸盘符被当成绝对路径**：`isAbsoluteLocalPath` 复用了「Windows 风格」的判断，
+  而风格判断为了兼容 `C:` 这种写法接受了裸盘符 —— 于是 `requireCaseDir('C:')` 会放行一条
+  「盘符相对路径」，案例目录随进程 cwd 漂移。现在风格（`DRIVE_STYLE`）与绝对（`DRIVE_ROOTED`）
+  是两条正则，并新增 `tests/unit/host-case-dir-gate.test.mjs` 覆盖门禁全部分支
+  （裸盘符 / 相对路径 / `..` / UNC 策略 / `fs.contains` 而非字符串前缀）。
+- **[P1] 本地路径迁移不完整**：`bootstrap.ts`（输入快照目录与三个快照文件）、`knowledge.ts`
+  （knowledge 目录 / 下载目标 / manifest）、`dingtalk.ts`（通知幂等状态文件）、
+  `audit/state.ts`（案例目录候选）、`WorkbenchPanel.tsx`（打开本地 HTML）、
+  `workspace-view.ts`（界面上的落盘位置说明）仍在用 `/` 拼 Windows 本地路径 ——
+  其中快照、知识库与本地报告打开都属于核心审核链路。全部改走 `joinLocalPath`/
+  `localSeparator`；新增 Windows 行为测试（bootstrap 的三条快照路径与真实落盘目标、
+  knowledge 目录、`assessAudit` 的案例目录候选、`artifactHint`），
+  并在 `host-platform-shell.test.mjs` 加一条**本地路径载体名单**的静态门禁
+  （名单短、每条写得出理由；对象键与 URL 不在名单里）。
+- **[P2] `fs.stat` 异常被当成「文件不存在」**：`case-files.ts` 把 `resolve/stat` 的所有异常
+  都折叠成「没什么可删的」，删除后的回读也一样 —— 于是 `Access denied` 会被回报成删除成功。
+  现在探测是**三态**（存在 / 不存在 / 查不出来），「查不出来」一律按基础设施失败上报；
+  `ensureDirectory` 在确认不了目标状态时也不许报成功。
+- **[P2] `verified` 没有真正回读**：协议与注释都把 `verified` 定义为「执行并回读确认」，
+  而实现只看了 `chmod` 的退出码 —— 有些文件系统会静默忽略 chmod。现在收紧之后**必须回读模式位**：
+  新增 `readFileModeCommand()`（GNU `stat -c %a` / BSD `stat -f %Lp` / Windows 不适用，
+  分歧只在适配器里出现一次）与 `parseFileMode()`；回读失败、模式对不上都算 `failed` 并带原因。
+- **[P2] Windows 的 OSS 输入错误仍报 POSIX 机制**：`ossCredSave` 的输入校验失败信封硬编码了
+  `mechanism: 'posix-0600'`，在 `win32-x64` 上说错了「谁在负责权限」。改为复用
+  `failedPermission(error, deps.platform)`。
+- 文档：`docs/windows-acceptance.md` 的收尾步骤在 PowerShell 里错用了 `rm -rf`，
+  改为 `Remove-Item -LiteralPath … -Recurse -Force`。
+
 ## package · 0.0.12 · 2026-09-28
 
 **首个包含自更新能力的正式版本。** 0.0.10 / 0.0.11 用户需要**手动完成一次**引导升级

package/README.en.md

@@ -206,13 +206,42 @@ it builds when the sources are present and skips with an explanation when they a
 `tests/unit/host-package.test.mjs` pins this with a real `npm pack` + `npm install` + import regression —
 both failure modes were invisible to local gates and only surfaced for the person installing the package.
 
-`peerDependencies` currently target the `@deepseek-ai/dsh-*@^0.1.7-rc.2` line (cordis `^4.0.4`), matching the
-installed DSH. The DSH plugin API is a developer preview: when you upgrade DSH, re-check those peers, re-run the
-gate, and record the supported DSH version in `CHANGELOG.md`.
+`peerDependencies` cover **two DSH lines**: `@deepseek-ai/dsh-*@^0.1.7-rc.2 || ^0.2.0-rc.1` (cordis `^4.0.4`).
+One `^` range per line, joined with `||`, rather than a single `>=… <…` — the latter would also admit the
+unverified 0.3 line. The DSH plugin API is a developer preview: **before adding a line**, diff the
+`@deepseek-ai/dsh-*` packages of both lines file by file, re-run the gate, and record the supported DSH
+version in `CHANGELOG.md`.
 
 > **Since 0.1.7 this is a hard gate.** DSH compares the runtime version against every `@deepseek-ai/dsh*` peer
 > range and **skips the whole bundle** on any mismatch (recorded in `skippedBundles`) — the symptom is "the plugin
-> is installed but nothing appears", with a clean startup log. The check reads `peerDependencies`, not `engines.dsh`.
+> is installed but nothing appears", with a clean startup log; the plugin manager also marks the row
+> "incompatible with DSH \<version\>" and disables it. The check reads `peerDependencies`, not `engines.dsh`.
+> Note that `^0.1.7-rc.2` means `>=0.1.7-rc.2 <0.2.0-0` and therefore **excludes** `0.2.0-rc.1`.
+
+### Supported platforms
+
+| Dimension | Supported | Notes |
+| --- | --- | --- |
+| Windows | **10 / 11 x64** | DSH passes the whole command as **one argv element** to `pwsh -NoLogo -NoProfile -NonInteractive -Command <string>`. The plugin therefore builds PowerShell (call operator `&`, single-quoted literals) and never assumes `cmd.exe` or Git Bash. PowerShell 7 (`pwsh`) required. |
+| macOS / Linux | darwin-arm64 / linux-x64 | POSIX dialect; only `darwin-arm64` ships bundled binaries. |
+| CPU | `win32-x64` / `darwin-arm64` | **`win32-arm64` is explicitly unsupported**: the plugin reports a capability gap and never silently falls back to x64. |
+| Node.js | `^22.19.0 \|\| >=24` | CI covers 22 and 24 on both Linux and Windows. |
+| DSH | `0.1.7-rc.2` line, `0.2.0-rc.1` line | `npm run compat:dsh` installs each line's full peer set into a clean project and calls DSH's own compatibility check; `0.3.x` is out of scope. |
+| Local paths | drive-letter absolute paths, spaces, CJK, single quotes | e.g. `C:\Users\Jane\Case's Work`. |
+| UNC | `\\server\share\…` | **Delegated to the underlying DSH `fs`**; when it cannot resolve, the plugin returns a readable "cannot resolve case directory: … (reason)" instead of building a broken path. Not yet accepted end-to-end on a real share. |
+
+### Windows troubleshooting
+
+| Symptom | Check first | Fix |
+| --- | --- | --- |
+| Plugin installed, nothing appears, clean startup log | Whether DSH rejected it as **incompatible** (`skippedBundles`, or the plugin manager marking it "incompatible with DSH `<version>`") | The check reads `peerDependencies` (**not** `engines.dsh`); this package declares `^0.1.7-rc.2 \|\| ^0.2.0-rc.1`. Upgrade the plugin after a DSH upgrade; `npm run compat:dsh` reproduces the verdict |
+| `ParserError` / `UnexpectedToken` / "unexpected token" | A command starting with a quoted path (in PowerShell that is a string expression, not a command invocation) | Upgrade to 0.0.14+: every command is generated by `src/host/platform/shell.ts` (with `&` on Windows). If it persists, a call site bypassed the adapter — the static gate in `host-platform-shell.test.mjs` goes red first |
+| "parameter name is ambiguous" / `mkdir` is not recognized | POSIX-only syntax leaking in (`mkdir -p`, `chmod`, `rm -f`, `cmd /c …`) | Same as above: those literals may only appear inside the adapter |
+| A command "succeeded" but the file was not touched | A swallowed failure (`-ErrorAction SilentlyContinue`) | Removed in 0.0.14+; `case-files.ts` also re-reads post-conditions with `ctx.fs.stat` |
+| Truncated paths, a directory name that is a whole path | Local paths handled with POSIX string rules | 0.0.14+ routes them through `shared/utils/local-path.ts`; containment uses `fs.contains`, never string prefixes |
+| Bundled binary fails with "not a valid Win32 application" / missing DLL | Release artifact architecture (`win32-x64` vs `win32-arm64`) | `win32-arm64` is unsupported by design; `npm run bin:smoke` actually launches the release binaries on a Windows runner |
+| Credential file never shows mode `600` | Windows has no POSIX permission bits and no `chmod` | The UI says "using the current Windows account ACL; POSIX 0600 does not apply" (`permission.status = inherited`) — neither a failure nor "verified" |
+| `prepare` cannot find `tsdown`, or a path gets mangled | Whether the build command goes through a shell | 0.0.14+ runs tsdown's JS entry with `process.execPath` (`scripts/lib/cli-entry.mjs`) and **never through a shell**, so spaces and single quotes survive |
 
 ## Development
 

package/README.md

@@ -311,7 +311,7 @@ dsh plugin --profile web remove dsh-crwu-workbench
 
 - 它建在插件选定的**工作空间**里（`cwd = 案例根目录`），是个普通顶层会话，侧栏里归在该工作空间下；
 - 命名 `审核子代理根节点 · MM-DD HH:mm`，见名知义；所有审核子代理都挂在它下面，形成一棵树；
-- 建的时候先跑一句 hello 预检（模型链路 + bash + 沙箱 + cwd），跑不通就不发起审核；
+- 建的时候先跑一句 hello 预检（模型链路 + **当前平台的 shell** + 沙箱 + cwd），跑不通就不发起审核；
 - 稳定优先：能用就复用；不能用（进程重启 / 换工作空间）就新建一个，旧的树留着；
 - 界面位置：⑧ 运行环境信息里的「审核根会话」。
 
@@ -505,13 +505,42 @@ npm 安装**已发布的 tarball** 时也会执行 `prepare`，而 tarball 里
 
 ### 版本兼容
 
-`peerDependencies` 当前锁在 `@deepseek-ai/dsh-*@^0.1.7-rc.2`（与已安装的 DSH 一致，cordis `^4.0.4`）。
-DSH API 仍是 developer preview，升级 DSH 时**必须**同步核对这几个包、重新跑门禁，
-并在 `CHANGELOG.md` 里写明兼容到哪个 DSH 版本。
+### 支持矩阵
+
+| 维度 | 支持 | 说明 |
+| --- | --- | --- |
+| Windows | **10 / 11 x64** | DSH 在 Windows 上把整条命令作为一个 argv 元素交给 `pwsh -NoLogo -NoProfile -NonInteractive -Command <整串>`；插件按 PowerShell 语义拼命令（`&` 调用运算符、单引号字面量），**不假定 `cmd.exe` 或 Git Bash**。需要 PowerShell 7（`pwsh`）。 |
+| macOS / Linux | darwin-arm64 / linux-x64 | POSIX 方言；随包二进制只有 `darwin-arm64`。 |
+| CPU | `win32-x64` / `darwin-arm64` | **`win32-arm64` 明确不支持**：插件如实回 capability gap，不会静默用 x64 顶上。 |
+| Node.js | `^22.19.0 \|\| >=24` | CI 在 Linux / Windows 上各跑 22 与 24。 |
+| DSH | `0.1.7-rc.2` 线、`0.2.0-rc.1` 线 | `npm run compat:dsh` 会**真的**在干净工程里装这两条线的完整 peer 集并调用 DSH 自己的兼容判定；`0.3.x` 不在声明范围内。 |
+| 本地路径 | 盘符绝对路径、空格、中文、单引号 | 例：`C:\Users\张三\Case's Work`。 |
+| UNC | `\\server\share\…` | **交给底层 DSH `fs` 解析**；解析不了时返回可读的「案例目录不可解析：…（原因）」，不生成损坏路径。尚未在真实共享上做端到端验收。 |
+
+### Windows 故障排查
+
+| 症状 | 先查什么 | 处置 |
+| --- | --- | --- |
+| 插件装上了、界面里什么都没有，启动日志干净 | 是否被 DSH 判为**不兼容**（`skippedBundles` / 插件管理器标「与 DSH `<版本>` 不兼容」并禁用） | 判据是 `peerDependencies`（**不是** `engines.dsh`）：本包写 `^0.1.7-rc.2 \|\| ^0.2.0-rc.1`。升级 DSH 后出现就先升插件；应急用 profile 的 `compatibility.json` 精确豁免。跑 `npm run compat:dsh` 复现判定 |
+| 报 `表达式或语句中包含意外的标记` / `ParserError` / `UnexpectedToken` | 命令是不是以引号包住的路径开头（PowerShell 里那是字符串表达式，不是命令调用） | 升级到 0.0.14+：所有命令都由 `src/host/platform/shell.ts` 生成（Windows 上带 `&`）。若仍出现，说明有调用点绕过了适配器 —— `host-platform-shell.test.mjs` 的静态门禁会先红 |
+| 报「参数名不明确」/ `mkdir` 不是内部或外部命令 | 有没有混用 POSIX 写法（`mkdir -p`、`chmod`、`rm -f`、`cmd /c …`） | 同上：这些字面量只允许出现在适配器里；静态门禁会在 PR 阶段拦住 |
+| 命令「成功」了但文件其实没动 | 是否被 `-ErrorAction SilentlyContinue` 之类吞掉 | 0.0.14+ 已去掉；`case-files.ts` 还会用 `ctx.fs.stat` 回读后置条件 |
+| 路径被截断、目录名变成一长串 | 是不是按 POSIX 规则拼/取本地路径 | 0.0.14+ 统一走 `shared/utils/local-path.ts`；安全判定走 `ctx.fs.check` 之外的 `fs.contains`，不用字符串前缀 |
+| 二进制启动报「不是有效的 Win32 应用程序」/ 缺 DLL | 发布形态的架构是否匹配（`win32-x64` vs `win32-arm64`） | `win32-arm64` 不支持（设计如此）；`npm run bin:smoke` 会在 Windows runner 上真的启动一次发布二进制 |
+| 凭据文件权限看不到「600」 | Windows 没有 POSIX 权限位、也没有 `chmod` | 界面会明说「使用当前 Windows 账户 ACL；POSIX 0600 不适用」（协议 17 的 `permission.status = inherited`）——这不是失败，也不是「已验证」 |
+| 安装/`prepare` 报找不到 `tsdown` 或路径被拆坏 | 构建命令是否经过 shell | 0.0.14+ 用 `process.execPath` 直接执行 tsdown 的 JS 入口（`scripts/lib/cli-entry.mjs`），**不经过 shell**，所以路径里的空格与单引号不会被改写 |
+
+
+`peerDependencies` 覆盖**两条 DSH 线**：`@deepseek-ai/dsh-*@^0.1.7-rc.2 || ^0.2.0-rc.1`（cordis `^4.0.4`）。
+一条线一个 `^` 区间并列，而不是 `>=… <…` 一把梭 —— 后者会顺带放行还没验证过的 0.3 线。
+DSH API 仍是 developer preview，**加一条线之前**必须把两条线的 `@deepseek-ai/dsh-*` 逐包比对过、
+重新跑门禁，并在 `CHANGELOG.md` 里写明兼容到哪个 DSH 版本。
 
 > **0.1.7 起这条是硬门禁**：DSH 会拿运行时版本与每个 `@deepseek-ai/dsh*` peer 范围比对，
 > 不匹配的 bundle 会被**整包跳过**（记进 `skippedBundles`）—— 症状是「插件装上了、界面里什么都没有」，
-> 而启动日志没有任何报错。判据是 `peerDependencies`，不是 `engines.dsh`。
+> 而启动日志没有任何报错；插件管理器还会把这一行标成「与 DSH \<版本\> 不兼容」并禁用。
+> 判据是 `peerDependencies`，不是 `engines.dsh`。注意 `^0.1.7-rc.2` = `>=0.1.7-rc.2 <0.2.0-0`，
+> **不含** `0.2.0-rc.1`。
 
 ---
 

package/common/skills/crwu-dws/SKILL.md

@@ -177,27 +177,27 @@ DSH 下的三条硬规则：
 
 - M1/P1 库解析（分范围全量取空间，精确名匹配）：
 
-  ```bash
+  ```text
   dws wiki +space-list --type orgWikiSpace --limit 50 --page-all --format json
   dws wiki +space-list --type myWikiSpace --limit 50 --page-all --format json
   ```
 
 - P2 目录遍历（`--workspace` 必填；子层追加 `--folder`；页数上限显式放大）：
 
-  ```bash
+  ```text
   dws wiki +node-list --workspace <ID> --page-all --page-limit 200 --format json
   dws wiki +node-list --workspace <ID> --folder <folderId> --page-all --page-limit 200 --format json
   ```
 
 - M2/M3 取节点元数据（判 `extension`）：
 
-  ```bash
+  ```text
   dws wiki +node-get --node <nodeId> --format json
   ```
 
 - M2/M3 双通道取正文：
 
-  ```bash
+  ```text
   dws doc +export --node <nodeId> --export-format markdown --output <相对路径>
   dws drive +download --node <nodeId> --output <相对路径>
   ```

package/common/skills/crwu-h3yun-login/SKILL.md

@@ -66,7 +66,7 @@ description: >-
 
 **唯一推荐步骤（自动扫码）**
 
-```bash
+```text
 crwu h3yun session login
 ```
 
@@ -84,7 +84,7 @@ crwu h3yun session login
 
 **验证**
 
-```bash
+```text
 crwu h3yun session status
 ```
 
@@ -95,7 +95,7 @@ crwu h3yun session status
 若浏览器自动流程不可用（无浏览器/被禁用），可以让员工在 `h3yun.com` 网页扫码
 登录后，由**绑定者本人在本机**执行并把浏览器里的会话 JWT 只粘贴给本机命令：
 
-```bash
+```text
 crwu h3yun session bind --token '<JWT>'
 ```
 

package/common/skills/crwu-h3yun-query/SKILL.md

@@ -62,7 +62,7 @@ DSH 里氚云取数只走工作台插件注册的 CRWU 结构化 Tool，**不要
 ## 前置检查
 
 1. 先确认能读取会话：
-   ```bash
+   ```text
    crwu h3yun session status
    ```
    - 成功：输出里出现 `engineCode` 与 `expiresIn`，继续。
@@ -75,7 +75,7 @@ DSH 里氚云取数只走工作台插件注册的 CRWU 结构化 Tool，**不要
 
 ### 第 1 步：列系统（应用），请用户选择
 
-```bash
+```text
 crwu h3yun apps list
 ```
 
@@ -85,7 +85,7 @@ crwu h3yun apps list
 
 ### 第 2 步：选中的系统下钻，看父集/子集（表单），再请用户选择
 
-```bash
+```text
 crwu h3yun apps children --app <appCode>
 ```
 
@@ -99,7 +99,7 @@ crwu h3yun apps children --app <appCode>
 
 ### 第 3 步：在表单里查记录（默认每页 20 条，可翻页）
 
-```bash
+```text
 # 用户没给标题 → 首页 20 条
 crwu h3yun records list --schema <schemaCode> --size 20
 
@@ -131,7 +131,7 @@ crwu h3yun records list --schema <schemaCode> --size 20 --filter "F0000036 Equal
 
 ### 第 4 步：查看用户选中记录的具体内容（简要输出）
 
-```bash
+```text
 crwu h3yun records get --schema <schemaCode> --id <ObjectId>
 ```