核心用法
TokenGuard 是一款专为 AI Agent 设计的本地化 API 成本管控工具。其核心工作流围绕"预算前置检查-执行-成本记录"的闭环展开：用户通过 set 命令设定会话预算上限（默认 $20），在发起昂贵 API 调用前使用 check 命令进行预检，若预算充足则执行调用，完成后通过 log 记录实际支出。系统支持 extend 动态追加预算、、override 单次绕过限制等灵活机制，并提供完整的 history 审计追踪与 JSON 格式 export 导出功能。所有数据持久化于 ~/.tokenguard// 目录，按日自动重置或手动触发 reset。
显著优点
零依赖纯本地架构：无需网络连接、无外部服务依赖，完全基于 Python 标准库实现，部署成本极低。 工程化集成友好：提供标准化退出码（0/1/2）与命令行接口，可无缝嵌入 Shell 脚本或 Python 子进程调用，示例代码即拿即用。 精细化成本感知：内置主流模型（Claude/GPT 系列）的每百万 token 定价参考表，辅助用户快速估算调用成本。 防御性设计：80% 预算阈值预警、硬限制阻断、单次绕过需显式声明，多重机制防止意外超支。 数据主权可控：MIT 开源协议，数据文件为纯 JSON 格式，用户完全掌握审计轨迹。
潜在缺点与局限性
单机会话隔离：预算状态绑定本地文件系统，无法在分布式多机部署的 Agent 集群间同步，多实例场景需自行解决状态一致性。 精度与币种局限：仅支持美元计价，最小单位为分，对需要多币种或更精细计费的场景覆盖不足。 无实时价格同步：内置定价表为静态参考，无法自动跟随厂商调价更新，长期使用可能产生估算偏差。 覆盖机制的信任假设：override 命令虽需显式调用，但若 Agent 本身被恶意控制，仍可能成为绕过成本管控的通道。 缺乏可视化报表：仅提供命令行表格与原始 JSON 导出，无 Web 仪表盘或趋势分析能力。
适合的目标群体
独立开发者与小型团队：预算敏感、需要快速为个人项目或原型系统添加成本护栏。 AI Agent 框架构建者：需要将成本管控作为基础设施组件集成到更复杂的 Agent 编排系统中。 教育与实验场景：教学演示、学生作业、研究原型等需要"保险丝"机制防止意外高额账单的环境。 CI/CD 自动化测试：在持续集成流水线中限制测试用例的 API 调用成本，防止配置错误导致费用失控。
使用风险
数据持久化风险：TOKENGUARD_DIR 环境变量允许自定义存储路径，若指向系统关键目录或共享存储，可能引发权限冲突或数据泄露。 状态丢失风险：会话数据存储于本地 JSON 文件，磁盘损坏、误删除或容器重启（未挂载持久卷）将导致历史记录与预算状态丢失。 估算误差累积：check 命令依赖用户提供的预估成本，若实际调用因 token 消耗超预期而超支，系统仅在 log 阶段发现，此时费用已产生。 并发写入冲突：多进程同时操作同一 session.json 文件时存在竞态条件风险，极端情况下可能导致支出记录丢失或预算计算错误。 覆盖机制滥用：虽然 override 设计为单次有效，但频繁使用或脚本自动化调用可能削弱预算纪律，形成"狼来了"效应。