# 桌面控制 · 使用说明

> 一句话：**你可以直接让 AI 帮你操作电脑上的软件。**
> 它不是"看图猜位置"，而是直接读软件界面里的元素清单（控件树），所以点得准、能核对、不会乱动你的鼠标。

---

## 1. 它能帮你做什么

- 打开程序、系统设置页、文件、网址
- 在软件里找到按钮/菜单/输入框并点击（会优先用控件本身的方式点击，**不移动你的鼠标**）
- 往输入框里填字、发送快捷键（`Ctrl+S` 这类）
- 读界面上的文字、数字、表格内容、勾选状态
- 等某个窗口或某段内容出现，再继续下一步
- 管理窗口：切到前台、最大化、最小化、移动、关闭
- 截图（如果你用的是支持看图的模型，它会直接看到图）

**你只要用中文说需求，不用记任何工具名。**

---

## 2. 五分钟上手（真实例子）

**例一：让它算个数**
> 你：打开计算器，算 1234 × 56，把结果告诉我。
>
> 它会：打开计算器 → 读出所有按键 → 依次"按"下 1、2、3、4、×、5、6、= → 读结果 → 告诉你答案。
> 全程鼠标不会动，你能看到计算器上的数字自己在变。

**例二：读界面状态**
> 你：看一下"设置"窗口里 WLAN 现在是开还是关？
>
> 它会：找到设置窗口 → 读控件树 → 告诉你开关状态（它读的是界面真实状态，不是猜的）。

**例三：填表**
> 你：在记事本里输入"今天的待办：1. 交报告"，然后 Ctrl+S。
>
> 它会：往编辑区写字 → 按保存 → 告诉你结果。

**例四：关窗口**
> 你：把 QQ 窗口关掉。
>
> 它会：找到 QQ 窗口 → 关闭 → 确认窗口确实消失了。

---

## 3. 怎么跟它说话（三句经验）

1. **说清是哪个窗口**："在记事本里…" 比 "在那个窗口里…" 好用得多。
2. **一次一件事**：一步一步来，比一口气给十个步骤稳。
3. **不对就让它重看**："再看看现在界面是什么状态" —— 它每次动作后都会比对"什么变了"，没变它会自己重新看，不会瞎点。

---

## 4. 什么时候会问你（审批）

默认是**跟着 DSH 走**：DSH 会弹审批时就弹给你确认，DSH 本身已经关掉审批（比如"完全放开"权限预设）就直接执行。

你可以在**面板**里改：

| 设置项 | 作用 |
| --- | --- |
| 审批模式 | **跟随 DSH**（默认）/ **总是询问**（每次都问，没人回答就拒绝）/ **从不询问**（全放行） |
| 信任进程 | 加进去的软件**不再询问**，比如你常用的记事本、Excel |
| 禁止进程 | 这些软件**永远不许动** |
| 只允许这些进程 | 一填就变成白名单，只许动列出来的软件 |
| 动作后自动对比 | 每次动手后重新看一遍并列出"新增/消失/变化的元素"（建议开着） |
| 快照上限 | 一次最多读多少层、多少元素（读得太慢时可以调小） |

**读操作从不询问**（看窗口、看控件树、看元素详情、读剪贴板、截图），**会改变状态的操作才问**（点击、输入、按键、启动程序、写剪贴板、改窗口）。

**每个动作都会留痕**，包括"看过什么"，记录在
`%APPDATA%\dsh-desktop\harness\storages\dsh-desktop-uia\audit.jsonl`，面板里也能直接看。

---

## 5. 面板怎么看（设置 → 桌面控制）

![面板：服务状态、窗口列表、控件树、元素详情、动作日志](docs/images/panel.png)

| 区块 | 内容 |
| --- | --- |
| **服务状态** | 后台助手是否在跑、进程号、是否管理员权限；旁边有刷新 / 自检 / 重启服务 |
| **窗口** | 当前所有可见窗口（进程、标题、PID、状态）；点一行就会读它的控件树，点"切到前台"把它调到前面 |
| **控件树** | 选中窗口的界面元素清单（每个元素都有编号、类型、名字、可用操作）；点某个元素看它的详细属性 |
| **动作日志** | AI 做过/看过什么、结果如何、有没有被拒绝 |
| **设置** | 上面第 4 节那些开关，改完即时保存；其中"读取操作也记入日志"关掉后，只记写入动作，方便在很长一串翻找里看清"到底改了什么" |

面板只做"看 + 配置"，不会替你点东西——真正动手的永远是经过审批的动作。

---

## 5.5 它能自己发现错误（1.1 版新增）

AI 看不见屏幕，所以有几类错误它特别容易犯。这版把这几种情况变成了它会读到的提示，你不需要额外做什么：

| 情况 | 现在的表现 |
| --- | --- |
| 点一个按钮**弹出了对话框** | 动作结果里直接告诉它新窗口叫什么、句柄多少：`new window appeared: "另存为" (notepad pid=111)`，让它接着去读那个新窗口，而不是继续对着旧窗口发呆 |
| 启动程序后找不到窗口 | `desktop_launch` 会等最多 5 秒，把新窗口的名字和句柄报出来 |
| 某个窗口**读起来很慢**（浏览器、Java 程序） | 第一次慢就会说明原因，并建议"只查某一个元素"；从下一次起自动把读取范围收紧，不再每次都硬读整棵树 |
| 同一个按钮**连点两次都没反应** | 第二次会在结果里标注"这是第 2 次无效点击"；**第三次同样的点击会被直接拒绝**，并告诉它先看清元素状态、或改用输入/选择/展开的方式。复选框、下拉框这类"点两次状态会变"的控件不算在内；重新读一次窗口，或加 `force: true`，都可以继续点 |
| 控件树被上限截断了 | 结果里会说明被截断，以及该调大哪个上限 |

这样即使你不盯着，它也不会陷进"点—没反应—再点"的死循环。


---

## 6. 安装 / 卸载 / 更新

**最省事：双击安装（不用命令行）**

1. 打开项目的 [Releases 页面](https://github.com/1jiegejiayouxuewangan1/dsh-desktop-uia/releases)，下载最上面那个版本的 `dsh-desktop-uia-<版本号>.zip`（页面里数字最大的那个就是最新版）
2. 解压到任意目录（比如桌面新建一个文件夹）
3. **双击 `install.cmd`**，窗口里会显示安装进度，最后停在"请按任意键继续"
4. 重启 DSH Desktop，工具和面板就出现了

压缩包里已经带了编译好的后台助手，所以这一步不会调用任何编译器。窗口里的英文提示依次是：`[install]` 各步骤 → 最后一行是 `[OK] Installed`（成功）或 `[X] Installation failed`（失败，上面会写原因）。

**从源码目录安装（命令行）：**

在插件目录（`ds harness\dsh-desktop-uia`）里执行：

```powershell
# 安装（已有编译好的助手就跳过编译；加 -Rebuild 强制重编）
powershell -ExecutionPolicy Bypass -File install.ps1

# 装完必须重启 DSH Desktop，工具和面板才会出现
# 更新：改完源码后重跑 install.ps1 -Rebuild（装的是 profile 内的副本，需要刷新一次）
# 卸载（双击 uninstall.cmd，或加 -Purge 连设置和日志一起删）
powershell -ExecutionPolicy Bypass -File uninstall.ps1
```

**只想改几个字／改完代码想立刻生效？** 不用重装，用"同步"脚本（它会逐个文件比对，只复制变了的）：

```powershell
# 只看会改哪些文件，不真写
powershell -ExecutionPolicy Bypass -File scripts\dev-sync.ps1 -WhatIf
# 真同步（改完记得重启 DSH Desktop 才会加载）
powershell -ExecutionPolicy Bypass -File scripts\dev-sync.ps1
```

DSH 实际加载的不是源码目录，而是 `%APPDATA%\dsh-desktop\harness\profiles\web\node_modules\dsh-desktop-uia` 里的副本——所以"改了代码没反应"通常是忘了同步 + 重启。自检会替你查这一项。

自检（不启动 DSH 也能跑，会真读你的桌面）：

```powershell
node dsh-desktop-uia\scripts\doctor.mjs
```

输出里最后是 `RESULT: PASS` 就一切正常；`[FAIL] the installed copy matches this checkout` 说明上面的副本是旧的，跑一次 dev-sync.ps1 即可。

---

## 7. 常见问题

**问：为什么有的软件"读不出界面"？**
答：终端、游戏、画图、部分播放器是"自己画出来的"，系统看不到里面的元素。这类只能靠截图兜底。**网页建议用浏览器工具**（更快更准），桌面软件才用这个插件。

**问：为什么动不了某个软件？**
答：那个软件是"以管理员身份运行"的，而 DSH 不是。要么把那个软件用普通权限打开，要么**以管理员身份启动 DSH**。

**问：它说"元素已失效"是什么意思？**
答：界面刷新了（比如切了标签页），之前的元素编号作废。它会重新读一次，你不需要做任何事。

**问：鼠标会不会乱跑？**
答：默认不会。点击优先用控件自己的方式（Invoke/Value 等模式），窗口被挡住也能点、鼠标纹丝不动。只有自绘界面才退化成坐标点击。

**问：它会不会乱点我的东西？**
答：三层保护：① 会改变状态的操作都要过审批（或至少留痕）；② 每次动手后都有"什么变了"的对比，没变就说明没生效，它会重新看；③ 禁止/只允许名单可以兜死范围。

**问：某个窗口读起来特别慢？**
答：浏览器、Electron 类软件（VS Code、各种客户端）的界面接口本身慢。可以让它"只找某个按钮"而不是"读整棵树"，会快很多。1.1 版起它会自己说出"这个窗口慢"，并自动把读取范围收紧。

**问：它一直点同一个按钮却没反应？**
答：1.1 版起，第三次完全一样的无效点击会被拒绝，并提示它换方式（或重新读一遍界面）。你看到"refused"不是出错，是在拦它。确实需要连点时，让它加 `force: true`。

**问：我改了插件源码，为什么行为没变？**
答：DSH 读的是 profile 里的副本。跑一次 `scripts\dev-sync.ps1`，然后重启 DSH Desktop。

**问：面板打不开 / 显示 404？**
答：说明 DSH 还没重启，插件没加载。重启 DSH Desktop 即可。

**问：会不会自己乱来（不受我控制地操作）？**
答：它只在你的对话里、按你的要求动手，而且动手前后都有记录可查（动作日志 + `audit.jsonl`）。真出问题，把"信任进程"清空并把审批模式改成"总是询问"，就变成每步都要你点头。

---

## 8. 想更深入了解

- 完整技术说明（工具清单、审批实现、性能取舍、故障排查）：同目录 `README.zh-CN.md`（英文版 `README.md`）
- 英文使用说明（给国外用户看的同一份）：同目录 `GUIDE.md`
- 自动测试与自检：`node --import ./test/helpers/register.mjs --test "test/*.test.mjs"`、`node scripts/doctor.mjs`