只存总点击数不够：短链统计 API 的时间序列教训

为 AI Agent 构建一个短链点击统计端点，听起来只是几个计数器的事——总点击数、近 30 天点击数、最后一次点击时间。跳转时自增，写进内存映射，用管理密钥读回来。上线，看着数据面板数字上涨，一切正常。

直到某个 Agent 提出一个再合理不过的问题：「我这 40 个链接里，哪个快死了？」

答案是：我不知道。

总量与时间戳掩盖了「死活」

问题的根源在于数据结构本身。我手里只有两个维度：累计点击数和最后点击时间戳。这两个数字听起来够用，实际却无法回答任何关于趋势的问题。

原文作者描述得很精确：一个链接有 900 次点击、全部发生在一月，另一个链接有 900 次点击、均匀分布在六个月里，在我的统计端点上返回的结果完全一样。前者已死，后者还活着，但 API 分辨不出。

「最后一次点击时间」之所以是一种自欺，是因为它只给出一个瞬时快照。它无法告诉你点击是集中在早期还是持续发生，也无法区分「刚好昨天有人点了一次」和「过去半年每天都稳定有流量」。在 Agent 驱动的自动化场景里，链接是否需要替换、是否还在产生价值，取决于速率，而不是总量。

用环形缓冲区补上时间维度

解决方案并不复杂，也不需要引入 Prometheus 或时序数据库。作者的做法是：为每个链接维护一个长度为 30 的整数数组，每天一个计数器，读取时惰性轮转。

核心逻辑只有一行索引计算：day_index = floor(now / 86400) % 30。当前时间戳映射到数组中的一个槽位，写入或读取时自动落在正确的「今天」上。跨越 30 天的旧数据被自然覆盖，环形缓冲区不需要额外的清理任务。

统计端点现在返回一个 daily_clicks 数组。Agent 拿到这串按天排列的数字后，可以自行计算速率、趋势、衰减曲线——想怎么用就怎么用，而服务端只需提供原始的时间序列切片。

这个设计的巧妙之处在于成本：没有额外基础设施，没有后台轮转进程，只有一个数组和一次取模运算。对于面向 Agent 的轻量统计接口，这几乎是能提供时间维度信息的最低成本方案。

环形缓冲区（Ring Buffer） 是一种固定容量、首尾相接的线性数据结构，写入指针到达末尾后回绕到起始位置，新数据覆盖最旧的数据。它的核心优势是空间恒定且无需显式清理：在本文场景中，长度为 30 的数组天然承担了「滚动 30 天窗口」的职责，第 31 天的写入会覆盖第 1 天的槽位。相比队列或日志，环形缓冲区不需要移动元素、不需要扩容，读取和写入都是 O(1)。选择长度等于窗口天数、并用 floor(now / 86400) % 30 做索引映射，是让「时间槽位」与「物理槽位」解耦的常见技巧：无论过了多少天，当天总会落在正确的数组位置上。

惰性轮转（Lazy Rotation） 是与环形缓冲区常搭配的策略。传统做法是起一个定时任务每天零点把所有槽位前移一格，但这需要后台进程、可能引入时区与漂移问题，且在没有写入时白白消耗资源。惰性轮转把「轮转」这一步推迟到读写发生时，靠索引取模自动定位，因此完全不需要定时器。代价是无法主动感知某个槽位「已经过期」，但若读取时结合时间戳判断有效性即可弥补。这种设计在嵌入式、监控代理和轻量 API 中都很常见。

聚合计数器回答「多少」，不回答「何时」

这个教训值得所有为 Agent 构建分析能力的人记下。聚合计数器天生只能回答「多少」，而 Agent 一旦拿到数据，必然会问时间相关问题。

「这个还在工作吗？」——这句话表面上是在问总量，本质上永远是在问速率。一个总量很高的链接可能早已停止产出，一个总量普通的链接可能正在稳定增长。如果存储层没有保留可恢复速率的信息，端点上再怎么包装也补不回来。

单个时间戳列解决不了这个问题。它记录的是最后一个点，而速率需要至少两个点之间的差值，以及它们之间的时间跨度。作者的建议很直接：在设计存储时，就让速率可恢复；如果做不到，就别指望上层能用总量推出来。

聚合计数器与时间序列的区别，本质上是「点」与「流」的区别。聚合计数器在每次事件发生时做一次不可逆的归约（求和、取最大值、更新最后时间），存储的只是结果，原始事件被丢弃。时间序列则保留按时间轴排列的采样点，允许事后计算差分、斜率、移动平均。二者不是性能差异，而是信息论意义上的差异：归约一旦发生，被丢弃的信息无法从结果中反推。

速率可恢复性（Rate Recoverability） 是评估存储设计的一个实用判据：给定一段存储数据，能否在事后重建任意时间段内的变化速率？单点时间戳不具备这一性质，因为它只记录最后一个事件，缺乏时间跨度内的分布。至少需要两个或以上的时间分桶（bucket）才能计算 Δ计数 / Δ时间。这也是监控系统普遍采用直方图或时间分桶而非单一累计值的原因——累计值可以派生出速率，前提是它被周期性地采样并保留。

Prometheus 式的 pull 模型 之所以流行，正是因为它按固定间隔抓取并存储带时间戳的样本，天然满足速率恢复；而本文的环形缓冲区可以看作这一思想在单链接粒度上的极简化实现：不引入外部 TSDB，只在应用内存里保留窗口内的日级样本。

面向 Agent 的默认权限设计

这个统计接口已经上线在 x402.freeq.one 的工具页面上，可以查看按天拆分的点击明细。作者提到管理密钥仍然控制着访问权限，链接所有者免费使用——他称之为「目前找到的唯一合理的默认值」。

这个细节指向一个更宽泛的话题：当 Agent 成为 API 的主要消费者时，权限模型和数据结构一样需要重新思考。免费给链接所有者、按密钥门控，是一种把「谁该看什么」和「谁在调用」对齐的简单模式。相对于一刀切的公开或全封闭，这种分层默认值更适配多 Agent 协作的场景。

从总点击数到每日点击数，改动很小，但它决定了 API 能不能回答 Agent 真正会问的问题。

x402 协议 是一套面向机器支付的 HTTP 原生协议，名称取自 HTTP 状态码 402「Payment Required」，旨在让 API 在被调用时按次计费、无需人工介入即可完成结算，典型场景正是 AI Agent 自主采购数据或算力。文章提到的 x402.freeq.one 即是这一生态下的工具服务端点。理解这一点有助于看清文章提到的「链接所有者免费、管理密钥门控」：它并非单纯的访问控制，而是把计费与授权单元对齐到「谁拥有资源」而非「谁在调用」。

面向 Agent 的权限模型 与面向人类的模型有几个关键差异：第一，调用方没有可交互的登录界面，密钥即身份；第二，Agent 可能同时代表多个主体（自己的用户、上游任务）、需要细粒度委托；第三，权限判断必须机器可读、可缓存、低延迟。分层默认值——例如「资源所有者免费、第三方按量计费、管理操作需高权限密钥」——在不需要复杂身份系统的情况下提供了合理的基线。为了避免密钥泄漏导致越权，实践中常配合短时效令牌、按 scope 限定的 API Key 以及可审计的调用日志。