智能体集成

从只观察的适配器开始

二进制文件提供本地操作能力，任务选择和操作授权交给你的智能体来做。最简单的集成不需要模型 SDK、API key，也不需要拼 shell 命令。

完成快速开始之后，把下面的代码保存为仓库根目录下的 observe.py，然后运行 python3 observe.py。它只接受一种结构化操作：以参数数组启动程序，检查退出码，解码输出，最后打印 observation.png 的路径。

import base64
import binascii
import subprocess
from pathlib import Path

binary = Path("target/release/nano-use").resolve(strict=True)

def observe(action):
    if action != {"command": "screenshot"}:
        raise ValueError("This adapter accepts screenshot only")
    result = subprocess.run(
        [str(binary), "screenshot"],
        shell=False, check=True, capture_output=True, timeout=30,
    )
    try:
        png = base64.b64decode(result.stdout.strip(), validate=True)
    except binascii.Error as error:
        raise RuntimeError("Invalid base64 output") from error
    if not png.startswith(b"\x89PNG\r\n\x1a\n"):
        raise RuntimeError("Output is not a PNG")
    Path("observation.png").write_bytes(png)
    return Path("observation.png").resolve()

print(observe({"command": "screenshot"}))

打开那张 PNG 看看观察结果。FileNotFoundError 说明二进制文件找不到或工作目录不对；CalledProcessError 说明截图命令失败了；TimeoutExpired 说明超过了 30 秒。遇到这些错误时，不要继续执行输入操作。

每次只扩展一种命令

这个示例只接受 {"command": "screenshot"}。传入 {"command": "type", "text": "hello"} 或多出来的字段会被拒绝——这是故意的。它是一个适配器示例，不是完整的智能体框架或安全沙箱。

当你要加入输入命令时，记得校验命令名、参数数量、坐标的有限性和文本长度上限。保持固定的二进制路径和 shell=False，千万不要把模型输出拼进 shell 代码。位置参数可能以 - 开头的，前面加 --，详见命令参考。

观察、操作、验证

1. 截图，检查当前桌面。
2. 找到具体目标，确认下一步操作属于用户的任务范围。
3. 执行一次允许的输入操作。
4. 再次截图，确认结果符合预期后再继续。

退出码为零并不能证明事件真的到达了目标窗口。显示缩放、窗口焦点和权限仍然是调用方的责任。工具本身没有自主规划器、远程传输或 MCP 服务。把截图发给模型是你的集成层另外做的事情。