dsh-crwu-workbench 0.0.13 → 0.0.15

package/README.md

@@ -145,14 +145,30 @@ node <仓库>/install/browser-check.mjs \
 > （**不再用模态层遮住整页**）。
 
 - **这是一次性授权、长期有效**：写进工作台状态文件 `~/.dsh/crwu-workbench.json` 的
-  `trustCredentials`，重启 profile 后仍然生效。
+  **版本化授权收据**（`localAccess`：`schemaVersion` + 时间 + 五项固定能力）。协议 18 起，
+  旧版的 `trustCredentials: true` 一律判为 `outdated` —— **它不算一次授权**（防静默扩权）。
+- **从 0.0.14 升级后必须完整退出并重启 DSH**：协议从 17 跳到 18，是**语义**变化
+  （见 [`CHANGELOG.md`](CHANGELOG.md) 的 0.0.15 一节）。只刷新页面会留下旧宿主，
+  表现为「新的凭据活动被拦，提示完整重启」（验收项 P-18）。
 - **不授权 = 插件不可用**：环境自检把它算作阻塞项（「进入报告审核」被门禁挡住），
   并且**不会**谎报「钉钉没登录」——那正是没授权时沙箱读不到钥匙串的假象。
-- **授权之后才谈真假**：凭据类命令才带 `sandboxPolicy: { mode: 'danger-full-access', workspaceRoot }`
-  去拿真结论（已登录 / 未登录 / 未绑定 / 已过期）。
-- **最小权限**：只有确实读本机凭据的命令提权；插件包完整性核对（只 stat 包内文件）、
-  `ossutil` 上传/列举、写案例目录、开浏览器等一律走 profile 的默认沙箱。
+- **未授权时一个凭据进程都不起**：连"先探一下看看"都没有。所以未授权时看到的
+  「未登录 / 密钥错误」不可能是真的结论，界面也不会这么说。
+- **授权之后才谈真假**：每个**具名操作**在自己的定义里声明要不要逐次 `danger-full-access`
+  （`src/host/access/operations.ts`）——调用方提交不了提权开关，模型更不能。
+- **最小权限**：只有确实碰工作区外路径的操作提权（氚云会话、钉钉 `~/.dws`、
+  `~/.ossutilconfig`、iFinD 凭据文件、插件状态文件）；插件包完整性核对（只 stat 包内文件）、
+  写案例目录、开浏览器等一律走 profile 的默认沙箱。
+  注意 `ossutil` **也算**本机凭据访问（它每次都会读 `~/.ossutilconfig`），
+  这是协议 18 相对 0.0.14 的口径修正。
 - 授权被部署的审批策略拒绝时，界面如实报「本机凭据读取被拦住」，并指回那个开关。
+- **审核会话固定收敛**：审核根与审核子会话永远是 `workspace-write` + `approval=never`
+  （不跟部署默认走）。审核需要的本机凭据由上面的具名操作按授权提供，子代理自己既不需要、
+  也不允许提权；未登录时它会**停下并要求员工回到工作台**，不会自己发起登录。
+- **「钉钉本机目录」卡片**：环境页「账号连接」里可以只读体检 `<HOME>/.dws`
+  （模式位 / 所有者 / 可写性 / 锁 / 钥匙串状态）。只有确诊「本机文件权限问题」时才会出现
+  「修复权限」按钮，并且要**二次确认**；它只改 `.dws`（700）与 `.data.lock`（600），
+  不改上级目录、不夺所有权、不删锁、不结束进程。
 
 `DSH_PERMISSION_MODE=danger-full-access` 只在**开发自测**（§「真实验证」里那个临时 profile）才需要。
 
@@ -213,8 +229,10 @@ dsh plugin --profile web add dsh-crwu-workbench   # 从 npm 取预构建产物
    然后到「交付与外部数据」里填**向管理员获取**的阿里云 AccessKey（iFinD API-Key 同页填写，
    是必需项，未通过会拦住受保护页面）—— `crwu` / `dws` / `ossutil` 三个命令**随插件自带**，
    不需要安装；**密钥只在这个页面上填**，不要贴进对话、也不要让 Agent 代填；
-3. 要发起审核，先在**顶层会话**的会话头点「登记为子会话父级」——审核只允许挂在顶层会话下
-   （只挂一层，嵌套会导致状态跟丢）。
+3. 要发起审核：在**报告审核**页点「AI 审核」即可。插件会自己在选定工作空间里建一个
+   **审核子代理根会话**，审核子会话挂在**它**下面（不再挂在你正在看的那个聊天会话下）。
+   会话头的「登记为子会话父级」现在只用来把**你正在用的会话的 preset** 提示给审核根
+   （让审核的工具链与你手动跑时一致），**不是**发起审核的前置条件。
 
 > **技能随包发布，按层组织**：包里带三层技能 —— `skills/crwu/`（本仓自研 27 个）、
 > `skills/dws/`（上游 `dingtalk-workspace-cli` vendored 的 14 个钉钉技能）、`common/skills/`
@@ -311,7 +329,7 @@ dsh plugin --profile web remove dsh-crwu-workbench
 
 - 它建在插件选定的**工作空间**里（`cwd = 案例根目录`），是个普通顶层会话，侧栏里归在该工作空间下；
 - 命名 `审核子代理根节点 · MM-DD HH:mm`，见名知义；所有审核子代理都挂在它下面，形成一棵树；
-- 建的时候先跑一句 hello 预检（模型链路 + bash + 沙箱 + cwd），跑不通就不发起审核；
+- 建的时候先跑一句 hello 预检（模型链路 + **当前平台的 shell** + 沙箱 + cwd），跑不通就不发起审核；
 - 稳定优先：能用就复用；不能用（进程重启 / 换工作空间）就新建一个，旧的树留着；
 - 界面位置：⑧ 运行环境信息里的「审核根会话」。
 
@@ -505,13 +523,52 @@ 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 的提权是「逐次、需人工批准、
+> 只对该次调用生效」，没有审批通道时 fail closed。插件能做到的是：① 对工作区外的路径逐次声明
+> `sandboxPolicy`；② 见到沙箱拒绝就**如实报因**（而不是把它显示成「未登录 / 未配置」）；
+> ③ 用一次性的「同意并继续」授权覆盖插件自己发的凭据命令。要把整台机器设成不沙箱，只有改 DSH 侧：
+> `DSH_PERMISSION_MODE=danger-full-access dsh --profile <profile>`（或 profile 里
+> `dsh-sandbox-policy` 的 `mode`）—— 那是机器设置，不是本插件的默认口径。
+
+| 症状 | 先查什么 | 处置 |
+| --- | --- | --- |
+| 插件装上了、界面里什么都没有，启动日志干净 | 是否被 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 上真的启动一次发布二进制 |
+| 报 `file access denied under workspace-write mode`（例如写 `C:\Users\<你>\.ossutilconfig` 或 `~/.dsh/`） | 那是 **DSH 沙箱**的拒绝标记，不是 Windows 权限 | 0.0.14 起插件对工作区外的落盘自己声明 `sandboxPolicy`；若仍出现，说明 profile 把提权请求降级了 —— 见下一条 |
+| 环境页说「未登录」，但你在终端里 `crwu h3yun session status` / `dws auth status` 明明是登录的 | 受限沙箱里读不到系统凭据存储，命令会**如实**回 `secret not found in keyring` —— 那是假结论 | 点面板「同意并继续」完成**一次性授权**（长期有效），插件才会带 `sandboxPolicy` 去读；这就是「未授权时不许猜」 |
+| 钉钉登录报 `acquiring file lock: opening lock file: open C:\Users\<你>\.dws\.data.lock: Access is denied.` | 两种可能：命令在沙箱里写不了 `~/.dws/`，**或**那个文件真的被占用 / 有异常 ACL | ① 先在面板授权后重试；② 仍失败就在**你自己的 PowerShell**（不受沙箱约束）里关掉残留的 `dws` 进程，必要时删掉 `%USERPROFILE%\.dws` 再登录 |
+| 凭据文件权限看不到「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>
 ```