名称： agent-money-tracker
描述： 面向 AI 代理的智能预算追踪与财务管理库 - 支持支出追踪、收入管理、预算设定、储蓄目标以及基于 LLM 的智能洞察

Agent Money Tracker

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

安装

npm install agent-money-tracker

使用指南

初始化预算追踪器

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

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

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

支出追踪

// 添加一笔支出
await clawhub.addExpense(50, 'Food & Dining', 'Grocery shopping', {
  date: '2026-01-31',
  tags: ['weekly', 'essentials'],
  merchant: 'Whole Foods'
});

// 自然语言输入
await clawhub.addFromNaturalLanguage('spent $45 on uber yesterday');

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

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

收入追踪

// 添加收入
await clawhub.addIncome(5000, 'Salary', 'January salary', {
  date: '2026-01-15'
});

// 添加自由职业收入
await clawhub.addIncome(500, 'Freelance', 'Website project');

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

预算管理

// 创建月度预算
await clawhub.createBudget('Food Budget', 'Food & Dining', 500, 'monthly', 0.8);

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

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

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

储蓄目标

// 创建储蓄目标
await clawhub.createGoal('Emergency Fund', 10000, {
  description: '6 months expenses',
  deadline: '2026-12-31',
  priority: 'high'
});

// 添加贡献金额
await clawhub.contributeToGoal('goal_abc123', 500, 'January savings');

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

分析与报告

// 月度支出摘要
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 }

智能洞察

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

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

周期性交易

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

// 创建周期性收入（例如工资）
await clawhub.createRecurring(
  'income', 5000, 'Salary', 'Monthly salary', 'monthly'
);

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

数据管理

// 获取统计信息
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();

默认类别

支出类别

收入类别

跨平台存储

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

可通过环境变量覆盖：

export CLAWHUB_DATA_PATH=/custom/path

API 参考摘要