dsh-draft-polish

Readme

# dsh-draft-polish

> DSH（DeepSeek Harness）Web 插件：把输入框里还没发出的口语化草稿，一键润色成更专业、更顺口的表达 —— 默认快路径只出「核心意思」一版，想要其它风格再按需展开。替换回输入框后由你确认再发送。**AI 只帮你把话说到位，绝不替你发言。**

## ✨ 功能特性（轻量化版）

- **轻**：默认只出 **核心意思** 一版（快、省），不再一次拉 8 段；想要其它视角在面板里按需展开、逐条生成。
- **简洁**：compact 560px 面板，主卡一个「用这版替换」主按钮；7 个视角折叠进「更多风格」次级入口，不抢主视觉。
- **多选降级为高级能力**：展开的视角卡可勾「并入」，勾选 ≥2 才浮现「合并 N 版替换」（带 `【视角】` 标题拼接）；平时主路径零干扰。
- **口语清洗**：去掉口头禅、重复、乱序，还原事实主干，不编造用户没说过的事实。
- **替换可反悔**：走官方 `setDraft` 通道，Ctrl+Z 可撤销回原始草稿。
- **绝不阻塞发送**：LLM 挂掉 / 超时 / 拒答时，只提示「可原样发送」，主消息链路零影响。

## 🖱️ 使用流程（小白版，3 步）

1. **写**：在输入框里输入或语音转写一段话（口语化、有口头禅没关系）。
2. **点**：点输入框右侧的「✨ 润色」→ 稍等片刻弹出「润色结果」，默认已给你一版**核心意思**。
3. **换**：看着合适点「用这版替换」→ 回输入框检查、删改 → 点发送。

> 想要别的风格？面板里点「想要其它风格？」→ 挑个视角「生成这版」，同样可「用这版」或勾「并入」后「合并 N 版替换」。
> 不想要任何一版？直接关面板（Esc / 点遮罩），输入框原样保留，不影响发送。

## 📁 目录结构

```
dsh-draft-polish/
├── cordis.yml              # bundle patch（loader entries 挂载）
├── package.json            # dsh.bundle / dsh.client 声明（客户端半边自动发现）
├── lib/
│   ├── index.js            # 宿主半边：fenced 路由 + payload 白名单（/draft-polish/api/*）
│   ├── polish-core.js      # 润色编排器（单视角生成 / 全量 8 段兼容 / 解析）
│   ├── prompts.js          # 8 套角色模板 + 公共系统提示词（纯数据）
│   └── client.js           # 浏览器半边：compact 面板 + 草稿快照锁定 + 回填
├── test/
│   └── polish-core.test.mjs# P0 回归：上下文红线 / 白名单 / 边界（node:test，npm test）
├── docs/design.md          # 完整架构设计文档（含 M0–M4 实测记录）
└── README.md               # 本文档
```

## 🔧 安装部署（技术版）

### 前置要求

- Node.js 20+（实测 v22.22.2 ✅）
- `@deepseek-ai/dsh`（0.1.1-rc.2，`npx @deepseek-ai/dsh web` 可启动）
- DSH profile 目录（Windows 默认 `C:\Users\<你>\.dsh\profiles\web`）

### 步骤

1. **进入插件目录**（本项目根）：
   ```powershell
   cd D:\mycode\dsh\dsh-draft-polish
   ```

2. **以 link: 协议装进 profile**（实时生效，改代码无需重装）：
   ```powershell
   cd C:\Users\wanch\.dsh\profiles\web
   npm install link:D:\mycode\dsh\dsh-draft-polish
   ```

3. **确认 profile 的 package.json** 已含依赖与 bundle 注册：
   ```jsonc
   // profiles\web\package.json（示例，插件包名会随 link 自动写入 dependencies）
   { "dependencies": { "dsh-draft-polish": "link:..." } }
   ```
   bundle 注册项（`dsh.profile.bundles` 追加包名）如缺失，参考同机官方 bundle 写法补齐。

4. **启动 DSH Web**：
   ```powershell
   npx @deepseek-ai/dsh web
   ```
   浏览器打开 `http://127.0.0.1:3456`，输入框工具行右侧即出现「✨ 润色」按钮。

> ⚠️ 若改动 `cordis.yml` / `package.json` 的 bundle 声明，需重启 dsh web 生效；仅改 `lib/*.js` 无需重启（link 实时）。

## 🔌 宿主路由契约（浏览器半边经同源 fetch 调用，宿主侧 fenced）

| 方法/路径 | 入参 | 出参（成功） | 说明 |
|---|---|---|---|
| `POST /draft-polish/api/polish/one` | `{ draft, roleId, timeoutMs? }` | `{ ok:true, value:{ roleId, text } }` | **前端默认路径**：单视角生成（core=核心意思快路径，其余按需） |
| `POST /draft-polish/api/polish` | `{ draft, timeoutMs? }` | `{ ok:true, value:{ requestId, core, roles } }` | 全量润色，单次生成 8 段（保留兼容，前端默认不再用） |

- 失败统一信封：`{ ok:false, error:{ code, message } }`
- **Payload 白名单（上下文红线）**：两个路由只接受上表列出的字段；夹带 `sessionId` / `conversation` / `history` 等任何会话上下文字段 → 一律 `400 UNEXPECTED_FIELD`（见 `lib/index.js` 的 `assertOnlyKeys`）。
- 安全：路由带 DNS-rebinding / CSRF fence（Host 必须 loopback 或受信 + Origin 同源），浏览器进程不直连 `ctx.llm`。

## 🔒 隐私边界（你关心的那条线，已锁死）

- **只发草稿快照**：浏览器半边在【点击按钮那一刻】锁定草稿快照（`lockedRef`），面板开着期间你继续输入的内容、正在进行的对话、历史消息，**一律不会出现在任何 LLM 请求里**——面板里的「更多风格」逐条生成同样只用这份快照。
- **不夹带会话**：请求体只有 `{ draft, roleId }`，宿主侧白名单强制校验（见上）。
- **不泄露正文日志**：宿主侧不打草稿正文日志；本地 profile 数据由 DSH 官方机制管理。
- **回归测试兜底**：`npm test` 的用例锁死「messages 只含 1 条 user = 草稿」与「多余字段 400」，防止未来改动把上下文拼回去。

## 🛡️ 降级行为（设计铁律：润色失败绝不阻塞发送）

| 场景 | 用户看到 | 影响 |
|---|---|---|
| LLM 全挂 / 全超时 | toast「润色暂时不可用，可原样发送」 | 输入框原样保留，可直接发送 |
| 展开的某视角生成失败 | 该卡「生成失败，可重试或忽略」 | 点重试；或关面板不影响发送 |
| 内容过长（>2000 字） | 接口报 `DRAFT_TOO_LONG`「内容过长，请精简后再试」 | 明确可行动 |
| 内容安全拒答 | 该视角生成失败，可重试 | 可原样发送 |
| 发送中（submitting/adjudicating） | 按钮置灰「正在发送中，稍后再试」 | 防误触 |

## ⚙️ 可调参数（lib/polish-core.js）

| 常量 | 默认 | 说明 |
|---|---|---|
| `DEFAULT_TIMEOUT_MS` | 30000 | 单次 LLM 生成超时（实测真模型单次约 15–24s） |
| `MAX_DRAFT_CHARS` | 2000 | 草稿长度上限，超出报错不静默截断 |
| 生成策略（客户端） | 默认单视角（`/polish/one`, core） | 只出核心意思 1 版；其余按需展开逐条生成，避免一次 8 段长等待 |

## ✅ 测试与验收记录

| 里程碑 | 内容 | 结果 |
|---|---|---|
| M0 Spike | `dsh web` 拉起；`conversation.input.right` 插槽实证存在 | ✅ |
| M1 骨架 | 按钮注册：空草稿置灰 / 输入亮起 / 点击读到草稿 | ✅ Playwright 实测 |
| M2 润色链路 | 宿主路由 + 真模型单次出 8 段（24.3s）、单视角（15.7s）质量合格 | ✅ 真模型实测 |
| M3 UI 闭环 | 面板 8 卡、用这版替换、Ctrl+Z 撤销 | ✅ Playwright 实测 |
| 多选（方案 A） | 勾选 3 版 → `【视角】` 拼接替换；全选/清空；N=0 置灰 | ✅ Playwright 实测 |
| M4 降级演练 | LLM 全挂 toast「可原样发送」+ 草稿保留；单视角缺失 2 卡 → 重试补齐 1 卡 | ✅ Playwright 实测（mock 快测） |
| **V2 轻量化（2026-09-04）** | 默认单段快路径 + compact 面板 + 快照锁定 + payload 白名单 + `npm test` 9/9 绿 | ✅ 单测通过；真机 UI 待 Playwright 复测 |

**缺陷记录**：
- 多选默认勾选曾因数组多包一层（`[defs]` 嵌套）导致永不勾选，已修复并复测（见 docs/design.md 第 17 节）。
- V2 修复的真实泄漏隐患：旧版面板打开后的「重试」读的是**实时**输入框内容——用户面板开着继续打字，重试会把新输入带进请求。已改为快照锁定（见上「隐私边界」）。

## 🧑‍💻 开发说明

- 浏览器半边与宿主半边分离：UI 只做展示与回填，LLM 能力全部收口宿主路由（`lib/index.js`），DSH rc 版 API 演进只改宿主一处。
- 角色模板为纯数据（`lib/prompts.js`），与代码解耦，可热调措辞。
- 插件随 `ctx` 生命周期自动清理（路由经 `ctx.effect` 注册），卸载无残留。

## 📄 License

MIT