cargo-connection

Cargo CLI — 连接

连接器和集成管理：列出连接器，发现可用的集成，以及管理已认证的连接器实例。

完整的 JSON 响应结构请参见 references/response-shapes.md。
常见错误及解决方法请参见 references/troubleshooting.md。
连接器的 CRUD 和发现示例请参见 references/examples/connectors.md。
列出可用集成和 OAuth 流程示例请参见 references/examples/integrations.md。
关于第三方连接器的速率限制处理和重试配置，请参见 cargo-orchestration/references/polling.md 和 cargo-orchestration/references/troubleshooting.md。原生集成没有速率限制。

关键概念

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

连接器： 集成的已认证实例。一个集成可以有多个连接器（例如两个不同的 HubSpot 账户）。连接器是你在工作流节点图中引用的对象。

前提条件

安装、登录（--oauth / --token）、JSON 输出约定和错误格式请参见 ../cargo/references/prerequisites.md。在运行以下任何命令之前，请使用 cargo-ai whoami 验证会话。

首先发现资源

cargo-ai connection connector list                        # 所有已认证的连接器
cargo-ai connection integration list                      # 所有可用的集成类型
cargo-ai connection integration list --search "hubspot"   # 按名称搜索
cargo-ai connection integration get <slug>                # 第三方特定操作（例如 HubSpot）
cargo-ai connection native-integration get                # 仅内置 Cargo 操作（非第三方）

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> --slug <slug> --name <name>
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 integration list
cargo-ai connection integration get <slug>
cargo-ai connection integration get-documentation <slug>
cargo-ai connection native-integration get

连接器

连接器是到外部服务的已认证连接。

# 列出所有连接器
cargo-ai connection connector list

# 创建连接器
cargo-ai connection connector create \
  --integration-slug clearbit \
  --slug clearbit_production \
  --name "Clearbit - Production"

# 更新连接器
cargo-ai connection connector update --uuid <connector-uuid> --name "Clearbit - Staging"

# 删除连接器
cargo-ai connection connector remove <connector-uuid>

# 检查连接器 slug 是否已被占用
cargo-ai connection connector exists-by-slug --slug clearbit_production

注意： 创建连接器需要 --slug（唯一标识符）以及 --name（显示名称）和 --integration-slug。对于基于 OAuth 的集成，认证流程通过 connection integration complete-oauth 单独完成。

集成

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

# 列出所有可用集成
cargo-ai connection integration list

# 按类别过滤
cargo-ai connection integration list --category enrichment

# 按名称搜索
cargo-ai connection integration list --search "hubspot"

# 按精确 slug 查找
cargo-ai connection integration list --slug clearbit

# 仅包含有操作的集成（可在工作流节点中使用）
cargo-ai connection integration list --has-actions true

# 仅包含有提取器的集成（可将数据同步到模型中）
cargo-ai connection integration list --has-extractors true

# 获取内置 Cargo 操作和提取器（非第三方连接器操作）
cargo-ai connection native-integration get

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

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

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

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

如何检测自动补全字段

当操作的配置如下所示时：

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

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

如何调用连接器自动补全

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. 首先，获取对象类型列表
cargo-ai connection connector autocomplete \
  --connector-uuid <uuid> --slug listObjects --params '{}'

# 2. 然后，获取所选对象类型的属性
cargo-ai connection connector autocomplete \
  --connector-uuid <uuid> --slug listObjectProperties \
  --params '{"objectType": "contacts"}'

响应格式

{
  "results": [
    { "label": "联系人", "value": "contacts" },
    { "label": "公司", "value": "companies" },
    { "label": "交易", "value": "deals" }
  ]
}

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

端到端示例：配置 HubSpot 操作

# 1. 找到你的 HubSpot 连接器 UUID
cargo-ai connection connector list --integration-slug hubspot

# 2. 获取 HubSpot 操作并检查其配置和 uiSchema
cargo-ai connection integration get hubspot
# → "findRecords" 操作具有 objectType，自动补全 slug 为 "listObjects"

# 3. 获取可用的对象类型
cargo-ai connection connector autocomplete \
  --connector-uuid <hubspot-connector-uuid> \
  --slug listObjects --params '{}'
# → 返回：contacts, companies, deals, tickets 等

# 4. 获取所选对象类型的属性
cargo-ai connection connector autocomplete \
  --connector-uuid <hubspot-connector-uuid> \
  --slug listObjectProperties \
  --params '{"objectType": "contacts"}'
# → 返回：email, firstname, lastname, phone 等

# 5. 在工作流节点配置中使用这些值

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

连接器操作在工作流图中用作节点。要使用操作：

# 1. 找到你的连接器 UUID
cargo-ai connection connector list
# → 按 integrationSlug 过滤输出以找到正确的连接器

# 2. 发现集成的可用操作
cargo-ai connection integration get <integration-slug>
# → 操作按 actionSlug 键控，每个操作都有 config.jsonSchema（输入）
# → 许多操作还带有 output.schema — 操作输出的 JSON Schema；
#   用它来连接下游节点，而不是猜测（某些操作上缺失）
# → 或者使用 get-documentation 获取纯文本概述
# → 或者使用 native-integration get 获取内置 Cargo 操作（非第三方）

# 3. 在节点图中引用连接器和操作
# 完整节点语法请参见 cargo-orchestration references/nodes.md

读取操作的输入模式 — 以及输入的位置

操作的输入字段位于 integration get <slug> 输出的 actions.<slug>.config.schema 中（config.jsonSchema 是相同的模式，为表单 UI 装饰）。在调用操作之前请先阅读它 — 不要猜测字段名称。

# 操作的必需输入字段：
cargo-ai connection integration get linkedin \
  | jq '.integration.actions.connectProfile.config.schema'
# → required: linkedinProfileUrl, identityIds

两个注意事项：

• 对于顶层操作（action execute / execute-batch），输入值放在 --data 中，而不是操作的 config 中。 操作定义的 config（{"kind":"connector",…,"config":{}}）保持 {}；config.schema 描述的字段是 --data 负载。将它们放在 config 中会失败，并显示 A top-level action does not use action.config; pass the action's inputs via data instead.（在工作流节点图中，这些相同的字段放在节点的 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