dsh-prompt-enhance 0.2.7 → 0.3.1

package/README.md

@@ -47,14 +47,14 @@ flowchart LR
 
 The plugin is one npm package with two halves, following the dsh plugin conventions:
 
-- **Host half** (`exports "."`, Node): registers the `prompt-enhance` settings section (schemastery — rendered automatically by the built-in plugin config page), the `POST /prompt-enhance/enhance` route on the shared webserver (loopback-fenced, body-capped), and the `/enhance` slash command. The model call goes through `ctx.llm.stream` with a normalized output pass — the same auxiliary-call discipline the harness applies to session titles: deadline + caller cancellation rechecked during and after the stream, terminal-finish validation, tool-call rejection.
+- **Host half** (`exports "."`, Node): declares the `prompt-enhance` settings schema (schemastery, every field marked `.volatile()` — the host's `describe()` **drops any entry with no volatile field**, so that mark is both what makes the config page appear and the contract for "edits apply to the next request"; the plugin **re-reads it on every request** instead of caching the boot snapshot), registers the `POST /prompt-enhance/enhance` route on the shared webserver (loopback-fenced, body-capped), and the `/enhance` slash command. The model call goes through `ctx.llm.stream` with a normalized output pass — the same auxiliary-call discipline the harness applies to session titles: deadline + caller cancellation rechecked during and after the stream, terminal-finish validation, tool-call rejection.
 - **Browser half** (`exports "./client"`): registers the enhance button into the `conversation.input.right` slot and the undo bar into `conversation.input.dock`, binds a live mirror of the settings namespace, and installs the global shortcut. All copy is localized (zh/en) through the harness locale system.
 
 ## Requirements
 
 - `dsh >= 0.1.1-rc.2 < 0.3.0` — the range states what has actually been exercised, not an open-ended promise.
-- Boot-verified on `0.1.1-rc.2`, `0.1.2-alpha.3`, `0.1.7-rc.2`, and `0.2.0-rc.2` (layer mounts, enhance route answers, client bundle builds; on alpha the plugin takes the newer `ctx.settings.installSection` registration path, and on `0.2.0-rc.2` it also passes the runtime's plugin-compatibility gate). The `0.2.0-rc.2` checks include the **dsh desktop application** — the environment this plugin is normally used in. On a `0.2.x` runtime expect some *other* plugins to disappear from the UI: the gate skips any bundle whose `peerDependencies` pin an older `@deepseek-ai/dsh-*` range (observed: `dshmarket`, `dsh-find-plugin`, `dsh-better-sidebar`). The harness has broken two APIs the plugin touches: `@deepseek-ai/dsh-settings` changed its registration entry between the two early lines, and from `0.1.5-rc.3` the settings service became `SettingsForms` (no synchronous `get`) while `dsh-agent-default-model` moved the harness default model behind its own `ctx.agentDefaultModel.currentSelection()` service. The plugin probes all three shapes at runtime and adapts, no configuration needed.
-- The ceiling covers the whole `0.2.x` line (including its prereleases); a `0.3.x` is untested and therefore outside the range. `dsh.engines` is advisory metadata read by the loader and plugin manager — it states support, it does not enforce it.
+- Boot-verified on `0.1.1-rc.2`, `0.1.2-alpha.3`, `0.1.7-rc.2`, `0.2.0-rc.2`, and **`0.2.1-rc.2`** (layer mounts, enhance route answers, client bundle builds; on alpha the plugin takes the newer `ctx.settings.installSection` registration path, and on `0.2.0-rc.2` it also passes the runtime's plugin-compatibility gate). The `0.2.1-rc.2` check is a **real-host end-to-end smoke**: with the local build installed into a temporary profile, the enhance route returned a real model result; setting that profile's `maxInputChars` to `300` made a 400-character draft fail with `422 {count: 400, max: 300}`, and after editing the same profile to `20000` — **without restarting** — the identical draft went through, so a settings edit reaches the *next* request instead of staying at the boot-time snapshot. The `0.2.0-rc.2` checks include the **dsh desktop application** — the environment this plugin is normally used in. On a `0.2.x` runtime expect some *other* plugins to disappear from the UI: the gate skips any bundle whose `peerDependencies` pin an older `@deepseek-ai/dsh-*` range (observed: `dshmarket`, `dsh-find-plugin`, `dsh-better-sidebar`). The harness has broken several of the APIs this plugin touches: `@deepseek-ai/dsh-settings` changed its registration entry between the two early lines, from `0.1.5-rc.3` the settings service became `SettingsForms` (no synchronous `get`), and `0.2.x` **deleted the `installSettingsSection` / `settingsNamespace` exports outright**; `dsh-agent-default-model` moved the harness default model behind its own `ctx.agentDefaultModel.currentSelection()` service; and the browser-side settings mirror moved from `ctx.settingsScope` to `ctx.configForms`. The plugin probes every generation at runtime and adapts, no configuration needed.
+- The ceiling covers the whole `0.2.x` line (including its prereleases); a `0.3.x` is untested and therefore outside the range. `dsh.engines` **is enforced**: the host's boot preflight marks a mismatched entry `disabled = true`, and only an explicit `--accept-risk` gets past the throw (`Incompatible plugins may cause crashes or data loss`). A wrong range means the plugin does not load — not that it loads with a warning.
 - Node `^22.19.0 || >=24.0.0` (for building from source)
 - Browser peers `react` / `react-dom` (`^18.2.0`) come from the web shell's module registry. The host-half module `@deepseek-ai/dsh-llm` is a **runtime module supplied by the dsh host and is not installed from npm** (the `lib/` bundles keep every package import external), so it is declared as an *optional* peer: an install that does not provide it produces no warning, and the plugin reports a normal error at enhance time rather than failing to load.
 

package/README.zh-CN.md

@@ -47,14 +47,14 @@ flowchart LR
 
 插件是单个 npm 包、双半区结构,完全遵循 dsh 插件规范:
 
-- **宿主半区**(`exports "."`,Node):注册 `prompt-enhance` 设置节(schemastery,由内置插件配置页自动渲染)、共享 webserver 上的 `POST /prompt-enhance/enhance` 路由(仅回环、限长),以及 `/enhance` 斜杠命令。模型调用走 `ctx.llm.stream` 并做规范化处理——与 harness 对会话标题相同的辅助调用纪律:超时与调用方取消在流过程中和结束后复查、终结 finish 校验、拒绝工具调用。
+- **宿主半区**(`exports "."`,Node):声明 `prompt-enhance` 设置 schema(schemastery,每个字段带 `.volatile()`——宿主的 `describe()` 会**跳过没有任何 volatile 字段的条目**,这个标记既是"设置页会出现"的前提,也是"改完下次请求就生效"的契约;插件在**每次请求时**重新读取,而不是缓存启动快照),注册共享 webserver 上的 `POST /prompt-enhance/enhance` 路由(仅回环、限长),以及 `/enhance` 斜杠命令。模型调用走 `ctx.llm.stream` 并做规范化处理——与 harness 对会话标题相同的辅助调用纪律:超时与调用方取消在流过程中和结束后复查、终结 finish 校验、拒绝工具调用。
 - **浏览器半区**(`exports "./client"`):把增强按钮注册进 `conversation.input.right` 插槽、撤销条注册进 `conversation.input.dock` 插槽,绑定设置命名空间的实时镜像,并安装全局快捷键。全部文案经 harness locale 系统提供中英双语。
 
 ## 环境要求
 
 - `dsh >= 0.1.1-rc.2 < 0.3.0` —— 这个区间表示**实际验证过的范围**,而不是无限期的承诺。
-- 实测环境:`0.1.1-rc.2`、`0.1.2-alpha.3`、`0.1.7-rc.2`、`0.2.0-rc.2` 均已 boot 验证(插件层挂载、增强路由应答、客户端 bundle 构建通过;alpha 上走新版 `ctx.settings.installSection` 注册路径,`0.2.0-rc.2` 上还通过了运行时的插件兼容性闸门)。其中 `0.2.0-rc.2` 的验证包含 **dsh 桌面应用**——也就是本插件日常实际运行的环境。在 `0.2.x` 运行时上,可能会发现**别的**插件从界面消失:凡 `peerDependencies` 把 `@deepseek-ai/dsh-*` 锁在旧区间的 bundle 都会被闸门跳过(实测被跳过的是 `dshmarket`、`dsh-find-plugin`、`dsh-better-sidebar`)。宿主在插件用到的两处 API 上做过破坏性变更:`@deepseek-ai/dsh-settings` 的注册入口在两条早期版本线之间变了;`0.1.5-rc.3` 起 settings 服务改为 `SettingsForms`(不再有同步 `get`),同时 `dsh-agent-default-model` 把全局默认模型收进了自己的 `ctx.agentDefaultModel.currentSelection()` 服务。插件对三种形态均做运行时探测并自动适配,无需配置。
-- 上界覆盖整条 `0.2.x` 线(含其预发布版本);`0.3.x` 尚未验证,因此不在区间内。`dsh.engines` 是加载器与插件管理器读取的**声明性元数据**——它表达支持范围,并不强制拦截。
+- 实测环境:`0.1.1-rc.2`、`0.1.2-alpha.3`、`0.1.7-rc.2`、`0.2.0-rc.2`、**`0.2.1-rc.2`** 均已 boot 验证(插件层挂载、增强路由应答、客户端 bundle 构建通过;alpha 上走新版 `ctx.settings.installSection` 注册路径,`0.2.0-rc.2` 上还通过了运行时的插件兼容性闸门)。`0.2.1-rc.2` 的验证是**真实宿主的端到端冒烟**:在临时 profile 里装入本地构建后,增强路由对着在线模型返回了真实结果;把该 profile 的 `maxInputChars` 设为 `300` 后,400 字草稿被 `422 {count:400,max:300}` 拒绝,随后**不重启**把它改成 `20000`,同一份草稿立即通过——设置改动确实作用到下一次请求,而不是停在启动时的快照。其中 `0.2.0-rc.2` 的验证包含 **dsh 桌面应用**——也就是本插件日常实际运行的环境。在 `0.2.x` 运行时上,可能会发现**别的**插件从界面消失:凡 `peerDependencies` 把 `@deepseek-ai/dsh-*` 锁在旧区间的 bundle 都会被闸门跳过(实测被跳过的是 `dshmarket`、`dsh-find-plugin`、`dsh-better-sidebar`)。宿主在插件用到的几处 API 上做过破坏性变更:`@deepseek-ai/dsh-settings` 的注册入口在两条早期版本线之间变过,`0.1.5-rc.3` 起 settings 服务改为 `SettingsForms`(不再有同步 `get`),而 `0.2.x` 干脆**删掉了 `installSettingsSection` / `settingsNamespace` 导出**;`dsh-agent-default-model` 把全局默认模型收进了自己的 `ctx.agentDefaultModel.currentSelection()` 服务;浏览器侧的设置镜像则从 `ctx.settingsScope` 迁到了 `ctx.configForms`。插件对每一代形态均做运行时探测并自动适配,无需配置。
+- 上界覆盖整条 `0.2.x` 线(含其预发布版本);`0.3.x` 尚未验证,因此不在区间内。`dsh.engines` **是强制的**:宿主启动预检会把不匹配的条目直接 `disabled = true`,要放行必须显式 `--accept-risk`,否则抛 `Incompatible plugins may cause crashes or data loss`。所以这个区间写错的结果是**插件不加载**,而不是"只提示一下"。
 - Node `^22.19.0 || >=24.0.0`(仅从源码构建时需要)
 - 浏览器侧 peer `react` / `react-dom`(`^18.2.0`)由 Web 壳的模块注册表提供。宿主半区用到的 `@deepseek-ai/dsh-llm` 是**由 dsh 宿主提供的运行时模块,不从 npm 安装**(`lib/` 产物把包引用全部保持为外部),因此声明为**可选** peer:未提供它的环境不会出现安装警告,增强时按正常错误路径报错,而不是加载失败。
 

package/cordis.patch.yml

@@ -4,8 +4,9 @@
 # `dsh plugin --profile web add link:<repo>/dsh-prompt-enhance`.
 #
 # One package, both halves: the node half (exports ".") runs in the host
-# process and registers the POST /prompt-enhance/enhance route, the
-# /enhance slash command, and the "prompt-enhance" settings section; the
+# process and registers the POST /prompt-enhance/enhance route and the
+# /enhance slash command, and declares the "prompt-enhance" settings schema
+# this entry's config page renders (read live, per request); the
 # browser half (declared by `dsh.client`, served from lib/client.js) adds
 # the composer enhance button (conversation.input.right), the preview
 # panel, and the undo bar (conversation.input.dock).

package/docs/release-0.2.5.md

@@ -0,0 +1,28 @@
+## Two metadata corrections
+
+No runtime behavior changes. Both corrections remove claims the project could not back.
+
+### `dsh.engines.dsh` is now bounded: `>=0.1.1-rc.2 <0.2.0`
+
+It previously read `>=0.1.1-rc.2` — an open-ended claim that *any* future harness version is supported. Boot verification at the time covered `0.1.1-rc.2`, `0.1.2-alpha.3`, and `0.1.7-rc.2`, while the current npm line was already `0.2.0-rc.2`, so the open ceiling was over-promising.
+
+`<0.2.0` rather than `<0.1.8` is deliberate: per semver, a prerelease only matches a range that names a prerelease, so `<0.1.8` would have **excluded the verified `0.1.7-rc.2`** — the exact version the range has to keep. `<0.2.0` keeps every `0.1.x` and excludes the then-unverified `0.2.0-rc.1` / `0.2.0-rc.2`.
+
+> Superseded by **0.2.6**, which widened the ceiling to `<0.3.0` after `0.2.0-rc.2` was verified on the dsh desktop application. This release is the honest intermediate step, not the final state.
+
+### `dsh.client.inject` no longer lists `@deepseek-ai/dsh-client-ui-settings`
+
+That entry dated from the layout in which the browser half hard-declared the settings surface — the declaration that produced, on a profile without that package:
+
+```
+web boot: 1 entry did not activate
+dsh-prompt-enhance: pending (waiting for service: settingsScope)
+```
+
+…and took the whole GUI down with it (fixed in 0.2.3 by reaching every optional service through `ctx.inject`). With that fix in place the module no longer belongs in the required-provider list.
+
+### Verification
+
+- `npm run typecheck`, `npm run build` clean.
+- **207 tests across 20 files** pass.
+- Metadata-only: `lib/` is byte-identical to 0.2.4, which is why the tarball contents are unchanged apart from `package.json`.

package/docs/release-0.2.7.md

@@ -0,0 +1,22 @@
+## Version bump carrying the desktop-app verification record
+
+No runtime behavior changes. This version exists because a **docs-only** change followed 0.2.6: the source had already been verified on the current dsh line, but the record of *where* it was verified needed correcting.
+
+### What this version carries
+
+The `0.2.6` release notes described the `0.2.0-rc.2` verification as having happened on the global CLI. That was incomplete: the environment the plugin is **actually used in day to day** is the dsh **desktop application**, and its `FileVersion` is `0.2.0-rc.2` too. The record now names both hosts, and the READMEs say so as well.
+
+This matters for anyone reading the support claim: "verified on `0.2.0-rc.2`" should not rest on a CLI smoke test when the desktop app is the real target. Both were checked, and the evidence is the same three signals:
+
+1. **The runtime's plugin-compatibility gate accepts this plugin.** `0.2.0-rc.2` refuses bundles whose `peerDependencies` pin an older `@deepseek-ai/dsh-*` range. This plugin passes, thanks to the optional `@deepseek-ai/dsh-llm` peer (`>=0.1.1-rc.2`) introduced in 0.2.4. The gate skipped `dshmarket@1.45.0`, `dsh-find-plugin@0.4.0`, and `dsh-better-sidebar@0.15.2` on the same host.
+2. **No `pending (waiting for service: …)` and no `1 entry did not activate`.**
+3. **A real enhancement completed end to end**: `[prompt-enhance] … in=2 out=64 ctx=0 1928ms ok`.
+
+### Documentation-only
+
+`src/` and `lib/` are unchanged from 0.2.6; the shipped bundles are identical. The declared range is `>=0.1.1-rc.2 <0.3.0`, boot-verified on `0.1.1-rc.2`, `0.1.2-alpha.3`, `0.1.7-rc.2`, and `0.2.0-rc.2` (desktop app and CLI).
+
+### Verification
+
+- `npm run typecheck`, `npm run build` clean.
+- **207 tests across 20 files** pass.

package/docs/release-0.3.0.md

@@ -0,0 +1,36 @@
+## Adapting to the `0.2.1-rc.2` settings contract
+
+No new features. This release exists because the harness moved the two services that carry the plugin's settings, and the plugin's probes for them **failed silently**: the settings page kept rendering, edits kept landing on disk, and nothing ever reached a request or the composer. Five defects are fixed; three of them predate the update but only became reachable on the current line.
+
+### What was silently broken
+
+| Surface | What `0.2.x` did | What the user saw | Fix |
+|---|---|---|---|
+| Host: the section | Deleted the `installSettingsSection` / `settingsNamespace` exports outright; `SettingsForms.describe()` replaced them | Settings edits applied on disk, never to the next enhance | Read the row through `describe()` **per request** |
+| Browser: the mirror | `ctx.settingsScope` no longer exists | `enabled` / `maxInputChars` / `shortcut` / `streaming` stuck at the bundled defaults | `configForms.get(entryId)` first, then the aggregate binder, then the legacy scope |
+| Browser: the attachment guard | `InputState.imageIds` renamed `attachmentIds` | The "attachments only" guard never fired | Read both names |
+
+The host fix is verified end to end, not just in unit tests: on a real `dsh web` at `0.2.1-rc.2`, a profile with `maxInputChars: 300` refused a 400-character draft with `422 {count: 400, max: 300}`, and editing the same profile to `20000` — **without restarting** — let the identical draft through.
+
+### Two defects in the new browser mirror
+
+Found on a second pass over the code this release introduces.
+
+1. **It disposed an object it does not own.** `configForms.get()` does not create a form per caller: the settings provider caches one controller per entry and hands the same instance to the settings page, and `dispose()` permanently stops that controller deriving — the provider keeps the dead instance in its cache. Tearing it down on plugin unload would have frozen this entry's settings page for the rest of the session. The mirror now releases only its own subscription.
+2. **It resolved the entry id once.** With the describe mirror not yet loaded, the namespace list was empty, so the plugin bound its configured candidate — which on an aggregate bundle is not the real row, and a namespace that does not exist answers `unavailable` forever. Resolution now re-runs on every describe tick and rebinds when the served id changes, which also covers a rename the first pass could not see.
+
+### Three behaviour fixes
+
+- **Retry storms.** The rate window counts successful calls only, by design — a run of timeouts must not lock the user out when the model recovers. That left deterministic failures (wrong key, mistyped provider) bounded by nothing but the concurrency cap. Three consecutive failures now trip a 30-second cool-down answering `429 {code: 'cooldown', retryAfterSeconds, failures}` before a body is read or the model is called; a success clears the streak.
+- **`413` killed the socket.** The over-length answer used `res.socket.destroy()`, which also tore down anything else riding the same keep-alive connection. It now answers `connection: close` and lets Node discard the unread body.
+- **A rebuilt webserver left the plugin routeless.** Registration was guarded by a bare "already mounted on this context" flag, so a host that replaced its `webServer` service kept the button on screen while every click 404'd. The guard now compares service identity and re-mounts.
+
+### Migration
+
+Nothing to do. The package is a drop-in replacement for `0.2.7`; the declared range is unchanged at `>=0.1.1-rc.2 <0.3.0`, and both older settings APIs are still probed, so a `0.1.x` host keeps working.
+
+### Verification
+
+- `npm run typecheck` and `npm run build` clean against `@deepseek-ai/dsh-*@0.2.1-rc.2`; a clean rebuild of `lib/` is byte-identical.
+- **231 tests across 22 files** pass, including two new files (`tests/settings-source.test.ts`, `tests/client-settings-source.test.ts`) that pin the probe order, the rebind-on-settle path, and the "never dispose the provider's form" contract.
+- Real-host smoke on `dsh web` at `0.2.1-rc.2`: no `pending` / `did not activate`, the enhance route answered with a real model result (`deepseek-official` / `deepseek-flash`), and the settings schema appeared in the config page with Chinese descriptions.

package/docs/release-0.3.1.md

@@ -0,0 +1,50 @@
+# 0.3.1 — 设置页真的会出现，失败流真的会关
+
+0.3.0 把插件搬到了 `0.2.1-rc.2` 的契约上，但有两条最关键的路径**在真实宿主上从未生效**：设置页不存在，失败流不结束。两条都属于"看着在、其实不在"，所以这次每条都配了一个**在旧代码上必然失败**的测试。
+
+## 两个致命项
+
+| 面 | 0.2.x 的真实行为 | 用户看到什么 | 修法 |
+|---|---|---|---|
+| **设置** | `SettingsForms.describe()` 用内部 `volatileForm()` 过滤每个条目：**没有任何字段带 `meta.volatile` 时整条被丢弃** | 设置页里没有本插件；即使写入也会抛 `Plugin entry "prompt-enhance" has no volatile fields` | 16 个字段全部加 `.volatile()`；schema 库从裸 `schemastery` 换成 `@deepseek-ai/schemastery`（只有它带 `.volatile()` 与配套的位置校验） |
+| **流式失败** | 错误分支写了 `event: error` 帧，**没有 `res.end()`** | 浏览器因为收到帧而正常显示错误；`curl` / `response.text()` / 代理**永久挂起** | 成功与失败共用 `endResponse()` 收尾 |
+
+复现与验证（不是推断）：
+
+```
+宿主 volatileForm(Config)  → 修复前: undefined（条目被跳过）
+                           → 修复后: present, 16 个字段
+真宿主 dsh web @0.2.1-rc.2 → 插件激活、POST /prompt-enhance/enhance
+                             返回 deepseek-official / deepseek-flash 的真实结果
+```
+
+失败流那条的证伪：把 `endResponse(res)` 注释掉，新用例在 2.07 秒被 abort 判失败——正是"永久挂起"。
+
+## 生命周期与失败路径
+
+- **路由不随卸载回收**：`webServer.register` 只返回"从表里删项"的函数，disposer 却存在模块级 map 里、无人调用 ⇒ 卸载后路由仍用旧配置与旧限流窗答卷，重载撞 `duplicate prefix route`。改为 `ctx.inject(['webServer'])` + `ctx.effect`，服务按身份跟随、随光纤回收。
+- **`/enhance` 在无 webServer 的组合里整体消失**：`inject` 里硬写了 `['llm','webServer']`。`webServer` 移出硬依赖、改按需注入后，斜杠命令在纯 CLI 组合里依然可用。
+- **`/enhance` 遇配置异常直接抛**：`readConfig()` 在 `try` 之外，provider/model 半填时抛出的是未捕获异常，而不是路由侧那句中英双语提示。已移入 `try`。
+- **流式端点把"服务端拒绝"当成"宿主不支持流式"**：`response.ok === false` 时丢弃整个错误信封并**原样重发一次**——429 反而打两次、结构化原因（`limit`/`retryAfterSeconds`）全丢。现在先按 `ok` 分流：拒绝即报拒绝，只有"200 但不是流"才回退一次性。
+- **面板打开时快捷键打到别的会话**：结果面板 `createPortal` 挂在 `body` 上并接管焦点，上溯循环走到 `body` 时 `body.contains(每个 composer)` 恒真 ⇒ 返回注册表里的第一个会话。现在遇 `body`/`documentElement` 即停，退回"最近挂载的会话"。证伪：去掉这行判断，用例立刻变成"点了另一个会话"。
+- **设置镜像可能永久停在默认值**：`boundId` 在 `forms.get()` **之前**落值，取不到时后续每次 describe tick 都因 `entryId === boundId` 直接返回 ⇒ 永不重试。改为取到 form 之后才认领 id。
+
+## 可诊断性与小项
+
+- 客户端三处空 `catch` 改为 `console.warn`（模块注释早就承诺 "caught and logged"，代码里一行都没有）——"按钮不出现"这类报告唯一的线索来源。
+- 对话框 Tab 焦点陷阱的**反向**漏：面板根节点是刻意 `tabIndex={-1}`，既不是 first 也不是 last，`Shift+Tab` 能直接逃出。已把根节点视为"first 之前"。
+- 关闭插件后不再抢键：此前仍 `preventDefault` 后跑一个空动作，等于静默吃掉用户绑给同一组合的宿主快捷键。
+- `scripts/build.mjs` 列在 `tsconfig.include` 里但 `allowJs` 没开 ⇒ 从未被检查。现在开 `checkJs`，并给 esbuild 选项补 JSDoc（否则 `packages: 'external'` 会退化成 `string`）。
+- README 不再称 `dsh.engines` 为"声明性、不强制"：宿主启动预检会直接 `disabled = true`，放行必须显式 `--accept-risk`。
+
+## 验证
+
+- `npm run typecheck` 干净（`build.mjs` 现在确实在检查范围内，`tsc --listFilesOnly` 命中 1）
+- `npm test` **24 文件 / 242 用例全绿**（0.3.0 为 22 / 231，新增 `client-enhance-client`、`client-shortcut-target` 及配置/路由/镜像若干条）
+- 真实宿主冒烟：临时 profile 装本地包 → 插件激活、无 `pending` / `did not activate` → 增强路由返回真实模型结果 → 临时 profile 与临时目录已删除
+
+## 未做（有意）
+
+- **快捷键没有迁移到宿主的 `shortcuts` 服务**（`dsh-client-shortcuts` 支持用户改键与冲突消解）。迁移需要先确认该服务的注册契约与冲突语义，属于独立改动，不在这次"失败路径闭包"的范围内。
+- **`Origin` 只比对 hostname、不比对端口**：任意 `localhost:任意端口` 的页面都被信任。收紧需要把服务实际监听的端口传进栅栏，同样属独立改动。
+- 跨代探测的兼容死分支（`installSection`、旧 settings 模块、`webUiSettings`、`settingsScope`）保留：它们在旧版本线上仍是唯一的路径。

package/lib/client.js

@@ -65,6 +65,11 @@ function checkInputText(text, maxChars) {
 // src/shared/protocol.ts
 var ENHANCE_ENDPOINT = "/prompt-enhance/enhance";
 var ENHANCE_STREAM_ENDPOINT = "/prompt-enhance/enhance-stream";
+var PROMPT_ENHANCE_ROW_IDS = [
+  "prompt-enhance",
+  "dsh-prompt-enhance",
+  "web-ui-prompt-enhance"
+];
 
 // src/client/enhance-client.ts
 var EnhanceClientError = class extends Error {
@@ -80,6 +85,7 @@ var KNOWN_ERROR_CODES = /* @__PURE__ */ new Set([
   "rejected",
   "rate-limit",
   "concurrency-limit",
+  "cooldown",
   "timeout",
   "upstream",
   "unconfigured",
@@ -118,6 +124,16 @@ async function readEnvelope(response) {
   }
   throw new EnhanceClientError({ code: "internal", message: `\u5BBF\u4E3B\u670D\u52A1\u8FD4\u56DE\u5F02\u5E38\uFF08HTTP ${response.status}\uFF09\u3002` });
 }
+async function rejectionOf(response) {
+  try {
+    const parsed = await response.json();
+    if (parsed !== null && typeof parsed === "object" && parsed.error !== void 0) {
+      return new EnhanceClientError(parseError(parsed.error));
+    }
+  } catch {
+  }
+  return new EnhanceClientError({ code: "internal", message: `\u5BBF\u4E3B\u670D\u52A1\u62D2\u7EDD\u4E86\u8BF7\u6C42\uFF08HTTP ${response.status}\uFF09\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002` });
+}
 function takeFrames(buffer) {
   const frames = [];
   let rest = buffer;
@@ -164,9 +180,9 @@ async function requestEnhanceStream(body, options) {
     throw new EnhanceClientError({ code: "internal", message: "\u65E0\u6CD5\u8FDE\u63A5\u5BBF\u4E3B\u670D\u52A1\uFF0C\u8BF7\u786E\u8BA4 dsh web \u6B63\u5728\u8FD0\u884C\u540E\u91CD\u8BD5\u3002" });
   }
   const contentType = String(response.headers.get("content-type") ?? "").toLowerCase();
+  if (!response.ok) throw await rejectionOf(response);
   const stream = response.body;
-  const streamable = response.ok && stream !== null && stream !== void 0 && contentType.includes("event-stream");
-  if (stream === null || stream === void 0 || !streamable) {
+  if (stream === null || stream === void 0 || !contentType.includes("event-stream")) {
     void Promise.resolve().then(() => stream?.cancel()).catch(() => {
     });
     return requestEnhance(body, options.signal);
@@ -243,6 +259,8 @@ function localizedErrorMessage(t, code, params) {
       return t("error.rateLimit", params);
     case "concurrency-limit":
       return t("error.concurrencyLimit", params);
+    case "cooldown":
+      return t("error.cooldown", params);
     case "timeout":
       return t("error.timeout", params);
     case "unconfigured":
@@ -287,10 +305,12 @@ function ResultPanel(props) {
         const first = focusables[0];
         const last = focusables[focusables.length - 1];
         if (first === void 0 || last === void 0) return;
-        if (event.shiftKey && document.activeElement === first) {
+        const active = document.activeElement;
+        const atRoot = active === panel;
+        if (event.shiftKey && (active === first || atRoot)) {
           event.preventDefault();
           last.focus();
-        } else if (!event.shiftKey && document.activeElement === last) {
+        } else if (!event.shiftKey && active === last) {
           event.preventDefault();
           first.focus();
         }
@@ -554,6 +574,7 @@ function shortcutTarget() {
   if (active !== null && active instanceof Element) {
     let node = active;
     for (let depth = 0; depth < 8 && node !== null; depth++) {
+      if (node === document.body || node === document.documentElement) break;
       for (const entry of sessions.values()) {
         if (entry.root !== null && (node === entry.root || node.contains(entry.root))) {
           const found = entry;
@@ -637,7 +658,10 @@ function EnhanceButton(props) {
   const draft = useInput((state) => stringOf(state.draft));
   const phase = useInput((state) => state.phase);
   const occurrenceCount = useInput((state) => countOf(state.occurrences));
-  const imageCount = useInput((state) => countOf(state.imageIds));
+  const attachmentCount = useInput((state) => {
+    const record = state;
+    return countOf(record.attachmentIds) + countOf(record.imageIds);
+  });
   const settings = (0, import_react3.useSyncExternalStore)(subscribeClientSettings, getClientSettings);
   const panel = (0, import_react3.useSyncExternalStore)(subscribe, getPanel);
   const rootRef = (0, import_react3.useRef)(null);
@@ -651,9 +675,9 @@ function EnhanceButton(props) {
       openError(uiKey, draft, { code: "rejected", localized: disabled });
       return;
     }
-    if (imageCount > 0 && draft.trim() === "") {
-      const imagesOnly = t("error.imagesOnly");
-      openError(uiKey, draft, { code: "rejected", localized: imagesOnly });
+    if (attachmentCount > 0 && draft.trim() === "") {
+      const attachmentsOnly = t("error.attachmentsOnly");
+      openError(uiKey, draft, { code: "rejected", localized: attachmentsOnly });
       return;
     }
     const check = checkInputText(draft, settings.maxInputChars);
@@ -687,7 +711,7 @@ function EnhanceButton(props) {
       return;
     }
     requestEnhance({ sessionId: wireId, text: draft }, controller.signal).then(settle, fail);
-  }, [anyBusy, draft, imageCount, occurrenceCount, phase, settings, uiKey, wireId, t]);
+  }, [anyBusy, draft, attachmentCount, occurrenceCount, phase, settings, uiKey, wireId, t]);
   const runRef = (0, import_react3.useRef)(start);
   (0, import_react3.useEffect)(() => {
     runRef.current = start;
@@ -799,7 +823,7 @@ var zh = {
   "undo.dismiss": "\u5173\u95ED\u63D0\u793A",
   "error.empty": "\u8F93\u5165\u6846\u4E3A\u7A7A\uFF0C\u8BF7\u5148\u8F93\u5165\u8981\u589E\u5F3A\u7684\u63D0\u793A\u8BCD\u3002",
   "error.tooLong": "\u5185\u5BB9\u5171 {count} \u4E2A\u5B57\u7B26\uFF0C\u8D85\u8FC7 {max} \u4E2A\u5B57\u7B26\u4E0A\u9650\uFF08\u6309 Unicode \u5B57\u7B26\u6570\u7EDF\u8BA1\uFF0C\u4E0D\u662F token \u6570\uFF09\u3002\u4E3A\u907F\u514D\u6539\u53D8\u539F\u610F\u4E0D\u4F1A\u81EA\u52A8\u622A\u65AD\uFF0C\u8BF7\u7CBE\u7B80\u540E\u518D\u8BD5\u3002",
-  "error.imagesOnly": "\u5F53\u524D\u53EA\u9644\u52A0\u4E86\u56FE\u7247\uFF0C\u4EC5\u652F\u6301\u589E\u5F3A\u6587\u672C\u5185\u5BB9\u3002",
+  "error.attachmentsOnly": "\u8F93\u5165\u6846\u53EA\u9644\u52A0\u4E86\u9644\u4EF6\uFF08\u56FE\u7247\u6216\u6587\u4EF6\uFF09\uFF0C\u8BF7\u8865\u5145\u8981\u589E\u5F3A\u7684\u6587\u672C\u3002",
   "error.occurrences": "\u8F93\u5165\u5185\u5BB9\u5305\u542B\u547D\u4EE4\u6216\u6587\u4EF6\u5F15\u7528\uFF0C\u6682\u4E0D\u652F\u6301\u589E\u5F3A\uFF1B\u8BF7\u5148\u79FB\u9664\u540E\u518D\u8BD5\u3002",
   "error.phase": "\u5F53\u524D\u8F93\u5165\u6B63\u88AB\u5360\u7528\uFF08\u63D0\u4EA4\u4E2D\uFF09\uFF0C\u8BF7\u7A0D\u540E\u518D\u8BD5\u3002",
   "error.disabled": "\u63D0\u793A\u8BCD\u589E\u5F3A\u5DF2\u5728\u63D2\u4EF6\u8BBE\u7F6E\u4E2D\u5173\u95ED\u3002",
@@ -810,6 +834,7 @@ var zh = {
   "error.internal": "\u589E\u5F3A\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5\uFF1B\u539F\u8F93\u5165\u672A\u6539\u52A8\u3002",
   "error.rateLimit": "\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF1A\u6BCF\u5206\u949F\u6700\u591A {limit} \u6B21\u589E\u5F3A\uFF0C\u8BF7\u5728 {retryAfterSeconds} \u79D2\u540E\u518D\u8BD5\u3002",
   "error.concurrencyLimit": "\u5DF2\u6709 {max} \u4E2A\u589E\u5F3A\u6B63\u5728\u8FDB\u884C\uFF0C\u8BF7\u7B49\u5176\u4E2D\u4E00\u4E2A\u5B8C\u6210\u540E\u518D\u8BD5\u3002",
+  "error.cooldown": "\u8FDE\u7EED {failures} \u6B21\u589E\u5F3A\u5931\u8D25\uFF0C\u5DF2\u6682\u505C\u8C03\u7528\u4EE5\u514D\u6301\u7EED\u51B2\u51FB\u6A21\u578B\u670D\u52A1\uFF1B\u8BF7 {retryAfterSeconds} \u79D2\u540E\u91CD\u8BD5\uFF0C\u6216\u5148\u68C0\u67E5\u8BBE\u7F6E\u91CC\u7684\u6A21\u578B\u914D\u7F6E\u3002",
   "error.upstream.auth": "\u9274\u6743\u5931\u8D25\uFF1A\u8BF7\u68C0\u67E5\u8BE5 provider \u7684 API Key \u914D\u7F6E\u3002",
   "error.upstream.invalidCredential": "\u9274\u6743\u5931\u8D25\uFF1A\u5B58\u50A8\u7684 API Key \u4E0D\u53EF\u7528\uFF0C\u8BF7\u4FEE\u6B63\u540E\u91CD\u8BD5\u3002",
   "error.upstream.rateLimit": "\u6A21\u578B\u670D\u52A1\u9650\u6D41\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
@@ -844,7 +869,7 @@ var en = {
   "undo.dismiss": "Dismiss",
   "error.empty": "The input box is empty \u2014 type a prompt to enhance first.",
   "error.tooLong": "The draft is {count} characters, above the {max} cap (Unicode characters, not tokens). It is never auto-truncated (that would change your meaning) \u2014 please shorten it.",
-  "error.imagesOnly": "Only images are attached; prompt enhance supports text only.",
+  "error.attachmentsOnly": "The composer only has attachments; add the text you want enhanced.",
   "error.occurrences": "The draft contains commands or file references, which are not supported yet \u2014 remove them first.",
   "error.phase": "The input box is busy (submitting) \u2014 try again in a moment.",
   "error.disabled": "Prompt enhance is disabled in the plugin settings.",
@@ -855,6 +880,7 @@ var en = {
   "error.internal": "Enhancement failed. Retry; your draft is untouched.",
   "error.rateLimit": "Too many requests \u2014 at most {limit} enhancements per minute; retry in {retryAfterSeconds} seconds.",
   "error.concurrencyLimit": "{max} enhancements are already running \u2014 wait for one to finish, then retry.",
+  "error.cooldown": "{failures} enhancements failed in a row; calls are paused to stop hammering the model service. Retry in {retryAfterSeconds}s, or check the model settings first.",
   "error.upstream.auth": "Authentication failed \u2014 check the API key configured for this provider.",
   "error.upstream.invalidCredential": "Authentication failed \u2014 the stored API key is invalid; fix it and retry.",
   "error.upstream.rateLimit": "The model provider is rate-limiting; retry later.",
@@ -1108,61 +1134,206 @@ function matchesShortcut(event, combo) {
   return event.ctrlKey === combo.ctrl && event.altKey === combo.alt && event.shiftKey === combo.shift && event.metaKey === combo.meta && (event.code === combo.code || event.key.toLowerCase() === combo.key);
 }
 
+// src/client/settings-source.ts
+var RANK = {
+  none: 0,
+  legacyScope: 1,
+  binder: 2,
+  configForms: 3
+};
+function sectionOf(snapshot) {
+  if (snapshot === null || typeof snapshot !== "object") return void 0;
+  const record = snapshot;
+  if (record.status === "unavailable") return void 0;
+  return record.value;
+}
+function servedNamespaces(forms) {
+  try {
+    const namespaces = forms.describe?.()?.getSnapshot?.()?.view?.namespaces;
+    return Array.isArray(namespaces) ? namespaces.map((entry) => String(entry?.ns ?? "")) : [];
+  } catch {
+    return [];
+  }
+}
+function installClientSettingsSource(ctx, options) {
+  let rank = RANK.none;
+  const adopt = (next, section) => {
+    if (section === void 0 || next < rank) return;
+    rank = next;
+    options.onSection(section);
+  };
+  const adoptSnapshot = (next, form) => {
+    try {
+      const section = sectionOf(form.getSnapshot?.());
+      if (section !== void 0) adopt(next, section);
+    } catch {
+    }
+  };
+  ctx.inject(["configForms"], (formsCtx) => {
+    const forms = formsCtx.configForms;
+    if (forms === void 0 || typeof forms.get !== "function") return;
+    let boundId;
+    let unsubscribeForm;
+    const resolveEntryId = () => {
+      const served = servedNamespaces(forms);
+      return options.rowIds.find((id) => served.includes(id)) ?? served.find((ns) => ns.includes("prompt-enhance")) ?? options.rowIds[0];
+    };
+    const bind = () => {
+      const entryId = resolveEntryId();
+      if (entryId === void 0 || entryId === boundId) return;
+      let form;
+      try {
+        form = forms.get?.(entryId);
+      } catch {
+        return;
+      }
+      if (form === void 0) return;
+      try {
+        unsubscribeForm?.();
+      } catch {
+      }
+      unsubscribeForm = void 0;
+      boundId = entryId;
+      adoptSnapshot(RANK.configForms, form);
+      try {
+        unsubscribeForm = form.subscribe?.(() => adoptSnapshot(RANK.configForms, form));
+      } catch {
+        unsubscribeForm = void 0;
+      }
+    };
+    bind();
+    ctx.effect(() => () => {
+      try {
+        unsubscribeForm?.();
+      } catch {
+      }
+    }, "prompt-enhance: settings form mirror");
+    try {
+      const watch = forms.describe?.()?.subscribe?.(() => bind());
+      if (typeof watch === "function") {
+        ctx.effect(() => () => {
+          try {
+            watch();
+          } catch {
+          }
+        }, "prompt-enhance: settings namespace watch");
+      }
+    } catch {
+    }
+  });
+  ctx.inject(["webUiSettings"], (binderCtx) => {
+    const binder = binderCtx.webUiSettings;
+    if (binder === void 0 || typeof binder.bind !== "function") return;
+    let bound;
+    for (const namespace of options.rowIds) {
+      try {
+        bound = binder.bind({ namespace });
+      } catch {
+        bound = void 0;
+      }
+      if (bound !== void 0) break;
+    }
+    if (bound === void 0) return;
+    adoptSnapshot(RANK.binder, bound);
+    let unsubscribe;
+    try {
+      unsubscribe = bound.subscribe?.(() => adoptSnapshot(RANK.binder, bound));
+    } catch {
+      unsubscribe = void 0;
+    }
+    ctx.effect(() => () => {
+      try {
+        unsubscribe?.();
+      } catch {
+      }
+    }, "prompt-enhance: settings binder mirror");
+  });
+  ctx.inject(["settingsScope"], (scopeCtx) => {
+    const scopeCtxLike = scopeCtx;
+    const scope = scopeCtxLike.settingsScope;
+    if (scope === void 0 || typeof scope.bind !== "function") return;
+    let bound;
+    try {
+      bound = scope.bind({ namespace: options.rowIds[0] ?? "prompt-enhance", decode: (value) => value });
+    } catch {
+      return;
+    }
+    adoptSnapshot(RANK.legacyScope, bound);
+    let unsubscribe;
+    try {
+      unsubscribe = bound.subscribe?.(() => adoptSnapshot(RANK.legacyScope, bound));
+    } catch {
+      unsubscribe = void 0;
+    }
+    ctx.effect(() => () => {
+      try {
+        unsubscribe?.();
+      } catch {
+      }
+    }, "prompt-enhance: settings scope mirror");
+  });
+}
+
 // src/client/index.tsx
 var inject = [];
+function report(step, error) {
+  try {
+    console.warn(`[prompt-enhance] ${step} failed; that feature stays off.`, error);
+  } catch {
+  }
+  return () => {
+  };
+}
 function apply(ctx) {
   ensureStyles();
   ctx.inject(["locale"], (localeCtx) => {
     ctx.effect(() => {
       try {
         return localeCtx.locale.register(NS, dictionaries);
-      } catch {
-        return () => {
-        };
+      } catch (error) {
+        return report("dictionary registration", error);
       }
     }, "dsh-prompt-enhance: dictionaries");
   });
   setClientSettings(decodeClientSettings(void 0));
-  ctx.inject(["settingsScope"], (settingsCtx) => {
-    const scope = settingsCtx.settingsScope.bind({ namespace: NS, decode: decodeClientSettings });
-    const sync = () => {
-      setClientSettings(scope.getSnapshot().value ?? decodeClientSettings(void 0));
-    };
-    sync();
-    ctx.effect(() => scope.subscribe(sync), "dsh-prompt-enhance: settings mirror");
+  installClientSettingsSource(ctx, {
+    rowIds: PROMPT_ENHANCE_ROW_IDS,
+    onSection: (section) => setClientSettings(decodeClientSettings(section))
   });
   ctx.inject(["slots"], (slotsCtx) => {
     const slots = slotsCtx.slots;
+    if (slots === void 0) return;
     return slots.inject("conversation.input.right", () => {
       try {
         return slots.register(
           { name: "conversation.input.right", id: "prompt-enhance", order: 60, locale: NS },
           EnhanceButton
         );
-      } catch {
-        return () => {
-        };
+      } catch (error) {
+        return report("composer enhance button slot", error);
       }
     });
   });
   ctx.inject(["slots"], (slotsCtx) => {
     const slots = slotsCtx.slots;
+    if (slots === void 0) return;
     return slots.inject("conversation.input.dock", () => {
       try {
         return slots.register(
           { name: "conversation.input.dock", id: "prompt-enhance-undo", order: 90, locale: NS },
           UndoBar
         );
-      } catch {
-        return () => {
-        };
+      } catch (error) {
+        return report("undo bar slot", error);
       }
     });
   });
   ctx.effect(() => {
     const onKeyDown = (event) => {
       if (event.defaultPrevented || event.isComposing) return;
-      const combo = parseShortcut(getClientSettings().shortcut);
+      const settings = getClientSettings();
+      if (!settings.enabled) return;
+      const combo = parseShortcut(settings.shortcut);
       if (!matchesShortcut(event, combo)) return;
       const target = shortcutTarget();
       if (target === void 0) return;