dsh-quiet-windows 0.0.0-stage → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-quiet-windows contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,47 @@
1
- # Temporary Holding Version
1
+ # dsh-quiet-windows
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 让 agent 在屏幕上「看不见的地方」启动并操作 Windows 图形界面。
4
+
5
+ 窗口从创建起就停在所有显示器之外,agent 用 UI Automation 读控件、点控件,用 PrintWindow 截图——不吃遮挡、不怕离屏,并尽量避免抢键盘焦点。
6
+
7
+ ## 工具
8
+
9
+ | 工具 | 作用 |
10
+ |---|---|
11
+ | `quiet_launch` | 屏幕外启动程序,返回 `hwnd`;浏览器默认开独立 profile |
12
+ | `quiet_windows` | 列出屏幕外窗口,附显示器布局与 DPI |
13
+ | `quiet_shot` | 截图(窗口在屏幕外或完全被遮挡都拿得到) |
14
+ | `quiet_tree` | 读 UI Automation 控件树 |
15
+ | `quiet_act` | 按控件执行 invoke / set / select / toggle / expand |
16
+ | `quiet_close` | 收尾关闭;共享进程的窗口不会被强杀 |
17
+
18
+ ## 安装
19
+
20
+ ```json
21
+ plugin_manager install_bundle target: "<tgz 的绝对路径>"
22
+ ```
23
+
24
+ 装完重启 DSH,新会话即可在工具列表里看到 `quiet_*`。
25
+
26
+ ## 依赖
27
+
28
+ - Windows 10/11
29
+ - Python 3,且装有 `pywin32`、`uiautomation`、`comtypes`、`Pillow`
30
+ (插件会自动探测解释器;DSH 自带的运行时 Python 没有 pywin32,不能直接用)
31
+
32
+ ## 测试
33
+
34
+ ```powershell
35
+ python -m unittest discover -s tests -p "test_*.py" # 不碰桌面
36
+ node --test tests/tools.test.mjs # 不碰桌面
37
+ python tests/regress_browser.py --run # 会真的拉起浏览器
38
+ ```
39
+
40
+ ## 限制
41
+
42
+ - 只走控件模式:坐标点击在屏幕外不可用。
43
+ - 少数应用在屏幕外停止绘制,此时截图会报 `looks_blank`。
44
+ - 焦点是「尽量避免并自动恢复」,不是零干扰保证。
45
+ - 仅 Windows。
46
+
47
+ 详细说明与设计取舍见 [docs/DETAIL.md](docs/DETAIL.md)。
@@ -0,0 +1,11 @@
1
+ # dsh-quiet-windows:把「安静窗口」工具行插入 profile。
2
+ # 可选配置(覆盖本行 config 时整块替换):
3
+ # - id: quiet-windows
4
+ # name: 'dsh-quiet-windows'
5
+ # config:
6
+ # pythonPath: C:\Python312\python.exe # 非 PATH 时显式指定
7
+ # timeoutMs: 120000 # 单次操作超时
8
+ # launchTimeoutMs: 180000 # 启动等待窗口的上限
9
+ - insert:
10
+ - id: quiet-windows
11
+ name: 'dsh-quiet-windows'
package/docs/DETAIL.md ADDED
@@ -0,0 +1,89 @@
1
+ # 静默窗口(dsh-quiet-windows)
2
+
3
+ 智能体需要打开一个图形界面才能继续任务时,最烦人的是它把窗口甩到你桌面正中。这个插件把那条路换掉:**窗口从创建起就停在你所有显示器之外**,智能体照样能读它、点它、截图看它,但你一帧也看不到。
4
+
5
+ ## 它能做什么
6
+
7
+ | 工具 | 作用 |
8
+ |---|---|
9
+ | `quiet_launch` | 在屏幕外启动程序,返回窗口句柄 `hwnd` |
10
+ | `quiet_windows` | 列出所有屏幕外窗口,附带显示器布局、系统 DPI、前台窗口 |
11
+ | `quiet_shot` | 截图(PrintWindow):窗口在屏幕外、被完全遮挡都拿得到画面 |
12
+ | `quiet_tree` | 读 UI Automation 控件树:类型、文字、class、AutomationId、可用模式 |
13
+ | `quiet_act` | 按控件执行 invoke / set / select / toggle / expand,不依赖前台与坐标 |
14
+ | `quiet_close` | 收尾,先正常关闭再按需强杀 |
15
+
16
+ ## 典型流程
17
+
18
+ 1. `quiet_launch` 启动程序(网址、文件路径、启动参数一起给)。
19
+ 2. `quiet_shot` 看一眼当前画面,确认加载完成。
20
+ 3. `quiet_tree` 找到目标控件的名字或 `AutomationId`。
21
+ 4. `quiet_act` 直接操作那个控件(输入框用 `set`,按钮用 `invoke`,标签页用 `select`)。
22
+ 5. `quiet_close` 关掉它。
23
+
24
+ ## 运行前提
25
+
26
+ - Windows 10 / 11。
27
+ - 一个装好 **pywin32、uiautomation、comtypes、Pillow** 的 Python 3。
28
+
29
+ 插件不盲信 `python` 这个名字:它按 `pythonPath` 配置 → `python` → `py -3` → 常见安装目录的顺序逐个探测,并用 `import win32gui, uiautomation, comtypes, PIL` 实际验证。全部失败时,工具会直接报出一条能照做的错误,列出试过哪些解释器、各自缺什么。
30
+
31
+ **注意**:DSH 自带的运行时 Python 只有 Pillow,没有 pywin32,不能指向它。
32
+
33
+ ## 为什么不是「把它放到另一个虚拟桌面」
34
+
35
+ 实测过,不行:
36
+
37
+ - 窗口搬到别的虚拟桌面后,**从外部重新枚举它的 UI Automation 子树会失败**(只剩 1 个节点),智能体等于瞎了;只有搬之前抓在手里的元素还能用。
38
+ - 一旦某个操作让那个窗口成为前台,**Windows 会把你的屏幕直接切到它所在的虚拟桌面**——比占屏更打扰。
39
+ - 隐藏或最小化的窗口**搬不到虚拟桌面**(没有 AppView),想“零闪现进桌面”根本做不到。
40
+
41
+ ## 为什么不是「最小化」或「压在别的窗口下面」
42
+
43
+ - 最小化后系统不再为它合成画面:截图变黑、UIA 子树消失,而且浏览器一类应用会把定时器降频,等进度会卡死。
44
+ - 压在下面只是“看不见”:`Win+D`、任务视图、你自己把窗口最小化,都会把它翻出来。
45
+
46
+ ## 限制(都是实测结论)
47
+
48
+ - **坐标点击不可用**。窗口在虚拟屏幕之外,`SetCursorPos` 会被夹回屏幕范围。所以本插件只走控件模式;碰到处处画布的应用(游戏、远程桌面、部分自绘界面),必须短暂接管屏幕。
49
+ - **截图可能变黑**:应用若在离屏时停止绘制,`quiet_shot` 会报 `looks_blank`;如果 `PrintWindow` 本身失败,插件**不会落盘**,而是直接报错——半黑的图比“没有图”更容易骗到模型。
50
+ - **焦点是“尽量避免”,不是零干扰**。窗口显示前会被加上 `WS_EX_NOACTIVATE`,使它无法被常规激活;万一仍被抢走,插件会把前台还回去。但没有任何用户态手段能 100% 阻止所有程序的抢焦点行为。
51
+ - **仅 Windows**。
52
+
53
+ ## 浏览器与进程归属
54
+
55
+ 浏览器会把新窗口交给已经运行的实例,新进程随即退出——这时窗口属于旧进程,`kill` 可能把用户整个浏览器带走。所以:
56
+
57
+ - 启动 `msedge / chrome / brave / firefox` 时**默认开独立 profile**(放在 `%TEMP%\dsh-quiet-profiles`,每次启动顺手清理 6 小时前的旧目录)。
58
+ - 返回里的 `pid` 一律是**窗口所属进程**,启动器进程单独放在 `proc_pid`;两者不一致时 `process_mismatch` 为 `true`。
59
+ - 属于共享进程的窗口**不会被执行 `--kill`**,只关闭窗口本身。
60
+
61
+ ## 句柄安全
62
+
63
+ Windows 会复用窗口句柄。插件为每个启动的窗口记录 `hwnd → pid`,之后每次 `shot / tree / act / close` 都带上 `--expect-pid` 交给 helper 校验:句柄失效或被复用会直接拒绝,而不是操作到别的窗口上。
64
+
65
+ ## 测试
66
+
67
+ ```powershell
68
+ # 不碰桌面:纯计算 + 句柄校验 + 工具层
69
+ python -m unittest discover -s tests -p "test_*.py"
70
+ node --test tests/tools.test.mjs
71
+
72
+ # 会真的拉起浏览器(独立 profile、离屏),验证进程归属与截图
73
+ python tests/regress_browser.py --run
74
+ ```
75
+
76
+ ## 配置
77
+
78
+ 在 profile 的 `cordis.patch.yml` 里覆盖 `quiet-windows` 这一行的 `config`:
79
+
80
+ ```yaml
81
+ - id: quiet-windows
82
+ name: 'dsh-quiet-windows'
83
+ config:
84
+ pythonPath: C:\Python312\python.exe
85
+ timeoutMs: 120000
86
+ launchTimeoutMs: 180000
87
+ ```
88
+
89
+ `launchTimeoutMs` 是「等窗口出现」的总预算,helper 自身会收到比它小 8 秒的等待上限,确保超时也能返回结构化错误而不是被掐断。