- Accueil
- Plugins
- Outils et capacités
- dsh-click
dsh-click
perrylink/dsh-click
Outils d'utilisation d'ordinateur de bureau Windows (click, type, key, screenshot) avec vérifications d'actualisation, validation par approbation, vérification de l'identité du processus autour de chaque action et piste d'audit nettoyée.
Installer
dsh plugin --profile web add github:perrylink/dsh-clickREADME
dsh-click
让模型看见屏幕、动手操作——每个变更动作都过审批,每次观察与操作都留审计。
面向 DeepSeek Harness 的原生桌面控制插件(Windows 优先):无障碍树与像素提示让纯文本模型也能“看”,窗口级点击与输入让模型“动”,审批、新鲜度与进程身份校验守在中间。
安装 · 配置 · FAQ · 简体中文 · English · Español · Português · हिन्दी
dsh plugin --profile <name> add dsh-click
社区插件,与 DeepSeek 官方无关。唯一仓库:https://github.com/PerryLink/dsh-click(Gitee 为镜像)。
它是什么
dsh-click 给模型一条完整的「观察 → 行动」通道:先用 screen_read 读窗口的无障碍树(元素 id、类型、名称、矩形、支持的模式)与像素位置提示,或用 screen_shot 截一张图;再用 click / type / scroll / key 按元素 id 或坐标操作同一个窗口。每个变更性动作都必须引用一次新鲜观察(basedOn)——屏幕变了或观察过期就拒绝,并给出模型可读的理由;默认还要过 ctx.approval 审批,动作前后各校验一次目标进程身份。它默认不抢前台焦点(focusFallback: never),所有观察与操作都落成脱敏的 dsh-click/observed / dsh-click/action 审计事件。
三步上手
-
安装(三选一):
# git 渠道(最新 main;等价于 git+https://github.com/PerryLink/dsh-click.git) dsh plugin --profile web add github:PerryLink/dsh-click # npm 渠道(已发布版本) dsh plugin --profile web add dsh-click # tarball 渠道:本仓库 pnpm pack 后 dsh plugin --profile web add ./dsh-click-<version>.tgzgit 渠道的
prepare脚本只用生产依赖构建。 -
最小配置(默认即可用;只对特定窗口免审批时再动
autoApproveWindows):- insert: - id: dsh-click name: dsh-click config: requireApproval: true autoApproveWindows: ['^Notepad'] focusFallback: never -
验证已生效(重启后):
dsh --profile web --dump-config | grep -A3 'id: dsh-click'然后让 agent 观察窗口并操作——每次变更性操作都会弹出审批:
> 打开记事本,输入 "hello",再读回屏幕上的内容。
卸载:dsh plugin --profile web remove dsh-click(或从 profile patch 删掉该行)。
如果 pnpm 对本包报
ERR_PNPM_IGNORED_BUILDS(esbuild 的平台二进制无害校验),在你的pnpm-workspace.yaml中加入allowBuilds: { esbuild: true }——dshCLI 会打印确切片段。
从 DSH Desktop 市场安装
所有 PerryLink 插件均可在 DSH Desktop 内置市场中浏览:市场 → 来源 → 添加来源 → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选中。安装仍需通过市场的 npm 身份校验与你的确认。
核心能力
dsh-click 把原生桌面拆成可审计的观察面与动作面:
screen_shot—— 截取窗口(或主屏幕),按maxScreenshotSide缩放。窗口截图优先走PrintWindow(PW_RENDERFULLCONTENT),不受其它窗口遮挡影响;结果里的captureMethod写明实际路径。模型支持图像时结果附带图片;纯文本模型则得到文字描述,照常可用。screen_read—— 结构化观察:无障碍树(元素 id、类型、名称、矩形、支持的模式)加像素位置提示与颜色 —— 纯文本,无需图像模型。screen_find—— 对没有无障碍树的应用,用可选 OCR(ocr.*,挂载时探测 tesseract)或视觉 grounding 按文字/描述找可点目标,返回屏幕坐标与observationId;只读,不需要审批。click/type/scroll/key—— 以元素 id 或坐标寻址的窗口级操作。优先 UIA invoke,回退到 post 窗口消息,且默认绝不抢占前台焦点;type走 UIAValuePattern快路径,失败再用SendInput注入真实按键(CJK 安全);key对忽略 post 输入的应用会大声拒绝。app_list/app_launch—— 枚举运行中的应用及其可见窗口(最小化窗口标minimized: true且不返回rect);按名称或可执行路径启动应用。
每个变更性操作都穿过同一条安全边界:
- 新鲜度 —— 操作必须引用
basedOn观察;执行前重新捕获窗口,像素哈希(staleCheckPixels)或控件树(staleCheckTree)变化、或观察超过maxObservationAgeMs,即拒绝并要求重新观察。 - 审批 —— 默认经
ctx.approval门禁;autoApproveWindows的窗口标题/可执行路径正则可放行特定窗口(仍做新鲜度与进程身份校验,仍记录审计)。 - 进程身份 —— 操作前后分别校验所属进程 pid 与可执行路径;中途换进程即大声拒绝(
PROCESS_CHANGED)。 - 审计 —— 观察与操作以
dsh-click/observed/dsh-click/action事件写入会话日志(脱敏、仅日志)。
模型 harness
│ screen_read ──▶ observationId (+ 元素、像素) ← 结构化文本
│ click {basedOn, target} ──▶ 新鲜度校验 ──▶ 审批 ──▶ helper (UIA)
│ 像素哈希变化? ── 拒绝 + 要求重新观察
│ 操作后 pid/exe 变化? ── PROCESS_CHANGED
│ ◀── 规范 JSON + 审计事件 (dsh-click/action)
工具面
| 工具 | 只读 | 需要审批 | 说明 |
|---|---|---|---|
screen_shot | ✅ | — | 返回 observationId 供后续操作在 basedOn 中引用;模型支持图像时附带图片 |
screen_read | ✅ | — | 无障碍树 + 像素提示;元素 id 是操作的寻址方式 |
screen_find | ✅ | — | 无 UIA 树时的 OCR/视觉定位;返回坐标目标 + observationId |
click | ✅ | elementId 与 (x, y) 二选一;优先 UIA invoke,回退 post 消息 | |
type | ✅ | 仅限 value 模式元素;失败时备份并还原控件文本 | |
scroll | ✅ | 元素(scroll 模式)或窗口(post 滚轮) | |
key | ✅ | post 按键组合("Ctrl+S");忽略 post 输入的应用会大声拒绝 | |
app_list | ✅ | — | 运行中的应用及其可见窗口 |
app_launch | ✅ | 按名称或可执行路径启动,可带参数 |
截图与坐标空间
- 带
target才是窗口截图;不带target抓的是主屏(snapshot.windowId = 0、title = "primary screen"),不是前台窗口。要整个虚拟桌面(多屏,含负坐标)请传scope: "virtual";该模式标注为实验性,多屏几何尚未完整验证。 - 窗口截图先走
PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT):窗口自己绘制,不受其它窗口遮挡影响;失败或空图时依次回退PrintWindow(0)与CopyFromScreen。结果里的captureMethod为printwindow-fullcontent/printwindow/copyfromscreen,直接说明这张图是怎么来的。 width/height是位图尺寸,不是窗口尺寸:它们已被maxScreenshotSide下采样;snapshot.rect始终是物理像素的窗口(或屏幕)矩形。换算方式:bitmapX = (screenX - rect.x) * width / rect.width。- 所有矩形都是物理像素:DPI 感知在 helper 启动时设置(Per-Monitor V2),
app_list、screen_read、screen_shot与click共用同一坐标空间。 - 最小化窗口:
app_list标记minimized: true并且不返回rect(Windows 在最小化时给的是-32000占位矩形);screen_shot/screen_read对它明确报WINDOW_MINIMIZED,请先还原窗口。
示例
以下为插件真实入口;安装后调用一个即可。
详细示例 — 命令 app_list,输入:
{}
输出:
1 running application(s) with windows:
- Demo (pid 4242, C:\Apps\demo.exe)
- [windowId 1122867] "Demo App" at (10, 20) 800x600
Observed from plugins/dsh-click/tests/tools.spec.ts:159-185; renderer at src/tools.ts:933-942
失败分支 — 输入:
{}
输出:
Error: dsh-click backend unavailable on linux: Linux backend is reserved but not implemented yet (Windows-first); only Windows can act today
Observed from plugins/dsh-click/src/platform/selection.ts:61-62,81; plugins/dsh-click/src/tools.ts:133-136; plugins/dsh-click/tests/tools.spec.ts:226-245
简短示例:screen_read · app_list
配置
所有可调项都是 Schemastery Config 字段(可在 cordis.yml 中修改)。按 id 定向覆盖会替换整行 —— 需要重述每个键。cordis.patch.yml 逐键内联注释。
最常用键:
| 键 | 默认值 | 含义 |
|---|---|---|
requireApproval | true | 每个变更性操作都过审批;观察类工具从不询问 |
autoApproveWindows | [] | 跳过审批询问的窗口标题/可执行路径正则(仍做新鲜度与进程身份校验,仍记录审计) |
focusFallback | never | 操作是否可在最后手段下把目标窗口带到前台(never / allow) |
imageMode | auto | screen_shot 渲染:auto(模型支持图像时附图像,否则文字)或 text |
staleCheckPixels | true | 每次操作前对比新像素哈希,变化即拒绝 |
staleCheckTree | target | 控件树新鲜度:target 校验目标元素(默认),strict 任一节点变化即拒绝,off 跳过整树哈希(身份/年龄/像素检查仍生效) |
maxObservationAgeMs | 30000 | 操作可引用观察的最大时限(毫秒,1000..600000) |
auditSessionEvents | true | 是否追加 dsh-click/observed / dsh-click/action 审计事件;设为 false 可完全停止审计追加 |
完整配置表(17 行)
| 键 | 默认值 | 含义 |
|---|---|---|
requireApproval | true | 每个变更性操作都过审批;观察类工具从不询问 |
autoApproveWindows | [] | 跳过审批询问的窗口标题/可执行路径正则(仍做新鲜度与进程身份校验,仍记录审计) |
auditSessionEvents | true | 追加 dsh-click/observed / dsh-click/action 会话审计事件。自适应门已在无信封宿主(rc.6–rc.8、0.1.1-rc.2,以及对未知类型读取即失败的 0.1.2-rc.1)上跳过追加;设为 false 可完全停止审计追加。0.1.2-rc.1(2026-09-02 已适配):会话信封保留 ignorable 字段但仅用于存量日志读取兼容——Session.append 仍无法盖章,门控行为不变 |
focusFallback | never | 操作是否可在最后手段下把目标窗口带到前台(never / allow) |
imageMode | auto | screen_shot 渲染:auto(模型支持图像时附图像,否则文字)或 text |
helperTimeoutMs | 30000 | 每次 helper 调用的超时(毫秒,1..300000) |
maxHelperOutputBytes | 25165824 | 单次 helper 响应的字节上限(1024..67108864) |
maxScreenshotSide | 2560 | 截图最长边像素(320..7680);超出即缩放 |
staleCheckPixels | true | 每次操作前对比新像素哈希,变化即拒绝 |
staleCheckTree | target | 控件树新鲜度:target 校验目标元素(默认),strict 任一节点变化即拒绝,off 跳过整树哈希(身份/年龄/像素检查仍生效) |
maxObservationAgeMs | 30000 | 操作可引用观察的最大时限(毫秒,1000..600000) |
maxCachedObservations | 8 | 观察缓存 LRU 上限(1..64) |
maxElements | 500 | 每次 screen_read 的无障碍元素上限(1..2000) |
maxTreeDepth | 32 | 无障碍树遍历最大深度(1..64) |
maxTextLength | 200 | 脱敏后模型可见字符串的截断长度(16..10000) |
rollbackEnabled | true | type 失败时备份并还原控件文本 |
ocr.enabled / command / language | true / tesseract / eng | screen_find 的可选 OCR(挂载时探测;无 tesseract 时降级为不可用) |
profile patch 中的覆盖示例:
- insert:
- id: dsh-click
name: dsh-click
config:
requireApproval: true
autoApproveWindows: ['^Notepad']
focusFallback: never
FAQ
截图和观察缓存存在哪?会不会把屏幕内容写到磁盘?
screen_shot 的截图存进 harness 的 attachment store(内容寻址,受宿主附件策略约束),并只随该次工具结果提供给你正在用的模型。观察本身只在内存里(maxCachedObservations 有界 LRU,重启即失);除此之外插件不落盘、不发网络请求、不存凭据。落进会话日志的只有 dsh-click/* 审计事件,窗口标题、可执行路径与自由文本在写入或展示前先脱敏并截断。
在 macOS / Linux 上会怎样?会静默失败吗?
不会静默。这两个平台的后端已预留但未实现,每次调用都以模型可读的原因失败关闭(dsh-click backend unavailable on linux: ...);profile 在哪个平台都能正常启动。Windows 上若缺 subprocess 服务或 helper 不可用,同样大声拒绝,而不是假装成功。
会和其他插件抢命令、服务或 slot 吗?
不提供任何 service key,只消费两个可选 seam(dsh-click/backend、dsh-click/grounding,测试/嵌入用);不注册客户端 slot、不注册 webServer 路由、不装任何 waterfall 监听器;审计事件全部落在 dsh-click/* 命名空间。每次工具注册都包在 ctx.effect 里,停止/热重载只撤销自己注册的工具。
性能开销多大?每次动作都要重新截图吗?
观察按需产生:screen_read 只读无障碍树(纯文本),screen_shot 才编码 PNG。每次变更性动作前会重新捕获一次目标窗口做新鲜度对比(默认像素哈希 + 控件树),这是安全边界的一部分;helper 调用有 helperTimeoutMs / maxHelperOutputBytes 兜底,观察缓存默认只留 8 条。
安全边界
- 先观察后行动,每次如此。 操作必须引用新鲜观察;屏幕变化(像素哈希)或观察过期即拒绝,并以模型可读的原因要求重新观察。
- 审批是默认。 除非你显式放行特定窗口,否则
requireApproval: true;每次操作 —— 无论放行与否 —— 都记录审计。 - 不抢前台焦点。 helper 从不把目标窗口带到前台(默认
focusFallback: 'never');输入经 UIA 或 post 消息送达,不打扰后台窗口。focusFallback: 'allow'是唯一被认可的例外。 - 进程身份前后复验。 每个操作前后立即校验进程身份;操作中途进程被替换则判失败(
PROCESS_CHANGED)。 - 输出脱敏。 控制字符被剥离、制表符折叠、凭据形态内容(密钥、token、JWT、bearer 头)在到达模型或日志前一律打码。
- 失败关闭。 不支持的平台、缺失的 subprocess 服务或不可用的 helper 都会大声拒绝每个调用 —— profile 在任何地方都能正常启动。
权限与数据
- 权限:变更性操作走官方
ctx.approval接缝 —— 插件从不重实现或绕过它。autoApproveWindows只会对特定窗口跳过询问,不能关闭新鲜度或进程身份校验。dshWorkshopmanifest 声明fs:read、subprocess:spawn、session:append、network:none、native-code:none。 - 数据:除 attachment store 保存的截图(内容寻址、受 harness 自身附件策略约束)外,插件不落盘任何东西。观察仅存内存(有界 LRU)。无网络请求,不存凭据。
- 会话日志:
dsh-click/observed与dsh-click/action是仅日志的审计事件,携带脱敏后的窗口/进程事实 —— 标题、路径与自由文本在写入或展示前均先脱敏并截断。
已知限制
- Windows 优先。 macOS 与 Linux 后端已预留;在这些平台上每次调用都以明确原因失败关闭。
- 纯文本保真度。
screen_read依赖应用暴露 UIAutomation;没有无障碍树的应用只有像素提示与screen_find的 OCR/grounding 路径。坐标点击仍然可用。 - post 输入类应用。 部分应用忽略 post 窗口消息(游戏、部分 Electron 界面);
key会如实报告而非假装成功。0.3.24 起type的SendInput回退覆盖了真实键盘输入与 CJK 混排,但仍受目标应用自身的输入模型限制。 - 无信封 harness 构建上的会话审计。 审计事件走自适应门:认识该词汇的宿主直接追加,带
ignorable信封的宿主带标记追加,无信封宿主——0.1.0-rc.6–0.1.0-rc.8、0.1.1-rc.2以及无法盖章 ignorable 标记(信封字段仅为存量日志读取兼容而保留)且对未知类型读取即失败的0.1.2-rc.1——不追加审计事件;工具结果仍是可重建的审计轨迹。设auditSessionEvents: false可完全停止审计追加。
与其他 DSH 插件的互操作性
dsh-click 只暴露工具面,不参与其他插件的接缝:
- 只注入两个硬服务。
inject = ['tools', 'subprocess'];不提供任何 service key,因此不存在服务键冲突。 - 不占客户端与 HTTP 资源。 不注册客户端 slot、不注册
webServer路由、不装agent/pre-step/tools/post-execute等 waterfall 监听器,也不改全局对象。 - 审计命名空间隔离。 只写
dsh-click/observed与dsh-click/action两个事件;宿主不认识该词汇时自适应门直接跳过,工具结果仍是可重建的审计轨迹。 - 可选 seam 可缺省。
dsh-click/backend与dsh-click/grounding只服务测试/嵌入;真实部署缺省回退到平台选择,不要求任何其他插件在场。 - 注册即 effect。 每次
ctx.tools.register都包在ctx.effect里,停止/热重载只撤销自己注册的工具。
兼容性
| 维度 | 状态 |
|---|---|
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1(GitHub tag,2026-09-25 已核验)。已于 2026-09-11 对照 dsh-v0.1.7-alpha.1 master checkout 核验(完整门禁链 + profile 安装冒烟)。engines.dsh:>=0.2.1-0 <0.3.0 || >=0.2.2-0 <0.3.0 |
| Node | ^22.19.0 || >=24.9.0 |
| 平台 | Windows 优先(UIAutomation + Win32 输入,经内置 PowerShell helper);macOS/Linux 后端已预留,失败时以明确原因关闭 |
| 模型 | 纯文本模型完整可用(screen_read 输出结构化文本);视觉模型额外获得 screen_shot 图像 |
生态与质量
- Gitee 镜像(同步镜像,以 GitHub 为准)
- dshfind 插件页(安装量与排名)
- OpenSSF Scorecard 报告(由 .github/workflows/scorecard.yml 驱动)
- dsh-plugin-doctor 验证报告(K10–K13 全
pass) - DSH Market(已上架)
- 1024 商店渠道:先
npm i -g dsh1024,再dsh1024 plugin --profile web add dsh-click(计入 deepseek1024.com 安装排行) - 生态实测知识库:插件开发指南 · 选型实测数据 · 维护取舍判据
开发
pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc:src + tests,对照本地 harness checkout
pnpm run typecheck:ci # tsc:对照已发布的宿主类型(无 paths)
pnpm test # vitest:79 个测试、13 个文件(helper 冒烟在 Windows 上运行)
pnpm run build # tsdown bundle + tsc 声明(lib/)
pnpm run verify:self-contained # 依赖声明全部来自 registry
pnpm run verify:artifacts # 构建产物 ESM 面 + 原生 helper 齐全
pnpm run check:readmes # 五语 README 一致性
pnpm pack # 发布用 tarball
配图由 scripts/gen-readme-assets.py 程序化生成(Python + Pillow),可重复执行:python scripts/gen-readme-assets.py。
Topics:dsh, dsh-plugin, deepseek-harness, deepseek, cordis, computer-use, windows-automation, uiautomation, desktop-control, screen-reader
家族与致谢
本项目是 PerryLink 维护的 DeepSeek Harness 插件家族成员(全部 Apache-2.0)。如果这个插件帮到了你,给个 star —— 它不解锁任何功能,但会让下一个人更容易找到它。
- Windows helper 冒烟清单 —— 0.3.24+ 的真实输入/焦点验证步骤。
- @LIU12312-Source —— Windows helper 的真实
SendInput/ 前台聚焦回退(PR #21)。 - @Mchsd —— 为会话读取器拒绝
dsh-click审计事件的主机新增auditSessionEvents退出开关(#2)。 - @PerryLink —— 创建者与维护者:工具面、操作安全边界、Windows 原生 helper、脱敏层与五语文档。
展开全部插件
License
LICENSE(Apache License 2.0)© 2026 dsh-click contributors
Apache-2.0 · 社区插件,与 DeepSeek 无关。
Plugins associés
archify (deepseek-harness)
tt-a1i/archify
WeKnora (dsh-weknora)
tencent/weknora
next-ai-draw-io (dsh-plugin)
dayuanjiang/next-ai-draw-io
weknora
tencent/weknora