building-nango-functions

构建 Nango 函数

构建 Nango action 和 sync 实现，无需选择执行工作流。

此技能涵盖函数设计约定：架构、提供商调用、action 输出、sync 模型、检查点、删除处理、元数据、重试和运行时限制。它有意不涵盖本地 CLI 验证/部署或远程 API 编译/试运行/部署。

如果任务明确转为基于本地/CLI，请改用 building-nango-functions-locally。如果任务明确转为基于远程/API，请改用 building-nango-functions-remotely。

实现范围

• 构建或修改 Nango 函数实现
• 在 Nango 中使用 createAction() 构建 action
• 在 Nango 中使用 createSync() 构建 sync
• 使用当前工作流技能处理编译、试运行、测试和部署机制

Sync 策略关卡（写代码前必须完成）

如果任务是 sync，请在写代码前阅读 references/syncs.md，并首先说明以下路径之一：

• 检查点方案：
  • 更改来源（updated_at、modified_since、变更记录端点、游标、页面令牌、偏移量/页码、since_id 或 webhook）
  • 检查点架构
  • 检查点如何改变提供商请求或恢复状态
  • 请求仍会遍历完整数据集，还是只返回变更行
  • 删除策略
• 全量刷新阻碍因素：
  • 文档或示例负载中指出的确切提供商限制
  • 检查点在此处无法发挥作用的原因

无效的 sync 实现：

• 因为更简单而执行全量刷新
• 调用 saveCheckpoint() 却不调用 getCheckpoint()
• 读取或保存检查点，却不在请求参数或分页状态中使用
• 在新 sync 中使用 syncType: 'incremental' 或 nango.lastSyncDate
• 全量刷新没有 checkpoint 架构，或未在每一页后保存检查点——超过执行时限时，运行会从第 1 页重新开始
• 对 saveCheckpoint() 设置条件，仅在还有更多页时才调用（例如 if (nextCursor) { await nango.saveCheckpoint(...) }）。每个成功页面（包括最后一页）都必须调用 saveCheckpoint()；否则，单页 sync 在执行 clearCheckpoint() 时没有检查点记录，会失败并出现 checkpoint_conflict。
• 在 clearCheckpoint() 之前调用 trackDeletesEnd()，或完全没有先调用 clearCheckpoint()
• 对仅包含变更的检查点（modified_after、updated_after、变更记录端点）使用 trackDeletesStart() / trackDeletesEnd()。这些请求会省略未变更的行，因此 trackDeletesEnd() 会错误地删除它们。
• 在已显式包含删除记录事件的增量 sync 中使用 trackDeletesStart() / trackDeletesEnd()

选择路径

Action：

• 一次性请求，由用户触发，使用 createAction() 构建
• 写代码前阅读 references/actions.md

Sync：

• 使用 createSync() 构建，由计划任务或 webhook 驱动的缓存更新
• 首先完成 Sync 策略关卡
• 写代码前阅读 references/syncs.md

必需输入（缺失时询问用户）

始终需要：

• 集成 ID（提供商名称）
• 脚本／函数名称（kebab-case）
• API 参考 URL 或示例响应
• 如果当前工作流将验证或 dryrun 该函数，则需要连接 ID

特定于操作：

• 用例摘要
• 输入参数
• 输出字段
• 必要时提供元数据 JSON
• 如果当前工作流将验证或 dryrun 该操作，则需要测试输入 JSON（无输入操作使用 {}）

特定于同步：

• 模型名称（单数形式，PascalCase）
• 频率（每小时、每 5 分钟等）
• 检查点架构（时间戳、游标、页面令牌、偏移量／页码、since_id 或组合形式）
• 检查点如何改变提供商请求或恢复状态
• 删除策略（已删除记录端点／webhook，或说明为何必须完整刷新）
• 如果建议完整刷新，请提供文档／示例响应中阻止使用检查点的确切提供商限制
• 必要时提供元数据 JSON（team_id、workspace_id）

如果缺少任何必需的外部值，请在检查代码库和提供商文档后提出有针对性的问题。对于同步，只要提供商支持，就选择检查点和删除策略。如果找不到可行的检查点策略，请在编写完整刷新方案前准确说明原因。

不可妥协的规则

共享平台限制

• Nango 函数使用 createAction() / createSync()。
• 不得添加任意软件包。仅在所选工作流支持时使用相对导入；内置模块包括 zod、crypto/node:crypto 和 url/node:url。
• 在函数代码之外进行连接查询、凭据获取和代理调用时，使用 Nango HTTP API。不得编造 CLI 令牌或连接命令。
• 在每次提供商调用上方添加 API 文档链接注释。
• 操作输出不得超过 2 MB。
• 操作无法实现文件上传和下载（沙盒运行时：没有 fs、没有 axios，输出上限为 2 MB）。请改用 {integration}/proxy/ 中的代理脚本，并使用 @nangohq/node，参见 references/actions.md。
• HTTP 重试默认值为 0；请审慎设置 retries。通常最多设为 3；对于同步提供商调用，除非文档证明更高的值安全且必要，否则实际上禁止超过 3。对于非幂等写入操作，除非 API 支持幂等性，否则避免重试。
• 不要设置已弃用的函数定义路由字段：操作中的 endpoint 和同步中的 endpoints。通过 SDK/API 按操作名称触发操作，并通过 records API 获取同步记录。

同步规则

• 同步记录需要稳定的字符串 id。
• 新同步应定义 checkpoint 模式，先调用 nango.getCheckpoint()，并在每页或每批之后调用 nango.saveCheckpoint()。
• 只有在检查点会改变请求或恢复状态（since、updated_after、cursor、page_token、offset、page、since_id 等）时，它才有效。保存检查点却不使用它，不算增量同步。
• 新同步不得使用 syncType: 'incremental' 或 nango.lastSyncDate。
• 默认使用 nango.paginate(...) + nango.batchSave(...)。当 cursor、link 或 offset 分页适用时，避免手动编写 while (true) 循环。
• 当提供商返回删除记录、墓碑记录或删除 webhook 时，优先使用 batchDelete()。
• 仅当提供商无法返回变更、删除记录或恢复状态，或数据集很小时，才使用全量刷新。
• 对于全量刷新，请引用文档或负载中关于提供商限制的具体内容。“这样更简单”并不足以成为理由。
• 全量刷新同步也需要 checkpoint 模式（涵盖分页进度的 page/cursor/offset），而不仅是增量同步。Nango 同步在有时间限制的执行窗口内运行；如果全量刷新超出执行窗口且没有检查点，每次运行都会从第 1 页重新开始，浪费计算资源重复获取相同的前几页，永远无法处理其余数据。
• deleteRecordsFromPreviousExecutions() 已弃用。对于全量刷新，每次执行都调用 trackDeletesStart()（安全且幂等——不会覆盖已打开窗口的起始位置），然后在每页之后调用 saveCheckpoint()，最后一页之后调用 clearCheckpoint()，并且仅在调用 clearCheckpoint() 后调用 trackDeletesEnd()。
• 在全量刷新中，成功处理每一页后都要调用 saveCheckpoint()，包括最后一页，并且要在调用 clearCheckpoint() 之前完成。不要使用“仍有更多页面”的条件来控制是否保存。如果某条单独的执行路径根本没有创建检查点（例如，该路径未处理任何页面），不要在这条路径上调用 clearCheckpoint()；否则运行时会抛出 checkpoint_conflict。此例外不能替代对最后一页的保存。
• 绝不要将 trackDeletesStart() / trackDeletesEnd() 与仅针对变更记录的检查点（modified_after、updated_after、变更记录端点等）组合使用。这些方式会省略未变更的行，因此 trackDeletesEnd() 会将它们删除。
• 带检查点的全量刷新仍然是全量刷新。仅在完成并清除检查点的那次运行中调用 trackDeletesEnd()。
• 如果同步需要元数据（例如 team_id、workspace_id、guild_id），请设置 autoStart: false。调用方设置元数据之前，同步无法运行，因此自动启动会导致失败。

约定

• 字段大小写应与外部 API 一致。直通字段保留提供商的大小写；非直通字段应使用该 API 中占多数的大小写。
• 优先使用明确的字段名。
• 为 ID、时间戳、枚举和 URL 添加 .describe() 示例。
• 避免使用 any；使用内联映射类型。
• 列表操作应公开 cursor，以及符合该 API 中占多数写法的下一个游标字段（next_cursor、nextCursor 等）。
• 仅在需要自定义验证或日志记录时使用 nango.zodValidateInput()；否则依赖模式以及所选的验证工作流。

Schema 语义

• 将非必填输入默认设为 .optional()。
• 只有当 null 有实际含义时才使用 .nullable()，通常用于更新时清除值；如果调用方也可以省略该字段，则添加 .optional()。
• 原始提供方架构应与提供方保持一致：省略的字段使用 .optional()，显式的 null 使用 .nullable()，仅当提供方确实同时支持两者时才使用 .nullish()。
• 最终操作输出和规范化的同步模型应优先使用 .optional()，并将上游的 null 规范化为省略，除非 null 有实际意义。
• 生成的架构默认将非必填输入和规范化输出设为 .optional()；只有上游契约有依据时才放宽限制。
• 优先使用 .nullable()，而非 z.union([z.null(), T]) 或 z.union([T, z.null()])。
• 仅当输出架构允许时才返回 null。
• z.object() 默认会剔除未知键。对于原样传递提供方数据的情况，使用 z.object({}).passthrough()、z.record(z.unknown()) 或带有最少精炼规则的 z.unknown()。

字段命名和大小写规则

• 按 API 的主要大小写风格使用明确的后缀：ID（user_id、userId）、名称（channel_name、channelName）、电子邮件（user_email、userEmail）、URL（callback_url、callbackUrl）和时间戳（created_at、createdAt）。

映射示例（API 期望使用不同的参数名称）：

const InputSchema = z.object({
    userId: z.string()
});

const config: ProxyConfiguration = {
    endpoint: 'users.info',
    params: {
        user: input.userId
    },
    retries: 3
};

如果 API 使用 snake_case，则使用 user_id。目标是保持 API 一致性。

参考资料

• 操作模式、CRUD 示例、元数据用法和 ActionError 示例：references/actions.md
• 同步模式、具体的检查点示例、删除策略和完整刷新回退：references/syncs.md

Nango 文档速查链接

• 函数运行时 SDK 参考：https://nango.dev/docs/reference/functions
• 实现操作：https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
• 实现同步：https://nango.dev/docs/implementation-guides/use-cases/syncs/implement-a-sync
• 检查点：https://nango.dev/docs/implementation-guides/use-cases/syncs/checkpoints
• 删除检测（完整与增量）：https://nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection
• 测试集成（dryrun、--save、Vitest）：https://nango.dev/docs/implementation-guides/platform/functions/testing
• Nango HTTP API 参考：https://nango.dev/docs/reference/api

API 文档无法加载时

如果网页抓取返回的文档不完整（由 JS 渲染）：

• 请用户提供示例响应
• 如果工作区中存在现有的 Nango 操作或同步，则以其为模式
• 使用该技能专用的验证或 dryrun 工作流，直到通过为止