智慧體整合

從僅觀察的介接程式開始

執行檔提供本機操作能力，任務的選擇和操作授權交給你的 Agent 來處理。最簡單的整合不需要模型 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"} 或多出來的欄位會被拒絕——這是故意的。它是一個介接範例，不是完整的 Agent 框架或安全沙箱。

當你要加入輸入命令時，記得校驗命令名稱、參數數量、座標的有限性和文字長度上限。保持固定的執行檔路徑和 shell=False，千萬不要把模型輸出拼進 shell 程式碼。位置參數可能以 - 開頭的，前面加 --，詳見命令參考。

觀察、操作、驗證

1. 截圖，檢查目前桌面。
2. 找到具體目標，確認下一步操作屬於使用者的任務範圍。
3. 執行一次允許的輸入操作。
4. 再次截圖，確認結果符合預期後再繼續。

結束代碼為零並不能證明事件真的到達了目標視窗。顯示縮放、視窗焦點和權限仍然是呼叫端的責任。工具本身沒有自主規劃器、遠端傳輸或 MCP 服務。把截圖傳給模型是你的整合層另外做的事情。