AgentLedger — AI Agent 费用追踪系统

概述

AgentLedger 是一项会计能力，用于记录您发起的每一笔交易、跨多个账户追踪支出，并生成详细报表。使用本工具可完整保存您的采购财务记录。

重要提示：请务必在完成采购后立即记录交易。该能力专为 AI Agent 设计，用于追踪其自身费用（如 API 成本、工具订阅费等）。

核心功能

1. 记录一笔交易

每次发生采购时，请立即执行记录操作：

// 在 Node.js 环境中，引入 ledger 模块
const AgentLedger = require('./src/ledger.js');
const ledger = new AgentLedger();

// 记录一笔交易
await ledger.logTransaction({
  amount: 29.99,
  currency: 'USD',
  vendor: 'OpenAI',
  description: 'GPT-4 API credits',
  category: 'API/Services',
  account: 'privacy-card-1',
  context: 'Needed additional tokens for user project analysis',
  receiptUrl: 'https://platform.openai.com/receipts/xyz',
  confirmationId: 'sub_1234567890'
});

CLI 使用方式（支持位置参数与命名参数两种风格）：

# 位置参数风格
node src/cli.js log 29.99 "OpenAI" "GPT-4 API credits" --category="API/Services"

# 命名参数风格  
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="GPT-4 API credits" --category="API/Services" --context="Monthly API refill"

2. 查询当前支出

// 获取支出汇总
const summary = await ledger.getSummary('this-month');
console.log(`Total spent this month: $${summary.total}`);

// 查询特定分类支出
const apiSpending = await ledger.getCategorySpending('API/Services', 'this-month');

3. 生成报表

// 月度报表
const report = await ledger.generateReport('monthly', { month: '2024-01' });

// 自定义日期范围
const customReport = await ledger.generateReport('custom', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

4. 预算管理

// 为 API 服务设置月度预算
await ledger.setBudget('API/Services', 500, 'monthly');

// 检查预算状态
const budgetStatus = await ledger.checkBudget('API/Services');
if (budgetStatus.isNearLimit) {
  console.log(`Warning: ${budgetStatus.percentUsed}% of API budget used`);
}

分类体系

请使用以下预定义分类，以确保支出追踪的一致性：

• API/Services — API 积分、SaaS 订阅服务
• Infrastructure — 托管服务、域名、CDN
• Marketing — 广告投放、社交媒体工具
• Tools — 软件许可证、实用工具
• Subscriptions — 按月/年周期性续订的服务
• Other — 其他杂项支出

账户集成

Privacy.com 卡片

若存在 Privacy.com 卡片数据，系统将自动识别：

// 若 workspace/privacy/ 目录下存在 Privacy.com JSON 导出文件
await ledger.importPrivacyTransactions('./privacy/card-1.json');

手动添加账户

// 注册新的付款方式
await ledger.addAccount({
  id: 'stripe-main',
  name: 'Main Stripe Account',
  type: 'credit_card',
  currency: 'USD'
});

自然语言查询

支持以下形式的自然语言提问：

• "本月我在 API 密钥上花了多少钱？"
• "昨天那笔 20 美元的扣款是什么？"
• "显示上季度所有基础设施相关费用"
• "我的市场营销支出是否已超预算？"

CLI 可直接处理此类查询：

node src/cli.js query "API spending this month"
node src/cli.js find "OpenAI" --last-week

时间范围标识

支持的自然语言时间范围如下：

• today、yesterday
• this-week、last-week
• this-month、last-month
• this-quarter、last-quarter
• this-year、last-year
• last-30-days、last-90-days

数据导出

// 导出为 CSV 格式
await ledger.exportTransactions('csv', './exports/transactions.csv');

// 导出为 JSON 格式
await ledger.exportTransactions('json', './exports/transactions.json');

CLI 快速参考

AI Agent 必备命令

# 初始化（仅需运行一次）
node src/cli.js init

# 记录交易（支持两种参数风格）
node src/cli.js log 29.99 "OpenAI" "API credits" --category="API/Services"
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="API credits" --category="API/Services"

# 查询当前支出
node src/cli.js summary                    # 本月
node src/cli.js summary --period="today"   # 仅今日
node src/cli.js summary --period="this-week" # 本周

# 设置与检查预算
node src/cli.js budget set "API/Services" 500    # 设置月度预算
node src/cli.js budget status                    # 检查全部预算状态

# 生成详细报表  
node src/cli.js report monthly
node src/cli.js report --type=category
node src/cli.js report --type=vendor

# 搜索交易记录
node src/cli.js find "OpenAI"                    # 按供应商搜索
node src/cli.js find "API" --category="API/Services"  # 按分类搜索
node src/cli.js find --min-amount=50             # 查找大额支出

# 导出数据
node src/cli.js export csv                       # 导出为 CSV
node src/cli.js export --format=json            # 导出为 JSON

# 自然语言查询
node src/cli.js query "How much did I spend on APIs this month?"
node src/cli.js query "What was that $25 charge?"

# 从 Privacy.com 导入数据
node src/cli.js import privacy ./privacy-export.json

文件存储路径

• 交易记录：workspace/ledger/transactions.json
• 账户信息：workspace/ledger/accounts.json
• 预算配置：workspace/ledger/budgets.json
• 系统设置：workspace/ledger/settings.json

最佳实践

1. 即时记录 — 切勿延迟，采购发生即刻登记
2. 补充上下文 — 说明采购发生的必要原因
3. 统一分类 — 始终使用预定义分类，避免自定义类别
4. 保留凭证 — 存储确认编号与收据 URL 链接
5. 设定预算 — 为每个分类分别设立支出上限
6. 定期复盘 — 每月生成报表，持续分析支出趋势

错误处理与边界情况

AgentLedger 对常见异常情形具备鲁棒性处理能力：

输入校验

• 负金额：拒绝接受（仅允许正数金额）
• 必填字段缺失：返回清晰错误提示，并附带用法示例
• 无效币种：允许通过（不校验币种有效性 — 默认用户明确自身操作）
• 超长描述文本：完整保留，不作截断

数据安全机制

• 自动备份：每次保存前均创建备份副本
• 损坏数据恢复：自动从 .backup 文件恢复
• 空时间段处理：对无交易时段优雅显示 $0.00 总额
• 多币种支持：汇总与报表中按币种严格分离统计

错误恢复示例

# 若出现 "Could not load transactions" 提示：
# 系统将自动尝试从备份恢复
# 数据通常可完全自动还原

# 手动检查备份文件是否存在
ls workspace/ledger/*.backup  # 查看备份文件列表

安全与隐私

• 本地化存储：所有数据仅保存于 workspace/ledger/ 下的 JSON 文件中
• 零外部 API 调用：核心功能完全离线可用
• 不存储敏感信息：绝不保存真实银行卡号或密码
• 账户别名机制：推荐使用语义化 ID，例如 privacy-card-1 或 company-amex
• 收据链接管理：仅保存收据 URL，不保存收据原始内容