核心用法
Coda API Skill 提供与 Coda.io 平台的全功能 REST API 对接能力，覆盖文档生命周期管理的完整链路。用户可通过封装脚本 scripts/coda.sh 或直接使用 curl 调用 API，实现对 Coda 文档、页面、表格、列、行、公式、控件、文件夹、权限、发布、自动化及分析数据的操作。
读取流程：list-docs → list-tables → list-columns → list-rows，支持分页（nextPageToken）和列名映射（useColumnNames=true）。
写入流程：先发现列 ID，构建包含 cells 数组的行 JSON，使用 insert-rows 新增或 upsert-rows 基于 keyColumns 实现幂等更新。写入操作异步返回 HTTP 202，可通过 mutation-status 轮询确认。
关键特性：强制使用稳定资源 ID（而非可编辑名称）；支持 X-Coda-Doc-Version: latest 避免读取陈旧数据；提供 simple/rich 等多级 valueFormat 格式。
显著优点
- 功能全面：涵盖 Coda 生态几乎所有可编程对象，从基础 CRUD 到权限分享、自动化触发、发布控制。
- 封装友好：
coda.sh助手脚本降低命令行使用门槛，支持管道化 JSON 处理（jq 集成）。 - 幂等写入：
upsert-rows配合keyColumns实现去重更新，适合数据同步场景。 - 文档解析清晰：Doc ID 提取规则、列名/ID 映射策略均有明确指引。
潜在缺点与局限性
- 异步一致性：写入非即时生效，需额外轮询确认，实时性要求高的场景需设计补偿逻辑。
- 限流严格：读 100/6秒、写 10/6秒、文档内容写 5/10秒，高频批量操作易触发 429。
- 列 ID 依赖：写入前必须预先获取列 ID，无法直接通过列名写入（虽读取支持列名）。
- 无原生 OAuth：仅支持 API Token 认证，令牌泄露风险集中。
适合人群
- 需要将外部系统数据（CRM、数据库、日志）双向同步至 Coda 的工程师/数据团队
- 构建 Coda 自动化工作流（如审批、数据聚合）的公民开发者
- 管理多文档权限、批量分享的企业管理员
常规风险
- 令牌安全：
CODA_API_TOKEN需妥善保管，泄露可导致工作空间数据被完全访问。 - 数据覆盖：
upsert匹配逻辑配置错误可能导致意外批量更新或删除。 - 异步延迟：依赖写入即时生效的业务逻辑可能因延迟导致状态不一致。
- 限流中断：未实现退避重试的脚本可能在批量任务中失败。