用 Rube MCP 驱动 Xero 记账自动化：awesome-codex-skills 中 Xero Automation 技能全解析-创锋一号

用 Rube MCP 驱动 Xero 记账自动化：awesome-codex-skills 中 Xero Automation 技能全解析

【免费下载链接】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

本文系统讲解 awesome-codex-skills 仓库中 Xero Automation 技能的完整用法：如何在 Codex 会话中通过 Rube MCP 服务器连接 Xero 云端会计软件，自动化处理发票查询、联系人管理、收款登记、银行交易记账、科目表（Chart of Accounts）查看等多租户记账工作流。读完本文，你将掌握该技能的连接配置、9 个核心工具的参数语义与调用格式，以及多租户路由、OData 过滤语法、分页等关键实战避坑点，可直接在小企业记账场景中落地使用。

技能定位：面向小企业记账的 Xero 自动化指令包

Xero 是面向小型企业的云端会计平台，涵盖发票、联系人、付款、银行交易与科目表等核心记账对象。在 awesome-codex-skills 的composio-skills目录下，每个子目录对应一个由 Composio 提供的自动化技能，Xero Automation 正是其中专注于会计记账场景的一个。

该技能的元数据定义在文件头部的 YAML frontmatter 中（composio-skills/xero-automation/SKILL.md）：

--- name: Xero Automation description: "Xero Automation: manage invoices, contacts, payments, bank transactions, and accounts in Xero for cloud-based bookkeeping" requires: mcp: [rube] ---

这段元数据的含义是：技能名称为Xero Automation；description声明其能力范围——管理发票、联系人、付款、银行交易与账户，用于云端记账；requires.mcp声明它依赖名为rube的 MCP 服务器。Codex 正是依据description来判断何时自动触发该技能（参见仓库 README.md 对 Codex Skills 触发机制的说明），因此描述中精准写明"记账/发票/银行交易"等关键词，便于 Agent 在相关请求出现时自动命中。

该技能与仓库中同目录下的其他 Composio 技能（如 QuickBooks Automation、FreshBooks Automation）共用同一套 Rube MCP 基础设施，但工具集与参数体系各自针对 Xero 的 API 模型定制，本文聚焦 Xero 部分。

环境准备：连接 Rube MCP 与 Xero 租户

第一步：挂载 Rube MCP 服务器

执行任何 Xero 工具之前，必须先让 Codex 会话可用 Rube MCP 服务器，其端点地址为https://rube.app/mcp。从仓库中同族的 composio-automation 技能可知，Rube 的接入方式是将其添加为客户端配置中的 MCP server，无需 API Key——添加端点即可工作。挂载后，会话中会出现RUBE_SEARCH_TOOLS、RUBE_MANAGE_CONNECTIONS、RUBE_MULTI_EXECUTE_TOOL等一组 Rube 工具，它们是对底层 1000+ 集成能力（含 Xero）的统一入口。

第二步：建立 Xero toolkit 连接

在调用任何XERO_*工具前，必须确认存在xerotoolkit 的活动连接：

若尚无连接，通过RUBE_MANAGE_CONNECTIONS（指定 toolkit 为xero）发起连接流程；
按照返回的认证链接完成 Xero 账户授权（OAuth 流程由 Rube 托管）；
确认连接状态为 ACTIVE 后再执行工作流。

第三步：多租户确认（可选但重要）

若你同时管理多个 Xero 组织（org / tenant），需先调用XERO_GET_CONNECTIONS列出当前活动的租户连接，取出正确的tenant_id供后续所有工具调用使用。

快速自检清单：Rube MCP 已挂载 →RUBE_SEARCH_TOOLS可响应 →RUBE_MANAGE_CONNECTIONS中xero连接为 ACTIVE → 多租户场景下已用XERO_GET_CONNECTIONS锁定tenant_id。

技能安装（可选）

若希望将该技能安装到本地 Codex 环境，可参照仓库提供的 skill-installer 技能使用其脚本：

python skill-installer/scripts/install-skill-from-github.py --repo ComposioHQ/awesome-codex-skills --path composio-skills/xero-automation

安装后重启 Codex 以加载新元数据（参见 README.md 的安装说明）。

核心工作流一：发票的查询与过滤

工具与参数

工具：XERO_LIST_INVOICES

参数	说明
`Statuses`	逗号分隔的状态过滤，取值`"DRAFT"`、`"SUBMITTED"`、`"AUTHORISED"`、`"PAID"`
`ContactIDs`	逗号分隔的 Contact ID 列表，按联系人过滤
`InvoiceIDs`	逗号分隔的 Invoice ID 列表，按发票 ID 过滤
`where`	OData 风格过滤表达式，如`"Status==\"AUTHORISED\" AND Total>100"`
`order`	排序表达式，如`"Date DESC"`、`"InvoiceNumber ASC"`
`page`	分页页码
`If-Modified-Since`	UTC 时间戳；仅返回该时间之后被修改过的发票（增量同步）
`tenant_id`	Xero 组织 ID；省略时默认使用第一个租户

调用示例

Tool: XERO_LIST_INVOICES Arguments: Statuses: "AUTHORISED,PAID" order: "Date DESC" page: 1

实战要点

状态过滤是最高频用法：例如应收账龄分析时，通常需要先取AUTHORISED（已确认待收）与PAID（已收款）状态的发票。
增量同步：周期性任务（如每日同步）应记录上次运行时间并传入If-Modified-Since，只拉取增量数据，避免全量重复拉取。
多条件组合：where可与Statuses、order、page叠加使用；注意where中字符串值须用转义双引号包裹（见后文"已知陷阱"）。

核心工作流二：联系人的检索与管理

联系人（Contact）是发票、银行交易等对象的外键基础，先检索出正确的ContactID是后续记账的前提。

工具与参数

工具：XERO_GET_CONTACTS

参数	说明
`searchTerm`	不区分大小写的搜索词，覆盖 Name、FirstName、LastName、Email、ContactNumber 字段
`ContactID`	按 ID 获取单个联系人
`where`	OData 过滤，如`"ContactStatus==\"ACTIVE\""`
`page`/`pageSize`	分页控制
`order`	排序，如`"UpdatedDateUTC DESC"`
`includeArchived`	设为`true`时包含已归档联系人
`summaryOnly`	设为`true`时返回轻量响应（减少负载）

调用示例

Tool: XERO_GET_CONTACTS Arguments: searchTerm: "acme" page: 1 pageSize: 25

实战要点

优先用searchTerm而非复杂where：原文档特别提示，在高流量（数据量大）的账户上，某些where过滤条件（如IsCustomer、IsSupplier）可能被 Xero 拒绝，此时应回退到searchTerm+ 分页。
summaryOnly优化性能：仅需确认联系人存在或获取 ID 列表时，开启轻量模式可显著减少响应体积，适合大批量核对场景。

核心工作流三：创建付款记录

付款（Payment）将发票与银行账户关联起来，是"客户付了钱"这一记账动作的落点。

工具与参数

工具：XERO_CREATE_PAYMENT

参数	必填	说明
`InvoiceID`	✅	付款所对应的 Xero 发票 ID
`AccountID`	✅	收款银行账户 ID
`Amount`	✅	付款金额（数字类型）
`Date`	—	付款日期，格式`YYYY-MM-DD`
`Reference`	—	付款参考或描述
`CurrencyRate`	—	外币付款时的汇率

调用示例

Tool: XERO_CREATE_PAYMENT Arguments: InvoiceID: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" AccountID: "b2c3d4e5-f6a7-8901-bcde-f12345678901" Amount: 1500.00 Date: "2026-02-11" Reference: "Payment for INV-0042"

实战要点

InvoiceID与AccountID均为 UUID 格式，应分别通过XERO_LIST_INVOICES与XERO_LIST_ACCOUNTS（或银行账户列表）预先解析获得，切忌凭空编造。
外币场景务必传入CurrencyRate，否则 Xero 可能按默认汇率处理，导致对账偏差。

核心工作流四：创建银行交易

银行交易（Bank Transaction）用于登记资金流出（SPEND，付款出去）与资金流入（RECEIVE，收进来），是日常记账最常用的动作之一。

工具与参数

工具：XERO_CREATE_BANK_TRANSACTION

参数	必填	说明
`Type`	✅	`"SPEND"`（支出）或`"RECEIVE"`（收入）
`ContactID`	✅	Xero 联系人 ID
`BankAccountCode`	✅	科目表中的银行账户代码
`LineItems`	✅	行项目数组，每项包含：`Description`（必填，描述）、`UnitAmount`（必填，单价）、`AccountCode`（必填，分类科目代码）、`Quantity`（数量，默认 1）、`TaxType`（税率类型：`"OUTPUT"`、`"INPUT"`、`"NONE"`）
`Date`	—	交易日期，格式`YYYY-MM-DD`
`Reference`	—	交易参考
`Status`	—	`"AUTHORISED"`或`"DELETED"`
`CurrencyCode`	—	货币代码，如`"USD"`、`"EUR"`

调用示例

Tool: XERO_CREATE_BANK_TRANSACTION Arguments: Type: "SPEND" ContactID: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" BankAccountCode: "090" LineItems: [ { "Description": "Office supplies", "UnitAmount": 75.00, "AccountCode": "429", "Quantity": 1, "TaxType": "INPUT" } ] Date: "2026-02-11" Reference: "Feb office supplies"

实战要点

科目代码必须真实有效：BankAccountCode与行项目内的AccountCode都必须匹配科目表中实际存在的代码。应先调用XERO_LIST_ACCOUNTS获取有效代码清单，再构造请求（见"已知陷阱"中的说明）。
税类型语义：INPUT表示进项税（采购抵扣）、OUTPUT表示销项税（销售收取）、NONE表示不涉及税。中国等实行增值税的场景，需与 Xero 中的税率映射对照。
行项目默认数量为 1，省略Quantity时按单价全额入账。

核心工作流五：付款与银行交易的查询

对已发生的收款和银行流水进行复核，是记账对账闭环的重要一环。

工具：

XERO_LIST_PAYMENTS—— 列出将发票与银行交易关联起来的付款记录
XERO_LIST_BANK_TRANSACTIONS—— 列出 SPEND/RECEIVE 银行交易

通用参数：

参数	说明
`where`	OData 过滤，如`"Status==\"AUTHORISED\""`
`order`	排序，如`"Date DESC"`
`page`	分页页码
`If-Modified-Since`	增量更新：仅返回该时间戳之后的变更
`tenant_id`	组织 ID

典型场景：对账时用XERO_LIST_PAYMENTS找出"已标记付款但状态异常"的发票；用XERO_LIST_BANK_TRANSACTIONS按日期范围复核银行流水是否与银行对账单一致。两个查询都支持分页与增量参数，适合纳入定时对账脚本。

核心工作流六：科目表与连接信息查看

记账分类的正确性依赖科目表，多租户路由的正确性依赖连接信息。

工具：

XERO_LIST_ACCOUNTS—— 获取全部科目代码，用于给银行交易行项目做分类
XERO_GET_CONNECTIONS—— 列出活动的 Xero 租户连接（多租户场景的第一步）
XERO_LIST_ATTACHMENTS—— 列出某实体（发票、联系人等）上的附件

这三个工具虽不直接产生记账分录，但分别是"选对科目"、"选对租户"、"核对凭证附件"的前置能力，建议在复杂工作流开始时先调用XERO_GET_CONNECTIONS与XERO_LIST_ACCOUNTS建立上下文。

典型端到端流程：从收款到入账

综合以上工作流，一个完整的"收到客户付款"自动化流程可编排为：

调用XERO_GET_CONNECTIONS确认租户，取出tenant_id；
调用XERO_LIST_INVOICES（Statuses: "AUTHORISED"）找到待收款发票，取其InvoiceID；
调用XERO_LIST_ACCOUNTS确认银行账户与科目代码；
调用XERO_CREATE_PAYMENT将发票与银行账户关联、登记收款；
（如需拆分入账）调用XERO_CREATE_BANK_TRANSACTION登记RECEIVE类型的银行流水；
调用XERO_LIST_PAYMENTS复核付款记录是否生成正确。

该编排与仓库中 QuickBooks Automation 的"先解析外键 ID → 再创建主记录 → 最后验证"推荐执行计划一脉相承，体现了 Composio 技能族共同的最佳实践：所有外键（ContactID、AccountID、AccountCode）都必须先经查询工具解析，再用于写操作。

已知陷阱与避坑指南

下表汇总了原文档列出的六大高频问题，务必在编写工作流时逐一规避：

陷阱	详情
多租户路由	省略`tenant_id`时默认使用第一个已连接租户。管理多个组织时，务必先用`XERO_GET_CONNECTIONS`核对当前租户，避免把账记到错误的公司。
高流量账户的过滤被拒	在数据量大的账户上，某些`where`过滤（如`IsCustomer`、`IsSupplier`）可能被 Xero 拒绝。回退方案：改用`searchTerm`+ 分页。
OData 过滤语法	必须使用双等号`==`，例如`Status=="AUTHORISED"`；写成单等号`=`会报错。这是 Xero API 的 OData 风格约定。
必须分页	大多数列表端点都会分页返回。务必检查响应中是否还有下一页，并持续拉取直到取完全部数据，否则会遗漏记录。
日期格式	所有日期必须是`YYYY-MM-DD`格式；`If-Modified-Since`时间戳必须是完整的 ISO 8601 UTC 日期时间。
银行科目代码有效性	银行交易中的`BankAccountCode`必须匹配科目表中真实存在的代码。用`XERO_LIST_ACCOUNTS`先发现有效代码，再构造请求。

补充建议：结合 composio-automation 技能的通用陷阱提示，执行任何 Xero 工具前建议先通过RUBE_SEARCH_TOOLS获取最新工具 schema，避免因工具参数结构变更导致调用失败；工作流内复用同一个 session ID，新工作流再生成新 session。

工具速查表

工具 Slug	用途
`XERO_LIST_INVOICES`	带过滤与分页地列出发票
`XERO_GET_CONTACTS`	检索与查询联系人
`XERO_CREATE_PAYMENT`	创建付款，将发票关联到银行账户
`XERO_CREATE_BANK_TRANSACTION`	登记一笔 SPEND 或 RECEIVE 银行交易
`XERO_LIST_PAYMENTS`	列出付款记录
`XERO_LIST_BANK_TRANSACTIONS`	列出银行交易
`XERO_LIST_ACCOUNTS`	获取科目表
`XERO_GET_CONNECTIONS`	列出活动的 Xero 租户连接
`XERO_LIST_ATTACHMENTS`	列出某实体上的附件

这 9 个工具覆盖了"读（发票/联系人/付款/银行流水/科目表）→ 写（付款/银行交易）→ 查（连接/附件）"的完整记账闭环，足以支撑应收管理、应付登记、银行对账、多组织记账等常见小企业场景。

结语

Xero Automation 技能通过 Rube MCP 把 Xero 的记账能力封装成一组语义清晰、参数规范的XERO_*工具，配合技能自身的 OData 过滤、分页、多租户与增量同步约定，可以让 Codex 在对话中直接完成从发票查询到收款入账的完整记账操作。使用时的三条主线值得牢记：先连接（Rube MCP +RUBE_MANAGE_CONNECTIONS+XERO_GET_CONNECTIONS）→ 再解析外键（ContactID、AccountID、AccountCode）→ 最后写入并复核（创建后用 List 类工具验证）。把握好这三点，即可在 Xero 云端记账场景中稳定复用该技能，并与仓库中其他 Composio 会计类技能协同，构建完整的 AI 记账自动化体系。

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

企业官网建设流程全解析