前言¶
做智能体开发时常见的一类场景：屏幕上弹了个报错窗口，得切窗、复制、粘贴、描述；或者一张图表、一段公式、一张外文截图，想就着它继续问。传统做法是把截图丢进聊天窗口，再打字描述一遍，问题和图对不上。
waterfish111 维护的 dsh-glance（一瞥 / Glance）就是针对这个动作的 DSH Desktop 本地插件。点会话标题栏的「一瞥」，屏幕角落出现一个置顶悬浮球；点球框选任意区域，截图直接发给多模态模型，流式分析显示在悬浮面板里，之后追问只发文字、不再重传图。
它解决的问题很明确：把「截图 + 描述上下文」压缩成「框一下，问一句」。但它不适合批量的文字 OCR、长文档总结，也只支持 Windows。
下面按实际资料介绍这个插件能做什么、怎么装、怎么用，以及哪些地方会踩坑。
核心能力¶
dsh-glance 是 DSH Desktop 的本地 profile 插件，核心流程只有两步：框选屏幕区域，然后就着这张图提问。能力都围绕这个展开。
悬浮球支持：左键单击进入框选，拖动换位置不误触发，右键菜单提供更换外观 / 恢复默认外观 / 悬浮球大小 / 退出。悬浮球大小有 4 档：小 72、标准 84、大 96、特大 108（DIP），选择立即生效并写进 settings.json，下次启动沿用。
面板支持：首轮发送带截图，之后输入变成追问，只带文字、复用同一条线索；「停止」真正调用 sessionController.cancel 中断 Harness 里这一轮，已生成部分保留并标注「已停止」；「重新框选」换一张图、开一条新线索；标题栏可以换外观、收起面板。
命令行侧有三条：
/glance 或 /glance status 查询是否在运行
/glance on 启动悬浮球（幂等）
/glance off 关闭悬浮球
技术路线上没有 OCR、没有本地推理：截图以 base64 直接进模型上下文，发给专用会话，再用 sessionController.follow 把流式回答回灌到面板。三个进程之间是三条单向管道：index.js（Host）通过 stdin/stdout 与 widget.ps1（PowerShell + WinForms）通信，widget.ps1 内嵌 WebView2 跑 panel.html，client.js 每 2 秒向 /api/local/dsh-glance/status 轮询真实状态，然后把按钮状态反映到标题栏。
安装与启用¶
环境要求先确认，否则装完会卡在运行阶段：
| 项 | 要求 |
|---|---|
| 系统 | Windows 10 / 11 |
| 宿主 | DSH Desktop（本地 profile 插件机制） |
| 运行时 | Microsoft Edge WebView2 Runtime（Win11 通常自带，Win10 可能需手动装） |
| 脚本 | Windows PowerShell 5.1（系统自带，widget.ps1 依赖它） |
| 模型 | 默认的 DeepSeek-V4.1-Flash 原生支持图片，不需要额外装插件；换成纯文本模型会失败 |
把仓库放到任意本地目录（不要放在需要管理员权限的位置），然后执行：
dsh plugin --profile desktop add 'link:D:/path/to/dsh-glance'
打开 %USERPROFILE%\.dsh\profiles\desktop\package.json，确认 dsh.profile.bundles 数组里有 "@local/dsh-glance"，没有就加一行：
"dsh": { "profile": { "bundles": [ "...", "@local/dsh-glance" ] } }
注意：只写进 dependencies 不会加载，dsh.profile.bundles 才是决定加载哪些 bundle 的层列表；重复一遍，这一步不做，重启后标题栏不会有「一瞥」按钮。
重启 DSH Desktop，会话标题栏出现「一瞥」按钮即安装成功。
典型用法¶
第一次使用按下面顺序走一遍：
- 点标题栏「一瞥」→ 屏幕出现悬浮球，按钮变成「运行中」
- 点悬浮球 → 屏幕冻结，拖出要分析的矩形
- 面板里看截图，可写一句补充说明（「这报错什么意思」／「帮我改这个 UI」）
- 点「发送」→ 回答流式出现在「分析结果」里
- 接着输入 → 按钮变「追问」→ 只发文字，不再重传截图
一次框选等于一条线索。新截图自动开新会话，追问复用同一条；会话标题带时间（一瞥 · 11-05 19:32），方便事后在 DSH 会话列表里翻回旧线索。同一张图追问到第 6 轮会给一句软提示，提醒换话题时重新框选。
停止与重框是最常用的两个干预动作：想中断当前分析点「停止」，想换一张图点「重新框选」。被中断的回答可能缺结尾，因为已经进入的消息不会撤回。
数据放在哪¶
插件的本地状态都在 %LOCALAPPDATA%\dsh-glance\ 下，日志在 %TEMP%：
| 位置 | 内容 |
|---|---|
%LOCALAPPDATA%\dsh-glance\state.json |
当前线索（v2：sessionId / title / startedAt / turns） |
%LOCALAPPDATA%\dsh-glance\settings.json |
悬浮球大小，形如 {"ballSize":96} |
%LOCALAPPDATA%\dsh-glance\ball.png |
自定义的悬浮球图片 |
%LOCALAPPDATA%\dsh-glance\WebView2\ |
WebView2 用户数据目录 |
%TEMP%\glance-host.log |
宿主侧日志（命令、会话创建、取消、失败原因） |
%TEMP%\glance-widget.log |
小部件侧日志（DPI、框选、WebView2 初始化、菜单动作） |
状态文件旧格式（v1，扁平 {sessionId,title}）会在首次启动时自动升级。日志只记流程与错误，不记截图内容。
适用场景与注意¶
适合：Windows 10/11 + DSH Desktop 环境，遇到报错弹窗、公式推导、图表、UI 修改、外文截图这类「看一眼就能接着问」的场景。不适合：需要批量文字提取的 OCR、需要长文档总结的场景、非 Windows 环境。
几点使用上的限制需要注意：
- 面板只展示当前这一条线索，之前的问答收成可点开的气泡，更早的线索要去 DSH 会话列表里找
- 「停止」中断的是 Harness 这一轮，但不会撤回已经进入队列的消息；发送失败会自动重试一次，模型侧可能看到重复提问
- 分析会话在 DSH 里被删掉时，插件会自动新建并在面板顶部提示，旧上下文不再保留
- 自定义外观只做等比缩放：图片不是正方形时四周留空，小于 128×128 会被放大变糊；且不区分悬停态
- 标题栏按钮每 2 秒轮询一次，从球菜单退出后按钮最多 2 秒才变回「一瞥」
- 宿主与 widget 之间没有协议版本握手：如果两者版本不一致（例如只更新了一半），不会明确报「版本不匹配」
排错时先看日志。标题栏没按钮，检查 dsh.profile.bundles 里有没有 @local/dsh-glance，然后重启 DSH；球没出来，看 glance-host.log 与 glance-widget.log 的最后几行，最常见是 WebView2 Runtime 缺失或 widget.ps1 被安全软件拦截；球在但点不动，首次初始化 WebView2 需要一两秒，仍无反应再看 glance-widget.log 的 webview init 行。
分析一直失败多半是当前会话选的模型不接受图片输入。默认的 DeepSeek-V4.1-Flash 在 DSH 内置模型目录里声明了 inputModalities: ["text", "image"]，开箱即用；换成纯文本型号图片会被直接拒收，换回带视觉的模型即可。面板会显示具体错误，据此区分「模型不收图片」和「网络/鉴权失败」。
隐私方面：截图只发送到你在 DSH 里配置的模型服务商，插件不向其他服务上传；屏幕捕获只在主动框选时发生，不后台持续截屏；插件本体不额外落盘截图（-SelfTest 自测模式除外）。
卸载两步：
dsh plugin --profile desktop remove @local/dsh-glance
再从 dsh.profile.bundles 里删掉 "@local/dsh-glance"，重启 DSH。本地数据 %LOCALAPPDATA%\dsh-glance\ 可留可删。
版本与开发¶
当前版本 0.5.2（beta），许可证 MIT。采样几个版本节点理解演进方向：0.5.0 引入「一次框选一条线索」的会话生命周期、面板多轮气泡、停止保留文本；0.4.2 让「停止」真正中断 Harness 这一轮；0.4.0 实现追问不再重传截图、DPI 面板尺寸；0.3.0 改名「一瞥 / Glance」，引入 WebView2 面板与流式分析。
源码结构如下，开发前值得先读：
index.js Host 半：命令、会话、子进程、图片 prompt、流式回传
client.js Web 半：标题栏启动按钮 + 状态轮询
widget.ps1 原生小部件：悬浮球、冻结框选、WebView2 面板宿主
panel.html 面板页面（单文件 HTML/CSS/JS）
cordis.patch.yml DSH bundle 声明
webview2/ vendored WebView2 SDK（Core / WinForms / Loader）
test/ 回归测试
测试命令：
npm run check # 一键：JS 语法 + 宿主协议/停止链路 + 面板脚本编译
npm test # 只跑测试（9 项断言 + 面板内联脚本）
powershell -STA -File .\widget.ps1 -SelfTest # 小部件自测：起面板、截图、退出，exit 0 为通过
开发时有三条硬约束：widget.ps1 必须保持 UTF-8 带 BOM（PowerShell 5.1 读无 BOM 文件会按 ANSI 解码，中文变乱码且解析失败）；宿主与 widget 之间的消息是裸 JSON 行，改协议要同时改 index.js、widget.ps1、panel.html 三处；改完 widget.ps1 要重启 DSH，因为宿主把脚本作为子进程常驻，不会热更新。
结尾¶
dsh-glance 的取舍很清楚：不碰 OCR、不做本地推理、不引入额外依赖，只把「截图 + 上下文」这件事压到最小路径，代价是常驻悬浮球、只支持 Windows，以及面板只保留当前线索。对日常要看报错、图表、UI 的开发者来说，这个代价换来的是省掉一次切窗加复制粘贴。
目录页：https://www.skillhub.cn/plugins/waterfish111/dsh-glance
仓库：https://github.com/waterfish111/dsh-glance
完整说明见仓库 docs/MANUAL.md，更新日志见 CHANGELOG.md。安装前建议自己过一遍源码，确认它符合你的模型服务商配置。
