airtable-master

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Airtable Master

This is NOT a user-facing skill. It's a shared resource library.

这并非面向用户的skill，而是一个共享资源库。

Purpose

用途

Provides shared resources to eliminate duplication across:

```
airtable-connect
```
- Connect to bases, discover schema
```
airtable-query
```
- Query records with filters
```
airtable-sync
```
- Import/export records

Instead of loading this skill, users invoke the specific skill above.

为以下技能提供共享资源，以消除重复内容：

```
airtable-connect
```
- 连接到工作区，发现数据结构
```
airtable-query
```
- 使用过滤器查询记录
```
airtable-sync
```
- 导入/导出记录

请勿加载此skill，用户应调用上述特定技能。

Architecture: DRY Principle

架构：DRY原则

Problem solved: Multiple Airtable skills would have duplicated content (setup instructions, API docs, error handling).

Solution: Extract shared content into

references/

and

scripts/

Result: Single source of truth, reduced context per skill.

解决的问题：多个Airtable技能会存在重复内容（设置说明、API文档、错误处理）。

解决方案：将共享内容提取到

references/

和

scripts/

目录中。

成果：单一事实来源，减少每个技能的上下文内容。

Shared Resources

共享资源

references/

setup-guide.md - Complete setup wizard

Creating Personal Access Token (PAT)
Configuring .env file
Selecting scopes
Validation steps

api-reference.md - API patterns

Base URL and headers
Key endpoints (bases, tables, records)
Pagination
Batch operations
Rate limits

error-handling.md - Troubleshooting

HTTP error codes (401, 403, 404, 422, 429)
Recovery patterns
Debugging tips

field-types.md - Field type reference

All 20+ Airtable field types
Read and write formats
Type-specific validation

setup-guide.md - 完整设置向导

创建个人访问令牌（PAT）
配置.env文件
选择权限范围
验证步骤

api-reference.md - API模式

基础URL与请求头
核心端点（工作区、表格、记录）
分页
批量操作
请求速率限制

error-handling.md - 故障排除

HTTP错误码（401、403、404、422、429）
恢复模式
调试技巧

field-types.md - 字段类型参考

全部20余种Airtable字段类型
读写格式
类型专属验证

scripts/

Configuration & Setup

配置与设置

check_airtable_config.py - Pre-flight validation

bash

python check_airtable_config.py [--verbose] [--json]

Argument	Required	Default	Description
`--verbose` / `-v`	No	False	Show detailed output
`--json`	No	False	Output structured JSON for AI consumption

Exit codes: 0=configured, 1=partial (no bases), 2=not configured

When to Use: Run this FIRST before any Airtable operation. Use to validate PAT is configured, test API connection, check base access, or diagnose authentication issues.

setup_airtable.py - Interactive setup wizard

bash

python setup_airtable.py [--non-interactive] [--api-key KEY]

Argument	Required	Default	Description
`--non-interactive`	No	False	Skip prompts (requires API key)
`--api-key`	No	-	API key for non-interactive mode

Default: Runs interactively. Guides through PAT creation, tests connection, saves to

.env

, auto-runs base discovery.

When to Use: Use when Airtable integration needs initial setup, when check_airtable_config.py returns exit code 2, or when user needs to reconfigure credentials or switch workspaces.

discover_bases.py - Base discovery (GET /meta/bases)

bash

python discover_bases.py [--refresh] [--json] [--with-schema]

Argument	Required	Default	Description
`--refresh`	No	False	Force re-discovery even if cache exists
`--json`	No	False	Output as JSON only (no progress messages)
`--with-schema`	No	False	Also fetch table schemas (slower)

Saves to:

01-memory/integrations/airtable-bases.yaml

When to Use: Use when user asks "what bases do I have", "list my airtable bases", "show tables", after adding new bases, or when base/table name resolution fails (--refresh to update cache).

check_airtable_config.py - 预验证脚本

bash

python check_airtable_config.py [--verbose] [--json]

参数	是否必填	默认值	描述
`--verbose` / `-v`	否	False	显示详细输出
`--json`	否	False	输出结构化JSON供AI使用

退出码：0=已配置，1=部分配置（无可用工作区），2=未配置

适用场景：在任何Airtable操作前首先运行此脚本。用于验证PAT是否配置、测试API连接、检查工作区访问权限，或诊断认证问题。

setup_airtable.py - 交互式设置向导

bash

python setup_airtable.py [--non-interactive] [--api-key KEY]

参数	是否必填	默认值	描述
`--non-interactive`	否	False	跳过提示（需提供API密钥）
`--api-key`	否	-	非交互模式下使用的API密钥

默认行为：以交互式运行。引导用户创建PAT、测试连接、保存到

.env

文件、自动运行工作区发现。

适用场景：当Airtable集成需要初始设置时、当check_airtable_config.py返回退出码2时，或当用户需要重新配置凭据或切换工作区时使用。

discover_bases.py - 工作区发现（调用GET /meta/bases）

bash

python discover_bases.py [--refresh] [--json] [--with-schema]

参数	是否必填	默认值	描述
`--refresh`	否	False	即使缓存存在，强制重新发现
`--json`	否	False	仅输出JSON（无进度信息）
`--with-schema`	否	False	同时获取表格数据结构（速度较慢）

保存路径：

01-memory/integrations/airtable-bases.yaml

适用场景：当用户询问“我有哪些工作区”“列出我的Airtable工作区”“显示表格”时、添加新工作区后，或当工作区/表格名称解析失败时（使用--refresh更新缓存）。

Record Operations

记录操作

query_records.py - Query records from table (GET /{baseId}/{tableIdOrName})

bash

python query_records.py --base BASE --table TABLE [--filter FORMULA] [--fields FIELDS] [--view VIEW] [--sort FIELD] [--limit N] [--json] [--verbose]

Argument	Required	Default	Description
`--base`	Yes	-	Base ID (appXXX) or name
`--table`	Yes	-	Table ID (tblXXX) or name
`--filter`	No	-	Airtable formula filter
`--fields`	No	-	Comma-separated field names to retrieve
`--view`	No	-	View ID or name
`--sort`	No	-	Sort field (prefix with `-` for descending)
`--limit`	No	-	Max records to return
`--json`	No	False	Output as JSON
`--verbose` / `-v`	No	False	Show debug info

Filter Formula Examples:

bash

--filter "{Status}='Active'"
--filter "AND({Status}='Active', {Priority}='High')"
--filter "SEARCH('john', LOWER({Name}))"
--filter "{Due Date} < TODAY()"

When to Use: Use when user wants to read records from a table, search with filters, list data from Airtable, or retrieve specific records. Supports Airtable formula syntax for complex filters.

manage_records.py - CRUD operations (POST/PATCH/PUT/DELETE /{baseId}/{tableIdOrName})

bash

undefined

query_records.py - 从表格查询记录（调用GET /{baseId}/{tableIdOrName}）

bash

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`	否	False	输出为JSON格式
`--verbose` / `-v`	否	False	显示调试信息

过滤器公式示例：

bash

--filter "{Status}='Active'"
--filter "AND({Status}='Active', {Priority}='High')"
--filter "SEARCH('john', LOWER({Name}))"
--filter "{Due Date} < TODAY()"

适用场景：当用户需要从表格读取记录、使用过滤器搜索、列出Airtable中的数据，或检索特定记录时使用。支持Airtable公式语法实现复杂过滤。

manage_records.py - CRUD操作（调用POST/PATCH/PUT/DELETE /{baseId}/{tableIdOrName}）

bash

undefined

Create record(s)

创建记录

python manage_records.py create --base BASE --table TABLE --data JSON [--file FILE] [--typecast] [--json] [--verbose]

Update record(s)

更新记录

python manage_records.py update --base BASE --table TABLE --record RECID --data JSON [--file FILE] [--typecast] [--replace] [--json] [--verbose]

Delete record(s)

删除记录

python manage_records.py delete --base BASE --table TABLE --record RECID [--file FILE] [--json] [--verbose]


| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `action` | **Yes** | - | Action: `create`, `update`, `delete` (positional) |
| `--base` | **Yes** | - | Base ID (appXXX) or name |
| `--table` | **Yes** | - | Table ID (tblXXX) or name |
| `--record` | No* | - | Record ID (for update/delete single record) |
| `--data` | No* | - | JSON data for fields |
| `--file` | No* | - | JSON file with record(s) data |
| `--typecast` | No | False | Enable automatic type conversion |
| `--replace` | No | False | Replace mode for update (PUT vs PATCH) |
| `--json` | No | False | Output as JSON |
| `--verbose` / `-v` | No | False | Show debug info |

*For create: `--data` or `--file` required
*For update: `--record` + `--data` or `--file` required
*For delete: `--record` or `--file` required

**Usage Examples:**
```bash

python manage_records.py delete --base BASE --table TABLE --record RECID [--file FILE] [--json] [--verbose]


| 参数 | 是否必填 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `action` | **是** | - | 操作类型：`create`、`update`、`delete`（位置参数） |
| `--base` | **是** | - | 工作区ID（appXXX）或名称 |
| `--table` | **是** | - | 表格ID（tblXXX）或名称 |
| `--record` | 否* | - | 记录ID（用于更新/删除单条记录） |
| `--data` | 否* | - | 字段的JSON数据 |
| `--file` | 否* | - | 包含记录数据的JSON文件 |
| `--typecast` | 否 | False | 启用自动类型转换 |
| `--replace` | 否 | False | 更新时使用替换模式（PUT 替代 PATCH） |
| `--json` | 否 | False | 输出为JSON格式 |
| `--verbose` / `-v` | 否 | False | 显示调试信息 |

*创建操作：需提供`--data`或`--file`
*更新操作：需提供`--record` + `--data`或`--file`
*删除操作：需提供`--record`或`--file`

**使用示例**：
```bash

Create a single record

创建单条记录

python manage_records.py create --base "My CRM" --table "Contacts"
--data '{"Name": "John Doe", "Email": "john@example.com"}'

Create multiple records from file

从文件创建多条记录

python manage_records.py create --base appXXX --table tblYYY --file records.json

Update a record

更新记录

python manage_records.py update --base "Tasks" --table "Tasks"
--record recXXX --data '{"Status": "Done"}'

Delete a record

删除记录

python manage_records.py delete --base "Tasks" --table "Tasks" --record recXXX

Batch operations with typecast

启用类型转换的批量操作

python manage_records.py create --base "CRM" --table "Leads"
--file leads.json --typecast


**Batch Limits:** Max 10 records per API call (script handles batching automatically)

**When to Use:** Use `create` when user wants to add new records, `update` to modify existing records (PATCH=partial, PUT=replace), `delete` to remove records. Supports batch operations from JSON files.

---

python manage_records.py create --base "CRM" --table "Leads"
--file leads.json --typecast


**批量操作限制**：每次API调用最多处理10条记录（脚本会自动处理分批）

**适用场景**：使用`create`添加新记录，使用`update`修改现有记录（PATCH=部分更新，PUT=完全替换），使用`delete`删除记录。支持从JSON文件进行批量操作。

---

Intelligent Error Detection Flow

智能错误检测流程

When an Airtable skill fails due to missing configuration, the AI should:

当Airtable技能因配置缺失而失败时，AI应执行以下步骤：

Step 1: Run Config Check with JSON Output

步骤1：运行带JSON输出的配置检查

bash

python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json

bash

python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json

Step 2: Parse the

ai_action

Field

步骤2：解析

ai_action

字段

The JSON output includes an

ai_action

field that tells the AI what to do:

ai_action	What to Do
`proceed_with_operation`	Config OK, continue with the original operation
`proceed_with_warning`	Partial config (API works but no bases accessible)
`prompt_for_api_key`	Ask user: "I need your Airtable API key. Get one at https://airtable.com/create/tokens"
`run_setup_wizard`	Run: `python 00-system/skills/airtable/airtable-master/scripts/setup_airtable.py`

JSON输出包含

ai_action

字段，用于告知AI应执行的操作：

ai_action 值	操作说明
`proceed_with_operation`	配置正常，继续执行原操作
`proceed_with_warning`	配置不完整（API可用但无访问权限的工作区）
`prompt_for_api_key`	询问用户：“我需要您的Airtable API密钥。请前往https://airtable.com/create/tokens获取”
`run_setup_wizard`	运行： `python 00-system/skills/airtable/airtable-master/scripts/setup_airtable.py`

Step 3: Help User Fix Issues

步骤3：协助用户解决问题

ai_action

prompt_for_api_key

Tell user: "Airtable integration needs setup. I need your Personal Access Token (PAT)."
Show them: "Get one at: https://airtable.com/create/tokens"
Guide them through scopes: "Add scopes: data.records:read, data.records:write, schema.bases:read"
Ask: "Paste your Airtable PAT here (starts with 'pat.'):"

Once they provide it, write directly to
.env
:

# Edit .env file to add:
AIRTABLE_API_KEY=pat.their_token_here

Re-run config check to verify

如果

ai_action

为

prompt_for_api_key

：

告知用户：“Airtable集成需要设置。我需要您的个人访问令牌（PAT）。”
提供链接：“获取地址：https://airtable.com/create/tokens”
引导设置权限范围：“添加以下权限范围：data.records:read, data.records:write, schema.bases:read”
请求用户提供：“请在此粘贴您的Airtable PAT（以'pat.'开头）：”

用户提供后，直接写入
.env
文件：

# 编辑.env文件添加：
AIRTABLE_API_KEY=pat.their_token_here

重新运行配置检查以验证

JSON Output Structure

JSON输出结构

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"
}

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"
}

How Skills Reference This

各技能如何引用本资源库

Each skill loads shared resources only when needed (progressive disclosure):

airtable-connect uses:

```
check_airtable_config.py
```
(validate before connection)
```
discover_bases.py
```
(find and cache bases)
```
api-reference.md
```
(schema endpoints)
```
error-handling.md
```
(troubleshooting)

airtable-query uses:

```
check_airtable_config.py
```
(validate before query)
```
query_records.py
```
(list/filter records)
```
api-reference.md
```
(query patterns)
```
field-types.md
```
(interpret results)

airtable-sync uses:

```
check_airtable_config.py
```
(validate before sync)
```
manage_records.py
```
(CRUD operations)
```
api-reference.md
```
(batch patterns)
```
error-handling.md
```
(recovery)

每个技能仅在需要时加载共享资源（渐进式加载）：

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
```
（CRUD操作）
```
api-reference.md
```
（批量操作模式）
```
error-handling.md
```
（恢复操作）

Usage Example

使用示例

User says: "query my Projects base in Airtable"

What happens:

AI loads
```
airtable-connect
```
(NOT airtable-master)
```
airtable-connect
```
SKILL.md says: "Run check_airtable_config.py first"

AI executes:

python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json

If exit code 2, AI prompts user for API key and helps them set up

If exit code 0, AI executes:

python 00-system/skills/airtable/airtable-master/scripts/query_records.py --base "Projects"

If errors occur, AI loads:

airtable-master/references/error-handling.md

airtable-master is NEVER loaded directly - it's just a resource library.

用户提问：“查询我Airtable中的Projects工作区”

执行流程：

AI加载
```
airtable-connect
```
（而非airtable-master）
```
airtable-connect
```
的SKILL.md提示：“先运行check_airtable_config.py”

AI执行：

python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json

如果返回退出码2，AI会提示用户提供API密钥并协助完成设置

如果返回退出码0，AI执行：

python 00-system/skills/airtable/airtable-master/scripts/query_records.py --base "Projects"

若出现错误，AI加载：

airtable-master/references/error-handling.md

airtable-master永远不会被直接加载——它只是一个资源库。

Key Differences from Notion

与Notion的主要差异

Aspect	Airtable	Notion
Auth	Personal Access Token (PAT)	Integration Token
Rate Limit	5 req/s per base	3 req/s
Batch Size	10 records	Variable
Pagination	Offset-based	Cursor-based
Field Types	20+ types	20+ property types

Version: 1.3 Created: 2025-12-11 Updated: 2025-12-11 Status: Production Ready

Changelog:

v1.3: Added "When to Use" sections to all 5 scripts for AI routing guidance
v1.2: Added comprehensive script argument documentation with usage examples and argument tables
v1.1: Added Intelligent Error Detection Flow with
```
--json
```
support, added setup_airtable.py
v1.0: Initial release

维度	Airtable	Notion
认证方式	个人访问令牌（PAT）	集成令牌
请求速率限制	每个工作区每秒5次请求	每秒3次请求
批量操作大小	10条记录	可变
分页方式	基于偏移量	基于游标
字段类型	20余种	20余种属性类型

版本：1.3 创建时间：2025-12-11 更新时间：2025-12-11 状态：可用于生产环境

更新日志：

v1.3：为所有5个脚本添加“适用场景”章节，用于AI路由指导
v1.2：添加全面的脚本参数文档，包含使用示例和参数表格
v1.1：添加带
```
--json
```
支持的智能错误检测流程，新增setup_airtable.py
v1.0：初始发布

airtable-master

Original

Translation

Airtable Master

Airtable Master

Purpose

用途

Architecture: DRY Principle

架构：DRY原则

Shared Resources

共享资源

references/

references/

scripts/

scripts/

Configuration & Setup

配置与设置

Record Operations

记录操作

Create record(s)

创建记录

Update record(s)

更新记录

Delete record(s)

删除记录

Create a single record

创建单条记录

Create multiple records from file

从文件创建多条记录

Update a record

更新记录

Delete a record

删除记录

Batch operations with typecast

启用类型转换的批量操作

Intelligent Error Detection Flow

智能错误检测流程

Step 1: Run Config Check with JSON Output

步骤1：运行带JSON输出的配置检查

Step 2: Parse the ai_action Field

步骤2：解析ai_action字段

Step 3: Help User Fix Issues

步骤3：协助用户解决问题

JSON Output Structure

JSON输出结构

How Skills Reference This

各技能如何引用本资源库

Usage Example

使用示例

Key Differences from Notion

与Notion的主要差异

Step 2: Parse the
`ai_action`
Field

步骤2：解析
`ai_action`
字段