AgentLedger - AI 智能体支出追踪

概述

AgentLedger 是一款记账功能，可记录您的每一笔交易，追踪多个账户的支出，并提供详细报告。使用此功能来维护您购买的完整财务记录。

重要说明：请在完成购买后立即记录交易。此功能专为 AI 智能体追踪其自身支出（API 成本、工具订阅等）而设计。

核心功能

1. 记录交易

当您进行任何购买时，请立即记录：

// In Node.js context, require the ledger
const AgentLedger = require('./src/ledger.js');
const ledger = new AgentLedger();

// Log a transaction
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'
});

命令行界面用法（同时支持位置参数和命名参数）：

# Positional style
node src/cli.js log 29.99 "OpenAI" "GPT-4 API credits" --category="API/Services"

# Named parameter style  
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="GPT-4 API credits" --category="API/Services" --context="Monthly API refill"

2. 检查当前支出

// Get spending summary
const summary = await ledger.getSummary('this-month');
console.log(`Total spent this month: $${summary.total}`);

// Check specific category
const apiSpending = await ledger.getCategorySpending('API/Services', 'this-month');

3. 生成报告

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

// Custom date range
const customReport = await ledger.generateReport('custom', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

4. 预算管理

// Set monthly budget for API services
await ledger.setBudget('API/Services', 500, 'monthly');

// Check budget status
const budgetStatus = await ledger.checkBudget('API/Services');
if (budgetStatus.isNearLimit) {
  console.log(`Warning: ${budgetStatus.percentUsed}% of API budget used`);
}

类别

使用这些预定义类别以保持追踪的一致性：

• API/服务- API 额度，SaaS 订阅
• 基础设施- 托管服务，域名，CDN
• 市场营销- 广告、社交媒体工具
• 工具- 软件许可证、实用程序
• 订阅服务- 按月/按年计费的周期性服务
• 其他- 杂项支出

账户集成

Privacy.com 虚拟卡

若可用，账本将自动检测 Privacy.com 虚拟卡数据：

// If you have Privacy.com JSON exports in workspace/privacy/
await ledger.importPrivacyTransactions('./privacy/card-1.json');

手动账户设置

// Register a new payment method
await ledger.addAccount({
  id: 'stripe-main',
  name: 'Main Stripe Account',
  type: 'credit_card',
  currency: 'USD'
});

自然语言查询

可提出如下问题：

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

命令行界面可处理这些查询：

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

时间周期

支持的自然语言时间周期：

• 今天昨天本周
• 上周本月上月
• 本季度上季度今年
• 去年过去30天过去90天
• 数据导出CLI快速参考AI代理必备命令
• 文件存储交易：workspace/ledger/transactions.json

账户：

// Export to CSV
await ledger.exportTransactions('csv', './exports/transactions.csv');

// Export to JSON
await ledger.exportTransactions('json', './exports/transactions.json');

workspace/ledger/accounts.json

预算：

# Initialize (run once)
node src/cli.js init

# Log transactions (supports both styles)
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"

# Check current spending
node src/cli.js summary                    # This month
node src/cli.js summary --period="today"   # Today only
node src/cli.js summary --period="this-week" # This week

# Set and check budgets
node src/cli.js budget set "API/Services" 500    # Set monthly budget
node src/cli.js budget status                    # Check all budgets

# Generate detailed reports  
node src/cli.js report monthly
node src/cli.js report --type=category
node src/cli.js report --type=vendor

# Search transactions
node src/cli.js find "OpenAI"                    # Search by vendor
node src/cli.js find "API" --category="API/Services"  # Search by category
node src/cli.js find --min-amount=50             # Find large expenses

# Export data
node src/cli.js export csv                       # Export to CSV
node src/cli.js export --format=json            # Export to JSON

# Natural language queries
node src/cli.js query "How much did I spend on APIs this month?"
node src/cli.js query "What was that $25 charge?"

# Import from Privacy.com
node src/cli.js import privacy ./privacy-export.json

File Storage

• Transactions:workspace/ledger/transactions.json
• Accounts:workspace/ledger/accounts.json
• Budgets:workspace/ledger/budgets.json
• 设置：workspace/ledger/settings.json

最佳实践

1. 立即记录- 不要等待，每次消费发生时立即记录
2. 添加上下文- 解释购买的必要性
3. 使用一致的分类- 坚持使用预定义的类别
4. 包含收据- 存储确认号和收据URL
5. 设置预算- 为每个类别设定消费限额
6. 定期审查- 生成月度报告以追踪消费模式

错误处理与边界情况

账本能够妥善处理常见错误：

输入验证

• 负金额：拒绝（仅使用正金额）
• 缺少必填字段附带使用示例的清晰错误提示
• 无效货币：已接受（无验证 - 假设用户清楚自己的操作）
• 超长描述内容：完整处理，不做截断

数据安全

• 自动备份：每次保存操作前自动创建
• 损坏数据恢复：自动从.backup备份文件恢复
• 空白周期：优雅显示$0.00总计金额
• 多币种支持：在汇总和报表中完全独立处理

错误恢复示例

# If you see "Could not load transactions" message:
# The system automatically tries to recover from backup
# Your data should be restored automatically

# Manual backup check
ls workspace/ledger/*.backup  # Check if backups exist

安全与隐私

• 仅限本地存储：所有数据仅保存在workspace/ledger/JSON文件中
• 无外部API调用核心功能支持离线使用
• 不存储敏感数据：绝不存储真实卡号或密码
• 账户别名：使用描述性标识，例如隐私卡-1或公司-美国运通卡
• 收据链接：存储收据链接，而非收据内容本身