Airtable

通过 curl 使用 Airtable REST API。支持记录的 CRUD、过滤和 upsert（更新或插入）。

技能元数据


来源	Bundled（默认安装）
路径	`skills/productivity/airtable`
版本	`1.1.0`
作者	community
许可证	MIT
平台	linux, macos, windows
标签	`Airtable`, `Productivity`, `Database`, `API`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Airtable — Base、表与记录

通过 terminal 工具直接使用 curl 操作 Airtable 的 REST API。无需 MCP 服务器，无需 OAuth 流程，无需 Python SDK — 只需 curl 和个人访问令牌。

前提条件

在 https://airtable.com/create/tokens 创建个人访问令牌 (PAT)（令牌以 pat... 开头）。
授予以下作用域（最低要求）：
- data.records:read — 读取行
- data.records:write — 创建/更新/删除行
- schema.bases:read — 列出 base 和表
重要： 在同一令牌界面中，将每个要访问的 base 添加到令牌的访问 (Access) 列表中。PAT 是按 base 限定作用域的 — 在错误的 base 上使用有效令牌将返回 403。
将令牌存储在 ~/.hermes/.env 中（或通过 hermes setup）：

   AIRTABLE_API_KEY=pat_your_token_here

注意：旧版 key... API 密钥已于 2024 年 2 月弃用。现在仅支持 PAT 和 OAuth 令牌。

API 基础

端点： https://api.airtable.com/v0
认证头： Authorization: Bearer $AIRTABLE_API_KEY
所有请求均使用 JSON（任何 POST/PATCH/PUT 正文的 Content-Type: application/json）。
对象 ID： base 为 app...，表为 tbl...，记录为 rec...，字段为 fld...。ID 永不更改；名称可能会变。在自动化中优先使用 ID。
速率限制： 每个 base 每秒 5 个请求。遇到 429 时需退避。单个 base 上的突发请求将被限流。

基本 curl 模式：

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

-s 抑制 curl 的进度条 — 每次调用都保持设置此项，以便工具输出对 Hermes 保持干净。通过 python3 -m json.tool（始终存在）或 jq（如果已安装）管道传输以获得可读的 JSON。

字段类型（请求正文形状）

字段类型	写入形状
单行文本	`"Name": "hello"`
长文本	`"Notes": "multi\nline"`
数字	`"Score": 42`
复选框	`"Done": true`
单选	`"Status": "Todo"`（除非 `typecast: true`，否则名称必须已存在）
多选	`"Tags": ["urgent", "bug"]`
日期	`"Due": "2026-04-01"`
日期时间 (UTC)	`"At": "2026-04-01T14:30:00.000Z"`
URL / 电子邮件 / 电话	`"Link": "https://…"`
附件	`"Files": [{"url": "https://…"}]`（Airtable 获取并重新托管）
关联记录	`"Owner": ["recXXXXXXXXXXXXXX"]`（记录 ID 数组）
用户	`"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}`

在创建/更新正文的顶层传递 "typecast": true，以让 Airtable 自动强制转换值（例如，动态创建新的选项值，将 "42" 转换为 42）。

常见查询

列出令牌可见的 base

curl -s "https://api.airtable.com/v0/meta/bases" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

列出 base 的表 + 架构

curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

在修改之前使用此命令 — 确认确切的字段名称和 ID，显示单选字段的 options.choices，并显示主字段名称。

列出记录（前 10 条）

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

获取单条记录

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

过滤记录 (filterByFormula)

Airtable 公式必须进行 URL 编码。让 Python 标准库处理 — 切勿手动编码：

FORMULA="{Status}='Todo'"
ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

有用的公式模式：

精确匹配：{Email}='user@example.com'
包含：FIND('bug', LOWER({Title}))
多条件：AND({Status}='Todo', {Priority}='High')
或：OR({Owner}='alice', {Owner}='bob')
非空：NOT({Assignee}='')
日期比较：IS_AFTER({Due}, TODAY())

排序 + 选择特定字段

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

查询参数中的方括号必须进行 URL 编码（%5B / %5D）。

使用命名视图

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

视图在服务器端应用其保存的过滤器 + 排序。

常见变更操作

创建记录

curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool

在一次调用中创建最多 10 条记录

curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typecast": true,
    "records": [
      {"fields": {"Name": "Task A", "Status": "Todo"}},
      {"fields": {"Name": "Task B", "Status": "In progress"}}
    ]
  }' | python3 -m json.tool

批量端点限制为每个请求最多 10 条记录。对于更大的插入操作，请以 10 条为一批循环，并短暂休眠以遵守每个 base 每秒 5 个请求的限制。

更新记录（PATCH — 合并，保留未更改的字段）

curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool

通过合并字段 Upsert（无需 ID）

curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "performUpsert": {"fieldsToMergeOn": ["Email"]},
    "records": [
      {"fields": {"Email": "user@example.com", "Status": "Active"}}
    ]
  }' | python3 -m json.tool

performUpsert 创建合并字段值为新的记录，修补合并字段值已存在的记录。非常适合幂等同步。

删除记录

curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

在一次调用中删除最多 10 条记录

curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

分页

列表端点每页最多返回 100 条记录。如果响应包含 "offset": "..."，请在下一次调用中传回它。循环直到该字段不存在：

OFFSET=""
while :; do
  URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"
  [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"
  RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")
  echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'
  OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')
  [ -z "$OFFSET" ] && break
done

典型 Hermes 工作流

确认身份验证。 curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY" — 预期返回 200。
查找 Base。 列出 bases（上一步）或者如果令牌缺少 schema.bases:read 权限，则直接向用户询问 app... ID。
检查架构。 GET /v0/meta/bases/$BASE_ID/tables — 在进行任何变更操作之前，先在本地会话中缓存确切的字段名称和主字段名称。
先读后写。 对于“更新满足条件 Y 的 X”，首先使用 filterByFormula 解析出 rec... ID，然后执行 PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID。切勿猜测记录 ID。
批量写入。 将相关的创建操作合并为一个包含 10 条记录的 POST 请求，以保持在每秒 5 次请求的限制预算内。
破坏性操作。 删除操作无法通过 API 撤销。如果用户说“删除所有 X”，请回显过滤器 + 记录数量并在执行前确认。

常见陷阱

filterByFormula 必须进行 URL 编码。 包含空格或非 ASCII 字符的字段名也需要编码（{My Field} → %7BMy%20Field%7D）。使用 Python 标准库（上述模式）— 切勿手动转义。
空字段在响应中被省略。 缺少 "Assignee" 键并不意味着该字段不存在 — 它意味着此记录中的值为空。在得出字段缺失的结论之前，请检查架构（步骤 3）。
PATCH 与 PUT。 PATCH 将提供的字段合并到记录中。PUT 完全替换记录并清除任何未包含的字段。默认使用 PATCH。
单选选项必须存在。 当 Shipping 不在字段的选项列表中时，写入 "Status": "Shipping" 会报错 INVALID_MULTIPLE_CHOICE_OPTIONS，除非你传递 "typecast": true（这将自动创建该选项）。
每个 Base 的令牌作用域。 如果一个 Base 返回 403 而另一个正常，这意味着令牌的访问列表未包含该 Base — 这不是作用域或身份验证问题。引导用户前往 https://airtable.com/create/tokens 授予权限。
速率限制是按 Base 而非按令牌计算的。 baseA 每秒 5 次请求且 baseB 每秒 5 次请求是可以的；仅 baseA 每秒 6 次请求将会被限流。监控 429 响应中的 Retry-After 头。

Hermes 重要注意事项

始终使用带有 curl 的 terminal 工具。 不要使用 web_extract（它无法发送身份验证头）或 browser_navigate（需要 UI 身份验证且速度较慢）。
加载此技能时，AIRTABLE_API_KEY 会自动从 ~/.hermes/.env 流入子进程 — 无需在每次 curl 调用前重新导出它。
仔细转义公式中的花括号。 在 heredoc 主体中，{Status} 是字面量。在 shell 参数中，{Status} 在 {...} 花括号扩展上下文之外是安全的 — 但在拼接到 URL 之前，请通过 python3 urllib.parse.quote 传递动态字符串。
使用 python3 -m json.tool（始终存在）进行美化打印，而不是 jq（可选）。仅在需要过滤/投影时才使用 jq。
分页是按页进行的，而非全局的。 Airtable 的 100 条记录上限是硬性限制；无法提高它。循环使用 offset 直到该字段 absent。
读取非 2xx 响应中的 errors 数组 — Airtable 返回结构化错误代码，如 AUTHENTICATION_REQUIRED、INVALID_PERMISSIONS、MODEL_ID_NOT_FOUND、INVALID_MULTIPLE_CHOICE_OPTIONS，这些代码会准确告知你哪里出错了。

技能元数据​

参考：完整 SKILL.md​

Airtable — Base、表与记录

前提条件​

API 基础​

字段类型（请求正文形状）​

常见查询​

列出令牌可见的 base​

列出 base 的表 + 架构​

列出记录（前 10 条）​

获取单条记录​

过滤记录 (filterByFormula)​

排序 + 选择特定字段​

使用命名视图​

常见变更操作​

创建记录​

在一次调用中创建最多 10 条记录​

更新记录（PATCH — 合并，保留未更改的字段）​

通过合并字段 Upsert（无需 ID）​

删除记录​

在一次调用中删除最多 10 条记录​

分页​

典型 Hermes 工作流​

常见陷阱​

Hermes 重要注意事项​