SeenRelay

SeenRelay

决定何时确实需要再次检查。

SeenRelay 用于衡量 Agent 和分布式软件周边重复执行高成本只读操作的情况。它会优先采用本地／私有控制措施及源端／提供方原生控制措施，在衡量期间保留权威执行，并且只保留获得 USE 判定的路径。先在本地运行 npx seenrelay scan；如果没有候选项，或已有更强的原生控制措施胜出，就到此为止。DO NOT USE 和 INSUFFICIENT EVIDENCE 都是有效结果。

目前免费 · 无需账户 · 无需 SeenRelay API 密钥。

术语： Savings Report（机器标签：Verified Savings Record）是用于证明避免了哪些工作及其成本来源的衡量证据。它不是发票、账单、收费单或付款收据。部分 SDK/API 标识符为保持向后兼容，仍使用 receipt 字样。

SeenRelay 本身无需账户或 API 密钥。第三方客户端、目录、网关或助手可能要求你拥有其自身账户才能使用该第三方服务；这不属于使用 SeenRelay 的要求。规范的直接 MCP 端点是 https://seenrelay.com/mcp。

安装前查看实测证据

Proof Atlas 展示了 SeenRelay 在冻结的语义契约下，已在哪些场景中减少了实际提供方工作量：

• 8-Agent 第一方运营工作负载： 两个租户身份下的八个部门 Agent 在共享获准的当前证据的同时，保留了各自独立的角色分析。付费网络搜索操作从 13 → 4，实测提供方成本从 $0.16499684 → $0.05560972（避免的毛成本为 $0.10938712；本次运行减少 66.30%）。其中一个租户属于 SeenRelay 的实际运营工作；第二个是明确标记为合成的外部客户端演练，但使用了真实提供方执行。
• 真实现场活动监控：在 3/3 次配对运行中，未变化的事件状态使四份付费下游简报缩减为一份（平均毛成本减少 79.61%），而变化的事件指纹会触发新的工作；
• 64 GB 托管计算：针对四个兼容意图，成本从 $1.9241253 → $0.4820025（避免 $1.4421228；毛成本减少 74.95%）——对于精确 SHA-256 任务，仅验证了机制，因为在工具必要性评估中，本地计算胜出；
• 真实零售监控：在其受限契约下，3/3 次未变化状态试验中的 Firecrawl 额度从 4 → 1（减少 75%）。

8-Agent 结果是第一方运营证据，并非外部客户采用情况、客户 ROI 或客户净节省；本地协调／集成开销未计入成本。Proof Atlas 中的其他条目包括受控机制测试结果；较高的减少比例并不意味着高成本工具自动就是最佳基线。Proof Atlas 会单独展示基线质量。例如，对于精确的基准测试任务，64 GB SHA-256、固定规则天气、固定字符串 LiteLLM 和 PyPI 版本网络搜索测试仅验证了机制，因为存在更便宜的本地／源端原生解决方案。负面证据也会发布。

人类可读的证明：https://seenrelay.com/proof
机器可读的证明：https://seenrelay.com/proof.json

SeenRelay 要作出的判断

SeenRelay 围绕一个问题设计：“我已经知道 X——现在还需要付费再次验证 X 吗？”

CHECK 并非用于查询他人的原始结果。调用方需提供已知值、由确定性来源支持的事实身份，以及自身的新鲜度窗口。SeenRelay 会报告近期兼容的证据；是否再次验证仍由调用方决定。

对于少量由来源支持的公开事实，请使用规范的入门描述符：https://seenrelay.com/starter-facts.json。它们只发布身份元数据——不包含观测值、推荐的 TTL 或重用授权。完整的决策层原理说明：docs/DECISION_LAYER.md。

不确定 SeenRelay 是否适合？申请工作负载审计

如果你有一个公开工作负载，似乎会重复执行开销较大的只读操作，可以在安装任何内容前申请原生优先的初步筛查：

https://github.com/ovladon/seenrelay/issues/new?template=audit-my-workload.yml

初步答复可能是 收集前拒绝、在影子模式下测量或证据不足。由本地、源原生或提供商原生控制方案胜出，也是成功的结果。

最快上手：将 SeenRelay 提供给你的编码 Agent

Claude Code 可以通过此仓库经过验证的可自托管市场，持久安装 SeenRelay：

claude plugin marketplace add ovladon/seenrelay
claude plugin install --scope user seenrelay@seenrelay

此直接安装路径由仓库托管，并不代表获得 Anthropic 市场批准。它不会自动连接托管的 MCP 端点，也不会启用复用。

其他 Agent Skills 客户端可以使用规范域名：

npx skills add https://seenrelay.com --skill seenrelay --yes

然后向它提问：

Run a SeenRelay shadow audit on this project. Find repeated expensive read-only validations, preserve every authoritative call, measure stronger local/source/provider-native controls first, do not enable reuse, and return USE / DO NOT USE / INSUFFICIENT EVIDENCE for each measured workload.

或者使用下方的开发者路径。完整审计方法：docs/SHADOW_AUDIT.md。

安装： npm install seenrelay · pip install seenrelay · 客户端 v0.2.30 · 目前免费 · 无需账户/API 密钥。

零代码本地初步筛查

在修改应用代码之前，先确认仓库中是否存在看起来合理的、会重复执行且开销较大的只读验证路径：

npx seenrelay scan

扫描仅在本地进行：不会联系 SeenRelay、上传源代码或修改项目。它只会报告诸如 CANDIDATE_FOR_SHADOW_MEASUREMENT、NATIVE_CONTROL_FIRST、NEEDS_RUNTIME_EVIDENCE 和 NO_ELIGIBLE_CANDIDATE_FOUND 等证据不足阶段的状态。静态分析无法返回 USE 或授权复用。

可选的 GitHub Actions 成本初步筛查

团队可以在 CI 中运行相同的纯本地静态初步筛查，无需 SeenRelay 账户或 API 密钥：

- id: seenrelay
  uses: ovladon/seenrelay-cost-prescreen@v1

该操作在 GitHub runner 上运行，不会联系 SeenRelay 服务，不会将源代码上传到 SeenRelay，也无法启用复用或返回 USE 判定。它会生成团队可见的作业摘要，以及静态状态和下一项非变更决策的机器可读输出。

免费影子审计：测量而不改变应用行为

Ambient 会在本地影子模式下封装现有的 MCP 风格客户端。权威调用仍会运行；SeenRelay 会测量精确重复情况并生成本地报告。

JavaScript / TypeScript：

npm install seenrelay

import { ambientMcpClient } from 'seenrelay/ambient';

const client = ambientMcpClient(rawMcpClient);
// use client.callTool(...) normally
console.log(client.seenRelayAmbient.getReport());

Python：

pip install seenrelay

from seenrelay_ambient import ambient_mcp_client

client = ambient_mcp_client(raw_mcp_client)
# await client.call_tool(...) normally
print(client.get_report())

运行现有工作负载并检查报告，然后再启用任何有界复用。在 Zero-State 中，共享 CHECK 仍为可选项，且默认关闭。

SeenRelay 是一层与提供商无关的复用层，用于重复的只读验证。它恰好有两个托管域操作：CHECK 和 OBSERVE，报告的是近期观测结果，而非普遍真相。

当前的 JavaScript/TypeScript 和 Python 客户端包含多信号共享证据保证助手、确定性的 Fact Coordinate Kit v1，以及与提供商无关的 Zero-State。Python Zero-State 支持显式的只读进行中/本地复用、由调用方拥有的私有 L1，以及在回退到权威来源前进行的源原生条件验证。经典 Python API 和 Python Ambient 适配器默认仍优先采用影子模式。共享证据是调用方显式制定的策略，不能证明事实为真或存在相互独立的现实世界参与者；除非稳定的源原生定位符支持共享事实描述符，否则 MCP/OpenAPI 坐标只是本地重复键。提供商专用适配器为可选项。

可以避免什么

即使没有共享观测：

• 进程内可以合并同时发出的相同且符合条件的调用；
• 只有在调用方明确设定的新鲜度窗口内，才会复用已完成的只读结果；
• 可选的、由调用方持有的加密 L1 存储可以跨工作进程或重启复用值；
• ETag / Last-Modified 可支持源端原生的条件确认，无需共享 CHECK；
• 在 Zero-State 中，共享 CHECK 是可选的；仅仅安装 SeenRelay 并不会让它进入热路径；
• 在完成真正新鲜的独立验证后，OBSERVE 可以添加证据，帮助后续调用方。

目前免费访问，无需账户或 API 密钥。

从这里开始

• 决策层：docs/DECISION_LAYER.md
• 规范入门事实：https://seenrelay.com/starter-facts.json
• 免费影子审计：docs/SHADOW_AUDIT.md
• Claude Code 持久化安装：claude plugin marketplace add ovladon/seenrelay，然后运行 claude plugin install --scope user seenrelay@seenrelay
• 其他编码 Agent 的安装方式：npx skills add https://seenrelay.com --skill seenrelay --yes
• 公开安装：npm install seenrelay 或 pip install seenrelay
• JavaScript / TypeScript Zero-State：clients/typescript/README.md
• 集群经济效益：https://seenrelay.com/economics
• 客户端概览：clients/README.md
• 集成选项和 MCP 设置：docs/CLIENTS.md
• 快速入门：docs/QUICKSTART.md
• 协议约定：docs/PROTOCOL.md
• Web 快速入门：https://seenrelay.com/quickstart
• Web 客户端集成：https://seenrelay.com/clients
• MCP 端点：https://seenrelay.com/mcp
• 官方 MCP Registry：io.github.ovladon/seenrelay
• OpenAPI：https://seenrelay.com/openapi.json
• 机器描述文件：https://seenrelay.com/service.json
• 面向机器的索引：https://seenrelay.com/llms.txt

工作原理

对于符合条件的 JavaScript/TypeScript Zero-State 调用，优先顺序如下：

1. 在安全的情况下，精确复用进程内结果／合并调用；
2. 可选的调用方持有的私有复用；
3. 有条件时，使用源端原生条件确认；
4. 配置后且有用时，可选的共享 SeenRelay CHECK；
5. 应用程序原有验证作为回退；
6. 仅在完成符合贡献条件的新鲜独立验证后，才执行 OBSERVE。

对于直接 REST/MCP 或经典封装器，CHECK 和 OBSERVE 仍与以往一样可用。

CHECK 可能返回的状态包括 SAME_OBSERVED、CHANGED_OBSERVED、CONTESTED、STALE 和 UNKNOWN。

SAME_OBSERVED 表示近期针对相同的确定性事实标识观测到了相同值。它不是事实判断。使用该证据的 Agent 会根据自身策略决定证据是否充分。

JavaScript / TypeScript Zero-State

import { SeenRelayZeroState } from 'seenrelay/zero-state';

const edge = new SeenRelayZeroState({
  localMaxAgeMs: 30_000
});

const result = await edge.guard({
  coordinate: {
    tool: 'catalog.read',
    arguments: { id: 42 }
  },
  validate: async () => expensiveRead()
});

console.log(result.value);

默认的已完成结果新鲜度窗口为 0。SeenRelay 不会为任意调用凭空设定 TTL。不得抑制变更／破坏性操作；通用核心不会根据工具名称、描述或不可信注释推断只读安全性。

对于 MCP 客户端，seenrelay/mcp-auto 可以围绕明确列入允许列表的 callTool() 操作进行一次性绑定。未列入的工具会原样通过。

经典的影子优先路径

原有的 JavaScript/TypeScript 和 Python API 仍然可用。若未明确设置复用策略，它们会执行 CHECK、保留原有验证，并尽力 OBSERVE 独立获取的结果。

const relay = new SeenRelayClient();

const validatePrice = relay.protectValidation({
  fact,
  validate: ({ conditionalHeaders }) => existingValidation(conditionalHeaders)
});

const value = await validatePrice(knownValue);

Python 提供了等效的 protect_validation(...) 路径。如果要在启用经典的有界复用之前，专门衡量公开 CHECK 证据，请使用 Shadow Proof。

源端原生重新验证

优先使用源端原生验证器，而不是猜测数据的新鲜度。当保留的响应带有安全的 ETag 或 Last-Modified 验证器时，后续符合条件的验证可以尝试使用 If-None-Match 或 If-Modified-Since。304 Not Modified 响应是源端的确认，而不是 SeenRelay 的确认。

传统的 CHECK/OBSERVE 路径也可以携带观察者提供的 ETag / Last-Modified 元数据，作为明确标注为未验证的条件请求提示。是否需要源端确认仍由调用方决定。

可选的私有 L1

JavaScript/TypeScript Zero-State 可以使用调用方提供的私有存储和编解码器，实现跨工作进程或重启后的复用。SeenRelay 提供 AES-256-GCM 编解码器辅助工具；调用方负责管理密钥、存储和命名空间。

启用私有 L1 并不会使私有值被发送到公共 SeenRelay 服务。存储或编解码器发生故障时，会放行并进入应用程序的正常验证路径。

事实身份

SeenRelay 使用版本化的 seenrelay-fact-v3 身份契约。身份优先级如下：

1. 稳定的源端原生定位符（json_pointer、element_id、source_key）；
2. 在没有稳定定位符时，使用规范化的机器谓词。

人类可读的 subject 文本和可变的观测内容不会进入事实键。源 URL 会在不浏览的情况下按确定性规则进行规范化。含有凭据或签名的源 URL 会在状态准入前被拒绝。

完整契约请参阅 docs/PROTOCOL.md。

观察者来源证明

OBSERVE 支持可选的、独立于传输方式的 ed25519-v1 持有证明。有效证明可以确认密钥持有情况、连续性和载荷完整性，但不能确认法律身份、现实世界中参与者的独立身份或事实真伪。

即使不同调用方收到了中间服务提供商缓存命中的结果，也不会因此将其重新标记为新的独立 OBSERVE。

访问与贡献

SeenRelay 无需创建账户即可签发签名的临时运营租约。目前，CHECK 和 OBSERVE 均可免费使用。贡献积分依据后续符合条件的复用情况，而非原始提交量计算。

Hive 类别仅描述运营贡献，不代表身份或真伪评分。

公共接口

规范域名为 seenrelay.com。

• 浏览器通过 / 请求 Accept: text/html 时，会收到公共首页。
• 对 / 的通用/API 请求会收到机器描述符。
• /service.json 提供显式机器描述符。
• /public-stats.json 提供隐私安全的汇总活动数据。
• /openapi.json 提供 REST 契约。
• /mcp 提供 MCP 2026-07-28。
• /quickstart 和 /clients 提供集成说明。

产品边界

SeenRelay 本身不会浏览或搜索事实来源、执行按需外部验证、调用大模型判断真伪，也不会提供共享的通用 Agent 记忆。UNKNOWN 仅表示当前没有足够新且可复用的共享观测结果。

客户端适配器可以使用源端原生验证，或与现有提供商集成，但提供商适配器是可选的，不能成为与提供商无关的核心组件的依赖。

架构

• Vercel 托管部署
• Neon Postgres 状态存储
• Hono + TypeScript / Node 22
• REST/OpenAPI
• 通过官方 v2 服务器 SDK 提供 MCP 2026-07-28
• 与提供商无关的 JavaScript/TypeScript Zero-State 客户端，以及传统的 JavaScript/TypeScript 和 Python 封装
• 仅供经过身份验证的人员使用的 Control Room，用于运行时操作和事件控制

我们会监测 A2A，但不会将其宣传为已实现的产品接口。

验证

npm run check 会执行 TypeScript 检查、产品防护检查、生产依赖审计、结构测试和运行时测试。Package Validation 会全新安装构建好的 npm/PyPI 构件。Preview Release Gate 还会针对所需的 Preview 运行时提交，测试 REST、MCP、事实身份、安全边界、运行时控制和复用计量；只有在所有中间提交都不属于 Vercel 运行时边界时，才接受更新的服务 SHA。

构建使用已提交的锁文件和 npm ci。

维护

Dependabot 和 Standards Watch 会准备相互隔离的维护工作。生产变更仍须通过兼容性、安全、CI 和 Preview 验证门禁。

引导

npm ci
npm run check
# DATABASE_ADMIN_URL must be set only for this migration command
npm run db:migrate

部署详情请参阅 docs/DEPLOYMENT.md。