export CLAWHUB_DATA_PATH=/custom/path

代理资金追踪器

一个用于AI代理追踪支出、收入、预算和储蓄目标的TypeScript库，支持基于LLM的自然语言解析。无需前端 - 专为代理和机器人程序化使用而设计。

安装

bash
npm install agent-money-tracker

---

使用方法

初始化预算追踪器

typescript
import { clawhub } from agent-money-tracker;

// 初始化（在任何操作前必须执行）
await clawhub.initialize();

// 或使用自定义存储路径
await clawhub.initialize(/path/to/data);

支出追踪

typescript
// 添加一笔支出
await clawhub.addExpense(50, 餐饮, 购买日用品, {
date: 2026-01-31,
tags: [每周, 必需品],
merchant: 全食超市
});

// 自然语言输入
await clawhub.addFromNaturalLanguage(昨天打车花了45美元);

// 获取近期支出
const expenses = clawhub.getExpenses({ limit: 10 });

// 按类别和日期范围筛选
const foodExpenses = clawhub.getExpenses({
category: 餐饮,
startDate: 2026-01-01,
endDate: 2026-01-31
});

收入追踪

typescript
// 添加收入
await clawhub.addIncome(5000, 工资, 一月工资, {
date: 2026-01-15
});

// 添加自由职业收入
await clawhub.addIncome(500, 自由职业, 网站项目);

// 获取所有收入
const income = clawhub.getIncome();

预算管理

typescript
// 创建月度预算
await clawhub.createBudget(食品预算, 餐饮, 500, 月度, 0.8);

// 检查预算状态
const status = clawhub.getBudgetStatus();
// 返回：[{ budgetName, spent, limit, remaining, percentageUsed, status }]

// 获取预算提醒
const alerts = clawhub.checkBudgetAlerts();
// 当超出阈值或限额时返回警告

// 获取智能预算建议
const suggestions = clawhub.suggestBudgetLimits();
// 返回：[{ category, suggested, average, max }]

储蓄目标

typescript
// 创建储蓄目标
await clawhub.createGoal(应急基金, 10000, {
description: 6个月生活费,
deadline: 2026-12-31,
priority: 高
});

// 添加储蓄贡献
await clawhub.contributeToGoal(goal_abc123, 500, 一月储蓄);

// 查看进度
const progress = clawhub.getGoalProgress();
// 返回：[{ goalName, targetAmount, currentAmount, percentageComplete, daysRemaining, onTrack }]

分析与报告

typescript
// 月度支出汇总
const summary = clawhub.getSpendingSummary();
// 返回：{ totalExpenses, totalIncome, netSavings, expensesByCategory, incomeByCategory }

// 查看月度趋势
const trends = clawhub.getMonthlyTrends(12);
// 返回：[{ date, expenses, income, netSavings }]

// 完整月度报告
const report = clawhub.generateMonthlyReport(2026, 1);

// 与上月对比
const comparison = clawhub.compareToLastMonth();
// 返回：{ expenseChange, incomeChange, topIncreases, topDecreases }

智能洞察

typescript
// 生成AI驱动的洞察
const insights = await clawhub.generateInsights();
// 返回类似以下洞察：
// - ⚠️ 您的餐饮支出是平时的3倍
// - 💡 取消未使用的订阅每月可节省50美元
// - 🏆 您已连续7天追踪支出！

// 获取未读洞察
const unreadInsights = clawhub.getInsights();

周期性交易

typescript
// 创建周期性支出（例如：Netflix订阅）
await clawhub.createRecurring(
expense, 15.99, 订阅, Netflix, 月度,
{ startDate: 2026-02-01 }
);

// 创建周期性收入（例如：工资）
await clawhub.createRecurring(
income, 5000, 工资, 月度工资, 月度
);

// 处理到期的周期性交易
await clawhub.processRecurring();

数据管理

typescript
// 获取统计数据
const stats = clawhub.getStats();
// 返回：{ totalTransactions, totalExpenses, totalIncome, netSavings, avgExpense, topCategory }

// 获取可用类别
const categories = clawhub.getCategories();

// 导出数据
const jsonData = await clawhub.exportData();

// 创建备份
const backupPath = await clawhub.backup();

// 获取存储位置
const dataPath = clawhub.getDataPath();

---

默认类别

支出类别

类别	图标
餐饮	🍔
交通

🚗 |

| 购物 | 🛍️ | | 账单与水电 | 💡 | | 娱乐 | 🎬 | | 健康与健身 | 💪 | | 教育 | 📚 | | 个人护理 | 💄 | | 订阅 | 📱 |

收入类别

类别	图标
工资	💰
自由职业

💻 |

| 投资 | 📈 | | 礼物 | 🎁 |

---

跨平台存储

数据存储在特定平台的位置：

平台	默认路径
Windows	%APPDATA%\clawhub
macOS

~/Library/Application Support/clawhub |
| Linux | ~/.local/share/clawhub |

通过环境变量覆盖：
bash
export CLAWHUBDATAPATH=/custom/path

---

API参考汇总

方法	描述
initialize(path?)	初始化预算追踪器
addExpense(amount, category, description, options?)

添加支出 |
| addIncome(amount, category, description, options?) | 添加收入 |
| addFromNaturalLanguage(text) | 从自然语言解析并添加 |
| createBudget(name, category, limit, period, threshold?) | 创建预算 |
| getBudgetStatus() | 获取所有预算状态 |
| checkBudgetAlerts() | 获取预算警告/提醒 |
| createGoal(name, target, options?) | 创建储蓄目标 |
| contributeToGoal(goalId, amount, note?) | 向目标添加贡献 |
| getGoalProgress() | 获取所有目标进度 |
| getSpendingSummary(start?, end?) | 获取支出明细 |
| getMonthlyTrends(months?) | 获取月度趋势数据 |
| generateMonthlyReport(year?, month?) | 生成完整报告 |
| generateInsights() | 生成AI洞察 |
| createRecurring(type, amount, category, desc, freq, options?) | 创建周期性交易 |
| processRecurring() | 处理到期的周期性交易 |
| getStats() | 获取交易统计 |
| exportData() | 导出所有数据为JSON |
| backup() | 创建带时间戳的备份 |