提示词修改助手 wnei-f/dsh-prompt-dock

dsh-prompt-dock（提示词修改助手）

DSH 插件，挂在输入框工具行（conversation.input.right，模型选择左侧），对输入框草稿做两件事：

- AI 改写：更简洁 / 更详细 / 结构化 / 译成英文 / 自定义；SSE 流式输出、可取消、写入后可撤销
- 模板插入：常用提示词模板一键追加到草稿

改写结果为 AI 辅助生成，请自行核实内容。

工具行从左到右是「风格 / 模板 / 改写」三个独立控件：风格与模板各自是一级触发器、互不嵌套；「改写」是本插件这一行最靠右的控件，紧邻官方模型选择器。设置已从工具行移入 DSH 官方「插件」页。下拉箭头、选中态、开关沿用官方主题令牌，选中项用底色 + 细阴影描边而不是打勾。「改写」为纯图标（官方 sparkle 形状，文案在 tooltip），进行中显示转圈 + 已接收字符数，完成后同一槽位变成「↩ 撤销」。

模型默认走 DSH 全局默认模型（agentDefaultModel），也可在插件配置里固定为某个模型；改写在宿主半调用 ctx.llm.stream。

目录

- 界面交互
- 设置
- 提示词设计
- 隐私与版权
- 安全与边界
- 兼容性
- 路由与错误码
- 安装
- 开发

界面交互

工具行三级降级

按可用宽度自动切换布局，避免在窄容器里挤压官方控件：

| 层级 | 条件 | 布局 |
| L0 完整 | 宽度 > compactThreshold（默认 320px） | 风格 / 模板 / 改写三个独立控件 |
| L1 紧凑 | 宽度 ≤ 阈值 | 风格与模板只显示图标 + tooltip |
| L2 合并 | 宽度 < 阈值 × 0.75 | 回退为单一两级菜单 |

若配置里把 showStyleEntry 或 showTemplateEntry 设为 never，直接进入 L2。

快捷键

默认 Alt+M 打开风格、Alt+T 打开模板、Alt+R 改写，可在插件配置的「快捷键」分组修改。

输入框里也能用：带 Alt / Ctrl / Cmd 的组合键即使焦点在输入框中也会触发；单独按字符键仍交还给输入框，不会吞掉正在打的字。

修改方式：点击设置里的快捷键输入框 → 直接按下想要的组合键，自动录入为规范格式（如 Alt+J），不需要手打字符串。

| 操作 | 行为 |
| Esc | 放弃本次录入 |
| Backspace / Delete | 清空该绑定 |
| 只按修饰键 | 继续等待，不提交 |
| 未包含修饰键 | 拒绝提交并提示 |

浮层键盘导航

浮层打开时焦点仍在输入框，因此插件在 document 捕获阶段接管方向键：

| 按键 | 行为 |
| ↑ / ↓ | 逐项切换高亮（实时跟随，首尾不越界，连按不丢步） |
| Home / End | 跳到第一项 / 最后一项 |
| Enter | 选中当前项，不会发送输入框内容 |
| Esc | 关闭浮层并把焦点交还触发器 |

当前键盘项用品牌色内描边标出（.pd-optionActive），与「已选中的风格」（底色 + 细描边）是两个不同的视觉状态，可以同时出现。中文输入法组合中（isComposing）不拦截回车，避免与候选词确认冲突。

风格 / 模板互相切换

两个浮层共用一套快捷键，可以互相直接切换，不需要先关闭：

| 当前状态 | 按下 | 结果 |
| 浮层关闭 | Alt+M / Alt+T | 打开对应浮层 |
| 风格开着 | Alt+T | 直接切到模板 |
| 模板开着 | Alt+M | 直接切到风格 |
| 风格开着 | Alt+M | 关闭（原有 toggle 语义） |
| 模板开着 | Alt+T | 关闭（原有 toggle 语义） |
| 浮层开着 | Alt+R | 拦下，避免误触发改写 |

反馈

改写走一个六态状态机，所有提示由同一套组件渲染：

| 状态 | 表现 |
| idle | sparkle 图标 + 主按钮填充 |
| requesting | 转圈，按钮禁用，tooltip「正在连接…」 |
| streaming | 转圈 + 「改写中 N 字」，输入框上缘 2px 流光条 |
| success | 同槽位变成「↩ 撤销」，1.5s 绿色高亮，toast「改写完成，可撤销」 |
| error | 恢复 sparkle，1px 危险色描边，左侧错误条 + 重试 |
| cancelled | 回到 idle |

六类错误各有固定文案，不展示原始错误文本：网络失败、超时、认证/配置、模型返回错误、空结果、用户取消。错误日志只记录类型与耗时，原始信息写入浏览器控制台。

提示显示位置：错误提示、长度提示、芯片说明统一显示在工具行左侧（绝对定位的旁注槽位），出现和消失都不会挪动「风格 / 模板 / 改写」三个按钮。同一时刻只显示一条，优先级：错误 > 长度提示 > 芯片说明。窄视口（< 640px）左侧放不下时自动改挂到工具行下方，仍不影响按钮位置。

Toast 位于底部居中，最多 2 条，2.8s 自动消失，尊重 prefers-reduced-motion。

设置卡片

- 风格库 / 模板库默认折叠：每条只显示「名称 + 摘要」，点击标题栏才展开编辑，避免一屏塞满输入框。
- 上下文开关旁显示「已开启 / 已关闭」文字，下方说明随状态变化，不只依赖滑块颜色。
- 加载态：配置尚未读到时显示「正在读取配置…」；读取失败则显示原因 + 重试，不会渲染成空白卡片。
- 首次使用告知：首次点击「改写」时提示「点击改写会将当前草稿发送至你配置的模型」，关闭后不再出现。

设置

设置不走插件自己的 JSON 文件，而是用 DSH 官方的插件配置：

- 入口：侧栏 插件 → 找到 dsh-prompt-dock → 打开它的页面，配置区在页面里（plugins.bundle.config 插槽，以包名 dsh-prompt-dock 为 key）。
- 存储：写入当前 profile 的 cordis.patch.yml，由 DSH 的 configEditor 管理，插件本身不直接读写该文件。
- 生效：每个字段都是 Config 的 .volatile() 字段，保存后无需重启，改写行为立即变化。

配置分组

| 分组 | 内容 |
| 改写模型 | 跟随全局默认，或固定为某个 provider/model（同名模型按 provider 区分显示） |
| 上下文 | 是否附带最近对话、附带轮数（1–20） |
| 全局改写纪律 | system prompt 的共同纪律；默认只读，可解锁编辑，也可一键恢复默认 |
| 风格库 | 每个风格的 name / instruction 可编辑 |
| 模板库 | 每条模板的 text / category / tags 可编辑，可增删 |
| 工具行 | showStyleEntry / showTemplateEntry（auto / always / never）、compactThreshold |
| 快捷键 | 三个快捷键，点击后直接按组合键录入 |

配置字段

对应 cordis.patch.yml 里 dsh-prompt-dock 行的 config：

- id: dsh-prompt-dock
name: dsh-prompt-dock
config:
rewriteProvider: deepseek-official # 空串 = 跟随全局默认 rewriteModel: deepseek-chat # 空串 = 跟随全局默认 timeoutMs: 90000 # 5000–300000 useContext: true contextRounds: 6 # 1–20 globalDiscipline: "" # 空串 = 用内置默认
styles: { concise: { name: 更简洁, instruction: "……" } }
templates: { t-review: { name: 代码审查, text: "……", category: 代码, tags: [review] } }
showStyleEntry: auto # auto | always | never
showTemplateEntry: auto
compactThreshold: 320 # 160–1200
shortcutStyle: Alt+M
shortcutTemplate: Alt+T
shortcutRewrite: Alt+R

字段约束：模板 ≤ 100 条，name ≤ 60 字、text ≤ 4000 字；风格 name ≤ 40 字、instruction ≤ 2000 字；共同纪律 ≤ 4000 字。超限在保存时截断。

从旧版迁移

旧版把设置放在 ~/.dsh/prompt-dock/settings.json。升级后首次启动会自动：

1. 读取旧文件，转换成官方配置字段；
2. 只回填官方配置里尚未由用户设置过的字段（已设过的值不会被旧文件覆盖）；
3. 把旧文件原子改名为 settings.json.migrated，此后不再读写（超过 30 天自动清理）。

回填以 settings.describe() 返回的 user 层区分「用户设过」与「用了默认值」，因此重复启动是幂等的。

提示词设计

改写分两条互不相干的链路：

- 共同纪律 + 风格 instruction → 改写请求的 system prompt（纪律在前，风格在后）
- 模板 text → 直接插入输入框的正文，不进 system prompt

共同纪律（system prompt 主体）

内置默认文案的核心是「改写器不是需求生成器」：只让草稿更可用，不新增草稿里没有的事实、数据、案例或结论。改写前先做性质判断：

- 草稿若是确认、道谢、闲聊、简单提问或纯情绪表达 → 原样返回或只修正明显语病，不按任何风格扩写
- 草稿若是可执行的任务请求 → 再按风格约束改写

六条共同约定：

1. 只输出改写后的正文，不输出解释、前言、问候、改写说明
2. 逐字保留：反引号内代码、文件路径、命令行参数、函数/变量/类名、URL、@引用、/命令、Markdown 结构
3. 逐字保留：专有名词、规范术语、直接引语中的措辞、具体数字与版本号
4. 不把用户的观察改写成结论（「我觉得它有点慢」不得变成「它性能不足」）
5. 不替用户做草稿未做的决定；不确定处保留原表述
6. 控制长度：不低于 80 字；超限先收敛，仍超则保持原样并提示

第 6 条是软约束：代码层不自动截断，而是在预览区加琥珀色提示。纪律在设置里默认只读，可解锁编辑，也可一键「恢复默认」（存为空串，后续版本改进默认文案会自动生效）。

四个风格 instruction

| 风格 | 实际约束 |
| 更简洁 | 删重复、修饰、客套；必须原样保留全部约束与否定条件、失败路径与异常处理要求、数字与阈值、文件/接口/字段名、验收标准；不得把含义不同的两句合并、不得把并列要求压成一个；目标 50%–70% 且不低于 80 字 |
| 更详细 | 只补草稿已隐含的目标、输入、输出、边界、验证方式；禁止引入未提及的技术选型、第三方库、数据结构或数据；判断强度不变；目标 1.5–2.5 倍且不超过 800 字，草稿不足三行时按内容补全，不做比例扩写 |
| 结构化 | 固定章节序：目标 / 上下文 / 任务步骤 / 约束 / 输出格式；缺失章节写「未指定」，不要编造；步骤以动词开头按序排列；标识符、路径、数字保留原形；只重组，不新增需求 |
| 译成英文 | 地道英文技术写作；逐字保留代码、路径、命令行参数、标识符、URL、术语、直接引语、数字与版本号；保留 Markdown 与 @引用 /命令；保持判断强度，不扩写、不解释、不补充建议；无公认译法时保留原文并括号注明 |

「自定义」风格的 instruction 为空串，改写时读取该风格自身的 instruction（在设置卡片「风格库」里编辑）；若该指令为空且请求未提供一次性覆盖，报 NO_INSTRUCTION。

三个模板 text

三个模板统一遵循「任务 + 禁止项 + 兜底」结构——先说做什么，再说不能做什么，最后规定信息不足或没有发现时怎么办，避免模型硬凑内容。

| 模板 | 任务 | 禁止项 | 兜底 |
| 代码审查 | 按严重程度降序，每条给「位置 / 问题类型 / 触发条件 / 最小修复方向」 | 只报能定位的问题；不假设未展示代码有问题；不评价命名与格式偏好 | 无问题则输出「未发现可定位问题」，并列未覆盖部分 |
| 解释代码 | 依次说明：整体职责、数据流、边界与失败路径、对调用方的约束 | 标识符、路径、数字不意译；不评价好坏、不提改进建议 | 无法确认处标「未验证」，不推测 |
| 写测试 | 每个用例给「名称 / 输入 / 预期结果 / 覆盖路径」 | 不修改被测代码、不改签名、不重命名、不引入新测试框架、不 mock 被测逻辑本身 | 无法确定预期行为时列为待确认问题，不编造断言 |

以上都是默认值。在插件配置里保存过风格或模板后，config 中的值会覆盖内置默认。

隐私与版权

- 草稿不落日志、不落磁盘：草稿原文只用于当次改写调用，从不写入日志、探针文件或任何持久化文件。错误日志只记录错误类型、耗时与字符数。开发期探针接口在写盘前会剔除 draft / text / content 等草稿字段，仅保留字符数。
- 不接触凭据：插件不读取任何 API Key，模型凭据由宿主 llm 服务持有；配置里也不保存凭据。
- 无外网出口：改写不直接发起网络请求，而是走宿主 llm 服务；插件自身没有明文 HTTP 出口，也不提供可降级到 http 的配置项。
- AI 辅助告知：首次点击「改写」时提示草稿会发送到你配置的模型，关闭后不再出现。
- 许可证：MIT，覆盖插件代码、内置模板正文与风格指令，见 LICENSE。

安全与边界

- 回环围栏：所有 /api/prompt-dock/ 只接受本机来源（校验 socket 地址、Host、Origin，并拒绝带 X-Forwarded-For / Forwarded 的请求）。.localhost 与非 http(s) 的自定义 scheme（桌面壳 app://、tauri://、file://）放行，http(s) 必须是回环。不要把 dsh web 暴露在反向代理后还指望这道围栏生效。
- 改写限流：同一宿主进程内并发改写上限 2，每分钟成功调用上限 10（失败调用不占配额）。
- 芯片保护：草稿含 @文件 / /命令 引用芯片时，「改写」置灰并提示。判据取自宿主真实发布状态——InputState.occurrences 非空即视为含芯片。
- 变更检测：改写期间若草稿被改动，结果不会回填，避免覆盖新输入。
- 只走 inputActions.setDraft：不猜测其它方法名。宿主不支持时显式报错，而不是静默换一条未知路径。

权限清单（与 package.json 的 dsh.permissions 一致）

| 能力 | 声明值 | 实际用途 |
| network.fetch / network.socket | false / false | 不发起任何外部网络请求；改写经宿主 llm 服务 |
| process.child_process | true | 仅「打开配置文件」：调用系统文件管理器（explorer.exe / open / xdg-open）定位当前 profile 的 cordis.patch.yml |
| filesystem.read / fs.write | $DSH_HOME/prompt-dock | 仅旧配置目录：读取一次旧 settings.json 做回填、改名为 .migrated、清理 30 天前过期文件。官方设置由 DSH 官方 configEditor 写入 |
| env.read | DSH_HOME、DSH_PROMPT_DOCK_DISABLE_OPEN | 前者定位旧配置目录；后者为 1 时不弹文件管理器（无头环境）。不读取任何凭据类环境变量 |

与宿主 API 的对应关系（已核对 dsh 0.2.1-rc.2 运行时）

| 宿主事实 | 本插件的处理 |
| SessionInputShell.compose() 发布 { draft: projection.clipboardText, draftRev, phase, occurrences, ... } | pickDraftText 读 draft；chipFromState 读 occurrences |
| inputActions.setDraft(text) 是单参数，内部 text.replace(REFERENCE_PLACEHOLDER_RE, "") 并重建段落 | 回填只调用 setDraft(text)；含芯片时直接禁用改写 |
| 芯片占位符为 [\uE100-\uE11D\uFFFC]，setDraft 会清掉它们 | detectChip 额外检测这些字符作为兜底 |
| 设置表单只接受 volatile 字段：settings.mutate(ns, ops) 校验路径后经 configEditor.edit() 写 YAML | 所有可编辑项都声明为 Config 的 .volatile() 字段；写入走 settings.mutate |
| volatile 字段只有 .get()，值由 Loader 从 cordis.patch.yml 重新解析产生 | 插件不在内存里改配置；回填与保存都写存储，读时重新取 |
| plugins.bundle.config 是以包名为 key 的 keyed slot，只在组合包详情页以 view: 'page' 渲染 | 配置卡片注册为 key: "dsh-prompt-dock" |

说明：早期设计文档提到的 settings.plugin.item / installSection / SettingsScope 在 DSH 0.2.1-rc.2 中不存在，本插件按上述真实 API 实现。

兼容性

- dsh >=0.2.0-rc.2 <0.3.0 || >=0.2.1-0 <0.3.0（已在 0.2.1-rc.2 上核对 API 与行为；区间用并集是因为 semver 的预发布门控要求同 major.minor.patch 的比较器）。
- 宿主未提供 inputActions.setDraft 时，改写会明确报「当前宿主不支持改写回填」。
- 宿主未提供 settings 服务时，配置保存会明确失败（SAVE_FAILED），不会假装成功。

路由与错误码

| 路由 | 说明 |
| GET/POST /api/prompt-dock/config | 读取（规范化后的）设置；POST 接受部分字段补丁，未提交的字段保持现值 |
| GET /api/prompt-dock/models | 模型目录 + 全局默认 |
| POST /api/prompt-dock/open-config | 在文件管理器中定位 profile 的 cordis.patch.yml |
| POST /api/prompt-dock/rewrite | {text, styleId, customInstruction?, sessionId, useContext} → {ok, text} |
| POST /api/prompt-dock/rewrite-stream | 同上，text/event-stream：meta / delta / done / error；meta 带 draftChars 与 timeoutMs |
| POST /api/prompt-dock/cancel | {requestId} 中断进行中的流式改写 |
| POST /api/prompt-dock/probe | 开发期探针（~/.dsh/prompt-dock/probe.json，写入前剔除草稿原文） |

错误码：AUTH / RATE_LIMIT（含 retryAfter）/ CONCURRENCY_LIMIT / QUOTA / CONTEXT_WINDOW / TIMEOUT / EMPTY_TEXT / TEXT_OVER / NO_INSTRUCTION / NO_MODEL / NO_LLM / LLM_FAILED / EMPTY_REPLY / BAD_JSON / BODY_OVER_SIZE / METHOD / SAVE_FAILED / NO_DOCUMENT。

安装

从 GitHub 安装（lib/ 为已提交产物，无需本地构建）：

dsh plugin --profile web add github:wnei-f/dsh-prompt-dock
重启 dsh web 后生效

从本地目录安装（开发迭代用）：

dsh plugin install <本目录绝对路径>

也可以在 GUI 插件管理里安装。改完代码必须重启 DSH：客户端 bundle 的 rev 由宿主进程按文件元数据计算并注入页面，只刷新页面拿不到新代码。

开发

npm test # 宿主路由/迁移/隐私 + 客户端纯逻辑 + 组件挂载

测试只用 Node 内置模块，但宿主半依赖 DSH 自带的 @deepseek-ai/schemastery（Config schema 是官方设置表单读取 volatile 字段的唯一接口），因此它是 peerDependencies，不随包发布拷贝。

npm test 之前会自动运行 scripts/link-dsh-deps.mjs，在 ~/.dsh/profiles/*/node_modules 里找到 DSH 安装后，把 schemastery / cosmokit 软链进本仓库的 node_modules（不复制）。找不到时会打印提示但不中断，此时手动指定：

DSH_NODE_MODULES=/path/to/node_modules npm test

Node 版本要求见 package.json 的 engines。

标识

| 项目 | 值 |
| GitHub topic | dsh-plugin（插件市场按此 topic 自动收录） |
| 兼容 DSH | 0.2.x（已在 0.2.1-rc.2 上核对） |
| 许可证 | MIT |
| 挂载插槽 | conversation.input.right（工具行）、plugins.bundle.config（配置卡片，key = dsh-prompt-dock） |
| 仓库 | https://github.com/wnei-f/dsh-prompt-dock |