用途:该技能让智能体在终端中用 curl 直接操作 Airtable REST API,无需 MCP 服务器、OAuth 流程或 Python SDK。
准备工作:在 https://airtable.com/create/tokens 创建个人访问令牌(PAT,以 pat 开头),至少授予 data.records:read、data.records:write、schema.bases:read 三项权限,并在同一界面把要访问的 base 加入令牌的 Access 列表——PAT 按 base 授权,令牌有效但 base 不在列表会返回 403。旧版 API key 已于 2024 年 2 月弃用,只能用 PAT 或 OAuth 令牌。令牌存于 ${HERMES_HOME:-~/.hermes}/.env 中的 AIRTABLE_API_KEY。
API 基础:端点 https://api.airtable.com/v0,认证头 Authorization: Bearer $AIRTABLE_API_KEY,请求体用 JSON。base/table/record/field 的 ID 前缀分别为 app、tbl、rec、fld,ID 不变而名称可变,自动化中优先用 ID。速率限制为每个 base 每秒 5 次请求,收到 429 需退避。调用时加 -s 保持输出干净,可用 python3 -m json.tool 美化输出。
主要能力:可列出令牌可见的 base、查看 base 的表与字段结构;支持读取、创建、更新(PATCH 合并字段,PUT 会整体替换)、删除记录;支持 filterByFormula 过滤(公式必须 URL 编码,可用 python3 的 urllib.parse.quote 处理)、排序、选取字段、使用命名视图;支持 performUpsert 按合并字段做幂等的新增或更新。批量写入与批量删除每次上限 10 条记录,超出需按 10 条分批并注意速率限制。列表接口每页最多 100 条,响应含 offset 时需循环取下一页。
字段写入:文本、数字、复选框、单选、多选、日期、日期时间、URL/邮箱/电话、附件、关联记录、用户等各有对应请求体格式;单选选项必须已存在,除非传入 typecast: true 自动创建。
限制与注意:破坏性操作无法通过 API 撤销,删除前应先回传过滤条件与记录数量确认;空字段会从响应中省略,字段不存在需以 schema 为准;PATCH 与 PUT 语义不同,默认用 PATCH;401/403 等错误应读取响应中的 errors 数组;分页 100 条为硬限制。