Vai al contenuto principale
P

dsh-click

perrylink/dsh-click

Strumenti di uso del computer desktop per Windows (click, type, key, screenshot) con controlli di freschezza, approvazione obbligatoria, verifica dell'identità del processo per ogni azione e una traccia di audit sanitizzata.

Installazione

dsh plugin --profile web add github:perrylink/dsh-click

README

dsh-click:窗口的无障碍元素(e12 Edit、e13 Button)经 screen_read 变成 observationId,动作以 basedOn 引用它,穿过新鲜度、审批与进程身份安全边界,由 Windows UIA helper 执行,并写入 dsh-click/observed 与 dsh-click/action 审计事件

dsh-click

让模型看见屏幕、动手操作——每个变更动作都过审批,每次观察与操作都留审计。

面向 DeepSeek Harness 的原生桌面控制插件(Windows 优先):无障碍树与像素提示让纯文本模型也能“看”,窗口级点击与输入让模型“动”,审批、新鲜度与进程身份校验守在中间。

安装 · 配置 · FAQ · 简体中文 · English · Español · Português · हिन्दी

License DSH npm CI Node

Stars npm downloads dshfind OpenSSF Scorecard DSH Market Gitee

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 审计事件。

dsh-click 的边界双侧结构:左侧只读观察面(screen_read / screen_shot / screen_find / app_list)产出 observationId;中间 SAFETY BOUNDARY 依次校验 basedOn、新鲜度、审批、helper 派发与进程身份,拒绝路径回到重新观察;右侧变更动作面(click / type / scroll / key / app_launch)经 helper 作用于目标窗口;底部是 dsh-click/observed 与 dsh-click/action 两条脱敏审计事件

三步上手

  1. 安装(三选一):

    # 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>.tgz
    

    git 渠道的 prepare 脚本只用生产依赖构建。

  2. 最小配置(默认即可用;只对特定窗口免审批时再动 autoApproveWindows):

    - insert:
        - id: dsh-click
          name: dsh-click
          config:
            requireApproval: true
            autoApproveWindows: ['^Notepad']
            focusFallback: never
    
  3. 验证已生效(重启后):

    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 } —— dsh CLI 会打印确切片段。

从 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 走 UIA ValuePattern 快路径,失败再用 SendInput 注入真实按键(CJK 安全);key 对忽略 post 输入的应用会大声拒绝。
  • app_list / app_launch —— 枚举运行中的应用及其可见窗口(最小化窗口标 minimized: true 且不返回 rect);按名称或可执行路径启动应用。

每个变更性操作都穿过同一条安全边界:

  1. 新鲜度 —— 操作必须引用 basedOn 观察;执行前重新捕获窗口,像素哈希(staleCheckPixels)或控件树(staleCheckTree)变化、或观察超过 maxObservationAgeMs,即拒绝并要求重新观察。
  2. 审批 —— 默认经 ctx.approval 门禁;autoApproveWindows 的窗口标题/可执行路径正则可放行特定窗口(仍做新鲜度与进程身份校验,仍记录审计)。
  3. 进程身份 —— 操作前后分别校验所属进程 pid 与可执行路径;中途换进程即大声拒绝(PROCESS_CHANGED)。
  4. 审计 —— 观察与操作以 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 逐键内联注释。

最常用键:

键默认值含义
requireApprovaltrue每个变更性操作都过审批;观察类工具从不询问
autoApproveWindows[]跳过审批询问的窗口标题/可执行路径正则(仍做新鲜度与进程身份校验,仍记录审计)
focusFallbacknever操作是否可在最后手段下把目标窗口带到前台(never / allow)
imageModeautoscreen_shot 渲染:auto(模型支持图像时附图像,否则文字)或 text
staleCheckPixelstrue每次操作前对比新像素哈希,变化即拒绝
staleCheckTreetarget控件树新鲜度:target 校验目标元素(默认),strict 任一节点变化即拒绝,off 跳过整树哈希(身份/年龄/像素检查仍生效)
maxObservationAgeMs30000操作可引用观察的最大时限(毫秒,1000..600000)
auditSessionEventstrue是否追加 dsh-click/observed / dsh-click/action 审计事件;设为 false 可完全停止审计追加
完整配置表(17 行)
键默认值含义
requireApprovaltrue每个变更性操作都过审批;观察类工具从不询问
autoApproveWindows[]跳过审批询问的窗口标题/可执行路径正则(仍做新鲜度与进程身份校验,仍记录审计)
auditSessionEventstrue追加 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 仍无法盖章,门控行为不变
focusFallbacknever操作是否可在最后手段下把目标窗口带到前台(never / allow)
imageModeautoscreen_shot 渲染:auto(模型支持图像时附图像,否则文字)或 text
helperTimeoutMs30000每次 helper 调用的超时(毫秒,1..300000)
maxHelperOutputBytes25165824单次 helper 响应的字节上限(1024..67108864)
maxScreenshotSide2560截图最长边像素(320..7680);超出即缩放
staleCheckPixelstrue每次操作前对比新像素哈希,变化即拒绝
staleCheckTreetarget控件树新鲜度:target 校验目标元素(默认),strict 任一节点变化即拒绝,off 跳过整树哈希(身份/年龄/像素检查仍生效)
maxObservationAgeMs30000操作可引用观察的最大时限(毫秒,1000..600000)
maxCachedObservations8观察缓存 LRU 上限(1..64)
maxElements500每次 screen_read 的无障碍元素上限(1..2000)
maxTreeDepth32无障碍树遍历最大深度(1..64)
maxTextLength200脱敏后模型可见字符串的截断长度(16..10000)
rollbackEnabledtruetype 失败时备份并还原控件文本
ocr.enabled / command / languagetrue / tesseract / engscreen_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 只会对特定窗口跳过询问,不能关闭新鲜度或进程身份校验。dshWorkshop manifest 声明 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 里,停止/热重载只撤销自己注册的工具。

兼容性

维度状态
HarnessDeepSeek 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 图像

生态与质量

开发

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、脱敏层与五语文档。
展开全部插件
插件状态
dsh-aqua-input-check
dsh-archive-check
dsh-auto-review
dsh-autotier🧊 已冻结 — 见仓库 README
dsh-bid-ca-precheck
dsh-bid-qual-check
dsh-cert-mcp🧊 已冻结 — 见仓库 README
dsh-checkpoint-rewind
dsh-click
dsh-composer-history
dsh-contract-stance
dsh-customs-doc-check
dsh-data-quality🧊 已冻结 — 见仓库 README
dsh-demurrage-ledger
dsh-doublecheck
dsh-drill-script-check
dsh-eia-guide-check
dsh-emergency-plan
dsh-essay-rubric-check
dsh-evidence-check
dsh-export-ctl-check
dsh-fast
dsh-fmea-table-check
dsh-forecast-penalty
dsh-fund-research
dsh-github
dsh-gongwen-flow-check
dsh-gongwen-word-check
dsh-guard-plan-qc
dsh-hazchem-check
dsh-hazplan-check
dsh-hidden-risk-map
dsh-hs-classify
dsh-icd-rule-check
dsh-industry-research
dsh-lawcite-adapter
dsh-laya
dsh-lc-doc-check
dsh-learning-gap-check
dsh-library
dsh-local-ai
dsh-lsp-actions
dsh-mask
dsh-mcp-panel
dsh-medrec-qc
dsh-memento🧊 已冻结 — 见仓库 README
dsh-nsfc-form-check
dsh-nurse-record-check
dsh-observe
dsh-origin-rvc-check
dsh-ota-review-check
dsh-output-styles
dsh-paper-doc-adapter
dsh-permission-rules
dsh-permit-report-check
dsh-pipeline-check
dsh-pleading-draft
dsh-plugin-doctor🚫 已退役(仓库已归档)
dsh-plugin-guide
dsh-plugin-kit🚫 已退役(仓库已归档)
dsh-plugin-upgrade🚫 已退役(仓库已归档)
dsh-policy-brief-draft
dsh-power-loss-split
dsh-power-ticket-check
dsh-ppap-check
dsh-protest-deadline
dsh-railway-window
dsh-repair-order-qc
dsh-research-report
dsh-review-reply-check
dsh-rulefile-check
dsh-safety-brief-check
dsh-score🧊 已冻结 — 见仓库 README
dsh-session-sync
dsh-site-log-check
dsh-skill-pack-security
dsh-soe-decision-check
dsh-soilwater-check
dsh-sop-sync-check
dsh-spc-gbt-adapter
dsh-talk
dsh-tender-extract
dsh-tender-matrix
dsh-test-drive
dsh-ticktick🚫 已退役(仓库已归档)
dsh-translate
dsh-warranty-calc
dsh-budget🧊 已冻结 — 见仓库 README
dsh-claude-move🧊 已冻结 — 见仓库 README
dsh-defend🧊 已冻结 — 见仓库 README
dsh-draw🧊 已冻结 — 见仓库 README
dsh-reach🧊 已冻结 — 见仓库 README
dsh-background-agents🚫 已退役(仓库已归档)
dsh-session-pin🚫 已退役(仓库已归档)
dsh-team-rooms🚫 已退役(仓库已归档)

License

LICENSE(Apache License 2.0)© 2026 dsh-click contributors

Apache-2.0 · 社区插件,与 DeepSeek 无关。

工具链:dsh-plugin-guide · dsh-standards · dsh-plugin-start

Plugin correlati