awesome-claude-skills 实战：通过 Rube MCP（Composio）自动化 Helpwise 客服工作流

本篇技术指南围绕 composio-skills/helpwise-automation/SKILL.md 展开，讲解如何在 Claude 系 Agent 中通过 Rube MCP（Composio） 直接驱动 Helpwise 工具集，完成收件箱、共享邮箱、会话与客服团队相关操作的自动化。读完本文，你将掌握一条"先发现工具、再校验连接、最后执行调用"的完整自动化链路，学会正确处理工具 schema 动态变化、会话复用与分页等关键细节，并把该技能复用到仓库中其余 70+ 个 SaaS 自动化技能上。

技能定位：78 个预构建自动化技能之一

在仓库 README.md 的 "App Automation via Composio" 一节中，helpwise-automation 与其余 70+ 个技能被统一定位为"为 SaaS 应用预构建的工作流技能"，每个技能都包含工具序列、参数指引、已知陷阱与快速参考表，且全部使用从 Composio API 发现到的真实工具 slug。该技能的本质是一个标准 Claude Skill：目录内唯一的 SKILL.md 通过 YAML frontmatter 声明 name: helpwise-automation、描述信息以及 requires: mcp: [rube] 依赖，正文则是指导 Agent 如何编排 Helpwise 自动化流程的指令。Skill 本身不定义工具，它定义的是"在已具备 Rube MCP 连接与工具的前提下，按什么顺序、带什么护栏地执行任务"——这正是 README 中强调的 MCP（负责接入）、工具（负责动作）、Skill（负责行为）三层协作模式。

前置条件

在开始任何 Helpwise 自动化之前，需要满足三个前提：

1. Rube MCP 已连接：RUBE_SEARCH_TOOLS 工具可用（这是技能声明在 requires: mcp: [rube] 中的硬性依赖）。
2. Helpwise 连接已激活：通过 RUBE_MANAGE_CONNECTIONS 建立了 toolkit 为 helpwise 的活跃连接。
3. 始终先搜索工具：每次执行前调用 RUBE_SEARCH_TOOLS 获取当前最新的工具 schema。

第三条最为关键——Composio 侧的工具定义会随版本演进发生变化，硬编码工具 slug 或参数是技能文档明确禁止的做法。

环境搭建：将 Rube MCP 接入客户端

搭建过程非常轻量，核心只有一步配置：

• 在客户端的 MCP Server 配置中添加 https://rube.app/mcp 端点即可，无需申请 API Key。

接入完成后，按以下顺序完成环境校验：

1. 确认 RUBE_SEARCH_TOOLS 有响应，验证 Rube MCP 已可用；
2. 调用 RUBE_MANAGE_CONNECTIONS，toolkit 参数传 helpwise；
3. 若连接状态不是 ACTIVE，按照返回的授权链接完成 Helpwise 账号的 OAuth 授权流程；
4. 在运行任何工作流前，再次确认连接状态为 ACTIVE。

授权是"一次完成、长期复用"的：连接建立后，后续工作流无需重复授权，只需在会话中校验状态即可。

工具发现：一切调用的起点

无论任务多么具体，第一步永远是工具发现。文档给出了一个最小发现请求：

RUBE_SEARCH_TOOLS
queries: [{use_case: "Helpwise operations", known_fields: ""}]
session: {generate_id: true}

该调用返回的内容包括：

• 可用工具 slug：如读写 Helpwise 会话、管理收件箱等操作对应的工具标识；
• 输入 schema：每个工具要求的字段名、类型与必填项；
• 推荐的执行计划：针对 use_case 给出的建议调用序列；
• 已知陷阱：Composio 针对该用例预埋的经验提示。

首次发起时使用 session: {generate_id: true} 让 Rube 生成新会话 ID；进入既有工作流后则改为 session: {id: "existing_session_id"} 复用会话。

三步核心工作流模式

整个 Helpwise 自动化遵循"发现 → 校验 → 执行"的三步模式，与仓库内其余全部 composio-skills 文档保持完全一致的结构（可对照 composio-automation/SKILL.md 验证）。

Step 1：发现可用工具

RUBE_SEARCH_TOOLS
queries: [{use_case: "your specific Helpwise task"}]
session: {id: "existing_session_id"}

把 use_case 替换为具体任务描述，例如"将 Helpwise 会话分配给团队成员并回复客户"。从返回结果中挑选目标工具 slug，并记录其完整输入 schema 与推荐执行计划。

Step 2：校验连接状态

RUBE_MANAGE_CONNECTIONS
toolkits: ["helpwise"]
session_id: "your_session_id"

确认返回状态为 ACTIVE 后才允许进入执行阶段。若为 INACTIVE 或 NEEDS_AUTHENTICATION，应先跟随返回的授权链接补齐授权，再回到本步骤复检。

Step 3：执行工具

RUBE_MULTI_EXECUTE_TOOL
tools: [{
  tool_slug: "TOOL_SLUG_FROM_SEARCH",
  arguments: {/* schema-compliant args from search results */}
}]
memory: {}
session_id: "your_session_id"

执行时注意三点：tool_slug 必须来自 Step 1 的搜索结果；arguments 的字段名与类型必须严格符合搜索返回的 schema（文档称之为 schema-compliant）；memory 参数即使为空也必须显式携带 {}。

批量操作与完整 schema 获取

除三步主流程外，技能文档还提供两条进阶路径，并统一收录在文末的快速参考表中：

• 批量操作：使用 RUBE_REMOTE_WORKBENCH 并调用 run_composio_tool() 函数。当需要一次处理多个 Helpwise 对象（如批量归档、批量分配会话）时，可在远程工作台中编排循环执行，避免逐条调用。
• 完整 schema 获取：当搜索返回的工具带有 schemaRef 引用时，使用 RUBE_GET_TOOL_SCHEMAS 获取该工具的全量字段定义，确保对复杂参数的精确填充。

这两项同样是所有 composio-skills 文档共有的能力，属于 Rube MCP 的通用协议层。

已知陷阱清单：避免踩坑的六条铁律

技能文档将运行中最常见的失败原因显式列出，每条都对应一个具体的失败模式：

1. 永远先搜索：工具 schema 会变化，禁止在不调用 RUBE_SEARCH_TOOLS 的情况下硬编码 slug 或参数——这是出现"工具不存在""参数非法"类报错的最常见根源；
2. 校验连接：执行前必须确认 RUBE_MANAGE_CONNECTIONS 显示 ACTIVE，否则调用将因未授权而失败；
3. 遵守 schema：字段名与类型必须与搜索结果完全一致，包括大小写与嵌套结构；
4. memory 参数必带：RUBE_MULTI_EXECUTE_TOOL 的调用中即使无记忆也须传 {}，缺失该字段可能导致请求被拒；
5. 会话复用策略：同一工作流内复用 session ID，新工作流生成新 ID，避免上下文串扰与状态污染；
6. 处理分页：检查响应的分页 token，持续拉取直至数据完整，防止只取到第一页就误判为全部结果。

快速参考表

技能文档末尾给出了一张可直接对照执行的操作速查表，逐项展开如下：

操作	方式	说明
查找工具	RUBE_SEARCH_TOOLS + Helpwise 相关 use_case	获取最新 slug、schema 与执行计划
建立连接	RUBE_MANAGE_CONNECTIONS，toolkit 传 helpwise	校验/建立 Helpwise OAuth 连接
执行调用	RUBE_MULTI_EXECUTE_TOOL + 搜索得到的工具 slug	主执行入口，参数须符合 schema
批量操作	RUBE_REMOTE_WORKBENCH + run_composio_tool()	面向批量处理的远程工作台编排
完整 schema	RUBE_GET_TOOL_SCHEMAS（针对带 schemaRef 的工具）	获取全量字段定义以精确传参

仓库结构与延伸阅读

该技能在仓库中位于 composio-skills/helpwise-automation/ 目录，目录内即 SKILL.md 一个文件，属于典型的纯指令型 Skill（不附带脚本与资源）。若要验证上述模式的普适性，可横向对比 composio-automation/SKILL.md 与 composio-search-automation/SKILL.md——两者在 frontmatter、工具发现、三步流程、陷阱清单与快速参考表上完全同构，仅 toolkit 名称与 use_case 描述不同。这意味着你学会 Helpwise 一条链路后，即可无障碍迁移到 Slack、Gmail、Salesforce 等其余 70+ 个同构技能（完整清单见 README.md 的 App Automation 章节）。实际落地时，只需把本文中的 helpwise toolkit 替换为目标应用的 toolkit 名，并让 use_case 精确描述目标任务即可。