astrbot_plugin_antigravity_acp
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 8 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
免反代、免 API Key:把 Google Antigravity 经官方 agy CLI 的 ACP 协议接成 AstrBot 原生 Provider,支持思考、工具调用与图片输入,自带 429 归因与宿主兼容加固。
AstrBot Antigravity ACP (astrbot_plugin_antigravity_acp)
通过 Google 官方 agy 客户端内置的 ACP(Agent Client Protocol)协议,把 Antigravity 模型安全、稳定地接入 AstrBot,作为日常对话主力。
💡 版本速递(v0.7.2,2026-11-17):修复 AstrBot 4.29.4 Safe Mode 第 4 条规则触发的上游伪 429(detail-free
RESOURCE_EXHAUSTED)——定点等义改写该句中的style/role-play,安全约束保持不变。详细改动见 CHANGELOG.md。
💡 为什么这份 README 分成了两部分?
现在大家装插件、查报错或者改代码,很多时候会直接把仓库丢给各种 AI 助手。但人类和 AI 读文档的需求完全是反过来的:
- 人类看文档:这插件干啥用的、好不好用、怎么最快装上并不踩坑。
- AI 看文档:协议契约、会话生命周期、参数规范和排障 SOP。
遇到疑难杂症时,直接把本 README 或仓库链接丢给你的 AI 助手,它读完下半部分就能帮你定位,然后烧你的token帮我修插件(目移)
📖 快速跳转:
👤 给人类看的说明
1. 为什么做这个插件?
折腾过反代、抓包提取 OAuth Token、或者接过野生号池的朋友应该都懂:账号风控是玄学,哪天睡醒号就没了。
做这个插件最大的初衷,就是因为被 Google 杀号杀怕了。为了稳稳用上官方模型,本插件坚持纯合规路线:
- 不碰逆向,不写黑科技:只调用本机官方
agy客户端,走标准 stdio 管道和 ACP 协议通信。 - 免 API Key,零中转:本地客户端自带鉴权,不需要搭建任何第三方 HTTP 反代服务,登录即用。
- 权限安全物理熔断:
agy原生拥有读写本地文件和执行终端命令的 Agent 权限。为了防止机器人在聊天中被提示词注入破坏系统,插件在启动时强制关闭了自带的所有本地文件与终端工具,外部工具调用完全交由 AstrBot 自身的权限体系托管。
📌 功能边界一览
| ✅ 支持的功能 (Do) | ❌ 坚决不做的事 (Don't) |
|---|---|
调用本机官方 agy 客户端,走标准 stdio 管道通信 |
不做号池切换与多号轮询(单实例仅绑定本机当前登录账号) |
把 AstrBot 的对话上下文、图片和工具调用桥接给 agy |
不做提示词破限与客户端伪造(仅为已知宿主兼容问题定点处理 system,不改 IDE 指纹) |
| 提供 WebUI 向导,辅助完成官方登录与模型选择 | 不提取或存储 OAuth Token(登录凭证全归官方客户端保管) |
| 独立的会话运行沙箱与进程清理机制 | 不开放未受控的本地终端与文件系统操作 |
2. 核心特性
- 官方通道直连:原生 stdio 管道通信,享受 Google 官方客户端的稳定连接与低风控保障(这不构成账号安全或上游可用性的绝对保证)。
- 双模能力支持:支持多模态识图(Vision)以及内置 MCP 桥接工具调用(Tool Use),可无缝调用 AstrBot 的各种技能插件。
- WebUI 运行监控:在 AstrBot 插件详情 →「首次设置」查看,按「概览 / 详细统计 / 高级诊断」分层展示会话池、近 24 小时用量与上下文缓存情况。纯本地轻量渲染,只读脱敏快照,不额外消耗模型额度。
- 智能防雪崩:具备 429 限流快速熔断、错误提前中断与疑似压缩后的上下文退役机制,避免异常重试浪费资源。
3. 快速上手(三步完成)
第一步:安装官方 agy 客户端
确保运行 AstrBot 的机器上已安装 Google 官方命令行工具 agy(必须与 AstrBot 运行在同一个系统用户下)。参考 Google 官方文档 安装完成后,在终端验证:
agy --version
agy acp --help
注:插件不会自动下载二进制文件。Windows 用户请确保使用的是原生
agy.exe,不支持.cmd或.bat包装脚本。
第二步:安装本插件
在 AstrBot WebUI 插件管理页上传 主分支 ZIP 包,或者直接在 AstrBot 根目录下克隆:
git clone --branch main https://github.com/sl251/astrbot_plugin_antigravity_acp.git data/plugins/astrbot_plugin_antigravity_acp
安装后重载或重启插件。
第三步:配置与启用(首次设置)
打开 AstrBot WebUI → 插件 → Antigravity ACP → 首次设置(也可以用管理员账号给机器人发送 /agy setup):
- 环境检测:页面会自动检测本机
agy是否就绪。 - 官方登录:点击「开始官方登录」,复制生成的授权链接到浏览器完成登录;需要手动提交时只粘贴浏览器给出的单行授权码(当前不解析完整 localhost 回调 URL),注意不要把授权码发到公开群聊里。
- 选择模型:拉取当前账号实际可用的模型列表,挑选所需模型并调节思考档位(
default/low/medium/high),点击 「保存并启用模型」。
之后想换模型,用 /agy use <provider_id>,或直接在 AstrBot 的提供商列表里切换。纯聊天建议在首次设置中选 chat 角色,避免工具 schema 额外占用上下文空间。
4. 避坑指南(FAQ)
国内网络连接超时:
若服务器直连 Google 不通,可以在插件配置中将proxy_mode设为custom,并在proxy_url填入本地代理地址(如http://127.0.0.1:7890)。该代理仅注入给agy子进程,不影响 AstrBot 里的其他国内模型。
(Docker 部署注意:容器内的127.0.0.1指向容器自身,请填写宿主机内网 IP 或host.docker.internal)工具调用(Tool Use)与识图(Vision)没反应?
本插件采用双重安全门禁,两处均需开启:- 先在 插件配置 中开启
enable_tools或enable_images,保存并重载插件; - 再去 AstrBot 的 模型 / 提供商配置 中,为对应模型勾选
tool_use或image能力。
从
v0.5.1起还可用custom_extra_body.agy_tools_mode(chat/tools/inherit)做聊天/工具分流:纯聊天用chat(不注入工具 schema),需要工具的会话用tools(仍受插件总闸enable_tools控制)。- 先在 插件配置 中开启
关于连通测试与额度:
插件「首次设置」里的环境检测、登录与拉取模型列表完全免费、不消耗模型额度;但 AstrBot 模型列表自带的「连通测试」会实际发送一条打招呼测试消息,消耗少量额度。另外,保存成功只代表协议握手通过,不等于实际对话一定可用。触发 429 限流问题:
0.7.1 起已自动过滤 AstrBot 4.29.4 与 4.30 已知的失实本地能力声明,但这不等于完整支持 4.30(当前支持>=4.29.4,<4.30)。若开启「使用电脑能力 → 本机环境」后仍出现 429,可暂在模型配置中改回「不允许任何环境」;这是针对该现象的临时对照,不是所有 429 的通用修复。
0.7.2 另对 #19 的 Safe Mode 第 4 条规则实施结构锚定的等义改写,保留安全约束(实机已验收:不再出现该伪 429);详见 CHANGELOG。只读诊断与统计指令:
/agy doctor:进行无损连通性与会话自检。/agy cost:查看各实例只读缓存复用、近 24 小时 Token 统计与进程池摘要(不发任何模型请求)。
5. 更新日志(最近版本)
(完整历史见 CHANGELOG.md)
- v0.7.2:定点兼容 AstrBot 4.29.4 Safe Mode 第 4 条规则触发的上游伪 429(
style/role-play等义改写,fail-open,不改冷却语义)。 - v0.7.1:429 结构化标签过滤扩展至 AstrBot 4.30 已知声明,新增内容相关 429 候选遥测(
content_429_candidate,不改冷却语义);WebUI 监控三层重构与纯 SVG 可视化。 - v0.6.1:MCP 权限分层、工具失败归因、数组 schema 宿主契约与本地能力声明过滤。
- v0.6.0:疑似压缩后终态退役、强错误提前中断、部分输出防重放、Windows 认证 MCP 桥与 Job Object。
🤖 给 Agent 看的上下文
先读 AGENTS.md。当前发布基线为 v0.7.2;仅支持 AstrBot >=4.29.4,<4.30、Python 3.11+。本节只保留当前有效契约,历史实现和既有验收见 CHANGELOG。
| 当前契约 | 详细说明与证据入口 |
|---|---|
模型请求只走官方 agy acp stdio;每会话隔离目录,认证由官方 CLI 管理,不读取或记录凭据内容 |
架构与认证,启动/登录排障 |
CLI 内置文件、终端、web search/browser 继续拒绝;只有当前活跃 prompt 中已观测且匹配的快照 MCP 调用可获唯一 allow_once,宿主审批/校验/预算仍有效 |
MCP 权限与 schema,#12 排障 |
| 模型 schema 适配与宿主原始契约独立;执行按原始 schema 校验,两者均参与工具指纹 | #13 参数排障 |
| 默认严格会话复用;已输出正文/思考或交接工具后失败禁止重试/fallback,避免重复副作用 | 会话与防重放 |
system 仅过滤已知宿主能力声明并定点兼容改写已知 Safe Mode 单句;4.30 文案处理不是 4.30 宿主兼容证明;content_429_candidate 是候选遥测,不是上游根因 |
过滤与 429 边界,#14 / #19 排障 |
| 检测/保存不等于真实生成;用量缺失保留未知;监控只读现有脱敏快照,不发模型请求 | 排障 SOP,实机验收分层 |
| 工具/图片默认关闭,要求插件与宿主双开关;不支持音频、视频、PDF 或图片生成 | 关键配置、配置 schema |
开发时按 测试与交付规范 记录通过/失败/跳过、环境与实机边界。定位错误直接用 故障 → 源码 → 测试索引,无需先读旧施工书。
致谢与协议
- 灵感来源:感谢 L 站大佬的
dsh-antigravity-acp插件提供的思路。 - 开源协议:详见
LICENSE与THIRD_PARTY_NOTICES.md。 - 免责声明:本插件仅作为本地官方
agy客户端与 AstrBot 之间的协议适配器,与 Google 官方无关。请遵守 Google Antigravity 官方服务条款使用。
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found