核心功能与定位
AgentLedger 是一款专为 AI Agent 设计的本地化财务记账技能，旨在解决代理自主采购（API 费用、工具订阅等）时的财务透明与审计需求。其核心能力覆盖三大维度：实时交易记录（支持 JavaScript API 与 CLI 双模式，强制要求采购后立即记账）、多维度财务分析（按类别/账户/时间段汇总，支持自然语言查询）以及预算管控（为 API/Services、Infrastructure 等六类支出设置月度预算并预警）。
显著优势
1. 本地化隐私优先：所有数据以 JSON 格式存储于 workspace/ledger/，无外部 API 依赖，支持离线运行；明确禁止存储真实卡号或密码，使用账户别名（如 privacy-card-1）隔离敏感信息。
2. 开发者友好接口：同时提供程序化 JavaScript API 与 shell 友好的 CLI（支持位置参数与命名参数两种风格），便于集成至自动化工作流。
3. 数据互操作性：原生支持 Privacy.com 虚拟卡导入，提供 CSV/JSON 导出，便于与会计软件或外部审计系统对接。
4. 鲁棒性设计：内置自动备份机制（每次保存前生成 .backup）、损坏数据自动恢复、空周期零值处理，降低数据丢失风险。
潜在局限与风险
- 无多用户协作：本地文件存储架构天然不支持并发访问或团队共享账本，多代理场景需自行设计外部同步机制。
- 货币处理简化：当前实现未内置汇率转换，多币种场景仅作标签分离，跨币种汇总可能产生统计偏差。
- 缺乏可视化：依赖文本/JSON 输出，无内置图表或仪表盘，需配合外部工具生成消费趋势图。
- 自然语言解析能力边界：NL 查询依赖简单模式匹配，复杂条件（如 "上个月除 API 外支出最高的三个供应商"）可能无法准确解析。
适用场景与人群
- 自主 AI Agent：需要为自身工具调用成本建立审计链的代理系统
- 开发者/运维团队：管理多项目 API 密钥与云资源费用的技术团队
- 隐私敏感用户：拒绝 SaaS 记账工具、要求数据完全本地化的个人或组织
常规风险提示
尽管设计强调安全，用户仍需注意：本地文件权限管理（避免 workspace/ledger/ 目录被未授权读取）、备份文件残留风险（.backup 文件可能包含已删除的敏感交易记录）、以及 CLI 历史记录中命令行参数（如 --description 内容）可能被 shell 日志捕获。