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 删掉该行）。
从 DSH Desktop 市场安装如果 pnpm 对本包报
ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制无害校验），在你的pnpm-workspace.yaml中加入allowBuilds: { esbuild: true }——dshCLI 会打印确切片段。
所有 PerryLink 插件均可在 DSH Desktop 内置市场中浏览：市场 → 来源 → 添加来源 → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选中。安装仍需通过市场的 npm 身份校验与你的确认。
核心能力
dsh-click 把原生桌面拆成可审计的观察面与动作面：
screen_shot—— 截取窗口（或主屏幕），按maxScreenshotSide缩放。模型支持图像时结果附带图片；纯文本模型则得到文字描述，照常可用。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—— 枚举运行中的应用及其可见窗口；按名称或可执行路径启动应用。
每个变更性操作都穿过同一条安全边界：
- 新鲜度 —— 操作必须引用
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 |
✅ | 按名称或可执行路径启动，可带参数 |
示例
以下为插件真实入口；安装后调用一个即可。
详细示例 — 命令 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 可完全停止审计追加 |
| 键 | 默认值 | 含义 |
|---|---|---|
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/* 审计事件，窗口标题、可执行路径与自由文本在写入或展示前先脱敏并截断。
不会静默。这两个平台的后端已预留但未实现，每次调用都以模型可读的原因失败关闭（dsh-click backend unavailable on linux: ...）；profile 在哪个平台都能正常启动。Windows 上若缺 subprocess 服务或 helper 不可用，同样大声拒绝，而不是假装成功。
不提供任何 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 无关。
No comments yet. Be the first to write one.