核心用法
Agent Rate Limiter 是一个纯 Python 实现的本地限流工具，通过环境变量配置后，以 gate → work → record 的三步循环嵌入 Agent 工作流。执行 python3 rate-limiter.py gate 获取当前流量层级（ok/cautious/throttled/critical/paused），根据返回的退出码（0/1/2）动态调整行为强度；任务完成后使用 record 命令记录消耗，系统基于滚动窗口自动计算使用率。遭遇 429 错误时，自动触发指数退避并进入 paused 状态，待冷却期结束后通过 resume 恢复。
显著优点
零依赖架构：仅依赖 Python 3 标准库，无 pip 安装、无 API Key、无外部服务，彻底消除供应链攻击面。预防性限流：区别于传统的"撞墙后重试"模式，该工具在达到 90% 阈值时即进入 cautious 层级，通过五级渐进式降级（ok → cautious → throttled → critical → paused）实现平滑降速，避免上下文丢失与 Token 浪费。智能恢复机制：内置指数退避算法（exponential backoff with jitter），429 触发后自动计算恢复时间，无需人工干预。多厂商兼容：预设 Claude（Max 5x/20x）与 OpenAI（Plus/Pro）策略，同时支持完全自定义配置。状态透明化：JSON 状态文件记录完整流量轨迹，便于审计与调优。
潜在缺点与局限性
启发式估算误差：由于 Anthropic/OpenAI 未开放实时用量 API，该工具基于请求计数进行启发式估算，准确率约 70-85%，需用户根据实际体验手动调优 RATE_LIMIT_ESTIMATE。配置门槛：虽然提供保守默认值，但不同账户的实际限额存在差异，初期可能需要多次试错才能找到最优参数。多实例隔离成本：每个 Agent 实例需配置独立的 RATE_LIMIT_STATE 路径，否则状态文件相互覆盖将导致估算失效。无可视化界面：纯命令行交互，缺乏图形化监控仪表盘。仅限于请求频次控制：不处理 TPM（Tokens Per Minute）或并发连接数等细粒度限流场景。
适合的目标群体
高频自动化 Agent 开发者：需要长时间无人值守运行的 Claude Max/OpenAI Pro 用户，尤其是涉及子 Agent 编排、定时任务（cron）或批量处理的场景。成本敏感型团队：希望避免因 429 重试导致的 Token 浪费与 API 账单激增。合规要求严格的组织：零依赖、纯本地执行、无数据外传的架构，满足金融、医疗等行业的数据安全审计要求。运维自动化工程师：需要将 AI 能力集成至 CI/CD 流水线或后台批处理系统，追求稳定可预期的执行节奏。
使用风险
性能风险：每次 gate 检查涉及本地 JSON 文件读取与解析，极高并发场景下（>1000 TPS）可能成为 I/O 瓶颈，建议结合内存缓存或批量 gate 检查优化。状态文件风险：虽然已实现路径遍历防护与 0600 权限控制，但若配置于共享目录或 NFS 存储，仍可能面临并发写入冲突或权限漂移问题。估算漂移风险：长期运行后若未定期校准 RATE_LIMIT_ESTIMATE，可能因账户限额调整或供应商策略变更导致防护失效。Python 版本依赖：依赖 fcntl 模块实现文件锁，Windows 平台需额外适配（当前未提供 Windows 兼容版本）。降级策略设计风险：五级阈值的默认配置（90%/95%/98%）基于 Claude Max 经验，其他厂商或计费模式可能需要重新调参。