@studyzy/dsh-suggest-prompt

dsh plugin --profile web add @studyzy/dsh-suggest-prompt

dsh-suggest-prompt



为 DeepSeek Harness 开发的「建议提示词」插件：每个 agent 回合完成后，通过一次有界的辅助 LLM 调用，在插件自己的持久化存储中写入一条建议的下一条提示词；Web 端把它渲染成输入框内部的浅色幽灵占位文字，按 Tab（默认）即可采纳进草稿（与 Claude Code 一致）。

想快速上手？直接看 [使用说明](USAGE.zh.md)（面向终端用户的操作指南）。

[Read this in English](#dsh-suggest-prompt-1) · 中文文档

对于开发者 / 维护者：本仓库是单个 bundle 包（@studyzy/dsh-suggest-prompt）的权威源码，把宿主生成与浏览器渲染合并为一个可一键安装的 bundle：

包 · 作用

[@studyzy/dsh-suggest-prompt](.) · 宿主插件（., ./invariant, ./types）：在 turn/end（reason=completed）时生成建议，发布 suggestPrompt 会话投影。浏览器插件（./client）：读取投影，渲染为输入框内部的浅色幽灵占位文字（inputActions.setDraft），按配置的快捷键填入草稿。

特性

一个自动「接话」助手：AI 答完后，它替你预测下一句该说什么——既省去反复输入，又不会打断你的思路。

• 默认轻量：不配置 provider / model 时继承主请求最近一次记录的路由，无需为建议单独选模型；需要时也可显式指定任意路由（例如本地 OpenAI 兼容网关）。
• 免思考、快速便宜：建议生成默认携带 reasoningEffort: off（DeepSeek 序列化为 thinking: disabled），不消耗推理预算；模型不支持该参数时自动去掉并重试一次。
• 界面配置模型路由：日常只需在 WebUI「插件」页的「建议提示词」卡片里选择建议生成的 provider / model（或跟随会话路由），保存后下一完成回合生效，无需手动改配置文件。
• 只发最后一轮：默认只把最后一轮的用户输入与 AI 最终回答发给建议模型（maxRecentTurns 默认为 1），中间的工具调用 / 推理过程一律不发送。
• 有界调用：字节 / 令牌 / 超时上限、转录长度预算、建议可见字符上限，全部可配置。
• 安全：转录在发送前脱敏（密钥形状被掩蔽）；输出净化（控制序列、围栏、引号剥离、单行化）并做语义过滤（元文本、评价套话、助手口吻等被当作「无建议」丢弃）。
• 无建议是常态：模型回复为空或不合格时静默跳过，不报错、不写事件、不打扰。
• 免调用重显：删回空草稿会重新显示已持久化的建议，不再发新的模型请求。
• 快捷键可配：采纳快捷键默认 Tab，可在「插件」页的「建议提示词」表单里按实际按键录制（如 Alt+Slash、Ctrl+Enter）。

效果预览

每个 agent 回合完成后，建议模型会在输入框里以浅色幽灵占位文字的形式显示一条预测，按 Tab 即可采纳进草稿：

安装

前置条件

• Node.js ^22.19 或 >=24、pnpm。
• 一个基于 deepseek-harness 的 dsh 部署（web profile），dsh ≥ 0.2.0-rc.2（0.2.0 变更了会话投影、Web 客户端模块表与设置面板契约，本插件按该版本适配）。浏览器端需要 conversation.input.overlay 槽位与 inputActions.setDraft（deepseek-harness 的标准 web 输入机均已提供）。

从 GitHub 安装（默认方式，一行命令）

本插件是一个单包 bundle：仓库根 @studyzy/dsh-suggest-prompt 声明了 dsh.bundle（自带 cordis.patch.yml），因此用 dsh plugin add 指向 GitHub 仓库即可安装，装完自动成为 profile 的一个 bundle 层，无需手动改配置文件。

# 从 GitHub 安装（推荐）
dsh plugin --profile web add git@github.com:studyzy/dsh-suggest-prompt.git

# 或 HTTPS
dsh plugin --profile web add https://github.com/studyzy/dsh-suggest-prompt.git

装完后重启正在运行的 dsh web 服务即可。安装后 profile 层叠顺序变为 dsh-base → dsh-web-app → @studyzy/dsh-suggest-prompt。

卸载：

dsh plugin --profile web remove @studyzy/dsh-suggest-prompt

git 安装的 pnpm ≥10 提示：git 托管的插件在安装时通过 prepare 脚本构建，pnpm ≥10 会拦截该脚本直到放行。若 add 报错，把 pnpm 打印的包键加进 ~/.dsh/profiles/web/pnpm-workspace.yaml 的 allowBuilds，再重跑 add。

本地源码安装（开发用）

dsh plugin --profile web add /path/to/dsh-suggest-prompt

通过 npm 安装（发布后）

dsh plugin --profile web add @studyzy/dsh-suggest-prompt

说明：无论哪种来源，装完都是同一个 bundle 层。日常建议模型的 provider / model 通过 WebUI 的「插件」页卡片配置（见下「配置」），不需要在安装时手动指定。

配置

配置分两层：日常的路由配置走界面，一次性的资源上限在 bundle 自带的补丁层提供（可在 profile 补丁层覆盖）。

通过 WebUI 界面配置建议模型（日常）

「建议提示词」表单在 「插件」页上有两个入口，渲染的是同一张表单：

• 「官方」分组里的「建议提示词」卡片 —— 点开即可看到表单；
• 「已安装」分组里的 @studyzy/dsh-suggest-prompt 包卡片 —— 点进详情页后，表单出现在「包含的组件」上方。

这是日常配置建议模型的主入口，无需手动改配置文件。两个入口共用同一份草稿：在一处改了 provider / model / 快捷键，切到另一处能看到同样的改动；保存是一次写入（写入 profile patch 的 config，全局层），保存后下一个完成回合生效。

• Provider / Model：从已安装的 provider 目录（内置 DeepSeek 与 pi-ai 各 provider）中选择建议生成使用的路由；选择「跟随会话路由」则不覆盖，继承主请求路由。
• Accept shortcut：点击输入框获得焦点后，直接按下想用的按键或组合键，按键即录制显示（先按 Alt 再按 Slash → Alt+Slash，Ctrl+Alt+X 显示为三个键），无需手动打字。
• 编辑是暂存式的（带「未保存」标记与「放弃 / 保存」按钮），保存会由界面写入当前 profile 的 suggest-prompt entry；保存后下一个完成回合生效，无需重启。
• 下拉只会列出目录中显式声明的模型；某 provider 未声明模型列表时，模型字段退化为自由文本输入。
• 依赖 harness 的设置能力：没有挂载设置服务的组装（如 headless）不显示此表单，此时仍可在补丁层配置 provider / model / acceptKey。

只有当宿主能描述该 entry 时表单才会出现，这要求设置字段在插件 Config schema 中标记 volatile()（见 [AGENTS.md](AGENTS.md) 的「Version-critical contracts」）。同一标记也让这些值以活引用而非普通值传入插件，因此 resolveSuggestPromptConfig 会在配置边界统一解包。

该截图拍的是搬迁前的「设置 → 内置插件」标签页，内容已过时（见 [CHANGELOG.md](CHANGELOG.md)：「插件」页表单截图待更新）。

补丁层字段（安装即带默认，可覆盖）

以下字段由 bundle 自带的 cordis.patch.yml 提供默认值，通常无需改动；需要自定义时，在 profile 补丁层（~/.dsh/profiles/web/cordis.patch.yml）用 - insert: 覆盖同名 entry 的 config。provider / model / acceptKey 可在 WebUI「插件」页的「建议提示词」表单中配置；其余字段不在该表单中：

字段 · 含义 · 默认值

maxInputBytes · 最终框架化用户提示的最大 UTF-8 字节数 · 4096

maxOutputTokens · 建议生成输出令牌上限 · 512

timeoutMs · 辅助请求端到端截止时间（毫秒） · 60000

maxRecentTurns · 转录尾部保留的最近完成回合数 · 1（只取最后一轮的用户输入 + AI 最终回答）

maxTranscriptChars · 转录字符预算 · 12000

maxSuggestionChars · 建议的可见字符上限 · 240

provider / model · 各自独立覆盖主请求路由的对应字段；省略的字段自动继承主请求路由 · 继承（也可经界面配置）

acceptKey · 采纳建议的输入框快捷键 · Tab（界面可录制为 Alt+Slash、Ctrl+Enter 等）

maxOutputTokens 提示：建议生成默认关闭思考（reasoningEffort: off），推理不消耗输出预算；但对无法关闭思考的模型（如部分 pi-ai 路由）会降级重试，此时思考仍会消耗预算——maxOutputTokens 偏小时，流会在输出建议文本之前就以 max-tokens 结束。这类模型请留足预算（例如 512）。

工作方式

• 宿主在 turn/end（reason=completed）时触发生成；按会话 + 回合去重，下一个完成回合会中止上一个在途生成。
• 建议保存在插件自己的 storage domain，浏览器通过同源 /api/suggest-prompt 路由读取；自动与手动生成都不追加会话事件，不污染模型可见上下文或会话日志。
• 生成能力依赖公开的 sessionProjections 服务；没有该服务的宿主组合不会挂载生成能力。插件不依赖私有历史读取或 appendPluginRecord。
• 喂给辅助调用的对话记录由仅宿主端的 suggestPromptTranscript 投影从已提交事件增量折叠而来，而不再扫描会话历史：dsh >= 0.2.0 禁止新生产代码同步读取历史事件。该折叠同时约束内存，只保留最近约 4 个回合。
• 幽灵文字在 agent 空闲且草稿为空时显示；键入即隐藏，删回空草稿重新显示。dsh >= 0.2.0 移除了客户端的 turnEnds 映射，因此新鲜度改由空闲标志判断，而非本地比对完成回合。
• 显示建议时，输入框的原生占位文字会被隐藏（用 visibility，不引起重排）；否则两者会绘制在同一文字起点上，谁都看不清。
• 按 acceptKey（默认 Tab）把建议填入草稿（可编辑后再发送）；焦点不在输入框或处于 IME 组合输入时不触发，快捷键也只在显示幽灵文字时才被拦截（否则 Tab 保持默认焦点行为）。
• dsh >= 0.2.0 的输入框是 Lexical 的 contenteditable 宿主而非 <textarea>；采纳路径同时兼容两种形态，因此快捷键在任一形态下都可用。

触屏采纳与手动生成

• 输入框工具栏在空闲、空草稿、可编辑时显示操作按

…(truncated)