何时使用此技能

当用户提出以下请求时，请使用此技能：

• 从外部 API 获取数据
• 调用某个端点（endpoint）
• 在本地上下文之外获取或搜索信息
• 通过外部 API 生成图像、视频、语音、转录文本或音乐
• 从 URL 抓取/提取数据
• 为某项任务查找可用的 API（例如：“X 有可用的 API 吗？”）

若该任务需调用需付费的外部 API，请首先运行 agentspend search。

操作流程（默认工作流）

1. npx agentspend search ""
2. 与用户确认费用及限制条件（如 --max-cost、预算、域名白名单）
3. npx agentspend pay --method ... --header ... --body ... --max-cost ...

配置

npx agentspend configure

打开一个网页链接，用于添加信用卡并设置每周支出限额。凭证将保存至 ~/.agentspend/credentials.json。

若已配置完成，再次运行该命令将直接打开控制台以更新设置。

命令

pay

npx agentspend pay 

发起一次需付费的请求。AgentSpend 将自动处理支付流程。

选项：

• --method — HTTP 方法（默认为 GET）
• --body — 请求体（JSON 或纯文本格式）
• --header
  — 请求头，格式为 key:value（可重复使用）
• --max-cost — 可接受的最高扣费金额（单位：美元，支持最多 6 位小数）

返回内容：

• 端点返回的响应体
• 本次扣费金额及本周剩余预算

示例：

npx agentspend pay  
  --method POST 
  --header "key:value" 
  --body '{"key": "value"}' 
  --max-cost 0.05

check

npx agentspend check 

在不实际付费的前提下，查询端点的预估价格。

重要提示：

• check 命令所使用的请求结构，必须与后续计划执行的 pay 请求完全一致。
• 对于非 GET 类型的端点，务必显式指定 --method。
• 若端点需要请求头或请求体，请在 check 中使用相同的 --header 和 --body 参数。
• 若请求结构不匹配，端点可能返回 404/400 而非 402，导致无法提取价格信息。

示例：

npx agentspend check  
  --method POST 
  --header "content-type:application/json" 
  --body '{"key":"value"}'

返回内容：

• 价格（单位：美元）
• 描述信息（如提供）

search

npx agentspend search 

在服务目录中按服务名称和描述进行关键词检索，最多返回 5 个匹配的服务。

示例：

npx agentspend search "video generation"

status

npx agentspend status

显示账户支出概览。

返回内容：

• 每周预算额度
• 本周已支出金额
• 本周剩余预算
• 最近几笔扣费记录，含金额、域名及时间戳

configure

npx agentspend configure

启动初始化配置流程，或打开控制台以更新设置（包括每周预算、域名白名单、付款方式等）。

支出控制机制

• 每周预算 — 在 configure 阶段设定。任何会导致超支的请求将被拒绝。
• 单次请求最高费用限制 — 在 pay 命令中使用 --max-cost 参数，可拒绝高于指定阈值的请求。
• 域名白名单 — 通过控制台配置。对未列入白名单的域名发起的请求将被拒绝。

常见错误

• WEEKLY_BUDGET_EXCEEDED — 已达本周支出上限。运行 npx agentspend configure 可提升预算限额。
• DOMAIN_NOT_ALLOWLISTED — 目标域名未加入白名单。运行 npx agentspend configure 更新允许访问的域名列表。
• PRICE_EXCEEDS_MAX — 端点报价高于 --max-cost 设定值。请提高该参数值，或移除该参数。