cargo-connection

Cargo CLI — 连接

连接器与集成管理：列出连接器、发现可用集成，以及管理已通过身份验证的连接器实例。

完整的 JSON 响应结构请参阅 references/response-shapes.md。 常见错误及其修复方法请参阅 references/troubleshooting.md。 连接器的创建、读取、更新、删除和发现示例请参阅 references/examples/connectors.md。 可用集成列表和 OAuth 流程示例请参阅 references/examples/integrations.md。 有关第三方连接器在工作流中的速率限制处理和重试配置，请参阅 cargo-orchestration/references/polling.md 和 cargo-orchestration/references/troubleshooting.md。原生集成没有速率限制。

初始化

已登录（cargo-ai whoami 返回工作区）？请跳到下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 输出到标准输出；失败时会以非零状态码退出，并返回 {"errorMessage": "..."}。任何会创建运行或批次的操作都是异步的——传入 --wait-until-finished，或轮询对应的 get 命令。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定、令牌作用域和仅限管理员使用的功能说明。

关键概念

集成： 外部服务类型（例如 HubSpot、Clearbit、Salesforce）。集成定义可用的操作。

连接器： 已通过身份验证的集成实例。一个集成可以有多个连接器（例如两个不同的 HubSpot 账户）。工作流节点图中引用的就是连接器。

先发现资源

要找某个操作？请搜索，不要浏览目录。 两种关键词 搜索即可覆盖所有内容，而且都比翻页查看 integration list 或 读取完整的 integration get 负载更高效：

cargo-ai orchestration action list <query>                # START HERE — connector + native + tools + agents.
                                                          # Returns a ready-to-run action object (connectorUuid
                                                          # resolved) and the action's credit costs.
cargo-ai connection action search <query> --credits-only  # connector catalog only, but filters by
                                                          # "is it paid", which `action list` cannot.

需要的是集成本身而非操作时，才使用目录命令——例如查看其身份验证字段、提取器，或已选定操作的完整输入架构：

cargo-ai connection connector list                        # all authenticated connectors
cargo-ai connection integration list                      # all available integration types
cargo-ai connection integration list --search "hubspot"   # search by name
cargo-ai connection integration get <slug>                # one integration's actions + input schemas
cargo-ai connection native-integration get                # built-in Cargo actions only (NOT third-party)

默认情况下，已弃用的集成不会显示在目录中。 除非传入 --is-deprecated true，否则 integration list、action list 和 action search 都会排除它们；integration get <slug> 则始终会返回指定集成，并标记 isDeprecated: true，且显示名称以 (deprecated) 结尾。它们已无法再建立连接。现有连接器仍可使用，但切勿将新工作流连接到它们。CLI 1.0.92 弃用了两个集成，其中包括可自我引用的 cargo 集成。请读取该标记，而不是维护清单：对于通过浏览而非 action list 找到的集成，提出建议前先检查 isDeprecated。

该用哪种操作搜索？

	orchestration action list	connection action search
覆盖范围	连接器、原生操作、工具、Agent	仅限连接器目录
返回内容	可运行的 action 对象，包含 connectorUuid、工作区连接器、credits，并支持自动补全	integrationSlug + actionSlug、类别、credits——需要自行组装操作
筛选条件	--kind、--integration-slug、--category、--is-deprecated、--limit	--category、--integration、--credits-only、--is-deprecated、--limit
所需版本	CLI ≥ 1.0.66	CLI ≥ 1.0.36

默认使用 action list——它会直接提供可执行的内容。 遇到只有 action search 才能回答的问题时，再切换到它：哪些付费 操作符合条件？（--credits-only）。两者的排序规则相同：操作 slug 或名称命中的结果优先于集成命中的结果， 集成命中的结果又优先于描述命中的结果；同时，查询中的所有词都必须匹配。

integration get 与 native-integration get

这两条命令返回的操作集合不同，不能互换使用：

命令	第三方服务操作（HubSpot、Salesforce、Clearbit 等）	Cargo 内置操作（HTTP、转换、实用工具）	使用场景
integration get <slug>	✓	✗	需要特定第三方服务的操作时——HubSpot、Salesforce、Clearbit 等服务请使用此命令。
native-integration get	✗	✓	需要不属于任何特定第三方连接器的 Cargo 原生功能时

**示例：**要查找 HubSpot 专属操作，请使用 integration get hubspot；native-integration get 不会返回这些操作。

快速参考

cargo-ai connection connector list --integration-slug <slug>
cargo-ai connection connector create --integration-slug <slug>   # hosted form in the browser
cargo-ai connection connector create --integration-slug <slug> --slug <slug> --name <name> --config '<json>'
cargo-ai connection connector update --uuid <uuid> --name <name>
cargo-ai connection connector remove <connector-uuid>
cargo-ai connection connector get <connector-uuid>
cargo-ai connection connector autocomplete --connector-uuid <uuid> --slug <slug> --params '<json>'
cargo-ai connection connector get-dynamic-schema --connector-uuid <uuid> --slug <slug> --params '<json>'
cargo-ai connection custom-integration list
cargo-ai connection integration list
cargo-ai connection integration get <slug>
cargo-ai connection integration get-documentation <slug>
cargo-ai connection native-integration get

连接器

连接器是经过身份验证的外部服务连接。

# List all connectors
cargo-ai connection connector list

# Create a connector: no flags beyond --integration-slug opens the hosted form and waits
cargo-ai connection connector create --integration-slug clearbit

# Non-interactive: --config (shape depends on the integration) plus --slug and --name
cargo-ai connection connector create \
  --integration-slug clearbit \
  --slug clearbit_production \
  --name "Clearbit - Production" \
  --config '<integration-specific JSON>'

# Update a connector
cargo-ai connection connector update --uuid <connector-uuid> --name "Clearbit - Staging"

# Throttle and cache a connector (on create or update)
cargo-ai connection connector update --uuid <connector-uuid> \
  --rate-limit '{"unit":"minute","max":100,"strategy":"spread"}' \
  --cache-ttl-milliseconds 86400000

# Remove a connector
cargo-ai connection connector remove <connector-uuid>

# Check if a connector slug is taken
cargo-ai connection connector exists-by-slug --slug clearbit_production

**注意：**使用 --config 时，必须指定 --slug（唯一标识符）和 --name（显示名称）；不使用 --config 时则不能指定（托管表单会要求填写）。对于基于 OAuth 的集成，需通过 connection integration complete-oauth 单独完成身份验证流程。

速率限制和缓存按连接器分别设置。--rate-limit 接受 {"unit": "second" | "minute" | "hour" | "day", "max": <n>, "strategy": "spread" | "burst"}——spread 会均匀调节调用频率，burst 会先放行调用，然后等待；burst 与 "second" 搭配时会被拒绝。如果多个 play 共用一个 API 密钥，请将其设为低于提供商自身的上限。--cache-ttl-milliseconds 会让 TTL 期间内采用完全相同计算配置的工作流节点返回缓存结果，而不是调用提供商；且这类调用不会消耗提供商额度。此选项仅对操作兼容缓存的集成生效；其他情况下会被忽略。对于数据丰富连接器，将 TTL 设为一天即可免费对重叠批次进行去重。

集成

集成定义可用的服务及其连接器操作。

# List all available integrations
cargo-ai connection integration list

# Filter by category
cargo-ai connection integration list --category enrichment

# Search by name
cargo-ai connection integration list --search "hubspot"

# Find by exact slug(s)
cargo-ai connection integration list --slugs clearbit

# Only integrations that have actions (usable in workflow nodes)
cargo-ai connection integration list --has-actions true

# Only integrations that have extractors (can sync data into models)
cargo-ai connection integration list --has-extractors true

# Get built-in Cargo actions and extractors (NOT third-party connector actions)
cargo-ai connection native-integration get

集成类别：engagement、marketing、sales、finance、analytics、freeform、success、support、enrichment、storage、custom。

使用 integration get <slug> 可发现特定第三方服务（例如 HubSpot、Salesforce）的所有可用操作。native-integration get 仅用于 Cargo 内置操作——它不会返回 HubSpot 或其他服务专属操作。在工作流节点图中，操作通过 actionSlug 引用（参见 cargo-orchestration 技能的 references/nodes.md）。

自定义集成

自定义集成是由你托管的集成：一个使用 Cargo 集成协议的 HTTP 服务器——GET /manifest、POST /actions/<slug>/execute、POST /extractors/<slug>/fetch（以及 /count）、POST /autocompletes/<slug>、POST /dynamicSchemas/<slug>——并注册到工作区，使其操作和提取器显示在目录项目旁。它可以运行在你自己的服务器上（external），也可以运行在 Cargo Hosting worker 上（worker；使用 cargo-ai hosting worker init <dir> --template custom-integration 创建脚手架）。

cargo-ai connection custom-integration create --kind external --base-url https://integrations.example.com
cargo-ai connection custom-integration create --kind worker --worker-uuid <worker-uuid>
cargo-ai connection custom-integration list
cargo-ai connection custom-integration get <uuid>
cargo-ai connection custom-integration update --uuid <uuid> --base-url https://new.example.com   # or --worker-uuid; kind cannot change
cargo-ai connection custom-integration remove <uuid>

注册会为集成分配一个自动生成的 slug；与其他集成一样，使用 connector create --integration-slug <that slug> 为其创建连接器。external 的基础 URL 必须可从公网访问——私有地址和环回地址会被拒绝（unsafeOutboundUrl），因此本地服务器需要使用隧道。若此工作区中不存在对应 worker，worker 会失败并返回 workerNotFound。

连接器自动补全——获取操作字段的可用值

某些操作字段不接受自由输入——必须从连接器动态获取其允许的值。检查操作配置（通过 integration get <slug> 或 native-integration get）时，请同时查看 uiSchema 和 jsonSchema。如果某个字段的 uiSchema 包含 "ui:widget": "IntegrationAutocompleteWidget"，则必须使用 connector autocomplete 获取该字段的有效值。

如何检测自动补全字段

当操作的 config 如下所示时：

{
  "jsonSchema": {
    "type": "object",
    "properties": {
      "objectType": { "type": "string", "description": "The object type" }
    }
  },
  "uiSchema": {
    "objectType": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listObjects",
        "allowRefresh": true
      }
    }
  }
}

objectType 字段需要自动补全。ui:options.slug（"listObjects"）就是传给 connector autocomplete 的自动补全 slug。

如何调用 connector autocomplete

cargo-ai connection connector autocomplete \
  --connector-uuid <connector-uuid> \
  --slug <autocomplete-slug> \
  --params '{}'

标志	必填	说明
--connector-uuid	是	用于自动补全的连接器 UUID
--slug	是	来自 uiSchema[field]["ui:options"].slug 的自动补全 slug
--params	是	参数的 JSON 对象（无需参数时使用 {}）
--value	否	用于筛选结果的搜索字符串
--refresh	否	绕过缓存并获取最新结果

使用参数进行自动补全

某些自动补全字段依赖于另一个字段的值。这由 ui:options 中的 params 对象标明：

{
  "uiSchema": {
    "objectType": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": { "slug": "listObjects" }
    },
    "propertyName": {
      "ui:widget": "IntegrationAutocompleteWidget",
      "ui:options": {
        "slug": "listObjectProperties",
        "params": { "objectType": "$this.$parent.objectType" }
      }
    }
  }
}

这里，propertyName 依赖于所选的 objectType。将 $this.$parent... 表达式替换为你选择的实际值：

# 1. First, get the list of object types
cargo-ai connection connector autocomplete \
  --connector-uuid <uuid> --slug listObjects --params '{}'

# 2. Then, get properties for the chosen object type
cargo-ai connection connector autocomplete \
  --connector-uuid <uuid> --slug listObjectProperties \
  --params '{"objectType": "contacts"}'

响应格式

{
  "results": [
    { "label": "Contacts", "value": "contacts" },
    { "label": "Companies", "value": "companies" },
    { "label": "Deals", "value": "deals" }
  ]
}

在节点配置中使用 value 字段。label 是便于人类阅读的显示名称。结果还可能包含可选的 description 和 parent 字段。

动态 schema — 形状取决于另一个值的字段

如果某个字段的 uiSchema 包含 "ui:widget": "DynamicSchemaWidget"，则该字段没有固定 schema：其子字段会在配置时由连接器提供（例如，HubSpot 的表单同意选项取决于所选的 formId）。按照与自动补全相同的方式获取 schema——使用 ui:options.slug 及其 params，并将 $this.$parent… 引用替换为你选择的值：

cargo-ai connection connector get-dynamic-schema \
  --connector-uuid <uuid> --slug getConsentOptions --params '{"formId":"<form-id>"}'

--slug 是 ui:options 中的 dynamic-schema slug，而不是操作 slug（CLI 1.0.128 之前的帮助信息曾称其为“action slug”）。响应包含 schema（该字段的 JSON Schema）和 uiSchema；请据此填写字段。未通过验证的参数会返回空结果（没有 schema），而不是错误，因此空响应通常表示参数缺失或名称错误。

端到端示例：配置 HubSpot 操作

# 1. Find your HubSpot connector UUID
cargo-ai connection connector list --integration-slug hubspot

# 2. Get HubSpot actions and inspect their config + uiSchema
cargo-ai connection integration get hubspot
# → The "findRecords" action has objectType with autocomplete slug "listObjects"

# 3. Fetch available object types
cargo-ai connection connector autocomplete \
  --connector-uuid <hubspot-connector-uuid> \
  --slug listObjects --params '{}'
# → Returns: contacts, companies, deals, tickets, etc.

# 4. Fetch properties for the chosen object type
cargo-ai connection connector autocomplete \
  --connector-uuid <hubspot-connector-uuid> \
  --slug listObjectProperties \
  --params '{"objectType": "contacts"}'
# → Returns: email, firstname, lastname, phone, etc.

# 5. Use these values in your workflow node config

在工作流中使用连接器操作

连接器操作作为节点用于工作流图中。使用某个操作的方法如下：

# 1. Find your connector UUID
cargo-ai connection connector list
# → Filter the output by integrationSlug to find the right connector

# 2. Discover the action — search first, and only then read its schema
cargo-ai orchestration action list <keywords> --integration-slug <integration-slug>
cargo-ai connection integration get <integration-slug>
# → actions are keyed by actionSlug, with config.schema (input) for each
# → many actions also carry output.schema — the JSON Schema of what the action
#   emits; use it to wire downstream nodes instead of guessing (absent on some actions)
# → Or use get-documentation for a plain text overview
# → Or use native-integration get for built-in Cargo actions (not third-party)

# 3. Reference the connector and action in a node graph
# See cargo-orchestration references/nodes.md for the full node syntax

读取操作的输入架构——以及输入的传递位置

操作的输入字段位于 integration get <slug> 输出中的 actions.<slug>.config.schema（config.jsonSchema 是为表单 UI 添加了修饰的同一架构）。调用操作前请先阅读，不要猜字段名。

# the required input fields for an action:
cargo-ai connection integration get linkedin \
  | jq '.integration.actions.connectProfile.config.schema'
# → required: linkedinProfileUrl, identityIds

两个容易踩坑的地方：

• 对于顶层操作（action execute / execute-batch），输入值要放在 --data 中，而不是操作的 config 中。 config.schema 描述的字段就是 --data 的负载；操作定义本身根本没有 config 键。放错位置不再会明确报错：旧版后端会拒绝调用，并返回 A top-level action does not use action.config; pass the action's inputs via data instead.；新版后端会在接收时移除 config，因此其中的输入不会传递过去——如果缺少第一个必填字段，会在运行前拒绝调用（invalidData）；如果没有必填字段，则会运行，但不执行任何操作，且绝不会提示 config 相关信息。如果操作无明显原因就返回空结果或被拒绝，请检查输入是否放在 --data 中。--data 中的键若拼写错误，会在运行前被拒绝（Unknown field: <key>）。（在工作流的节点图中，相同字段要放在节点的 config 中——参见 cargo-orchestration/references/nodes.md。"--data，而不是 config" 规则仅适用于 action execute/execute-batch。）
• 有些输入必须先通过自动补全解析。 如果字段的 uiSchema 带有 IntegrationAutocompleteWidget，请使用 connector autocomplete（见上文）获取其值。值得注意的是，LinkedIn 互动/提取操作（connectProfile、visitProfile、extractEventAttendees、extractProfileViewers）需要 identityIds——即执行操作的已连接账户——并通过 listIdentityIds 自动补全进行解析。如果出现 must match format "uuid" 错误，说明缺少该身份标识。

连接器节点示例（Clearbit 公司信息丰富）：

{
  "uuid": "node-uuid",
  "slug": "enrich",
  "kind": "connector",
  "integrationSlug": "clearbit",
  "actionSlug": "enrichCompany",
  "connectorUuid": "<clearbit-connector-uuid>",
  "config": {
    "domain": {
      "kind": "templateExpression",
      "expression": "{{nodes.start.domain}}",
      "instructTo": "none",
      "fromRecipe": false
    }
  },
  "childrenUuids": ["end-node-uuid"],
  "fallbackOnFailure": false,
  "position": { "x": 0, "y": 166 }
}

帮助

每条命令都支持 --help：

cargo-ai connection connector list --help
cargo-ai connection connector create --help
cargo-ai connection integration list --help