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）時，請查看 jsonSchema 旁的 uiSchema。如果某欄位的 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。

如何呼叫 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. 首先，取得物件類型列表
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