Airtable 参与者技能

用途

从 Ceremonia Airtable 基础数据库中查询静修营参与者数据。该数据库是接收邮件和短信人员信息的唯一权威来源。

默认仅提供只读访问权限——任何记录修改操作均须获得 Austin 的明确指令，且每次变更均需单独确认。

必要配置

确保 AIRTABLE_API_KEY 已在 .env 文件中设置。

此外还需以下信息：

• Base ID： [待验证 — 可在 Airtable 开发者文档（airtable.com/developers）中查找，或直接向 Austin 确认]
• 表名（Table name）： [待验证 — 请与 Austin 确认参与者所在表的确切名称]

待上述值经核实后，请将确认结果同步更新至 TOOLS.md 和 MEMORY.md 中。

预期数据结构

参与者记录至少应包含以下字段：

[首次使用时请与 Austin 核实实际字段名 — 待确认后更新本节内容]

常用查询模式

获取全部活跃参与者（用于发送新闻简报）

curl -s "https://api.airtable.com/v0/{BASE_ID}/{TABLE_NAME}?filterByFormula={retreat_status}='active'&fields[]=name&fields[]=email" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | jq '.records[].fields'

获取拥有电话号码的参与者（用于短信营销活动）

curl -s "https://api.airtable.com/v0/{BASE_ID}/{TABLE_NAME}?filterByFormula=AND({retreat_status}='active',{phone}!='')&fields[]=name&fields[]=phone" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | jq '.records[].fields'

按状态统计参与者数量

curl -s "https://api.airtable.com/v0/{BASE_ID}/{TABLE_NAME}?fields[]=retreat_status" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | jq '[.records[].fields.retreat_status] | group_by(.) | map({status: .[0], count: length})'

按标签获取参与者

curl -s "https://api.airtable.com/v0/{BASE_ID}/{TABLE_NAME}?filterByFormula=FIND('february-2026',ARRAYJOIN({tags}))" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | jq '.records[].fields'

注意：Airtable 默认每页返回 100 条记录。如需获取后续页面，请使用响应中的 offset 参数：

curl -s "https://api.airtable.com/v0/{BASE_ID}/{TABLE_NAME}?offset={OFFSET_TOKEN}" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | jq .

在生成汇总总数或构建收件人列表前，务必完成完整分页请求。

行为规范

• 默认为只读访问 —— 未经 Austin 针对每次操作的明确指令，禁止执行任何 PATCH、POST 或 DELETE 操作
• 构建邮件或短信收件人列表时：必须过滤掉 retreat_status 为 unsubscribed 的记录
• 严禁在 Slack 消息中直接暴露邮箱地址或电话号码 —— 仅可汇报统计数量及人群分组摘要
• 若查询意外返回 0 条结果：应立即向 Austin 报告问题，不得向空列表发送消息
• 所有列表类查询均须完整分页 —— 不得汇报部分计数或构建不完整的收件人列表
• 若 Airtable API 返回错误：须立即将错误码与错误信息上报 Austin

记录修改（需 Austin 审批）

当 Austin 下达记录修改指令（例如：将某人标记为已退订、更新 last_contact 字段）时：

1. 执行前须与 Austin 明确确认具体修改内容
2. 执行 PATCH 请求
3. 在 memory/logs/crm-writes/YYYY-MM-DD.md 中记录本次变更，包括：记录姓名/邮箱、被修改字段、旧值、新值、Austin 指令的时间戳

调用示例

• “我们目前有多少活跃参与者？”
• “获取二月静修营参与者的邮箱列表”
• “最近三次静修营的参会者有哪些？”
• “系统中留存了多少人的电话号码？”
• “将 [name] 标记为已退订”（需 Austin 批准）
• “拉取完整活跃参与者列表用于新闻简报”
• “今年一月以来新增了多少人？”