diff --git a/README.md b/README.md index 304ca41..8fbb01a 100644 --- a/README.md +++ b/README.md @@ -1,234 +1,158 @@ -# dsh-computer - -独立自研的 DSH 常驻插件:给所有标准会话一个统一的 `computer` 工具,用 Cua Driver 观察和操作 -Windows 桌面。纯 ESM JavaScript + JSDoc,零构建、零运行时依赖。 +

dsh-computer:桌面与 AI 光标

+

dsh-computer

+

让 AI 操作真实桌面,让每一步都看得见。

+

一个 computer 工具 · 可见 AI 光标 · 先观察,再行动,再验证

+

+ CI + Latest release + Windows 10 / 11 + Node.js 24 or later +

+

+ 亮点 · 快速开始 · 工作方式 · 完整指南 · 下载 +

+ + + + 流程示意:DSH Agent 通过 computer 工具观察 Windows 桌面,经安全检查执行动作,并回读结果。 + +

工作流程示意图;非实际运行截图。

+ +dsh-computer 是面向 **DSH Desktop 的独立常驻插件**。它通过 Cua Driver 读取截图与 Windows UI Automation 控件树,让 Agent 在标准会话中按需操作桌面应用,无需切换预设或模式。 + +插件使用 ESM JavaScript,无需构建;运行时使用 DSH 提供的宿主接口,并通过本机 Cua Driver 执行桌面操作。 + +> **当前版本:0.1.0。** 已记录 Windows 真机截图、控件读取、点击、输入及回读验证。自动更新支持兼容性选择、SHA-256 校验与手动回滚,尚不能自动确认新版本加载成功。查看 [验证记录](docs/verification.md) 与 [版本变更](CHANGELOG.md)。 + +## 亮点 + +| | 能做什么 | +| --- | --- | +| **一个入口** | 用 `computer` 的 `observe / act / session` 完成观察、操作与会话管理,标准会话直接可用。 | +| **看见操作** | 独立 AI 光标展示点击、移动、拖拽与元素滚动的轨迹,让操作目标更直观。 | +| **先看再动** | 同时读取截图与控件树,优先按元素标识操作;过期观察需要重新获取。 | +| **回读结果** | 点击与输入后回读,区分 `confirmed`、`noop`、`unverifiable` 与 `refused`。无法验证不会被当作成功。 | +| **保留控制权** | 风险审批、密码框与 UAC 启发式阻断、用户输入检测,以及进程内单 Agent 租约。 | +| **便于维护** | 安装、自检、卸载与更新脚本齐备;JSONL 审计中的输入仅记录长度与哈希摘要。 | -- 没有 `Computer Use` 预设,也不需要切模式;工具常驻,模型按需调用。 -- 观察(截图 + UIA 控件树)→ 动作 → 回读验证;`unverifiable` 不会被当成成功。 -- 可见 AI 光标、风险审批、不可绕过的硬阻断、用户接管、JSONL 审计。 -- 安装/卸载/自检/更新脚本;GitHub Releases + sha256 的自动更新基础。 +## 快速开始 -## 环境要求 +### 1. 准备环境 -| 项目 | 要求 | +| 依赖 | 要求 | | --- | --- | -| 操作系统 | Windows 10 / 11 | -| Node.js | 24.x(`>=24.0.0`) | -| DSH Desktop | `>=0.2.1-rc.2 <0.3.0`(`engines.dsh`,不满足会拒绝加载) | -| Cua Driver | `>=0.36`(`cua-driver mcp`;Windows 安装包默认在 `%LOCALAPPDATA%`) | +| 系统 | Windows 10 / 11,当前支持主显示器 | +| Node.js | **24 或更高版本**;CI 使用 Node 24 | +| DSH Desktop | **`>=0.2.1-rc.2 <0.3.0`**,不满足范围会拒绝加载 | +| Cua Driver | **0.36 或更高版本**,提供 `cua-driver mcp`;[上游安装说明](https://github.com/trycua/cua/tree/main/libs/cua-driver) | -## 安装 +### 2. 安装插件 -从仓库检出运行(不发布到 npm,也不需要构建): +在 PowerShell 中运行: ```powershell git clone https://github.com/Curlance/dsh-computer.git cd dsh-computer -node scripts/install.mjs --dry-run # 先看计划,不写文件 -node scripts/install.mjs # 复制版本、写 profile 链接/skill、写托管插件行 + +node scripts/install.mjs --dry-run +node scripts/install.mjs +node scripts/doctor.mjs ``` -安装器做五件事: +无需 `npm install` 或构建。安装器会写入版本目录、profile 链接、操作 skill 和托管配置,并备份已有的同名 skill。检测到旧版 `dsh-computer-use` 时会执行迁移;自定义路径、备份与恢复见 [完整指南](docs/GUIDE.md#安装)。 -1. 检测并迁移旧的 `dsh-computer-use`(旧预设/旧根行删除,旧包移到 - `~/.dsh/plugins/_backup/`,可用 `node scripts/install.mjs --rollback` 恢复); -2. 把包复制到 `~/.dsh/plugins/dsh-computer//`; -3. 把 `~/.dsh/profiles/desktop/node_modules/dsh-computer` 指向该版本(junction); -4. 把 `skills/computer-use` 复制到 `~/.dsh/skills/computer-use`;已有同名目录先移到 - `~/.dsh/computer/backup/skills-`; -5. 在 `~/.dsh/cordis.patch.yml` 写入一段带标记的根插件行。 +### 3. 重启并开始使用 -参数:`--home `(**用户主目录**,DSH 根为 `/.dsh`);不传 `--home` 时把 -`$DSH_HOME` 直接当作 DSH 根(未设置时用 `~/.dsh`)。`--home` 与 `$DSH_HOME` 同时设置时 -`$DSH_HOME` 会被忽略,不要混用。另有 `--profile `(默认 `desktop`)、 -`--patch `(默认 `/cordis.patch.yml`)、`--dry-run`、`--rollback`。 -**安装后完全退出并重启 DSH**,新会话即可看到 `computer` 工具和 `computer-use` skill。 +**完全退出并重启 DSH**,新建一个标准会话,确认可以使用 `computer` 工具。可以先试试: -`package.json#files` 包含 `scripts/`、`docs/`、`skills/`,所以从 tarball 解包后也能运行安装器 -并安装 skill;`tests/` 与 `.github/` 不在 tarball 里。 +> 观察当前活动窗口,告诉我它是什么应用、有哪些可操作控件,先不要点击。 -## 自检(doctor) +想验证输入时,先手动打开一个空白记事本,再告诉 Agent: -```powershell -node scripts/doctor.mjs -node scripts/doctor.mjs --json -``` +> 在当前记事本中输入“Hello from dsh-computer”,然后回读确认文字是否出现,先不要保存。 -检查项: +遇到环境问题,运行 `node scripts/doctor.mjs --json` 查看检查结果。驱动未被发现时,可设置 `CUA_DRIVER_BIN` 指向驱动可执行文件。 -- `dsh-version`:能探测到 DSH 运行时版本(`DSH_VERSION` → `DSH_APP_PACKAGE_JSON` → - `/version` → 解包桌面的 `resources/app/package.json`(仅信任 DSH 包名)→ `dsh --version`); -- `dsh-compat`:版本落在 `>=0.2.1-rc.2 <0.3.0`; -- `cua-driver`:`CUA_DRIVER_BIN` / PATH / 官方安装位置能找到 `cua-driver.exe`; -- `cordis-patch`:托管插件行存在; -- `plugin-install`:版本目录存在且 profile 链接指向它。 +## 工作方式 -任一失败退出码为 1。驱动缺失时按提示安装 Cua Driver 或设置 `CUA_DRIVER_BIN`。 +**观察 → 安全检查 → 执行动作 → 回读验证**。Agent 根据最新观察选择目标,并使用工具返回的实际效果决定下一步。 -## 使用:一个 `computer` 工具 +下面是 `computer` 工具的调用参数示例,不是终端命令: -标准会话(无预设)里模型可以直接调用。先观察: +**① 观察活动窗口**,获取截图、控件标识和 revision。 ```json { "action": "observe", "target": { "kind": "active" }, "mode": "both" } ``` -返回 `revision`、`space=宽x高` 和控件行: - -``` -revision=7 window="记事本" space=1456x912 -[s00000001:2] Document "文本编辑器" @(720,456) TextPattern -``` - -再用元素 id 或截图空间坐标动作: +**② 按控件输入**。将示例中的 `s00000001:2` 替换为本次观察返回的真实元素标识。 ```json { "action": "act", "op": "type", "target": { "element": "s00000001:2" }, - "text": "hello" + "text": "Hello from dsh-computer" } ``` -```json -{ "action": "act", "op": "key", "keys": ["ctrl", "s"] } -``` +**③ 检查结果**。查看动作返回的 `effect`;需要继续操作时重新观察,也可以查询会话状态: ```json { "action": "session", "op": "status" } ``` -- `action`:`observe` / `act` / `session`。 -- `act` 的 `op`:`click`、`doubleClick`、`rightClick`、`move`、`type`、`key`、`scroll`、`drag`、 - `wait`、`launch`、`focus`、`resize`、`kill`;可用 `steps[]` 批量顺序执行。 -- 坐标是**最近一次观察的截图空间**里的窗口本地像素;元素动作优先,避免坐标点击。 -- 动作需要当前观察(`revision` 或本进程最近一次观察,默认 60 s 过期);先观察再动作。 -- `effect` 为 `confirmed` / `noop` / `unverifiable` / `refused`;`unverifiable` 不是成功。 -- 详细的参数、坐标语义、错误处理见 [`skills/computer-use/SKILL.md`](skills/computer-use/SKILL.md)。 - -## 配置 - -安装器写入的托管段在 `~/.dsh/cordis.patch.yml`,形如: - -```yaml -# >>> dsh-computer (managed) -- insert: - - id: dsh-computer - name: dsh-computer - config: - cursor: - enabled: true - theme: cua.default - idleHideMs: 0 - glideMs: 600 - approvals: - mode: ask - policy: - allowedApps: [] - blockedApps: [] - maxActionsPerMinute: 60 - audit: - path: ~/.dsh/computer/audit.jsonl - includeScreenshots: false - backend: - timeoutMs: 15000 - observation: - maxElements: 250 - maxImageDimension: 1456 - ttlMs: 60000 -# <<< dsh-computer -``` +
+支持的动作与坐标规则 -| 配置 | 默认 | 说明 | -| --- | --- | --- | -| `cursor.enabled` | `true` | 显示独立 AI 光标;关掉则完全不启动光标会话 | -| `cursor.theme` / `idleHideMs` / `glideMs` | `cua.default` / `0` / `600` | Cua 主题与轨迹参数 | -| `approvals.mode` | `ask` | `ask`:高风险审批;`strict`:中/高风险审批;`relaxed` 当前等同 `ask` | -| `policy.allowedApps` / `blockedApps` | `[]` | 按窗口标题(不区分大小写)子串匹配;blocked 优先,非空 allowed 只放行列出的标题 | -| `policy.maxActionsPerMinute` | `60` | 每进程 60 s 滑动窗口;`observe`/`session`/`wait` 不计,重启清零 | -| `audit.path` | `~/.dsh/computer/audit.jsonl` | JSONL 审计;`~` 会展开 | -| `audit.includeScreenshots` | `false` | 仅为配置兼容;截图从不写审计 | -| `backend.timeoutMs` | `15000` | 单次 cua-driver MCP 调用超时 | -| `observation.maxElements` | `250` | UIA 树预算 | -| `observation.maxImageDimension` | `1456` | 截图最长边 | -| `observation.ttlMs` | `60000` | 观察 revision 有效期 | - -改配置后重启 DSH(或等 HMR)生效。不要删除托管段的标记;重新运行安装器会保持段内配置幂等。 - -## 安全 - -- **审批**:高风险动作(`launch`/`kill`、坐标点击、前台输入、敏感词输入)默认请求用户审批; - 拒绝后不会执行。 -- **硬阻断(不可配置绕过)**:密码框(直接阻断,不走审批)、UAC/安全桌面、没有当前观察的盲动作。 -- **应用门禁/限流**:`policy.allowedApps` / `blockedApps` 按窗口标题子串拦截;`maxActionsPerMinute` 限制动作频率。 -- **控制门禁**:用户 3 秒内有键鼠输入时拒绝动作并返回 `waitSeconds`;自身输入有 700 ms 启发式抵消。 -- **租约**:同一时间只有一个 agent 操作桌面(120 s TTL,自动续期);其他会话得到 `busy`。 -- **审计**:默认 `~/.dsh/computer/audit.jsonl`;输入只记长度 + sha256 前缀,不记明文/截图。 -- **残余风险**:不是沙箱;硬阻断与空闲检测都是启发式;应用白/黑名单只匹配窗口标题子串, - 限流是进程内窗口(重启清零);截图会进入模型上下文。完整说明见 [`docs/SAFETY.md`](docs/SAFETY.md)。 - -## 自动更新 - -发布走 GitHub Releases(本仓库以 `Curlance/dsh-computer-use` 为准): - -- tag `v*` 触发发布工作流:测试 → `npm pack` → 生成 `compat.json`(含 tarball sha256)→ - 上传 tgz + `compat.json` → 创建 Release; -- 更新器按 `compat.json` 里每个条目的 `dsh` 范围(发布时取自 `package.json#engines.dsh`)选最高兼容版本; - sha256 校验通过后才写插件目录,原子切换 profile 链接,保留 previous 供 `--rollback`; -- `--apply` 先写 `pending.json`,在写完 `source:"updater"` 心跳后立即清除它;因为运行时还不写心跳, - pending 只用于发现“切换中途中断”,不是加载成功确认; -- **不做签名**:sha256 只防损坏,信任边界是本仓库与 GitHub 账号。 +`act.op` 支持 `click`、`doubleClick`、`rightClick`、`move`、`type`、`key`、`scroll`、`drag`、`wait`、`launch`、`focus`、`resize`、`kill`;可用 `steps[]` 顺序执行多个动作。 -```powershell -# 完全退出 DSH 后: -node scripts/update.mjs --manifest "https://github.com/Curlance/dsh-computer/releases/latest/download/compat.json" --check -node scripts/update.mjs --manifest ".../compat.json" --apply -node scripts/update.mjs --rollback -``` +优先使用元素标识。坐标属于**最近一次观察的截图空间**,是窗口本地像素;观察默认 60 秒过期。批量操作也会逐步授权与记录。完整参数及错误处理见 [computer-use skill](skills/computer-use/SKILL.md)。 + +
+ +## 安全与边界 -计划任务(`node scripts/register-task.mjs`,登录时 + 每 6 小时)会传 -`--apply --home --manifest `,所以自动更新的命令已接通;但 DSH 运行时仍不写健康心跳, -新版本加载失败不会被自动发现,更新后要人工检查并手动 `--rollback`。细节与故障处理见 -[`docs/AUTO-UPDATE.md`](docs/AUTO-UPDATE.md)。 +插件操作的是当前用户的**真实桌面**。默认高风险动作需要审批;密码框、UAC / 安全桌面和没有当前观察的盲动作会被阻断。用户近期有键鼠输入时,插件会暂缓动作。 -## 卸载 +- **启发式防护,非沙箱。** 密码框识别与用户空闲检测存在局限;检测失败时当前实现可能放行。截图会进入模型上下文。 +- **应用策略按窗口标题匹配。** 白名单与黑名单使用标题子串;限流与租约仅在进程内生效。 +- **当前仅支持 Windows 主显示器。** 驱动 0.36 的焦点元素等待存在限制;观察预算无法中断正在执行的 UIA 遍历。 +- **更新后需要人工检查。** SHA-256 用于完整性校验,发布包未签名;尚无运行时健康心跳或加载失败自动回滚。 + +审批模式、控制权规则与完整限制见 [安全模型](docs/SAFETY.md);配置项见 [配置指南](docs/GUIDE.md#配置)。 + +## 更新与维护 + +完全退出 DSH 后,在仓库根目录检查更新: ```powershell -node scripts/uninstall.mjs --dry-run -node scripts/uninstall.mjs +node scripts/update.mjs --manifest "https://github.com/Curlance/dsh-computer/releases/latest/download/compat.json" --check ``` -删除托管插件行、profile 链接、当前版本目录和 `~/.dsh/skills/computer-use`;如果安装时备份过同名 -skill,会恢复最近一个 `skills-*` 备份。保留 `~/.dsh/computer/**`(审计、备份等用户数据)。 -卸载后重启 DSH。要恢复被迁移的旧版:先卸载,再 `node scripts/install.mjs --rollback`。 +将 `--check` 改为 `--apply` 应用更新;需要恢复上一版本时运行 `node scripts/update.mjs --rollback`。计划任务与兼容性规则见 [自动更新指南](docs/AUTO-UPDATE.md)。 + +卸载前可用 `node scripts/uninstall.mjs --dry-run` 预览,再运行 `node scripts/uninstall.mjs`。审计与备份数据会保留,详见 [卸载与恢复](docs/GUIDE.md#卸载)。 -## 开发与测试 +## 开发与验证 ```powershell -npm test # node --test tests/*.test.mjs -node --test tests/tool.test.mjs # 单个文件 -node scripts/smoke.mjs # 真机只读冒烟(需要桌面 + cua-driver) -node scripts/smoke-action.mjs # 真机动作冒烟(会启动/清理一个 mshta 目标) +npm test ``` -单测不需要 DSH、桌面或 cua-driver(宿主/驱动/时钟都是注入的);冒烟脚本才会碰真实桌面。 -CI 为 `.github/workflows/ci.yml`(windows-latest + Node 24 + `npm test`),不安装驱动。 +单元测试注入宿主、驱动和时钟,不需要启动 DSH 或操作桌面;CI 使用 Windows + Node 24。真机验证记录单独保存在 [docs/verification.md](docs/verification.md)。真机冒烟命令见 [开发指南](docs/GUIDE.md#开发与测试)。 -## 文档 +## 文档导航 -- [架构与不变量](docs/ARCHITECTURE.md) · [安全模型](docs/SAFETY.md) · - [自动更新](docs/AUTO-UPDATE.md) · [验证证据](docs/verification.md) · - [变更记录](CHANGELOG.md) -- [设计](docs/superpowers/specs/2026-10-21-dsh-computer-independent-design.md) · - [实现计划](docs/superpowers/plans/2026-10-21-dsh-computer-a-b.md) +| 我想了解… | 从这里开始 | +| --- | --- | +| 安装、迁移、配置和卸载 | [完整指南](docs/GUIDE.md) | +| 工具参数与操作规范 | [computer-use skill](skills/computer-use/SKILL.md) | +| 审批、控制权与残余风险 | [安全模型](docs/SAFETY.md) | +| 发布、校验和回滚 | [自动更新](docs/AUTO-UPDATE.md) | +| 插件内部如何协作 | [架构与不变量](docs/ARCHITECTURE.md) | +| 已验证的行为与版本变化 | [验证记录](docs/verification.md) · [CHANGELOG](CHANGELOG.md) | -## 已知限制 +--- -- 只支持 Windows 与主显示器;`target:{kind:"screen"}` 不支持多屏。 -- `focused_element` 等待条件在 cua-driver 0.36 上通常不命中(驱动不报告焦点元素)。 -- `policy.allowedApps` / `blockedApps` 只按窗口标题子串匹配;限流是进程内 60 s 窗口,重启清零。 -- AI 光标 glide 覆盖 `click`/`move`/`drag`/元素 `scroll`;`type`/`key`/`wait`/`launch`/`focus`/`resize`/`kill` 不移动光标。 -- 观察的 `budgetMs` 只能事后标记超时,不能取消进行中的 UIA 遍历。 -- 无运行时健康心跳:更新后无法自动确认新版本加载成功,回滚需要手动执行;无签名。 -- npm tarball 含运行时、`scripts/`、`docs/` 和 `skills/`;`tests/`、`.github/` 不在包内。 +

Built for DSH Desktop · Powered by Cua Driver

diff --git a/docs/AUTO-UPDATE.md b/docs/AUTO-UPDATE.md index bf4ae8f..d637196 100644 --- a/docs/AUTO-UPDATE.md +++ b/docs/AUTO-UPDATE.md @@ -9,7 +9,7 @@ ## 1. 信任根 -- 更新源固定为本仓库的 GitHub Releases(README 以 `Curlance/dsh-computer-use` 为准); +- 更新源固定为本仓库的 GitHub Releases(README 以 `Curlance/dsh-computer` 为准); 发布工作流用 `${{ github.repository }}` 生成下载 URL,所以 fork 也能产出指向自己的 `compat.json`。 - 完整性:每个版本在 `compat.json` 里带 tarball 的 sha256;下载后先校验,再写任何插件目录。 - **不做签名**(评审决定):sha256 只防损坏/传输错误,不防仓库账号被篡改。 diff --git a/docs/GUIDE.md b/docs/GUIDE.md new file mode 100644 index 0000000..b94968e --- /dev/null +++ b/docs/GUIDE.md @@ -0,0 +1,230 @@ +# 安装、配置与维护指南 + +[← 返回项目首页](../README.md) + +以下命令均在仓库根目录运行。 + +## 环境要求 + +| 项目 | 要求 | +| --- | --- | +| 操作系统 | Windows 10 / 11 | +| Node.js | 24 或更高版本(`>=24.0.0`) | +| DSH Desktop | `>=0.2.1-rc.2 <0.3.0`(`engines.dsh`,不满足会拒绝加载) | +| Cua Driver | `>=0.36`(`cua-driver mcp`;Windows 安装包默认在 `%LOCALAPPDATA%`) | + +## 安装 + +从仓库检出运行(不发布到 npm,也不需要构建): + +```powershell +git clone https://github.com/Curlance/dsh-computer.git +cd dsh-computer +node scripts/install.mjs --dry-run # 先看计划,不写文件 +node scripts/install.mjs # 复制版本、写 profile 链接/skill、写托管插件行 +``` + +安装器做五件事: + +1. 检测并迁移旧的 `dsh-computer-use`(旧预设/旧根行删除,旧包移到 + `~/.dsh/plugins/_backup/`,可用 `node scripts/install.mjs --rollback` 恢复); +2. 把包复制到 `~/.dsh/plugins/dsh-computer//`; +3. 把 `~/.dsh/profiles/desktop/node_modules/dsh-computer` 指向该版本(junction); +4. 把 `skills/computer-use` 复制到 `~/.dsh/skills/computer-use`;已有同名目录先移到 + `~/.dsh/computer/backup/skills-`; +5. 在 `~/.dsh/cordis.patch.yml` 写入一段带标记的根插件行。 + +参数:`--home `(**用户主目录**,DSH 根为 `/.dsh`);不传 `--home` 时把 +`$DSH_HOME` 直接当作 DSH 根(未设置时用 `~/.dsh`)。`--home` 与 `$DSH_HOME` 同时设置时 +`$DSH_HOME` 会被忽略,不要混用。另有 `--profile `(默认 `desktop`)、 +`--patch `(默认 `/cordis.patch.yml`)、`--dry-run`、`--rollback`。 +**安装后完全退出并重启 DSH**,新会话即可看到 `computer` 工具和 `computer-use` skill。 + +`package.json#files` 包含 `scripts/`、`docs/`、`skills/`,所以从 tarball 解包后也能运行安装器 +并安装 skill;`tests/` 与 `.github/` 不在 tarball 里。 + +## 自检(doctor) + +```powershell +node scripts/doctor.mjs +node scripts/doctor.mjs --json +``` + +检查项: + +- `dsh-version`:能探测到 DSH 运行时版本(`DSH_VERSION` → `DSH_APP_PACKAGE_JSON` → + `/version` → 解包桌面的 `resources/app/package.json`(仅信任 DSH 包名)→ `dsh --version`); +- `dsh-compat`:版本落在 `>=0.2.1-rc.2 <0.3.0`; +- `cua-driver`:`CUA_DRIVER_BIN` / PATH / 官方安装位置能找到 `cua-driver.exe`; +- `cordis-patch`:托管插件行存在; +- `plugin-install`:版本目录存在且 profile 链接指向它。 + +任一失败退出码为 1。驱动缺失时按提示安装 Cua Driver 或设置 `CUA_DRIVER_BIN`。 + +## 使用:一个 `computer` 工具 + +标准会话(无预设)里模型可以直接调用。先观察: + +```json +{ "action": "observe", "target": { "kind": "active" }, "mode": "both" } +``` + +返回 `revision`、`space=宽x高` 和控件行: + +``` +revision=7 window="记事本" space=1456x912 +[s00000001:2] Document "文本编辑器" @(720,456) TextPattern +``` + +再用元素 id 或截图空间坐标动作: + +```json +{ + "action": "act", + "op": "type", + "target": { "element": "s00000001:2" }, + "text": "hello" +} +``` + +```json +{ "action": "act", "op": "key", "keys": ["ctrl", "s"] } +``` + +```json +{ "action": "session", "op": "status" } +``` + +- `action`:`observe` / `act` / `session`。 +- `act` 的 `op`:`click`、`doubleClick`、`rightClick`、`move`、`type`、`key`、`scroll`、`drag`、 + `wait`、`launch`、`focus`、`resize`、`kill`;可用 `steps[]` 批量顺序执行。 +- 坐标是**最近一次观察的截图空间**里的窗口本地像素;元素动作优先,避免坐标点击。 +- 动作需要当前观察(`revision` 或本进程最近一次观察,默认 60 s 过期);先观察再动作。 +- `effect` 为 `confirmed` / `noop` / `unverifiable` / `refused`;`unverifiable` 不是成功。 +- 详细的参数、坐标语义、错误处理见 [`skills/computer-use/SKILL.md`](../skills/computer-use/SKILL.md)。 + +## 配置 + +安装器写入的托管段在 `~/.dsh/cordis.patch.yml`,形如: + +```yaml +# >>> dsh-computer (managed) +- insert: + - id: dsh-computer + name: dsh-computer + config: + cursor: + enabled: true + theme: cua.default + idleHideMs: 0 + glideMs: 600 + approvals: + mode: ask + policy: + allowedApps: [] + blockedApps: [] + maxActionsPerMinute: 60 + audit: + path: ~/.dsh/computer/audit.jsonl + includeScreenshots: false + backend: + timeoutMs: 15000 + observation: + maxElements: 250 + maxImageDimension: 1456 + ttlMs: 60000 +# <<< dsh-computer +``` + +| 配置 | 默认 | 说明 | +| --- | --- | --- | +| `cursor.enabled` | `true` | 显示独立 AI 光标;关掉则完全不启动光标会话 | +| `cursor.theme` / `idleHideMs` / `glideMs` | `cua.default` / `0` / `600` | Cua 主题与轨迹参数 | +| `approvals.mode` | `ask` | `ask`:高风险审批;`strict`:中/高风险审批;`relaxed` 当前等同 `ask` | +| `policy.allowedApps` / `blockedApps` | `[]` | 按窗口标题(不区分大小写)子串匹配;blocked 优先,非空 allowed 只放行列出的标题 | +| `policy.maxActionsPerMinute` | `60` | 每进程 60 s 滑动窗口;`observe`/`session`/`wait` 不计,重启清零 | +| `audit.path` | `~/.dsh/computer/audit.jsonl` | JSONL 审计;`~` 会展开 | +| `audit.includeScreenshots` | `false` | 仅为配置兼容;截图从不写审计 | +| `backend.timeoutMs` | `15000` | 单次 cua-driver MCP 调用超时 | +| `observation.maxElements` | `250` | UIA 树预算 | +| `observation.maxImageDimension` | `1456` | 截图最长边 | +| `observation.ttlMs` | `60000` | 观察 revision 有效期 | + +改配置后重启 DSH(或等 HMR)生效。不要删除托管段的标记;重新运行安装器会保持段内配置幂等。 + +## 安全 + +- **审批**:高风险动作(`launch`/`kill`、坐标点击、前台输入、敏感词输入)默认请求用户审批; + 拒绝后不会执行。 +- **硬阻断(不可配置绕过)**:密码框(直接阻断,不走审批)、UAC/安全桌面、没有当前观察的盲动作。 +- **应用门禁/限流**:`policy.allowedApps` / `blockedApps` 按窗口标题子串拦截;`maxActionsPerMinute` 限制动作频率。 +- **控制门禁**:用户 3 秒内有键鼠输入时拒绝动作并返回 `waitSeconds`;自身输入有 700 ms 启发式抵消。 +- **租约**:同一时间只有一个 agent 操作桌面(120 s TTL,自动续期);其他会话得到 `busy`。 +- **审计**:默认 `~/.dsh/computer/audit.jsonl`;输入只记长度 + sha256 前缀,不记明文/截图。 +- **残余风险**:不是沙箱;硬阻断与空闲检测都是启发式;应用白/黑名单只匹配窗口标题子串, + 限流是进程内窗口(重启清零);截图会进入模型上下文。完整说明见 [`docs/SAFETY.md`](SAFETY.md)。 + +## 自动更新 + +发布走 GitHub Releases(本仓库以 `Curlance/dsh-computer` 为准): + +- tag `v*` 触发发布工作流:测试 → `npm pack` → 生成 `compat.json`(含 tarball sha256)→ + 上传 tgz + `compat.json` → 创建 Release; +- 更新器按 `compat.json` 里每个条目的 `dsh` 范围(发布时取自 `package.json#engines.dsh`)选最高兼容版本; + sha256 校验通过后才写插件目录,原子切换 profile 链接,保留 previous 供 `--rollback`; +- `--apply` 先写 `pending.json`,在写完 `source:"updater"` 心跳后立即清除它;因为运行时还不写心跳, + pending 只用于发现“切换中途中断”,不是加载成功确认; +- **不做签名**:sha256 只防损坏,信任边界是本仓库与 GitHub 账号。 + +```powershell +# 完全退出 DSH 后: +node scripts/update.mjs --manifest "https://github.com/Curlance/dsh-computer/releases/latest/download/compat.json" --check +node scripts/update.mjs --manifest "https://github.com/Curlance/dsh-computer/releases/latest/download/compat.json" --apply +node scripts/update.mjs --rollback +``` + +计划任务(`node scripts/register-task.mjs`,登录时 + 每 6 小时)会传 +`--apply --home --manifest `,所以自动更新的命令已接通;但 DSH 运行时仍不写健康心跳, +新版本加载失败不会被自动发现,更新后要人工检查并手动 `--rollback`。细节与故障处理见 +[`docs/AUTO-UPDATE.md`](AUTO-UPDATE.md)。 + +## 卸载 + +```powershell +node scripts/uninstall.mjs --dry-run +node scripts/uninstall.mjs +``` + +删除托管插件行、profile 链接、当前版本目录和 `~/.dsh/skills/computer-use`;如果安装时备份过同名 +skill,会恢复最近一个 `skills-*` 备份。保留 `~/.dsh/computer/**`(审计、备份等用户数据)。 +卸载后重启 DSH。要恢复被迁移的旧版:先卸载,再 `node scripts/install.mjs --rollback`。 + +## 开发与测试 + +```powershell +npm test # node --test tests/*.test.mjs +node --test tests/tool.test.mjs # 单个文件 +node scripts/smoke.mjs # 真机只读冒烟(需要桌面 + cua-driver) +node scripts/smoke-action.mjs # 真机动作冒烟(会启动/清理一个 mshta 目标) +``` + +单测不需要 DSH、桌面或 cua-driver(宿主/驱动/时钟都是注入的);冒烟脚本才会碰真实桌面。 +CI 为 `.github/workflows/ci.yml`(windows-latest + Node 24 + `npm test`),不安装驱动。 + +## 文档 + +- [架构与不变量](ARCHITECTURE.md) · [安全模型](SAFETY.md) · + [自动更新](AUTO-UPDATE.md) · [验证证据](verification.md) · + [变更记录](../CHANGELOG.md) +- [设计](superpowers/specs/2026-10-21-dsh-computer-independent-design.md) · + [实现计划](superpowers/plans/2026-10-21-dsh-computer-a-b.md) + +## 已知限制 + +- 只支持 Windows 与主显示器;`target:{kind:"screen"}` 不支持多屏。 +- `focused_element` 等待条件在 cua-driver 0.36 上通常不命中(驱动不报告焦点元素)。 +- `policy.allowedApps` / `blockedApps` 只按窗口标题子串匹配;限流是进程内 60 s 窗口,重启清零。 +- AI 光标 glide 覆盖 `click`/`move`/`drag`/元素 `scroll`;`type`/`key`/`wait`/`launch`/`focus`/`resize`/`kill` 不移动光标。 +- 观察的 `budgetMs` 只能事后标记超时,不能取消进行中的 UIA 遍历。 +- 无运行时健康心跳:更新后无法自动确认新版本加载成功,回滚需要手动执行;无签名。 +- npm tarball 含运行时、`scripts/`、`docs/` 和 `skills/`;`tests/`、`.github/` 不在包内。 diff --git a/docs/images/README.md b/docs/images/README.md new file mode 100644 index 0000000..7fb2db1 --- /dev/null +++ b/docs/images/README.md @@ -0,0 +1,11 @@ +# README visual assets + +- `logo.svg`: original desktop-and-cursor mark. +- `overview.svg`: desktop workflow illustration (1120 × 510). +- `overview-mobile.svg`: narrow-screen composition (560 × 740). + +These are editable, self-contained SVGs without scripts, external fonts or raster dependencies. The interface is a schematic, not a product screenshot. Keep that distinction in the README caption. + +Palette: midnight `#12152c`, violet `#a78bfa`, cyan `#38bdf8`. + +Editorial references: [ppt-agent](https://github.com/Curlance/ppt-agent), [simulink-formula-modeler](https://github.com/Curlance/simulink-formula-modeler), [Cua](https://github.com/trycua/cua), and [Browser Use](https://github.com/browser-use/browser-use). These informed the centered header, concise introduction and quick-start structure; no upstream artwork was copied. diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..8a38bfb --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1 @@ +dsh-computerObserve, act and verify on a real Windows desktop with a visible AI cursor. diff --git a/docs/images/overview-mobile.svg b/docs/images/overview-mobile.svg new file mode 100644 index 0000000..858aab3 --- /dev/null +++ b/docs/images/overview-mobile.svg @@ -0,0 +1 @@ +dsh-computerObserve, act and verify on a real Windows desktop with a visible AI cursor.DESKTOP AUTOMATIONOne tool.A visible workflow.真实桌面,可见操作。DSH Agent → computer → Cua DriverWINDOWS DESKTOPAgent taskOBSERVATION / UI AUTOMATIONHello from dsh-computerelement: s00000001:2readback01 / OBSERVE截图 + 控件树02 / ACT授权后执行03 / VERIFY回读实际结果WORKFLOW ILLUSTRATION diff --git a/docs/images/overview.svg b/docs/images/overview.svg new file mode 100644 index 0000000..dfe4022 --- /dev/null +++ b/docs/images/overview.svg @@ -0,0 +1 @@ +dsh-computerObserve, act and verify on a real Windows desktop with a visible AI cursor.DESKTOP AUTOMATIONOne tool.A visible workflow.真实桌面,可见操作。DSH Agent → computer → Cua DriverVISIBLE CURSOR / APPROVALS / AUDITWINDOWS DESKTOPAgent taskOBSERVATION / UI AUTOMATIONHello from dsh-computerelement: s00000001:2readback01 / OBSERVE截图 + 控件树02 / ACT授权后执行03 / VERIFY回读实际结果WORKFLOW ILLUSTRATION