WanchunLian/dsh-draft-polish

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. 进入插件目录（本项目根）：
cd D:\mycode\dsh\dsh-draft-polish

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

3. 确认 profile 的 package.json 已含依赖与 bundle 注册：
// profiles\web\package.json（示例，插件包名会随 link 自动写入 dependencies）
{ "dependencies": { "dsh-draft-polish": "link:..." } }

bundle 注册项（dsh.profile.bundles 追加包名）如缺失，参考同机官方 bundle 写法补齐。

4. 启动 DSH Web：
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