agent-ctl · 桌面动作闸门

给「敢让 AI 动手、但必须能事后证明它干了什么」的人： 人类签发 → AI 执行 → 全程可审计 → 随时可急停。

Windows 上的「桌面动作闸门」：人类签发通行证 → AI 执行 GUI 动作 → 全程留证据 → 急停文件一键全停。

TL;DR (English) — A Windows-only desktop action gate for AI agents: human issues a pass → the agent acts → every action leaves evidence → one kill switch. Experimental 0.x personal project: no SLA, API may change. Needs Windows 10/11 x64 + Python 3.12 + git. Default-deny by design (nothing moves until a human issues a pass); scope is deliberately narrow — see「适用范围（很有限）」below. Keywords: computer-use agent · MCP server · desktop action gate · Windows automation · agent safety · audit trail.

⚠ 这是第一次开源的个人项目：由作者与几位协作者共同维护，技术与运营都还不成熟。 不提供 SLA、不承诺兼容性、会有破坏性变更。 详见 免责声明。

协作者：本仓已开放 GitHub / Gitee 协作者权限，欢迎提 PR。 贡献者名单见 CONTRIBUTORS.md，贡献流程见 CONTRIBUTING.md。

成熟度自评（2026-10-25 · 外部评审原话，作者接受） 设计层接近成熟，实现层半熟，验证层基本没有。 · 设计：安全模型 / fail-open 防御 / capture 绑定 / 租约语义达到生产系统推演水准； · 实现：闸门内核质量高，但 core.py 巨石、双 gate 生成、错误码历史包袱是没还完的债； · 验证：判据全部跑在作者自己的机器上，A/B 只有 3/3 小样本，零外部用户、零真实故障史。 ⇒ 完成度很高，成熟度很低；可以当“本机可控实验 + 设计参考”，不建议现在拿它当生产防线。 走向成熟的关键路径：外部真实环境跑坏它 → 坏法变成判据 → 桌面判据进 CI（自托管 runner）→ core.py 瘦身 → API 冻结一个周期。

Copyright (c) 2026 GALAXYLLIYI 源码头部建议加一行 SPDX 标识：# SPDX-License-Identifier: Apache-2.0（统一补头由维护者处理）

只说三句

1. AI 点之前，必须你点头；点之后，必须留下证据。

2. 一份通行证管 30 分钟 60 次，一个急停文件能立刻全停。

3. 它点错窗，这一击根本发不出去——并告诉你该关哪个窗；不会骗你说成功。

Related MCP server: guarded-computer-use-mcp

五道闸（每个 UI 动作落到键鼠之前，依次过）

人类签发（弹窗一次给 ABCD，30 分钟/60 次） → 租约（任务→窗口，只追加不覆盖，子随父亡）
→ 帧凭据（旧帧点新画面 = 拒绝） → 敏感窗服务端终判（--xy 直点也拦）
→ 急停一票否决（文件级，拉下即全灭） ⇒ 证据链（前后差分 / hit_test 归属 / 决策日志）

装完默认关闭：没有通行证，A/B/C/D 一律拒（这是设计，不是没装好）。急停三通道：面板 ⏹ / Ctrl+Alt+Home / 删急停标志；关面板 ≠ 解除急停。

这是给谁的 / 不是给谁的

适合

• 愿意为每一次动作做授权与复核的人 —— 本项目的全部价值就在这一步。

• 需要「事后能证明 AI 干了什么」的场景：合规留痕、复盘、交接。

• 在自己的机器上跑、愿意接受「默认拒绝、逐次签发」这个节奏的实验者。

不适合

• ❌ 无人值守批量点击 —— 每 60 次动作就要人点一次授权，这正是它的设计，不是缺陷。

• ❌ 绕过风控 / 验证码 / 权限边界 —— 本项目不做这个，也不应被用来做这个。

• ❌ 需要 SLA 的生产环境 —— 实验性个人项目，无可用性承诺、无响应时限。

• ❌ 需要稳定兼容性的集成方 —— 0.x 阶段，接口与契约会主动变。

装之前先看三句

1. 环境：Windows 10/11 x64 + Python 3.12 + git（建议 PowerShell 7）。Linux / macOS 不支持。

2. 装完默认什么都不通——这是设计，不是装坏了：没有通行证，A/B/C/D 一律拒；要先用面板「🔑 授权」或 CLI 签发。

3. 目前不是安装包：是脚本安装（install.ps1，不往系统目录写新 exe、因此无需代码签名）。从 Release 下 zip 的话，先核 agentctl.zip.sha256 再装。

安装

仓库拓扑（2026-10-24 起）：

两个仓都已公开；下载安装包请到 Release（附 agentctl.zip.sha256）。

主仓与镜像现同名 computer-use-gate（旧链接自动重定向）。

公开仓：

git clone https://gitee.com/GALAXYLIYI/computer-use-gate ; cd computer-use-gate ; pwsh -File .\install.ps1

一行装（先看清脚本再跑更稳）：

irm https://gitee.com/GALAXYLIYI/computer-use-gate/raw/main/install.ps1 -OutFile install.ps1
notepad install.ps1      # 看一眼
.\install.ps1

离线：python -X utf8 tools\pack_dist.py 生成 dist\agentctl.zip，目标机 .\install.ps1 -Zip .\agentctl.zip。更新=重跑同一条命令；.\uninstall.ps1 卸载（数据保留），-Purge 全清。旧版详细安装/构建/已知问题见 docs\README_旧版存档_v1.2.md。

下载压缩包时先核哈希再装（发布页会同时提供 agentctl.zip.sha256）：

Get-FileHash .\agentctl.zip -Algorithm SHA256
# 与 .sha256 文件里的第一列逐字符比对；不一致就别装、重新下载

默认关闭（装完什么都不通，这是设计）

• 默认无通行证 ⇒ 一切动作一律被拒：ctl_authorize 之前，所有写动作都返回未授权；急停 flag 一票否决。

• 怎么开：调用 ctl_authorize（或跑 python -X utf8 tools\申请授权.py）→ 屏幕上弹窗，由人点「允许」， 弹出时现场签发密钥（写进 _auth\auth_pass.json，默认 30 分钟 / 60 次）；弹窗不可被 agent 代点。

• 怎么自验：python -X utf8 tests\_默认关闭_判据.py（默认全拒、显式放行后才通、急停压过一切）。

明确不做什么

• ❌ 不做通用 CUA（点得准是别人的战场）

• ❌ 不做多 agent 调度平台（派单不是产品能力）

• ❌ 不承诺 VLM 升级（未接线就是假承诺；must_vlm 只如实报"不可用原因"）

• ❌ 不发布 IDG 隐形网格（p95 尾部未压到 400ms 前不上）

能力边界与已知限制

下面每条都来自仓内已实测的记录（文件名可回查），不是设计愿望。

适用范围（很有限 —— 先看这条）

本项目现在只适合：Windows 桌面 + 已授权 + 有人值守的短时操作。 很多能力仍在开发中， 请不要按「通用 RPA / 无人值守框架」的预期来用它：

• ✅ 能做：在一台 Windows 机器上，让被授权的 agent 通过 MCP / CLI / 面板做可留痕的点击、打字、窗口操作； 慢应用有加长观测；出错给明确码（成功 / 没测出来 / 确认没变）。

• ⛔ 不能做：Linux / macOS；云端或远程控制；无人值守批量；验证码/风控绕过；需要 SLA 的生产集成； Canvas、游戏、PDF 内嵌、未开无障碍的 Electron 等 UIA 看不见的界面（只能截图兜底，等于「看不清」）。

• 🚧 开发中：多显示器与缩放适配、更丰富的感知通道、更多业务工具（答题/作业等）、跨机器配置迁移。

一句话：它是「安全可控的个人电脑操作面」，不是万能助手；功能会继续加，但现在请按上面的范围用。

等生效：有效预算比名义预算少一整轮

• 生产点击路径的等生效预算是 450ms（legacy_tools\act.py 里 do_click 三处传 budget_ms=int(_settle(450)*1000)； AGENTCTL_SETTLE_MS 环境变量可调）。⛔ act.py 里的 POLL_BUDGET_MS = 800 只是函数默认值、不是生产值 —— 拿 800 去定性能曲线会系统性偏一倍（docs\七小时任务_阶段总结_20221022.md、docs\意见\意见_windowB_20221022.md）。

• 实测：名义 450ms 只能覆盖约 431ms 的响应延迟。差的那一整轮不是应用慢，而是 need=2 迟滞要求「多一帧确认」， 在预算边界上把「看见了但来不及确认」判成了「没变」（docs\发现_有效预算比名义预算少一轮_20221023.md）。

• 实测检测率矩阵（预算 450ms）：响应 0ms / 100ms / 200ms 检出率 100%，300ms 及以上整段掉到 0% ⇒ 切线在 200ms，不在 450ms（同上，§一）。

• 填字路径的总预算是 1500ms（POLL_BUDGET_MS_FILL），与点击不是同一个数。

• core 侧另有一层 300ms 的回落预算（framecache.WAIT_BUDGET_MS = 300）；M20「core 甲案」在判「确认没变」之前 用 core 自己的尺子再看 ≤300ms（docs\实测_M20_core加长观测_20221023.md）。

判词是三态，不是两态

M19 → M19′ → M19P → M19P2 这一串修复的就是这件事：「没测出来」曾被报成「确认没变」，现在统一走三态映射 （docs\实测_M19_语义修复_20221023.md、docs\实测_M19P2_同族两处_20221023.md）。

判据与桌面

• 判据规模（2026-10-25 实测口径）：主清单 60 条登记（python -X utf8 tests\run_all.py --list）； 仓库里 76 个「判据」文件、107 个测试文件。对外说数量请用这两个可核的数，别用记忆里的旧数。

• 桌面相关判据必须在有交互桌面会话的 Windows 上跑：无头会话 / 服务 / CI 跑不了。 tests\run_all.py 文件头的原话是「别把它当 CI 判据使」。

• 部分窗口不支持 PrintWindow（部分 WinUI/DWM、DRM/游戏类画面）⇒ 取不到帧时如实报「取不到」，不猜。

• UIA 控件树对自绘 / Canvas / 游戏 / PDF 视图只能拿到窗口壳 ⇒ 要退到「截图 + 编号标注」路线。

视觉感知的已知代价

• OCR 走系统自带 WinRT OCR（不额外下模型）；首扫有暖机成本：真页 0.5s 只拿到 18 节点外壳，3s 稳定到 49 节点 （docs\AGENT接口.md §ctl_screen）。

• must_vlm 通道未接线 —— 如实报「不可用原因」，不做假承诺。

• 定位有多条路（坐标 / 元素 id / 控件名 / OCR / CDP），按可靠性递降；旧帧点新画面一律拒绝（code=12）。

平台

• Windows 10/11 x64（用到 WinRT OCR，需 Win10 1903+）；Python 3.10+（开发版本 3.12）。

• ⛔ 不承诺特定 Windows 版本矩阵，也不承诺与未来版本兼容。

隐私与数据边界

• 无遥测、不上传任何数据。 本项目没有任何上报 / 统计 / 回传逻辑；服务只监听 127.0.0.1。

• 证据只落本机 work\ 目录（时间线 jsonl、前后帧指纹、决策日志）。 ⚠ 证据里含前后屏幕截图，属敏感本地数据 —— 不要提交到版本库。 work\ 已被 .gitignore 排除，但发布前仍要自己核一遍。

• 动作日志含窗口标题与坐标 —— 窗口标题可能带文件名、账号、客户名；日志转发给别人前先过一遍。

• 授权状态、通行证、急停标志写在本机 %LOCALAPPDATA%\AgentCtl\（可用 AGENTCTL_HOME 改）。

• 分发包刻意不含：baseline\（历史快照，含真实手机号 / 授权状态 / 明文 API Key）、work\、dist\、 __pycache__、*.bak*。打包走 tools\pack_dist.py 的白名单 + 隐私复扫，核验走 tools\verify_dist.py （独立重新实现一遍判据，不信打包脚本 —— 同一份代码既是运动员又是裁判，出错就一起错）。

• 提交前扫一遍：python -X utf8 tools\presubmit_scan.py（扫 git 索引里已暂存的内容： 手机号 / 密钥字面量 / 个人绝对路径 / 本地 agent 凭据引用 四类）。

安全与授权边界

• 只在用户明确授权的窗口上动作。 授权通过弹窗现场签发，弹窗不可被 agent 代点； 密钥明文不落盘、不回显（只存加盐 SHA-256），主 agent 物理接触不到。

• 默认关闭：装完、开机、重启之后，没有通行证 ⇒ A/B/C/D 四档一律被拒。装完不会替你签任何证。

• 急停三通道（任选其一，关面板 ≠ 解除急停）：面板 ⏹ / Ctrl+Alt+Home 全局热键 / 删急停标志。 急停一拉下，所有自动控制当场停，并联动吊销当前租约。

• 敏感窗服务端终判：用户的授权弹窗（标题 本地 agent电脑控制授权）任何动作一律禁止 —— 不问、不放行。

• 租约只追加不覆盖，子随父亡：同一时刻只允许一个 agent 动手；拿不到租约就只能看。

• 观测与动作绑定：点击必须带 from_capture，不许凭记忆点坐标；不拿「看起来对」当判据。

• ⛔ 不要用于绕过风控、验证码或权限边界。 本项目是「让授权过的动作留下证据」， 不是「帮你通过它不该通过的检查」。

• ⛔ 不要第一次就在生产机 / 有真实账号的机器上开闸。 先在测试环境、测试账号上把整套流程走一遍。

免责声明

• 本项目是实验性的个人项目，由作者与几位协作者共同维护，技术与运营都不成熟。

• 不提供 SLA：没有可用性承诺、没有响应时限承诺、没有赔偿承诺。

• 不承诺兼容性：0.x 阶段 API、契约、判据口径都可能变；会主动做破坏性变更， 升级前请读 CHANGELOG.md。

• 不承担因误用造成的损失：包括但不限于误点、误填、误删、误提交、账号风控、设备异常。 本项目提供的是「让动作可审计」的能力，不是「保证动作正确」的能力。

• 证据链只证明「发生了什么」，不证明「这应该发生」。

• 自担风险，请先在测试环境验证。

开发环境（要改这个仓的人看这节）

# 建 .venv、装依赖、跑一遍无桌面依赖的闸门
pwsh -File tools\dev_env.ps1

判据分三层（无桌面依赖 / 要桌面 / 已知红），一键脚本、环境变量表、目录速查、 提交前流程、常见坑，全部在 docs\开发环境.md。

★ 判据分两层这件事很重要：tests\run_all.py 要真弹窗、真抓屏、真抢全局热键， 无头会话跑不了 —— 它的文件头就写着「别把它当 CI 判据使」。 CI 跑的是另一套（语法 / 静态 / 契约 / 提交前扫描），见 .github\workflows\ci.yml。

文档导航

公开可推荐

历史实测记录（保留本机路径，仅供追溯）

⚠ 这一组文档保留了当时那台机器的绝对路径，仅供追溯当时的实测现场； 它们不是面向外部读者的推荐阅读材料，路径需在公开前脱敏。

docs\实测_M16_加速第二刀_20221022.md｜docs\实测_M17A_导入归因_20221022.md｜docs\实测_M18d_numpy轻量化_20221023.md｜ docs\实测_M19_语义修复_20221023.md｜docs\实测_M19P2_同族两处_20221023.md｜docs\七小时任务_阶段总结_20221022.md｜ docs\交接_M19P与下一刀_20221023.md｜docs\意见\*（裁决与意见存档）

许可

本项目采用 Apache License 2.0，详见 LICENSE。

• 允许使用、修改、分发、再分发，包括闭源商业使用。

• 保留版权声明与 NOTICE，注明变更。

• Apache-2.0 额外提供专利授权与专利诉讼终止条款。

• 本仓库不设任何附加限制 —— 不追加任何与 Apache-2.0 冲突的使用条款。

• Copyright (c) 2026 GALAXYLLIYI

• 源码头部建议加 # SPDX-License-Identifier: Apache-2.0（统一补头由维护者处理）

第三方许可

本项目再分发了第三方组件（vendor\ 里的预编译包、requirements.txt 的直接依赖）。 完整的清单、版本、SPDX 许可证标识、来源 URL 与用途见 THIRD_PARTY_NOTICES.md。

⚠ Apache-2.0 §4(a)/(d) 要求随分发附上本许可原文，并在第三方组件带 NOTICE 时保留其 NOTICE 声明； 各依赖自身的许可条款同样必须遵守。第三方许可原文已随包提供（逐项见 THIRD_PARTY_NOTICES.md）。

漏洞报告

优先走平台的 Private Vulnerability Reporting（Gitee 仓库页的漏洞报告入口）—— 这样漏洞细节在修复前不公开可见。

报告请写清：版本 / commit、复现步骤、观察到的行为、期望的行为。 不要在公开 issue 里先发漏洞细节。

处理方式：先私下修好，再公开发布修复，并给受影响版本留出升级期。详见 SECURITY.md。

贡献指南

见 CONTRIBUTING.md，行为准则见 CODE_OF_CONDUCT.md。

第一次来？照着 docs\贡献者上手指南.md 走 —— 接受邀请 → 配环境 → 认证 → 切分支 → 提 PR，一步一步带命令和常见坑。

一句话版本：0.x 阶段 API 可能变，请以 docs\ 里的实测记录为准；PR 要附判据退出码 + 复现步骤。

致谢

• 仓里 44 条判据（tests\）与「注入必红」的自证纪律，是这个仓最值钱的部分。

• 视觉方向的公开文献书目见 docs\视觉参考书目_20261019.md；社区已有路径的调研见 docs\电脑控制_社区路径调研_20261002.md。

• 感谢每一个提 issue、跑判据、补文档的人。

• 本仓贡献者名单见 CONTRIBUTORS.md（协作者与署名贡献者都在那里）。

验收口径（端到端注入必红 5~8 条 / 人工交互 ≤1 / 点错窗报成功 = 0）见 docs\判据降载清单.md。