最近在整理自己常用的编程助手工作流时发现一个很常见的尴尬局面我一边用着 Codex 和 Claude Code 这类命令行编程助手一边又想把某个云端推理服务这里用 Antigravity 作代号具体是哪家的服务不重要重要的是方案可以平移到绝大多数带配额限制的云上能力的能力接进来让它变成助手可以随时调用的一个“外部技能”。直接裸调 API 不行写在提示词里又不可维护申请配额还要反复等人审批所以我花了点时间把它包装成了一个标准 Skill走通之后效果确实理想。这篇就完整复盘一下当时的封装思路和落地过程重点放在 Skill 的注册机制、服务接入方式、配额管理的正规做法以及我把这套方案实际放进命令行工具之后踩过的坑。适合正在搭个人编码工作流、或者想给公司内部模型服务做一个 CLI 入口的工程师参考。1. 先想清楚为什么要封装成外部 Skill而不是直接写死在提示词里1.1 编程助手的内置工具与外部工具边界在哪里Codex 和 Claude Code 这类工具本身已经带了不少有用的内置能力比如文件读写、执行命令、搜索代码库。但“调用一个不在它内置列表里的云端服务”这种事通常不在默认范围内。要么你得通过 MCP 挂一个服务端要么就得自己做一层封装。Antigravity 这类服务的调用方式很直接准备好请求参数发 HTTP 请求拿回结果。但编程助手在对话中并不能保证每次都能自己构造出正确的鉴权、超时、重试逻辑更麻烦的是如果让我把 API 参数和调用细节塞进 prompt那既不优雅也容易泄漏密钥。所以正确的做法是让助手只看到一个“命令”命令背后才是我写好的脚本脚本负责和 Antigravity 服务打交道。1.2 Skill 相比“把调用方式写进提示词”的最大优势我最早也试过在项目的系统提示词里写一大段“当需要调用 Antigravity 时请使用 curl 加以下参数……”实际操作下来问题很多。助手不一定每次都会遵守格式偶尔会把密钥带进调试输出甚至会在参数上自由发挥导致请求参数根本不符合服务端要求。而把它们封装成 Skill 之后代码逻辑是确定性的助手不再需要猜测“怎么调”它只需要根据描述判断“什么时候调”。Skill 的本质就是把原来要在大模型上下文里反复解释的工具使用协议变成一段注释良好的代码。可复用、可版本化、可测试这三点就足以说服我优先选择封装而不是继续在提示词层面打补丁。1.3 “外部调用 Skill”到底解决什么问题一句话概括它给编程助手装了一个“自定义抽屉”。抽屉里放什么工具、工具怎么操作、操作失败怎么反馈都由我自己控制。Antigravity 服务更新换代、接口换参数我只需要改脚本不需要来回调教助手。这和 MCP 的思路有相似之处但 Skill 更轻。MCP 需要额外维护一个服务进程而 Skill 通常一个目录、一个描述文件、一个可执行脚本就够了。对于那些“调用一次、拿结果就走”的轻量场景Skill 的成本明显更低。1.4 什么场景不适合用这种方式也得分情况。如果我对 Antigravity 的调用非常频繁响应数据量大且需要流式传输和复杂的会话状态管理那我还是建议走正式的 SDK 集成或者自定义 MCP 服务。Skill 适合的是“单个独立任务、一次请求一次结果”的中间态。封装方案没有银弹先判断使用姿势再决定架构形态比什么场景都套 Skill 更理智。2. Skill 在 Codex / Claude Code 里的注册机制和你需要遵守的调用约定2.1 先摸清两种工具的加载方式不同的编程助手对自定义 Skill 的加载方式略有差异但在设计上大家逐渐趋同了都是“目录 描述文件 可执行脚本”的组合。拿 Claude Code 来说比较常见的是在.claude/skills/skill-name/目录下放一个SKILL.md里面用 YAML frontmatter 写清楚技能名称和描述正文部分说明使用方式和注意事项。Codex 则更多依赖项目级的AGENTS.md或用户级自定义命令配置把外部工具注册成可以独立执行的命令脚本。这里我不准备把某个版本的所有字段都抄一遍因为工具迭代很快字段会变。我更想说明白它们共通的地方你给助手看的“说明书”要足够清晰让它知道这个技能是干什么的、什么时候该用、什么时候不该用、输入输出长什么样。2.2 一个最小编译的 SKILL.md 长什么样下面是我实际在项目里用过的简化版 SKILL.md结构上可以直接抄--- name: antigravity_call description: 调用 Antigravity 云端推理服务完成文本生成/分析任务。当用户明确要求使用 Antigravity、或者 Claude/Codex 需要借助外部云端模型能力时使用。 ---正文部分我会写这几件事调用方式执行antigravity_call.py传入一个 JSON 字符串包含prompt、temperature、max_tokens等字段。输出格式脚本返回一个 JSON 对象包含status、result、error三个字段。注意事项不要把密钥放进 prompt如果返回 429 或 503等待重试不要连续快速调用。使用示例给一个简单的对话样例让助手能快速理解“何时触发”。这个文件的核心不是代码而是减少歧义。助手不是真的“理解”你的业务逻辑它只是在做模式匹配你把边界写得越清楚它误用的概率就越低。2.3 可执行脚本的接口约定外部脚本本质上是一个黑盒子所以我给antigravity_call.py定义了非常明确的 stdin/stdout 契约输入从标准输入读取 JSON。输出把所有日志写到 stderr把最终结果写到 stdout且 stdout 只输出一行 JSON。这么做完全是为了配合编程助手的执行机制。它通常会把 stdout 当作主要反馈把 stderr 当作调试信息。如果我把日志和结果混在一起输出助手解析结果时会非常痛苦。2.4 让助手在合适的时机“发现”这个技能很多人的技能写好了但助手从来不用原因往往出在描述上。比如 description 写得太宽泛“一个调用 Antigravity 的工具”。助手确实能发现它但不知道什么时候该激活。我后来把描述改成“当用户提到需要 Antigravity 进行文本生成、内容摘要、代码解释或用户明确要求调用 Antigravity 模型时使用此技能。如果是简单的算术或即时回答不要使用。”改了之后调用准确率提升非常明显。原则就是描述要带触发条件也要带“不要使用”的边界。这和写函数注释是一个道理不能只写它能干嘛还要写它不能干嘛。3. Antigravity 服务接入认证、请求结构与错误处理3.1 身份凭证永远不要以明文方式出现在 Skill 目录里Antigravity 服务的认证方式通常是 API Key 或者服务账号令牌。我强烈建议不要把这个值硬编码在脚本里也不要写进 SKILL.md。我在antigravity_call.py里用的是环境变量读取方式import os token os.environ.get(ANTIGRAVITY_API_TOKEN) if not token: raise RuntimeError(缺少环境变量 ANTIGRAVITY_API_TOKEN)然后通过一个简单的包装函数来请求def call_antigravity(prompt, temperature0.2, max_tokens1024): headers { Authorization: fBearer {token}, Content-Type: application/json, } payload { prompt: prompt, temperature: temperature, max_tokens: max_tokens, } ...这样做的第一好处是安全第二好处是便于切换不同环境。开发环境、测试环境、生产环境用不同的 token只需要改环境变量不需要改代码。3.2 请求模型输入、输出、超时和大小控制对接 Antigravity 这类云端推理服务时有两个参数最容易踩坑超时时间和输出长度。我见过不少外部调用脚本不设超时结果网络抖动一次整个编程助手会话卡在那里十几秒严重影响交互体验。所以我给脚本加了两个硬性保护请求超时固定为 60 秒连接阶段 10 秒。max_tokens 上限默认 4096通过外部参数可调但超过上限就拒绝请求。这样做还有一个额外好处由于 max_tokens 有上限单次请求的计费不会出现“失控”的情况配合后面要讲的配额治理成本更可预测。3.3 错误语义限流、服务不可用、重试与退避云端服务不会永远稳定Antigravity 也可能返回 429请求过多、503服务暂不可用甚至 504网关超时。我在脚本里没有用粗暴的无限重试而是采用三次重试加指数退避import time import requests def request_with_retry(prompt, max_attempts3): for attempt in range(max_attempts): try: response call_antigravity(prompt) return response except requests.exceptions.HTTPError as exc: status_code exc.response.status_code if status_code in (429, 503, 504): time.sleep(2 ** attempt) # 1s, 2s, 4s continue raise RuntimeError(f无法处理的服务响应: {status_code}) raise RuntimeError(重试次数已耗尽请稍后重试)为什么退避间隔用 2 的指数因为大部分限流不是永久性的而是瞬间并发过高。如果所有重试都在同一秒内打过去等于没有重试。间隔拉长一点反而成功率更高同时也更尊重服务端的配额约束。3.4 输出里那些容易被忽略的细节Antigravity 这类服务的返回 JSON 通常会有多层嵌套比如data.choices[0].text。如果直接在脚本里取整段 JSON 抛给助手助手的上下文会被大量无用字段污染。我会在脚本里做一次清洗只保留真正需要的内容。我自己保留的字段是result_text、usagetoken 消耗、request_id。其中usage可以用于之后的配额监控request_id能在出问题时对齐服务端日志。这些表面上看起来多此一举真出问题的时候能帮你省下大把排查时间。4. 配额限制的正规解法预算、分级调用与官方提额4.1 先搞清楚限制到底卡在哪说回标题里那个绕不开的话题配额限制。Antigravity 服务的限制一般分成几层我整理成下面这个表格方便大家对照排查限制类型典型表现常见控制时机每分钟请求数RPM短时间高频调用触发 429脚本层限流与退避每分钟 Token 数TPM并发请求过多或单请求过长触发超限控制 max_tokens 与并发数每日调用量/成本上限日终或月底超支后服务被暂停用量监控与预算告警单次请求大小请求体过大被拒绝输入裁剪与分片很多人以为配额限制只有“每分钟几次”这一种其实真正的风险往往藏在 Token 消耗和每日成本上限里。编程助手这类场景最容易出现的问题是一个循环任务在不知不觉间发起上百次调用每分钟 RPM 没有超但当天总成本已经翻了好几倍。4.2 第一道防线用量控制而不是事后补救我的做法是把“控量”前置到 Skill 的设计里而不是等配额超了再写脚本去清理。具体有三条经验默认 temperature 设低一点减少无意义随机输出。对长文本先生成摘要只把摘要传给 Antigravity而不是丢整篇原文。对可重复计算的任务做本地结果缓存以prompt model temperature为 key 缓存返回结果。缓存这招非常实用。很多调用场景是重复的比如同一个代码解释问题被问了两次可能只是在对话里换了问法但核心内容一样。加了本地缓存之后不仅省配额响应速度还更快。4.3 分级调用把不紧急的请求送进排队通道我在外部 Skill 脚本里设计了一个简单的分级机制默认走同步调用但如果判断当前任务不紧急比如批处理任务、定时摘要可以传一个prioritylow参数脚本会把任务写进本地队列由另一个常驻进程按每分钟固定频率消费。这套设计对配额管理特别有效。因为配额限的是速率你没办法让瞬时突发变得合法但你可以把突发请求拉长到时间轴上让它们均匀地消费配额。如果后台任务和交互任务共享同一个 Skill不排队的结果就是交互触发 429后台任务也受阻两边都体验很差。4.4 官方配额提升路径才是真正要走的正路再次强调我不主张任何“绕过配额”的方式合规做法永远只有一个就是找服务方申请提升配额。Antigravity 服务对应的控制台里一般都会有配额管理页面能申请提高 RPM、TPM 或者日调用量。在提交提额申请之前我通常会准备三样东西当前配额的使用率截图和近 7 天趋势证明业务确有增长。预估的峰值需求和持续时间说明自己不是短时脚本在刷量。应用场景描述例如“用于提升研发人员编码效率”让审批方理解价值。按正常流程去申请一般比你预想的更快。反而是在那里想各种偏门办法折腾既不稳定还可能把整个项目账号拉黑。4.5 监控和告警别等成本账单出来才后悔我在调用脚本里加了一个usage字段透传机制同时每完成一次调用会追加一行结构化日志到本地文件。然后用一个 crontab 任务每天统计总调用次数总 Token 消耗平均响应延迟429/503 错误比例超过设定阈值时发个告警哪怕只是往群里推一条消息也比月初看到账单震惊要强得多。很多人的配额问题根本不是单次配置有问题而是缺少用量感知等到触发限制时已经来不及优化了。5. 端到端实操把 Skill 装进命令行编程助手跑通第一个调用5.1 准备目录与凭证我的项目结构如下my-assistant-project/ ├── .claude/ │ └── skills/ │ └── antigravity_call/ │ ├── SKILL.md │ └── scripts/ │ └── antigravity_call.py ├── .env └── AGENTS.md.env文件里放着ANTIGRAVITY_API_TOKEN启动编程助手前用source .env加载。如果是 Codex 场景我再把相同的调用逻辑注册为自定义命令实际执行文件还是同一个antigravity_call.py避免维护两套脚本。5.2 编写调用脚本Python 示例核心脚本我概括一下关键步骤#!/usr/bin/env python3 # -*- coding: utf-8 -*- import json, os, sys, syslog import requests def main(): raw sys.stdin.read() try: params json.loads(raw) except json.JSONDecodeError: print(json.dumps({status: error, error: 输入不是合法 JSON})) sys.exit(1) prompt params.get(prompt, ) temperature float(params.get(temperature, 0.2)) max_tokens int(params.get(max_tokens, 1024)) token os.environ.get(ANTIGRAVITY_API_TOKEN) if not token: print(json.dumps({status: error, error: 缺少环境变量 ANTIGRAVITY_API_TOKEN})) sys.exit(1) try: result request_with_retry(prompt, temperature, max_tokens, token) print(json.dumps({status: ok, result: result[text], usage: result[usage]})) except Exception as exc: print(json.dumps({status: error, error: str(exc)})) sys.exit(2) if __name__ __main__: main()这里要注意几点所有日志输出到stderrstdout只输出最终 JSON错误退出码至少区分 1输入错误和 2服务错误这样编程助手能根据退出码判断是做格式修正还是直接等待重试。5.3 写一份让助手能精确触发的 SKILL.md我最终落地的版本大致是这样的--- name: antigravity_call description: 调用 Antigravity 云端推理服务用于文本生成、代码生成、摘要总结等任务。当用户提到 Antigravity、云端模型、外部大模型或需要额外推理能力时使用。不要在简单问答或本地可处理任务中使用。 ---正文里我还会附一段“何时不要使用”的描述比如如果只是问时间、算加减法、查本地文件直接回答就行不要调用 Antigravity。别小看这一句它能拦下相当一部分无意义的配额消耗。5.4 第一次调用与结果校验写完之后先在终端手动测一次echo {prompt: 用三句话解释什么是装饰器, temperature: 0.3} | python3 .claude/skills/antigravity_call/scripts/antigravity_call.py看到正常的 JSON 返回后再打开编程助手在对话里说“帮我用 Antigravity 解释一下这段代码”。观察助手是否自动调起了 Skill。如果没有我会优先检查描述文件里的名称和触发词是否匹配而不是去改脚本。5.5 关于提示词风格的兼容建议部分编程助手会要求 Skill 的说明文档尽量简洁不能像给人类看的文档那样长篇大论。我在实践中发现描述字段控制在 2 到 4 句话正文不超过 30 行触发准确率最高。写多了反而会干扰模型的判断它更容易在低相关场景下误触发。6. 实测中的坑与处理思路6.1 超时设置不当整个会话都卡住第一次调试时我没有给 HTTP 请求单独设置连接超时结果服务端网络抖动脚本一直等到默认超时时间编程助手界面卡了将近一分钟。后来我把超时拆成两段连接阶段 10 秒读取阶段 60 秒。这样最坏情况最多等 70 秒但日常基本几十秒内必有反馈。6.2 stdout 里的杂音真的会毁掉结果一开始我在打印最终结果前加了一行print(正在获取结果...)结果编程助手把这段提示当作主要输出导致后续 JSON 解析失败。排查之后才明白这类外部脚本的 stdout 是“程序协议面”不能混入任何人类阅读用的废话。日志全部走 stderr这个教训后来被我写进了所有 Skill 模板里。6.3 技能冲突多个 Skill 同时命中当项目里的 Skill 数量变多之后可能会出现两个技能同时命中同一个请求的情况。比如一个叫general_llm_call一个叫antigravity_call描述里都写了“云端模型调用”。解决方法是调整描述让每个技能拥有明确的使用前提。我后来给antigravity_call增加了品牌/代号限定只在上下文出现 Antigravity 相关词汇时才触发。6.4 密钥泄露风险事故往往发生在调试日志里有一次我在调试时把完整请求头和响应体打到了 stderr 里差点把 token 带进对话历史。从那之后我在日志输出前强制做了一次脱敏处理把Authorization头里的内容替换成***再输出。这也提醒了我Skill 目录本身要加入.gitignore或者至少保证不包含任何真实密钥文件。6.5 响应体过大直接把上下文挤爆Antigravity 返回的结果如果很长全部塞给编程助手会让上下文窗口迅速膨胀。我在脚本里加了后处理逻辑如果result_text超过 2000 个字符就自动截断并附上一句“结果已截断可继续追问细节”的提示。这样既保留关键信息又不会把上下文撑爆。7. 把 Skill 推广到更多服务前先对照这份检查清单我封装完 Antigravity 之后很快就有了第二个、第三个服务需要接入于是把经验整理成了一份检查清单在这里分享给你是否已经用环境变量管理所有密钥而不是硬编码脚本是否严格区分 stdout 和 stderr是否设置了连接超时和总超时是否处理了 429、503、504 这类临时错误并做退避重试是否对输出做了长度截断和字符清洗是否在 SKILL.md 里明确写了“何时不应该使用”是否有用量日志能否统计出每天消耗了多少配额是否在项目仓库里忽略了含密钥的文件这些检查项看起来都很基础但每个背后都对应一次真实故障。我的个人体会是外部 Skill 的代码量不大难点从来不在“怎么调 API”而在“如何让另一个智能体和你这个脚本之间形成稳定、可预期的协作关系”。这套东西目前已经稳定跑了几个月的日常开发单日配额用量基本平稳再也没有出现把成本账单跑爆或者服务端拒绝响应的情况。如果你也在折腾类似的外部调用封装建议先从最小的 SKILL.md 加脚本开始跑通了再加缓存、队列和监控别一上来就追求大而全的架构。小步快走遇到问题再逐步加固这种模式在命令行工具集成这种场景里最靠谱。
最近在整理自己常用的编程助手工作流时发现一个很常见的尴尬局面我一边用着 Codex 和 Claude Code 这类命令行编程助手一边又想把某个云端推理服务这里用 Antigravity 作代号具体是哪家的服务不重要重要的是方案可以平移到绝大多数带配额限制的云上能力的能力接进来让它变成助手可以随时调用的一个“外部技能”。直接裸调 API 不行写在提示词里又不可维护申请配额还要反复等人审批所以我花了点时间把它包装成了一个标准 Skill走通之后效果确实理想。这篇就完整复盘一下当时的封装思路和落地过程重点放在 Skill 的注册机制、服务接入方式、配额管理的正规做法以及我把这套方案实际放进命令行工具之后踩过的坑。适合正在搭个人编码工作流、或者想给公司内部模型服务做一个 CLI 入口的工程师参考。1. 先想清楚为什么要封装成外部 Skill而不是直接写死在提示词里1.1 编程助手的内置工具与外部工具边界在哪里Codex 和 Claude Code 这类工具本身已经带了不少有用的内置能力比如文件读写、执行命令、搜索代码库。但“调用一个不在它内置列表里的云端服务”这种事通常不在默认范围内。要么你得通过 MCP 挂一个服务端要么就得自己做一层封装。Antigravity 这类服务的调用方式很直接准备好请求参数发 HTTP 请求拿回结果。但编程助手在对话中并不能保证每次都能自己构造出正确的鉴权、超时、重试逻辑更麻烦的是如果让我把 API 参数和调用细节塞进 prompt那既不优雅也容易泄漏密钥。所以正确的做法是让助手只看到一个“命令”命令背后才是我写好的脚本脚本负责和 Antigravity 服务打交道。1.2 Skill 相比“把调用方式写进提示词”的最大优势我最早也试过在项目的系统提示词里写一大段“当需要调用 Antigravity 时请使用 curl 加以下参数……”实际操作下来问题很多。助手不一定每次都会遵守格式偶尔会把密钥带进调试输出甚至会在参数上自由发挥导致请求参数根本不符合服务端要求。而把它们封装成 Skill 之后代码逻辑是确定性的助手不再需要猜测“怎么调”它只需要根据描述判断“什么时候调”。Skill 的本质就是把原来要在大模型上下文里反复解释的工具使用协议变成一段注释良好的代码。可复用、可版本化、可测试这三点就足以说服我优先选择封装而不是继续在提示词层面打补丁。1.3 “外部调用 Skill”到底解决什么问题一句话概括它给编程助手装了一个“自定义抽屉”。抽屉里放什么工具、工具怎么操作、操作失败怎么反馈都由我自己控制。Antigravity 服务更新换代、接口换参数我只需要改脚本不需要来回调教助手。这和 MCP 的思路有相似之处但 Skill 更轻。MCP 需要额外维护一个服务进程而 Skill 通常一个目录、一个描述文件、一个可执行脚本就够了。对于那些“调用一次、拿结果就走”的轻量场景Skill 的成本明显更低。1.4 什么场景不适合用这种方式也得分情况。如果我对 Antigravity 的调用非常频繁响应数据量大且需要流式传输和复杂的会话状态管理那我还是建议走正式的 SDK 集成或者自定义 MCP 服务。Skill 适合的是“单个独立任务、一次请求一次结果”的中间态。封装方案没有银弹先判断使用姿势再决定架构形态比什么场景都套 Skill 更理智。2. Skill 在 Codex / Claude Code 里的注册机制和你需要遵守的调用约定2.1 先摸清两种工具的加载方式不同的编程助手对自定义 Skill 的加载方式略有差异但在设计上大家逐渐趋同了都是“目录 描述文件 可执行脚本”的组合。拿 Claude Code 来说比较常见的是在.claude/skills/skill-name/目录下放一个SKILL.md里面用 YAML frontmatter 写清楚技能名称和描述正文部分说明使用方式和注意事项。Codex 则更多依赖项目级的AGENTS.md或用户级自定义命令配置把外部工具注册成可以独立执行的命令脚本。这里我不准备把某个版本的所有字段都抄一遍因为工具迭代很快字段会变。我更想说明白它们共通的地方你给助手看的“说明书”要足够清晰让它知道这个技能是干什么的、什么时候该用、什么时候不该用、输入输出长什么样。2.2 一个最小编译的 SKILL.md 长什么样下面是我实际在项目里用过的简化版 SKILL.md结构上可以直接抄--- name: antigravity_call description: 调用 Antigravity 云端推理服务完成文本生成/分析任务。当用户明确要求使用 Antigravity、或者 Claude/Codex 需要借助外部云端模型能力时使用。 ---正文部分我会写这几件事调用方式执行antigravity_call.py传入一个 JSON 字符串包含prompt、temperature、max_tokens等字段。输出格式脚本返回一个 JSON 对象包含status、result、error三个字段。注意事项不要把密钥放进 prompt如果返回 429 或 503等待重试不要连续快速调用。使用示例给一个简单的对话样例让助手能快速理解“何时触发”。这个文件的核心不是代码而是减少歧义。助手不是真的“理解”你的业务逻辑它只是在做模式匹配你把边界写得越清楚它误用的概率就越低。2.3 可执行脚本的接口约定外部脚本本质上是一个黑盒子所以我给antigravity_call.py定义了非常明确的 stdin/stdout 契约输入从标准输入读取 JSON。输出把所有日志写到 stderr把最终结果写到 stdout且 stdout 只输出一行 JSON。这么做完全是为了配合编程助手的执行机制。它通常会把 stdout 当作主要反馈把 stderr 当作调试信息。如果我把日志和结果混在一起输出助手解析结果时会非常痛苦。2.4 让助手在合适的时机“发现”这个技能很多人的技能写好了但助手从来不用原因往往出在描述上。比如 description 写得太宽泛“一个调用 Antigravity 的工具”。助手确实能发现它但不知道什么时候该激活。我后来把描述改成“当用户提到需要 Antigravity 进行文本生成、内容摘要、代码解释或用户明确要求调用 Antigravity 模型时使用此技能。如果是简单的算术或即时回答不要使用。”改了之后调用准确率提升非常明显。原则就是描述要带触发条件也要带“不要使用”的边界。这和写函数注释是一个道理不能只写它能干嘛还要写它不能干嘛。3. Antigravity 服务接入认证、请求结构与错误处理3.1 身份凭证永远不要以明文方式出现在 Skill 目录里Antigravity 服务的认证方式通常是 API Key 或者服务账号令牌。我强烈建议不要把这个值硬编码在脚本里也不要写进 SKILL.md。我在antigravity_call.py里用的是环境变量读取方式import os token os.environ.get(ANTIGRAVITY_API_TOKEN) if not token: raise RuntimeError(缺少环境变量 ANTIGRAVITY_API_TOKEN)然后通过一个简单的包装函数来请求def call_antigravity(prompt, temperature0.2, max_tokens1024): headers { Authorization: fBearer {token}, Content-Type: application/json, } payload { prompt: prompt, temperature: temperature, max_tokens: max_tokens, } ...这样做的第一好处是安全第二好处是便于切换不同环境。开发环境、测试环境、生产环境用不同的 token只需要改环境变量不需要改代码。3.2 请求模型输入、输出、超时和大小控制对接 Antigravity 这类云端推理服务时有两个参数最容易踩坑超时时间和输出长度。我见过不少外部调用脚本不设超时结果网络抖动一次整个编程助手会话卡在那里十几秒严重影响交互体验。所以我给脚本加了两个硬性保护请求超时固定为 60 秒连接阶段 10 秒。max_tokens 上限默认 4096通过外部参数可调但超过上限就拒绝请求。这样做还有一个额外好处由于 max_tokens 有上限单次请求的计费不会出现“失控”的情况配合后面要讲的配额治理成本更可预测。3.3 错误语义限流、服务不可用、重试与退避云端服务不会永远稳定Antigravity 也可能返回 429请求过多、503服务暂不可用甚至 504网关超时。我在脚本里没有用粗暴的无限重试而是采用三次重试加指数退避import time import requests def request_with_retry(prompt, max_attempts3): for attempt in range(max_attempts): try: response call_antigravity(prompt) return response except requests.exceptions.HTTPError as exc: status_code exc.response.status_code if status_code in (429, 503, 504): time.sleep(2 ** attempt) # 1s, 2s, 4s continue raise RuntimeError(f无法处理的服务响应: {status_code}) raise RuntimeError(重试次数已耗尽请稍后重试)为什么退避间隔用 2 的指数因为大部分限流不是永久性的而是瞬间并发过高。如果所有重试都在同一秒内打过去等于没有重试。间隔拉长一点反而成功率更高同时也更尊重服务端的配额约束。3.4 输出里那些容易被忽略的细节Antigravity 这类服务的返回 JSON 通常会有多层嵌套比如data.choices[0].text。如果直接在脚本里取整段 JSON 抛给助手助手的上下文会被大量无用字段污染。我会在脚本里做一次清洗只保留真正需要的内容。我自己保留的字段是result_text、usagetoken 消耗、request_id。其中usage可以用于之后的配额监控request_id能在出问题时对齐服务端日志。这些表面上看起来多此一举真出问题的时候能帮你省下大把排查时间。4. 配额限制的正规解法预算、分级调用与官方提额4.1 先搞清楚限制到底卡在哪说回标题里那个绕不开的话题配额限制。Antigravity 服务的限制一般分成几层我整理成下面这个表格方便大家对照排查限制类型典型表现常见控制时机每分钟请求数RPM短时间高频调用触发 429脚本层限流与退避每分钟 Token 数TPM并发请求过多或单请求过长触发超限控制 max_tokens 与并发数每日调用量/成本上限日终或月底超支后服务被暂停用量监控与预算告警单次请求大小请求体过大被拒绝输入裁剪与分片很多人以为配额限制只有“每分钟几次”这一种其实真正的风险往往藏在 Token 消耗和每日成本上限里。编程助手这类场景最容易出现的问题是一个循环任务在不知不觉间发起上百次调用每分钟 RPM 没有超但当天总成本已经翻了好几倍。4.2 第一道防线用量控制而不是事后补救我的做法是把“控量”前置到 Skill 的设计里而不是等配额超了再写脚本去清理。具体有三条经验默认 temperature 设低一点减少无意义随机输出。对长文本先生成摘要只把摘要传给 Antigravity而不是丢整篇原文。对可重复计算的任务做本地结果缓存以prompt model temperature为 key 缓存返回结果。缓存这招非常实用。很多调用场景是重复的比如同一个代码解释问题被问了两次可能只是在对话里换了问法但核心内容一样。加了本地缓存之后不仅省配额响应速度还更快。4.3 分级调用把不紧急的请求送进排队通道我在外部 Skill 脚本里设计了一个简单的分级机制默认走同步调用但如果判断当前任务不紧急比如批处理任务、定时摘要可以传一个prioritylow参数脚本会把任务写进本地队列由另一个常驻进程按每分钟固定频率消费。这套设计对配额管理特别有效。因为配额限的是速率你没办法让瞬时突发变得合法但你可以把突发请求拉长到时间轴上让它们均匀地消费配额。如果后台任务和交互任务共享同一个 Skill不排队的结果就是交互触发 429后台任务也受阻两边都体验很差。4.4 官方配额提升路径才是真正要走的正路再次强调我不主张任何“绕过配额”的方式合规做法永远只有一个就是找服务方申请提升配额。Antigravity 服务对应的控制台里一般都会有配额管理页面能申请提高 RPM、TPM 或者日调用量。在提交提额申请之前我通常会准备三样东西当前配额的使用率截图和近 7 天趋势证明业务确有增长。预估的峰值需求和持续时间说明自己不是短时脚本在刷量。应用场景描述例如“用于提升研发人员编码效率”让审批方理解价值。按正常流程去申请一般比你预想的更快。反而是在那里想各种偏门办法折腾既不稳定还可能把整个项目账号拉黑。4.5 监控和告警别等成本账单出来才后悔我在调用脚本里加了一个usage字段透传机制同时每完成一次调用会追加一行结构化日志到本地文件。然后用一个 crontab 任务每天统计总调用次数总 Token 消耗平均响应延迟429/503 错误比例超过设定阈值时发个告警哪怕只是往群里推一条消息也比月初看到账单震惊要强得多。很多人的配额问题根本不是单次配置有问题而是缺少用量感知等到触发限制时已经来不及优化了。5. 端到端实操把 Skill 装进命令行编程助手跑通第一个调用5.1 准备目录与凭证我的项目结构如下my-assistant-project/ ├── .claude/ │ └── skills/ │ └── antigravity_call/ │ ├── SKILL.md │ └── scripts/ │ └── antigravity_call.py ├── .env └── AGENTS.md.env文件里放着ANTIGRAVITY_API_TOKEN启动编程助手前用source .env加载。如果是 Codex 场景我再把相同的调用逻辑注册为自定义命令实际执行文件还是同一个antigravity_call.py避免维护两套脚本。5.2 编写调用脚本Python 示例核心脚本我概括一下关键步骤#!/usr/bin/env python3 # -*- coding: utf-8 -*- import json, os, sys, syslog import requests def main(): raw sys.stdin.read() try: params json.loads(raw) except json.JSONDecodeError: print(json.dumps({status: error, error: 输入不是合法 JSON})) sys.exit(1) prompt params.get(prompt, ) temperature float(params.get(temperature, 0.2)) max_tokens int(params.get(max_tokens, 1024)) token os.environ.get(ANTIGRAVITY_API_TOKEN) if not token: print(json.dumps({status: error, error: 缺少环境变量 ANTIGRAVITY_API_TOKEN})) sys.exit(1) try: result request_with_retry(prompt, temperature, max_tokens, token) print(json.dumps({status: ok, result: result[text], usage: result[usage]})) except Exception as exc: print(json.dumps({status: error, error: str(exc)})) sys.exit(2) if __name__ __main__: main()这里要注意几点所有日志输出到stderrstdout只输出最终 JSON错误退出码至少区分 1输入错误和 2服务错误这样编程助手能根据退出码判断是做格式修正还是直接等待重试。5.3 写一份让助手能精确触发的 SKILL.md我最终落地的版本大致是这样的--- name: antigravity_call description: 调用 Antigravity 云端推理服务用于文本生成、代码生成、摘要总结等任务。当用户提到 Antigravity、云端模型、外部大模型或需要额外推理能力时使用。不要在简单问答或本地可处理任务中使用。 ---正文里我还会附一段“何时不要使用”的描述比如如果只是问时间、算加减法、查本地文件直接回答就行不要调用 Antigravity。别小看这一句它能拦下相当一部分无意义的配额消耗。5.4 第一次调用与结果校验写完之后先在终端手动测一次echo {prompt: 用三句话解释什么是装饰器, temperature: 0.3} | python3 .claude/skills/antigravity_call/scripts/antigravity_call.py看到正常的 JSON 返回后再打开编程助手在对话里说“帮我用 Antigravity 解释一下这段代码”。观察助手是否自动调起了 Skill。如果没有我会优先检查描述文件里的名称和触发词是否匹配而不是去改脚本。5.5 关于提示词风格的兼容建议部分编程助手会要求 Skill 的说明文档尽量简洁不能像给人类看的文档那样长篇大论。我在实践中发现描述字段控制在 2 到 4 句话正文不超过 30 行触发准确率最高。写多了反而会干扰模型的判断它更容易在低相关场景下误触发。6. 实测中的坑与处理思路6.1 超时设置不当整个会话都卡住第一次调试时我没有给 HTTP 请求单独设置连接超时结果服务端网络抖动脚本一直等到默认超时时间编程助手界面卡了将近一分钟。后来我把超时拆成两段连接阶段 10 秒读取阶段 60 秒。这样最坏情况最多等 70 秒但日常基本几十秒内必有反馈。6.2 stdout 里的杂音真的会毁掉结果一开始我在打印最终结果前加了一行print(正在获取结果...)结果编程助手把这段提示当作主要输出导致后续 JSON 解析失败。排查之后才明白这类外部脚本的 stdout 是“程序协议面”不能混入任何人类阅读用的废话。日志全部走 stderr这个教训后来被我写进了所有 Skill 模板里。6.3 技能冲突多个 Skill 同时命中当项目里的 Skill 数量变多之后可能会出现两个技能同时命中同一个请求的情况。比如一个叫general_llm_call一个叫antigravity_call描述里都写了“云端模型调用”。解决方法是调整描述让每个技能拥有明确的使用前提。我后来给antigravity_call增加了品牌/代号限定只在上下文出现 Antigravity 相关词汇时才触发。6.4 密钥泄露风险事故往往发生在调试日志里有一次我在调试时把完整请求头和响应体打到了 stderr 里差点把 token 带进对话历史。从那之后我在日志输出前强制做了一次脱敏处理把Authorization头里的内容替换成***再输出。这也提醒了我Skill 目录本身要加入.gitignore或者至少保证不包含任何真实密钥文件。6.5 响应体过大直接把上下文挤爆Antigravity 返回的结果如果很长全部塞给编程助手会让上下文窗口迅速膨胀。我在脚本里加了后处理逻辑如果result_text超过 2000 个字符就自动截断并附上一句“结果已截断可继续追问细节”的提示。这样既保留关键信息又不会把上下文撑爆。7. 把 Skill 推广到更多服务前先对照这份检查清单我封装完 Antigravity 之后很快就有了第二个、第三个服务需要接入于是把经验整理成了一份检查清单在这里分享给你是否已经用环境变量管理所有密钥而不是硬编码脚本是否严格区分 stdout 和 stderr是否设置了连接超时和总超时是否处理了 429、503、504 这类临时错误并做退避重试是否对输出做了长度截断和字符清洗是否在 SKILL.md 里明确写了“何时不应该使用”是否有用量日志能否统计出每天消耗了多少配额是否在项目仓库里忽略了含密钥的文件这些检查项看起来都很基础但每个背后都对应一次真实故障。我的个人体会是外部 Skill 的代码量不大难点从来不在“怎么调 API”而在“如何让另一个智能体和你这个脚本之间形成稳定、可预期的协作关系”。这套东西目前已经稳定跑了几个月的日常开发单日配额用量基本平稳再也没有出现把成本账单跑爆或者服务端拒绝响应的情况。如果你也在折腾类似的外部调用封装建议先从最小的 SKILL.md 加脚本开始跑通了再加缓存、队列和监控别一上来就追求大而全的架构。小步快走遇到问题再逐步加固这种模式在命令行工具集成这种场景里最靠谱。
