建议者 · DSH Advisor

在 DeepSeek Harness 的输入框里提供行内写作建议和下一句建议。默认跟随当前会话的模型，默认在 agent 一轮输出结束后猜你接下来想说什么；/suggest 可以打开多建议面板，最后一行还能输入你自己的方向。

> English · 简体中文

┌────────────────────────────────────────────┐
│  ← 输入框（灰字为建议，Tab 接受）           │
│  帮我审一下这段代码，重点看▏并发安全        │
└────────────────────────────────────────────┘

功能

• 行内 ghost text：草稿末尾显示灰色建议，Tab 接受，一次 undo 可撤销。
• 回合结束建议：agent 一轮输出完成且输入框为空时，猜你下一句想说什么（可关）。
• /suggest 面板：列出多条建议，默认选中「建议」预设，支持模式与预设切换、↑↓ 选择、Tab/Enter 应用。
• 双击 Tab：在输入框里连续按两次 Tab 也能打开面板。
• 自定义方向：面板最后一行输入你的想法，例如“更具体一点，加个例子”，再按这个方向生成。
• 模式 + 预设：模式负责装配（代码、写作、翻译），预设是具体能力（建议、续写、润色、修 Bug、翻译……）。预设的 prompt、类型、温度、输出上限和推理强度单独编辑，所有模式共享。
• 模型可选：跟随当前会话 / 全局默认 / 固定 provider+model。
• 上下文可配：最近 N 条对话、工作区路径、时间，全部可开关。
• 分页设置页：在侧栏 Plugins → Installed plugins 打开 dsh-advisor，点插件行的 Configure 进入；分为通用、模式、预设、诊断四页，通用里包含模型、触发、上下文、面板和界面。
• 可选挂起：通用 → 界面里的「挂起到设置侧边栏」开关可以把同一套设置挂到 Settings 弹窗左侧，方便经常调整模型或预设。
• 本地优先：没有遥测、没有额外服务端；草稿只在浏览器里，自动触发或你主动打开面板时才会把必要内容发给你在 DSH 里配置的模型。

环境要求

• 已安装 DeepSeek Harness，并使用 Web GUI 或 Desktop 界面（插件依赖浏览器侧插槽，不支持纯 TUI）。
• 已在 DSH 里配置至少一个可用模型。
• 安装时需要能访问本机文件系统，通过 Harness 自带的 plugin_manager 安装；安装动作会请求权限，按 Harness 提示批准即可。
• 开发和测试基于 DeepSeek Harness 0.2.1-rc.2。插件使用了 DSH 的内部扩展点，升级 DSH 后可能需要跟随调整；最低版本声明在 plugin/package.json 的 engines.dsh 里。

安装

1. 克隆仓库：

git clone https://github.com/KristoffLiu/dsh-advisor.git
cd dsh-advisor

2. 在 Harness 里让 agent 安装插件。安装目标必须指向仓库里的 plugin/ 子目录，并且用绝对路径：

plugin_manager install_bundle target=/absolute/path/to/dsh-advisor/plugin

例如：

plugin_manager install_bundle target=/Users/me/code/dsh-advisor/plugin

3. 重启 Harness（Host 侧代码在启动时加载），然后刷新页面。插件会出现在侧栏 Plugins → Installed plugins。

打开 dsh-advisor 的 bundle 页，在插件行点 Configure 编辑设置。Settings → Built-in plugins 只提供只读清单，不是插件配置入口。

> 为什么是 plugin/ 而不是仓库根目录？仓库根目录只放文档和开发文件，可安装的 Harness 插件包在 plugin/ 里，这样 plugin/package.json 的 files 和 exports 只暴露运行所需文件。

更新

cd dsh-advisor
git pull

然后在 Harness 里对同一个 plugin/ 路径重新执行 install_bundle，并重启 Harness。只刷新页面不够：Host 侧的 host.js 会在重启后生效；Client 侧刷新页面即可，但重新安装可以确保版本号更新、避免模块缓存。

卸载

在 Harness 里执行：

plugin_manager remove_bundle target=dsh-advisor

然后重启 Harness。配置文件 ~/.dsh/dsh-advisor.json 不会被删除，需要的话可以手动清理。

使用

重写类预设（修 Bug、补测试、解释、重构、润色、精简、扩写、正式、翻译）通常只在面板里出现，应用时会整段替换草稿；续写和下一句走行内灰字。只有在配置里完全没有 next 类预设时，回合结束建议才不会触发。

配置

首次请求配置时（打开页面或设置页）会生成：

$DSH_HOME/dsh-advisor.json

默认是 ~/.dsh/dsh-advisor.json。可以直接改文件，也可以在 Plugins → dsh-advisor → Configure 里改；配置文件有 2 秒缓存，保存或改文件后最多 2 秒生效。

下面是常用字段的节选；完整默认配置（归一化后的实际生效值，含所有模式、预设和 order 字段）见 examples/dsh-advisor.default.json。

{
"model": {
"mode": "session",                   // session | default | fixed
"fallbackToSession": true
},
// "model": { "mode": "fixed", "provider": "deepseek", "model": "deepseek-chat", "fallbackToSession": true },

"auto": {
"onTurnEnd": true,                   // 一轮结束后给下一句建议
"onTypingPause": false,              // 打字停顿后给续写建议（默认关）
"delayMs": 1400,
"minChars": 8,
"cooldownMs": 4000,
"turnEndDelayMs": 600
},

"panel": { "count": 3, "maxHeight": 380, "directionDelayMs": 400 },

"context": {
"sessionMessages": 4,                // 0 = 不带对话
"maxContextChars": 6000,
"workspace": true,
"time": false
},

"limits": { "maxDraftChars": 20000, "requestTimeoutMs": 20000, "fixedTimeoutMs": 20000 },

"ui": { "mountSettingsInSidebar": false },  // 开启后 Settings 侧边栏出现「建议者」

"defaultMode": "code"
// "modes" / "presets" 见下方说明
}

模式与预设

内置三套模式：

内置预设的 kind 决定应用方式：

• next：用于空输入框，给出下一句消息（suggest）。
• continue：用于草稿续写（continue）。
• rewrite：用于整段改写（fix、tests、explain、refactor、polish、shorten、expand、formal、to-en、to-zh）。

modes 和 presets 的完整默认值见 examples/dsh-advisor.default.json：

• 模式只保存装配关系：标题、描述、默认预设和预设 id 列表；模式描述会作为上下文交给模型。
• 预设是全局能力库，存 prompt、类型、温度、上限和推理强度。多个模式可以共用同一个预设。
• modes 和 presets 两个数组分别整体替换内置数组，二者互不影响：
• 只写 modes：模式列表被替换，presets 仍是内置预设库；引用不到预设的模式会被丢弃。
• 只写 presets：预设库被替换，内置模式里引用不到新预设的模式会被丢弃；如果一个模式都不剩，整体回退到内置默认配置。
• 最稳妥的做法是同时提供完整的 modes 和 presets，也就是以完整默认配置为起点修改。
• 旧版 groups + tabs 配置会在读取时自动迁移：prompt 相同、id 相同的 tab 合并成一个预设；prompt 不同的 tab 会生成新 id（前缀为 group id），标题追加 （group 标题）。设置页的「恢复默认模式与预设」可随时回到内置配置。
• ui.mountSettingsInSidebar 为 true 时，Settings 弹窗左侧会多一个「建议者」入口；关闭并保存后移除。这只影响设置界面挂载位置，不影响建议行为。
• 数字字段会被夹到安全范围；未知字段忽略。

它是怎么工作的

• Host 半边 host.js 注册 /api/dsh-advisor 这条带登录鉴权的 RPC 通道（ctx.connection.fetch.register），请求体是 { endpoint, payload }，端点包括 complete、config、reload、settings、save、models、probe、diagnostics、ping。它负责读配置、取会话上下文、解析模型、拼 prompt、调用 ctx.llm。
• Client 半边 client.js 注册 conversation.input.overlay（灰字/面板）、conversation.input.left（✦ 按钮）和 plugins.row.config（插件设置页），并用 commandUi 注册 /suggest。ui.mountSettingsInSidebar 为真时再动态挂载一个 settings.section。
• 草稿和光标来自插槽标准 props：useInput / inputActions.captureInsertion()；写回统一走 inputActions.insertText()，因此每次应用都是一步可撤销编辑。
• 行内灰字是编辑器段落上的 CSS ::after / ::before，和 Harness 自己的命令提示共用同一机制，不改编辑器 DOM；DSH 若调整段落结构，灰字会静默失效，不影响其他功能。
• 模型调用使用 ctx.llm.prepareCall() + stream()。模型解析：fixed 用配置里的 provider/model；default 用 DSH 的全局默认模型（agentDefaultModel，取不到时回退到会话模型）；session 先用当前会话的 requestHeader().config，再回退到 agentDefaultModel。固定模型失败且打开了 model.fallbackToSession 时，会回退到会话模型。

开发

没有构建步骤，也没有运行时依赖：插件是直接加载的 ES 模块。

plugin/host.js      Host：HTTP 路由、配置、上下文、模型调用
plugin/config.js    默认模式/预设、合并、校验与旧配置迁移
plugin/prompts.js   prompt 拼装、输出清洗
plugin/client.js    Client：灰字、面板、按钮、/suggest

本地迭代方式：

1. 用 plugin_manager install_bundle target=<绝对路径>/plugin 把当前工作区装进 profile（安装会建立到工作区的 link）。
2. 改 Host 文件后重启 Harness；改 client.js 后刷新页面即可。
3. 改版本号（plugin/package.json 与 client.js / host.js 里的版本常量）可以绕开模块缓存。

提交前可本地检查：

node --check plugin/host.js && node --check plugin/client.js && node --check plugin/config.js && node --check plugin/prompts.js
node scripts/check-default-config.mjs
node -e "JSON.parse(require('node:fs').readFileSync('plugin/package.json')); console.log('JSON OK')"
(cd plugin && npm pack --dry-run)

CI（GitHub Actions）会跑同样的语法检查、JSON 校验、打包检查和「示例配置是否与内置默认同步」的检查。注意 plugin/package.json 里的 private 是有意保留的：插件通过路径安装，不发布到 npm。

修改默认模式、预设或归一化逻辑后，用下面的命令重新生成示例配置：

node -e "import('./plugin/config.js').then(({DEFAULT_CONFIG,normalizeConfig})=>require('node:fs').writeFileSync('examples/dsh-advisor.default.json', JSON.stringify(normalizeConfig(DEFAULT_CONFIG), null, 2) + '\n'))"

已知限制

• 草稿里带 @文件 chip 时，整段改写会把 chip 压平成文本；建议先只改纯文本。
• 行内灰字依赖 [data-composer-input] > p:last-child 结构，属于非公开 API。
• 客户端与 Host 只通过一条自定义 RPC 通道通信，因此只支持 Web GUI / Desktop，不支持纯 TUI。
• 建议不会写入会话日志，也不会消耗会话上下文。
• 插件注册的插槽（conversation.input.overlay 等）和 ctx.llm 是 DSH 的内部扩展点，DSH 升级后可能需要跟随调整。

隐私

• 没有遥测、分析或远程配置。
• 草稿和光标只存在于当前浏览器页面。请求建议时，会向你选择的模型提供商发送：当前草稿与光标位置、最近 N 条对话（默认 4 条，可设为 0）、当前模式和预设的提示、工作区路径（默认开）、时间（默认关），以及面板里输入的自定义方向。
• 请求时机：默认在每一轮 agent 输出结束且输入框为空时自动请求一次（auto.onTurnEnd）；可选在打字停顿后请求（auto.onTypingPause，默认关）；/suggest、双击 Tab 或点击 ✦ 按钮时按需请求。
• 配置保存在本机 ~/.dsh/dsh-advisor.json；建议内容不会写入会话记录。

目录

dsh-advisor/                 项目仓库
├── README.md
├── README.en.md             English README
├── LICENSE                  MIT
├── CONTRIBUTING.md          贡献指南
├── CHANGELOG.md             变更记录
├── examples/
│   └── dsh-advisor.default.json   完整默认配置
├── scripts/
│   └── check-default-config.mjs   检查示例配置是否与内置默认同步
└── plugin/                  可安装的 Harness 插件包（dsh-advisor）
├── host.js              Host：HTTP 路由、配置、上下文、模型调用
├── config.js            默认模式/预设、合并、校验与旧配置迁移
├── prompts.js           prompt 拼装、输出清洗
├── client.js            Client：灰字、面板、按钮、/suggest
├── cordis.patch.yml     Bundle patch
├── locale/              Settings/Plugins 页面元数据
└── icon.svg

贡献

欢迎 issue 和 PR。提交前请阅读 CONTRIBUTING.md，变更历史见 CHANGELOG.md，并尽量保持改动小而聚焦。

许可证

MIT © 2026 Zhikang Liu