FRESH — Shared URL Freshness Intelligence

FRESH

判断是否需要重新获取。

FRESH 是面向 AI Agent 的共享 URL 新鲜度情报服务。在重新获取、重新抓取、重新渲染或重新嵌入某个 URL 之前，先判断之前看到的版本是否可能仍足够新鲜，可以继续使用。

生产环境基础 URL：https://fresh-api-production-c783.up.railway.app

MCP 端点：https://fresh-api-production-c783.up.railway.app/mcp

FRESH 会返回以下三种决策之一：

• REUSE — 缓存的知识可能仍足够新鲜，可以继续使用
• REFETCH — 该 URL 可能已经过时，值得再次获取
• UNKNOWN — 证据不足；FRESH 宁可承认不确定，也不盲目自信

FRESH 的存在意义

本地缓存知道你上次获取某项内容的时间，却不知道外部资源此后是否发生变化，也不知道其他调用方最近观察到了什么。FRESH 根据时间戳、ETag、Last-Modified 值和内容哈希，构建共享且保护隐私的 URL 变更历史。

REST

POST /v1/check

{"url":"https://example.com/docs/api","lastSeenAt":"2026-08-13T12:00:00Z","toleranceSeconds":3600}

POST /v1/observe

{"url":"https://example.com/docs/api","observedAt":"2026-08-13T13:00:00Z","etag":"abc123","lastModified":"Wed, 13 Aug 2026 12:45:00 GMT","contentHash":"sha256:..."}

无需提供原始页面内容。

MCP

• fresh_check — 判断是否需要再次获取某个 URL
• fresh_observe — 获取后报告保护隐私的新鲜度证据

隐私

FRESH 不需要原始页面内容、Cookie、目标站点凭据或客户载荷。URL 键以单向哈希形式存储，并附带汇总后的观测元数据。

陌生用户验证

核心工具调用是使用证据，但不自动证明调用者是真正的陌生用户。FRESH 会将候选活动分类为 KNOWN_VALIDATOR、LIKELY_VALIDATOR、CONTROLLED_TEST、UNKNOWN_MACHINE 或 CREDIBLE_REAL_USE。只有 CREDIBLE_REAL_USE 才会推动陌生用户里程碑。

我们的验收／冒烟测试流量会使用 X-Tollbooth-Internal: 1 或 X-Fresh-Internal: 1，因此不会计入陌生用户额度。

生产环境验收门槛

现在，每次 Railway 部署都会先针对运行中的服务执行实时内部检查，然后 /health 才能返回 200。此门槛会测试 REST、UNKNOWN、REUSE、REFETCH、持久化观测数据重新加载、MCP 初始化、MCP 工具发现和 MCP fresh_check，并验证受控自测不会增加已验证陌生用户的计数。

状态

v0.1.2 实验性生产基础设施。优先事项：保守决策、低延迟、低于一美分的成本、保护隐私的共享学习、REST + MCP、持久化观测数据，以及可审计的真实使用情况分析。