Xero Cli

核心功能

Xero Accounting Skill 是一款面向开发者和财务自动化场景的 CLI 工具，基于 Bun 运行时构建，通过 Xero 官方 API 实现全栈会计操作。核心能力覆盖六大模块：

1. 认证与租户管理
采用 OAuth 2.0 标准流程，支持多组织切换（tenants list/select），满足代账公司或集团企业的多账套需求。

2. 发票全生命周期
支持创建（invoices create）、状态流转（DRAFT→AUTHORISED→PAID）、按联系人/状态过滤查询，适配销售发票（ACCREC）和账单（ACCPAY）双模式。

3. 联系人管理
客户/供应商分类管理，支持模糊搜索和详情查询，可直接关联到发票创建。

4. 会计科目体系
按类型（BANK/REVENUE/EXPENSE 等）和会计科目大类（ASSET/LIABILITY 等）筛选，确保分录合规。

5. 银行交易与支付
完整支持收款/付款记录、超额支付处理、附件上传（收据关联），以及付款核销（自动标记发票为已付）。

6. 复杂资金处理
专项处理预付（prepayment）、超额支付（overpayment）、贷项通知单（credit note）的分配与核销。

---

显著优点

• JSON 原生输出：所有命令返回结构化数据，无缝接入 CI/CD 或 ETL 管道
• 类型安全：TypeScript 实现，命令参数有明确的枚举约束（如状态机、科目类型）
• 场景示例完备：从创建发票到记录收付款的完整工作流均有现成命令参考
• 多租户支持：单套凭证可切换多个 Xero 组织，降低代账场景的配置成本

潜在局限

• 运行时依赖：强制使用 Bun（npx -y bun），Node.js 用户需额外安装
• 本地回调限制：OAuth redirect URI 固定为 localhost:5001，云端部署需改造
• 无沙箱隔离：直接操作生产数据，无内置的测试环境切换机制
• 权限粒度粗：依赖 Xero App 级别的 scope 配置，无法实现字段级权限控制

适用人群

• 需要将财务数据同步到内部系统的开发团队
• 处理大量重复发票/付款录入的财务自动化场景
• 使用 Xero 的代账公司（Bookkeeping firms）技术部门
• 希望用脚本替代手工 Excel 导入的中大型企业财务岗

常规风险

• OAuth Token 安全：Client Secret 存储于本地配置文件，多人共用机器存在泄露风险
• 数据一致性：API 调用失败时的幂等性需调用方自行保障（如无内置重试机制说明）
• 审计追溯：CLI 操作日志依赖本地 shell history，不满足严格审计合规要求
• API 限流：高频批量操作可能触发 Xero API rate limit，导致服务中断

核心用法

Xero Accounting Skill 是一个基于 TypeScript 开发的命令行工具，通过与 Xero 官方 API 深度集成，为用户提供完整的会计数据管理能力。该工具采用 OAuth 2.0 标准认证流程，支持多租户组织切换，所有操作均返回结构化 JSON 数据便于自动化处理。

用户首先需要配置 XERO_CLIENT_ID 和 XERO_CLIENT_SECRET 环境变量，通过 auth login 完成浏览器 OAuth 授权后，即可调用完整的财务操作指令集。核心功能覆盖六大模块：发票全生命周期管理（创建、更新、状态流转）、联系人数据库维护（客户/供应商分类）、会计科目查询与过滤、银行交易记录及附件管理、支付处理与核销，以及预付款/超额付款的分配操作。

典型工作流包括：搜索联系人 → 查询收入科目 → 创建草稿发票 → 授权生效 → 记录银行支付 → 标记发票为已付状态。所有数据操作均实时同步至 Xero 云端，确保财务数据的一致性和可追溯性。

显著优点

官方生态深度整合：直接调用 xero-node 官方 SDK，API 行为与 Xero 平台保持 100% 兼容，避免因第三方封装导致的数据格式差异或功能阉割。

企业级安全架构：采用标准 OAuth 2.0 授权码模式，Token 本地存储不经过中间服务器；所有 API 通信强制 TLS 1.2+ 加密；代码层面无危险函数调用，无敏感信息硬编码风险。

自动化友好设计：全量 JSON 输出格式天然适配 CI/CD 流程、RPA 机器人及数据管道集成。支持按状态、类型、联系人等多维度过滤查询，便于构建自动化对账和报表系统。

多组织灵活切换：通过 tenants select 支持单一凭证管理多个 Xero 组织，适合会计事务所服务多客户或集团企业多子公司场景。

潜在缺点与局限性

Token 存储安全性待提升：当前 OAuth Token 以明文 JSON 形式存储于本地文件系统，虽位于用户目录下，但在共享设备或权限配置不当场景存在泄露风险。建议后续版本集成系统密钥库（macOS Keychain/Windows Credential Manager）。

硬编码端口冲突风险：OAuth 回调服务固定监听 5001 端口，若用户本地已有服务占用该端口将导致授权失败。需手动修改源码或等待配置化端口支持。

实时同步依赖网络：作为纯云端 API 工具，离线环境下无法执行任何操作，不适合网络条件受限或需要本地离线账套的场景。

功能边界清晰：专注数据操作层，不提供复杂财务分析、税务计算或报表可视化能力，深度财务分析需配合 BI 工具使用。

适合的目标群体

• 中小企业财务团队：需要批量处理发票、自动化收款确认、简化银行对账流程
• 会计服务外包商（Bookkeepers）：管理多客户 Xero 账套，快速切换组织执行标准化操作
• 技术驱动型创业公司：开发、运营、财务人员共用，通过 CLI 实现财务流程 DevOps 化
• 财务系统集成开发者：需要将 Xero 数据同步至 ERP、CRM 或自建系统的技术团队
• 审计与合规团队：程序化导出交易流水、附件凭证，满足审计追踪和数据归档要求

使用风险与注意事项

授权凭证管理：XERO_CLIENT_SECRET 等敏感配置需严格限制文件权限（建议 chmod 600），避免提交至版本控制系统。建议采用环境变量注入而非配置文件硬编码。

API 速率限制：Xero 对 API 调用存在频率限制，批量操作（如历史数据迁移）需内置重试和限流逻辑，避免触发服务降级。

数据操作不可逆性：发票作废（VOIDED）、支付删除等操作直接影响财务账面，建议在关键操作前增加人工确认节点或操作日志审计。

依赖维护责任：项目依赖 express 等网络库，需定期执行 npm audit 检查安全更新。当前许可证信息未明确，商用前建议联系维护者确认授权条款。