dsh-composer-ux 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.22.0] — 2026-10-15（借鉴 dsh-ops：安全门控 / 运行期覆盖 / 自检 / 市场清单 / CLI + 适配 dsh 0.2.1-alpha.4）
+
+### 适配 dsh 0.2.1-alpha.4（用户 2026-10-15：「更新网页版，把插件适配，测试没问题就发布」）
+
+宿主从 0.2.1-alpha.2 升到 **0.2.1-alpha.4**（独立分支 `upgrade-0.2.1-alpha.4`，检出 + `pnpm install`
++ 全量 `npm run build`，构建 9 项全过）。形状核对 36 项对着 alpha.4 源码**全部通过**：
+settings 三入口与 `document-updated` 事件、`volatile` 处理、`webServer.register`、沙箱
+`confine(argv, policy, signal)`、目录流程槽位、tool-terminal 都在。alpha.4 对插件作者的两处新增：
+`engines.dsh`（声明后**单独决定**兼容性、忽略 peerDependencies）与官方可选 bundle
+`@deepseek-ai/dsh-experimental-terminal-bundle`。
+
+**真机抓到并修掉的问题（这次适配的实质内容）**：`@deepseek-ai/dsh-tool-terminal` 声明的是
+**精确版本 peer**。我插件自带的依赖范围被 pnpm 解析成 `0.2.1-alpha.3`（本地元数据缓存旧），
+而运行时是 `alpha.4` ⇒ 宿主判定不兼容后**只是把那一行禁用**（启动日志一句 warning），
+模型工具表里少 6 个 `terminal_*` 工具，界面上完全看不出来。修法两条：
+
+1. **profile 层按运行时版本钉**（与桌面 profile 一直以来的做法一致）：
+   `bin/dsh-composer-ux.mjs` 的 `install` 在装完插件后自动 `add @deepseek-ai/dsh-tool-terminal@<运行时版本>`；
+2. **把这个静默失败变成可见**：设置页「自检」新增一行「持久终端工具」，
+   拿 tool-terminal 的 peer 要求与**运行时版本**（从进程入口往上找最近的 package.json —— 本仓锁步版本）
+   比对，不一致就红并给出修法。CLI 的 `status` 也打印同一份结论。
+
+真机验证（alpha.4 web profile `a4web`）：启动日志干净、自检 9 行全对（含「持久终端工具 — 已挂上；
+tool-terminal 0.2.1-alpha.4（要求 0.2.1-alpha.4）」）、运行期请求头覆盖已挂上、旧写入清理已完成。
+
+**刻意没做的**：不声明 `engines.dsh`。alpha.4 起它一旦声明就单独决定兼容性，而本插件**刻意**支持
+0.1.6/0.1.7 的老设置形状（见下面「两代设置服务」），声明下限会把那些用户一刀切掉；
+上限又会把"其实还能跑"的新运行时挡在门外。所以继续用"能力探测 + 失败方向安全"的老办法。
+
+
+
+用户 2026-10-13：「第一梯队和第二梯队 除了英文化 其他都做，做完之后先测试，不要发布」。
+来源是 [dsh-ops@0.2.9](https://github.com/T-Auto/dsh-ops) 的对比分析（见 `../dsh-ops-对比分析.md`）。
+
+### 1. 安全：解释层「内置 Bash」按会话权限门控（这条其实是我这边的真问题）
+
+它以前是 `node:child_process.spawn` **直接执行**、只锁 cwd —— 也就是**绕过会话策略**：
+一个 `read-only` 会话里，只要用户开过这一栏，解释层就能跑任意命令。
+现在（用户选定"接沙箱为主、门控兜底"）：
+
+- 会话是 `danger-full-access` ⇒ 直接跑（与宿主同判据）；
+- `read-only` / `workspace-write` ⇒ **必须**先过 `ctx.sandbox.confine(argv, policy)`，
+  且后端自报 `enforcement !== 'full'` 时**拒绝执行**（"部分约束"不算边界）；
+- 拿不到权限模式、或没有沙箱服务 ⇒ **不发这个工具**（证明不了安全就不给），并在设置页/自检里说明。
+
+### 2. 安全：请求头改成**运行期可逆覆盖**，不再写用户配置
+
+以前「OpenCode 请求头」把 `providers.<route>.headers.<name>` **写进用户的模型路由配置**，
+再靠记账 + 撤销回滚 —— 那是本插件唯一会动用户配置的功能。
+现在照 dsh-ops 的路子：挂官方 loader 的 `internal/config` 事件，在**配置被解析时**补上字段，
+从不落盘（官方 `llm-pi-ai` 自己也是这么挂的）。旧版本写进去的残留由迁移表**一次性**清掉，
+且只删"值等于我们记账值"的那些（用户自己写的同名头绝不动）。
+
+### 3. 新功能：自检（设置页一张卡 + `/composer-ux/doctor` 路由）
+
+一行一句人话，把散在五处的状态摊平：设置字段是否都在宿主 schema（**不在 ⇒ 开关拨不动**）、
+八栏开关、终端服务与 bash 探测、请求头覆盖与迁移、快捷指令本、通知凭据、解释层档位、运行环境。
+真机首跑就抓出两条：覆盖状态读的是**陈旧值**（已修）、以及测试 profile 的「通知开着但缺凭据」。
+
+### 4. 新功能：`command` XOR `script_path`（长脚本走文件）
+
+长脚本、多行、含大量引号/反斜杠/中文的命令，先落文件再传路径 —— 避免在工具调用 JSON 里做多层转义
+（一处漏了就整轮 `MALFORMED_RESPONSE` 作废，这是 dsh-ops 明确记下来的一条）。
+
+### 5. 工程：版本化迁移表（`src/migrations.ts`）
+
+以前迁移靠"文档里有没有这个键"这类判据，写在业务代码里。现在每条迁移一行、带版本号字段，
+成功才写标记、失败下次重来、绝不覆盖用户后续的显式选择。
+
+### 6. 展示：市场清单 `dsh-plugin.json` + 图标
+
+`package.json` 加 `icon`（**宿主真的会读它**：`@deepseek-ai/dsh-package-manifest`），
+并补一份带**权限及理由**披露的 `dsh-plugin.json`（当前宿主不消费它，属市场/生态展示口径）。
+
+### 7. 新功能：CLI `dsh-composer-ux`
+
+`status` / `doctor` / `install` / `uninstall`；**安装卸载一律委托官方 CLI**（探测桌面自带的 dsh.cmd，
+不在 profile 上另搞一套锁与回滚）。运行时自检仍在设置页那张卡里（CLI 拿不到宿主服务）。
+
+### 8. 体验：错误文案标准化
+
+未知参数在执行前点名拒绝（同时列出可接受的键）、缺执行器给 `ENOENT` 说人话而不是裸 spawn 异常、
+长命令被拒时直接指向 `script_path`。
+
+### 顺手修掉的启动期问题
+
+真机重启时又撞到一次 profile 写锁（这次是「终端状态写入」）：把所有**启动期/迁移期**的写
+统一走 `retryWrite`（抽成 `src/retry-write.ts`，终端子系统也用它）。
+
+**验证**：`npm test` —— **31 个套件 2668 passed / 0 failed**（新增 `test/doctor.mjs` 32 条；
+`host-header-mirror` 重写为"绝不写用户配置 + 运行期注入 + 一次性清理" 57 条；解释层 bash 的
+权限组合四条；自检卡渲染 5 条）。真机（0.2.1-alpha.2 实例）验过：覆盖挂上、旧写入清理完成、
+自检报告正确、启动日志干净。**未发布**（用户要求只测不发）。
+
+
+## [0.21.0] — 2026-10-10（「优化提示词」默认收缩：面板打开回到快捷指令那半 + 优化选项加折叠）
+
+用户 2026-10-10（截图）：「让优化提示词默认收缩起来」。确认后两处都改：
+
+### 1. 打开面板回到默认那一半（不再被"上次的结果"顶过去）
+
+- 旧规则：结果框"从无到有"就自动切到优化那半 —— 但**重开面板时上一轮的结果也算"从无到有"**，
+  于是每次打开都直接落在优化那半、外加一整组选项，把「优化完成」顶到看不见（截图里只剩一行）。
+- 现在：每次**打开**面板 ⇒ 回到「快捷指令」那半，哪怕上一轮结果还摆着（打开那一刻就有的结果框算
+  **基线**，不抢视图；切换按钮写「上次的结果在这儿」）。
+- 保留的：**面板已经开着**时结果框从无到有照旧自动切过去（点 ✨ 必须看得到结果，不能"点了没反应"）；
+  「**正在跑**」是打开时唯一的例外 —— 那时要能看见进度与「取消」。
+- 点 ✨ 另外**明确**切一次那半：上一轮结果还在时它不是"从无到有"，只靠那条规则会看起来没反应。
+
+### 2. 「优化选项」加一层折叠，默认收起
+
+- 收起时标题行右侧给一行当前值摘要（权限 · 上下文 · 只读工具 · Bash；指定过模型时才带模型），
+  不点开也看得见关键值；展开后与 0.14.0 的形态完全一致（七个控件 + 详情）。
+- 卡片改成**受控**（`open` / `onToggle` 由面板给）：折叠要在每次打开面板时复位，卡片只负责画。
+
+### 验证
+
+- `npm test`：30 套件 **2591 passed / 0 failed**。`panel-split-render` 40→55：
+  新增 §0（把"打开=默认""从无到有才切"这两条跨渲染规则抽成纯函数钉住 —— SSR 一次渲染测不到转换）、
+  §2 改成"有结果框也不抢视图"、§2c 直接渲卡片验收起/展开两态、§3 直接渲结果框验布局；
+  `client-registration` 271→276（旧的那条源码断言改写 + 5 条新契约）。
+- `npm run test:mutations`：**195 条全部咬住**（EB 的 expect 跟着改，新增 HP–HU 5 条：
+  打开不回到默认、不复位折叠、折叠初值改展开、收起照样渲七个控件、摘要丢了、✨ 不明确切换）。
+
 ## [0.20.0] — 2026-10-10（适配 DSH 0.2.1-alpha.2：真机测出并修掉三处真问题）
 
 用户 2026-10-10：把 `D:\DeepSeek Harness`（未封装版检出）升到最新（`dsh-v0.2.1-alpha.2`）并用它测插件。

package/README.md

@@ -50,6 +50,20 @@ DeepSeek Harness Web 输入体验增强插件：
 2. **快捷指令按钮**：输入框工具行里、「展开」按钮左侧的胶囊按钮，点开是常备提示词清单 + 「优化提示词」。
 3. **键位生效**（仅主聊天输入框）：默认值 = 现状（Enter 发送、Shift+Enter 换行、Ctrl+Enter 加速提交），改动即时生效并持久保存。
 
+## 0.22.0 新增（安全 / 自检 / CLI）
+
+- **解释层「内置 Bash」按会话权限门控**：完全权限直跑；其它模式**必须**过 `ctx.sandbox.confine`，
+  约束不是 `full` 就拒绝执行；拿不到权限模式或没有沙箱服务 ⇒ **不发这个工具**。
+- **「OpenCode 请求头」不再写你的配置**：改成挂官方 `internal/config` 事件做**运行期可逆覆盖**，
+  0.21.x 及以前写进去的残留由迁移表一次性清掉（只删值与记账一致的，你自己写的同名头不动）。
+- **自检**：设置页多了「自检」卡（也可 `GET /composer-ux/doctor`），一行一句人话摊平
+  设置字段是否都在宿主 schema、八栏开关、终端服务与 bash 探测、请求头覆盖、快捷指令本、
+  通知凭据、解释层档位、运行环境。
+- **CLI**：`npx dsh-composer-ux status|doctor|install|uninstall`（安装卸载一律委托官方 CLI）。
+- **长命令走文件**：解释层的 bash 工具支持 `command` 与 `script_path` 二选一，
+  多行/长脚本落文件再传路径，免得在工具调用 JSON 里做多层转义。
+- **市场清单**：`package.json` 的 `icon`（宿主会读）+ `dsh-plugin.json`（权限及理由披露）。
+
 ## 安装
 
 ```sh
@@ -143,10 +157,17 @@ dsh plugin --profile web add <你克隆或解压出来的目录>
   - **0.12.0 起有记忆链**：你把成品插进输入框、改了几处、又点一次优化时，宿主会把**上一版成品**
     一起给模型（截断 1500 字），它只需围绕变化点调整、不必从零重写（你已确认过的地方不会被改回去）。
     不带的三种情况：同一段原文重跑（同文重试）、草稿就是上一轮成品（对成品重跑）、上一轮失败/取消；“重新优化”只在你手改过框里成品时才带。
-  - **面板分两半（0.13.1）**：中部现在是「**优化提示词**」（结果框）与「**快捷指令**」（分类 + 条目列表）**二选一**，
-    中间一个切换按钮（▸ / ▾）换着看；打开面板**默认展开快捷指令**，标题行的**三档档位与 ✨ 按钮始终露在外面**
-    —— 所以「跑一次优化」永远是一步，不必先展开。**点 ✨ 会自己切到优化那半**（否则结果被藏在收起的一半里，
-    看起来像没反应）；手动切回快捷指令不会被抢回去；点结果框的「✕」会顺手切回快捷指令。
+   - **面板分两半（0.13.1）**：中部现在是「**优化提示词**」（结果框 + 优化选项）与「**快捷指令**」（分类 + 条目列表）**二选一**，
+     中间一个切换按钮（▸ / ▾）换着看；标题行的**三档档位与 ✨ 按钮始终露在外面**
+     —— 所以「跑一次优化」永远是一步，不必先展开。**点 ✨ 会自己切到优化那半**（否则结果被藏在收起的一半里，
+     看起来像没反应）；手动切回快捷指令不会被抢回去；点结果框的「✕」会顺手切回快捷指令。
+   - **默认收缩（0.21.0，用户 2026-10-10 的截图）**：每次**打开面板**都回到「快捷指令」那半，
+     哪怕上一轮的结果还摆着 —— 旧规则是"结果框从无到有就自动切过去"，而重开面板时旧结果也算"从无到有"，
+     于是每次打开都直接落在优化那半、外加一整组选项，把「优化完成」顶到看不见。
+     现在：打开那一刻就有的结果框算**基线**（不抢视图，切换按钮会写「上次的结果在这儿」）；
+     **面板已经开着**时结果框从无到有照旧自动切过去；「**正在跑**」是打开时唯一的例外（要能看见进度与「取消」）。
+     同一张面板里的「**优化选项**」也加了一层折叠、**默认收起** —— 收起时标题行右侧给一行当前值摘要
+     （权限 / 上下文 / 只读工具 / Bash，指定过模型时才带模型），不点开也看得见关键值。
   - **修掉「展开后看不到按钮」（0.13.1）**：以前结果框和快捷指令列表**挤同一块固定高度**，结果框一长
     （条目多 + 成品多行）就把列表挤没、再把自己底部的**「插入输入框 / 重新优化 / 复制」顶出面板边界被裁掉**。
     现在两半互斥、各自内部滚，而且结果框拆成「可滚内容区 + **钉在底部的按钮行**」—— 面板再矮也不裁那排按钮。
@@ -553,7 +574,7 @@ Windows 上 DSH 给模型的终端工具是 **PowerShell**（工具名 `pwsh`）
 | 工具循环的消息形状 / 轮次封顶 / 异常必须降级 | 同上第 6 节（假 llm 驱动整条循环，逐条检查 `role:'tool'` 与 `toolCallId`） |
 | 工具路径：默认关、开了才派、**查完吐散文必须回落**、拿不到工作目录就不派 | `test/quick-commands.mjs` 5g 节（13 条，真路由 + 假 llm） |
 | 工具读到的内容不进台账 | 同 5g 节：断言台账里只有工具名与次数、没有读到的文件内容 |
-| 变异守卫真的会咬人，且**必须是指定的那条测试变红** | `npm run test:mutations`：**189 条全部咬住**（判据是 `red.some(line => line.includes(item.expect))`，不是"有红就行"） |
+| 变异守卫真的会咬人，且**必须是指定的那条测试变红** | `npm run test:mutations`：**（205 条全部咬住）**（判据是 `red.some(line => line.includes(item.expect))`，不是"有红就行"） |
 | **桌面应用里弹系统文件夹框**（0.18.0 起；0.19.0 起默认关、设置页可开） | ✅ **有真机证据**：2026-10-09 用户在桌面应用点「选择工作区目录」，实测「成功替换为系统文件管理器」（先用 profile 补丁验过一次，之后的插件内 shadow 版走的是同一条 preload 桥）；`node test/directory-flow.mjs` 49 条 + 变异 FS–FY（判定/状态机）与 GZ/HA（开关幂等装卸）罩着 |
 | **设置字段全部进了宿主 schema**（0.19.2 起） | `test/client-registration.mjs` 第 16 节：把设置契约里 49 个 `*_FIELD` 常量逐个核对 `ownSchema()`，再点名 6 个（5 个通知 + 目录选择）+ 变异 HG/HH。**为什么值得单列一行**：写设置走 `settings.mutate`，字段没进 schema 会被直接抛 `Config field "…" is not volatile` —— 0.17.0 的 5 个通知字段就是这么漏的（症状是"开关拨不动 + 写入失败提示"），2026-10-09 才发现并修掉 |
 | 发布门禁三条判据 | `npm run gates` 全过；`check:tag` 实测 `v0.12.0` 的 tag 名与所指提交里的版本一致 |
@@ -690,9 +711,9 @@ node build.mjs                    # 产出 lib/index.js + lib/client.js
                                   #   ⚠️ 宿主半会**内联** schemastery / cosmokit：
                                   #   优先用 DSH 检出里的 vendor 副本，检出不在时退到 node_modules
                                   #   里同版本的 npm 包（两者逐字节相同）——CI 上走的就是退路
-npm test                          # 30 个套件；当前 2569 passed, 0 failed（2026-10-09 实测；CI 三平台同样全绿）
+npm test                          # 31 个套件；当前 2676 passed, 0 failed（2026-10-09 实测；CI 三平台同样全绿）
                                   #   走 scripts/run-tests.mjs：顺带把"多少套件/多少条"记进 test/.last-run.json
-npm run test:mutations            # 手动跑：变异测试，证明那套护栏真的在咬人（189 条，须单独跑）
+npm run test:mutations            # 手动跑：变异测试，证明那套护栏真的在咬人（206 条，须单独跑）
                                   #   同样记录结果，供下面的文档门禁核对
 npm run gates                     # 发版门禁三条一起跑：tag 指向 / 包内容 / 文档数字
 npm run check:tag                 #   ① tag 名里的版本 == 该 tag 所指提交里的 package.json 版本

package/bin/dsh-composer-ux.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+/**
+ * `dsh-composer-ux` 命令行（0.22.0）。
+ *
+ * 为什么要有它（借鉴 dsh-ops 的 install/status/uninstall）：
+ *   · 安装：官方 CLI 的用法与"保留 profile"的坑（桌面端得用应用自带的那个 CLI）对新手不友好，
+ *     这里把探测与提示做掉，**但绝不自己实现一套 profile 锁与回滚** —— 一律委托官方 CLI；
+ *   · 排障：`status` / `doctor` 把"装到哪了、版本对不对、依赖在不在"直接打出来。
+ *     更完整的运行时报告（设置字段、终端替换、请求头覆盖…）在设置页那张「自检」卡里 ——
+ *     那需要跑在宿主进程里读服务，CLI 拿不到。
+ *
+ * 用法：
+ *   npx dsh-composer-ux status  [--profile desktop]
+ *   npx dsh-composer-ux doctor  [--profile desktop] [--dsh-cli <path>]
+ *   npx dsh-composer-ux install [--profile desktop] [--dsh-cli <path>] [--version 0.22.0]
+ *   npx dsh-composer-ux uninstall [--profile desktop] [--dsh-cli <path>]
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const PACKAGE = 'dsh-composer-ux'
+const SELF = dirname(dirname(fileURLToPath(import.meta.url)))
+const own = JSON.parse(readFileSync(join(SELF, 'package.json'), 'utf8'))
+
+/** 解析 `--flag value` 风格的参数（不做花哨的短选项）。 */
+function parseArgs(argv) {
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (token.startsWith('--')) {
+      const key = token.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith('--')) out[key] = true
+      else { out[key] = next; i += 1 }
+    } else out._.push(token)
+  }
+  return out
+}
+
+const dshHome = () => (typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME !== ''
+  ? process.env.DSH_HOME
+  : join(homedir(), '.dsh'))
+
+/** 列出所有 profile 及其是否装了本插件。 */
+function listProfiles() {
+  const root = join(dshHome(), 'profiles')
+  const rows = []
+  let names = []
+  try {
+    names = readdirSync(root, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name)
+  } catch {
+    return rows
+  }
+  for (const name of names) {
+    const dir = join(root, name)
+    const manifest = join(dir, 'package.json')
+    let declared = false
+    let installed = ''
+    try {
+      const parsed = JSON.parse(readFileSync(manifest, 'utf8'))
+      declared = parsed?.dependencies?.[PACKAGE] !== undefined
+        || (parsed?.dsh?.profile?.bundles ?? []).includes(PACKAGE)
+    } catch { /* 没有 package.json 就当作没装 */ }
+    const versionFile = join(dir, 'node_modules', PACKAGE, 'package.json')
+    if (existsSync(versionFile)) {
+      try { installed = JSON.parse(readFileSync(versionFile, 'utf8')).version ?? '' } catch { installed = '' }
+    }
+    if (declared || installed !== '') rows.push({ name, dir, declared, installed })
+  }
+  return rows
+}
+
+/**
+ * 找官方 CLI。
+ *
+ * 桌面端必须用它自带的那个（普通 CLI 管不了保留的 `desktop` profile）——这与 dsh-ops 的说明一致。
+ */
+function findDshCli(explicit) {
+  const candidates = []
+  if (typeof explicit === 'string') candidates.push(explicit)
+  if (typeof process.env.DSH_CLI === 'string' && process.env.DSH_CLI !== '') candidates.push(process.env.DSH_CLI)
+  const localAppData = process.env.LOCALAPPDATA ?? ''
+  if (localAppData !== '') {
+    candidates.push(join(localAppData, 'Programs', 'DeepSeek Harness', 'resources', 'runtime', 'cli', 'bin', 'dsh.cmd'))
+  }
+  for (const base of ['C:/Program Files/DeepSeek Harness', 'D:/deepseekharness', 'D:/DeepSeek Harness']) {
+    candidates.push(join(base, 'resources', 'runtime', 'cli', 'bin', 'dsh.cmd'))
+    candidates.push(join(base, 'apps', 'cli', 'lib', 'bin.js'))
+  }
+  candidates.push('dsh')
+  for (const candidate of candidates) {
+    if (candidate === 'dsh') return { cli: candidate, how: 'PATH 上的 dsh' }
+    if (existsSync(candidate)) return { cli: candidate, how: candidate }
+  }
+  return undefined
+}
+
+/** 跑官方 CLI（一律委托，不自己动 profile）。 */
+function runOfficial(cli, args, options) {
+  const isNodeScript = cli.endsWith('.js')
+  const command = isNodeScript ? process.execPath : cli
+  const argv = isNodeScript ? [cli, ...args] : args
+  console.log(`> ${command} ${argv.join(' ')}`)
+  // Windows 上的 .cmd/.bat 包装器必须经 shell 才能起（否则 spawnSync 直接 ENOENT）。
+  const needsShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(command)
+  const result = spawnSync(command, argv, {
+    stdio: 'inherit',
+    windowsHide: true,
+    ...(needsShell ? { shell: true } : {}),
+    ...options,
+  })
+  return result.status ?? 1
+}
+
+function cmdStatus(args) {
+  console.log(`${PACKAGE} ${own.version}（本机 CLI）`)
+  console.log(`DSH_HOME: ${dshHome()}`)
+  const profiles = listProfiles()
+  const only = typeof args.profile === 'string' ? args.profile : undefined
+  const rows = only === undefined ? profiles : profiles.filter(row => row.name === only)
+  const cliForStatus = findDshCli(args['dsh-cli'])
+  const runtimeForStatus = cliForStatus === undefined ? '' : dshRuntimeVersion(cliForStatus.cli)
+  if (rows.length === 0) {
+    console.log(only === undefined ? '没有找到任何装过本插件的 profile。' : `profile ${only} 里没装本插件。`)
+  }
+  for (const row of rows) {
+    console.log(`· profile ${row.name}：${row.declared ? '已在 package.json 里声明' : '只在 node_modules 里'}；装上的是 ${row.installed === '' ? '（读不到版本）' : row.installed}`)
+    const term = toolTerminalState(row.dir, runtimeForStatus)
+    if (term.toolVersion === '') {
+      console.log('    · 持久终端：profile 里没有 @deepseek-ai/dsh-tool-terminal（模型那 6 个 terminal_* 工具会缺）')
+    } else if (term.mismatch) {
+      console.log(`    · ❗持久终端：tool-terminal ${term.toolVersion} 要求 ${term.peerRequired}，profile 里实际 ${term.peerInstalled} ⇒ 宿主会禁用那一行`)
+      console.log(`      修法：dsh plugin --profile ${row.name} add @deepseek-ai/dsh-tool-terminal@<运行时版本>`)
+    } else if (runtimeForStatus !== '' && term.toolVersion !== runtimeForStatus) {
+      // 只是提示：这个 profile 可能属于**另一个安装**（例如桌面应用的 profile），那就正常。
+      console.log(`    · 持久终端：tool-terminal ${term.toolVersion}；与本次所用 CLI 的运行时 ${runtimeForStatus} 不同`)
+      console.log('      （若该 profile 属于另一个安装，这是正常的；要确认就换成那个安装的 CLI 再跑一次 —— 宿主自检那张卡会直接说）')
+    } else {
+      console.log(`    · 持久终端：tool-terminal ${term.toolVersion}（要求 ${term.peerRequired || '无'}，profile 里 ${term.peerInstalled || '读不到'}）`)
+    }
+  }
+  console.log(`官方 CLI：${cliForStatus === undefined ? '没找到（安装/卸载时用 --dsh-cli 指定）' : cliForStatus.how}`)
+  console.log(`运行时版本：${runtimeForStatus || '（读不到）'}`)
+  return 0
+}
+
+/**
+ * 读一个 profile 里「持久终端三件套」的实际状态。
+ *
+ * 为什么 CLI 也要管这件事（2026-10-15 真机踩到）：`@deepseek-ai/dsh-tool-terminal` 声明的是
+ * **精确版本 peer**。若 profile 里装的版本与运行时对不上，宿主只会把那一行禁用 + 启动日志一句
+ * warning，模型工具表里少 6 个 terminal_* 工具，界面上完全看不出来。所以安装时按运行时版本钉住它，
+ * 并在 status/doctor 里核对（判据与宿主半自检那张卡一致：拿 peer 要求比 profile 里实际装的版本）。
+ */
+function toolTerminalState(profileDir, runtimeVersion) {
+  const read = name => {
+    try {
+      return JSON.parse(readFileSync(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'), 'utf8'))
+    } catch {
+      return undefined
+    }
+  }
+  const tool = read('@deepseek-ai/dsh-tool-terminal')
+  const peers = tool?.peerDependencies ?? {}
+  const peerName = Object.keys(peers).find(key => key.startsWith('@deepseek-ai/dsh-')) ?? ''
+  const required = peerName === '' ? '' : String(peers[peerName])
+  /**
+   * ⚠️ 只用 **profile 自己**能证明的东西判"不匹配"。
+   *
+   * 为什么不直接和运行时版本比：一个 profile 属于哪个安装（桌面应用 / 源码检出 / 另一个版本）
+   * 从 profile 目录本身看不出来 —— 2026-10-15 试过，拿检出的 alpha.4 去比桌面 profile 立刻是假阳性
+   * （桌面 profile 的 tool-terminal 是 0.2.0-rc.2，跟它自己的运行时才是对的）。
+   * 所以：profile 里能读到 peer 实际版本时才算"证实的越界"；否则只输出提示（见调用方）。
+   */
+  const installed = required === '' ? '' : String(read(peerName)?.version ?? '')
+  void runtimeVersion
+  return {
+    toolVersion: String(tool?.version ?? ''),
+    peerRequired: required,
+    peerInstalled: installed,
+    mismatch: required !== '' && installed !== '' && required !== installed,
+  }
+}
+
+/** 问官方 CLI 要运行时版本（用于把 tool-terminal 钉到同一版）。 */
+function dshRuntimeVersion(cli) {
+  const isNodeScript = cli.endsWith('.js')
+  const command = isNodeScript ? process.execPath : cli
+  const argv = isNodeScript ? [cli, '--version'] : ['--version']
+  try {
+    const needsShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(command)
+    const out = spawnSync(command, argv, {
+      encoding: 'utf8',
+      windowsHide: true,
+      ...(needsShell ? { shell: true } : {}),
+    })
+    const match = /\d+\.\d+\.\d+[-\w.]*/.exec(String(out.stdout ?? '').trim())
+    return match === null ? '' : match[0]
+  } catch {
+    return ''
+  }
+}
+
+function cmdDoctor(args) {
+  let bad = 0
+  const report = (ok, label, detail) => {
+    console.log(`${ok === true ? '✓' : ok === 'warn' ? '!' : '✗'} ${label}${detail === undefined ? '' : ` — ${detail}`}`)
+    if (ok === false) bad += 1
+  }
+  report(true, '本机 CLI 版本', own.version)
+  const manifestPath = join(SELF, 'dsh-plugin.json')
+  if (existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      report(manifest.version === own.version, '市场清单版本与包版本一致',
+        `${String(manifest.version)} vs ${own.version}`)
+    } catch (error) {
+      report(false, '市场清单可解析', String(error))
+    }
+  } else {
+    report('warn', '市场清单', '没有 dsh-plugin.json（不影响运行）')
+  }
+  report(existsSync(join(SELF, 'lib', 'index.js')), '宿主半产物在', 'lib/index.js')
+  report(existsSync(join(SELF, 'lib', 'client.js')), '客户端半产物在', 'lib/client.js')
+  report(existsSync(join(SELF, 'cordis.patch.yml')), '组合补丁在', 'cordis.patch.yml')
+  const cli = findDshCli(args['dsh-cli'])
+  report(cli !== undefined, '找得到官方 CLI', cli === undefined ? '用 --dsh-cli 指定' : cli.how)
+  const profiles = listProfiles()
+  report(profiles.length > 0 ? true : 'warn', '装到哪个 profile',
+    profiles.length === 0 ? '没有任何 profile 装了它' : profiles.map(row => `${row.name}@${row.installed === '' ? '?' : row.installed}`).join('、'))
+  report('warn', '更完整的运行时自检', '在 DSH 的「设置 → 输入体验 → 自检」里点「运行自检」（需要宿主进程）')
+  console.log(bad === 0 ? '\n结论：本机安装看起来是好的。' : `\n结论：有 ${String(bad)} 项需要处理。`)
+  return bad === 0 ? 0 : 1
+}
+
+function cmdInstall(args) {
+  const profile = typeof args.profile === 'string' ? args.profile : ''
+  if (profile === '') {
+    console.error('必须显式指定 profile：--profile desktop（或 web / 其它已初始化的 profile）')
+    console.error('桌面端要用桌面应用自带的 CLI；本机若探测不到，用 --dsh-cli <path> 指定。')
+    return 2
+  }
+  const cli = findDshCli(args['dsh-cli'])
+  if (cli === undefined) {
+    console.error('找不到官方 DSH CLI。用 --dsh-cli "<安装目录>/resources/runtime/cli/bin/dsh.cmd" 指定。')
+    return 2
+  }
+  if (profile === 'desktop') {
+    console.log('提示：`desktop` 是保留 profile，普通 CLI 管不了它；这里用的是探测到的官方 CLI（桌面自带那个）。')
+  }
+  const spec = typeof args.version === 'string' ? `${PACKAGE}@${args.version}` : `${PACKAGE}@${own.version}`
+  const first = runOfficial(cli.cli, ['plugin', '--profile', profile, 'add', spec])
+  if (first !== 0) return first
+
+  /**
+   * 顺手把持久终端那件「必须与运行时同版」的包按运行时版本钉进 profile。
+   *
+   * 为什么不用插件自己的依赖范围拉（2026-10-15 真机踩到）：范围会被 pnpm 解析成"当前发布的最新
+   * alpha"，一旦比运行时新（或本地元数据缓存旧而选了旧版），宿主就判定不兼容并把那一行禁掉 ——
+   * 模型少 6 个工具，界面无感。profile 层显式钉版本才是确定的（桌面 profile 一直是这么做的）。
+   */
+  const runtime = typeof args['dsh-version'] === 'string' ? args['dsh-version'] : dshRuntimeVersion(cli.cli)
+  if (runtime === '') {
+    console.log('提示：读不到运行时版本，跳过持久终端的版本对齐（可用 --dsh-version <版本> 指定）。')
+    return 0
+  }
+  const pinned = runOfficial(cli.cli, [
+    'plugin', '--profile', profile, 'add', `@deepseek-ai/dsh-tool-terminal@${runtime}`,
+  ])
+  if (pinned !== 0) {
+    console.log(`提示：@deepseek-ai/dsh-tool-terminal@${runtime} 没装上；模型那 6 个 terminal_* 工具会缺（设置页「自检」会显示）。`)
+  }
+  return 0
+}
+
+function cmdUninstall(args) {
+  const profile = typeof args.profile === 'string' ? args.profile : ''
+  if (profile === '') {
+    console.error('必须显式指定 profile：--profile desktop')
+    return 2
+  }
+  const cli = findDshCli(args['dsh-cli'])
+  if (cli === undefined) {
+    console.error('找不到官方 DSH CLI。用 --dsh-cli <path> 指定。')
+    return 2
+  }
+  return runOfficial(cli.cli, ['plugin', '--profile', profile, 'remove', PACKAGE])
+}
+
+function usage() {
+  console.log(`dsh-composer-ux ${own.version}
+
+  status    [--profile <name>] [--dsh-cli <path>]   看装在哪、装的什么版本
+  doctor    [--profile <name>] [--dsh-cli <path>]   本机自检（产物、清单、官方 CLI、profile）
+  install   --profile <name>  [--dsh-cli <path>] [--version <v>]
+  uninstall --profile <name>  [--dsh-cli <path>]
+  help
+
+安装与卸载一律**委托官方 DSH CLI**（不自己动 profile）；运行时自检在
+DSH 的「设置 → 输入体验 → 自检」里那张卡（它需要跑在宿主进程里读服务）。`)
+}
+
+const argv = process.argv.slice(2)
+const args = parseArgs(argv)
+const command = args._[0] ?? 'help'
+let code = 0
+if (command === 'status') code = cmdStatus(args)
+else if (command === 'doctor') code = cmdDoctor(args)
+else if (command === 'install') code = cmdInstall(args)
+else if (command === 'uninstall') code = cmdUninstall(args)
+else if (command === 'help' || command === '--help' || command === '-h') usage()
+else {
+  console.error(`不认识的子命令：${command}`)
+  usage()
+  code = 2
+}
+process.exit(code)

package/dsh-plugin.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://raw.githubusercontent.com/T-Auto/dsh-std/8a15541117cb3c13ddb8f2468308691b6051d162/packages/manifest/schema/dsh-plugin-0.15.schema.json",
+  "manifestVersion": "0.15",
+  "id": "dsh-composer-ux.input-experience",
+  "name": "dsh-composer-ux",
+  "version": "0.22.0",
+  "license": "MIT",
+  "facets": {
+    "host": {
+      "entry": "lib/index.js",
+      "apiVersion": "v1alpha1"
+    },
+    "client": {
+      "entry": "lib/client.js",
+      "platform": "web"
+    }
+  },
+  "requires": {
+    "contracts": []
+  },
+  "permissions": [
+    {
+      "name": "dsh-composer-ux.fs.read",
+      "scope": "dsh-home",
+      "reason": "Read the plugin's own files under <DSH_HOME>: quick-prompts.json, optimizer state, and the profile's settings document to resolve this plugin's config."
+    },
+    {
+      "name": "dsh-composer-ux.fs.write",
+      "scope": "dsh-home",
+      "reason": "Write only the plugin's own files under <DSH_HOME>: quick-prompts.json, optimizer dock state, and this plugin's own settings namespace. It never writes another plugin's config (the 0.21 request-header write path was replaced by a runtime overlay in 0.22.0)."
+    },
+    {
+      "name": "dsh-composer-ux.process.spawn",
+      "scope": "subprocess",
+      "reason": "Start the DSH restart helper when the user asks to restart, probe the local Git Bash path for the terminal swap, and (only when the user enables it) run the optimizer's fact-checking shell tool confined by ctx.sandbox.confine or limited to danger-full-access sessions."
+    }
+  ],
+  "contributes": {
+    "x-display": [
+      {
+        "icon": "./icon.png",
+        "title": "dsh-composer-ux",
+        "description": "输入体验增强：键位、右键菜单、快捷指令、提示词优化、通知、统计与成本、目录选择、终端策略（八栏，逐栏开关）"
+      }
+    ],
+    "x-prompt-sections": [
+      {
+        "name": "dsh-composer-ux:optimizer",
+        "order": 4200,
+        "summary": "提示词优化器只在用户点「✨ 优化提示词」时组装的一段调用说明；不写 AGENTS.md，设置里关掉即不注入。"
+      }
+    ]
+  },
+  "subscriptions": []
+}