AgentLedger

# AgentLedger - AI Agent Expense Tracking

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

**重要提示**：请在购买后立即记录交易。该技能专为 AI 智能体追踪其自身费用（如 API 成本、工具订阅等）而设计。

## 核心功能

### 1. 记录交易 当您进行任何购买时，请立即记录：

```javascript // 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' }); ```

**CLI 用法**（支持位置参数和命名参数）： ```bash # 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. 检查当前支出 ```javascript // 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. 生成报告 ```javascript // 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. 预算管理 ```javascript // 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/Services** - API 额度、SaaS 订阅 - **Infrastructure** - 托管、域名、CDN - **Marketing** - 广告、社交媒体工具 - **Tools** - 软件许可、实用工具 - **Subscriptions** - 定期月度/年度服务 - **Other** - 杂项支出

## 账户集成

### Privacy.com 卡 如果可用，账本会自动检测 Privacy.com 卡数据： ```javascript // If you have Privacy.com JSON exports in workspace/privacy/ await ledger.importPrivacyTransactions('./privacy/card-1.json'); ```

### 手动账户设置 ```javascript // Register a new payment method await ledger.addAccount({ id: 'stripe-main', name: 'Main Stripe Account', type: 'credit_card', currency: 'USD' }); ```

## 自然语言查询

提出如下问题： - "这个月我在 API 密钥上花了多少钱？" - "昨天那笔 20 美元的费用是什么？" - "显示上个月所有的基础设施成本" - "我的营销支出超预算了吗？"

CLI 处理这些查询： ```bash 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`

## 数据导出 ```javascript // Export to CSV await ledger.exportTransactions('csv', './exports/transactions.csv');

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

## CLI 快速参考

### AI 智能体必备命令

```bash # 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 ```

## 文件存储 - 交易记录：`workspace/ledger/transactions.json` - 账户：`workspace/ledger/accounts.json` - 预算：`workspace/ledger/budgets.json` - 设置：`workspace/ledger/settings.json`

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

## 错误处理与边缘情况

账本会优雅地处理常见错误：

### 输入验证 - **负数金额**：将被拒绝（仅使用正数金额） - **缺少必填字段**：提供带有用法示例的清晰错误信息 - **无效货币**：接受（无验证 - 假定用户清楚自己的操作） - **非常长的描述**：无截断处理

### 数据安全 - **自动备份**：每次保存操作前创建 - **数据损坏恢复**：从 `.backup` 文件自动恢复 - **空时间段**：优雅地显示 $0.00 总计 - **多币种**：在摘要和报告中正确分离

### 错误恢复示例 ```bash # 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 调用**：核心功能可离线工作 - **无敏感数据**：从不存储实际的卡号或密码 - **账户别名**：使用描述性 ID，如 `privacy-card-1` 或 `company-amex` - **收据 URL**：存储收据链接，而非收据内容本身