Agivar

概述

Agivar 是一款桌面应用。它内置的本地 MCP 服务让 AI 客户端（如 WorkBuddy、Claude Code 或 Cursor）能够在真实桌面上执行可视化 GUI 任务。你只需用自然语言描述任务；Agivar 会操作真实屏幕（移动鼠标、输入、打开应用），并返回执行结果。

本 Skill 说明如何连接 Agivar，以及更重要的，如何正确处理异步任务工作流。

前置条件

运行任何任务前，必须满足：

1. 本机已安装 Agivar 桌面应用。如未安装，请先前往 Agivar 官网下载安装：https://agivar.fittentech.com/
2. 本机正在运行 Agivar 桌面应用。
3. 用户已在 Agivar 内登录。未登录时任务会失败。

MCP 服务会随应用自动启动，无需用户手动启动。如果无法连接，最可能的原因是应用未运行。

连接方式

服务使用 HTTP（Streamable HTTP、无状态 / JSON 响应）。

工具

返回结构

• run_gui_task 返回 { status: "started", task_id, message }。Agivar 未就绪（例如已有任务在运行）时，返回 { status: "failed", error }。
• get_task_result：
  • 运行中：{ status: "running", elapsed_seconds, summary, new_observations, observations_total, message }
  • 已结束：{ status: "completed" | "failed" | "partial", summary, observations, screenshots, duration, error }
    • summary：任务的自然语言结果，其中包含 Agent 如何验证任务成功；仅阅读它也应能判断是否完成。
    • observations：本次运行中的关键工具调用摘要列表。
    • screenshots：{ path, caption } 列表。每个 path 是运行过程中保存的本地 .webp 文件，不是 base64；caption 描述对应屏幕画面。应结合 summary 和带说明的截图判断任务是否真正成功。需要查看时可打开这些路径。在 Windows 上，路径使用正斜杠，避免 Markdown 链接丢失反斜杠。
    • summary 会按步骤验证任务，并引用每张截图的完整绝对路径，与 screenshots[].path 一致。参见后面的“向用户报告结果”。
  • 对已结束任务再次轮询会返回相同的最终结果，具有幂等性，因此可在决定是否继续前再次读取。
• send_task_message 返回 { status: "started", task_id, message }，表示任务重新在后台运行，之后应按 run_gui_task 的方式轮询；若 task_id 不存在、会话被删除，或另一个任务正在运行，则返回 { status: "failed", error }。
• cancel_task 返回 { status: "stopping" | "already_done" | "failed", task_id, message }。
• get_status 返回 { logged_in, busy, running_tasks }。

工作流（必须严格遵循）

run_gui_task 会立即返回，任务在后台运行。必须轮询才能获得结果。这是最重要的规则。

get_status()                 # 建议先确认 logged_in=true、busy=false
   ↓
run_gui_task(task="...")      # 获得 task_id
   ↓
get_task_result(task_id)      # 每 15-30 秒轮询一次
   ↓  status == "running"  → 等待后继续轮询
   ↓  status in {completed, failed, partial} → 结束
阅读 summary 和带说明的 screenshots → 审核结果
   ↓  还需要继续？ → send_task_message(task_id, "下一步指令") → 再次轮询
   ↓  已满足？     → 停止

这是一个持续循环：派发任务 → 轮询 → 审核 summary 和带说明的截图 → 决定结束或继续。需要下一步时，优先使用 send_task_message，不要新建 run_gui_task；这样 Agent 可以保留之前会话的完整上下文。

重要规则及原因

1. 始终轮询到终态。 不要因为 run_gui_task 已返回就认为任务已完成。每 15-30 秒调用一次 get_task_result(task_id)，直到 status 为 completed、failed 或 partial。简单任务通常需要约 2-5 分钟，复杂工作流可能需要 10-30 分钟。过于频繁地轮询会浪费调用轮次；完全不轮询则永远无法获得结果。
2. 一次只能运行一个任务，绝不能并发运行两个任务。 GUI 任务操作同一台真实桌面；两个任务同时运行会争夺鼠标和键盘，导致相互干扰。只要 get_task_result 仍返回 running，就不要再次调用 run_gui_task，否则会得到 status:"failed"。若需切换任务，先调用 cancel_task 取消当前任务，或等待它结束。
3. 任务必须自包含且具体。 将明确步骤和预期最终状态放在 task 中，将额外背景放在 context 中。Agivar 自身的 Agent 会决定细粒度操作，因此清晰的目标优于模糊的描述。网页 UI 测试尤其如此：应写明 URL、精确交互和“通过”的判断标准。例如，验证前端改动时：

task="打开浏览器，访问 http://localhost:5173/settings，切换主题开关为深色，并确认页面背景变暗"，context="开发服务器已经运行；主题开关刚刚重构。"

1. 任务跑偏时取消，不要被动等待。 cancel_task(task_id) 会请求任务停止；任务将很快以 partial 状态结束，随后 get_task_result 会返回已经完成的内容。继续轮询，直到获得终态。
2. 需要继续时复用会话，不要从头开始。 任务结束后，若要追加步骤，请调用 send_task_message(task_id, "...")，而不是 run_gui_task。前者会保留已经打开、输入和导航过的所有上下文。同样遵守一次一个任务的规则：只在任务到达终态后再发送后续消息，然后重新轮询。只有完全无关的新工作才应新建 run_gui_task。先阅读 summary 和带说明的 screenshots，再判断是否真的需要继续。

向用户报告结果（逐步展示证据）

任务结束后，不要只转述结果，而应把验证过程一并呈现，让用户能够自行检查。summary 已按步骤说明验证过程，并引用每张截图的完整绝对路径。回复中应：

1. 按步骤呈现结果，并与 summary 中的验证过程对应。
2. 对每一个引用截图的步骤，同时给出可点击的 Markdown 链接和紧随其后的纯文本绝对路径。某些客户端中链接可能无法点击，纯文本路径仍可让用户手动打开。以 screenshots[].path 为唯一权威路径。
3. 最后给出整体通过/失败结论。

例如，不要只写“已完成。点赞成功。”；应写成：

任务完成。确认步骤如下：

1. 打开 B 站首页 — 页面正常加载且已登录
   截图 [01_gui_sub_task.webp](C:/…/mcp_shots/<conv>/01_gui_sub_task.webp)
   路径：C:/…/mcp_shots/<conv>/01_gui_sub_task.webp
2. 进入视频《非十科技 - agivar 产品介绍》 — 播放器正常显示
   截图 [02_gui_sub_task.webp](C:/…/mcp_shots/<conv>/02_gui_sub_task.webp)
   路径：C:/…/mcp_shots/<conv>/02_gui_sub_task.webp
3. 点击点赞 — 点赞按钮变为蓝色高亮
   截图 [03_gui_sub_task.webp](C:/…/mcp_shots/<conv>/03_gui_sub_task.webp)
   路径：C:/…/mcp_shots/<conv>/03_gui_sub_task.webp

整体结论：任务成功完成，点赞按钮处于已点赞状态。如需进一步操作，可继续用 send_task_message。

这样，每个结论都有可点击或可按路径打开的截图作为依据，用户可以据此决定是否继续当前会话。

端到端示例

1. get_status()
   → { "logged_in": true, "busy": false, "running_tasks": 0 }

2. run_gui_task(task="打开系统计算器，计算 23 * 19，并告诉我结果")
   → { "status": "started", "task_id": "a1b2c3d4e5f60718", "message": "..." }

3. get_task_result("a1b2c3d4e5f60718")
   → { "status": "running", "elapsed_seconds": 12.3, "message": "..." }   # 等待 15-30 秒后继续轮询

4. get_task_result("a1b2c3d4e5f60718")
   → {
       "status": "completed",
       "summary": "已打开计算器，输入 23 × 19；屏幕结果为 437，确认任务完成。",
       "observations": ["gui_sub_task：已打开计算器并输入表达式", "..."],
       "screenshots": [
         { "path": ".../mcp_shots/<conv>/01_gui_sub_task.webp", "caption": "计算器显示 23 × 19 = 437" }
       ],
       "duration": 0,
       "error": null
     }

5. # 若结果还不满足，可在同一会话中继续，保留上下文：
   send_task_message("a1b2c3d4e5f60718", "现在再计算 437 + 100，并告诉我总数")
   → { "status": "started", "task_id": "a1b2c3d4e5f60718", "message": "..." }   # 再次轮询

排障

• 无法连接 / 工具列表为空：确认 Agivar 正在运行；访问端口 17342 的健康检查。
• 任务持续失败：调用 get_status()；若 logged_in 为 false，请用户先登录 Agivar。
• run_gui_task 返回失败并提示已有任务运行：用 get_task_result 轮询当前任务，或调用 cancel_task 取消后再派发新任务。
• 用户在哪里看到任务：每个任务都会出现在 Agivar 主窗口中，作为标题为 MCP: <任务前 30 个字符> 的会话，并实时展示执行进度。