apify-integration-development

Apify 集成开发

在 Apify 提供最少帮助的情况下，为某家公司的产品设计并构建官方 Apify 集成。本技能涵盖 Apify 支持的所有集成形式——工作流自动化应用、AI Agent 插件（编码 Agent 和运行框架）、AI 框架包，以及直接应用客户端——帮助合作伙伴团队端到端地交付一流的 Apify 集成。以下通用规则适用于所有形式，其余内容则由一个类别专属的参考文件说明。

正在构建官方集成？ 发布后，请联系 [email protected]，让 Apify 团队在集成面向用户之前对其进行审查、测试和验证。我们会检查功能范围、成本控制、错误处理和归属标头，并帮助你弥补任何不足。

步骤 0 - 先了解 Apify 模型（必需）

开始设计之前，请先获取并阅读 https://apify.com/agents.md。这是面向 AI Agent 的权威快速入门指南，也是术语、运行流程和成本规则的唯一真实来源。如果获取失败，下面的迷你术语表仍可帮助你使用本技能。

Apify 术语（在平台上始终以大写 A 开头）：

• Actor - 一个无服务器云程序，接收 JSON 输入、执行任务并生成结构化输出。它不是 AI Agent。
• Actor Run - Actor 的一次执行。每次运行都有自己的数据集、键值存储和请求队列，并以终止状态结束（SUCCEEDED、FAILED、TIMED-OUT、ABORTED）。
• Dataset - 用于存储某次运行结果的只追加结构化存储。调用 Actor 会返回数据集 ID，而不是数据集内容。
• Key-Value Store - 非结构化/文件存储（屏幕截图、HTML、OUTPUT）。
• Actor Task - 为运行 Actor 保存的参数化配置。
• Apify Store - Actor 市场，地址为 https://apify.com/store.md。
• Apify Console - 网页 UI，地址为 https://console.apify.com。
• Compute Unit (CU) - 计费单位：内存（MB）x 持续时间（小时）。
• Server Actor - 作为随时就绪的 HTTP 服务运行并拥有稳定专属 URL 的 Actor（API 和文档中可能仍称为 Standby）。你发送请求后，结果会在响应中返回——无需启动运行，也无需读取数据集。

更多术语（build、request queue、proxy、定价模型）：https://docs.apify.com/llms.txt。

规划时使用 Apify MCP 获取实时信息

Apify MCP 服务是在集成设计期间研究 Actor、架构、定价和文档的最快方式。请参阅 https://docs.apify.com/integrations/mcp（追加 .md 可获取 Markdown 版本）。

如果此环境中已提供 Apify MCP 工具，请使用它们：

• search-actors - 按平台/产品关键词查找 Actor（按产品名称搜索，而不是按最终目标搜索）。
• fetch-actor-details - 在将某个 Actor 的形态纳入集成之前，先查看其输入架构、输出格式、README 和定价。
• search-apify-docs / fetch-apify-docs - 获取相关文档页面。

匿名发现工具集（search-actors、fetch-actor-details、search-apify-docs、fetch-apify-docs）无需账户即可使用，因此即使开发者尚未连接其令牌，你也可以进行研究。

选择你的集成形态

根据你要集成到的产品，准确阅读一个参考文件。每份参考文件都包含针对特定类别的 UX 设计、标准能力矩阵和完成标准清单。

产品形态	示例	阅读
工作流自动化平台	Zapier、n8n、Make、Pipedream、Activepieces	references/workflow-automation.md
AI Agent 插件（编码 Agent 或运行框架）	Cursor、Claude Code、Codex、GitHub Copilot（编码 Agent）；OpenClaw 风格的运行时、Hermes 风格的运行框架（运行框架）	references/ai-harness-plugin.md
AI 框架包（面向大模型框架的 PyPI/npm 包）	LangChain、LlamaIndex、Haystack、Vercel AI SDK	references/ai-framework-package.md
应用集成（直接客户端）	通过 apify-client 或 REST 调用 Actors 的后端服务、定时任务、产品功能	references/sdk-integration.md

路径相对于此技能文件夹。如果你的产品横跨两种形态（例如，构建在框架包之上的 AI 运行框架），请阅读两份文件——两者的规则可以组合使用。AI Agent 插件参考文件涵盖了两种权衡各异的方案：面向能够使用技能和 MCP 的编码 Agent 的轻量级技能 + MCP 套件，以及面向 OpenClaw/Hermes 风格运行框架的自定义工具注册插件。

跨领域设计规则（适用于所有集成类型）

这些不变规则提取自所有现有的 Apify 集成。无论集成形态如何，都应遵循这些规则。

术语保持一致

根据 Apify 的领域模型（Actor / Run / Dataset / KV Store / Task）设计集成资源。从 Apify Console 来的用户应能找到名称相同、概念一致的内容。

异步运行流程与有界轮询

Actor 的运行时间可能从几秒到几小时不等。请使用异步流程；除短时任务外，切勿使用 300 秒同步端点：

POST /v2/actors/{actorId}/runs            -> start, return runId
GET  /v2/actor-runs/{runId}               -> poll until terminal status
GET  /v2/datasets/{datasetId}/items       -> fetch results on SUCCEEDED

轮询必须有边界：使用运行自身的 timeoutSecs 加上宽限缓冲时间，并设置绝对上限作为回退。切勿使用 while (true)。如果状态尚未终止，请显示运行 ID，以便用户/Agent 再次轮询或检查失败情况。

将成本视为一等事项

每条启动运行的路径都必须提供成本控制。标准控制项为 maxTotalChargeUsd（在大多数定价模式下限制运行的总费用）和 maxItems（在按结果收费的 Actor 上限制计费项目数）。将它们作为选项 / 查询参数传递，绝不要作为 Actor 输入——放在输入中时，它们要么是 Actor 声明的字段，要么就是无效值。0 / 空值 / null 表示无限制。对于面向大模型的集成，上限由开发者控制，大模型无法扩大上限。Server Actor 请求（例如下文的 Web Fetch）不会启动运行，因此不接受这两个选项。

归因请求头

在每个出站请求中添加集成请求头，以便 Apify 归因流量：x-apify-integration-platform: <your-platform>。当请求由 AI 工具驱动（而非 UI 中的用户）时，还需发送 x-apify-integration-ai-tool: true。如果集成是使用此技能构建的，请添加 x-apify-integration-origin: apify-integration-development-skill，以便 Apify 区分由技能生成的集成和自定义集成。一行配置，大幅提升遥测效果。

身份验证

• 浏览器 / 面向消费者（由用户完成登录）：使用带 PKCE 的 OAuth2。不要索要原始令牌。
• 无头 / 服务端 / CI（没有用户在场）：使用 API 令牌作为 Authorization: Bearer <APIFY_TOKEN>，存储在环境变量或密钥管理器中，绝不硬编码或记录日志。

两种方式都适用——应根据身份验证时是否有用户在场来选择，而不是选择更容易的方式。

集中式 HTTP 层

凭据层和 HTTP 层共用一个基础 URL 常量。Actor 服务运行在独立主机上（https://web-fetch.apify.actor）——应通过同一层路由，使身份验证和归属标头仍然生效。遇到 429 和 5xx 时采用指数退避重试。网络错误时绝不重试非幂等的 POST /runs——重复启动 Actor 运行会产生真实费用和副作用。这是 HTTP 层最重要的正确性不变量。

错误分类

将 Apify 错误映射到宿主平台的错误类别（可重试、身份验证或永久性错误）。显示 API 的实际错误文本，而不是通用 HTTP 消息。对于权限审批失败（需要获得明确批准才能使用完全权限的 Actor），在验证审批 URL 是绝对 http(s) URL 后，将其一并返回。对于大模型消费者，应将错误作为数据返回（JSON 错误对象），绝不抛出异常——模型需要读取错误并据此推理。

使用 Webhook 处理运行结束事件，而非轮询

如果宿主支持接收 Webhook，应注册一个 Apify Webhook，并将其限定到 actorId 或 actorTaskId，同时指定用户选择的终止状态。注册操作必须幂等（重新激活工作流时不应创建重复的 Webhook），并持久化 Webhook ID，以便停用时清理。还应始终提供示例数据或回退数据，让用户无需等待真实运行即可测试触发器。

宿主允许时，从 OpenAPI 生成

如果宿主平台可以根据 OpenAPI 规范生成 UI 字段，就使用 Apify 的规范（https://apify.com/openapi.json）和标签允许列表。仅手写规范无法表达的内容：便捷封装、账单上限字段，以及精简的 AI 工具输出契约。

通用运行之外，还要提供高层便捷操作

通用的“运行 Actor”适合高级用户。对于常见场景，还应添加一些带有明确用途的高层操作，让非高级用户使用仅含 2 个字段的表单，而不是完整的 Actor 配置。典型操作是 Web Fetch：输入一个 URL，返回页面内容；它基于 apify/web-fetch Server Actor——向 POST https://web-fetch.apify.actor/ 发送 {"url": "...", "formats": ["markdown"]}，即可在响应中获得内容。它不会启动运行，因此上述运行规则（异步流程、轮询、maxTotalChargeUsd）不适用；每次成功请求的成本是一个 fetch 事件。以下三点务必处理正确：始终发送 formats；检查 fetch.httpStatusCode（HTTP 200 仅表示 Web Fetch 本身成功）；处理两种错误格式——Actor 返回的扁平格式 {code, error}，以及平台返回的嵌套格式 {error: {message}}——且不要对其 502/504 自动重试。完整契约：https://apify.com/apify/web-fetch.md。不要通过设置 maxCrawlDepth: 0 的爬虫运行来实现此功能——这属于过时的“抓取单个 URL”模式。

测试与发布

保留两种测试模式：模拟测试（环境隔离，无需凭据）和实时 E2E 测试（真实 API，由 CI 控制是否执行）。通过宿主平台的 CI，根据 Git 标签 / GitHub Releases 自动发布。如果发布工作流会管理版本或变更日志，绝不要手动编辑。

评审时应拒绝的主要反模式

1. 网络错误时重试 POST /runs——会重复产生付费运行。
2. 使用无界的 while (true) 轮询——会无限占用宿主资源。
3. 将 maxTotalChargeUsd / maxItems 放入 Actor 输入而非选项中——这不会形成上限，却不会显式报错。
4. 将完整数据集倾倒到大模型上下文中，却不限制大小或隔离不可信内容——会导致提示词注入和上下文膨胀。
5. 为 LLM Agent 提供一个庞大的工具列表——工具超过约 8 个后，路由准确率会下降；应精选子集。
6. 显示原始 HTTP 状态码 / 消息，而不是 Apify 的实际错误文本——用户无法根据“400”采取行动。

每个集成都需要的最精简 API

用途	方法 + 路径
启动 Actor 运行	POST /v2/actors/{actorId}/runs
启动 Task 运行	POST /v2/actor-tasks/{taskId}/runs
轮询运行	GET /v2/actor-runs/{runId}
列出运行	GET /v2/actor-runs
数据集条目	GET /v2/datasets/{datasetId}/items
KV 记录	GET /v2/key-value-stores/{storeId}/records/{key}
设置 KV 记录	PUT /v2/key-value-stores/{storeId}/records/{key}
搜索存储	GET /v2/store
Webhook 增删改查	POST/GET/DELETE /v2/webhooks
验证令牌 / 当前用户	GET /v2/users/me
获取单个 URL（Web Fetch，Server Actor）	POST https://web-fetch.apify.actor/

REST 参考文档：https://docs.apify.com/api/v2。OpenAPI 规范：https://apify.com/openapi.json。

工作流程

1. 获取 https://apify.com/agents.md 并熟悉其中的模型。
2. 选择上述集成形态，并阅读对应的参考文件。
3. 使用 Apify MCP（如可用）调研该集成将提供的具体 Actors、架构和定价。
4. 为所选类别起草能力矩阵（每份参考文档都包含一份）和 UX 规范（资源 -> 操作 -> 字段 -> 错误）。
5. 按照参考文档中的类别专属规则搭建集成。
6. 根据该参考文档末尾的完成定义清单进行验证。

值得研究的参考实现

每个类别都有真实的公开集成——如有疑问，请阅读其源代码：

• 工作流自动化：@apify/n8n-nodes-apify（npm）、Apify Zapier 应用。
• AI Agent 插件（编码 Agent）：面向 Cursor、Claude Code、Copilot 及类似工具发布的 Apify 插件包（MCP 服务 + 技能 + 路由器 + 斜杠命令）。
• AI Agent 插件（运行框架）：apify-hermes-agent-plugin（PyPI）、@apify/apify-openclaw-plugin。
• AI 框架包：langchain-apify（PyPI）。
• 应用集成：参见 references/sdk-integration.md，了解在 JS/TS、Python 和 REST 中使用 apify-client 的标准方式。

集成问题支持：[email protected]。在构建过程中，如需设计指导，请联系我们；发布后，也可联系我们进行审核和测试——在集成面向用户之前，我们会验证其能力范围、成本控制、错误处理和署名信息。