桌面原生控制 PerryLink/dsh-click

🖱️ dsh-click

- 1024 store channel：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-click（计入 deepseek1024.com 的安装排名）。

dshfind

为 DeepSeek Harness 提供跨平台原生桌面控制 —— 优先支持 Windows。

先看屏幕，再动手 —— 每次点击都受管控，每个动作都可审计。

dsh-doctor
DSH Market

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-click

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

- git 渠道（最新 main）：dsh plugin --profile web add github:PerryLink/dsh-click —— prepare 脚本只用生产依赖构建。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-click。
- tarball 渠道：在本仓库执行 pnpm pack，再执行 dsh plugin --profile web add ./dsh-click-<version>.tgz。
- 卸载：dsh plugin --profile web remove dsh-click（或从配置档补丁里删掉对应行）。

如果 pnpm 对这个包报 ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制校验，无害），在 pnpm-workspace.yaml 里加上 allowBuilds: { esbuild: true } —— dsh 命令行会打印出确切的片段。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

dsh-click 是什么？

为 DeepSeek Harness 提供跨平台的原生桌面控制 —— 优先支持 Windows。

先看屏幕，再动手 —— 每次点击都要过闸，每个动作都有审计。

dsh-click 的工作流示意图：安装 → 打开面板 → 动手。

工作流概览：安装 → 打开面板 → 动手。下面的示例用的都是真实命令接口。

兼容性

| 层面 | 状态 |
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（GitHub tag，2026-09-25 验证）。2026-09-11 在 dsh-v0.1.7-alpha.1 master 检出上验证过（完整闸门链 + 配置档安装冒烟测试）。 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 平台 | 优先支持 Windows（UIAutomation + Win32 输入，通过内置的 PowerShell 辅助脚本）；macOS/Linux 后端已预留，会以明确原因失败关闭 |
| 模型 | 纯文本模型完全支持（screen_read 返回结构化文本）；视觉模型额外拿到 screen_shot 图片 |

你能得到什么

dsh-click 给 harness 一套完整的「观察 → 动手」循环，覆盖原生桌面应用：

- screen_shot —— 窗口（或主屏幕）截图，按可配置的上限缩小。模型支持视觉时，结果里带图片；否则用文字描述兜底，纯文本模型照样能用。
- screen_read —— 结构化观察：窗口的无障碍树（元素 id、类型、名称、矩形、支持的模式），加上带颜色的像素位置提示 —— 纯文本，不需要图像模型。
- click / type / scroll / key —— 窗口范围内的动作，按元素 id 或坐标定位。投递优先走 UIA invoke，不行再退回投递窗口消息 —— 而且绝不抢占前台焦点。
- app_list / app_launch —— 枚举正在运行的应用及其窗口；按名称或路径启动应用。

每个会改变状态的动作都要过一道安全边界：

1. 新鲜度 —— 动作必须引用一次 basedOn 观察；动手前会重新抓取窗口，屏幕变了就拒绝执行（像素哈希校验 + 最大时效限制）。
2. 审批 —— 默认每个动作都要过 ctx.approval 审批；可以用窗口标题/可执行文件正则把特定窗口加入白名单（仍然审计）。
3. 进程身份 —— 动手前和动手后都校验所属进程的 pid 和可执行文件路径；一旦变化，就大声拒绝结果。
4. 审计 —— 观察和动作以 dsh-click/observed / dsh-click/action 事件写进会话日志（脱敏，仅日志）。

model harness
│ screen_read ──▶ observationId (+ elements, pixels) ← structured text
│ click {basedOn, target} ──▶ freshness check ──▶ approval ──▶ helper (UIA)
│ pixel hash changed? ── refuse + re-observe
│ pid/exe changed after act? ── PROCESS_CHANGED
│ ◀── canonical JSON + audit events (dsh-click/action)

快速开始

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

1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-click

or from npm (published releases)
dsh plugin --profile web add dsh-click

2. restart and verify the row
dsh --profile web --dump-config | grep -A2 'id: dsh-click'

然后让智能体查看窗口并执行操作——每个会改变状态的操作都会弹出审批提示：

Open Notepad, type "hello", then read back what is on screen.

示例

下面是插件的真实入口；安装一次，之后调用其中一个即可。

详细示例

命令

~~~sh
app_list

输入

~~~json
{}

输出

~~~text
1 running application(s) with windows:
- Demo (pid 4242, C:\Apps\demo.exe)
- [windowId 1122867] "Demo App" at (10, 20) 800x600

观察自 plugins/dsh-click/tests/tools.spec.ts:159-185; renderer at src/tools.ts:933-942

失败分支

输入

~~~text
{}

输出

~~~text
Error: dsh-click backend unavailable on linux: Linux backend is reserved but not implemented yet (Windows-first); only Windows can act today

观察自 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 | [] | 窗口标题/可执行文件的正则，匹配时跳过审批询问（仍会做新鲜度检查并记入审计） |
| 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）：会话信封保留其可忽略字段，仅用于已存日志的读取兼容——Session.append 仍然无法写入该字段，因此审计门控行为不变。 |
| focusFallback | never | 操作是否可以把目标窗口带到前台作为最后手段（never / allow） |
| imageMode | auto | screen_shot 的渲染方式：auto（模型接受图像时输出图像，否则输出文本）或 text |
| helperTimeoutMs | 30000 | 每次 helper 调用的超时，单位 ms（1..300000） |
| maxHelperOutputBytes | 25165824 | 单个辅助程序响应的字节上限（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 时降级为不可用） |

在配置档补丁中覆盖配置的示例：

- insert:
- id: dsh-click
name: dsh-click
config:
requireApproval: true
autoApproveWindows: ['^Notepad']
focusFallback: never

工具与界面

| 工具 | 只读 | 需要审批 | 说明 |
| screen_shot | ✅ | — | 返回 observationId，后续操作在 basedOn 中引用；模型接受图片时附带图像 |
| screen_read | ✅ | — | 无障碍树 + 像素提示；元素 id 就是操作寻址的目标 |
| click | | ✅ | elementId 或 (x, y) 二选一；优先 UIA invoke，回退到投递消息 |
| type | | ✅ | 仅支持值模式元素；失败时备份并恢复控件文本 |
| scroll | | ✅ | 元素（滚动模式）或窗口（投递滚轮） |
| key | | ✅ | 投递按键组合（"Ctrl+S"）；忽略投递输入的应用程序会明确拒绝 |
| app_list | ✅ | — | 运行中的应用及其可见窗口 |
| app_launch | | ✅ | 按名称或可执行文件路径启动，可带参数 |

权限与数据

- 权限：变更类操作走官方 ctx.approval 接口——插件从不重新实现或绕过它。允许列表只做一件事：对特定窗口跳过询问；它无法关闭新鲜度检查或进程身份检查。
- 数据：插件不在磁盘上存任何东西，只有附件存储保留的截图（内容寻址，遵循 harness 自己的附件策略）。观测缓存在内存中（LRU，有上限）。不发网络请求，不存凭据。
- 会话日志：dsh-click/observed 和 dsh-click/action 是只写日志的审计事件，携带脱敏后的窗口与进程信息——标题、路径和自由文本在写入或展示之前都会脱敏并限制长度。

安全边界

- 先观察，再操作，每次都如此。 操作必须引用一次新的观察结果；屏幕发生变化（像素哈希）或观察结果过期，都会被拒绝，并给出模型可读的原因，要求重新观察。
- 默认需要审批。 除非你显式把特定窗口加入白名单，否则 requireApproval: true；每个操作——无论是否放行——都会写入审计日志。
- 不抢占前台。 辅助程序从不把目标窗口带到前台（默认 focusFallback: 'never'）；输入通过 UIA 或投递消息送达，不打扰后台窗口。
- 进程身份会重新校验，就在每个操作之前和之后；操作中途进程被替换，结果判定为失败（PROCESS_CHANGED）。
- 输出经过脱敏。 控制字符被剥离，制表符被折叠，形似凭据的值（密钥、token、JWT、bearer 头）在到达模型或日志之前都会被脱敏。
- 失败即关闭。 不支持的平台、缺少子进程服务、辅助程序不可用，都会让每次调用大声拒绝——配置档在各处仍能正常启动。

已知限制

- Windows 优先。 macOS 和 Linux 后端暂未实现；在这些平台上，每次调用都会失败关闭，并给出明确原因。
- 文本保真度有限。 screen_read 依赖应用暴露 UIAutomation；没有可访问树的应用只能给出像素提示。坐标点击仍然可用。
- 忽略投递输入的应用。 有些应用会忽略投递的窗口消息（游戏、部分 Electron 界面）；key 会如实报告这一点，而不是假装成功。
- 无 envelope 的 harness 构建上的会话审计。 审计事件走一道自适应闸门：认识这套词汇的宿主直接追加，带 ignorable envelope 的宿主追加时带上标记，而没有 envelope 的宿主——0.1.0-rc.6–0.1.0-rc.8、0.1.1-rc.2 和 0.1.2-rc.1（它们无法打上 ignorable 标记——envelope 字段仅为兼容已存日志的读取而保留——并且在读取时遇到未知类型会失败关闭）——不会追加审计；工具结果仍是可重建的审计线索。把 auditSessionEvents 设为 false 可完全停止审计追加。

开发

pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc: src + tests against the local harness checkout
pnpm run typecheck:ci # tsc against the published 0.1.7-rc.2 types (no paths)
pnpm test # vitest: 79 tests, 13 files (helper smoke runs on Windows)
pnpm run build # tsdown bundle + tsc declarations (lib/)
pnpm run verify:self-contained # dependency specs resolve from the registry
pnpm run verify:artifacts # built ESM face + native helper present
pnpm pack # the published tarball

主题

dsh、dsh-plugin、deepseek-harness、deepseek、cordis、computer-use、windows-automation、uiautomation、desktop-control、screen-reader

贡献者

- Windows helper 冒烟检查清单 —— 针对 0.3.24+ 的真实输入与焦点验证。
- @LIU12312-Source —— 为 Windows helper 补上真实的 SendInput 与前台焦点回退（PR #21）。
- @PerryLink —— 创建者与维护者：工具面、动作安全边界、Windows 原生 helper、清理器，以及五种语言的文档。
- @Mchsd —— 新增 auditSessionEvents 退出开关，供会话读取器拒绝 dsh-click 审计事件的 harness 使用（#2）。

PerryLink DSH 插件家族

本项目属于 PerryLink 的 DeepSeek Harness 插件家族。下面的名单默认折叠，好让每个 README 的首屏都保持简短；展开即可看到每一行及其状态。

展开全部插件

| 插件 | 状态 |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | |
| dsh-checkpoint-rewind | |
| dsh-click | |
| dsh-composer-history | |
| dsh-contract-stance | |
| dsh-customs-doc-check | |
| dsh-data-quality | |
| 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 | |
| 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 | |
| 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 | 🚫 已退役 — 见仓库 README |
| dsh-session-pin | 🚫 已退役 — 见仓库 README |
| dsh-team-rooms | 🚫 已退役 — 见仓库 README |

许可证

Apache License 2.0 © 2026 dsh-click contributors