dsh-plugin-showcase 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 antonioxue
+
+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,287 @@
-# Temporary Holding Version
+# dsh-plugin-showcase
 
-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.
+A starter companion for **DeepSeek Harness (DSH)**: it says one useful thing about the
+host it runs in — and covers all eight plugin surfaces while doing it, so the whole
+surface area can be read in one small package.
+
+Version **0.2.0**. The v1 surface is unchanged (`showcase_inspect`, `/showcase on|off`,
+the gate, the three slots, locale, icon, patch); v2 adds a health check, two command
+branches, a first-run guide in the panel, and a self-hosted market index.
+
+| Surface | Anchor (v0.2.0) |
+| --- | --- |
+| Tool `showcase_inspect` | `lib/index.js:600`, registered `:638` |
+| Tool `showcase_doctor` | `lib/index.js:619`, registered `:639` |
+| Hook `tools/pre-execute` | `lib/index.js:641` (gate), patterns `:21`–`:38` |
+| Slash command `/showcase` | `lib/index.js:652` |
+| Settings card | `lib/client.js:531` (`settings.section`, id `showcase`) |
+| Right-sidebar panel | body `lib/client.js:551`, tab type `:539` |
+| i18n | `lib/client.js:13` (19 keys), `locale/en.json`, `locale/zh.json` |
+| Market index | `market/index.json` (shipped through `files`) |
+| Tests | `tests/host.test.mjs`, `tests/client.test.mjs` |
+
+Line numbers are as of v0.2.0. Nothing here is compiled: native ESM only, no
+third-party runtime dependency, no `@deepseek-ai` import.
+
+## Install and uninstall
+
+Profile on this machine: `C:\Users\baba\.dsh\profiles\web`.
+
+### A. From the market — the normal path
+
+1. Publish 0.2.0 to npm (see `PUBLISH.md`), so the index inside the package is
+   fetchable at
+   `https://cdn.jsdelivr.net/npm/dsh-plugin-showcase@latest/market/index.json`.
+2. Open DSH → Settings → the market / Discover page and add that URL as an index source.
+   The host service `pluginMarket` keeps that list (`indexes`), and it starts empty:
+   the Discover page does **not** search npm, so nothing shows up until an index is
+   configured.
+3. Search for `dsh-plugin-showcase` → install. The package lands in the profile and its
+   `dsh.bundle` entry is appended, so the layer activates.
+
+The index ships inside the package, so it only exists from **0.2.0** onward: 0.1.0 was
+published before `market/` existed and has no index. On any version >= 0.2.0 the CDN
+URL above serves the index directly — no local server, no process to keep alive.
+
+If you do not want to wait for the index, install by registry name instead:
+
+```sh
+dsh plugin --profile web add dsh-plugin-showcase
+```
+
+### B. From a checkout, with the documented command
+
+```sh
+dsh plugin --profile web add <path-to-this-directory>
+```
+
+There is no global `dsh` on this machine's `PATH`, so the same command through the
+checkout:
+
+```sh
+node "C:\Users\baba\Desktop\deepseek-harness\apps\cli\lib\bin.js" plugin --profile web add "C:\Users\baba\Desktop\DSH工作区\plugins\dsh-plugin-showcase"
+```
+
+Removal: `... plugin --profile web remove dsh-plugin-showcase`.
+
+### C. What this machine actually uses — the manual equivalent
+
+Three edits, no install run:
+
+1. `C:\Users\baba\.dsh\profiles\web\package.json` → `dependencies`:
+   `"dsh-plugin-showcase": "link:C:/Users/baba/Desktop/DSH工作区/plugins/dsh-plugin-showcase"`
+2. The same file → `dsh.profile.bundles`: append `"dsh-plugin-showcase"`.
+3. A directory junction so Node resolves the name:
+   `C:\Users\baba\.dsh\profiles\web\node_modules\dsh-plugin-showcase`
+   → `C:\Users\baba\Desktop\DSH工作区\plugins\dsh-plugin-showcase`
+   (verified `<JUNCTION>` reparse point; recreate with `cmd /c mklink /J <link> <target>`).
+
+**Why not the install command here.** It runs an install inside the profile, and that
+re-resolves the *whole* tree. This profile already carries eleven third-party plugins
+(`dsh-cost-meter`, `dsh-better-sidebar`, `dsh-chat-import`, `dsh-context`,
+`dsh-memgas`, `dsh-wallpaper-bg`, `@linxin666/*`, `@liustack/*`, `@tt-a1i/archify-dsh`).
+The three edits above are exactly the state a link install produces, without a resolver
+run that could rewrite one of those eleven.
+
+Check the layer without starting the host (verified output):
+
+```sh
+node "C:\Users\baba\Desktop\deepseek-harness\apps\cli\lib\bin.js" --profile web --dump-config
+# ...
+# == dsh-plugin-showcase
+# - id: showcase
+#   name: dsh-plugin-showcase
+```
+
+DSH's HMR watches the profile `package.json` (the `bundles` array) and the profile patch
+files, so appending the entry recomposes the running host without a restart; the browser
+half needs one page refresh. Undo by removing the three edits.
+
+## The health check (new in 0.2.0)
+
+`showcase_doctor` takes no arguments and returns a **HealthReport**:
+
+```
+{
+  generatedAt: "ISO", pluginVersion: "0.2.0",
+  dshVersion: "0.2.1-rc.2",                // string | null
+  summary: { ok, warn, fail, unknown },    // integers, always equal to the checks below
+  checks: [{ id, title, status, detail, hint }]   // hint: string | null
+}
+```
+
+Two ways to ask:
+
+- tool: run `showcase_doctor` (`showcase_inspect` still returns the v1 snapshot)
+- command: `/showcase doctor` — the same text, straight into the conversation
+
+The rendered text is `DSH 体检报告 <generatedAt>`, then one
+`[OK|WARN|FAIL|?] <title> — <detail>` line per check, an indented `  ↳ <hint>` line when
+there is a next step, and a closing `合计: ok N / warn N / fail N / unknown N`.
+
+The six checks, in order:
+
+| id | What it looks at | ok / warn / fail / unknown |
+| --- | --- | --- |
+| `engine.dsh` | running DSH version (read from `<profile>/node_modules/@deepseek-ai/dsh-app-boot/package.json`) against `engines.dsh` | ok = satisfies the range, fail = does not (hint: upgrade), warn = no `engines.dsh`, unknown = version unreadable or range not parseable offline |
+| `workspace.cwd` | `workingDirectory` | ok = a directory, warn = none |
+| `model.default` | `agentDefaultModel` | ok = `provider/model`, unknown = service missing |
+| `plugin.gate` | this plugin's gate | ok = on, warn = off (hint: `/showcase on`) |
+| `plugin.locale` | host language preference from `settings.describe()` | ok = a value, unknown = unreadable |
+| `market.index` | index list from `pluginMarket.listIndexes()` | ok = every source readable, warn = none configured or some broken, unknown = no market service |
+
+**A check that throws never fails the run.** Its own row degrades to `unknown` with
+`detail: "检查异常: <message>"` plus a hint; the other five keep their verdicts and the
+summary still adds up to six.
+
+## Commands
+
+| Input | Answer |
+| --- | --- |
+| `/showcase` | the v1 inspection report text |
+| `/showcase on` / `off` | `showcase 拦截门: 已开启` / `已关闭` |
+| `/showcase doctor` | the health report text (same render as the tool) |
+| `/showcase about` | one line: version, both tools, command branches, gate state, DSH version |
+| anything else | `/showcase [on|off|doctor|about]` |
+
+Input is trimmed and lower-cased first, so ` ON ` works and `Dr. Who` gets the usage line.
+
+## The guard gate
+
+On by default. A tool call is denied when its `command`, `cmd`, `script` or `code`
+argument (case-insensitive) contains one of:
+
+- `rm -rf /`, `rm -rf ~`
+- fork bombs: `:(){:|:&;}`, `:(){ :|:& };:`, `.(){ :|:& };:`, `bomb(){ bomb|bomb& };bomb`
+- `del /f /s /q c:\`, `format c:`
+- the `shutdown` / `shutdown.exe` word in command position, optionally behind `sudo`,
+  `doas` or `pkexec`, e.g. `shutdown /s /t 0` or `sudo shutdown -h now`
+
+Whitespace-collapsed spellings such as `rm   -rf   /tmp`, or the same commands written with
+tabs instead of spaces, are caught too. The deny reason is
+`showcase: 拒绝执行破坏性命令`; everything else calls `next()` and is allowed. Text
+outside those four argument keys is ignored, and a fault inside the hook still calls
+`next()` — a plugin bug must never block tool calls.
+
+## Settings card and panel
+
+**Settings card** — Settings → nav row **功能展示 / Showcase** (id `showcase`, order 90):
+title and subtitle, the doctor hint, a copyable `/showcase doctor` row, refresh and
+"open the panel" buttons, a footer with `v0.2.0` and the gate state, the three capability
+rows, then either the snapshot or the degraded copy.
+
+**Right-sidebar panel** — tab type id `showcase-panel`, kind `showcase`, title
+**巡检面板 / Showcase panel**, body seated under the same key. Open it from the ◎ button
+in the left sidebar footer (beside Settings) or from the settings card's button; both end
+in `sidebarRight.openTab('showcase')`. The type declares no `guide` entry, so it does not
+appear on the right sidebar's guide page.
+
+The panel opens on a three-step guide: 1) run a health check — the `/showcase doctor`
+text is shown and copyable, 2) open the settings card, 3) understand the gate —
+`/showcase on|off` is shown and copyable. Each step has its own copy button; pressing it
+flips the label to **已复制 / Copied** for about 1.6 s. The footer carries `v0.2.0` and,
+while no snapshot is reachable, the degraded line.
+
+## i18n
+
+19 runtime keys, each present in `en` and `zh`, translated rather than copied:
+
+`title` `subtitle` `panelTitle` `panelEmpty` `gateOn` `gateOff` `openPanel` `refresh`
+(the v1 eight) plus `welcome` `stepDoctorTitle` `stepDoctorBody` `stepSettingsTitle`
+`stepSettingsBody` `stepGateTitle` `stepGateBody` `copyHint` `copied` `doctorHint`
+`aboutBody`.
+
+Language resolution is `ctx.locale` → `navigator.language` → `en`; a host without a
+locale service still renders real copy.
+
+## Market index (self-hosted inside the package)
+
+Since v0.2.0 the index travels with the package: `market/index.json` (format 1, listing
+this plugin) is whitelisted in `package.json` → `files`, so it is inside the published
+tarball. Public address:
+
+```
+https://cdn.jsdelivr.net/npm/dsh-plugin-showcase@latest/market/index.json
+```
+
+Add that URL as an index source on the Discover page and the plugin is installable
+without any local server.
+
+The temporary service this machine used during development still listens on
+`http://127.0.0.1:8791` (its index answers 200 at `/index.json`). It is **no longer
+needed**: pointing the Discover page at the URL above replaces it, and after that the
+local service can be stopped.
+
+Marketplace metadata still comes from `locale/en.json` (the anchor) and `locale/zh.json`,
+so the Plugins page shows the localized title and description next to `icon.svg`.
+
+## Honest limitations
+
+1. **The client still cannot read live host data, and under the zero-build rule it
+   cannot.** The documented remote-API path needs typert decorators, a code-generation
+   step and a third-party dependency — three hard conflicts with "native ESM, no build,
+   no deps". `lib/client.js` probes the plausible shapes (`remote.showcase`,
+   `ctx.showcase`) and degrades to `null`. So the card and the panel show the static
+   capability rows and the degraded copy, never a live snapshot; that is also why the
+   first-run guide hands you the `/showcase doctor` text instead of calling the host.
+2. **`sidebar.footer.action` does not project `label`.** The sidebar shell renders that
+   seat with only `{ wide }`, so the visible text is what the component draws (`◎`, with
+   the label carried as `aria-label`). The `label` thunk is a legal `SlotLabel` and is
+   correct, but no shell reads it for this seat.
+3. **Around 390 px the layout is the host's call, not ours.** The seats stack when the
+   *measured box* drops below 320 px, and every box is `min-width: 0` plus
+   `overflow-x: hidden`, so a squeezed container can only shorten lines. But the right
+   column's width is clamped by DSH itself: the plugin cannot make the pane narrower or
+   wider than the host allows, and behaviour below roughly 390 px was only reached
+   through container measurement, not through a real narrow viewport.
+4. **No visual regression in a real browser — the tests cover facts, not pixels.** The
+   client evidence comes from Node stub tests: `react` is replaced by a minimal
+   `createElement`/`useState`/`useEffect`/`useRef` stand-in, so the assertions are the
+   element tree and its text (19 bilingual keys, three step titles, the copied label after
+   a click, the degraded copy). There is no screenshot baseline and no pixel comparison.
+
+## Extending it
+
+- **New tool.** Copy the raw JSON-Schema `ToolDefinition` shape of `inspectTool`
+  (`lib/index.js:600`) or `doctorTool` (`:619`) and register it with
+  `ctx.effect(() => ctx.tools.register(<tool>), 'showcase: <name>')` (`:638` / `:639`).
+  `output` must carry `{ schema, render }`.
+- **New check.** Add one `runCheck('<id>', '<title>', () => …)` entry to the array in
+  `buildHealthReport` (`lib/index.js:511`), keep it wrapped so a throw becomes
+  `unknown`, and extend `buildHealthSchema` only if the shape really changes.
+- **New slot.** In `apply()` (`lib/client.js:525`) copy the
+  `slots.inject(<slot>, () => slots.register({ name, … }, Component))` shape:
+  `settings.section` at `:531`, `sidebar.right.pane.tab` at `:551`,
+  `sidebar.footer.action` at `:559`. A right-sidebar tab needs both halves — the body key
+  must equal the id of the type registered through `sidebarRightTabs`.
+- **New runtime string.** Add the key to both `dict.en` and `dict.zh`
+  (`lib/client.js:13`) and extend `DICT_KEYS` in `tests/helpers/client-harness.mjs`, so
+  the bilingual test keeps guarding it.
+
+## Tests
+
+```sh
+npm install   # once, needs registry access (devDependency: vitest)
+npm test      # offline from then on, one command, whole suite
+```
+
+98 tests in 2 files, no machine path baked in — every path derives from
+`import.meta.url`, and the fixtures (a workspace, a two-version DSH profile) are temp
+directories created per run.
+
+- `tests/host.test.mjs` (66): module shape, the `ctx.effect` lifecycle of all four
+  registrations, both tools' parameters and `output` contract with returned values
+  validated against their own schemas, snapshot shape and `""`/`null` degradation,
+  git-branch discovery, all eight destructive patterns plus collapsed spellings and key
+  scoping, the word-boundary cases for power commands, hook-throw still allowing, gate
+  on/off, the HealthReport shape with "no `undefined`" and summary-vs-checks agreement,
+  each of the six checks in its ok / warn / unknown / fail branches, a throwing check
+  degrading on its own, the report render layout, and the five command inputs.
+- `tests/client.test.mjs` (32): lazy-CJS registration, factory exports including
+  `VERSION`, exactly three seats, tab-type/body-key agreement and late service arrival,
+  the footer's open path, all 19 bilingual dict keys, the three step titles, language
+  resolution including a host with no locale service, `fetchSnapshot` degradation,
+  rendering with and without data, the first-run guide, the copy-to-"已复制" flip, and
+  refresh clicks.
+
+Runner: **vitest 3** (the declared devDependency).

package/README.zh.md

@@ -0,0 +1,262 @@
+# dsh-plugin-showcase
+
+一个 **DeepSeek Harness（DSH）** 的新人首装搭档：用一句话说明它所在的这台 DSH 主机
+是什么状况，同时把八个插件能力面一次性用满，因此整块接口面可以在一个小包里读完。
+
+版本 **0.2.0**。v1 的能力面一个都没退化（`showcase_inspect`、`/showcase on|off`、
+拦截门、三处 slot、locale、icon、patch 全部保持），v2 增加了体检、两个命令分支、
+面板里的三步引导，以及随包分发的自托管市场索引。
+
+| 能力面 | 位置（v0.2.0） |
+| --- | --- |
+| 工具 `showcase_inspect` | `lib/index.js:600`，注册在 `:638` |
+| 工具 `showcase_doctor` | `lib/index.js:619`，注册在 `:639` |
+| 钩子 `tools/pre-execute` | `lib/index.js:641`（拦截门），模式表 `:21`–`:38` |
+| 斜杠命令 `/showcase` | `lib/index.js:652` |
+| 设置卡片 | `lib/client.js:531`（`settings.section`，id `showcase`） |
+| 右侧栏面板 | 面板体 `lib/client.js:551`，tab 类型 `:539` |
+| 国际化 | `lib/client.js:13`（19 键）、`locale/en.json`、`locale/zh.json` |
+| 市场索引 | `market/index.json`（在 `files` 白名单里随包发布） |
+| 测试 | `tests/host.test.mjs`、`tests/client.test.mjs` |
+
+行号对应 v0.2.0。全程零构建：只有原生 ESM JavaScript，没有第三方运行时依赖，也没有
+任何 `@deepseek-ai` import。
+
+## 安装与卸载
+
+本机使用的 profile：`C:\Users\baba\.dsh\profiles\web`。
+
+### 方式一：从市场安装（正常路径）
+
+1. 把 0.2.0 发布到 npm（流程见 `PUBLISH.md`），包内索引就能在
+   `https://cdn.jsdelivr.net/npm/dsh-plugin-showcase@latest/market/index.json` 取到。
+2. 打开 DSH → 设置 → 市场／发现页，把这个 URL 添加为索引源。宿主服务
+   `pluginMarket` 维护这份 `indexes` 列表，它的初始值是空数组：发现页**不搜索
+   npm**，所以没配索引之前什么都不会出现。
+3. 搜索 `dsh-plugin-showcase` → 安装。包会装进 profile，并把它在 `dsh.bundle` 里
+   对应的条目追加进 `dsh.profile.bundles`，层随即生效。
+
+索引随包分发，所以从 **0.2.0** 起才有：0.1.0 发布时包里没有 `market/`，它没有索引。
+0.2.0 及以后的版本，上面那条 CDN 地址直接就能取到索引——不需要本机服务，也没有任何
+进程要你养着。
+
+不想等索引，也可以直接按 registry 名安装：
+
+```sh
+dsh plugin --profile web add dsh-plugin-showcase
+```
+
+### 方式二：从 checkout 安装（官方命令）
+
+```sh
+dsh plugin --profile web add <本目录路径>
+```
+
+本机 `PATH` 上没有全局 `dsh`，所以同一个命令改从检出调用：
+
+```sh
+node "C:\Users\baba\Desktop\deepseek-harness\apps\cli\lib\bin.js" plugin --profile web add "C:\Users\baba\Desktop\DSH工作区\plugins\dsh-plugin-showcase"
+```
+
+卸载：`... plugin --profile web remove dsh-plugin-showcase`。
+
+### 方式三：本机实际使用的手动等价物
+
+三处改动，不跑安装：
+
+1. `C:\Users\baba\.dsh\profiles\web\package.json` 的 `dependencies` 加一行
+   `"dsh-plugin-showcase": "link:C:/Users/baba/Desktop/DSH工作区/plugins/dsh-plugin-showcase"`；
+2. 同一个文件的 `dsh.profile.bundles` 末尾追加 `"dsh-plugin-showcase"`；
+3. 建一个目录 junction，让 Node 能解析这个包名：
+   `C:\Users\baba\.dsh\profiles\web\node_modules\dsh-plugin-showcase`
+   → `C:\Users\baba\Desktop\DSH工作区\plugins\dsh-plugin-showcase`
+   （本机实测为 `<JUNCTION>` 重解析点；重建命令 `cmd /c mklink /J <链接> <目标>`）。
+
+**为什么本机不用安装命令。** 它会在 profile 内跑一次安装，而这次安装会重新解析整棵树。
+这个 profile 里已经装着十一个第三方插件（`dsh-cost-meter`、`dsh-better-sidebar`、
+`dsh-chat-import`、`dsh-context`、`dsh-memgas`、`dsh-wallpaper-bg`、`@linxin666/*`、
+`@liustack/*`、`@tt-a1i/archify-dsh`）。上面三处改动正是链接安装后的最终状态，但没有那次
+可能改写这十一个插件版本的解析过程。
+
+不启动、只验证层（以下为实测输出）：
+
+```sh
+node "C:\Users\baba\Desktop\deepseek-harness\apps\cli\lib\bin.js" --profile web --dump-config
+# ...
+# == dsh-plugin-showcase
+# - id: showcase
+#   name: dsh-plugin-showcase
+```
+
+DSH 的 HMR 监视 profile 的 `package.json`（只看 `bundles` 数组）与 profile 的 patch
+文件，因此追加条目会在不重启宿主进程的情况下重新组合；浏览器那一半需要刷新一次页面。
+撤销同样只是把这三处改回去。
+
+## 体检（0.2.0 新增）
+
+`showcase_doctor` 无参数，返回一份 **HealthReport**：
+
+```
+{
+  generatedAt: "ISO", pluginVersion: "0.2.0",
+  dshVersion: "0.2.1-rc.2",                // string | null
+  summary: { ok, warn, fail, unknown },    // 整数，与下面 checks 的统计恒等
+  checks: [{ id, title, status, detail, hint }]   // hint: string | null
+}
+```
+
+两种问法：
+
+- 工具：跑一次 `showcase_doctor`（`showcase_inspect` 仍然返回 v1 那份巡检快照）
+- 命令：`/showcase doctor` —— 同一段文本直接回在对话里
+
+渲染文本首行是 `DSH 体检报告 <generatedAt>`，随后每条 check 一行
+`[OK|WARN|FAIL|?] <title> — <detail>`，有下一步时再缩进一行 `  ↳ <hint>`，末行是
+`合计: ok N / warn N / fail N / unknown N`。
+
+六项 check（按顺序）：
+
+| id | 看什么 | ok / warn / fail / unknown |
+| --- | --- | --- |
+| `engine.dsh` | 运行中的 DSH 版本（读 `<profile>/node_modules/@deepseek-ai/dsh-app-boot/package.json`）与 `engines.dsh` 比对 | ok = 满足范围，fail = 不满足（hint 提示升级），warn = 未声明 `engines.dsh`，unknown = 版本读不到或范围无法离线解析 |
+| `workspace.cwd` | `workingDirectory` | ok = 有目录，warn = 取不到 |
+| `model.default` | `agentDefaultModel` | ok = `provider/model`，unknown = 无该服务 |
+| `plugin.gate` | 本插件的拦截门 | ok = 开启，warn = 关闭（hint: `/showcase on`） |
+| `plugin.locale` | `settings.describe()` 里的界面语言偏好 | ok = 有值，unknown = 读不到 |
+| `market.index` | `pluginMarket.listIndexes()` 的索引列表 | ok = 每个源都可用，warn = 一条都没配或部分不可用，unknown = 没有市场服务 |
+
+**任何一条 check 内部抛错都不会让整次体检失败。** 只有它自己那行退化成 `unknown`，
+`detail` 写成 `检查异常: <message>` 并带 hint，其余五项判决保持不变，合计仍然是六项。
+
+## 命令
+
+| 输入 | 回答 |
+| --- | --- |
+| `/showcase` | v1 那份巡检报告文本 |
+| `/showcase on` / `off` | `showcase 拦截门: 已开启` / `已关闭` |
+| `/showcase doctor` | 体检报告文本（与工具同一份渲染） |
+| `/showcase about` | 一行：版本、两个工具、命令分支、拦截门状态、DSH 版本 |
+| 其它 | `/showcase [on|off|doctor|about]` |
+
+输入先 trim 再转小写，所以 ` ON ` 有效，`Dr. Who` 得到用法那一行。
+
+## 拦截门
+
+默认开启。当一次工具调用的 `command`、`cmd`、`script` 或 `code` 参数（不区分大小写）
+命中下列任一模式时拒绝执行：
+
+- `rm -rf /`、`rm -rf ~`
+- fork 炸弹：`:(){:|:&;}`、`:(){ :|:& };:`、`.(){ :|:& };:`、`bomb(){ bomb|bomb& };bomb`
+- `del /f /s /q c:\`、`format c:`
+- 处在命令位置上的 `shutdown` / `shutdown.exe` 词（前面可以带 `sudo`、`doas` 或
+  `pkexec`），例如 `shutdown /s /t 0`、`sudo shutdown -h now`
+
+把空格抹掉的写法（例如 `rm   -rf   /tmp`），或把空格换成制表符，同样拦得住。拒绝理由固定为
+`showcase: 拒绝执行破坏性命令`；其余一律调用 `next()` 放行。这四个参数键之外的文本不
+参与匹配；钩子内部出故障也照样 `next()` —— 插件 bug 绝不能阻塞工具调用。
+
+## 设置卡与面板
+
+**设置卡片** —— 设置里的导航行 **功能展示 / Showcase**（id `showcase`，order 90）：
+标题与说明、体检提示、一行可复制的 `/showcase doctor`、刷新与"打开巡检面板"按钮、带
+`v0.2.0` 与拦截门状态的页脚、三条能力行，最后是快照或降级文案。
+
+**右侧栏面板** —— tab 类型 id `showcase-panel`、kind `showcase`、标题
+**巡检面板 / Showcase panel**，面板体挂在同一个 key 上。打开它有两个入口：左侧栏底部
+Settings 旁边的 ◎ 按钮，以及设置卡上的按钮，两者最终都走
+`sidebarRight.openTab('showcase')`。这个 tab 类型没有声明 `guide` 条目，所以它不会出现
+在右侧栏的引导页里。
+
+面板一打开就是三步引导：1）跑一次体检 —— 把 `/showcase doctor` 作为可复制文本交给你；
+2）打开设置卡；3）了解拦截门 —— 给出 `/showcase on|off` 的可复制文本。每一步都有自己
+的复制按钮，按下后标签变成 **已复制 / Copied**，约 1.6 秒后回退。页脚显示 `v0.2.0`，
+取不到快照时再加上降级那一行。
+
+## 国际化
+
+19 个运行期键，`en` 与 `zh` 各一份，都是真翻译而不是照抄：
+
+v1 的八个 `title` `subtitle` `panelTitle` `panelEmpty` `gateOn` `gateOff`
+`openPanel` `refresh`，加 v2 的 `welcome` `stepDoctorTitle` `stepDoctorBody`
+`stepSettingsTitle` `stepSettingsBody` `stepGateTitle` `stepGateBody` `copyHint`
+`copied` `doctorHint` `aboutBody`。
+
+语言解析顺序是 `ctx.locale` → `navigator.language` → `en`；没有 locale 服务的宿主照样
+渲染真实文案。
+
+## 市场索引（随包自托管）
+
+v0.2.0 起索引跟包一起走：`market/index.json`（format 1，收录本插件），并在
+`package.json` 的 `files` 白名单里，所以它在发布出去的 tarball 里。对外地址：
+
+```
+https://cdn.jsdelivr.net/npm/dsh-plugin-showcase@latest/market/index.json
+```
+
+在发现页把它添加为索引源，就不用任何本地服务器也能装。
+
+开发期本机用过的那套临时服务仍在 `http://127.0.0.1:8791` 上监听（它的索引在
+`/index.json` 回答 200）。**它已经不再需要**：把发现页的索引源换成上面那条 CDN 地址
+即可，之后那套本地服务可以停掉。
+
+市场元数据仍然来自 `locale/en.json`（锚点）与 `locale/zh.json`，所以插件页会显示本地化
+标题与描述，配上 `icon.svg`。
+
+## 诚实的限制清单
+
+1. **client 侧仍然拿不到宿主实时数据，零构建约束下也拿不到。** 官方 remote API 路线需要
+   typert 装饰器、代码生成步骤和第三方依赖——这三条与"原生 ESM、不构建、不加依赖"逐条
+   冲突。`lib/client.js` 会去探测几种可能的形状（`remote.showcase`、`ctx.showcase`），
+   失败即降级为 `null`。所以设置卡与面板显示的是静态能力行加降级文案，不是实时快照；
+   也正因如此，首启引导只能把 `/showcase doctor` 文本交给你，而不是替你去调用宿主。
+2. **`sidebar.footer.action` 座位不投影 `label`。** 侧栏外壳只以 `{ wide }` 渲染这个
+   座位，可见文本由组件自己画（`◎`，标签通过 `aria-label` 承载）。那个 `label` thunk
+   是合法的 `SlotLabel` 也没写错，只是这个座位没有壳去读它。
+3. **390px 左右的表现由宿主决定，不由插件决定。** 实测容器宽度低于 320px 时座位才改为
+   堆叠，且每个盒子都是 `min-width: 0` 加 `overflow-x: hidden`，被压窄时只会让行变短、
+   不会撑出横向滚动条。但右列宽度是 DSH 自己钳制的：插件既不能把面板做得比宿主允许的
+   更窄，也不能更宽，而 390px 以下的情况只是通过容器实测走到的，没有在真实窄视口里验证。
+4. **没有真实浏览器的视觉回归 —— 测试覆盖事实，不覆盖像素。** client 侧证据来自 Node 桩
+   测试：`react` 被换成最小的 `createElement`/`useState`/`useEffect`/`useRef` 替身，
+   所以断言的是元素树与文本（19 键双语、三条引导标题、点击后的"已复制"、降级文案）。
+   既没有截图基线，也没有像素比对。
+
+## 二次开发指引
+
+- **加一个工具。** 照抄 `inspectTool`（`lib/index.js:600`）或 `doctorTool`（`:619`）
+  那种原始 JSON-Schema `ToolDefinition` 形状，用
+  `ctx.effect(() => ctx.tools.register(<tool>), 'showcase: <name>')` 注册
+  （`:638` / `:639`）。`output` 必须带 `{ schema, render }`。
+- **加一项 check。** 在 `buildHealthReport`（`lib/index.js:511`）的数组里加一行
+  `runCheck('<id>', '<标题>', () => …)`，保持这层包裹（抛错才会退化成 `unknown`）；
+  只有形状真的变了才动 `buildHealthSchema`。
+- **加一个新 slot。** 在 `apply()`（`lib/client.js:525`）里照抄
+  `slots.inject(<slot>, () => slots.register({ name, … }, 组件))` 这个形状：
+  `settings.section` 在 `:531`、`sidebar.right.pane.tab` 在 `:551`、
+  `sidebar.footer.action` 在 `:559`。右侧栏 tab 必须两半都注册——面板体的 key 要等于
+  通过 `sidebarRightTabs` 注册的类型 id。
+- **加一条运行期文案。** 同时加进 `dict.en` 与 `dict.zh`（`lib/client.js:13`），并把
+  `tests/helpers/client-harness.mjs` 里的 `DICT_KEYS` 一起扩展，双语用例才会继续守住它。
+
+## 测试
+
+```sh
+npm install   # 只做一次，需要访问 registry（devDependency: vitest）
+npm test      # 之后完全离线，一条命令跑完整个套件
+```
+
+两个文件共 98 个用例，不写死任何机器路径——所有路径都由 `import.meta.url` 推导，夹具
+（一个工作区、一个双版本 DSH profile）是每次运行现建的临时目录。
+
+- `tests/host.test.mjs`（66 个）：模块形状、四处注册的 `ctx.effect` 生命周期、两个工具
+  的参数与 `output` 契约（返回值用各自声明的 schema 反向校验）、快照形状与 `""`/`null`
+  降级、git 分支发现、八条破坏性模式外加抹空格写法与参数键范围、关机类命令的词边界、
+  钩子内部抛错仍放行、拦截门开关、HealthReport 形状与"不出现 `undefined`"、summary 与
+  checks 恒等、六项 check 各自的 ok/warn/unknown/fail 分支、单条 check 抛错只降级自己、
+  报告渲染版式，以及命令的五种输入。
+- `tests/client.test.mjs`（32 个）：lazy-CJS 登记、factory 导出（含 `VERSION`）、恰好三个
+  座位、tab 类型与面板体 key 一致且服务晚到也能补注册、侧栏按钮的打开路径、19 个双语键、
+  三条引导标题、语言解析（含没有 locale 服务的宿主）、`fetchSnapshot` 的各级降级、
+  有数据与无数据两种渲染、首启引导、点击复制后变"已复制"、刷新点击。
+
+运行器：**vitest 3**（已声明的 devDependency）。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-plugin-showcase 的 bundle 层：一行 host + client 同包的插入。
+# name 必须是裸包名 —— modules 的宿主半侧只把 client 半挂在裸包名行上。
+- insert:
+    - id: showcase
+      name: 'dsh-plugin-showcase'

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#2f6fed"/>
+  <circle cx="32" cy="32" r="15" fill="none" stroke="#fff" stroke-width="3" stroke-dasharray="7 5"/>
+  <text x="32" y="41" font-family="sans-serif" font-size="22" font-weight="700" fill="#fff" text-anchor="middle">S</text>
+</svg>