build-product-integrations

应用集成

通过 Membrane 构建与外部服务集成的应用。使用 Membrane CLI。

当你需要为产品添加第三方集成时，请使用此技能——连接客户使用的外部应用、代表他们执行操作、同步数据，或提供 AI Agent 工具。

Membrane 的工作方式

Membrane 是一个集成引擎。你定义应用所需的内容（需要集成哪些外部应用、执行哪些操作、使用哪些数据），Membrane 则负责处理身份验证、API 调用和数据转换。

核心概念

工作区 — 你在 Membrane 中的项目，包含产品的所有集成、连接器和配置。

客户 — 你产品中的用户或组织。每位客户都有自己的一组连接和集成状态。通过你选择的唯一 ID（例如用户 ID 或组织 ID）进行识别。

连接器 — 用于外部应用（例如 Slack、HubSpot）的预构建适配器。负责身份验证（OAuth、API 密钥）、API 客户端设置和连接测试。Membrane 为数千种应用提供连接器——如果没有现成的连接器，Membrane Agent 可以为你构建。

集成 — 你的产品与外部应用之间的关联。在工作区中定义，按特定应用分组连接器、操作、数据集合和流程。

连接 — 客户与外部应用之间经过身份验证的链接。客户完成 OAuth/身份验证流程后创建。包含由 Membrane 管理的凭据。

操作 — 对已连接应用执行的一项操作（例如“发送消息”“创建任务”“列出联系人”）。具有类型化的 inputSchema 和 outputSchema。可通过 API 运行，也可用作 AI Agent 工具。

数据集合 — 用于处理外部应用数据的一致 API，类似数据库表。支持列出、查找、搜索、创建、更新和删除操作。

流程 — 由事件、计划任务或 API 调用触发的多步骤异步逻辑。由触发器、函数和控制节点组成。

元素层级

Membrane 元素分为三个层级：

1. 通用 — 适用于多个外部应用（不属于任何特定集成）。示例：可用于任何任务管理应用的“创建任务”操作。
2. 集成 — 专用于某个外部应用（具有 integrationId）。示例：“创建 Jira Issue”操作。
3. 连接 — 专用于某位客户的连接（具有 connectionId）。可按客户自定义集成级元素。

集成级元素需要针对每个集成提供实现。连接级元素可以覆盖或自定义集成级默认设置。

身份验证架构

Membrane 使用 JWT 令牌进行 API 访问：

• 工作区密钥 — 用于标识工作区（设置为 JWT 的 iss 声明）
• 工作区密钥 — 用于签署令牌（绝不可暴露给前端）
• 客户令牌 — 包含工作区密钥和客户 ID 的 JWT，由你的后端生成，供前端 SDK 和 API 调用使用

外部应用凭据（OAuth 令牌、API 密钥）由 Membrane 管理——你的应用无需直接处理这些凭据。

标准工作流：搜索 → 使用 → 委派

使用 Membrane 时始终遵循此模式：

1. 搜索所需内容 — 使用意图搜索查找操作、连接器或集成
2. 如果存在则使用 — 运行操作、使用连接器建立连接等
3. 如果不存在则委派给 Membrane Agent — 创建 Agent 会话来构建缺失的元素

示例：用户想要列出 Slack 频道

# Step 1: Search for a "list channels" action
npx @membranehq/cli action list --connectionId <slack-conn-id> --intent "list channels" --limit 5 --json

# Step 2: If found, run it
npx @membranehq/cli action run <actionId> --connectionId <slack-conn-id> --json

# Step 3: If NOT found, delegate to Membrane Agent
npx @membranehq/cli agent-session create --agent action-building --message "Create an action to list Slack channels for connection <slack-conn-id>" --json
npx @membranehq/cli agent-session get <sessionId> --wait --json
# Then search again and run the newly created action

示例：用户想要添加新的应用（例如 Notion）

# Step 1: Search for existing Notion connector
npx @membranehq/cli search notion --elementType connector --json

# Step 2: If found, create a connection
npx @membranehq/cli connect --connectorId <connectorId>

# Step 3: If NOT found, delegate to Membrane Agent
npx @membranehq/cli agent-session create --agent connection-building --message "Build a connector for Notion (https://notion.so)" --json
npx @membranehq/cli agent-session get <sessionId> --wait --json
# Then create a connection with the new connector

此模式适用于 Membrane 中的所有内容。 如果某个元素（操作、连接器、数据集合、流程）不存在，始终委派给 Membrane Agent 来构建——绝不要尝试自己构建。

身份验证

用于开发 / CLI

使用 Membrane CLI 进行开发和测试身份验证：

npx @membranehq/cli login --tenant

或者，全局安装（npm i -g @membranehq/cli@latest），然后使用 membrane login --tenant。

请始终使用 --tenant 获取限定租户范围的令牌 — 该令牌代表特定租户（工作区 + 客户）进行身份验证，因此后续命令无需每次都传入 --workspaceKey 和 --tenantKey。

这会打开浏览器，或输出授权 URL。用户在 Membrane 中完成身份验证，然后选择工作区和租户。

凭据存储在 ~/.membrane/credentials.json 中。

非交互式身份验证

如果无法使用浏览器登录（远程 / 无头环境），CLI 会输出授权 URL。请让用户打开该 URL 并输入看到的代码：

npx @membranehq/cli login complete <code>

用于生产环境（后端令牌生成）

在生产环境中，后端会针对每位客户的每个请求生成 JWT 令牌：

import jwt from 'jsonwebtoken'

function generateMembraneToken(customerId, customerName) {
  return jwt.sign(
    {
      id: customerId,
      name: customerName,
    },
    process.env.MEMBRANE_WORKSPACE_SECRET,
    {
      issuer: process.env.MEMBRANE_WORKSPACE_KEY,
      expiresIn: '2h',
    },
  )
}

在后端创建一个端点（例如，/api/membrane-token）来返回此令牌。前端 SDK 会调用该端点进行身份验证。

在应用中添加集成

在应用中使用 Membrane 主要有三种方式：

选项 A：JavaScript SDK（前端）

npm install @membranehq/sdk

import { MembraneClient } from '@membranehq/sdk'

const membrane = new MembraneClient({
  fetchToken: async () => {
    const response = await fetch('/api/membrane-token')
    const { token } = await response.json()
    return token
  },
})

// List available integrations
const integrations = await membrane.integrations.find()

// Open connection UI (popup)
await membrane.ui.connect({ integrationKey: 'hubspot' })

// List customer's connections
const connections = await membrane.connections.find()

// Reconnect a disconnected connection
await membrane.ui.connect({ connectionId: 'conn_123' })

// Delete a connection
await membrane.connection('conn_123').archive()

选项 B：React SDK（前端）

npm install @membranehq/react

import { MembraneProvider, useIntegrations, useConnections, useMembrane } from '@membranehq/react'

function App() {
  return (
    <MembraneProvider
      fetchToken={async () => {
        const res = await fetch('/api/membrane-token')
        const { token } = await res.json()
        return token
      }}
    >
      <IntegrationsPage />
    </MembraneProvider>
  )
}

function IntegrationsPage() {
  const { items: integrations, loading } = useIntegrations()
  const { items: connections } = useConnections()
  const membrane = useMembrane()

  const handleConnect = (integrationKey) => {
    membrane.ui.connect({ integrationKey })
  }

  // ... render integrations list with connect buttons
}

选项 C：REST API（后端）

直接从后端使用 Membrane API。

基础 URL：https://api.getmembrane.com（或 https://api.integration.app） 身份验证：Authorization: Bearer <token>

# List integrations
GET /integrations

# List connections
GET /connections

# Create connection request (returns auth URL)
POST /connection-requests
{"connectorId": "<id>"}

# Check connection request status
GET /connection-requests/<id>

# List actions for a connection
GET /actions?connectionId=<id>

# Run an action
POST /actions/<id>/run?connectionId=<cid>
{"input": {"channel": "#general", "text": "Hello!"}}

连接 UI

Membrane 提供预构建的连接 UI，可处理 OAuth 流程和凭据收集：

https://ui.integration.app/embed/integrations/{INTEGRATION_KEY}/connect?token={TOKEN}

在 iframe 中使用或重定向。可选查询参数：

• redirectUri — 连接后重定向回指定位置
• allowMultipleConnections=1 — 允许每个集成建立多个连接
• name — 预设连接名称

若要重新连接已断开的连接：

https://ui.integration.app/embed/connections/{CONNECTION_ID}/refresh?token={TOKEN}

运行操作

操作是在已连接应用上执行的操作。查找并运行操作：

使用 CLI

# Search actions by intent
npx @membranehq/cli action list --connectionId abc123 --intent "send a message" --limit 10 --json

# Run an action
npx @membranehq/cli action run <actionId> --connectionId abc123 --input '{"channel": "#general", "text": "Hello!"}' --json

使用 API

# Search actions
GET /actions?connectionId=abc123&intent=send+a+message&limit=10

# Run action
POST /actions/<actionId>/run?connectionId=abc123
{"input": {"channel": "#general", "text": "Hello!"}}

每个操作都包含：

• id — 唯一标识符
• name、description — 操作说明
• inputSchema — 接受参数的 JSON Schema
• outputSchema — 返回值的 JSON Schema

结果位于响应的 output 字段中。

AI Agent 工具

Membrane 操作可作为 AI Agent 的工具。可采用两种方式：

静态工具（已知工具集）

当你在会话开始前就知道 Agent 需要哪些工具时使用。

1. 列出连接：GET /connections
2. 获取连接的操作：GET /actions?connectionId=<id>
3. 映射为 Agent 的工具格式：

   const tools = actions.items.map((action) => ({
     id: action.id,
     name: action.name,
     description: action.description,
     inputSchema: action.inputSchema,
   }))
   

4. 当 Agent 调用工具时：使用 {"input": {...}} 调用 POST /actions/<id>/run?connectionId=<cid>

动态工具（运行时发现）

当工具取决于用户意图或对话上下文时使用。

通过自然语言意图搜索操作：

GET /actions?connectionId=abc123&intent=send+a+message

此功能使用语义搜索来查找最匹配的操作。

MCP 服务

Membrane 为 AI Agent 提供官方 MCP 服务：

https://mcp.integration.app/sse?token={TOKEN}&productKey={PRODUCT_KEY}

可与 Claude、Cursor 及任何兼容 MCP 的 Agent 配合使用。

使用 Membrane Agent

Membrane Agent 是一个 AI Agent，可为你构建集成元素（连接器、操作、数据集合、流程）。请勿自行构建这些元素 — 请交由 Membrane Agent 处理。

何时使用 Membrane Agent

• 尚无外部应用的连接器
• 找不到所需的操作
• 需要数据集合、流程或其他集成元素
• 需要自定义集成的工作方式

创建 Agent 会话

使用 CLI 创建 Agent 会话：

npx @membranehq/cli agent-session create --agent <agentName> --message "<description>" --json

可用的 Agent 类型：

• connection-building — 为外部应用构建连接器
• action-building — 为已连接的应用构建操作
• membrane — 通用 Membrane Agent（可构建任何元素）

Agent 会话工作流

1. 创建会话，清楚描述你的需求：

   npx @membranehq/cli agent-session create --agent action-building --message "Create an action to send a message in a Slack channel for connection abc123" --json
   

2. 轮询直至完成——Agent 会异步工作：

   npx @membranehq/cli agent-session get <sessionId> --wait --json
   

   • state: "busy" — 仍在工作，请再次轮询
   • state: "idle" — 当前请求已完成
   • status: "completed" — 会话已结束
   • summary — 对已完成工作的描述（在空闲时可用）

3. 发送后续请求（如有需要）：

   npx @membranehq/cli agent-session send <sessionId> --message "Also add support for thread replies" --json
   

4. 中止（如遇到问题）：

   npx @membranehq/cli agent-session abort <sessionId> --json
   

哪些工作应委派，哪些应自行构建

委派给 Membrane Agent：

• 连接器（身份验证、API 客户端、连接测试）
• 操作（API 映射、输入/输出架构、实现逻辑）
• 数据集合（字段架构、CRUD 操作、分页）
• 流程（多步骤自动化、事件处理、调度）
• 外部事件（Webhook 订阅、事件解析）
• 字段映射（应用之间的数据转换）

自行构建：

• 后端令牌生成端点
• 用于显示集成和连接的前端 UI
• Agent 工具映射（将 Membrane 操作转换为你的 LLM 工具格式）
• 使用 Membrane 操作/数据的业务逻辑
• 用于集成体验的自定义 UI 组件

高效 Agent 提示词技巧

创建 Agent 会话时，请提供：

• 连接 ID — 构建操作时务必提供（for connection abc123）
• 应用名称和 URL — 构建连接器时提供（Build a connector for Notion (https://notion.so)）
• 具体操作 — 准确描述该操作应执行的任务（Create an action to list all tasks assigned to the current user）
• 输入/输出预期 — 应接受哪些参数，以及应返回什么

通过 Agent 构建连接器

如果某个应用没有连接器：

# Search first
npx @membranehq/cli search notion --elementType connector --json

# If not found, build one
npx @membranehq/cli agent-session create --agent connection-building --message "Build a connector for Notion (https://notion.so)" --json

# Poll for completion
npx @membranehq/cli agent-session get <sessionId> --wait --json

# After built, create a connection
npx @membranehq/cli connect --connectorId <connectorId>

通过 Agent 构建操作

如果你需要的操作不存在：

# Search first
npx @membranehq/cli action list --connectionId abc123 --intent "create a task" --limit 10 --json

# If not found, build one
npx @membranehq/cli agent-session create --agent action-building --message "Create an action to create a task with title, description, and assignee for connection abc123" --json

# Poll for completion
npx @membranehq/cli agent-session get <sessionId> --wait --json

# Search again to get the action ID
npx @membranehq/cli action list --connectionId abc123 --intent "create a task" --limit 10 --json

故障排除

连接问题

检查连接状态：

npx @membranehq/cli connection get <connectionId> --json

关键字段：

• disconnected: true — 凭据已过期或被撤销，需要重新连接
• error — 出错详情

重新连接：

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

操作错误

操作失败时，响应中会包含错误详情。常见问题：

• 缺少必填输入 — 检查 inputSchema 中的必填字段
• 连接已断开 — 重试前先重新连接
• 速率限制 — 外部应用正在限制请求频率，请稍后重试
• 权限被拒绝 — 连接的 OAuth 范围不包含此操作所需权限

查找合适的操作

如果 action list --intent 没有返回你需要的内容：

1. 尝试用不同措辞描述意图
2. 不使用意图筛选器，列出所有操作：npx @membranehq/cli action list --connectionId abc123 --json
3. 如果操作不存在，请通过 Membrane Agent 构建（见上文）

CLI 参考

所有命令都支持 --json，用于输出结构化 JSON。添加 --workspaceKey <key> 和 --tenantKey <key> 可覆盖默认值。

connection

npx @membranehq/cli connection list [--json]                # List all connections
npx @membranehq/cli connection get <id> [--json]           # Get a connection by ID

connect（交互式）

npx @membranehq/cli connect --connectorId <id>                    # Create connection via browser OAuth
npx @membranehq/cli connect --connectionId <id>                   # Reconnect existing connection

打开浏览器进行身份验证。使用 --non-interactive 可改为打印 URL。

connection-request

npx @membranehq/cli connection-request create [options] [--json]   # Create connection request
npx @membranehq/cli connection-request get <requestId> [--json]    # Check request status

选项：--connectorId <id>、--integrationId <id>、--integrationKey <key>、--connectionId <id>（重新连接）、--name <name>

状态值：pending、success、error、cancelled

action

npx @membranehq/cli action list [--connectionId <id>] [--intent <text>] [--limit <n>] [--json]   # List/search actions
npx @membranehq/cli action run <actionId> --connectionId <id> [--input <json>] [--json]           # Run an action

search

npx @membranehq/cli search <query> [--elementType <type>] [--limit <n>] [--json]   # Search connectors, integrations, etc.

agent-session

npx @membranehq/cli agent-session create --agent <agentName> --message <text> [--json]   # Create session
npx @membranehq/cli agent-session list [--json]                                          # List sessions
npx @membranehq/cli agent-session get <id> [--wait] [--timeout <seconds>] [--json]       # Get status
npx @membranehq/cli agent-session send <id> --message <text> [--json]                    # Send follow-up
npx @membranehq/cli agent-session abort <id> [--json]                                    # Abort session
npx @membranehq/cli agent-session messages <id> [--json]                                 # Get messages

后备方案：原始 API

如果 CLI 不可用，请直接发送 API 请求。

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

CLI 命令	对应的 API
connection list --json	GET /connections
connection get <id> --json	GET /connections/:id
search <q> --json	GET /search?q=<q>
connection-request create --connectorId <id> --json	POST /connection-requests，请求体为 {"connectorId": "<id>"}
connection-request get <id> --json	GET /connection-requests/:id
action list --connectionId <id> --intent <text> --json	GET /actions?connectionId=<id>&intent=<text>
action run <id> --connectionId <cid> --input <json> --json	POST /actions/:id/run?connectionId=<cid>，请求体为 {"input": <json>}
agent-session create --message <text> --json	POST /agent/sessions，请求体为 {"prompt": "<text>"}
agent-session get <id> --wait --json	GET /agent/sessions/:id?wait=true
agent-session send <id> --message <text> --json	POST /agent/sessions/:id/message，请求体为 {"input": "<text>"}
agent-session abort <id> --json	POST /agent/sessions/:id/interrupt

外部端点

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

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

安全与隐私

• 所有数据都通过 HTTPS 发送至 Membrane API。
• CLI 凭据存储在本地 ~/.membrane/ 中，并限制文件权限。
• 连接身份验证（OAuth、API 密钥）由 Membrane 处理——外部应用的凭据由 Membrane 服务存储，不会存储在本地。
• 操作输入和输出会经由 Membrane API 传递至已连接的外部应用。
• 切勿向前端暴露 Workspace Secret。令牌必须在后端生成。

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