Pular para o conteúdo principal
P

dsh-click

perrylink/dsh-click

Ferramentas de uso de computador no desktop do Windows (click, type, key, screenshot) com verificações de atualização, controle de aprovação, verificação de identidade do processo em torno de cada ação e um rastro de auditoria sanitizado.

Instalar

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

Plugins relacionados