核心用法
xero_command_line 是 Xero 官方提供的 Node.js 命令行工具，基于 PKCE OAuth 认证，支持与 Xero 会计 API 进行完整交互。该技能覆盖了从联系人管理、发票/报价/贷项通知单处理、银行交易记录、支付、手动日记账到财务报表生成的全链条会计操作。
认证流程：首次使用需运行 xero login 完成浏览器 OAuth 授权。工具支持多配置文件（profile）管理，可通过 -p 参数切换不同组织/应用。2026 年 3 月后，Xero 已将 OAuth scope 细化为粒度权限，旧版 broad scope 将于 2027 年 9 月废弃，用户需根据应用启用范围精确指定 --scope。
关键操作模式：
- 查询优先：所有写入操作前必须先执行列表查询获取 GUID（如联系人 ID、科目代码）
- JSON 文件批量输入：多行项目资源（发票、手动日记账等）必须通过
--file传入 JSON，避免命令行长度限制 - 只读预览：任何修改前需用
--json或--csv导出数据确认
显著优点
- 官方维护：Xero API 团队直接开发，API 兼容性有保障，scope 迁移等变更及时同步
- 完整功能覆盖：支持 12 大类会计实体操作，含利润表、资产负债表、账龄分析等法定报表
- 多格式输出：原生支持 JSON/CSV，便于与
jq、Excel 或 BI 工具集成 - 配置隔离：profile 机制允许同一终端安全切换多个 Xero 组织，避免数据串扰
- 审计友好：手动日记账强制借贷平衡校验，银行交易与发票关联完整
潜在缺点与局限性
- OAuth 浏览器依赖：自动化场景（CI/CD）难以无人值守，需预先生成刷新令牌
- scope 粒度繁琐：2026 年后需逐项申请权限（如
accounting.invoices.read），配置复杂度上升 - 无事务回滚：API 调用成功后立即生效，误操作需手动冲销（创建反向分录）
- JSON Schema 无校验：本地仅做基础格式检查，非法科目代码或税种需提交后才报错
- 区域税种差异：
tax-type参数需根据组织所在地查询（如 NZ 的 OUTPUT2 vs AU 的 GST），无智能提示
适合人群
- 开发者/DevOps：为 ERP、电商平台编写账务同步脚本
- 财务自动化工程师：批量生成周期性发票、自动对账
- 会计师事务所：跨客户组织快速导出报表与审计追踪
- 技术型 CFO/财务经理：用 CLI 替代部分 Web 端重复操作
常规风险
| 风险场景 | 说明 |
|---------|------|
| **组织误操作** | `XERO_PROFILE` 环境变量静默覆盖默认配置，可能导致写入错误组织，每次会话必须执行 `xero org details` 确认 |
| **scope 不足** | 使用 `--scope` 限制权限后，后续操作若涉及未授权资源会返回 403，需重新登录授权 |
| **货币精度** | JSON 输入中的金额需符合 Xero 货币小数位规则（如 JPY 无小数），否则四舍五入可能产生分录差异 |
| **并发冲突** | 多用户同时操作同一发票时，API 乐观锁机制可能返回 409，需客户端实现重试逻辑 |
| **审计痕迹** | 手动日记账的 `narration` 字段为审计唯一描述，遗漏或模糊描述将影响合规追溯 |
建议：生产环境写入操作前，务必先用 --json 导出目标资源快照，并保留操作日志。