dsh-prompt-polisher

Readme

# DSH Prompt Polisher

在 DeepSeek Harness（DSH）输入框的发送按钮前增加一个原生「润色」按钮。它使用当前会话已经选择的 DSH 模型优化提示词，先展示结果，再由用户决定应用；请求期间输入发生变化时不会静默覆盖。

> 当前版本面向 DSH `0.1.0-rc.7`。DSH 官方仍将项目标记为 developer preview，后续 rc 版本可能包含破坏性变化。

## 功能

- 官方 `conversation.input.right` slot 中的清晰按钮；
- 复用当前 session 的 provider、model 和 reasoning effort，不重复配置 API key；
- 加载、取消、结果预览、失败重试、应用、复制和恢复原文；
- `draft + draftRev` 冲突检测，请求期间继续输入也不会被覆盖；
- 每会话独立 controller、AbortSignal 和 generation guard，避免陈旧响应跨会话写回；
- 默认只发送当前草稿；可选、受限的最近对话上下文；
- 中英文界面、键盘可访问、主题 token 和 reduced-motion 支持。

## 功能展示

使用流程：

1. 在 DSH 输入框写下提示词；
2. 点击发送按钮前的「润色」；按钮进入可取消的加载状态；
3. 输入框上方展示润色结果，原文仍保留；
4. 点击「应用」写回输入框，或复制/关闭；
5. 应用后可点「恢复原文」。若原文或结果已经被继续编辑，插件会停止自动替换并显示警告。

```text
输入框草稿 ──润色──> 结果预览 ──应用──> 输入框
     │                   │                │
     └─ 始终保留原文      └─ 冲突时不覆盖   └─ 可恢复原文
```

实机加载态截图见 [`docs/demo.png`](docs/demo.png)（在 release 验收中由 DSH rc.7 Web 运行实例生成，不含凭据或模拟的模型输出）。

## 安装

要求：Node.js `>=22.19.0`、DSH `0.1.0-rc.7`，并已在 DSH 中配置至少一个可用模型。

推荐固定 release tag：

```sh
dsh plugin --profile web add github:SiYue-ZO/dsh-prompt-polisher#v0.1.0
dsh --profile web --dump-config
dsh --profile web
```

Git 安装会在本机执行本项目的 `prepare` 构建。pnpm 10+ 若拒绝构建，请先审查源码，然后在该 profile 的 `pnpm-workspace.yaml` 添加：

```yaml
allowBuilds:
  dsh-prompt-polisher: true
```

再重试 `dsh plugin ... add`。这项许可意味着允许依赖执行本机代码；在生产环境建议将 `#v0.1.0` 换成审核过的 commit SHA。

本地开发安装：

```sh
git clone https://github.com/SiYue-ZO/dsh-prompt-polisher.git
cd dsh-prompt-polisher
npm ci
npm run check
dsh plugin --profile polish-dev add .
dsh --profile polish-dev --dump-config
dsh --profile polish-dev
```

升级/卸载：

```sh
dsh plugin --profile web remove dsh-prompt-polisher
dsh plugin --profile web add github:SiYue-ZO/dsh-prompt-polisher#v0.1.0

dsh plugin --profile web remove dsh-prompt-polisher
```

## 配置

安装后的 bundle 默认配置位于 `cordis.patch.yml`。如需覆盖，请在 profile 自己的 `cordis.patch.yml` 中按相同 row id `prompt-polisher` 提供完整 `config`（DSH 的后层 config 是整体替换，不是深合并）。

| 字段 | 默认值 | 说明 |
| --- | ---: | --- |
| `maxInputChars` | `20000` | 当前草稿字符上限；超限直接拒绝 |
| `maxOutputChars` | `30000` | 结果字符上限；超限不进入预览 |
| `maxOutputTokens` | `2048` | 辅助 LLM 输出 token 上限；截断结果视为失败 |
| `timeoutMs` | `60000` | 整轮请求超时 |
| `includeContext` | `false` | 是否发送受限的最近对话纯文本 |
| `contextMessages` | `6` | 最多上下文消息数，仅在上项开启时生效 |
| `contextMaxChars` | `8000` | 上下文总字符预算 |
| `customInstructions` | `''` | 部署级润色偏好，不应放密钥 |

完整覆盖示例：

```yaml
- patch:
    id: prompt-polisher
    config:
      maxInputChars: 20000
      maxOutputChars: 30000
      maxOutputTokens: 2048
      timeoutMs: 60000
      includeContext: false
      contextMessages: 6
      contextMaxChars: 8000
      customInstructions: '优先把验收标准整理为清晰列表。'
```

本插件不接收或存储 API key。模型凭据、endpoint 和计费仍由 DSH adapter 配置决定。

## 使用方法

- 空草稿或 DSH 输入状态不是 `plain` 时，按钮禁用。
- 点击「润色」后可以继续编辑，也可再次点击按钮/面板中的「取消」。
- 正常返回只进入预览，不自动写入。
- 若草稿未变化，「应用」写回结果；若草稿变化，按钮明确改为「仍然替换」。
- 「恢复原文」只在当前草稿仍等于刚应用结果、且 revision 未变化时可用，防止 ABA 编辑覆盖；原文也可单独复制。
- 失败面板保留原文，支持重试或关闭。

## 隐私与安全

点击按钮时才会发起请求。默认发送：当前草稿、session id、当前模型 route；草稿只进入 DSH Host 的一次性辅助 LLM 调用，不写入正常聊天 transcript，插件也不记录正文。最终数据会发送给当前 DSH 模型 adapter 所连接的服务商。

`includeContext: false` 是隐私默认值。开启后只提取最近的人类/模型纯文本；插件排除工具结果、图片、插件上下文和推理块，并同时受消息数/字符数限制。系统指令与草稿使用 JSON 数据边界分离，但任何发往模型的内容仍应视为已披露给模型服务商。

## 架构

```text
src/index.ts                    Host 生命周期、配置和 Typert manifest
src/runtime.ts / polish.ts      Remote 服务与一次性 ctx.llm.stream 调用
src/prompt.ts                   上下文最小化、system prompt、JSON framing
src/contract.ts                 Host/Client 共用的 zod 严格 wire codec
src/client/index.ts             slot、locale、Remote、每 session controller
src/client/controller.ts        可取消状态机、generation 与 CAS 规则
src/client/PromptPolish*.tsx    按钮和全宽预览面板
tests/                          合同、提示词边界、竞态与恢复测试
```

数据流：Client 从公开 `useInput` 读取草稿，经 `session.models` 捕获本次 route，通过严格 Typert Remote 调用 Host；Host 以 `createUserMessage`、`ctx.llm.stream` 和 `BlockAssembler` 完成辅助请求，检查 finish/工具调用/空结果/边界后返回；Client 只在明确操作时调用公开 `inputActions.setDraft()`。

详细调研和一手链接见 [docs/dsh-research.md](docs/dsh-research.md)。

## 开发指南

```sh
npm ci --ignore-scripts
npm run lint
npm run typecheck
npm test
npm run build
npm run pack:check
```

`npm run check` 顺序执行 lint、类型检查、12 项单元测试和生产构建。构建输出：

- `lib/index.js`：Node/Host ESM bundle；
- `lib/client.js`：由 DSH ModuleLoader 加载的浏览器 bundle；
- `lib/types/`：公开声明文件。

新增“扩写、压缩、翻译”等能力时，建议把处理器 id/配置扩展到 `contract.ts`，在 `prompt.ts` 提供独立策略，而复用 controller 的取消、冲突和恢复语义。不要在组件中增加 DOM selector 或直接改 textarea。

## 验证

发布前验收：

- Node.js 24 / Windows 11；
- DSH `0.1.0-rc.7`；
- `npm run check` 全通过；
- `npm run pack:check` 只包含声明的发布文件；
- 本地 profile 安装、`--dump-config`、Web 启动；
- 实际按钮渲染、加载面板、Client → Host Remote 请求与失败/重试路径；
- 自动化覆盖成功预览、应用、冲突、强制应用、恢复、取消、陈旧响应与竞态。

可复现的详细结果见 [docs/verification.md](docs/verification.md)。真实 Provider 成功调用需要用户自己的 DSH 凭据，仓库和 CI 均不保存凭据。

## 常见问题

### 按钮没有出现

确认使用 DSH Web、版本为 rc.7、`--dump-config` 中存在 `prompt-polisher` row，并重启 profile。CLI/Headless 不加载 Web Client slot。

### 提示模型不可用

插件使用当前 session 下一轮选中的模型。先在 DSH 模型选择器中选一个已配置凭据且 adapter 正在运行的 route。

### 请求失败或超时

检查 DSH 模型 adapter 的凭据、endpoint、限流和网络。面板错误不会改写原文；可以重试。超时可调 `timeoutMs`，但不要用无限值。

### 为什么没有自动应用？

这是防误覆盖设计。结果先预览；输入变化时必须明确点「仍然替换」。

### 为什么无法恢复原文？

应用后内容又被编辑时，自动恢复会覆盖新输入，因此插件禁用恢复。原文仍保存在当前面板状态中，可点击「复制原文」取回。

### 润色会出现在聊天记录里吗？

不会。它使用 Host 的辅助 LLM 调用，而不是向 session 提交一轮普通 prompt。模型服务商仍会收到本次调用内容。

### 能在未来 DSH 版本使用吗？

不作保证。DSH 仍处于 developer preview；升级后请先运行 CI、安装 smoke test 和 UI 验收。

## License

[MIT](LICENSE)