建议提示词 studyzy/dsh-suggest-prompt

dsh-suggest-prompt

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

想快速上手？直接看 使用说明（面向终端用户的操作指南）。

Read this in English · 中文文档

写给开发者 / 维护者：本仓库是单个 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）。

效果预览

每个智能体回合完成后，建议模型会在输入框里以浅色幽灵占位文字的形式显示一条预测，按 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 的「Version-critical contracts」）。同一标记也让这些值以活引用而非普通值传入插件，因此 resolveSuggestPromptConfig 会在配置边界统一解包。

「插件」页上的建议提示词表单

该截图拍的是搬迁前的「设置 → 内置插件」标签页，内容已过时（见 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 宿主而非 ；采纳路径同时兼容两种形态，因此快捷键在任一形态下都可用。

触屏采纳与手动生成

- 输入框工具栏在空闲、空草稿、可编辑时显示操作按钮；手机无需模拟 Tab 或连接键盘。
- 有建议时点 「采纳」：只填入可编辑草稿，绝不自动发送；桌面原有快捷键保持不变。
- 没有建议时点 「生成建议」：显式发起一次辅助调用，受既有模型路由、脱敏和预算限制，会产生模型用量。生成后先显示建议，再点「采纳」才填入草稿。
- 无已完成的对话上下文、会话运行中或已有生成任务时，不会另起调用；空结果、忙碌和失败都有反馈，可以稍后重试。多次连点不会并发生成。
- 输入了自己的草稿或输入框正在提交/处理时，操作入口隐藏，避免覆盖已有输入；检测到同一输入框的输入法组字时，采纳和生成也不会执行。切换会话或离开页面会中止客户端等待，旧响应不会填入其他会话。服务端仍独立约束模型超时和会话生命周期。
- 后端通过当前宿主的同源 POST /api/suggest-prompt/generate 接口处理手动请求（会话访问沿用宿主连接认证）；浏览器不接触模型密钥，也不读取私有会话历史。

模型体验

- 系统提示词：把模型限定为「以用户口吻预测下一条提示词」，禁止生成内容或元文本，给出具体正反例；回复语言跟随会话（最后一条用户消息含 CJK → 简体中文，否则 English）。
- 模型看到的输入：默认只有最后一轮的 [User Message] / [Assistant Response] 带标签块（已脱敏、受 maxTranscriptChars 约束）。
- 免思考：辅助请求默认携带 reasoningEffort: off（DeepSeek 序列化为 thinking: disabled），追求快速与低成本；模型不支持时自动去掉该字段重试一次（拒绝发生在任何网络 I/O 之前，几乎无额外开销）。
- 成本：自动生成在每个完成回合至多启动一次任务；显式「生成建议」可为无建议的同一回合再次调用。所有调用都受 maxInputBytes / maxOutputTokens 约束，主 agent 请求不增加任何 token。

安全

- 转录脱敏：AWS AKIA…、OpenAI sk-…、GitHub ghp_/gho_/ghu_、Slack xox-…、JWT、Stripe rk_… 等密钥形状在发送前被掩蔽为占位标签。
- 输出净化：ANSI/OSC/CSI/DCS 序列、C0/C1 控制符、双向覆盖符、孤立代理项被剥离；引号与代码围栏被去除；压缩为单行并截断到 maxSuggestionChars。
- 语义过滤：元文本（"no suggestion"、"stay silent"）、错误回显、评价套话（"thanks"、"looks good"、谢谢、不错）、助手口吻（"Let me…"、"I'll…"、我来、我帮你）、多句 / 过长回复、孤立单词会被当作「无建议」丢弃，而不是显示。

已知限制

- 每个完成回合都会生成（与输入框是否已有内容无关），幽灵文字只在草稿为空时显示。
- 被中止（取代）的生成不会为较早回合留下建议。
- 空回复或被过滤的回复 = 该回合无建议：不写建议记录，投影保持 null，也不记录警告。
- 投影保留最后一条建议：重新打开旧会话会显示其最终建议，且不发起新的模型调用。
- 建议模型的路由与预算由部署配置决定；无法关闭思考的模型（如部分 pi-ai 路由）会回退为模型默认的推理行为，想获得最快的建议体验，建议选支持关闭思考的路由（如内置 DeepSeek）。

开发

pnpm install
pnpm build # host tsc + client tsdown bundle
pnpm test # vitest
pnpm typecheck
pnpm test:e2e # browser e2e against an isolated dsh web (needs DEEPSEEK_API_KEY)
pnpm test:e2e:local # local e2e against your real ~/.dsh (macOS: visible browser)

E2E（CI）：pnpm test:e2e 会起一个隔离 $DSH_HOME，用 dsh plugin add 安装本插件、dsh web 起服务，再用 Playwright 走 WebUI（配置 DeepSeek Key、把建议模型设为 DeepSeek Flash），输入一道数学题后断言输入框出现下一条建议的幽灵文字。需要环境变量 DEEPSEEK_API_KEY（无则跳过）与全局 dsh；CI 里由 DEEPSEEK_API_KEY secret 注入。默认 pnpm test 不含 e2e。

E2E（本地）：pnpm test:e2e:local 复用你的真实 ~/.dsh（不装 dsh、不跑 onboarding、不连工作区——本机已就绪），把当前源码 link 进本地 web profile（dsh plugin add），起 dsh web 后用 Playwright 把「建议提示词」模型设为 DeepSeek Flash（ccr / hai/DeepSeek-V4-Flash），输入「出一道小学数学题给我」并断言幽灵建议出现。macOS 下弹出可见浏览器，Linux 下 headless。会写真实 ~/.dsh（suggest-prompt 模型与 profile 依赖来源）——仅限本地开发验证，不入 CI。
安装说明：本仓库依赖已发布的 @deepseek-ai/ 包（deepseek-harness 工作区）。上游少数内部包（@deepseek-ai/dsh-compact、@deepseek-ai/dsh-type-meta、@deepseek-ai/dsh-environment）还没出现在 npm registry，本仓库通过根 package.json 的 pnpm.overrides 把它们映射到本地 stubs/ 空包；同时用一条 @deepseek-ai/dsh-: 0.2.0-rc.2 override 把整个 dsh 依赖集统一到当前插件所适配的 0.2.0-rc.2（与本仓库针对 0.2.0 契约的适配保持一致），因此 pnpm install 可直接成功；等 registry 补齐、上游稳定后，这两处 overrides 与 stubs/ 均可清理。完整测试矩阵在 harness monorepo 内运行；本仓库是单 bundle 包的权威源码副本。pnpm build 产出宿主 ESM（lib/{index,invariant}.js）、浏览器 bundle（lib/client.js）与 lib/types/ 声明。

prepare 脚本：package.json 的 prepare 脚本会在 pnpm install（含 dsh plugin add <git-url> 的安装流程）时自动运行 pnpm build，现场构建 lib/，产物不入库。因此源码改动后无需手动构建，本地 dsh 就能加载；从 Git 安装也总能拿到完整产物（含类型声明）。

许可

MIT

dsh-suggest-prompt

阅读中文版 · English

Suggested-next-prompt 插件，用于 DeepSeek Harness。每轮智能体回合结束后，一次有界的辅助 LLM 调用会把一条建议的下一条提示词写入插件的持久化存储；Web 端把它渲染成输入框里的幽灵占位文本——按 Tab（默认）即可采纳进草稿（Claude Code 的行为）。

给开发者 / 维护者：本仓库是单 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），不把预算花在思维链上；拒绝 off 的模型会去掉该字段重试一次。
- 在 WebUI 里配置路由：日常使用时，在 Plugins 页的「建议提示词」卡片里选建议的服务商 / 模型（或保持「跟随会话路由」）；保存后从下一个完成的回合起生效——不用手动改配置文件。
- 只取最后一轮：默认只把最近一个已完成轮次的用户输入和助手最终回答发给建议模型（maxRecentTurns 默认为 1）；中间的工具调用和推理过程一律不包含。
- 有边界：字节、token、超时都有上限，还有对话记录预算，以及建议内容的可见字符上限——全部可配置。
- 安全：对话记录在拼接前先做密钥脱敏；输出会清洗（去掉控制序列、围栏、引号，压成单行），再做语义过滤（元文本、评价性填充、助手口吻的措辞都按「无建议」丢弃）。
- 静默无建议：模型回复为空或不可接受时直接跳过——不报错、不发事件、不打扰。
- 无需请求即可重新武装：删回空草稿时，直接重新显示已持久化的建议，不再发新的模型请求。
- 快捷键可配置：采纳快捷键由 acceptKey 指定（默认 Tab），可在 Plugins 页面的「建议提示词」表单里录制（例如 Alt+Slash、Ctrl+Enter）。

预览

每个智能体轮次完成后，建议模型会把预测的下一条提示词，以浅色幽灵占位文本的形式渲染在输入框里。按 Tab 采纳进草稿：

输入框中的幽灵建议

安装

前置条件

- Node.js ^22.19 或 >=24，以及 pnpm。
- 用 DeepSeek Harness 构建的 dsh 部署（web 配置档），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 仓库时，会把它作为配置档的一个 bundle 层安装——不用手动改配置文件。

From GitHub (recommended)
dsh plugin --profile web add git@github.com:studyzy/dsh-suggest-prompt.git

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

然后重启正在运行的 dsh web 服务。安装后配置档的分层变为 dsh-base → dsh-web-app → @studyzy/dsh-suggest-prompt。

卸载：

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

pnpm ≥10 的 git 注意事项：git 托管的插件在安装时通过 prepare 脚本构建，pnpm 默认拦截，需要放行。如果 add 失败，把 pnpm 打印出的确切 key 加到 ~/.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 层。日常用的建议服务商/模型从 WebUI 卡片配置（见下文「配置」）——安装时不用设任何东西。

配置

配置分两块：日常路由在 UI 里设，一次性资源上限随 bundle 的补丁层带默认值（可在你的配置档补丁层覆盖）。

在 WebUI 里配置建议模型（日常）

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

- 官方（Official）分组里的「建议提示词」卡片——打开它，表单就在那儿；
- 已安装（Installed）分组里的 @studyzy/dsh-suggest-prompt 包卡片——详情页上表单在「包含的组件」（Components）列表上方。

这是选择建议路由的主要入口——不用手动改配置文件。两个入口共用一份草稿：在任一处改服务商 / 模型 / 快捷键，另一处同步显示；保存只写一次（写配置档补丁的 config，全局层），下一轮对话完成时生效。

- 服务商 / 模型：从已安装的服务商目录（内置 DeepSeek + pi-ai 路由）里选辅助调用走哪条路由；选「跟随会话路由」就沿用主请求路由。
- 接受快捷键：聚焦输入框，然后按你想用的键或组合键——按下的键会被记录并显示（先按 Alt 再按 Slash → Alt+Slash；像 Ctrl+Alt+X 这样的三键组合显示为三个键），不用打字。
- 编辑先暂存（带「未保存」标记和「放弃」/「保存」按钮）；保存会写入当前配置档的 suggest-prompt 条目，下一轮对话完成时生效——不用重启。
- 下拉框只列显式声明过的模型；服务商没声明模型列表时，模型字段退化为自由文本输入。
- 这依赖 harness 的设置能力：没有设置服务的装配（比如 headless）不显示表单，继续用补丁层里的 provider / model / acceptKey。

只有当宿主能描述这个条目时，表单才可被发现，这要求插件 Config schema 里面向设置的字段标上 volatile()（见 AGENTS.md 的「Version-critical contracts」）。这个标记也让这些值以实时引用而非普通值的形式到达，所以 resolveSuggestPromptConfig 在配置边界处把它们解包。

插件页上的建议提示词表单

截图显示的是搬移前的「设置 → 内置插件」标签页，已经过时（见 CHANGELOG.md：插件页表单还需要一张新截图）。

补丁层字段（默认值随 bundle 提供，可覆盖）

以下字段由插件包自带的 cordis.patch.yml 提供默认值，通常无需改动；如需自定义，在配置档补丁层（~/.dsh/profiles/web/cordis.patch.yml）里用 - insert: 覆盖同一配置项的 config。provider / model / acceptKey 可在 Plugins 页面的 WebUI 表单里编辑，其余字段不在 WebUI 表单中：

| 字段 | 含义 | 默认值 |
| maxInputBytes | 最终拼装好的用户提示词的最大 UTF-8 字节数 | 4096 |
| maxOutputTokens | 建议输出的 token 上限 | 512 |
| timeoutMs | 辅助请求的端到端超时（毫秒） | 60000 |
| maxRecentTurns | 对话记录尾部最多保留最近多少个已完成的轮次 | 1（只保留最后一轮的用户输入 + 助手最终回答） |
| maxTranscriptChars | 对话记录的字符预算 | 12000 |
| maxSuggestionChars | 建议的可见字符上限 | 240 |
| provider / model | 各自独立覆盖主请求路由中对应的成员；省略的成员继承主路由 | 继承（也可在 WebUI 中编辑） |
| acceptKey | 采纳已显示建议的输入框快捷键 | Tab（在 UI 中可录制为 Alt+Slash、Ctrl+Enter 等） |

关于 maxOutputTokens：生成建议时默认关闭思考（reasoningEffort: off），所以推理不占用输出预算；但有些模型无法关闭思考（部分 pi-ai 路由），会退回到重试，此时思考仍会消耗预算——maxOutputTokens 设得太小，流会在产出任何建议文本之前就以 max-tokens 结束。这类模型请留足预算（例如 512）。

工作原理

- 宿主在 turn/end（reason 为 completed）时触发生成，按会话和轮次去重；下一个完成的轮次会中止正在进行的生成。
- 建议保存在插件自己的存储域中，浏览器通过同源的 /api/suggest-prompt 路由读取。无论自动生成还是手动生成，都不会追加会话事件，也不会改变模型可见的上下文。
- 只有在公开的 sessionProjections 服务可用时才会挂载生成逻辑。它不依赖私有的历史读取器，也不依赖 appendPluginRecord。
- 喂给辅助调用的对话记录，由已提交事件折叠出的宿主专用 suggestPromptTranscript 投影维护，而不是扫描会话历史：dsh >= 0.2.0 已弃用同步历史读取，供新的生产调用方使用。该折叠同时限制内存占用，大致保留最近四个轮次。
- 智能体空闲且草稿为空时显示幽灵文本；一旦输入就隐藏，删回空草稿会重新显示。dsh >= 0.2.0 移除了客户端的 turnEnds 映射，所以新鲜度来自空闲标志，而不是本地比较已完成的轮次。
- 显示建议期间，输入框自带的占位符会隐藏（通过 visibility 实现，因此不会引起重排）——否则两者会绘制在同一文本起点上，谁都看不清。
- 按下 acceptKey（默认 Tab）会填充草稿（可编辑，不发送）。焦点在输入框之外或处于输入法组合状态时，该操作会被忽略；只有在显示幽灵文本时才拦截该快捷键（否则 Tab 保持默认的焦点切换行为）。
- 在 dsh >= 0.2.0 中，输入框是 Lexical 的 contenteditable 宿主，不再是 ；接受路径会同时识别这两种形态的焦点，因此快捷键在两者上都能生效。

触摸接受与按需生成

- 会话空闲且可编辑草稿为空时，若已有建议，输入框工具栏显示 Accept，否则显示 Suggest。触摸用户无需硬件键盘；桌面快捷键依然可用。
- Accept 只填充可编辑草稿，绝不发送。 Suggest 会按配置的路由和脱敏规则发起一次显式、有预算的模型调用，因此会产生模型用量。生成只负责显示建议：接受建议是另一个独立操作。
- 需要已完成的对话上下文。会话忙碌、重复点击、输出为空和出错时都会给出反馈。已有输入草稿、输入提交或归属阶段会隐藏这些控件；切换会话或卸载组件会中止客户端等待，且无法填充其他会话的草稿。宿主侧的模型超时与生命周期保护独立生效。
- 手动请求使用宿主鉴权、同源的 POST /api/suggest-prompt/generate 端点。浏览器不会接触到任何模型凭据或私有历史读取器。

模型体验

- 系统提示词：约束模型用用户自己的口吻预测用户的下一条提示词，禁止生成内容或元文本，并给出具体示例与反例；回复语言跟随对话（最后一条用户消息含 CJK 时用 简体中文，否则用 English）。
- 模型看到什么：默认只看到最后一轮，以带标签的 [User Message] / [Assistant Response] 块呈现（已脱敏，受 maxTranscriptChars 限制）。
- 不思考：辅助请求默认携带 reasoningEffort: off（DeepSeek 会将其序列化为 thinking: disabled），以提升速度、降低成本；若模型拒绝 off，会去掉该字段重试一次（拒绝发生在任何网络 I/O 之前，因此重试几乎零成本）。
- 成本：自动生成每完成一轮最多启动一个任务。没有建议时，显式 Suggest 操作可能针对同一轮再次调用模型。所有调用都受 maxInputBytes / maxOutputTokens 限制；主智能体请求不增加任何 token。

安全

- 对话记录脱敏：AWS AKIA…、OpenAI sk-…、GitHub ghp_/gho_/ghu_、Slack xox-…、JWT 以及 Stripe rk_… 等密钥形态，都会在对话记录送达模型之前被掩码。
- 输出净化：清除 ANSI/OSC/CSI/DCS 序列、C0/C1 控制字符、双向覆盖字符和孤立代理项；去掉引号和代码围栏；文本压成一行，并截断到 maxSuggestionChars。
- 语义过滤：以下内容一律按「无建议」丢弃，不展示：元文本（「no suggestion」「stay silent」）、错误回显、评价性填充语（「thanks」「looks good」）、助手口吻的措辞（「Let me…」「I'll…」）、多句或过长的回复、零散单词。

已知限制

- 每轮对话完成后都会跑一次生成，不管输入框里是否已有文字；只有草稿为空时才显示幽灵文本。
- 生成被取代（中止）后，旧的那一轮就没有建议了。
- 回复为空或被过滤，这一轮就算「无建议」：不写记录，投影保持 null，也不打警告日志。
- 投影会持久化最后一条建议，所以重新打开旧会话时，直接显示它最后的建议，不再调用模型。
- 建议路由和预算是部署配置；关不掉思考的模型（部分 pi-ai 路由）会退回默认推理行为——想要最快的建议，就选支持 off 的路由（比如内置的 DeepSeek）。

开发

安装步骤、CI 门禁、版本耦合代码的规则，见 CONTRIBUTING.md。变更记录写在 CHANGELOG.md；安全问题走 SECURITY.md。

pnpm install
pnpm build # host tsc + client tsdown bundle
pnpm test # vitest
pnpm typecheck
pnpm test:e2e # browser e2e against an isolated dsh web (needs DEEPSEEK_API_KEY)
pnpm test:e2e:local # local e2e against your real ~/.dsh (macOS: visible browser)

E2E（CI）：pnpm test:e2e 会启动一个隔离的 $DSH_HOME，用 dsh plugin add 安装本插件包，启动 dsh web，再用 Playwright 驱动 WebUI（存入 DeepSeek key，把建议模型设为 DeepSeek Flash，发一道数学题，然后断言出现下一条提示词的幽灵建议、原生占位符藏在它下面——也就是双幽灵回归——以及按 Tab 采纳建议）。它需要 DEEPSEEK_API_KEY（没有就跳过）和全局安装的 dsh；CI 以 secret 注入 key。默认的 pnpm test 不含 e2e。CI 里这个 job 是 continue-on-error，因为它依赖真实的模型往返；build job 才是门禁。
E2E（本地）：pnpm test:e2e:local 复用你真实的 ~/.dsh（不安装 dsh、不走新手引导、不选工作区——你的机器已经配好了）。它用 dsh plugin add 把当前源码链接进本地 web 配置档，启动 dsh web，然后驱动 Playwright 把「建议提示词」的 suggestion model 设为 DeepSeek Flash（ccr / hai/DeepSeek-V4-Flash），发送「出一道小学数学题给我」，并断言出现 ghost suggestion。在 macOS 上浏览器以 headful 模式运行（能看着它操作 UI）；其他平台 headless。它会写入你真实的 ~/.dsh（suggest-prompt 模型和配置档的依赖源）——仅限本地开发，不属于 CI。

安装注意事项：本仓库依赖已发布的 @deepseek-ai/ 包（DeepSeek Harness 工作区）。已发布的 dsh- 版本引用了少量内部包，这些包还没上 npm registry（@deepseek-ai/dsh-compact、@deepseek-ai/dsh-type-meta、@deepseek-ai/dsh-environment）；根 package.json 的 pnpm.overrides 把它们映射到本地空的 stubs/ 包。第二个 override（@deepseek-ai/dsh-*: 0.2.0-rc.2）把整套 dsh 依赖固定到本插件针对的 0.2.0-rc.2 版本（与其 0.2.0 契约适配保持一致），因此 pnpm install 开箱即用——等 registry 补齐、上游稳定后，删掉这两个 override 和 stubs/ 即可。完整测试矩阵在 harness monorepo 内运行；本仓库是单 bundle 包的 source-of-record 副本。pnpm build 产出宿主 ESM（lib/{index,invariant}.js）、浏览器 bundle（lib/client.js）和 lib/types/ 声明。

prepare 脚本：package.json 的 prepare 在 pnpm install 时运行 pnpm build（包括 dsh plugin add <git-url>），当场构建 lib/。构建产物从不提交，所以改源码后本地 dsh 加载无需手动构建即可生效，Git 安装也总能拿到完整的产物集（含类型）。

License

MIT