API参考大全:Antigravity Phone Connect 全部HTTP端点清单与curl请求示例

原创2026-10-26 09:46:432,257 阅读

API参考大全:Antigravity Phone Connect 全部HTTP端点清单与curl请求示例

本文是 Antigravity Phone Connect 的完整 API参考:它把桌面端 Antigravity AI 会话实时镜像到手机,并提供远程发消息、停止生成、切换模型等能力。下面列出项目全部 HTTP 端点(如 /health、/snapshot、/send),逐一说明用途、请求参数,并附上可直接复制的 curl 请求示例,方便你用终端或脚本调用该服务。

Antigravity Phone Connect 手机镜像 AI 会话产品主图

💡 核心源码位于 server.js,所有路由都在这一个文件里;官方端点速查表见 CODE_DOCUMENTATION.md 的 "API Endpoints" 章节。

启动服务并确定 Base URL

所有端点都挂在同一个 Express 服务器上,默认端口 3000(可用环境变量 PORT 修改,定义见 server.js)。启动方式:

启动成功后终端会打印形如 http://192.168.1.5:3000 的地址(局域网 IP)。后文统一用 BASE_URL 指代它:

BASE_URL="http://192.168.1.5:3000"

认证规则很简单:同一局域网(LAN)内发起的请求自动免登录;只有走 ngrok / Cloudflare / Pinggy 隧道从外部访问时才需要密码登录。本地调试 curl 基本不用操心认证。

Antigravity Phone Connect 通过隧道实现全球远程访问 AI 会话

认证与会话管理:/login 与 /logout

端点 方法 请求体 说明
/login POST {"password": "..."} 校验 .env 中的 APP_PASSWORD,成功后签发 30 天有效期的签名 httpOnly Cookie(ag_auth_token)
/logout POST 无 清除会话 Cookie

curl 示例(外部访问场景,用 -c 保存 Cookie,后续请求用 -b 带上):

# 登录并保存会话 Cookie
curl -X POST "$BASE_URL/login" \
  -H 'Content-Type: application/json' \
  -d '{"password":"你的APP_PASSWORD"}' \
  -c cookies.txt

# 之后调用任意端点时携带 Cookie
curl "$BASE_URL/snapshot" -b cookies.txt

# 退出登录
curl -X POST "$BASE_URL/logout" -b cookies.txt

状态检查端点:快速判断服务是否就绪

查看服务健康:/health(GET)

最常用的"服务活着吗"检查接口,返回 CDP 连接状态、运行时长与是否启用 HTTPS:

curl "$BASE_URL/health"
# {"status":"ok","cdpConnected":true,"uptime":123.45,"timestamp":"...","https":false}

⚠️ 若 cdpConnected 为 false,说明还没连上 Antigravity,请确认它已用调试模式启动:antigravity . --remote-debugging-port=9000

查看 HTTPS 证书状态:/ssl-status(GET)

curl "$BASE_URL/ssl-status"
# {"enabled":false,"certsExist":false,"message":"No certificates found"}

查看聊天窗口状态:/chat-status(GET)

判断桌面端是否有打开的会话、是否已有消息、输入框是否就绪:

curl "$BASE_URL/chat-status"
# {"hasChat":true,"hasMessages":true,"editorFound":true}

排查 CDP 连接:/cdp-targets(GET)

依次探测 9000~9003 四个调试端口上可发现的 CDP 目标,是排查"连不上 Antigravity"问题的第一站:

curl "$BASE_URL/cdp-targets"

实时镜像数据端点:/snapshot 与 /app-state

Antigravity 桌面会话 1 秒实时同步镜像到手机

获取实时聊天快照:/snapshot(GET)

核心端点。服务端每秒轮询一次桌面会话,内容变化时更新缓存;调用时直接返回最新一份快照,包含清理后的 html、全量 css、滚动位置 scrollInfo 与统计信息 stats。首次启动尚未抓到内容时返回 503:

curl "$BASE_URL/snapshot" | head -c 300
# {"html":"<div id=\"conversation\">...","css":"...","scrollInfo":{"scrollPercent":0.02,...},"stats":{...}}

手机端页面就是靠它渲染镜像界面的,想验证"镜像是否正常",看这个端点最直接。

获取当前模式与模型:/app-state(GET)

返回桌面端当前的思考模式(Fast / Planning)和 AI 模型名:

curl "$BASE_URL/app-state"
# {"mode":"Planning","model":"Gemini 3 Flash"}

获取历史会话列表:/chat-history(GET)

自动点击桌面端历史按钮并抓取会话标题列表:

curl "$BASE_URL/chat-history"
# {"chats":[{"title":"...","index":0}, ...]}

远程控制端点:发消息、停止、新建会话

发送消息:/send(POST)

把一段文本注入桌面 Antigravity 输入框并自动提交。参数 message 必填(缺失返回 400)。该接口采用"乐观返回"——只要注入尝试完成即返回 success: true,客户端随后刷新快照确认:

curl -X POST "$BASE_URL/send" \
  -H 'Content-Type: application/json' \
  -d '{"message":"帮我总结当前改动"}'
# {"success":true,"method":"click_submit","details":{...}}

停止 AI 生成:/stop(POST)

点击桌面端取消按钮,中断当前生成:

curl -X POST "$BASE_URL/stop"
# {"success":true}

一键新建会话:/new-chat(POST)

等价于点击桌面右上角的 + 按钮:

curl -X POST "$BASE_URL/new-chat"
# {"success":true,"method":"data-tooltip-id"}

切换历史会话:/select-chat(POST)

参数 title 必填(来自 /chat-history 返回的标题,缺失返回 400):

curl -X POST "$BASE_URL/select-chat" \
  -H 'Content-Type: application/json' \
  -d '{"title":"修复登录bug"}'

关闭历史面板:/close-history(POST)

向桌面端派发一次 Escape 键事件,收起历史抽屉:

curl -X POST "$BASE_URL/close-history"

精确控制端点:点击、滚动、模式与模型切换

远程点击元素:/remote-click(POST)

三个可选参数配合定位目标:selector(CSS 选择器)、index(第几个匹配项)、textContent(按文字过滤)。内置"叶子节点过滤",保证点中的是最内层精确按钮:

curl -X POST "$BASE_URL/remote-click" \
  -H 'Content-Type: application/json' \
  -d '{"selector":"button","index":0,"textContent":"Run"}'

远程滚动同步:/remote-scroll(POST)

把手机滚动位置同步到桌面,scrollPercent(0~1,推荐)或 scrollTop 二选一:

curl -X POST "$BASE_URL/remote-scroll" \
  -H 'Content-Type: application/json' \
  -d '{"scrollPercent":0.5}'

切换思考模式:/set-mode(POST)

mode 只接受 Fast 或 Planning:

curl -X POST "$BASE_URL/set-mode" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"Planning"}'
# {"success":true}

切换 AI 模型:/set-model(POST)

model 传下拉列表中的名称,如 Claude Sonnet 4.5,脚本会自动打开选择器并完成点击:

curl -X POST "$BASE_URL/set-model" \
  -H 'Content-Type: application/json' \
  -d '{"model":"Claude Sonnet 4.5"}'
# {"success":true}

SSL 与调试端点

生成 SSL 证书:/generate-ssl(POST)

等价于执行 generate_ssl.js,在 certs/ 目录生成自签名证书,需重启服务后生效:

curl -X POST "$BASE_URL/generate-ssl"
# {"success":true,"message":"SSL certificates generated! Restart the server to enable HTTPS."}

调试 UI 结构:/debug-ui(GET)与 /ui-inspect(GET)

/debug-ui 返回序列化的 UI 树文本;/ui-inspect 返回页面所有可见按钮、图标的坐标、aria-label、svg 类等详细元数据(实现见 ui_inspector.js),开发或适配新版 Antigravity 界面时非常有用:

curl "$BASE_URL/ui-inspect"
# {"summary":{...},"frames":[...],"contexts":[...],"usefulButtons":[...],"bestContextData":{...}}

Antigravity Phone Connect 跨设备通信架构与安全示意

全部 HTTP 端点清单(速查表)

# 方法 端点 关键参数 作用
1 POST /login password 密码登录,签发会话 Cookie
2 POST /logout — 退出登录
3 GET /health — 服务状态与 CDP 连接检查
4 GET /snapshot — 最新聊天快照(html/css/滚动)
5 GET /ssl-status — HTTPS 与证书状态
6 POST /generate-ssl — 生成自签名证书
7 GET /app-state — 当前模式与模型
8 GET /chat-status — 会话/消息/输入框状态
9 GET /chat-history — 历史会话标题列表
10 POST /send message 向 AI 发送消息
11 POST /stop — 停止当前生成
12 POST /new-chat — 新建会话
13 POST /select-chat title 切换到指定历史会话
14 POST /close-history — 关闭历史面板
15 POST /remote-click selector、index、textContent 远程精确点击
16 POST /remote-scroll scrollPercent / scrollTop 远程滚动同步
17 POST /set-mode mode 切换 Fast / Planning
18 POST /set-model model 切换 AI 模型
19 GET /debug-ui — 序列化 UI 树(调试)
20 GET /ui-inspect — 按钮/图标元数据(开发)
21 GET /cdp-targets — 探测 9000~9003 调试端口

另外,服务器在同一端口上还运行 WebSocket 服务(ws:// 或 HTTPS 下的 wss://),快照更新时向所有已认证客户端推送 snapshot_update 通知——这是手机页面能秒级刷新的关键。

常见 HTTP 状态码与排查

状态码 含义 处理建议
401 Unauthorized 外部访问未登录:先调 /login,或用带 ?key=密码 的 Magic Link
400 Bad Request 缺少必填参数(message 或 title)
503 Service Unavailable CDP 未连接或快照尚未生成:确认 Antigravity 以 --remote-debugging-port=9000 启动且已有打开的会话

相关文件索引

登录后查看全文
antigravity_phone_chat