integrate-anything

自助集成

连接到任意外部应用并在其中执行操作。使用 Membrane CLI。

始终通过 Membrane 路由。 不要直接调用供应商 API。Membrane 会通过经过身份验证的连接代理每个请求，并注入正确的身份验证标头，包括自动刷新凭据。

切勿自行处理外部应用凭据。 OAuth 令牌、API 密钥、刷新令牌等均由 Membrane 在服务器端存储和管理。传入 connectionKey（或 connectionId），工具就会代表你调用供应商。

工作流

1. 通过 Membrane 进行身份验证（每台机器只需一次）。
2. 确保已连接到外部应用——查找现有连接、重新连接已断开的连接，或创建新连接。
3. 使用连接执行操作或调用应用的 API。

本技能的其余部分将详细介绍这三个步骤。

身份验证

npx @membranehq/cli login --tenant

--tenant 会获取租户范围的令牌（工作区 + 客户），这样后续命令就无需每次都传入 --workspaceKey 和 --tenantKey。

该命令会打开浏览器。在无头环境中，它会输出一个授权 URL——请让用户打开该链接、完成流程并粘贴返回的代码；然后运行以下命令完成操作：

npx @membranehq/cli login complete <code>

凭据存储在 ~/.membrane/credentials.json 中。后续命令会自动使用这些凭据。

如果使用 npx 不方便，可以全局安装：npm i -g @membranehq/cli@latest，然后直接使用 membrane …。在任何命令中添加 --json，即可获取机器可读的输出。

步骤 1 — 获取连接

1a. 查找现有连接

npx @membranehq/cli connection list --json

每个连接都包含 id、key、integrationKey 和 state。找到目标应用，并根据 state 采取相应操作：

• READY → 使用该连接。跳到步骤 2。

• CLIENT_ACTION_REQUIRED（已断开连接，需要重新进行身份验证）→ 重新连接现有连接，不要创建新连接：

  npx @membranehq/cli connect --connectionId <id>
  

如果旧连接处于 CLIENT_ACTION_REQUIRED 状态时创建新连接，会遗留孤立记录，并导致所有引用旧 connectionKey 的内容失效。务必重新连接。

• 有多个匹配项（例如 slack-work 和 slack-personal）→ 询问用户要使用哪一个。不要猜测。
• 没有匹配项 → 创建新连接（步骤 1b）。

1b. 创建新连接

通过 URL 或域名连接——最简单的方式：

npx @membranehq/cli connection ensure "https://slack.com" --json
# also accepts a bare domain: "slack.com"

URL 会被规范化为域名，并与已知应用匹配。如果找不到对应应用，系统会创建一个应用并自动构建连接器。

如需设置稳定且易于识别的键，以便之后查找（尤其适用于 slack-work + slack-personal 这样的多账号配置），请在创建后进行设置：

npx @membranehq/cli connection patch <id> --data '{"connectionKey":"slack-work"}'

对于明确的多连接场景（即为已连接的应用创建第二个连接），请使用 connect：

npx @membranehq/cli connect --integrationKey slack \
  --connectionKey slack-personal --allowMultipleConnections

1c. 推进连接至 READY

完成 1a 的重新连接或 1b 的创建后，读取 state 并按照状态机操作：

• READY — 完成。进入第 2 步。

• BUILDING — Membrane 的构建 Agent 正在工作。请等待：

  npx @membranehq/cli connection get <id> --wait --json
  

  --wait 会进行长轮询（最长等待 --timeout 秒，默认值为 30）。

• CLIENT_ACTION_REQUIRED — 用户或 Agent 必须执行某项操作。clientAction 对象会说明具体操作：

  • clientAction.type — "connect"（身份验证流程）或 "provide-input"（需要额外字段）。
  • clientAction.agentInstructions（可选）— 如果存在，请严格遵照这些指示。它们会告诉 Agent 如何以编程方式处理流程中的服务提供方操作。不要走捷径，直接说“粘贴此 URL”——这些指示之所以存在，是因为预期由 Agent 来处理。
  • clientAction.uiUrl（可选）— 由 Membrane 托管的页面，用户可在其中手动完成操作。仅当 agentInstructions 要求这样做，或不存在 agentInstructions 时，才显示此页面。
  • clientAction.description — 面向用户的摘要。

  当操作需要将数据写回连接时（例如，捕获到的 OAuth 凭据、自定义参数）：

  npx @membranehq/cli connection patch <id> --data '{"connectorParameters":{...},"input":{...}}'
  

  用户完成操作后，使用 connection get <id> --wait --json 轮询，直到 state 发生变化。

• CONFIGURATION_ERROR / SETUP_FAILED — 向用户展示 error 字段。这些状态为终止状态——不要盲目重试。

第 2 步 — 使用连接

获取实际响应最快的方式是使用内联分派调用 act。无需经历“创建操作 → 等待 → 运行”这一套流程。

act 支持以下四种分派方式，且只能选择其中一种：

分派方式	使用场景
--api '<json>'	新建连接后的首次调用，以及任何一次性 HTTP 请求。 Membrane 会处理身份验证和基础 URL。
--code '<js>'	需要少量逻辑（循环、转换、多步操作）时。
--key <key>	之前已将此调用保存为可复用操作时。
--id <id>	与 --key 相同，但使用 id（仅当操作没有 key 时使用）。

2a. 内联 api（推荐用于新建连接后的首次调用和一次性调用）

新连接上的首次调用，默认应使用此方式。 这是确认连接正常工作并向用户返回实际响应的最快方式——无需构建步骤，也不会进入 BUILDING 状态或等待。

传入一个 HTTP 规范；Membrane 会通过连接的身份验证层和基础 URL 转发该请求：

npx @membranehq/cli act --connectionKey slack-work \
  --api '{"method":"POST","path":"/api/chat.postMessage","body":{"channel":"#general","text":"Hello"}}' \
  --json

规范格式：{ method, path, body?, headers?, query? }。连接器的基础 URL 会自动添加为前缀。身份验证信息会自动注入。

仅当用户会反复运行相同调用时，才升级为保存的操作（第 3 步）——保存操作对重复使用确有价值，但会增加延迟和故障可能性，对首次启用而言得不偿失。

2b. 内联 code（需要逻辑，而不只是 HTTP 调用时）

npx @membranehq/cli act --connectionKey hubspot \
  --code 'module.exports = async ({ input, membrane }) => {
    const all = []
    let after
    do {
      const page = await membrane.api({ method: "GET", path: "/crm/v3/objects/contacts", query: { limit: 100, after } })
      all.push(...page.results)
      after = page.paging?.next?.after
    } while (after)
    return { count: all.length }
  }' \
  --input '{}' --json

函数会接收 { input, membrane, connection, integration }。在函数内部使用 membrane.api({ method, path, ... }) 进行经过身份验证的调用。函数的返回值会成为响应的 output。

2c. 按 key 调用可复用操作（用于重复使用）

如果用户会反复运行相同调用，请将其保存一次，然后按 key 调用：

npx @membranehq/cli act --key send-channel-message --connectionKey slack-work \
  --input '{"channel":"#general","text":"Hello"}' --json

有关如何创建已保存操作，请参阅下方的第 3 步。

2d. 查找现有可复用操作

如果你不确定是否已有此类操作：

# Ranked by semantic match against an intent
npx @membranehq/cli action list --connectionKey slack-work --intent "send a message" --limit 10 --json

# Catalog actions for one app (browse without a connection)
npx @membranehq/cli external-app list --search slack --json   # → externalAppId
npx @membranehq/cli action list --externalAppId <id> --json

每个结果都包含 id、key、name、description、inputSchema、outputSchema。运行前请先查看 inputSchema——它是权威依据。

如果没有匹配项，请改用内联 api 或 code（见上文），或创建已保存操作（第 3 步）。

步骤 3 — 保存可复用操作（可选）

当你发现自己准备第二次调用相同的 act --api 时，就把它保存下来。以后调用时，只需使用 act --key <key>，而不必提供完整的内联规格。

有两种方式：

按意图 — 描述你想做什么；Membrane 会构建配置并验证：

npx @membranehq/cli action create "send a message in a channel" --connectionKey slack-work --json

该操作会返回 state: BUILDING。等待它完成：

npx @membranehq/cli action get <id> --wait --json

按显式规格 — 直接提供 type + config。常用于将经过测试的内联 api 调用保存为操作：

npx @membranehq/cli action create \
  --key send-channel-message \
  --type api-request-to-external-app \
  --config '{"request":{"method":"POST","path":"/api/chat.postMessage"}}' \
  --integrationKey slack --json

作用范围取决于你设置的字段：

• connectionKey / connectionId → 连接级（绑定到一个连接）
• integrationKey / integrationId（无连接）→ 集成级（在该集成的所有连接间共享）

更新 / 删除：

npx @membranehq/cli action update <id-or-key> --data '<json-merge>'
npx @membranehq/cli action delete <id-or-key>

保存前询问用户 — 他们可能希望为操作命名、添加描述，或继续以内联方式使用。

错误恢复

阅读响应正文 — 切勿仅根据 HTTP 状态码进行分支处理。三种错误情况：

401 — Membrane 身份验证错误

你的 CLI 会话无效或已过期。再次运行 membrane login --tenant。

外部应用连接已断开

供应商的身份验证已失效（令牌被撤销、OAuth 已过期、凭据已轮换）。读取连接状态：

npx @membranehq/cli connection get <id-or-key> --json

如果 state 为 CLIENT_ACTION_REQUIRED，重新连接现有连接（不要创建新连接）：

npx @membranehq/cli connect --connectionId <id>

重新进行身份验证后，重试原来的 act 调用。

操作失败

每个 act 响应都会携带 actionRunId，无论成功还是出错。获取完整日志：

npx @membranehq/cli action-run-log get <actionRunId> --details --json

你会看到映射后的输入、输出、错误，以及与外部应用之间的原始 HTTP 交互。

CLI 参考

所有命令都支持 --json。添加 --workspaceKey <key> 和 --tenantKey <key> 可覆盖项目默认值。

connection

npx @membranehq/cli connection ensure <appUrl> [--name <n>] [--json]                       # Find or create by URL
npx @membranehq/cli connection list [--json]
npx @membranehq/cli connection get <id-or-key> [--wait] [--timeout <n>] [--json]
npx @membranehq/cli connection patch <id> --data '<json>' [--json]
npx @membranehq/cli connect --connectionId <id>                                              # Reconnect existing
npx @membranehq/cli connect --integrationKey <k> [--connectionKey <k>] [--allowMultipleConnections]

act

npx @membranehq/cli act --connectionKey <k> --api  '<json>' [--input <json>] [--json]   # Inline HTTP
npx @membranehq/cli act --connectionKey <k> --code '<js>'   [--input <json>] [--json]   # Inline JS
npx @membranehq/cli act --connectionKey <k> --key  <k>      [--input <json>] [--json]   # Reusable
npx @membranehq/cli act --connectionKey <k> --id   <id>     [--input <json>] [--json]   # Reusable by id

action（管理已保存的操作）

npx @membranehq/cli action list   [--connectionKey <k>] [--externalAppId <id>] [--intent <t>] [--limit <n>] [--json]
npx @membranehq/cli action create <intent> --connectionKey <k> [--json]                       # Build by intent
npx @membranehq/cli action create --key <k> --type <t> --config '<json>' --integrationKey <k> [--json]   # Explicit spec
npx @membranehq/cli action get    <id-or-key> [--wait] [--timeout <n>] [--json]
npx @membranehq/cli action update <id-or-key> --data '<json>'                                  # Merge
npx @membranehq/cli action delete <id-or-key>

action-run-log

npx @membranehq/cli action-run-log get <actionRunId> [--details] [--json]                      # Diagnostics for any /act call

external-app / search

npx @membranehq/cli external-app list --search <query> --json
npx @membranehq/cli search <query> [--elementType <type>] [--limit <n>] [--json]

回退方案：原始 API

如果 CLI 不可用，请直接调用 API。

基础 URL：https://api.getmembrane.com 身份验证标头：Authorization: Bearer $MEMBRANE_TOKEN

从 Membrane 控制台获取令牌。

CLI 命令	对应 API
connection ensure "<url>" --json	使用 {"appUrl": "<url>"} 调用 POST /connections/ensure
connection list --json	GET /connections
connection get <id> --wait --json	GET /connections/:id?wait=true
connection patch <id> --data <json>	使用 <json> 调用 PATCH /connections/:id
connect --connectionId <id>	POST /connections/:id/reconnect
act --connectionKey <k> --api <json>	使用 {"connectionKey":"<k>","api":<json>} 调用 POST /act
act --connectionKey <k> --code <js>	使用 {"connectionKey":"<k>","code":"<js>"} 调用 POST /act
act --connectionKey <k> --key <ak>	使用 {"connectionKey":"<k>","key":"<ak>","input":<json>} 调用 POST /act
action list --connectionKey <k> --intent <t>	GET /actions?connectionKey=<k>&intent=<t>
action create <intent> --connectionKey <k>	使用 {"intent":"<t>","connectionKey":"<k>"} 调用 POST /actions
action get <id> --wait	GET /actions/:id?wait=true
action-run-log get <actionRunId> --details	GET /action-run-logs/:id?details=true

外部端点

所有请求都发送到 Membrane API。此技能不会直接联系任何其他外部服务。

端点	发送的数据
https://api.getmembrane.com/*	身份验证凭据、连接参数、操作输入、Agent 提示词

安全与隐私

• 所有数据均通过 HTTPS 发送至 Membrane API。
• CLI 凭据存储在本地的 ~/.membrane/ 中，并设置了受限的文件权限。
• 连接身份验证（OAuth、API keys）由 Membrane 处理——外部应用的凭据存储在 Membrane 服务中，而非本地。
• 操作的输入和输出会经由 Membrane API 传递至已连接的外部应用。

使用此技能即表示数据会发送至 Membrane。只有在信任 Membrane 可访问你已连接的应用时才安装。