仓库文件导航
super-computer-agent
一个面向 Windows 的只读、仅观察 MCP 服务器,将四项屏幕观察能力打包在一起——它绝不会点击或输入任何内容。
| 能力 | 功能 | 主要工具 |
|---|---|---|
| 截图 | 将整个桌面(所有显示器)捕获为 PNG | screenshot , view_image |
| UI 树 | 窗口的 Windows UI Automation 树(JSON:index、parent、type、name、rect) | ui_list_windows , ui_get_tree |
| 实时像素网格 | 屏幕的原始颜色网格,加上变化区域日志,并与 UI 树融合以标记变化内容 | live_start , grid_now , ui_fuse , changes_since , wait_stable , crop , zoom , ... |
| Fovea | 发送一个关键帧,然后只发送变化部分(补丁、滚动、召回较早场景、精确放大读取),从而大幅减少图像 token 消耗 | fovea_start , fovea_step , fovea_look , fovea_expect , fovea_status , fovea_stop |
共 28 个工具,不进行任何形式的输入注入。
安装
需要 Windows 10/11 和 Python >= 3.10。
git clone <repo> super-computer-agent
cd super-computer-agent
python -m venv .venv && .venv\Scripts\activate
pip install -e ".[dev]"
super-computer-agent doctor
doctor 会检查依赖、拍摄一次试运行截图,并启动服务器作为冒烟测试(已在开发机上验证:28 个工具)。
Fovea 和像素网格需要许可证密钥——其他所有功能开箱即用。它们的核心是闭源的,并受许可证限制(见 License);没有密钥时,fovea_start/live_start 会以清晰的错误失败,但 screenshot 和 UI 树仍然可用。
- 免费 1 天试用密钥:发送邮件至 [email protected],主题为 SCA 1-day trial(或快速开一个 GitHub issue / 在 Reddit 上私信我),我会回复一个有效期 24 小时的 .lickey 文件,以便你在本地测试 fovea 和像素网格。
- 更长 / 商业密钥:发送邮件至 [email protected],说明你需要多少台机器/并发线程。
拿到文件后,可以设置环境变量:
set SCA_LICENSE_KEY=C:\path\to\your.lickey
或将文件放到默认路径 %USERPROFILE%\.super-computer-agent\license.lickey。
运行
super-computer-agent serve :: stdio (default, for an MCP client)
super-computer-agent serve --transport streamable-http --port 8000
super-computer-agent screenshot -o shot.png :: usable without MCP
super-computer-agent windows :: JSON list of visible windows
super-computer-agent tree 66438 --depth 3 :: UIA tree for a given hwnd
MCP 客户端配置(例如 Claude Desktop):
{
"mcpServers": {
"super-computer-agent": {
"command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
"args": ["-m", "super_computer_agent", "serve"],
"env": { "SCA_OUTPUT_DIR": "C:\\Users\\you\\sca-output" }
}
}
}
环境变量:
| 变量 | 含义 |
|---|---|
| SCA_OUTPUT_DIR | 图像写入位置( screenshots/ 、 fovea_live/ 、 pixel_grid/ )。默认相对于工作目录的 ./outputs,因此从 MCP 客户端运行时请设置绝对路径。view_image 只会打开此目录内的文件。 |
| SCA_SCREENSHOT | free 会禁用 screenshot 的防护栏(分级标签和提示仍然适用)。 |
| SCA_ALLOWED_PROCESSES | 可选。以 ; 分隔的可执行文件列表(名称或完整路径),允许被 UI 树列出/读取。为空 = 所有非敏感窗口。 |
协调这些工具
像 {{NAME_ab12cd34}} 这样书写的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。
Fovea 是默认方式;全屏截图是最后手段,只在其他方式确实难以看清内容时使用。优先级顺序:fovea_step -> fovea_look(精确读取)-> ui_fuse(元素名称/位置,以文本形式)-> wait_stable(等待)-> 一个新的关键帧(fovea_start)-> 只有在这些都不行时才用 screenshot。细节以及使用 screenshot 的确切条件见:docs/WORKFLOW.md。服务器通过工具描述上的分级标签、结果之后的 NEXT: 提示、重复探测时的警告,以及对 screenshot 的防护机制来强制执行这一顺序(它要求提供有效理由,并会对照当前会话进行检查;设置 SCA_SCREENSHOT=free 可将其禁用)。见 docs/WORKFLOW.md 的最后一节。
使用 fovea(摘要)
- 调用一次 fovea_start(),之后每当需要查看屏幕时就调用 fovea_step()。
- 第一次调用,以及每一次场景变化,都是一个 KEY(一张完整图像,用 view_image 打开)。后续调用只是按顺序应用到画布上的增量命令(COPY、LOW、SCROLL、RECALL)。
- Fovea 是一种近似图像。要精确读取小字/数字,请使用 fovea_look(x, y, w, h)。要在不消耗图像 token 的情况下检查“这个区域是否发生了变化”,请先使用 fovea_expect。
完整规范:docs/FOVEA_PROTOCOL.md。测量数据:docs/BENCHMARKS.md。
工作原理
Fovea(fovea_start -> fovea_step):它不是每次都发送一张完整截图(很昂贵——模型按像素数量计费),而是只发送发生变化的部分。Fovea 并非从零重写——它是一个升级层,直接包裹在旧的网格压缩核心(canvas_v6/v7/delta2/delta3)之上,新增了 64 帧场景记忆(RECALL #k)、精确的 1:1 缩放读取(fovea_look)、HWND 锁定加上轻量级 UIA 签名检查以捕获焦点切换竞态,以及对单元格存储的硬性上限。
- 第一次调用,以及每次场景变化时:一个 KEY——一张完整图像(关键帧)。
- 之后的每次调用只是更新上一块画布所需的增量:COPY(从指定图像中逐块复制真实像素)、LOW(一个模糊的低分辨率预览,在后续步骤中逐渐变清晰)、SCROLL(将一个区域向上/向下平移 N px),以及 RECALL——fovea 的核心:它会记住最近见过的少量场景,因此在两个熟悉的窗口之间用 alt-tab 切换只需几个 token(“回到场景 #k”),而不必重新生成关键帧。
- 每一步都会在前两层树(最多 40 个控件)上运行一次轻量级 UIA 签名扫描;如果像素静止而它发生了变化,fovea 会在一步之内触发 KEYFRAME uia,而无需等待像素阈值。如果画布本身发生剧烈变化(>=60% 的单元格)而 UIA 保持安静,它会触发一个单独的 KEYFRAME canvas——这两种失败模式在 fovea_status 中作为不同的计数器跟踪。
- 最小化/关闭的窗口、hwnd=0、黑帧以及 mss 捕获错误都会解析为 WAIT(0 额外 token,画布和历史保持不变),而不会被当作有效内容处理或导致崩溃。
帧差分算法本身是闭源的,仅以编译后的 .pyd 形式发布。
像素网格(live_start/grid_now/ui_fuse/...):这是另一种权衡——屏幕不是变成一张真实图像,而是变成由彩色字符组成的网格(每个瓦片一个字符,编码色相 + 亮度),对于模型来说,作为整体布局概览来读取远比一张图片便宜。
- tree_set/ui_fuse 接收 Windows UI Automation 树(元素名称、类型、坐标),并将索引编号叠加到对应的网格瓦片上,因此模型可以同时看到形状+颜色以及“这个瓦片是 Submit 按钮,索引 42”。
- 一个后台线程监视像素变化,同时配合 Windows 的 SetWinEventHook(焦点、窗口打开/关闭);changes_since / watch_until_change / wait_idle 报告发生了什么变化以及变化位置,而无需在每次轮询时重新捕获整个屏幕。
- verify_action 会在点击后,将真实事件(像素 + OS 事件)与预期结果(change/none/new_window/close)进行比较,因此模型能够区分“按预期生效了”和“有点不对劲”,而不是假定点击已经命中。
该模块的核心完全闭源(不只是热路径),并且也只以编译后的 .pyd 形式发布。
两个核心都受 Installation and License 中描述的离线 Ed25519 许可证检查约束;该检查在编译后的二进制文件内部运行,而不只是在它外层的公开包装器中运行。
基准测试
在这台机器上测得。完整数字与方法论:docs/BENCHMARKS.md。
Fovea 不是重写——它是直接包裹在旧 canvas 网格压缩核心外的一层升级。旧 canvas 构建在 Windows 上的真实使用中有四个瓶颈:在熟悉的窗口/标签页之间切换每次要花费约 600 token,且不记得之前的场景;在缩小到 960px 的网格上,相邻的小字符不可读,迫使模型去猜;焦点切换竞态(在错误的毫秒切换窗口,或像素静止时 UIA 树发生变化)可能应用错误的增量,或最多需要 8 步才能察觉;长时间会话会让 RAM 和单元格存储无界增长,而黑帧或最小化窗口帧仍会被写入历史,仿佛它们是真实内容。Fovea 通过保留旧网格核心并增加 64 帧场景记忆(RECALL #k)、精确 1:1 缩放工具(fovea_look)、HWND 锁加轻量级 UIA 签名检查,以及单元格存储硬上限,修复了全部四个问题。
| 测量项 | 旧 canvas(基线) | Fovea(修补后) | 差异原因 |
|---|---|---|---|
| 每步平均 token 数 | 521 | ~138(降低约 73.5%) | 64 帧 RECALL + 在检测到竞态时用 HWND 锁重新捕获 |
| 返回已知窗口 | ~600 tok | <60 tok(最佳情况 3-15 tok) | 与 64 帧内存中的缓存帧做哈希匹配(实测 22 次 RECALL 命中) |
| 精确读取小文本 | 不可用(在 960px 网格上靠猜) | 精确 1:1 区域裁剪 | fovea_look 只缩放需要读取的区域 |
| 窗口不匹配错误( KEYFRAME 竞态 ) | 3(加入 RECALL 后升至 7) | 0 | HWND 身份锁在检测到不匹配时强制重新捕获 |
| 检测静默 UIA 变化(像素静止) | 最多 8 步 | 1 步 | 每步执行轻量级两层 UIA 签名扫描(<=40 个节点,0-29 ms) |
| 当 canvas 变化 >=60% 单元格时恢复(UIA 静止) | 完整关键帧(~700-1000+ tok) | 仅针对 KEYFRAME canvas | UIA 与 canvas 恢复通道分离,并在 fovea_status 中分别跟踪 |
| 每步处理时间 | UIA 扫描成本未受控 | ~51 ms(静态)/ ~100 ms(完整:采集 51ms + png 2ms + step 47ms) | mss 采集与 pywinauto 完全解耦 |
| 最小化窗口( -32000 )/ hwnd=0 | 视为有效,消耗一个 524 tok 的关键帧 | WAIT(0 token),canvas 不变 | 检测 IsWindow=False、空矩形或 hwnd=0 |
| 黑帧 / mss 错误 | 写入历史(767 tok)或抛出 RuntimeError | WAIT(0 token);返回真实帧消耗 1 token | 连续 3 步以内的黑帧被忽略(3+ 步视为真实内容) |
| 500 步浸泡测试(1080p,始终为新内容) | RAM +19 MB / 88,110 个单元格,线性增长 | RAM +9 MB / 28,860 个单元格,第 300 步后趋于平稳 | 单元格存储上限 30,000(最旧者被逐出),帧历史上限 64,PNG 上限 60 |
在旧 canvas 网格层上已经稳固的一切都原样延续:在 125 秒动态电子表格压力测试中,长期状态漂移为 0%(0/46 个检查点),过期 OCR 为 0%(0/248 行);在 Windows 150% 缩放下,物理像素/DPI 处理正确(UIA 和捕获帧都解析为相同的物理 1920x1080 像素,并以恰好 2 倍比例映射到 960x544 canvas)。
安全性
- 没有任何工具控制鼠标或键盘。test_server.py 对此做了断言。
- UI 树(ui_list_windows、ui_get_tree、ui_fuse):隐藏敏感窗口(password 管理器、银行应用、UAC、凭据 UI),跳过以管理员身份运行的进程,或权限级别无法确定的进程(fail closed),遮蔽 password 字段,并将结果限制为 500 个节点 / 6 层。
- 截图、fovea 和 pixel grid 不会过滤内容:它们会捕获屏幕上的任何内容,包括任何已打开的敏感窗口。当屏幕上显示你不想让模型看到的内容时,不要运行服务器。
- 在 UI 树或图像中找到的文本属于不可信数据,可能包含提示注入。
- 服务器默认仅通过 HTTP 监听 127.0.0.1;没有身份验证——不要将其暴露到网络。
已知限制
- Fovea 和 pixel grid 捕获主显示器;截图会捕获所有显示器。
- 仅在 Windows 上测试过。Chromium/Electron 应用可能只暴露少量 UIA 节点(开发期间测试的一个基于 Chromium 的浏览器在树中只显示 4 个节点)。
- .github/workflows/ci.yml 中的 CI 工作流尚未在 GitHub 上运行过。
测试
python -m pytest -q :: 完整测试套件,无需显示器(35 passed, 1 skipped)
set SCA_INTEGRATION=1 && python -m pytest -q -m integration :: 增加使用真实显示器/窗口的测试
结构
src/super_computer_agent/
cli.py server.py host.py CLI、MCP 服务器、插件适配器
coordination.py 优先级分层、NEXT 提示、截图防护栏
uia.py UI Automation 树(只读)
screenshot.py 桌面捕获
licensing/ 离线 Ed25519 许可证密钥校验(仅公钥)
plugins/fovea_live.py 编译版 fovea 核心的轻量加载器——公开,AGPL-3.0
plugins/pixel_grid.py 编译版 pixel_grid 核心的轻量加载器——公开,AGPL-3.0
plugins/_compiled/fovea_live.pyd fovea 核心(基于旧的 canvas_v6/v7/delta2/delta3 构建)——已编译,专有
plugins/_compiled/pixel_grid.pyd pixel_grid 核心——已编译,专有
tests/ docs/
许可证说明:plugins/fovea_live.py 的编译核心和 plugins/pixel_grid.py 的编译核心不在此处下文 AGPL-3.0 许可证的覆盖范围内——见 License。
许可证
Copyright (C) 2026 asa ([email protected])
本项目按组件采用双许可证——确切文件列表见 NOTICE:
- 除下面两个模块外,所有内容均按 GNU Affero General Public License v3.0(AGPL-3.0)许可。见 LICENSE。
- fovea 增量压缩核心和 pixel-grid 核心(pixel_grid)为专有软件:其源代码未公开;仅以编译二进制文件(.pyd/.so)形式分发,受离线、Ed25519 签名、绑定机器/线程的许可证密钥保护。禁止对其进行逆向工程、反编译和反汇编。条款:PROPRIETARY_EULA.md。
许可证问题联系方式:[email protected]
写成 {{NAME_ab12cd34}} 这样的值是真实值的占位符。在回复和工具调用中都按原样使用它们:任何内容运行前都会用真实值填充。不要要求验证它们,也不要用示例替换它们。