技能介绍

真实桌面的 UI 自动化痛点

很多工作流无法只靠终端命令或文件读写完成：打开应用、点击菜单、在网页里切换设置、确认界面发生变化，这些操作天然发生在像素级 UI 上。传统脚本要么依赖脆弱的定位器，要么无法处理尚未稳定的前端界面。Agivar 把这类任务交给 AI Agent 在真实桌面上执行：Agent 通过本地 MCP 服务拿到一个可以移动鼠标、键入文本、点击与导航的执行环境，任务结果也不再只是文本，而是带说明的截图和逐步验证记录。

核心能力与工作流

Agivar 以 http://127.0.0.1:17342/mcp 暴露 HTTP 服务，AI 客户端在桌面应用运行且已登录时即可调用工具。常用链路是：先调用 get_status() 确认不是忙碌或未登录；再调用 run_gui_task(task, context?) 派发任务，它会立即返回 task_id；随后持续轮询 get_task_result(task_id)，直到状态变成 completed、failed 或 partial。

终态结果包含 summary、observations 和 screenshots。summary 负责用自然语言描述每一步做了什么以及如何验证；screenshots 给出本地 .webp 路径和画面说明，工程师可以直接打开文件复核，而不是相信一句“已完成”。若任务结束后还需要补做步骤，应调用 send_task_message(task_id, message) 在同一会话里追加指令；需要中止时调用 cancel_task(task_id)。

适用边界与注意点

这是一个异步系统：run_gui_task 返回 started 只代表任务已被接收，真正结果必须靠轮询拿到。简单任务约需 2-5 分钟，复杂流程可能到 10-30 分钟；每隔 15-30 秒轮询一次比较稳妥。更关键的是一次只能运行一个任务，因为两个任务会争夺同一套鼠标和键盘，并发通常导致相互干扰。任务跑偏时应尽快取消，而不是等待超时。

task 必须自包含：明确入口 URL、要执行的交互和判定成功的最终状态，context 只补充背景。例如前端改动验证可写成“打开浏览器访问 http://localhost:5173/settings，切换主题开关为深色，并确认页面背景变暗”，而不是只说“改一下主题”。向用户报告时，应把步骤、截图链接、纯文本绝对路径和整体通过/失败结论一起给出。