用 Cargo CLI 连接外部系统并解析工作流所需的…

当需要把 Cargo 连接到 HubSpot、Salesforce 等外部服务，认证连接器、浏览集成目录，并找出工作流节点所需的 connectorUuid 和 actionSlug 时使用。

适用场景

解决思路

1. 先确认已登录：运行 `cargo-ai whoami` 返回工作区则跳过引导步骤；否则执行 `npm install -g @cargo-ai/cli`（若无全局安装则在每条命令前加 `npx @cargo-ai/cli`），再运行 `cargo-ai login --email you@company.com`（邮件验证码、无需浏览器，首次使用会创建账号），也可用 `--oauth`（浏览器）或 `--token <api-token>`（CI）；写入前用 `cargo-ai whoami` 确认当前工作区。
2. 所有命令向 stdout 输出 JSON，失败时以非零退出并返回 `{"errorMessage": "..."}`；任何创建 run 或 batch 的操作都是异步的，需传 `--wait-until-finished` 或轮询对应的 `get`。
3. 找 action 时优先搜索而非浏览目录：先运行 `cargo-ai orchestration action list <query>`（覆盖 connector、native、tools、agents，返回可直接运行的 action 对象并已解析 connectorUuid，还带 credit 成本）；需要按类别或是否付费过滤时用 `cargo-ai connection action search <query> --credits-only`。
4. 需要的是 integration 本身（认证字段、extractors，或已选定 action 的完整输入 schema）时再用目录命令：`cargo-ai connection connector list`、`cargo-ai connection integration list`、`cargo-ai connection integration list --search "hubspot"`、`cargo-ai connection integration get <slug>`、`cargo-ai connection native-integration get`。
5. 注意已弃用的 integration 仍会出现在目录中：`integration list` 会返回 `isDeprecated: true` 且显示名以 `(deprecated)` 结尾；已有 connector 仍可用，但不要给新工作流接上它们，提案前先读 `isDeprecated` 标志。
6. 区分 `integration get <slug>` 与 `native-integration get`：前者返回第三方服务（HubSpot、Salesforce、Clearbit 等）的 actions，后者只返回 Cargo 内置 actions（HTTP、transforms、utilities），二者不可互换；找 HubSpot 专属 action 必须用 `integration get hubspot`。
7. 管理 connector：`cargo-ai connection connector list --integration-slug <slug>`、`cargo-ai connection connector create --integration-slug <slug> --slug <slug> --name <name>`（创建时必须同时提供唯一的 `--slug` 和显示名 `--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 exists-by-slug --slug <slug>`；OAuth 类 integration 的认证流程需另行通过 `connection integration complete-oauth` 完成。
8. 浏览 integration 目录时可用过滤参数：`--category enrichment`、`--search "hubspot"`、`--slugs clearbit`、`--has-actions true`（可用于工作流节点）、`--has-extractors true`（可同步数据到模型）；integration 类别包括 engagement、marketing、sales、finance、analytics、freeform、success、support、enrichment、storage、custom。
9. 识别需要 autocomplete 的字段：查看 action 配置时同时看 `uiSchema` 和 `jsonSchema`，若某字段的 `uiSchema` 含 `"ui:widget": "IntegrationAutocompleteWidget"`，则该字段的合法值必须通过 `connector autocomplete` 动态获取，`ui:options.slug` 即为要传给命令的 autocomplete slug。
10. 调用 autocomplete：`cargo-ai connection connector autocomplete --connector-uuid <connector-uuid> --slug <autocomplete-slug> --params '{}'`；`--connector-uuid`、`--slug`、`--params` 必填（无参数时传 `{}`），可选 `--value`（搜索过滤）和 `--refresh`（绕过缓存）。
11. 处理带依赖参数的 autocomplete：若 `ui:options` 中有 `params` 对象（如 `{"objectType": "$this.$parent.objectType"}`），需先把 `$this.$parent...` 表达式替换为实际选定的值，再分步调用——先取父字段列表（如 `--slug listObjects --params '{}'`），再用选定值取子字段（如 `--slug listObjectProperties --params '{"objectType": "contacts"}'`）。
12. 使用 autocomplete 响应：结果形如 `{"results": [{"label": "Contacts", "value": "contacts"}, ...]}`，在节点配置中使用 `value` 字段，`label` 仅供人阅读，结果还可能含可选的 `description` 和 `parent` 字段。
13. 端到端配置示例（HubSpot）：先用 `connector list --integration-slug hubspot` 找到 connector UUID；再用 `integration get hubspot` 查看 actions 及其 config + uiSchema（如 `findRecords` 的 objectType 使用 autocomplete slug `listObjects`）；然后 `connector autocomplete --slug listObjects --params '{}'` 取对象类型；再 `connector autocomplete --slug listObjectProperties --params '{"objectType": "contacts"}'` 取属性；最后把这些值填入工作流节点配置。
14. 在工作流中使用 connector action：先用 `connector list` 按 integrationSlug 过滤找到 connector UUID；再用 `orchestration action list <keywords> --integration-slug <integration-slug>` 或 `connection integration get <integration-slug>` 发现 action（actions 以 actionSlug 为键，含 `config.jsonSchema` 输入 schema，许多 action 还带 `output.schema` 描述输出，可用于连接下游节点，部分 action 没有）；也可用 `get-documentation` 获取纯文本概览，或用 `native-integration get` 获取 Cargo 内置 action；最后按 `cargo-orchestration` 的 `references/nodes.md` 中的节点语法引用 connector 和 action。
15. 调用 action 前先读输入 schema：输入字段位于 `integration get <slug>` 输出的 `actions.<slug>.config.schema`（`config.jsonSchema` 是同一 schema 的 UI 装饰版），不要猜字段名；例如 `cargo-ai connection integration get linkedin | jq '.integration.actions.connectProfile.config.schema'` 可看到 required 字段 `linkedinProfileUrl`、`identityIds`。
16. 避免两个易错点：其一，顶层 action（`action execute` / `execute-batch`）的输入值要放在 `--data` 而非 action 的 `config`，放错位置在新版后端会被静默丢弃并以「缺少必填字段」或空结果报错，若 action 无故返回空先检查输入是否在 `--data`（工作流节点图内这些字段才放在节点的 `config`）；其二，部分输入必须先经 autocomplete 解析，如 LinkedIn 的 engagement/extraction actions（`connectProfile`、`visitProfile`、`extractEventAttendees`、`extractProfileViewers`）需要 `identityIds`（执行动作的已连接账号），通过 `listIdentityIds` autocomplete 解析，报 `must match format "uuid"` 即表示缺少该 identity。
17. 参考文档：`references/response-shapes.md`（完整 JSON 响应结构）、`references/troubleshooting.md`（常见错误与修复）、`references/examples/connectors.md`（connector CRUD 与发现示例）、`references/examples/integrations.md`（列出可用 integration 与 OAuth 流程）；第三方 connector 的限流处理与重试配置见 `cargo-orchestration/references/polling.md` 和 `cargo-orchestration/references/troubleshooting.md`（原生 integration 无限流）。
18. 每条命令都支持 `--help`，如 `cargo-ai connection connector list --help`、`cargo-ai connection connector create --help`、`cargo-ai connection integration list --help`。

适用边界 · 注意事项

• 在为 GTM 任务选择 enrichment 供应商时不要用本技能，应改用 cargo-gtm 及其 provider playbooks。
• 不要用 `native-integration get` 查找 HubSpot、Salesforce 等第三方服务专属 action，它只返回 Cargo 内置 action。
• 不要给新工作流接上 `isDeprecated: true` 的 integration（已有 connector 仍可继续工作）。