划词注释提问 gaoxuan566/dsh-annotation

dsh-annotation

给 DeepSeek Harness 的聊天界面加一层「划词提问」：选中助手回答里的一段文字 → 点浮出的「✏️ 加为注释」→ 这段文字被收进注释托盘，显示成「注释1」「注释2」……每条注释各有各的输入框，各写各的问题，最后一起发出去。

发出去的消息里，每条注释是一个带标签的引用块，紧跟它自己的问题，模型能准确看出哪段对应哪个疑问，不用你再复制粘贴。

一、用安装包安装（推荐，无需懂代码）

前提

- Windows，已装 DeepSeek Harness 桌面版（本文按默认的 desktop profile 写）。
- 不需要装 Node.js、不需要命令行经验，照着复制粘贴即可。

第 1 步：下载

点这里下载安装包（约 14 KB）：

dsh-annotation-0.3.0.zip

也可以从 Releases 页面 手动选版本。

第 2 步：解压

右键 zip →「全部解压缩」。解压出来应该是：

dsh-annotation-0.3.0\
├─ install.ps1
├─ uninstall.ps1
├─ INSTALL.txt
└─ dsh-annotation\

一定要先解压再运行。直接在压缩包里双击 install.ps1 会找不到同目录的文件。

第 3 步：运行安装脚本

1. 打开解压出来的文件夹；
2. 点一下窗口上方的地址栏，输入 powershell 后回车（会在当前目录打开 PowerShell）；
3. 粘贴这一行并回车：

powershell -ExecutionPolicy Bypass -File .\install.ps1

（-ExecutionPolicy Bypass 只是让这一个脚本能跑，不改你系统的执行策略。）

成功的输出大致是：

backed up manifest -> C:\Users\<你>\.dsh\profiles\desktop\package.json.bak-before-annotation registered dsh-annotation in dsh.profile.bundles recorded dsh-annotation in dependencies (source: ...\dsh-annotation-0.3.0\dsh-annotation)

installed -> C:\Users\<你>\.dsh\profiles\desktop\node_modules\dsh-annotation

脚本只做四件事：备份 profile 清单、把插件目录复制进 node_modules、把 dsh-annotation 登记进 dsh.profile.bundles、在 dependencies 里记一条指向解压目录的 file: 依赖。它不改你的其他配置、不联网。

那行 file: 依赖是为了让应用把它算作"已安装"，从而出现在插件 → 已安装插件列表里。解压出来的文件夹最好留着（挪走也能用，只是列表里那条的来源路径会失效）。

第 4 步：重启应用

完全退出 DeepSeek Harness（包括右下角托盘图标 → 退出），再重新打开。客户端模块清单只在启动时构建，光刷新页面不行。

第 5 步：验证

在任意一条回答里选中一段文字，鼠标松开后旁边应出现「✏️ 加为注释」胶囊。点它 → 托盘出现「注释1」和它的专属输入框。出现了就装好了。

另外，左边栏 插件 → 已安装插件 里应该能看到一张 dsh-annotation 卡片（0.3.0），说明应用也把它当成一个正式安装的插件。

装到别的 profile / 升级 / 卸载

其他 profile（默认是 %USERPROFILE%\.dsh\profiles\desktop） powershell -ExecutionPolicy Bypass -File .\install.ps1 -Profile "D:\my-dsh\profiles\work"

升级：下新版 zip，再跑一次 install.ps1 即可（最早那份备份不会被覆盖）

卸载：重启应用前运行 powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

出问题怎么办

| 现象 | 处理 |
| 脚本报「禁止运行脚本」 | 用上面的 -ExecutionPolicy Bypass 写法，别直接双击 |
| 选字后没有胶囊 | 先确认第 4 步是"完全退出后重开"；再看是否选在了输入框里（输入框内不触发） |
| 重启后整个界面异常 | 运行 uninstall.ps1 还原清单再重启，插件坏了也不会影响应用本身（host 半边是空实现） |
| 想确认是否装上 | 打开 <profile>\package.json，dsh.profile.bundles 末尾应有 "dsh-annotation" |

二、交互说明

- 在聊天区（回答、你的提问、工具输出）里选字，松开鼠标后出现胶囊按钮。
- 点胶囊 → 这段文字记为「注释N」，托盘展开并聚焦到这条注释的提问框。
- 托盘里每条注释一块：上面是「注释N ×」标签，下面是这条注释专属的问题输入框。
- 点标签文字 = 展开/收起这段原文（默认收起，悬停也能看到）。
- 点 × = 删除该条，后面的自动重编号，已写的问题保留。
- 每条都写好问题后「发送」才可用；缺哪条会提示「注释N 还没写问题」并跳到那一行。
- 输入框里 Enter 发送，Shift+Enter 换行。
- 点「收起 ✕」或按 Esc 收起托盘，注释和问题都保留，右下角留「✏️ 注释 N」小胶囊，点它重新展开。
- 「清空」丢掉所有注释和问题。
- 在输入框（composer）里选字不会触发；单条选区超过 1000 字会被截断。

发送出去的消息：

关于你上面的回答，我有几处不明白：

注释1 第一步里 det A 是怎么算出来的？

问题1：这里为什么要单独交代一句？

注释2 为什么拆行之后大部分项都是 0？

问题2：能再展开讲讲吗？

只有一条注释时，开头是「我有个疑问：」。

三、实现方式

3.1 它是什么

一个 DSH bundle，由两个半边组成：

dsh-annotation\
├─ package.json # 声明 dsh.bundle.patch 与 dsh.client.platform = "web" ├─ dsh.bundle.patch.yml # - insert: [{ id: annotation, name: dsh-annotation }] ├─ lib\index.js # host 半边：空 apply，只让 Loader 认识这个包 └─ lib\client.js # 浏览器半边：全部 UI 与发送逻辑（无第三方依赖）

package.json 关键字段：

{
"main": "./lib/index.js",
"exports": { ".": "./lib/index.js", "./client": "./lib/client.js", "./package.json": "./package.json" },
"dsh": {
"bundle": { "patch": "./dsh.bundle.patch.yml" },
"client": { "platform": "web" }
}
}

装配顺序：profile 的 dsh.profile.bundles 列出包名 → boot 读取每个包的 dsh.bundle.patch 生成 cordis 配置 → 带 dsh.client 的包再被 client-modules 收集，页面按 /plugins/<name>/client.js 加载浏览器半边。

3.2 为什么不用槽位（slot）

DSH 的槽位（如 conversation.chat.assistant-actions）能拿到 messageId，但拿不到那条消息的文本，也没有稳定 DOM 属性可回溯到「哪条消息的哪一段」。所以这里不做 React 组件、不占槽位，而是直接监听 DOM：

- 选区来自 window.getSelection()，天然跨回答、跨工具输出；
- 会话 id 从选区锚点的 closest('[data-conversation-session]') 取；
- UI 用 document.createElement + inline style 挂到 <body>，与 React 渲染互不干扰；
- 生命周期挂在 ctx.effect(...) 返回的清理函数里，插件卸载时移除所有监听与节点。

3.3 浏览器半边的代码结构

模块外壳（DSH 客户端模块格式）：

window.__ModuleLoader__.load({
id: "dsh-annotation",
factory: (require) => {
function apply(ctx) { /* ... */ }
return (module.exports = { apply, inject: ["sessions"] });
},
});

inject 只依赖 sessions 服务。发送消息：

ctx.get("sessions").scope(sessionId).get("conversation").send(text);

要点：conversation 是 root 服务，但它的方法会绑定到调用方 ctx，所以必须从
sessions.scope(id) 拿 scope 版；直接 ctx.get("conversation").send() 会抛
conversation.send requires a session scope。

状态与拼装：

- items: [{ text, question }]、previewIndex、expanded、sessionId；
- buildMessage(items) 生成上文格式：首行按条数选「我有个疑问」/「我有几处不明白」，每条 注释N + > 引用块 + 空行 + 对应问题，引用按行加 >，超长截断；
- 发送前校验每条的 question，缺则 toast「注释N 还没写问题」并聚焦该行。

样式用 DSH 主题变量并给回退值，深浅色自动跟随：

--dsw-alias-bg-layer-2 / --dsw-alias-label-primary / --dsw-alias-label-secondary
--dsw-alias-border-l3 / --dsw-alias-state-business-primary / --dsw-elevation-prominent
--dsw-radius-lg / --dsw-font-family

3.4 开发与回归

改 lib/client.js 后刷新页面（Ctrl+R）就会加载新代码；改了 lib/index.js 或 package.json 才需要重启应用。

回归测试不发真实消息：用 fake DOM + vm.runInContext 直接跑 lib/client.js，断言选区 → 胶囊 → 托盘、逐行输入框、缺问题禁用发送、消息拼装顺序、删除重编号、预览、 Esc/徽章/清空、清理函数等 45 项。

四、手动安装（不用安装包）

安装 = 把包目录放进 profile 的 node_modules + 在 dsh.profile.bundles 登记包名。

1. 备份 <profile>\package.json；
2. 克隆本仓库到 <profile>\node_modules\dsh-annotation；
3. 编辑 <profile>\package.json，在 dsh.profile.bundles 末尾追加 "dsh-annotation" （UTF-8 无 BOM）：

{ "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-annotation"] } } }

4. 完全退出并重开应用。

五、卸载

用 uninstall.ps1（优先还原安装时的备份），或手工把 bundles 里的 dsh-annotation 删掉并删除 <profile>\node_modules\dsh-annotation，然后重启应用。

License

MIT