dsh-prompt-enhance 0.1.0 → 0.1.2

package/README.md

@@ -1,120 +1,237 @@
 # dsh-prompt-enhance
 
-DeepSeek Harness(DSH)Web GUI 的「提示词增强」插件:把输入框里的草稿一键改写为结构化提示词——补全背景与约束、明确目标与角色、拆分可执行步骤、指定输出格式与验收标准、补充边界条件;**不改变原意、不凭空编造需求**。增强前后并排对比,一键回填 / 复制 / 撤销。
+[![CI](https://github.com/rongxingda/dsh-prompt-enhance/actions/workflows/ci.yml/badge.svg)](https://github.com/rongxingda/dsh-prompt-enhance/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-prompt-enhance)](https://www.npmjs.com/package/dsh-prompt-enhance)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
-仿照 WorkBuddy 的提示词增强体验,基于 DSH 的 Cordis 插件体系实现,单包双半区:
+**Prompt enhancement for the [DeepSeek Harness](https://github.com/deepseek-ai) web GUI** — one click turns a rough composer draft into a well-structured prompt: explicit role and goal, executable steps, output format, acceptance criteria, and edge cases. Your intent is never changed, nothing is fabricated, and the original draft is always preserved.
 
-- **宿主半区**(`exports "."`):`prompt-enhance` 设置节(schemastery,自动渲染于 设置 → 插件配置)、`POST /prompt-enhance/enhance` 路由(经 `ctx.llm` 调模型,回环安全栅栏)、`/enhance <文本>` 斜杠命令。
-- **浏览器半区**(`exports "./client"`):输入框工具栏增强按钮(`conversation.input.right`)、增强前后对比预览面板、撤销条(`conversation.input.dock`)、可配置全局快捷键。
+English | [简体中文](./README.zh-CN.md)
 
-## 触发方式
+---
 
-| 入口 | 行为 |
+## Why
+
+Good agent prompts state *who the model should be*, *what to deliver*, *in what format*, and *how success is judged*. Most drafts don't. This plugin adds a **WorkBuddy-style "enhance" affordance** to the dsh composer: it sends your draft through a low-temperature rewrite pass (via the harness's own LLM service), shows the result next to the original, and lets you apply, copy, or discard it. Undo is one click away, and every failure path leaves your draft exactly as you typed it.
+
+## Features
+
+| | |
 |---|---|
-| 输入框工具栏 ✨ 按钮(发送键左侧) | 读取草稿 → 调用宿主增强 → 弹出对比面板 |
-| 快捷键(默认 `Ctrl+Alt+E`,可配置) | 作用于焦点所在的输入框;避免浏览器保留组合 |
-| `/enhance <文本>` 斜杠命令 | 增强命令参数文本,结果在命令面板展示可复制,不进入对话历史 |
+| ✨ **Composer button** | A small button in the input box's tool row (next to the send button), always at hand |
+| 🔀 **Preview panel** | Original vs. enhanced side by side, with model name and elapsed time |
+| ↩️ **One-click undo** | After applying, a quiet bar above the composer restores the original draft |
+| ⌨️ **Shortcut** | Default `Ctrl+Alt+E`, fully configurable, acts on the composer you are working in |
+| 💬 **`/enhance` command** | Rewrite any text from the slash-command plane; the result never enters model history |
+| 🧠 **Model routing** | Settings pair → current session model → harness default model, in that order |
+| 🔑 **Zero credential setup** | Calls ride the harness LLM service; keys come from the harness credential store |
+| ⚙️ **Live settings** | Every knob (model override, temperature, budgets, system prompt, shortcut) hot-applies from Settings → 插件配置 |
+| 🛡️ **Draft safety** | Empty, over-length, images-only, and command-chip inputs are rejected locally; upstream failures are mapped to readable messages; the draft is never mutated on failure |
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Composer draft] --> B{Local guards<br/>empty / length / chips / busy}
+    B -- pass --> C["POST /prompt-enhance/enhance<br/>(loopback-fenced host route)"]
+    B -- reject --> P[Preview panel:<br/>readable error, draft untouched]
+    C --> D["ctx.llm.stream<br/>rewrite with system strategy"]
+    D --> E[Normalize:<br/>strip fences, trim, refuse empty]
+    E --> F[Preview panel:<br/>original | enhanced]
+    F -- Apply --> G["setDraft(enhanced)<br/>original pushed to undo stack"]
+    F -- Cancel / Copy --> H[Draft untouched]
+    G --> U[Undo bar: one click restores]
+```
 
-面板内:**回填到输入框**(保留原文供撤销)/ **复制结果** / **取消**(Esc 或点击遮罩)。回填后输入框上方出现「✓ 已用增强结果替换原提示词 [撤销]」提示条,一键恢复原文;继续输入会自动撤销撤销条,不会用过期文本覆盖新编辑。原文始终保留,任何失败都不改动草稿。
+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.
+- **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.
 
-1. 插件设置中成对填写的 `provider` + `model`;
-2. 当前会话已记录的请求路由(跟随会话模型);
-3. 全局默认模型(`agent-default-model` 设置)。
+## Requirements
 
-三者皆无时明确报错并指引导配置,不做静默兜底。凭据与传输完全复用 harness 的 LLM 服务,无需在插件内再配 API Key。
+- `dsh >= 0.1.1-rc.1`
+- Node `^22.19.0 || >=24.0.0` (for building from source)
 
-## 配置(设置 → 插件配置 → prompt-enhance)
+## Install
 
-| 字段 | 默认 | 说明 |
-|---|---|---|
-| `enabled` | `true` | 总开关;关闭隐藏按钮并停用所有触发 |
-| `provider` / `model` | 空 | 成对覆盖模型路由;留空跟随当前会话 |
-| `temperature` | `0.3` | 低温改写更忠实原意 |
-| `maxOutputTokens` | `2048` | 单次输出上限 |
-| `maxInputChars` | `12000` | 输入字数上限;**超限拒绝而不截断**(避免改变原意) |
-| `timeoutMs` | `60000` | 单次超时(毫秒) |
-| `systemPrompt` | 内置策略 | 留空用内置增强策略;可整体替换 |
-| `shortcut` | `ctrl+alt+e` | 快捷键(如 `ctrl+shift+p`);留空禁用 |
-
-配置热生效:每次增强调用前重读设置,改完保存即作用于下一次调用。
-
-## 异常与边界
-
-- **空输入 / 仅空白 / 零宽字符**:本地拦截,提示「输入框为空」。
-- **超长输入**:本地 + 宿主双重校验,拒绝并给出字数,不截断。
-- **仅图片无文本**:提示仅支持文本。
-- **含命令 / 文件引用 chip**(如 `/compact`、`@file`):回填会破坏 chip,拒绝并提示先移除。
-- **提交中 / 请求在途**:防重入,提示稍候;面板加载中可取消(请求随之中止)。
-- **上游失败**:按稳定错误码映射为可读中文(AUTH → 鉴权失败、RATE_LIMIT → 限流、QUOTA_EXCEEDED → 配额不足、CONTEXT_WINDOW_EXCEEDED → 超上下文等),附「原输入未改动」。
-- **模型返回空 / 包裹代码围栏 / 请求工具调用**:规范化与校验兜底(剥围栏、拒绝空结果),错误可直接重试。
-- **浏览器中途关闭 / 切换会话**:宿主路由侦测连接断开即中止模型调用;面板与撤销栈按会话隔离,随会话清理。
-- 所有失败只出现在插件自己的面板中,输入框草稿永不被动丢失,可继续手动输入。
-
-## 安装
+From npm (recommended):
 
 ```bash
-cd dsh-prompt-enhance
-npm install
-npm run build          # tsc 类型检查 + esbuild 产出 lib/index.js(ESM)与 lib/client.js(ModuleLoader 包裹)
-dsh plugin --profile web add link:C:\path\to\dsh-prompt-enhance
-# 重启 dsh web
+dsh plugin --profile web add dsh-prompt-enhance
+# restart dsh web
 ```
 
-从 GitHub 安装(lib 已随仓库提交,无需本地构建):
+From GitHub (the built `lib/` is committed, so no local build happens):
 
 ```bash
 dsh plugin --profile web add github:rongxingda/dsh-prompt-enhance
-# 重启 dsh web
 ```
 
-卸载:`dsh plugin --profile web remove dsh-prompt-enhance`(并检查 profile package.json 的 `dsh.profile.bundles` 数组是否残留该行,残留则手动删除)。
+From a local checkout (for development — changes rebuild + restart take effect):
 
-要求:`dsh >= 0.1.1-rc.1`,Node `^22.19 || >=24`。
+```bash
+git clone https://github.com/rongxingda/dsh-prompt-enhance.git
+cd dsh-prompt-enhance && npm install && npm run build
+dsh plugin --profile web add link:C:\path\to\dsh-prompt-enhance
+```
 
-## 发布新版本(维护者)
+Uninstall:
 
-1. `npm version <patch|minor|major>` 更新版本号并打 tag;
-2. `npm run build` 确保 `lib/` 与源码一致,与版本提交一起推送;
-3. 推送 tag(`git push --follow-tags`),在 GitHub Releases 上发布说明。
+```bash
+dsh plugin --profile web remove dsh-prompt-enhance
+# check the profile's package.json `dsh.profile.bundles` array for a leftover
+# "dsh-prompt-enhance" row and remove it if present, then restart dsh web
+```
 
-`lib/` 是刻意提交的:GitHub 直装(`dsh plugin add github:...`)不会执行构建,提交产物让安装零构建依赖。CI 会在 `lib/` 与源码不一致时拒绝合并。
+## Usage
 
-## 开发
+**Composer button / shortcut** — type (or leave) a draft, hit ✨ or `Ctrl+Alt+E`:
 
-```bash
-npm run typecheck      # tsc --noEmit
-npm test               # vitest(48 个单测:校验/规范化/增强调用/撤销栈/快捷键/配置/客户端设置)
-npm run watch          # esbuild 监听构建双半区
-```
+1. Local guards run first: empty drafts, over-length drafts (never auto-truncated — that would change your meaning), images-only drafts, and drafts containing command or file-reference chips are refused with a clear message. Chips are rejected because filling back would destroy them.
+2. The preview panel opens with a cancellable spinner. Your draft stays untouched — the hint says so.
+3. The result phase shows both texts side by side. **Apply** fills the enhanced text back and raises the undo bar; **Copy** puts it on the clipboard; **Cancel** (or `Esc`, or clicking the overlay) discards everything.
+4. The undo bar sits above the composer: one click restores the original. If you keep typing after applying, the bar quietly retires itself so stale text can never overwrite newer edits.
 
-结构:
+**`/enhance <text>`** — rewrite any text from the slash menu. The result renders in the command plane (copyable) and never enters the conversation history or the model's context. To enhance the *composer draft itself*, use the button or shortcut — the draft lives in the browser.
+
+**Language consistency** is guaranteed by the rewrite strategy: Chinese in, Chinese out; English in, English out.
+
+## Configuration
+
+Everything lives in the `prompt-enhance` settings namespace, edited from the web GUI's **Settings → 插件配置** page. Changes apply to the very next call — no restart.
+
+| Field | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Master switch; off hides the button and disables every trigger |
+| `provider` + `model` | empty | Explicit route override; must be filled as a **pair** (or both empty to follow the current session model) |
+| `temperature` | `0.3` | Low temperature keeps the rewrite faithful to the original |
+| `maxOutputTokens` | `2048` | Output token budget of one enhancement call |
+| `maxInputChars` | `12000` | Input character cap; over-limit drafts are **rejected, never truncated** |
+| `timeoutMs` | `60000` | End-to-end deadline of one call |
+| `systemPrompt` | built-in strategy | Replace the whole enhancement strategy if you prefer your own |
+| `shortcut` | `ctrl+alt+e` | Global shortcut spec (at least one modifier + one alphanumeric/function key — bare keys are ignored so normal typing can never be swallowed); empty disables it |
+| `provider` + `model` values | — | Match the harness settings: each key under `llm-pi-ai.providers` (e.g. `zhipu`, `muyuu`) is a provider and each `models[].id` under it (e.g. `glm-5.3-flash`) is a model. Example pair: `provider: zhipu` + `model: glm-5.3-flash` |
+
+**Model routing precedence:** explicit settings pair → the route recorded in the current session's request header → the harness-wide default model (`agent-default-model`). If none of them names a route (e.g. a fresh session with no default model), the plugin fails with an actionable message instead of guessing.
+
+## The built-in enhancement strategy
+
+The default system prompt instructs the model to be a prompt-rewriting expert and to apply what the draft actually needs:
+
+1. **Role and goal** — state who the assistant acts as and what the deliverable is.
+2. **Context and constraints** — add only what the draft implies; never invent facts, data, names, or requirements.
+3. **Steps** — break vague or multi-part requests into numbered, executable steps.
+4. **Output format** — specify structure, language, length, and style where implied.
+5. **Acceptance criteria** — state how to recognize a correct result.
+6. **Boundary conditions** — list edge cases and what to do when information is missing.
+
+Hard rules: preserve intent exactly (never remove, alter, or contradict user information); never fabricate — insert an explicit placeholder like `(待补充：…)` / `(TBD: …)` for unknown details; keep the scope unchanged; output **only** the rewritten body (no explanations, fences, or pleasantries); mirror the input language; stay within roughly 1–3× the original length; lightly polish already-well-formed prompts instead of inflating them.
+
+Set `systemPrompt` in the settings to replace all of this with your own strategy.
+
+## Error handling & edge cases
+
+| Case | Behavior |
+|---|---|
+| Empty / whitespace / invisible-only draft | Local refusal: "input box is empty" |
+| Draft over `maxInputChars` | Rejected locally and at the route with exact counts; **no auto-truncation** |
+| Images attached but no text | Refused: text-only feature |
+| Command or file-reference chips in the draft | Refused: fill-back would destroy the chips |
+| Submitting / busy phase or a request already in flight | Refused with "try again in a moment" |
+| Upstream model failure | Stable codes mapped to readable hints: `AUTH` → check API key, `RATE_LIMIT` → retry later, `QUOTA_EXCEEDED` → check balance, `CONTEXT_WINDOW_EXCEEDED` → shorten input, `NO_ADAPTER`/unconfigured → configure a model |
+| Output reaches `maxOutputTokens` | Refused with a hint to raise the cap or shorten the draft |
+| Model returns empty / fence-wrapped / tool-call output | Normalized (fences stripped) or refused; retryable |
+| Timeout | `504`-mapped message with the configured seconds; retryable |
+| Browser tab closed mid-flight | The host route detects the disconnect and aborts the model call |
+| Session switch | Panel state, undo stack, and shortcut targeting are per-session; switching closes the panel and clears its undo entries |
+
+Every failure surfaces inside the plugin's own panel; the composer draft is never modified by a failed call, so manual input continues undisturbed.
+
+## Security model
+
+The enhance route is served by your own dsh host and reachable **only from this machine**:
+
+- **Socket fence** — requests from non-loopback addresses are refused (`127.0.0.1` / `::1` only). Note this means *any local process* can call the route; it carries no user authentication.
+- **Host allowlist** — the route also validates the `Host` header against `localhost` / `127.0.0.1` / `[::1]`, which defeats DNS-rebinding (a rebound attacker domain keeps the loopback socket address but carries the attacker's hostname and is refused). Responses are `cache-control: no-store`.
+- **Not for reverse-proxy exposure** — if you put dsh web behind a proxy that listens on the LAN, external callers appear as loopback to the route and the fence is moot. Do not expose a proxied host without adding your own authentication at the proxy.
+- **Prompt-injection boundary** — the draft is framed between `<raw_prompt>` tags, literal closing tags inside the draft are neutralized, and the strategy prompt treats the framed text as pure data. Enhancements run with your own credentials and the result is only ever shown back to you.
+
+## Architecture
 
 ```
 src/
-├── index.ts            宿主 apply:设置节 + 路由 + 命令
-├── config.ts           schemastery 模式 + 解析校验(成对路由)
-├── prompts.ts          内置增强策略系统提示词 + <raw_prompt> 框架
-├── enhancer.ts         ctx.llm 辅助调用(路由解析/超时竞速/finish 校验)
-├── enhance-routes.ts   POST /prompt-enhance/enhance(回环栅栏/限长/错误码)
-├── enhance-command.ts  /enhance 斜杠命令
-├── shared/             两端共用:协议类型、输入校验、输出规范化
-└── client/
-    ├── index.tsx       浏览器 apply:插槽注册 + 设置镜像 + 快捷键
-    ├── EnhanceButton   input.right 按钮 + 守卫链 + 调用编排
-    ├── ResultPanel     对比预览面板(回填/复制/取消/重试)
-    ├── UndoBar         input.dock 撤销条
-    ├── ui-state        跨组件面板/撤销/会话注册表(外部 store)
-    └── …               fetch 客户端、undo-stack、shortcut、locales、styles
+├── index.ts            host apply(): settings section + route + command
+├── config.ts           schemastery schema + resolution (paired route validation)
+├── prompts.ts          built-in strategy system prompt + <raw_prompt> framing
+├── enhancer.ts         the ctx.llm auxiliary call (route resolution, deadline
+│                       racing, finish validation, code → message mapping)
+├── enhance-routes.ts   POST /prompt-enhance/enhance (loopback fence, body cap)
+├── enhance-command.ts  /enhance slash command (host command registry)
+├── loopback.ts         127.0.0.1/::1 fence for the route
+├── http.ts             bounded JSON body reader / writer
+├── shared/             wire protocol types, input checks, output normalization
+│                       (imported by both halves)
+└── client/             browser half
+    ├── index.tsx       slots registration + settings mirror + shortcut listener
+    ├── EnhanceButton   conversation.input.right entry: guards + call orchestration
+    ├── ResultPanel     overlay panel: compare / apply / copy / cancel / retry
+    ├── UndoBar         conversation.input.dock entry: restore affordance
+    ├── ui-state.ts     external store shared by components (panel, undo, sessions)
+    ├── enhance-client  fetch client with abort + typed errors
+    ├── undo-stack.ts   per-session LIFO (depth 3)
+    ├── shortcut.ts     pure combo parsing / matching
+    ├── settings.ts     client mirror of the settings namespace
+    ├── locales.ts      zh + en dictionaries (harness locale namespace)
+    └── styles.ts       self-injected stylesheet (dsh-pe- prefixed classes)
+```
+
+Build outputs: `lib/index.js` (host half, ESM, package imports kept external) and `lib/client.js` (browser half bundled to CJS inside the `window.__ModuleLoader__.load({ id, factory })` envelope the dsh web shell expects). Both are committed so GitHub installs need no build step; CI fails if `lib/` drifts from `src/`.
+
+## Development
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit
+npm test              # unit + real-http + component suites
+npm run build         # typecheck + both halves
+npm run watch         # esbuild watch for both halves
+```
+
+**Test coverage:** input validation, output normalization, the enhancer against stubbed `ctx.llm` streams, a real-`node:http` route suite (loopback Host fence, disconnect abort, error envelopes), the loopback/Host fence units, prompt framing, config resolution, the undo stack, shortcut parsing, client settings, and React component tests locking the enhance → apply → undo flow (guards, stale marking, diverged-draft undo semantics).
+
+**Release process (maintainers):**
+
+```bash
+npm version patch   # or minor / major — bumps package.json and tags
+npm run build       # make lib/ match src/
+git push --follow-tags
+npm publish         # with 2FA OTP, or a granular token with "bypass 2FA" checked
 ```
 
-## 验收清单(实机 `dsh web`)
+CI runs typecheck + tests + build on every push/PR and rejects merges where `lib/` differs from the committed build.
+
+## FAQ
+
+**Why is my draft rejected when it contains `/commands` or `@references`?**
+The fill-back writes plain text via `inputActions.setDraft`, which would destroy the chips. Remove them, enhance, then re-insert.
+
+**Why isn't over-length input auto-truncated?**
+Truncation silently changes your meaning — the plugin refuses and shows the exact counts instead.
+
+**Can I pin a specific model?**
+Fill `provider` and `model` **as a pair** in the settings (e.g. your harness-configured provider route). Leave both empty to follow the current session's model.
+
+**Where does my draft go?**
+Browser → your own dsh host over a loopback-only route → the harness LLM service → the configured model provider. Nothing is sent anywhere else, and the enhancement never enters the session's model history.
+
+**Does it work with the official DeepSeek route?**
+Yes — it rides `ctx.llm`, so any provider the harness serves (DeepSeek official, OpenAI-compatible gateways) works.
+
+## Acknowledgments
+
+Plugin structure, the loopback fence, and the settings-section pattern follow the conventions established by the dsh plugin family — in particular [`@linxin666/dsh-tool-describe-image`](https://www.npmjs.com/package/@linxin666/dsh-tool-describe-image).
+
+## License
 
-- [ ] 中文输入「帮我写个爬虫」→ 增强 → 面板对比,回填后草稿为结构化中文提示词,撤销恢复原文
-- [ ] 英文输入返回英文(语言一致性)
-- [ ] 空输入 / 超长输入 / 含 `/命令` chip / 提交中,均被拦截且草稿不变
-- [ ] 面板加载中点取消:草稿不变,可继续输入
-- [ ] 拔掉 API Key 或断网:错误消息可读,重试可用
-- [ ] 设置改 `shortcut` / `maxInputChars` / `enabled` 后无需重启即生效
-- [ ] `/enhance 帮我写周报` 结果在命令面板展示且未发送给会话模型
+[Apache-2.0](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,236 @@
+# dsh-prompt-enhance
+
+[![CI](https://github.com/rongxingda/dsh-prompt-enhance/actions/workflows/ci.yml/badge.svg)](https://github.com/rongxingda/dsh-prompt-enhance/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-prompt-enhance)](https://www.npmjs.com/package/dsh-prompt-enhance)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+
+**DeepSeek Harness Web GUI 的「提示词增强」插件** —— 一键把输入框里的草稿改写为结构化提示词:明确的角色与目标、可执行步骤、输出格式、验收标准、边界条件。不改变原意、不凭空编造需求,原文始终保留。
+
+[English](./README.md) | 简体中文
+
+---
+
+## 为什么需要它
+
+好的智能体提示词会讲清*让模型扮演谁*、*交付什么*、*以什么格式*、*怎样算合格*——而大多数草稿不会。本插件给 dsh 输入框加上 WorkBuddy 风格的「增强」入口:草稿经低温重写(走 harness 自带的 LLM 服务),结果与原文并排对比,你可以回填、复制或丢弃。撤销只需一键,且**任何失败路径都不会改动你输入的内容**。
+
+## 功能一览
+
+| | |
+|---|---|
+| ✨ **输入框按钮** | 工具栏内发送键旁的小按钮,随手可及 |
+| 🔀 **对比预览面板** | 原文与增强结果左右并排,附模型名与耗时 |
+| ↩️ **一键撤销** | 回填后输入框上方出现撤销条,一键恢复原文 |
+| ⌨️ **快捷键** | 默认 `Ctrl+Alt+E` 可配置,作用于你正在使用的输入框 |
+| 💬 **`/enhance` 命令** | 斜杠面板直接改写任意文本;结果不进入模型历史 |
+| 🧠 **模型路由** | 设置成对覆盖 → 当前会话模型 → 全局默认模型,依次回退 |
+| 🔑 **零凭据配置** | 调用走 harness LLM 服务,密钥来自 harness 凭据存储 |
+| ⚙️ **配置热生效** | 模型覆盖、温度、预算、系统提示词、快捷键,全部在 设置 → 插件配置 即改即用 |
+| 🛡️ **草稿安全** | 空输入、超长、仅图片、含命令块在本地拦截;上游失败映射为可读提示;失败绝不改动草稿 |
+
+## 工作原理
+
+```mermaid
+flowchart LR
+    A[输入框草稿] --> B{本地守卫<br/>空 / 超长 / 命令块 / 占用}
+    B -- 通过 --> C["POST /prompt-enhance/enhance<br/>(仅回环的宿主路由)"]
+    B -- 拒绝 --> P[预览面板:<br/>可读错误,草稿不动]
+    C --> D["ctx.llm.stream<br/>按内置策略重写"]
+    D --> E[规范化:<br/>剥围栏 / 去空白 / 拒空]
+    E --> F[预览面板:<br/>原文 | 增强结果]
+    F -- 回填 --> G["setDraft(增强文本)<br/>原文压入撤销栈"]
+    F -- 取消 / 复制 --> H[草稿不动]
+    G --> U[撤销条:一键恢复]
+```
+
+插件是单个 npm 包、双半区结构,完全遵循 dsh 插件规范:
+
+- **宿主半区**(`exports "."`,Node):注册 `prompt-enhance` 设置节(schemastery,由内置插件配置页自动渲染)、共享 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.1`
+- Node `^22.19.0 || >=24.0.0`(仅从源码构建时需要)
+
+## 安装
+
+从 npm(推荐):
+
+```bash
+dsh plugin --profile web add dsh-prompt-enhance
+# 重启 dsh web
+```
+
+从 GitHub(构建产物 `lib/` 已随仓库提交,安装无需本地构建):
+
+```bash
+dsh plugin --profile web add github:rongxingda/dsh-prompt-enhance
+```
+
+从本地检出(开发用,改代码重建 + 重启即生效):
+
+```bash
+git clone https://github.com/rongxingda/dsh-prompt-enhance.git
+cd dsh-prompt-enhance && npm install && npm run build
+dsh plugin --profile web add link:C:\path\to\dsh-prompt-enhance
+```
+
+卸载:
+
+```bash
+dsh plugin --profile web remove dsh-prompt-enhance
+# 检查 profile 的 package.json 中 `dsh.profile.bundles` 数组是否残留
+# "dsh-prompt-enhance" 行,有则手动删除,然后重启 dsh web
+```
+
+## 使用方法
+
+**输入框按钮 / 快捷键** —— 输入(或留着)草稿,点 ✨ 或按 `Ctrl+Alt+E`:
+
+1. 先跑本地守卫:空草稿、超长草稿(**不自动截断**——截断会改变原意)、仅图片草稿、含命令或文件引用块的草稿,都会被拒绝并给出明确提示。引用块被拒是因为回填会破坏它们。
+2. 预览面板打开,显示可取消的加载动画。此时草稿原封不动——面板上写明了这一点。
+3. 结果阶段左右并排展示两份文本。**回填**把增强文本写回输入框并升起撤销条;**复制**进剪贴板;**取消**(`Esc` 或点击遮罩)丢弃一切。
+4. 撤销条停在输入框上方:一键恢复原文。回填后你继续输入,撤销条会安静地自我退位——过期的原文永远不会覆盖你更新的编辑。
+
+**`/enhance <文本>`** —— 从斜杠菜单改写任意文本。结果在命令面板渲染(可复制),不进入会话历史与模型上下文。要增强**输入框里的草稿**请用按钮或快捷键——草稿在浏览器里。
+
+**语言一致性**由重写策略保证:中文进中文出,英文进英文出。
+
+## 配置
+
+全部配置位于 `prompt-enhance` 设置命名空间,在 Web GUI 的 **设置 → 插件配置** 页编辑。改动作用于下一次调用——无需重启。
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `enabled` | `true` | 总开关;关闭隐藏按钮并停用所有触发方式 |
+| `provider` + `model` | 空 | 显式路由覆盖;必须**成对**填写(或都留空以跟随当前会话模型) |
+| `temperature` | `0.3` | 低温使改写更忠实于原意 |
+| `maxOutputTokens` | `2048` | 单次增强调用的输出 token 预算 |
+| `maxInputChars` | `12000` | 输入字数上限;超限**拒绝而不截断** |
+| `timeoutMs` | `60000` | 单次调用的端到端超时 |
+| `systemPrompt` | 内置策略 | 想用自己的增强策略时整体替换 |
+| `shortcut` | `ctrl+alt+e` | 快捷键规格(至少一个修饰键 + 单个字母/数字/功能键——纯裸键会被忽略,绝不会吞掉正常打字);留空禁用 |
+| `provider` + `model` 取值 | — | 与 harness 设置一致:设置文件 `llm-pi-ai.providers` 下的键就是 provider(如 `zhipu`、`muyuu`),其 `models[].id` 就是 model(如 `glm-5.3-flash`)。示例:`provider: zhipu` + `model: glm-5.3-flash` |
+
+**模型路由优先级:** 设置成对覆盖 → 当前会话请求头中记录的路由 → 全局默认模型(`agent-default-model`)。三者都指不出路由时(例如全新会话且无默认模型),插件给出可操作的报错而不是乱猜。
+
+## 内置增强策略
+
+默认系统提示词让模型扮演提示词重写专家,按草稿的实际需要施加:
+
+1. **角色与目标** —— 写明助手扮演谁、交付物是什么。
+2. **背景与约束** —— 只补全草稿可推断的信息;绝不编造事实、数据、名称或需求。
+3. **步骤** —— 把模糊或多头需求拆成编号、可执行的步骤。
+4. **输出格式** —— 在有暗示处指明结构、语言、长度与风格。
+5. **验收标准** —— 写明怎样判断结果正确。
+6. **边界条件** —— 列出边界情况与信息缺失时的做法。
+
+硬性规则:精确保留原意(不删除、不篡改、不与用户信息冲突);绝不编造——未知细节插入显式占位符如 `(待补充:…)` / `(TBD: …)`;保持任务范围不变;**只输出**改写后的正文(无解释、无围栏、无客套);镜像输入语言;长度约为原文 1–3 倍;已经成形的提示词只做轻度润色而不注水。
+
+在设置中填写 `systemPrompt` 即可整体替换为你的策略。
+
+## 异常与边界
+
+| 情形 | 行为 |
+|---|---|
+| 空 / 纯空白 / 零宽字符草稿 | 本地拒绝:「输入框为空」 |
+| 草稿超过 `maxInputChars` | 本地与路由双重拒绝并给出精确字数;**不自动截断** |
+| 只附加了图片没有文本 | 拒绝:仅支持文本 |
+| 草稿含命令 / 文件引用块 | 拒绝:回填会破坏引用块 |
+| 提交中 / 占用阶段 / 已有请求在途 | 拒绝并提示「稍后再试」 |
+| 上游模型失败 | 稳定错误码映射为可读提示:`AUTH` → 检查 API Key、`RATE_LIMIT` → 稍后重试、`QUOTA_EXCEEDED` → 检查余额、`CONTEXT_WINDOW_EXCEEDED` → 精简输入、`NO_ADAPTER`/未配置 → 先配置模型 |
+| 输出达到 `maxOutputTokens` | 拒绝并提示调大上限或精简原文 |
+| 模型返回空 / 围栏包裹 / 工具调用 | 规范化(剥围栏)或拒绝;可重试 |
+| 超时 | 映射为 `504` 的提示并给出配置秒数;可重试 |
+| 浏览器中途关闭 | 宿主路由侦测连接断开,立即中止模型调用 |
+| 切换会话 | 面板状态、撤销栈、快捷键目标均按会话隔离;切换即关闭面板并清理撤销记录 |
+
+所有失败只出现在插件自己的面板里;失败的调用绝不修改输入框草稿,手动输入不受任何干扰。
+
+## 安全模型
+
+增强路由由你自己的 dsh 宿主提供服务,**仅限本机访问**:
+
+- **套接字栅栏** —— 非回环地址(`127.0.0.1` / `::1` 之外)的请求一律拒绝。注意这意味着*本机任意进程*都可以调用该路由;路由本身不带用户鉴权。
+- **Host 白名单** —— 路由同时校验 `Host` 头是否为 `localhost` / `127.0.0.1` / `[::1]`,可防御 DNS 重绑定(重绑定的攻击者域名虽然落在回环套接字上,但携带的是攻击者主机名,会被拒绝)。响应均为 `cache-control: no-store`。
+- **不要经反向代理暴露** —— 若把 dsh web 放在监听局域网的代理后面,外部调用者在路由看来就是回环地址,栅栏形同虚设。除非在代理层自行加鉴权,否则不要暴露。
+- **提示注入边界** —— 草稿被框在 `<raw_prompt>` 标签之间,草稿内的字面闭合标签会被中和,策略提示词把框内文本视为纯数据。增强只使用你自己的凭据,结果也只回显给你本人。
+
+## 架构
+
+```
+src/
+├── index.ts            宿主 apply():设置节 + 路由 + 命令
+├── config.ts           schemastery 模式 + 解析校验(成对路由)
+├── prompts.ts          内置策略系统提示词 + <raw_prompt> 框架
+├── enhancer.ts         ctx.llm 辅助调用(路由解析、超时竞速、finish 校验、
+│                       错误码 → 文案映射)
+├── enhance-routes.ts   POST /prompt-enhance/enhance(回环栅栏、限长)
+├── enhance-command.ts  /enhance 斜杠命令(宿主命令注册表)
+├── loopback.ts         路由的 127.0.0.1/::1 栅栏
+├── http.ts             限长 JSON body 读取 / 写出
+├── shared/             传输协议类型、输入校验、输出规范化(两端共用)
+└── client/             浏览器半区
+    ├── index.tsx       插槽注册 + 设置镜像 + 快捷键监听
+    ├── EnhanceButton   conversation.input.right 条目:守卫链 + 调用编排
+    ├── ResultPanel     浮层面板:对比 / 回填 / 复制 / 取消 / 重试
+    ├── UndoBar         conversation.input.dock 条目:恢复入口
+    ├── ui-state.ts     组件共享的外部 store(面板、撤销、会话注册表)
+    ├── enhance-client  fetch 客户端(可中止 + 类型化错误)
+    ├── undo-stack.ts   按会话的 LIFO 栈(深度 3)
+    ├── shortcut.ts     纯函数的组合键解析 / 匹配
+    ├── settings.ts     设置命名空间的客户端镜像
+    ├── locales.ts      中英文字典(harness locale 命名空间)
+    └── styles.ts       自注入样式表(dsh-pe- 前缀类名)
+```
+
+构建产物:`lib/index.js`(宿主半区,ESM,包引用保持外部)与 `lib/client.js`(浏览器半区,打包为 CJS 并包进 dsh web 壳要求的 `window.__ModuleLoader__.load({ id, factory })` 信封)。两者都随仓库提交,因此 GitHub 直装无需构建;CI 会在 `lib/` 与 `src/` 不一致时拒绝合并。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit
+npm test              # 单元 + 真实 HTTP + 组件测试套件
+npm run build         # 类型检查 + 双半区构建
+npm run watch         # esbuild 监听构建双半区
+```
+
+**测试覆盖:** 输入校验(空 / 零宽字符 / 超长)、输出规范化(剥围栏、折行、拒空)、以桩 `ctx.llm` 流驱动的增强器(正常路径、AUTH/NO_ADAPTER/max-tokens 终结、空输出、挂起流失超时、预中止的调用方、路由优先级)、路由的真实 `node:http` 端到端套件(回环栅栏、方法守卫、畸形 body、结构化错误信封、停用开关)、撤销栈、快捷键解析与匹配、配置解析、客户端设置解码器。
+
+**发版流程(维护者):**
+
+```bash
+npm version patch   # 或 minor / major —— 更新 package.json 并打 tag
+npm run build       # 让 lib/ 与 src/ 一致
+git push --follow-tags
+npm publish         # 带 2FA OTP,或使用勾选了 "bypass 2FA" 的细粒度令牌
+```
+
+CI 在每次 push/PR 上运行类型检查 + 测试 + 构建,并在 `lib/` 与已提交构建不一致时拒绝合并。
+
+## FAQ
+
+**为什么草稿里有 `/命令` 或 `@引用` 时被拒绝?**
+回填通过 `inputActions.setDraft` 写纯文本,会破坏引用块。先移除它们,增强后再插回。
+
+**为什么不自动截断超长输入?**
+截断会无声地改变你的原意——插件宁可拒绝并给出精确字数。
+
+**能固定用某个模型吗?**
+在设置中**成对**填写 `provider` 与 `model`(例如 harness 已配置的 provider 路由)。都留空则跟随当前会话模型。
+
+**我的草稿会被发到哪里?**
+浏览器 → 你自己的 dsh 宿主(仅回环路由)→ harness LLM 服务 → 配置的模型服务商。不会发往其他任何地方,增强行为也绝不进入会话的模型历史。
+
+**官方 DeepSeek 路由能用吗?**
+能——调用走 `ctx.llm`,harness 支持的所有 provider(DeepSeek 官方、OpenAI 兼容网关)都可用。
+
+## 致谢
+
+插件结构、回环栅栏与设置节模式遵循 dsh 插件家族的既有惯例——特别是 [`@linxin666/dsh-tool-describe-image`](https://www.npmjs.com/package/@linxin666/dsh-tool-describe-image)。
+
+## 许可证
+
+[Apache-2.0](./LICENSE)