dsh-tool-switch 0.0.0-stage → 0.2.1

package/INSTALL.md

@@ -0,0 +1,321 @@
+# 安装指南
+
+> 适用：**DSH Desktop 0.13.x**（内置 DeepSeek Harness `0.2.2-alpha.x`）与同版本的 `dsh` CLI。
+> 插件本身**零依赖、无需构建**：`index.js` 是 Host 半侧（Node ESM），`lib/client.js` 是手写的
+> 客户端 bundle（`window.__ModuleLoader__.load({ id, factory })` 格式，与官方插件产物同构）。
+
+安装有两条路，选一条就好：
+
+| 方式 | 适合谁 | 特点 |
+|---|---|---|
+| **A. 作为「组合包」安装**（推荐） | 一般用户 | 插件页点几下就装上；升级 DSH 后仍在；可随时停用/卸载 |
+| **B. 在补丁层里手工挂载** | 想直接对着源码改、或不想让包管理器动 profile | 立刻热生效，改完就见效；但 profile 重装/清理时可能丢 |
+
+> 两条路**不要同时用**——同一份插件被两个 Loader 入口解析到，客户端会报
+> `package dsh-tool-switch resolves from multiple active Loader sources` 并拒绝组图。
+
+---
+
+## 0. 先认清三个位置
+
+| 名字 | 是什么 | 怎么找 |
+|---|---|---|
+| **插件目录** `<PLUGIN_DIR>` | 这个仓库放在哪 | 你自己放的地方，例如 `C:\Users\<你>\Documents\Codex\dsh-tool-switch` |
+| **Profile 目录** `<PROFILE_DIR>` | 当前正在跑的那套插件组合 | 见下表；有 `cordis.patch.yml`、`package.json`、`node_modules` |
+| **Harness 数据目录** `<HARNESS_DIR>` | 会话、日志、`cordis.patch.yml` 所在 | 见下表；日志在 `<HARNESS_DIR>\logs\harness.log` |
+
+| 系统 | `<HARNESS_DIR>` | `<PROFILE_DIR>`（默认 profile 名 `web`） |
+|---|---|---|
+| Windows | `%APPDATA%\dsh-desktop\harness` | `<HARNESS_DIR>\profiles\web` |
+| macOS | `~/Library/Application Support/dsh-desktop/harness` | `<HARNESS_DIR>/profiles/web` |
+| Linux | `~/.config/dsh-desktop/harness` | `<HARNESS_DIR>/profiles/web` |
+
+**怎么确认自己找对了**：`<PROFILE_DIR>\package.json` 里有 `"dsh": { "profile": { "bundles": [...] } }`，
+`<PROFILE_DIR>\cordis.patch.yml` 里有你装过的其它插件（`dsh-ops`、`dsh-market` 之类）。
+
+想在命令行里确认（Desktop 拉起 Harness 时会注入这些变量，普通终端里没有）：
+
+```powershell
+# PowerShell（Windows 预设）
+$env:DSH_PROFILE_DIR      # -> <PROFILE_DIR>
+$env:DSH_PROFILE          # -> web
+```
+
+```bash
+# bash（macOS / Linux）
+echo "$DSH_PROFILE_DIR" "$DSH_PROFILE"
+# 或者：dsh --profile web --dump-config | head -40
+```
+
+---
+
+## 方式 A：作为组合包安装（推荐）
+
+这个仓库根目录带着 `package.json` 的 `dsh.bundle.patch` 与 `cordis.patch.yml`，
+所以它本身就是一个可安装的**组合包**：装上去之后，它自带的补丁层会把 Host 入口接进插件树，
+不需要你手改任何 profile 配置。
+
+### A-1 用界面装（最省事）
+
+1. 左侧栏点 **插件**（不是「设置 → 插件」，那里是只读列表）。
+2. 点 **安装**，把 **插件目录的绝对路径** 贴进去，例如
+   `C:\Users\<你>\Documents\Codex\dsh-tool-switch`。
+   也可以粘这个仓库的地址：`https://github.com/suqing114/dsh-tool-switch`。
+3. 确认安装 → 等日志跑完（本插件没有依赖，通常一两秒）。
+4. 安装完它会自动被选中/启用。**刷新页面（Ctrl+R）**，输入框下方出现 `⚙ 工具` 胶囊即成功。
+
+> 装的是本地目录时，profile 记录的是 `link:<绝对路径>`：以后你在这个仓库里改代码，
+> 效果直接跟着变（Host 侧改完仍需重启，客户端 bundle 会热替换）。
+
+### A-2 用 agent / CLI 装
+
+在 DSH 里让 agent 装（Full access 下不会弹审批）：
+
+```
+用 plugin_manager 的 install_bundle，target 指向 C:\Users\<你>\Documents\Codex\dsh-tool-switch
+```
+
+或命令行：
+
+```powershell
+dsh plugin install "C:\Users\<你>\Documents\Codex\dsh-tool-switch"
+dsh plugin list                     # 确认 dsh-tool-switch 在列表里且已启用
+```
+
+### A-3 卸载
+
+- 界面：**插件** 页找到 `dsh-tool-switch` → 取消选择 / 移除。
+- CLI：`dsh plugin remove dsh-tool-switch`。
+- 移除后刷新页面，按钮消失；`<HARNESS_DIR>\dsh-tool-switch\state.json`（或
+  `~/.dsh-tool-switch/state.json`）可以留着，也可以删掉。
+
+---
+
+## 方式 B：在补丁层里手工挂载
+
+适合「我就在改这份源码」的场景。两种写法二选一。
+
+### B-1 直接指向目录（file URL，本机现在用的就是这种）
+
+编辑 `<HARNESS_DIR>\cordis.patch.yml`，在**末尾**追加（注意 YAML 顶层是数组，前面的条目不要动）：
+
+```yaml
+- insert:
+    - id: dsh-tool-switch
+      name: "file:///C:/Users/<你>/Documents/Codex/dsh-tool-switch/index.js?v=1"
+      config:
+        stateDir: C:\Users\<你>\AppData\Roaming\dsh-desktop\harness\dsh-tool-switch
+```
+
+- Windows 路径写成 `file:///C:/...`（正斜杠，三个斜杠）；macOS/Linux 例如
+  `"file:///Users/<你>/code/dsh-tool-switch/index.js?v=1"`。
+- `?v=1` 是 **ESM 模块缓存版本后缀**：Host 侧代码改过之后，把这个数字 +1（或重启 DSH）
+  才会加载新代码；客户端 `lib/client.js` 不用管，它按 mtime 自动热替换。
+- `config` 可以整段省略（默认状态目录是 `~/.dsh-tool-switch`）。
+- **热生效**：保存文件后 Loader 会自己重挂，不用重启；页面刷新一次即可看到按钮。
+- **卸载**：删掉 `- insert:` 这整块（连同它下面的两行），保存即可热卸载；
+  插件卸载时会自动撤销它装过的所有工具遮罩。
+
+### B-2 拷进 profile 的 node_modules，用包名挂
+
+```powershell
+# Windows：把仓库复制进 profile 的 node_modules（不要用符号链接，pnpm 清理时容易断）
+Copy-Item -Recurse "C:\Users\<你>\Documents\Codex\dsh-tool-switch" `
+  "$env:APPDATA\dsh-desktop\harness\profiles\web\node_modules\dsh-tool-switch"
+```
+
+```yaml
+- insert:
+    - id: dsh-tool-switch
+      name: "dsh-tool-switch"
+```
+
+> 注意：这种方式下次 `pnpm install` / 插件页装别的包时，可能把这份拷贝清掉。
+> 要长期用请走**方式 A**。
+
+---
+
+## 方式 C：用包管理器装（Git / tarball / 注册表）
+
+先弄清一件事：`pnpm add` 只把包放进 `node_modules`，DSH 还要知道「这个组合包要参与组合」。
+所以是**两步**——先装包，再让 profile 认它（插件页做的就是这两步）。
+
+### C-1 从 GitHub 直接装
+
+```powershell
+cd <PROFILE_DIR>
+pnpm add github:suqing114/dsh-tool-switch#v0.2.0     # 建议锁 tag，别跟 main 漂移
+```
+
+然后二选一让 profile 认它：
+
+- 把 `"dsh-tool-switch"` 加进 `<PROFILE_DIR>\package.json` 的 `dsh.profile.bundles` 数组
+  （它自带补丁层，会自动插入 Host 入口）；
+- 或者在 `<HARNESS_DIR>\cordis.patch.yml` 里 insert 一行 `name: 'dsh-tool-switch'`（用包名）。
+
+> 实测（2026-11-13，pnpm 10.34.5）：空目录里 `pnpm add github:suqing114/dsh-tool-switch` →
+> `+ dsh-tool-switch 0.2.0`；装出来的 `index.js`、`lib/client.js` 都能过 `node --check`，
+> `dsh.bundle.patch` / `dsh.client` 声明完整。
+
+### C-2 从本地 tarball 装
+
+```powershell
+cd <PLUGIN_DIR>
+npm pack                                    # 产出 dsh-tool-switch-0.2.0.tgz，28 kB，只含发布文件
+cd <PROFILE_DIR>
+pnpm add "file:C:\Users\<你>\Documents\Codex\dsh-tool-switch\dsh-tool-switch-0.2.0.tgz"
+```
+
+### C-3 从 npm 注册表装
+
+#### 现状（2026-11）
+
+`npmjs.com` 上账号 `suyuqing` 开了 **通行密钥（passkey）2FA**。对这种情况 npm 的规则是：
+CLI 发布必须带一次性密码 **或者** 带 bypass-2FA 的令牌——而 passkey 产生不了 6 位数字，
+所以「交互式 2FA 发布」这条在 CLI 上走不通（`npm publish` 只会打印一个被脱敏的
+`https://www.npmjs.com/auth/cli/***` 然后 `EOTP` 退出，即使给它真 TTY 也一样）。
+
+因此**首次发布**要用一次**短命凭据**，之后全部改用 OIDC，长期不留任何 token。
+
+#### ① 首次发布（只做一次，需要凭据）
+
+在 npmjs.com → Access Tokens 生成一个 **Granular Access Token**：
+
+- ✅ **Bypass two-factor authentication**
+- Permissions：**Read and write**
+- **Expiration：7 days 或更短**（做完就删）
+
+然后在本目录用它发一次（token 只进临时文件，别写进仓库、别进 CI）：
+
+```powershell
+$tmp = "$env:TEMP\npmrc-publish"; "//registry.npmjs.org/:_authToken=`${NODE_AUTH_TOKEN}" | Set-Content $tmp -Encoding ascii
+$env:NODE_AUTH_TOKEN = "npm_xxx"        # 刚生成的短命 token
+npm publish --userconfig $tmp           # publishConfig 已是 public
+Remove-Item $tmp                        # 立刻删掉临时文件
+# 发布成功后，回 npmjs 把这个 token 吊销
+```
+
+#### ② 之后永久改成 OIDC（不用 token、不用 2FA）
+
+npmjs.com → 这个包 → **Settings → Trusted publishing**（GitHub Actions）：
+
+| 字段 | 值 |
+|---|---|
+| Organization or user | `suqing114` |
+| Repository | `dsh-tool-switch` |
+| Workflow filename | `publish.yml` |
+| Allowed actions | `npm publish` |
+
+再把 **Publishing access** 改成 **“Require two-factor authentication and disallow tokens”**。
+这样连 bypass token 都不允许用，只剩仓库里的 `.github/workflows/publish.yml` 能发（它走 OIDC +
+provenance，`permissions: id-token: write`，全程没有任何密钥）。
+
+之后发版就是：
+
+```powershell
+# 改完 package.json 的 version
+git tag v0.2.1; git push --tags     # 工作流自动发布 + 生成 provenance
+```
+
+#### ③ 装
+
+```powershell
+pnpm add dsh-tool-switch        # 或在插件页里直接装 dsh-tool-switch
+```
+
+> 首次发布前可以用 `npm publish --dry-run` 看清单：本仓库当前是
+> `package size 29.4 kB / unpacked 84 kB / total files 10`。
+
+### C-4 本地开发：link 进去
+
+```powershell
+cd <PROFILE_DIR>
+pnpm add "link:C:\Users\<你>\Documents\Codex\dsh-tool-switch"
+```
+
+之后你改仓库里的代码，profile 里的那份立刻跟着变（Host 侧仍需重启或换 `?v=`）。
+
+> ⚠️ 已经用方式 A / B 装过的，**不要再用 pnpm 装一遍**：同一份插件被两个 Loader
+> 来源解析到，客户端会报 `resolves from multiple active Loader sources` 并拒绝组图。
+> 换方式之前先把旧的那条摘掉。
+
+## 装完怎么验（三条，从底层往上）
+
+```powershell
+# 1) Host 路由活着：200 + JSON；不带 session 应 400；随便一个路径应 404
+curl.exe "http://127.0.0.1:43129/tool-switch/state?session=test"
+curl.exe "http://127.0.0.1:43129/tool-switch/state"
+```
+
+```powershell
+# 2) 客户端启动图里有这一行（bundle 也能取到）
+cd <PLUGIN_DIR>
+node test\probe-client-graph.mjs
+# 期望：entries 里出现 {"id":"dsh-tool-switch","url":"plugins/??dsh-tool-switch/client.js&rev=…"}
+#      并且 bundle … 含我的代码: true
+```
+
+3. 页面里：输入框卡片**正下方那一行**、靠右、紧挨 `56%` 上下文档位左边 → `⚙ 工具` 胶囊。
+   点开是分组面板（默认全部收起），每类后面有 `全关 / 全开`。
+
+端口不是 43129 的话（`dsh web --port` 或用别的方式起的），把地址换成实际端口；
+`test\paths.mjs` 里所有路径/端口都能用环境变量覆盖：
+
+```powershell
+$env:DSH_URL = "http://127.0.0.1:38999"
+$env:DSH_HARNESS = "D:\elsewhere\harness"
+node test\probe-route.mjs
+```
+
+---
+
+## headless / QQ 这类没有输入框的入口
+
+按钮是给页面用的。没有页面（甚至没有 `webServer`）的时候，用另外两条通道——它们和按钮写同一份状态：
+
+1. **直接跟模型说**：在会话里说「把 rea 那类工具关掉 / 打开」，模型会调用 `tool_switch`
+   （`action: off|on|list|reset`，`target` 认分组名、`mcp__rea__` 前缀、精确工具名或 `all`）。
+   这条**不需要 webServer**，只要有 agent 能跑工具就行，QQ 那种转发式入口最合适。
+2. **斜杠命令**（需要该入口有命令适配器，例如 CLI 或网页 composer）：
+
+   ```
+   /tools                     看分组与当前开关
+   /tools off rea             关掉整组
+   /tools on mcp__rea__       按前缀打开
+   /tools all off｜all on      全关 / 全开
+   /tools reset               全部恢复
+   ```
+
+3. **HTTP**（有 `webServer` 时，脚本/外部程序用）：
+
+   ```bash
+   curl "http://127.0.0.1:43129/tool-switch/state?session=session-<uuid>"
+   curl -X POST "http://127.0.0.1:43129/tool-switch/state" \
+        -H 'content-type: application/json' \
+        -d '{"session":"session-<uuid>","disabled":["mcp__rea__open_binary"]}'
+   ```
+
+> `webServer` 只有 `dsh-web-app` 这个组合包会挂（桌面版、`dsh web` 自带；纯 CLI 组合没有），
+> 所以脚本方案在没有页面的部署里要先确认这条路由存在（404 = 没挂，改用前两条）。
+> `tool_switch` 自己不会被关掉，`all off` 之后它也还在，所以永远留着一个人能改回来的入口。
+
+## 常见问题
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| `curl …/tool-switch/state` 返回 **404** | 补丁没生效：确认 `- insert:` 块在 `cordis.patch.yml` 末尾、`id` 没拼错、文件保存了；看 `<HARNESS_DIR>\logs\harness.log` 里有没有 `patch: entry … not found` 之类的行；方式 B 下重新触发一次热加载（随便改一下该文件）即可 |
+| 路由 200，但页面**没有按钮** | 客户端半侧没加载：先 Ctrl+R 硬刷；再跑第 2 条验证。若启动图里没有这一行，说明 `package.json` 的 `dsh.client` 没被读到——方式 B-1 改 `package.json` 后需要重启 DSH |
+| 日志里 `resolves from multiple active Loader sources` | 同一份插件被挂了两遍（比如方式 A 和 B 同时开）。留一条，删掉另一条 |
+| 改了 `index.js`，行为没变 | Host 侧代码只在条目重启时重新导入：方式 B-1 把 `?v=` 数字 +1，或重启 DSH |
+| 改了 `lib/client.js`，样式没变 | 客户端 bundle 按 mtime 热替换，通常几秒内生效；没生效就 Ctrl+R |
+| 面板里有些工具标 `· 会话固定`、勾选框是灰的 | 那是 agent 作用域内注册的工具，框架规定 `tools.restrict` 管不到它们（例如某些预设注册的 `ops_discover_tools`） |
+| 关掉工具后模型“看不见”了，但我想验证真的挡住了 | 关掉某工具后让它调用一次，会得到 `UNKNOWN_TOOL`；`test\probe-live-restrict.mjs` 是同一路径的自动版（不会真的隐藏任何工具） |
+| 想一次性恢复默认 | 删掉状态文件（`<HARNESS_DIR>\dsh-tool-switch\state.json` 或 `~/.dsh-tool-switch/state.json`），或在面板里点 `全开` |
+
+## 安全边界
+
+- 路由只监听 loopback（Harness 的 `webServer` 本来就这么绑），同源访问；
+  `/api` 那套鉴权不覆盖它，因此**本机**任何进程都能读写这个状态——它只影响“本会话模型能用哪些工具”，
+  不涉及凭证、文件内容或执行权限。
+- 插件不联网、不读环境变量里的密钥；唯一的磁盘写入是它自己的 `state.json`。
+- 状态按 sessionId 存，换会话互不影响；插件被卸载/停用时所有遮罩会被撤销，工具集合回到全开。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Su Yuqing (suqing114)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# dsh-tool-switch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+会话级「工具开关」：在输入框下面加一个**工具**按钮，点开按分组勾选这个会话里模型可以用的工具。
+关掉的工具不会出现在系统提示词的工具清单里，模型也调不到（调用会得到 `UNKNOWN_TOOL`），改完下一条消息就生效，随时可以再改。
+
+```
+┌──────────────────────────────────────────────┐
+│ 本会话可用工具                     12/330  ×  │
+│ [ 搜索工具… ]                      [全开][全关]│
+│ ▾ 会话与计划            12/12                 │
+│ ▾ 终端与执行             4/4                  │
+│    ☑ pwsh           Run a PowerShell command. │
+│    ☐ job_list       List background jobs.     │
+│ ▾ rea · MCP            205/207                │
+│ ▸ 图像与音视频           5/5   （点组名=整组开关）│
+│ 改动从下一条消息开始生效；被关闭的工具模型既看不到也调用不了。│
+└──────────────────────────────────────────────┘
+```
+
+## 它做了什么
+
+- **按钮位置**：`conversation.composer.dock`——输入框（那个带花边的输入卡片）**正下方那一行**，
+  靠右、紧挨着上下文档位圆环（`56%` 那个）左边，是个描边胶囊：`⚙ 工具`。
+  关过工具后会变成强调色 + 一个小数字徽章（`工具 3` = 关了 3 个），悬停有提示。
+- **默认全收起**：面板一打开（以及切换会话后）所有分类都是收起的，只列 `▸ 分类名 已开/总数 [全关][全开]`，
+  想看某一组再点 `▸` 展开。工具栏上有 `展开` / `收起` 一次铺开或收拢所有分类；搜索时命中项会自动展开。
+- **一键整组**：每个分组标题行右侧有 `全关` / `全开` 两个小按钮——`全关` 一次关掉这一组下所有可关闭的
+  工具（锁定的那些自动跳过），`全开` 一次恢复。当前已经是目标状态的那个按钮会置灰，不会点了没反应还让人怀疑人生。
+  点组名本身也还是整组开关（老入口保留）。
+- **分组浏览**：内置能力按 会话与计划 / 终端与执行 / 文件与检索 / 网络检索 / 子代理与编排 /
+  文档与演示 / 图像与音视频 / MCP 资源 / 社交与发布 / 工具链与维护 分类；MCP 工具按服务器
+  （`mcp__<server>__*`）单独成组；认不出来的按名字前缀兜底。支持搜索、折叠（搜索时自动展开）。
+- **按会话记忆**：选择存在 `state.json` 里，按 sessionId 记「关掉了哪些」，重启后仍然生效。
+- **可放进对话中途改**：直接改就行，下一次模型请求开始用新的集合。
+- 面板用 `Esc` 或点面板外任意处关闭；`Esc` 在捕获阶段被面板吃掉并阻止冒泡，所以**不会**顺手把正在跑的回合停掉。
+- 折叠状态是「一次性」的：关掉面板或换会话就回到全收起，不会记住你上次展开了哪组（刻意的，省得下次点开一堆）。
+
+## 原理（为什么它真的能挡住工具）
+
+Host 侧用的是框架自带的按 agent 遮罩：
+
+```js
+// 只有通过 agent 作用域上下文调用，遮罩才只作用于这个 agent
+agent.ctx.tools.restrict({ allow: [...这个会话允许的工具名] })
+```
+
+- 遮罩会同时作用于「提示词里的工具清单」「PTC 绑定」和「执行时的工具集合」，所以不是把 UI 藏起来，
+  而是模型真的看不到、也调不到。
+- 插件记的是**关闭集合**而不是开启集合：`allow = 该 agent 可限制的工具 − 关闭集合`。这样后来才连上的
+  MCP 工具默认就是可用的，不会被悄悄藏掉。
+- 监听了 `agent/created` / `agent/disposed` / `tools/change`：新建会话、工具集合变化（MCP 晚了注册、
+  插件热插拔）都会自动重算；只有 allow 集合真的变了才重装遮罩，避免无谓地让提示词前缀失效。
+- 插件卸载时会撤掉自己装的所有遮罩（插件不在，就不该继续改会话能力）。
+
+浏览器半侧是一个手写的客户端 bundle（`lib/client.js`，与官方插件产物同构的
+`window.__ModuleLoader__.load({ id, factory })` 形式），注册进 `conversation.composer.dock`
+这个 list slot，通过同源 `fetch` 和 Host 通信：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/tool-switch/state?session=<id>` | 工具目录 + 当前选择（分组、描述、是否可关闭） |
+| `POST` | `/tool-switch/state` | body `{ session, disabled: [工具名…] }`，空数组=全部启用 |
+
+路由挂在框架的 `webServer` 上，同源、只监听回环；`/api` 那套鉴权不覆盖它，所以页面里 `fetch` 直接用。
+
+## 三个入口，同一份状态
+
+按钮只是壳。真正改状态的路径有三条，写的是同一份 `state.json`、走同一个重装逻辑：
+
+| 入口 | 谁用 | 依赖 |
+|---|---|---|
+| 输入框下方的 `⚙ 工具` 按钮 | 桌面版 / 网页版 | 需要页面（客户端 bundle） |
+| `/tools` 斜杠命令 | 有命令适配器的交互式入口（CLI、网页 composer） | 需要 `ctx.commands`，不需要 webServer、不进模型上下文 |
+| `tool_switch` 工具 | **任何入口，包括 QQ / headless** | 只需要模型能调工具 |
+
+```text
+/tools                       看分组和当前开关
+/tools off rea               关掉 rea 这一组（也认 终端与执行 / mcp:rea / mcp__rea__* / 精确工具名 / all）
+/tools on mcp__rea__         按前缀整片打开
+/tools all off | all on      全关 / 全开（动词在前后都认）
+/tools reset                 全部恢复
+```
+
+模型那边同理：用户说「把 XX 类工具关掉」时它会调用 `tool_switch`（`action: off|on|list|reset` + `target`），
+QQ 这种没有 UI、也没有 webServer 的部署就靠这条。`tool_switch` 自己**永远不会被关掉**——否则唯一的
+headless 入口就没了，所以即使 `all off` 它也留在 allow 集合里。
+
+## 安装 / 卸载
+
+**完整步骤看 [INSTALL.md](INSTALL.md)**（四种装法、三条验证命令、常见问题、跨平台路径都在那儿）。速览：
+
+1. 把仓库放到任意目录，例如 `C:\Users\<你>\Documents\Codex\dsh-tool-switch`。
+2. 挑一种挂上去：
+   - **A（推荐）当作组合包安装**：DSH 左侧栏 **插件 → 安装**，填这个目录的绝对路径
+     （或本仓库地址），确认后再刷新页面。仓库自带的 `cordis.patch.yml` 会负责接好 Host 入口。
+   - **C 包管理器直装**（就是「别的插件怎么装我就怎么装」）：
+
+     ```powershell
+     cd <PROFILE_DIR>
+     pnpm add github:suqing114/dsh-tool-switch#v0.2.0   # 或 file:<本地 tgz> / link:<本地目录>
+     # 再把 "dsh-tool-switch" 加进本文件 dsh.profile.bundles（或用包名写进 cordis.patch.yml）
+     ```
+
+     `pnpm add` 只负责放包，profile 还得知道这个组合包要参与组合——两步都要做。
+   - **B 手工挂进补丁层**：在 `<HARNESS_DIR>\cordis.patch.yml` 末尾追加
+     （Windows 下 `<HARNESS_DIR>` = `%APPDATA%\dsh-desktop\harness`）：
+
+     ```yaml
+     - insert:
+         - id: dsh-tool-switch
+           name: "file:///C:/Users/<你>/Documents/Codex/dsh-tool-switch/index.js?v=1"
+           config:
+             stateDir: C:\Users\<你>\AppData\Roaming\dsh-desktop\harness\dsh-tool-switch
+     ```
+
+     `?v=1` 只是 ESM 模块缓存的版本后缀：Host 侧代码改过之后把它 +1（或重启 DSH）才会重新加载。
+     **卸载**：删掉这整块即可（loader 会热卸载，插件装过的遮罩会一起撤销）。
+3. 刷新页面（Ctrl+R），输入框下方出现 `⚙ 工具` 胶囊。
+
+> A、B **不要同时用**：同一份插件被两个 Loader 入口解析到，客户端会报
+> `resolves from multiple active Loader sources` 并拒绝组图。
+
+状态文件：`<HARNESS_DIR>\dsh-tool-switch\state.json`（走 A 且没配 `stateDir` 时是 `~/.dsh-tool-switch/state.json`），
+格式 `{ version, sessions: { "<sessionId>": { disabled: [...] } } }`；删掉它等于把所有会话恢复成「全部启用」。
+
+### 测试脚本的路径
+
+`test\paths.mjs` 集中解析路径与端口，都可用环境变量覆盖，仓库里没有写死任何个人目录：
+
+| 变量 | 默认值 | 用途 |
+|---|---|---|
+| `DSH_APP` | `C:\Program Files\DSH Desktop\resources\app\package.json` | 借 app 自带的 React 做渲染测试 / 读前端 chunk |
+| `DSH_HARNESS` | `%APPDATA%\dsh-desktop\harness` | 补丁层、profile node_modules、日志 |
+| `DSH_URL` | `http://127.0.0.1:43129` | 探针打哪个 web GUI |
+| `SESSION` | 无 | 活会话探针要探测的 `session-<uuid>` |
+
+## 找不到按钮时按这个顺序查
+
+1. **它很小**：12px 字、在输入框正下方那行的最右端（`⚙ 工具`，描边胶囊，左边是 `缓存命中 …`、
+   右边是 `56%` 上下文档位）。
+2. **宿主半侧活着吗**：`curl http://127.0.0.1:43129/tool-switch/state?session=x` 应该返回
+   `{"ok":true,...}`；`/tool-switch/state`（不带 session）返回 400；别的路径 404。
+   若 404，说明补丁条目没生效（看 `harness\logs\harness.log`），把插件停掉再启用一次即可。
+3. **客户端半侧加载了吗**：`node test\probe-client-graph.mjs`——启动图里应有
+   `{"id":"dsh-tool-switch","url":"plugins/??dsh-tool-switch/client.js&rev=…"}` 且 bundle 里能找到
+   我们的代码。改 `lib/client.js` 后 `rev` 会变，页面会自动热替换；改 `index.js`（Host 侧）需要
+   换 `?v=` 或重启。
+4. **页面太旧**：Ctrl+R 硬刷新一次。
+
+## 已知边界
+
+- **agent 作用域里注册的工具关不掉**：框架规定「查看作用域自己的注册不受 restrict 影响」。这类工具在面板里
+  标成 `· 会话固定` 且勾选框禁用（例如 agent preset 注册的 `ops_discover_tools`）。
+- **只有按会话，没有全局默认**：新会话默认全部启用；想要「默认关掉某些」需要再加一层设置命名空间。
+- **遮罩按 allow 列表生效**：如果你先关了工具，之后又有同名工具被重新注册，`tools/change` 会重算并把它算进
+  「默认启用」。
+- **面板没有写 i18n 字典**：文案是中文硬编码（内联在 bundle 里），没有走 `ctx.locale`。
+
+## 自测
+
+```bat
+node test\test-host.mjs             :: Host：分组/持久化/restrict 重装/HTTP 路由/卸载清理（10 项）
+node test\test-client.mjs           :: 客户端：bundle 协议、slot 注册形状、默认收起、整组一键、真实 React 渲染（6 项）
+node test\verify-config.mjs         :: 本机补丁层 + 本仓库的组合包声明（bundle patch / locale / icon）
+node test\verify-client-inject.mjs  :: dsh.client.inject 点名的包确实是启动图里的行
+node test\probe-route.mjs           :: 打真实实例，看 400 / 200 / 404
+node test\probe-client-graph.mjs    :: 启动图里有没有这一行、bundle 能否取到
+node test\probe-live.mjs            :: $env:SESSION=… 后看某个会话的目录/agent 视图
+```
+
+`test\test-host.mjs` 用最小 ctx 桩跑通主路径；`test\test-client.mjs` 借 app 自带的 React 做静态渲染。
+路径与端口都由 [test/paths.mjs](test/paths.mjs) 解析，可用 `DSH_APP` / `DSH_HARNESS` / `DSH_URL` / `SESSION` 覆盖。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-tool-switch 作为组合包挂载时，由这一层把 Host 半侧的入口接进插件树。
+#
+# name 用包名（不是文件路径）：组合包安装后，profile 的 node_modules 里能解析到这个包。
+# 想固定状态目录或改路由，在 config 里追加即可，例如：
+#   config:
+#     stateDir: C:\Users\<你>\.dsh-tool-switch
+- insert:
+    - id: dsh-tool-switch
+      name: 'dsh-tool-switch'

package/icon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Tool switch">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4d6bfe"/>
+      <stop offset="1" stop-color="#8a4dfe"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="16" fill="url(#bg)"/>
+  <!-- 三条滑轨 + 旋钮：三个工具开关 -->
+  <g stroke="#fff" stroke-width="3" stroke-linecap="round" fill="#fff">
+    <line x1="16" y1="21" x2="48" y2="21" opacity=".55"/>
+    <circle cx="40" cy="21" r="5"/>
+    <line x1="16" y1="32" x2="48" y2="32" opacity=".55"/>
+    <circle cx="24" cy="32" r="5"/>
+    <line x1="16" y1="43" x2="48" y2="43" opacity=".55"/>
+    <circle cx="34" cy="43" r="5"/>
+  </g>
+</svg>