awesome-codex-skills：通过 Rube MCP 自动化 Docsumo 的完整实践——工具发现、连接管理与执行工作流-酒店常州论坛

awesome-codex-skills：通过 Rube MCP 自动化 Docsumo 的完整实践——工具发现、连接管理与执行工作流

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills

本文基于 composio-skills/docsumo-automation/SKILL.md 展开，系统讲解如何在 Codex 技能体系中接入 Docsumo（发票/单据智能提取平台）的自动化能力。读完本文，你将掌握 Rube MCP 的接入配置、RUBE_SEARCH_TOOLS/RUBE_MANAGE_CONNECTIONS/RUBE_MULTI_EXECUTE_TOOL三大工具的调用规范、会话（session）与 memory 参数的使用纪律，以及技能在 awesome-codex-skills 仓库中的安装与触发机制。

一、技能定位与元数据：Codex 如何识别这个技能

Docsumo Automation 技能是 awesome-codex-skills 仓库中composio-skills目录下的一个成员。该目录集中了 800 余个"应用自动化"技能（如 composio-skills/docmosis-automation、docsumo-automation等），它们共享同一套"Rube MCP + Composio toolkit"的自动化模式。

从 composio-skills/docsumo-automation/SKILL.md 的 YAML frontmatter 可以看到该技能的元数据定义：

--- name: docsumo-automation description: "Automate Docsumo tasks via Rube MCP (Composio). Always search tools first for current schemas." requires: mcp: [rube] ---

各字段的作用结合仓库 README 的说明可以确认：

name：技能唯一标识，对应安装后的目录名docsumo-automation。
description：触发依据。README 在"What Are Codex Skills?"一节说明，Codex 依据description的匹配度决定何时触发技能，并且"只在技能命中后才加载正文"，从而保持上下文精简。因此description特意写明了"Always search tools first"这一核心执行纪律。
requires.mcp: [rube]：声明该技能依赖名为rube的 MCP 服务。这是本技能与其他本地型技能的关键差异——它不是自包含指令，而是要求客户端已挂载 Rube MCP 端点。

二、安装与加载：把技能装进 $CODEX_HOME/skills

按照仓库 README.md 的 Quickstart，安装某个技能有两种方式。推荐使用内置的 skill-installer 脚本（其说明见 skill-installer/SKILL.md）：

git clone https://github.com/ComposioHQ/awesome-codex-skills.git cd awesome-codex-skills # 将技能安装到 $CODEX_HOME/skills（默认 ~/.codex/skills） python skill-installer/scripts/install-skill-from-github.py \ --repo ComposioHQ/awesome-codex-skills \ --path composio-skills/docsumo-automation

脚本 skill-installer/scripts/install-skill-from-github.py 的行为约束（来自 skill-installer/SKILL.md）：

默认对公开仓库走直接下载，认证/权限失败时回退到 git sparse checkout（先 HTTPS 再 SSH）；
若目标技能目录已存在则中止，避免覆盖；
可通过--ref（默认main）、--dest、--method auto|download|git、--name控制行为。

也可以手动安装：把composio-skills/docsumo-automation目录整体复制到$CODEX_HOME/skills/（默认~/.codex/skills/）。两种方式最后都需要重启 Codex以重新加载技能元数据。验证方式同样在 README 中给出：ls ~/.codex/skills查看目录，head ~/.codex/skills/docsumo-automation/SKILL.md查看元数据。

安装后的使用方式是自然语言描述任务（如"用 Docsumo 提取这批发票"），由 Codex 按description自动匹配触发；也可以直接点名docsumo-automation强制考虑该技能。

三、前置条件与 Rube MCP 连接配置

技能文档在 Prerequisites 一节给出了三条硬性前提，缺一不可：

Rube MCP 已连接：客户端中必须能调用RUBE_SEARCH_TOOLS；
Docsumo 连接处于 ACTIVE 状态：通过RUBE_MANAGE_CONNECTIONS以 toolkitdocsumo建立并核验；
始终先调用RUBE_SEARCH_TOOLS获取当前工具 schema，而不是凭记忆硬编码。

Setup 部分的配置要点是：在 MCP 客户端配置中加入 Rube MCP 端点（https://rube.app/mcp，作为 MCP server 地址配置）。文档强调该端点无需 API Key——"just add the endpoint and it works"，凭证与连接授权由后续的RUBE_MANAGE_CONNECTIONS交互式流程接管。

文档给出的完整连接建立步骤（4 步，原文顺序）：

调用RUBE_SEARCH_TOOLS确认其有响应，以此验证 Rube MCP 可用；
调用RUBE_MANAGE_CONNECTIONS并指定 toolkit 为docsumo；
若连接状态不是 ACTIVE，跟随接口返回的 auth link 完成授权（即用户在浏览器中完成 Docsumo 账号的 OAuth 类授权）；
在执行任何工作流之前，再次确认连接状态显示为ACTIVE。

从源码结构看，仓库内 800 多个*-automation技能（例如同为单据自动化类的 composio-skills/docmosis-automation/SKILL.md）都遵循完全相同的四步模板，仅 toolkit 参数不同（docsumovsdocmosis）。这说明连接管理是由 Rube 端统一抽象的，技能层只需声明 toolkit 名称。

四、工具发现：RUBE_SEARCH_TOOLS 的调用规范

文档在 Tool Discovery 一节要求：在执行任何工作流之前，必须先做工具发现。原始请求格式如下：

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

参数解读：

queries[].use_case：用自然语言描述任务场景。首次探索时用宽泛的"Docsumo operations"，具体任务时换成如"your specific Docsumo task"的具体描述（见下文 Step 1）；
queries[].known_fields：可留空字符串""，用于提示已知字段；
session.generate_id: true：为当前工作流生成一个新会话 ID。首次发现工具时使用该方式创建会话；同一工作流内的后续调用则复用返回的session_id。

调用返回的内容包括四部分（原文逐条列出）：可用工具的 slug（工具唯一标识）、输入 schema、推荐执行计划（recommended execution plans）、已知陷阱（known pitfalls）。后续步骤 3 中RUBE_MULTI_EXECUTE_TOOL的参数必须严格来自这次返回的 schema——这正是"Always search tools first"纪律的技术原因。

五、核心工作流：三步调用模式

文档把完整执行路径固化为三步。以下完整保留原文调用参数并补充字段语义。

Step 1：Discover Available Tools（工具发现）

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

与 Tool Discovery 一节的不同点在于：此处使用session: {id: "existing_session_id"}而非generate_id: true，即把发现动作挂到已建立的工作流会话上，保证会话内工具上下文一致。

Step 2：Check Connection（连接核验）

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

toolkits是数组形式，可同时核验多个 toolkit。该步骤的意义在于：连接状态可能在授权链接被放弃、token 过期等情况下从 ACTIVE 退化为非 ACTIVE，必须在执行前重新确认，而不能依赖"上次连过"的记忆。

Step 3：Execute Tools（工具执行）

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 搜索结果返回的 slug，禁止自行猜测或硬编码；
arguments：必须与搜索返回的输入 schema 精确匹配（字段名与类型都不能偏）；
memory：本技能要求每次调用都必须携带该参数，即使无内容也要显式传空对象{}——这是 Known Pitfalls 中单列的一条纪律；
session_id：沿用本工作流会话。RUBE_MULTI_EXECUTE_TOOL支持tools数组批量提交多个工具调用，适合"提取 + 查询 + 更新"这类串联操作。

六、已知陷阱（Known Pitfalls）逐条解析

文档列出的 6 条陷阱，按失败后果归类解读：

Always search first（先搜索后执行）：工具 schema 会随 upstream 变化，任何跳过RUBE_SEARCH_TOOLS直接硬编码 slug 或参数名的写法都可能随时失效。这是本技能第一条也是权重最高的一条纪律。
Check connection（连接核验）：执行前必须确认RUBE_MANAGE_CONNECTIONS返回 ACTIVE。非 ACTIVE 状态下执行工具调用属于无效操作。
Schema compliance（schema 精确匹配）：字段名与类型必须逐字对齐搜索结果，大小写、下划线都不能凭习惯改写。
Memory parameter（memory 必传）：RUBE_MULTI_EXECUTE_TOOL调用中memory参数必须出现，空场景也要传{}，否则可能触发参数校验失败。
Session reuse（会话复用边界）：同一工作流内复用同一个 session ID；开启新工作流时生成新的。混用会话会污染工具上下文。
Pagination（分页续取）：Docsumo 涉及文档列表等数据型接口，响应中若出现分页 token，必须沿 token 持续翻页直到取完，否则会拿到不完整结果。

七、Quick Reference：操作速查表

完整继承文档中的速查表，五个入口工具各司其职：

Operation	Approach
Find tools	`RUBE_SEARCH_TOOLS`（附 Docsumo 具体 use case）
Connect	`RUBE_MANAGE_CONNECTIONS`+ toolkit`docsumo`
Execute	`RUBE_MULTI_EXECUTE_TOOL`+ 搜索到的 tool slug
Bulk ops	`RUBE_REMOTE_WORKBENCH`内调用`run_composio_tool()`
Full schema	对带`schemaRef`的工具用`RUBE_GET_TOOL_SCHEMAS`取完整 schema

补充说明：速查表中RUBE_SEARCH_TOOLS返回的 schema 有时是引用式的（带schemaRef字段），此时不能只看摘要字段，必须用RUBE_GET_TOOL_SCHEMAS展开完整输入定义；而批量（bulk）场景则升级到RUBE_REMOTE_WORKBENCH的脚本化通道，在run_composio_tool()中循环执行——这两条路径覆盖了"单工具深 schema"和"大批量重复调用"两类典型工况。

八、在仓库中的位置与延伸阅读

技能正文：composio-skills/docsumo-automation/SKILL.md（本文全部工作流、参数与陷阱的直接来源）
同类模板对照：composio-skills/docmosis-automation/SKILL.md（同结构，toolkit 为docmosis，可对照验证四步模板）
技能机制与安装说明：README.md（"What Are Codex Skills?"、"Quickstart"、"Creating Skills" 三节）
安装工具脚本说明：skill-installer/SKILL.md、skill-installer/scripts/install-skill-from-github.py

从仓库组织方式可以推断，composio-skills下的每个*-automation目录都是一个最小可安装单元：单一SKILL.md承载全部指令，无额外脚本或引用文件，符合 README "Creating Skills" 一节中"保持技能目录精简、避免冗余文档"的最佳实践。如果你要接入的其他 SaaS 也有对应 Composio toolkit，完全可以照docsumo-automation的模式复刻：替换 toolkit 名称、按四步模板写连接流程、保留"先搜索后执行"与 memory/session 纪律即可。

适用前提与限制：本文所有工具名（RUBE_SEARCH_TOOLS、RUBE_MANAGE_CONNECTIONS、RUBE_MULTI_EXECUTE_TOOL、RUBE_REMOTE_WORKBENCH、RUBE_GET_TOOL_SCHEMAS）及其参数均来自仓库内技能文档的当前版本；Rube MCP 服务端能力（端点可用性、toolkit 覆盖范围、schema 结构）不在本仓库内，实际行为以RUBE_SEARCH_TOOLS的实时返回为准。技能生效前提是客户端已按第三节配置 Rube MCP 端点且 Codex 已重启加载技能。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析