Hermes - Antigravity 协同控制网关项目规划书

文件版本：v1.0 | 编制人：Worker (Local Sys-Ops) | 时间：2026年5月20日

项目概述： 本项目旨在打通 Hermes Agent（脑端控制/TUI网关/长期记忆） 与 Antigravity CLI (本地 Headless 物理执行节点)。通过在本地建立基于 Loopback RPC 或私有 A2A 通道的本地桥接器，在不将敏感 OAuth 凭证写入云端配置的前提下，实现“指令在云端（Telegram/Hermes 脑），代码调试在本地（Antigravity 物理沙箱）”的闭环，最大化、安全合规地使用用户已付费的 Gemini Pro 订阅额度。

一、 项目背景与介绍 (Project Introduction)

随着大语言模型应用从“一问一答”走向“多步循环智能体 (Agentic Workflows)”，代码重构与系统级调试的 Token 消耗量呈指数级上升。单次中等复杂度的重构任务在云端沙箱中多次编译交互，极易消耗上百万 Token（计费高达数十美元）。

与此同时，用户手头已订阅 Google AI Pro / Gemini Advanced ($20/月)。该订阅在 Google 官方最新的 Antigravity 2.0 / Antigravity CLI 运行期中，本身就享有充足的、不额外收费的高额 API 调用与沙箱计算额度。然而，如果通过常规的 API Key 方式调用，Google 会对 API Key 独立计费，无法复用个人订阅。

本项目核心突破：
通过在本地 VPS 或主机上部署 Headless 运行的 antigravity-cli 作为物理执行器（继承已登录的 Google AI Pro 订阅身份），再由 Hermes 作为高层控制大脑。当用户在 Telegram 中下达维护或代码重构指令时，Hermes 仅通过轻量指令调用本地 Antigravity 运行任务，将重度的、多轮循环的 Token 消耗和安全隔离沙箱运行全部留在 Antigravity 内部消化，实现零额外 API 账单成本的高阶运维自动化。

二、 架构设计与数据拓扑

为了保证安全性，架构采用 “控制面与物理执行面分离” 的设计，确保用户的 Google OAuth Session 永远不离开本地物理设备：

┌────────────────────────────────────────────────────────┐ │ 云端 / 网关层 (Control Plane) │ │ │ │ [用户 Telegram] ◄───(富文本通知/HTML 报告)───► [Hermes] │ └───────────────────────────┬────────────────────────────┘ │ │ (1. 安全内网通道 / 本地 loopback RPC) ▼ ┌────────────────────────────────────────────────────────┐ │ 本地物理执行层 (Execution Plane) │ │ │ │ [A2A 本地代理桥 (FastAPI / 50行) ] │ │ │ │ │ │ (2. 本地子进程拉起, 自动继承个人 Pro 凭证) │ │ ▼ │ │ [antigravity-cli (Headless Daemon)] │ │ │ │ │ │ (3. 跑调试 Loop / 本地沙箱编译 / 原地改代码) │ │ ▼ │ │ [本地持久化代码仓 / VPS 运维目标目录] │ └────────────────────────────────────────────────────────┘

三、 阶段性实施规划与里程碑

阶段 1：环境锚定与 Pro 凭证持久化验证 (Phase 1)

工期：1 天 目标：打通本地 Headless 运行与 Pro 账户额度识别

任务项 具体实施步骤 交付物 & 验证标准
Antigravity CLI 升级 1. 在运行 Hermes 的物理机/VPS 上检查并更新 antigravity-cli。
2. 运行 antigravity auth login 完成 OAuth 登录绑定 Google AI Pro。 		在终端执行 antigravity auth status，确认 Pro 订阅状态处于 Active 且额度生效。
Headless 运行期测试 1. 建立临时空测试目录。
2. 使用命令行模式一键唤醒并测试编译：
antigravity run-task --prompt "写一个快速排序" --dir "./test" 		1. 检查 ./test 下是否生成正确代码。
2. 确认本地沙箱在无 IDE 图形界面下成功自主闭环。

阶段 2：本地 A2A 协议微型桥接器开发 (Phase 2)

工期：2 天 目标：构建 Hermes 到本地 CLI 进程的安全调用管道

任务项 具体实施步骤 交付物 & 验证标准
编写 Local-A2A Bridge 1. 使用 Python/FastAPI 在本地 localhost 环回网卡上暴露出 /.well-known/agent.json。
2. 声明本节点为 "antigravity-local-coder"，具备 sandbox_compile 等本地专属工具。 		可以通过 curl http://127.0.0.1:8500/.well-known/agent.json 成功读取标准 A2A JSON 卡片。
命令封装与映射 1. 接收来自 Hermes 的 POST /api/a2a/message 异步任务请求。
2. 桥接器将请求参数（如目标工作路径、具体 Prompt）进行安全过滤与转义，通过 Python subprocess 唤醒本地的 antigravity run-task。 		接口可安全将外来指令转换为本地 CLI 任务执行，防止任意命令注入风险。

阶段 3：异步任务状态追踪与 Artifacts 热挂载 (Phase 3)

工期：2 天 目标：实现长耗时任务的挂起监听与本地结果秒级回传

任务项 具体实施步骤 交付物 & 验证标准
异步轮询与通知机制 1. 由于代码深度调试属于耗时任务（长达几分钟），采用非阻塞任务模型。
2. 本地 Bridge 记录任务句柄，Hermes 定期通过 Background Polling（或 Bridge 在任务结束时主动向 Hermes 回调 Webhook）获取状态。 		任务开始后，Hermes 网关能立刻释放当前会话进程，并显示“任务运行中”，完成后自动通过 Telegram 弹窗。
成果物 (Artifacts) 提取 1. 任务完成后，自动读取 Antigravity 原地修改的文件 Diff。
2. 将修改前后的代码差异和编译测试报告整合为标准的 A2A Artifact 响应。 		Hermes 接收到含有 Diff 和状态的 JSON Payload，并在内存中进行同步确认。

阶段 4：级联整合与多渠道网关上线 (Phase 4)

工期：1 天 目标：双智能体并轨，在 Telegram 中进行可视化操作

任务项 具体实施步骤 交付物 & 验证标准
Hermes TUI / Tool 绑定 1. 在 Hermes 的 worker profile 工具集中注册 mcp:antigravity-local 工具。
2. 配置 Hermes 的 TUI，增加对 Antigravity 执行成果的可视化展示卡片。 		在 Telegram 中输入 /antigravity 修复 ./src/auth.py 的报错，任务能自动流转。
双向通信联调与报告输出 1. 联调完整生命周期，并在运行结束时将重构报告自动转换为富文本 HTML，通过本地 Report Center 发布并呈送给用户。 最终交付成果包含直观的变更统计（LOC 增减、测试通过率标签等），用户一键确认即可同步。

四、 核心安全与防封控策略 (Risk Management)

⚠️ 关键风控提醒：
为了杜绝因高频自动化套壳导致 Google AI Pro 订阅账户被判定为“滥用/Abuse”而面临封号风险，本项目在控制层（Bridge）必须硬性嵌入以下限制：