核心用法
qb-cli 是一款面向 QuickBooks Online 的命令行接口工具，通过 Intuit 官方 API 直接连接，无需第三方代理。采用 Docker 容器化部署，支持 macOS 和 Linux 系统。用户需先在 Intuit Developer 平台创建应用获取 Client ID/Secret，完成 OAuth2 授权后即可使用。
工具涵盖 29 个命令组共 164 个命令，完整覆盖：
- 应收应付管理：客户/供应商、发票/账单、收付款、信用单、采购单
- 总账操作：科目表、库存项目、费用记录、日记账、存款、转账
- 财务报表：损益表、资产负债表、现金流量表、试算平衡、往来账龄分析
- 银行流程：OFX/QFX/CSV 对账单导入、自动匹配算法、对账辅助
- 期末工作流：月度关账检查、1099 准备、逾期账款跟进
默认输出 JSON 格式便于程序解析，支持 -o table 和 -o csv 切换人机可读模式。内置 8 条关键代理规则，强制要求搜索查重、完整客户信息、发送前确认等风控措施。
显著优点
1. 官方直连：直接调用 Intuit QuickBooks API，数据不经过中间服务器，隐私合规
2. Agent 原生设计：JSON 默认输出、结构化错误码、自动令牌刷新、SyncToken 自动处理，降低自动化开发成本
3. 功能完整：164 个命令覆盖 QBO 绝大多数业务场景，包括银行导入、期末关账等高级工作流
4. 严谨风控：内置多重校验规则（搜索查重、借贷平衡、支付验证），减少误操作导致的数据混乱
5. 灵活输出：支持报表多级汇总、自定义日期范围、CSV 导出对接下游系统
潜在局限
- API 限制：部分操作无法通过 API 完成，如标记交易为"已对账"必须在 QBO UI 中点击；某些字段不支持 SQL 查询（如 Vendor1099）
- 授权流程：OAuth 需人工浏览器介入，纯自动化部署需要处理回调 URL
- Docker 依赖：必须安装 Docker 和 Docker Compose，对轻量环境不够友好
- 沙盒限制：Intuit API 有速率限制，大批量操作需使用 batch 命令（单次最多 30 条）
适合人群
- 使用 QuickBooks Online 的中小企业财务团队
- 需要自动化发票/账单处理的 AI Agent 开发者
- 定期执行银行对账、月度关账、1099 准备的会计人员
- 希望将 QBO 数据集成到自定义报表系统的技术团队
常规风险
| 风险类型 | 说明 |
|---------|------|
| **财务数据误操作** | 发票/账单删除不可逆，建议严格执行"搜索先于创建"规则 |
| **OAuth 令牌泄露** | Client Secret 存储在本地 .env 文件，需确保文件权限 600 |
| **API 速率超限** | 频繁查询可能触发 Intuit 限流，批量操作用 batch 命令 |
| **对账标记遗漏** | CLI 无法真正"完成对账"，最终确认需人工在 QBO UI 操作 |
| **1099 税务合规** | 工具仅生成准备清单，正式申报需使用 IRS 授权软件 |