dsh-loadout 0.0.0-stage → 0.11.1

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+「装备栏」是一个 DeepSeek Harness 插件：给每个对话选一套工具（套装），只把用得上的工具投给模型。
+
+## 0.11.1
+
+- README 与界面同步：功能表不再把**预置套装**当卖点（0.10.2 起界面已隐藏它），改成介绍**我的套装**——新建、设为默认、复制切换命令、编辑（覆盖保存 / 另存为新套装）、备注、删除；并补上 token 账本一行。
+- 安装段改成三种来源并列：npm（`dsh plugin add dsh-loadout`）、GitHub（`add github:JungleYXu/dsh-loadout`）、本地目录链接安装。中英文 README 同步。
+- 无行为变化，只是文档与 npm 首页对齐（npm 页面读的是发布包里的 README）。
+
+## 0.11.0
+
+首个公开发布版本（npm + awesome-dsh-plugin）。
+
+- 存储文件带上 `schema: 1`：0.10.x 及更早的文件没有这个字段，读作 0，第一次保存时升级；以后改结构可以按版本迁移，不用再猜。新增断言 `the store file records its schema version` 和 `a 0.10 store without schema still loads`。
+- 包元数据补齐：`repository` / `homepage` / `bugs` / `author` / `publishConfig`，方便市场和 npm 页面互相跳转。
+- 加 `.github/workflows/ci.yml`（Node 20 / 22 跑 `npm test`，不装依赖）和 `.github/workflows/publish.yml`（打 `v*` 标签后从干净 checkout 发布，带 provenance，凭 `NPM_TOKEN` secret）。
+- 加英文 README（`README.en.md`），中文 README 与 npm 首页互链；新增 `docs/icon.png`（256×256，和 `icon.svg` 同一套抽屉图形），作为市场与 npm 的图标。
+- 无行为变化：底座、加挂、备注、刷新、token 账本与 0.10.5 一致。
+
+## 0.10.4
+
+- 新建 / 编辑套装的表单加了蓝色外框和浅色底（styles.editorCard），和只读的套装卡片区分开。
+- 设置页边界说明改为：本插件只控制「对话看得到哪些工具」。已启用的插件仍在后台运行；界面插件（侧边栏、主题等）不受影响。
+
+## 0.10.5
+
+- 修一个发布前发现的缺口：重启后还没新建过对话时，设置页的 token 账本显示「读不到工具定义」。原因是那一页不带会话 id，宿主拿不到 agent；现在没有 agent 时改用全局工具层的定义给整个目录定价（等于「全部」的数字），不再报错。
+- 新增断言「settings ledgers the catalogue before any conversation exists」。
+
+## 0.10.3
+
+- 「新建套装」的编辑器移到页面最上面（在「全部 / 仅内置」之上），点了按钮第一眼就看见表单；「编辑」仍在对应卡片下方。
+- 「插件」分组的计数改成「已选/可选」（例如 `0/4`），不再只显示已选数。
+- 去掉套装卡片上的「重命名」按钮：改名并入「编辑」——名字、备注、工具清单在同一个表单里改，避免三个互相重叠的行内编辑。
+- 设置页「边界」说明改为：本插件只控制「对话看得到哪些工具」。插件本身仍在后台运行；界面插件（侧边栏、主题等）不受影响。
+- 补一条断言：全新安装（没有 `~/.dsh/loadout.json`）时第一个对话就是「全部」；覆盖安装保留用户已选的默认套装。
+
+## 0.10.2
+
+- 套装卡片不再重复显示套装的内部名（以前「测试1 测试1」会并排出现）；没填备注时也不留空位，只显示名字。
+- 预置套装（写作 / 调研 / 编程）暂时从界面撤下：标题栏菜单和设置页都不再出现。数据仍在 `cordis.patch.yml` 里，`/kit 写作` 等命令照常可用，留作内部测试。开关是 `client.js` 的 `SHOW_PRESETS`。
+- 「新对话默认套装」里的「我的套装」默认折叠：有默认套装时只显示那一行（和标题栏同一套规则），点开才列出全部。
+- 三处介绍词统一为：全部 = 内置工具和已启用插件的工具都能用；仅内置 = 只带 Harness 内置的工具，下载插件的工具默认隐藏；我的套装 = 你自己配置的工具套装，内置工具和已启用插件的工具都能随意搭配。
+- 编辑套装不再在设置页顶部弹编辑器，而是展开在这张套装卡片的下面，「覆盖保存 / 另存为新套装 / 取消」仍在同一处。
+- `client-smoke` 断言改为「菜单与设置页都不出现预置套装」「全部/仅内置 是带两个动作的卡片（4 个复制、4 个设为默认）」，并新增 `openSections` 测试钩子用于展开我的套装。
+
+## 0.10.1
+
+- 设置页的「新对话默认套装」改成和套装一样的卡片：「全部」「仅内置」各带「复制切换命令」「设为默认」，不再有单独的行样式和那句说明文字。删掉了它们下面的两个折叠分组——默认列表就是这两张卡，套装本身在下面的「预设套装」「我的套装」里。
+- 预置套装卡片去掉「另存为我的套装」：预置只读，要改请在「我的套装」里「编辑」一个已有套装，或另存为新的。
+- `client-smoke` 断言随之改成「全部 / 仅内置 是带两个动作的卡片」（7 个复制按钮、7 个设为默认）与「预置卡片不再提供另存为」。这一版只有客户端改动，刷新页面即可；0.10.0 的主机修复仍需重启应用。
+
+## 0.10.0
+
+- **修好了「默认套装不生效」**：新对话的 `agent/created` 监听器在工具层还没挂好的时候就跑，遮罩失败只会留一行日志，于是新对话一律从「全部」开始。现在同一个幂等步骤（`ensureDefault`）也会在第一次读取状态时补做——界面在第一条消息之前一定会读一次状态。
+- 设置页不再像「切换当前对话」的开关：删掉「只影响之后新建的对话」那句，改成说明「新对话从这套工具开始；已有对话不受影响。」并把「全部 / 仅内置」直接列在这句下面。
+- 「预设套装」「我的套装」在默认选择里也默认折叠；折叠时只显示当前默认的那一行，和标题栏菜单同一套规则。
+- 「我的套装」增加「编辑」：复用同一个编辑器，名字锁定，可「覆盖保存」（正在用它的对话立即生效）或「另存为新套装」。
+- 新增回归断言：`a new conversation picks up the default on its first state read`（去掉 `ensureDefault` 会失败）、`settings offers an edit action for saved kits`、`the default caption sits above the choices`。
+
+## 0.9.9
+
+- 设置页和标题栏菜单改为互相同步：任一侧发生变更会广播 `dsh-loadout:changed`，另一侧立刻重读，不再停在打开时那份快照。设置页另外在窗口重新获得焦点、页面重新可见时重读。
+- 设置页的账本改成「最近活跃对话保留 …」，并注明设置页不绑定具体会话；「新对话默认套装」下注明它只影响之后新建的对话。此前在设置页改默认套装时账本不变，容易被当成 bug。
+## 0.9.8
+
+- 提示气泡不再把中文词拆到两行：气泡内 `wordBreak: keep-all`，只在标点处折行；「我的套装」的说明同时缩短为 `你自己保存的套装。点一下即可切换。`
+## 0.9.7
+
+发布准备版本。相对 0.9.6 的修复：
+
+- 备注（`note`）现在会写进 `~/.dsh/loadout.json`。此前 `save()` 只写了 `name/title/builtins/plugins`，重启后备注就没了——字段看起来只在界面里有效。
+- `kit_list` 的返回行补上 `note`，模型侧也能看到备注。
+- 套装文件改为「写临时文件 + rename」，中途崩溃或两个窗口同时保存不会再留下截断的 JSON。
+- 新增回归断言：`a note survives the store file`、`a note survives a restart`。
+- README 补上：预置套装内容、`kit_*` 工具清单、从 0.4.x/0.5.x 升级、启动失败排查。
+
+## 0.9.6
+
+- 删除「我的套装」提示里多余的一句（预设套装不在这个分组里）。
+
+## 0.9.5
+
+- 「我的套装」「预设套装」默认折叠；选中的那套在折叠状态下单独显示，点分组才展开全部。
+
+## 0.9.4
+
+- 菜单改用 `position: fixed` 并按触发按钮定位、按视口翻转/限高，标题栏 `overflow: hidden` 不再把面板裁成两行。
+
+## 0.9.3
+
+- token 账本改用单一表面（`view(agent).visible`），「全部」作为分母；此前 `schemas(ctx)` 只看全局层，把 44 当成全部而实际是 63。
+- 账本只统计本 agent 真能拿到的工具，套装估价不再包含别的 scope 注册的工具。
+- 标题栏按钮从 `conversation.session.header.utilities` 移到 `conversation.session.header.actions`，不再夹在中间。
+
+## 0.9.0
+
+- token 账本：菜单状态行、设置页账目、套装卡片估价（按工具定义长度 ÷ 3.5 字符/token 估算）。
+
+## 0.8.1
+
+- 三套预置各补上协作五件套（`send_message` 等），子代理切到预置后仍能回报。
+- `preflight` 增加断言：每套预置必须列 `send_message`。
+
+## 0.8.0
+
+- 遮罩机制重写为 deny：不再拼 allow 名单。0.7.0/0.8.0 的 allow 名单会把内置工具整批隐藏（运行时拒绝内置名，名单里没有就等于移除），此后只做减法，并在应用后用「保留的工具是否还在」复核，失败即回滚。
+- 菜单：分组默认折叠、备注、`⟳` 刷新、当前状态摘要、恢复为全部；设置页：默认套装支持「仅内置」、分组可折叠、套装备注编辑。
+
+## 0.5.0
+
+- 包名 `dsh-plugin-kits` → `dsh-loadout`，界面名改为「装备栏」，套装数据迁到 `~/.dsh/loadout.json`（旧文件只读一次）。
+
+## 0.4.1
+
+- 修复 0.4.0 启动崩溃：客户端工厂 id 必须等于包名；`apply()` 里任一插槽注册失败不再让整个条目失活。
+- `install.ps1` 改为 junction 链接安装，避免 profile 里留下过期拷贝。
+- 新增 `scripts/preflight.mjs`（id/包名、补丁行、安装漂移）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-loadout contributors
+
+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.en.md

@@ -0,0 +1,137 @@
+# Loadout (`dsh-loadout`)
+
+<img src="docs/icon.png" width="72" align="right" alt="Loadout icon">
+
+> **Loadout** is the plugin. A **kit** is one prepared set of tools. Pick one kit per conversation and carry only the tools that conversation needs.
+
+[中文说明](README.md) · [Changelog](CHANGELOG.md) · MIT
+
+DeepSeek Harness exposes every tool to every conversation: the more plugins you install, the longer the tool list each turn has to carry, and the easier it is for the model to reach for the wrong tool. Loadout groups tools into **kits** and keeps only the current kit's tools visible in that conversation.
+
+## What it does
+
+| Capability | Behaviour |
+| --- | --- |
+| Three bases | `All` (no masking, default) / `Built-in only` / one of your kits |
+| Your kits | Tick built-in tools and plugins under "New kit" and save them as a named loadout. Each card can be set as default, copied as a switch command, edited (overwrite in place, or save as a new kit), annotated, and deleted |
+| Add-ons | Attach a plugin on top of the base for a one-off combination, without saving a kit |
+| Notes | Up to 20 characters per kit, shown as `Test 1（for video work）` in the menu |
+| Token ledger | The menu status line says `saves ~1.9k tokens`; Settings shows the full account (tools kept, tokens kept, tokens saved) |
+| Refresh | `⟳` in the menu re-reads the tool catalogue and re-applies the current selection |
+| Per conversation | A switch affects only the current conversation, starting with the next message; new conversations start from the default kit in Settings → Loadout |
+
+## Install
+
+Three sources, same package:
+
+```bash
+# 1) npm (published)
+dsh plugin --profile desktop add dsh-loadout
+
+# 2) GitHub (same package, when the registry is unreachable)
+dsh plugin --profile desktop add github:JungleYXu/dsh-loadout
+
+# 3) a local directory (development; installs a link, not a copy)
+dsh plugin --profile desktop add link:<absolute path to this directory>
+```
+
+Letting Harness install it is the same as the third form:
+
+```text
+plugin_manager action=install_bundle target=<absolute path to this directory>
+```
+
+Restart the app afterwards: host plugins have no hot reload, and the UI needs at least a refresh.
+
+### Why not copy the files
+
+That is exactly how 0.4.0 broke startup: `install.ps1` copied files into the profile, so after the source was fixed the profile still ran the old bundle. A link cannot drift.
+
+### Self-checks
+
+```bash
+node scripts/preflight.mjs    # factory id vs package name, patch row, installed-copy drift
+node scripts/selftest.mjs     # host logic: bases, add-ons, saving, store round-trip, masking
+node scripts/client-smoke.mjs # browser bundle: menu and settings panel render
+```
+
+## Using it
+
+- **Loadout** button in the session header: switch base, attach plugins, create kits.
+- **Settings → Loadout**: manage kits, edit notes, choose the new-conversation default.
+- `/kit <name>`: switch from the message box.
+
+Settings has no conversation of its own, so it only decides *where new conversations start* — use the header button to change the current one. In the default list, `All` / `Built-in only` and kits are the same kind of card: each can copy its switch command or be set as default. **My kits** starts collapsed and shows only the current default; open it to see the rest. A saved kit can be **edited** on its card: the form opens under that card, and you either overwrite it (conversations already using it switch immediately) or save as a new kit.
+
+### What the shipped presets contain
+
+> Since 0.10.2 the UI does **not** show the presets (neither the header menu nor Settings). The three entries still live in `cordis.patch.yml` and `/kit writing` keeps working; they are kept for our own testing until they are clear enough to ship to users. The table documents them for review.
+
+All three are read-only; an edit becomes a copy of your own. They list **built-in tools only** — plugin tools come in through add-ons or by saving your own kit.
+
+| Preset | Built-in tools |
+| --- | --- |
+| Writing | `read` `write` `edit` `glob` `grep` + collaboration five |
+| Research | `web_search` `web_fetch` `read` `glob` `grep` + collaboration five |
+| Coding | `pwsh` `read` `write` `edit` `glob` `grep` `todo_write` + collaboration five |
+
+"Collaboration five" = `send_message` `list_agents` `interrupt_agent` `subagent` `subagent_fork`. Every preset carries them, otherwise a subagent switched to that preset cannot even report back.
+
+### Tools for the model
+
+`kit_list` (kits and the current selection), `kit_apply` (switch), `kit_create` / `kit_set_tools` / `kit_set_default` / `kit_delete` (manage). These are kept in every kit, so a kit can never lock the model out of switching back.
+
+## Upgrading
+
+- 0.5.x → 0.11.x: same package name (`dsh-loadout`); run `plugin_manager install_bundle` over it. Kits live in `~/.dsh/loadout.json` and are untouched.
+- 0.4.x → 0.11.x: the package was renamed from `dsh-plugin-kits`; remove the old one first:
+
+  ```text
+  plugin_manager action=remove_bundle target=dsh-plugin-kits
+  plugin_manager action=install_bundle target=<absolute path to this directory>
+  ```
+
+  The old `~/.dsh/plugin-kits.json` is read once and migrated.
+- Restart the app after **any** upgrade: host code has no hot reload, and refreshing the UI is not enough.
+
+## Token ledger
+
+The menu status line says `Current: Coding · saves ~1.9k tokens`; Settings shows the full accounting:
+
+```text
+This conversation keeps 18 tools · about 1.1k tokens · All is about 3.0k · this kit saves about 1.9k
+```
+
+Each kit card also carries its own estimate (`≈1.1k tokens`). The number is an **estimate**: each tool definition (name, description, parameter schema) is serialised and divided by 3.5 characters per token, covering only the tool list — not conversation history, the system prompt, or prompt-cache behaviour. The UI labels it "estimate" for that reason. The kept side is measured from the schemas the runtime actually sends; the "All" side comes from the tool layer's definition table.
+
+## Files
+
+- Kit data: `~/.dsh/loadout.json` (schema-versioned; the older `~/.dsh/plugin-kits.json` is read once, then left behind).
+- Uninstall: `plugin_manager action=remove_bundle target=dsh-loadout`.
+
+## Known limits
+
+- Loadout controls only *which tools a conversation can see*. Enabled plugins keep running in the background; UI plugins (sidebars, themes) are unaffected.
+- Tools of downloaded-but-not-started plugins cannot be shown: a tool exists only after its plugin's `apply()` runs.
+- Masking is subtractive: built-in tools are hidden by a `deny` rule on the tool layer, plugin tools by `tools.restrict({ deny })`. No allow list is ever written, because an allow list as a full replacement is what stripped conversations in 0.7/0.8.
+- A fresh install (or a deleted `~/.dsh/loadout.json`) starts on `All`; reinstalling keeps the default you already chose.
+
+## Troubleshooting
+
+**The app will not start: `web boot: … entry did not activate / dsh-loadout: import failed`**
+
+The client bundle failed to register its factory, and the boot audit treats any inactive entry as fatal. In order:
+
+1. `node scripts/preflight.mjs` — it reports whether the bundle's factory id matches the package name. A mismatch is this class of failure.
+2. Confirm the install is a **link**, not a copy: `preflight` prints `as a link (no copy to drift)`. If it is a copy, delete `node_modules/dsh-loadout` and `install_bundle` again.
+3. Otherwise `remove_bundle`, reinstall, restart. Do not hand-edit `package.json` / `cordis.patch.yml` inside the profile.
+
+**Installed, but no button / tools unchanged**
+
+- Host code loads on app restart; the browser bundle needs at least a page refresh.
+- `GET /dsh-loadout/state` returning JSON means the host is running; 404 means it did not load.
+- `⟳` re-reads the tool catalogue without a restart (only for a loaded host).
+
+**Tools vanished after switching**
+
+The allow-list defect from 0.7/0.8 is fixed; masking is deny-only now. If it still happens, click `All` to recover and keep a copy of `/dsh-loadout/debug`.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# 装备栏（dsh-loadout）
+
+<img src="docs/icon.png" width="72" align="right" alt="装备栏图标">
+
+[English](README.en.md) · [更新日志](CHANGELOG.md) · MIT
+
+> 「装备栏」是这个插件本身；「套装」是栏里那几套配好的工具。一个对话选一套装备，只带用得上的工具。
+
+DeepSeek Harness 的工具是全局可见的：插件装得越多，每个对话要背的工具清单越长，模型也越容易挑错工具。装备栏把工具编成**套装**，每个对话只留当前套装里的工具。
+
+## 它做什么
+
+| 能力 | 说明 |
+| --- | --- |
+| 三档底座 | `全部`（不裁剪，默认）/ `仅内置`（只留 DSH 自带工具）/ `我的套装` |
+| 我的套装 | 「新建套装」里勾选内置工具与插件，存成一套带名字的装备。卡片上可以**设为默认**、**复制切换命令**、**编辑**（改完覆盖保存，或另存成新的一套）、**备注**、**删除** |
+| 加挂 | 在底座之上临时加挂插件，不必为一次性组合新建套装 |
+| 备注 | 每个套装可加 20 字备注，菜单里显示成 `测试1（用于视频制作）` |
+| token 账本 | 菜单状态行 `省 ~1.9k tokens`，设置页给出「保留 N 个工具 · 约 X tokens · 省多少」的完整账目 |
+| 刷新 | 菜单右上 `⟳` 重拉工具目录并重套用当前选择 |
+| 每对话独立 | 切换只影响当前对话，下一条消息即按新清单组装；新对话用「设置 → 装备栏」的默认套装 |
+
+## 安装
+
+三种来源，装的是一个东西：
+
+```bash
+# 1) npm（已发布，最短）
+dsh plugin --profile desktop add dsh-loadout
+
+# 2) GitHub（npm 不可达时用同一个包）
+dsh plugin --profile desktop add github:JungleYXu/dsh-loadout
+
+# 3) 本地目录（开发用，链接安装，不拷贝）
+dsh plugin --profile desktop add link:<本目录绝对路径>
+```
+
+让 Harness 自己装也可以（等价于第 3 种）：
+
+```text
+plugin_manager action=install_bundle target=<本目录绝对路径>
+```
+
+装完重启应用：宿主插件没有热重载，界面至少刷新一次。
+
+### 为什么不能复制文件
+
+0.4.0 的启动崩溃就是这么来的：`install.ps1` 把文件拷进 profile，源码修好后 profile 里还是旧拷贝，启动时跑的是旧 bundle。链接安装没有这个问题。
+
+自检：
+
+```bash
+node scripts/preflight.mjs   # 校验 id/包名一致、补丁行、以及安装副本是否漂移
+node scripts/selftest.mjs    # 宿主逻辑：底座/加挂/保存/存储往返/遮罩
+node scripts/client-smoke.mjs # 浏览器 bundle：菜单与设置页渲染
+```
+
+## 使用
+
+- 标题栏「装备栏」按钮：切底座、加挂插件、新建套装。
+- 设置 → 装备栏：管理套装、改备注、选新对话默认套装。
+- `/kit <名字>`：在对话里直接切换。
+
+设置页没有自己的对话，所以它只管「新对话从哪套开始」，不切换当前对话——当前对话请在标题栏里切。默认列表里「全部 / 仅内置」和套装是同一种卡片：都能「复制切换命令」或「设为默认」；「我的套装」默认折叠，只显示当前默认的那一个，点开才列出全部。已经保存的套装可以在卡片上「编辑」：改动就在那张卡片下面展开，「覆盖保存」（正在用它的对话立刻按新工具集走）或「另存为新套装」。
+
+### 预置套装里有什么
+
+> 0.10.2 起，**界面暂时不展示预置套装**（标题栏菜单和设置页都不出现）。三套数据仍在 `cordis.patch.yml` 里、`/kit 写作` 这类命令也照常可用，保留给自己测试；等它们对用户足够直观再放出来。下面表格记录它们的内容，方便核对。
+
+三套都是只读的，改动会另存为你的套装。它们只列**内置工具**，插件工具要靠「加挂」或另存时勾选。
+
+| 套装 | 内置工具 |
+| --- | --- |
+| 写作 | `read` `write` `edit` `glob` `grep` + 协作五件套 |
+| 调研 | `web_search` `web_fetch` `read` `glob` `grep` + 协作五件套 |
+| 编程 | `pwsh` `read` `write` `edit` `glob` `grep` `todo_write` + 协作五件套 |
+
+「协作五件套」= `send_message` `list_agents` `interrupt_agent` `subagent` `subagent_fork`。每套都带着它们，否则子代理切到这套之后连回话都发不出来。
+
+### 给模型用的工具
+
+`kit_list`（列出套装与当前选择）、`kit_apply`（切到某套）、`kit_create` / `kit_set_tools` / `kit_set_default` / `kit_delete`（增删改）。这些工具在任何套装里都保留，不会把自己锁死。
+
+## 升级
+
+- 0.5.x → 0.9.x：包名没变（`dsh-loadout`），直接 `plugin_manager install_bundle` 覆盖即可；套装数据在 `~/.dsh/loadout.json`，不动。
+- 0.4.x → 0.9.x：包名从 `dsh-plugin-kits` 改成 `dsh-loadout`，先卸旧的再装新的：
+
+  ```text
+  plugin_manager action=remove_bundle target=dsh-plugin-kits
+  plugin_manager action=install_bundle target=<本目录绝对路径>
+  ```
+
+  旧数据 `~/.dsh/plugin-kits.json` 会被读一次并迁移到 `~/.dsh/loadout.json`。
+- 任何版本升级后都**重启应用**：宿主代码没有热重载，只刷新界面不够。
+
+
+## token 账本
+
+菜单的状态行会说 `当前：编程 · 省 ~1.9k tokens`，设置页顶部给出完整账目：
+
+```text
+当前对话保留 18 个工具 · 约 1.1k tokens　·　「全部」约 3.0k tokens　·　本套装省约 1.9k tokens
+```
+
+每个套装卡片也标着自己的估价（`≈1.1k tokens`）。算法是**估算**：把每个工具的定义（名字、说明、参数 schema）序列化后除以 3.5 字符/token，只算工具清单这一段——不含对话历史、系统提示或模型缓存的影响。界面上都写了「估算」，不要拿它当账单。「当前对话保留」这一侧直接量的是运行时真正投给模型的 schema，「全部」那一侧来自工具层的定义表。
+
+## 文件
+
+- 套装数据：`~/.dsh/loadout.json`（旧版 `~/.dsh/plugin-kits.json` 只读一次，随后迁移）。
+- 卸载：`plugin_manager action=remove_bundle target=dsh-loadout`。
+
+## 已知边界
+
+- 本插件只控制「对话看得到哪些工具」。已启用的插件仍在后台运行；界面插件（侧边栏、主题等）不受影响。
+- 看不到「已下载但未启动」插件的工具：工具只在插件 `apply()` 后存在。
+- 遮罩是「减法」：内置工具用工具层的 deny 规则隐藏，插件工具用 `tools.restrict({ deny })`。
+- 新装（或删掉 `~/.dsh/loadout.json` 后）默认是「全部」；覆盖安装会保留你已选的默认套装。
+
+## 排查
+
+**应用起不来，弹窗写 `web boot: … entry did not activate / dsh-loadout: import failed`**
+
+这是客户端 bundle 没注册成工厂导致的，启动审计对任何没激活的条目都是致命的。按顺序看：
+
+1. `node scripts/preflight.mjs` —— 它会直接告诉你 bundle 的工厂 id 和包名是否一致。不一致就是这一类问题。
+2. 确认安装的是**链接**不是拷贝：`preflight` 会打印 `as a link (no copy to drift)`；如果是拷贝，删掉 `node_modules/dsh-loadout` 重新 `install_bundle`。
+3. 仍不行就 `remove_bundle` 后重装并重启，别在 profile 里手工改 `package.json` / `cordis.patch.yml`。
+
+**装了但界面没有按钮 / 工具没生效**
+
+- 宿主代码要重启应用才加载；浏览器 bundle 至少刷新一次。
+- `GET /dsh-loadout/state` 能返回 JSON 说明宿主在跑；404 说明宿主没加载成功。
+- 菜单里点 `⟳` 可以重拉工具目录，不用重启（只对已加载的宿主有效）。
+
+**切换套装后工具全没了**
+
+0.7/0.8 的 allow 名单缺陷已修，现在只做 deny 遮罩。若仍遇到，点「全部」即可恢复，并把 `/dsh-loadout/debug` 的输出留一份。
 
-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.