SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场airtable-master

airtable-master

数据与分析

查看项目

更新于 10-15 10:26

技能介绍

用途

airtable-master 并非面向用户的技能，而是一个共享资源库，用于消除多个 Airtable 集成技能之间的内容重复。它遵循 DRY（Don't Repeat Yourself）原则，将公共内容抽取到 references/ 与 scripts/ 目录中，形成单一事实来源，从而减少每个技能占用的上下文。

它为以下技能提供共享资源：

  • airtable-connect：连接库、发现表结构
  • airtable-query：使用过滤器查询记录
  • airtable-sync：导入/导出记录

用户应调用上述具体技能，而不是直接加载 airtable-master。

主要能力

共享参考资料（references/）

  • setup-guide.md：完整配置向导，包括创建个人访问令牌（PAT）、配置 .env 文件、选择权限范围、验证步骤
  • api-reference.md：API 模式，包括基础 URL 与请求头、关键端点（bases、tables、records）、分页、批量操作、速率限制
  • error-handling.md：故障排查，包括 HTTP 错误码（401、403、404、422、429）、恢复模式、调试技巧
  • field-types.md：字段类型参考，包括 20 多种 Airtable 字段类型、读写格式、按类型的校验

脚本（scripts/）

配置与设置：

  • check_airtable_config.py：预检校验。用法 python check_airtable_config.py [--verbose] [--json]。参数：--verbose/-v（默认 False，显示详细输出）、--json（默认 False，输出结构化 JSON 供 AI 使用）。退出码：0=已配置，1=部分配置（无库），2=未配置。应在任何 Airtable 操作之前首先运行。
  • setup_airtable.py：交互式配置向导。用法 python setup_airtable.py [--non-interactive] [--api-key KEY]。参数：--non-interactive（默认 False，跳过提示，需要 API key）、--api-key（默认 -，用于非交互模式的 API key）。默认交互运行，引导完成 PAT 创建、连接测试、保存到 .env，并自动运行库发现。
  • discover_bases.py：库发现（GET /meta/bases）。用法 python discover_bases.py [--refresh] [--json] [--with-schema]。参数：--refresh（默认 False，强制重新发现即使存在缓存）、--json（默认 False，仅输出 JSON，无进度消息）、--with-schema（默认 False，同时获取表结构，较慢）。保存至：01-memory/integrations/airtable-bases.yaml。

记录操作：

  • query_records.py：从表查询记录（GET /{baseId}/{tableIdOrName}）。用法 python query_records.py --base BASE --table TABLE [--filter FORMULA] [--fields FIELDS] [--view VIEW] [--sort FIELD] [--limit N] [--json] [--verbose]。参数：--base（必填，库 ID appXXX 或名称）、--table（必填，表 ID tblXXX 或名称）、--filter（Airtable 公式过滤器）、--fields（逗号分隔的字段名）、--view（视图 ID 或名称）、--sort（排序字段，前缀 - 表示降序）、--limit（最大记录数）、--json、--verbose/-v。过滤公式示例：--filter "{Status}='Active'"、--filter "AND({Status}='Active', {Priority}='High')"、--filter "SEARCH('john', LOWER({Name}))"、--filter "{Due Date} < TODAY()"。
  • manage_records.py：CRUD 操作（POST/PATCH/PUT/DELETE /{baseId}/{tableIdOrName}）。用法：
    • 创建：python manage_records.py create --base BASE --table TABLE --data JSON [--file FILE] [--typecast] [--json] [--verbose]
    • 更新：python manage_records.py update --base BASE --table TABLE --record RECID --data JSON [--file FILE] [--typecast] [--replace] [--json] [--verbose]
    • 删除：python manage_records.py delete --base BASE --table TABLE --record RECID [--file FILE] [--json] [--verbose] 参数：action（必填，create/update/delete）、--base（必填）、--table（必填）、--record（单记录更新/删除）、--data（字段 JSON）、--file（含记录数据的 JSON 文件）、--typecast（启用自动类型转换）、--replace（更新时替换模式，PUT vs PATCH）、--json、--verbose/-v。创建需 --data 或 --file；更新需 --record + --data 或 --file；删除需 --record 或 --file。批量限制：每次 API 调用最多 10 条记录（脚本自动处理分批）。

使用方式

智能错误检测流程

当 Airtable 技能因缺少配置而失败时：

  1. 运行配置检查并输出 JSON：python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json
  2. 解析 ai_action 字段：
    • proceed_with_operation：配置正常，继续原操作
    • proceed_with_warning：部分配置（API 可用但无库可访问）
    • prompt_for_api_key：询问用户获取 API key（https://airtable.com/create/tokens）
    • run_setup_wizard：运行 python 00-system/skills/airtable/airtable-master/scripts/setup_airtable.py
  3. 帮助用户修复问题。若 ai_action 为 prompt_for_api_key：告知需要设置集成，索取个人访问令牌（PAT），引导权限范围（data.records:read、data.records:write、schema.bases:read），用户提供后写入 .env（AIRTABLE_API_KEY=pat.their_token_here），再重新运行配置检查验证。

JSON 输出结构

{
  "status": "not_configured",
  "exit_code": 2,
  "ai_action": "prompt_for_api_key",
  "missing": [
    {"item": "AIRTABLE_API_KEY", "required": true, "location": ".env"}
  ],
  "fix_instructions": [...],
  "env_template": "AIRTABLE_API_KEY=pat.YOUR_TOKEN_HERE",
  "setup_wizard": "python 00-system/skills/airtable/airtable-master/scripts/setup_airtable.py"
}

技能如何引用本库

各技能按需加载共享资源（渐进式披露）：

  • airtable-connect 使用：check_airtable_config.py、discover_bases.py、api-reference.md、error-handling.md
  • airtable-query 使用：check_airtable_config.py、query_records.py、api-reference.md、field-types.md
  • airtable-sync 使用：check_airtable_config.py、manage_records.py、api-reference.md、error-handling.md

使用示例

用户说："query my Projects base in Airtable"。流程：AI 加载 airtable-connect（而非 airtable-master）；其 SKILL.md 指示先运行 check_airtable_config.py；AI 执行该脚本并输出 JSON；若退出码为 2，AI 提示用户配置 API key；若为 0，AI 执行 query_records.py；如遇错误，AI 加载 airtable-master/references/error-handling.md。airtable-master 从不被直接加载，它只是资源库。

与 Notion 的关键区别

  • 认证：Airtable 使用个人访问令牌（PAT），Notion 使用集成令牌
  • 速率限制：Airtable 每库 5 请求/秒，Notion 3 请求/秒
  • 批量大小：Airtable 10 条记录，Notion 可变
  • 分页：Airtable 基于 offset，Notion 基于 cursor
  • 字段类型：Airtable 20 多种类型，Notion 20 多种属性类型

版本信息

  • 版本：1.3
  • 创建：2025-12-11
  • 更新：2025-12-11
  • 状态：Production Ready

变更日志：

  • v1.3：为全部 5 个脚本添加 "When to Use" 部分，用于 AI 路由指引
  • v1.2：添加全面的脚本参数文档，含用法示例与参数表
  • v1.1：添加支持 --json 的智能错误检测流程，添加 setup_airtable.py
  • v1.0：初始版本

限制

本资源库本身不是面向用户的技能，不应被直接加载或调用。具体的 API 使用限制（如速率限制、批量大小）已在参考资料中说明，不在此处重复。