桌面原生控制PerryLink/dsh-click

🖱️ dsh-click
- 1024 商店渠道：先执行一次 npm i -g dsh1024，然后执行 dsh1024 plugin --profile web add dsh-click（计入 deepseek1024.com 安装排名）。
Gitee

面向 DeepSeek Harness 的跨平台原生桌面控制——Windows 优先。

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

License
DSH plugin
dsh-doctor
Node
CI
Version
npm version
npm downloads

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

兼容性

| 层面 | 状态 |
|---|---|
| Harness | DeepSeek Harness dsh-v0.1.5-rc.2（GitHub tag，已于 2026-09-11 验证）。已于 2026-09-11 针对 dsh-v0.1.5-rc.2 master 检出进行验证（完整门控链 + profile 安装冒烟测试）。 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 平台 | Windows 优先（通过捆绑的 PowerShell 辅助程序使用 UIAutomation + Win32 输入）；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)

快速开始

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

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.

安装与卸载

- git 渠道（最新的 main）：dsh plugin --profile web add "github:PerryLink/dsh-click#main" —— prepare 脚本仅使用生产依赖进行构建。
- npm 渠道（已发布的版本）：dsh plugin --profile web add dsh-click。
- tarball 渠道：在本仓库中运行 pnpm pack，然后执行 dsh plugin --profile web add ./dsh-click-.tgz。
- 卸载：dsh plugin --profile web remove dsh-click（或从 profile 补丁中移除该行）。

如果 pnpm 针对此包报告 ERR_PNPM_IGNORED_BUILDS（esbuild 无害的平台二进制校验），请将 allowBuilds: { esbuild: true } 添加到你的 pnpm-workspace.yaml 中——dsh CLI 会打印出确切的代码片段。

配置

所有可调项都是 Schemastery Config 字段（可从 cordis.yml 更改）。针对某个 id 的覆盖会替换整行——请重新声明你需要的每个键。cordis.patch.yml 内联记录了每个键。

| 键 | 默认值 | 含义 |
|---|---|---|
| requireApproval | true | 将每个变更操作都置于审批之后；观察者从不询问 |
| autoApproveWindows | [] | 跳过审批询问的窗口标题/可执行文件正则表达式（仍会进行新鲜度检查并审计） |
| auditSessionEvents | true | 追加 dsh-click/observed / dsh-click/action 会话审计事件。自适应门控在无 envelope 的主机上已经跳过追加（rc.6–rc.8、0.1.1-rc.2 和 0.1.2-rc.1，后者在读取时对未知类型采取失败关闭）；设为 false 可完全停止审计追加 0.1.2-rc.1（适配于 2026-09-02）：会话 envelope 保留其可忽略字段仅用于存储日志读取兼容性——Session.append 仍然无法为其打戳，因此审计门控行为不变。 |
| focusFallback | never | 动作是否可以将目标窗口带到前台作为最后手段（never / allow） |
| imageMode | auto | screen_shot 渲染：auto（当模型接受图像时使用图像，否则使用文本）或 text |
| helperTimeoutMs | 30000 | 每次辅助调用的超时时间，单位为毫秒（1..300000） |
| maxHelperOutputBytes | 25165824 | 单个辅助响应的字节数上限（1024..67108864） |
| maxScreenshotSide | 2560 | 截图最长边的像素数（320..7680）；更大的捕获会被缩小 |
| staleCheckPixels | true | 在每次动作前比较新的像素哈希，并在发生变化时拒绝 |
| 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 补丁中覆盖的示例：

- 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，回退到 posted messages |
| type | | ✅ | 仅限值模式元素；失败时备份并恢复控件文本 |
| scroll | | ✅ | 元素（滚动模式）或窗口（posted wheel） |
| key | | ✅ | 发送按键组合（"Ctrl+S"）；忽略发送输入的应用程序会明确拒绝 |
| app_list | ✅ | — | 正在运行的应用程序及其可见窗口 |
| app_launch | | ✅ | 按名称或可执行文件路径启动，可带可选参数 |

权限与数据
- 权限：变更性操作会经过官方的 ctx.approval 接缝——插件绝不会重新实现或绕过它。允许列表只会跳过针对特定窗口的询问；它无法禁用新鲜度或进程身份检查。
- 数据：除附件存储保留的截图外（内容寻址，遵循 harness 自身的附件策略），插件不在磁盘上存储任何内容。观测结果缓存在内存中（LRU，有界）。无网络请求，无凭据存储。
- 会话日志：dsh-click/observed 和 dsh-click/action 是仅用于日志的审计事件，携带经过净化的窗口/进程事实——标题、路径和自由文本在写入或显示之前都会被脱敏并限制长度。

安全边界

- 每次操作前先观测。 操作必须引用新鲜的观测结果；屏幕发生变化（像素哈希）或观测结果过期时会被拒绝，并给出模型可读的原因，要求重新观测。
- 默认需要审批。 除非你明确将特定窗口加入允许列表，否则 requireApproval: true；每一个操作——无论是否被允许——都会记录审计日志。
- 不抢占前台。 辅助程序绝不会将目标窗口带到前台（默认 focusFallback: 'never'）；输入通过 UIA 或投递消息传递，因此后台窗口不会受到干扰。
- 进程身份会在每个操作前后立即重新验证；操作中途发生进程切换会导致结果失败（PROCESS_CHANGED）。
- 净化输出。 控制字符会被剥离，制表符会被折叠，凭据形态的值（密钥、令牌、JWT、bearer 头）在到达模型或日志之前都会被脱敏。
- 故障关闭。 不支持的平台、缺失的子进程服务或不可用的辅助程序会大声拒绝每一次调用——配置文件在所有平台上都能继续启动。

已知限制

- Windows 优先。 macOS 和 Linux 后端已预留；在这些平台上，每次调用都会以明确的原因故障关闭。
- 仅文本保真。 screen_read 依赖于应用程序暴露 UIAutomation；没有可访问树的应用程序只能产生像素提示。坐标点击仍然可用。
- 投递输入型应用。 某些应用程序会忽略投递的窗口消息（游戏、某些 Electron 界面）；key 会如实报告这一点，而不是假装成功。
- 无信封 harness 构建上的会话审计。 审计事件通过自适应门控传递：知道该词汇表的主机会直接追加，带有 ignorable 信封的主机会带标记追加，而无信封的主机——0.1.0-rc.6–0.1.0-rc.8、0.1.1-rc.2 和 0.1.2-rc.1（它们无法加盖 ignorable 标记——信封字段仅为存储日志读取兼容性而保留——并且在读取时对未知类型故障关闭）——不会追加审计；工具结果仍然是可重建的审计轨迹。设置 auditSessionEvents: false 可完全停止审计追加。

开发

pnpm install        # node ^22.19 || >=24bash
pnpm run typecheck  # tsc：针对本地 harness 检出运行 src + 测试
pnpm run typecheck:ci  # tsc：针对已发布的 0.1.5-rc.2 类型（无 paths）
pnpm test           # vitest：66 个测试，11 个文件（helper 冒烟测试在 Windows 上运行）
pnpm run build      # tsdown 打包 + tsc 声明文件（lib/）
pnpm run verify:self-contained  # 依赖规范可从 registry 解析
pnpm run verify:artifacts       # 构建出的 ESM 入口 + 原生 helper 存在
pnpm pack           # 已发布的 tarball

主题

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

贡献者

- @PerryLink — 创建者与维护者：工具界面、操作安全边界、Windows 原生 helper、清理器，以及五种语言的文档。
- @Mchsd — 为会话读取器会拒绝 dsh-click 审计事件的 harness 添加了 auditSessionEvents 退出选项（#2）。

PerryLink DSH 插件家族

本项目是由 PerryLink 维护的 40 个 DeepSeek Harness 插件之一。如果这个对你有帮助，其他的很可能也会：

| 插件 | 一句话简介 |
|---|---|
| dsh-auto-review | 在审批链上进行第二模型自动审查，默认失败即关闭 | |
| dsh-background-agents | 持久化的后台子代理，带 Web UI 侧边栏、消息传递与中断 | |
| dsh-budget | DeepSeek Harness 的成本治理：预算、碳排与延迟集于一个面板。 | |
| dsh-checkpoint-rewind | 等同于 Claude Code /rewind：快照、会话分叉、一键恢复 | |
| dsh-claude-move | 将 Claude Code 的会话、记忆、技能与 CLAUDE.md 迁移到 DSH | |
| dsh-composer-history | Web 输入框的终端风格输入历史：方向键、Ctrl+R 搜索 | |
| dsh-data-quality | 数据集质量检查与引用交叉核对（此处消费的可选数值桥接） | |
| dsh-defend | 面向 DeepSeek Harness 的提示注入、越狱与密钥泄露防御。 | |
| dsh-doublecheck | 工程纪律守卫：需求拷问、测试门禁、对抗性审查 | |
| dsh-draw | 面向 DeepSeek Harness 的统一静态图像生成路由。 | |
| dsh-fast | 面向 DeepSeek Harness 的只读性能诊断。 | |
| dsh-fund-research | 面向中国公募基金的确定性研究报告 | |
| dsh-github | 面向 DSH 的 GitHub PR/issue 集成，每次写入均需审批 | |
| dsh-industry-research | 行业研究编排，通过本插件的 ctx.researchReport.assemble 封存其交付物 | |
| dsh-library | 面向 DeepSeek Harness 的本地文档知识库。 | |
| dsh-local-ai | 面向 DeepSeek Harness 的本地模型（Ollama）集成。 | |
| dsh-lsp-actions | 基于语言服务器的 LSP 诊断、格式化、补全、代码操作与重命名 | |
| dsh-mask | PII 脱敏中间件：在模型边界处匿名化，在展示层还原 | |
| dsh-mcp-panel | 只读 MCP 运行时面板：/mcp 命令 + 设置标签页，含状态、工具与错误 | |
| dsh-memento | 审批门控的跨会话记忆：ctx.memory 接缝 + SQLite + memory 工具 | |
| dsh-observe | 面向 DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测性导出器。 | |
| dsh-output-styles | 等效于 Claude Code outputStyles 的运行时样式切换 | |
| dsh-reach | 多渠道审批/提问桥接：微信/Telegram/飞书，会话控制台 | |
| dsh-permission-rules | Claude Code 风格的声明式 allow/deny/ask 权限规则，带审计 | |
| dsh-personal-directive | 带顶栏开关的个人指令注入器（框架版） | |
| dsh-plugin-guide | 以按需智能体技能形式提供的插件开发知识库 | |
| dsh-plugin-doctor | 面向 DSH 插件的零依赖静态 + 沙箱冒烟检测器 | |
| dsh-research-report | 可验证的研究报告引擎：内容寻址的证据账本与封存版本 | |
| dsh-score | 面向 DeepSeek Harness 插件的多维度质量评分。 | |
| dsh-session-pin | 在 Web 侧边栏中固定会话，并保持持久排序 | |
| dsh-session-sync | 面向 DeepSeek Harness 的跨设备会话同步——你的会话存储的专用 git 镜像。 | |
| dsh-skill-pack-security | 安全审计技能包：密钥扫描、依赖项与供应链审查 | |
| dsh-talk | DeepSeek Harness 的语音优先会话循环：与它对话，聆听它的回答。 | |
| dsh-test-drive | 针对 DeepSeek Harness 插件的隔离式安装与冒烟测试试驾。 | |
| dsh-ticktick | TickTick/滴答清单任务桥接：会话头部面板 + 11 个工具 |
| dsh-translate | 面向 DeepSeek Harness 的供应商参数转换与确定性 JSON 修复。 | |
| dsh-wechat | 微信 ↔ DSH 桥接（腾讯 iLink 机器人）：文本/图片/文件/语音，在聊天中审批 |
| dsh-autotier | 自动进行强/廉价模型层级路由，具备确定性风险防护和 /tier 命令 | |
| dsh-catalog | PerryLink 系列的 DSH Desktop Market 标准目录源 | |
| dsh-cert-mcp | 只读 MCP 服务器，公开认证注册表：评级、快照和五维证据 | |
| dsh-kit | 一条命令即可安装核心系列组件的入门包 | |
| dsh-plugin-certification | 社区认证注册表，提供可复现检查的评级和徽章 | |
| dsh-plugin-kit | 面向 PerryLink DSH 插件的共享零运行时依赖工具包 | |
| dsh-plugin-portal | 零依赖静态门户，将整个插件系列渲染为单个页面 | |
| dsh-plugin-upgrade-015 | 合并后的 0.1.3-alpha.1 → 0.1.5-rc.1 升级通道卡片，外加零依赖接缝扫描器 | |
| dsh-team-rooms | 跨会话团队房间：共享消息总线、任务板和时线 | |

从 DSH Desktop Market 安装

所有 PerryLink 插件均可在内置的 DSH Desktop Market 中浏览：Market → Sources → add source → 粘贴 https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → 选择它。安装仍需经过 Market 的 npm 身份验证和你的确认。

许可证

Apache License 2.0 © 2026 dsh-click contributors