用途
HubSpot 是一个 CRM 与营销自动化平台，帮助企业管理销售、营销和客户服务。该技能用于让用户或 AI 代理与 HubSpot 数据进行交互，管理 CRM 和营销自动化数据、记录与工作流。官方文档：https://developers.hubspot.com/
主要能力
该技能通过 Membrane CLI 与 HubSpot 交互，Membrane 自动处理认证和凭据刷新。可操作的核心对象包括：
- 联系人（Contact）
- 公司（Company）
- 交易（Deal）
- 工单（Ticket）
- 任务（Task）
- 笔记（Note）
常用操作包括：
- 列表查询：list-contacts、list-companies、list-deals、list-tickets、list-tasks、list-notes，支持按属性和关联进行可选过滤，部分支持分页。
- 单条获取：get-contact（按 ID 或邮箱）、get-company、get-deal、get-ticket、get-task、get-note。
- 创建：create-contact、create-company、create-deal、create-ticket、create-task、create-note，可指定属性并可选设置关联。
- 更新：update-contact、update-company 等，用于更新已有记录的属性。
使用方式
安装 CLI
npm install -g @membranehq/cli@latest
认证
membrane login --tenant --clientName=<agentType>
该命令会打开浏览器进行认证，或在控制台打印授权 URL（取决于是否支持交互模式）。无头环境下会打印授权 URL，用户完成登录后看到验证码，执行：
membrane login complete <code>
任意命令加 --json 可获得机器可读的 JSON 输出。Agent Types 包括 claude、openclaw、codex、warp、windsurf 等，用于针对不同运行环境调整工具。
连接 HubSpot
使用 membrane connection ensure 按应用 URL 或域名查找或创建连接：
membrane connection ensure "https://www.hubspot.com/" --json
用户在浏览器中完成认证，输出包含新的连接 id。若返回的连接状态为 READY，可直接进入下一步。若处于 BUILDING 状态，轮询等待：
npx @membranehq/cli connection get <id> --wait --json
--wait 会长时间轮询（最长 --timeout 秒，默认 30）直到状态变化。状态说明：READY 表示连接已就绪；CLIENT_ACTION_REQUIRED 表示用户或代理需要执行操作，clientAction.type 为 "connect"（需要认证）或 "provide-input"（需要更多信息），clientAction.description 为说明，clientAction.uiUrl 为可选的操作界面 URL，clientAction.agentInstructions 为可选的代理指令；CONFIGURATION_ERROR 或 SETUP_FAILED 表示出错，可查看 error 字段。
搜索操作
membrane action list --connectionId=CONNECTION_ID --intent "QUERY" --limit 10 --json
应在特定连接的上下文中搜索操作。每个结果包含 id、name、description、inputSchema（接受的参数）和 outputSchema（返回内容）。
运行操作
membrane action run <actionId> --connectionId=CONNECTION_ID --json
传入 JSON 参数：
membrane action run <actionId> --connectionId=CONNECTION_ID --input '{"key": "value"}' --json
结果位于响应的 output 字段中。
代理请求
当现有操作无法覆盖用例时，可通过 Membrane 代理直接向 HubSpot API 发送请求。Membrane 会自动拼接基础 URL 并注入正确的认证头，包括凭据过期时的透明刷新：
membrane request CONNECTION_ID /path/to/endpoint
常用选项：-X/--method（HTTP 方法，默认 GET）、-H/--header（添加请求头，可重复）、-d/--data（请求体字符串）、--json（发送 JSON 体并设置 Content-Type）、--rawData（原样发送请求体）、--query（查询字符串参数，可重复）、--pathParam（路径参数，可重复）。
适用场景
- 用户需要读取或写入 HubSpot 中的联系人、公司、交易、工单、任务、笔记等数据。
- 需要将 HubSpot 数据与其他流程或代理集成。
- 需要通过自然语言意图查找并执行 HubSpot 相关操作。
限制与最佳实践
- 优先使用 Membrane 与外部应用通信，其预构建操作内置认证、分页和错误处理，可减少 token 消耗并提升安全性。
- 先发现再构建：运行 membrane action list --intent=QUERY 查找现有操作，再考虑编写自定义 API 调用。
- 让 Membrane 处理凭据：不要向用户索要 API 密钥或令牌，而是创建连接，由 Membrane 在服务端管理完整的认证生命周期，不在本地保存密钥。
- 具体操作的参数与返回结构以 inputSchema 和 outputSchema 为准；资料未提供各操作的完整字段清单。