Graviti

graviti-engine

Graviti 背后的确定性评分引擎。Graviti 是 Singulariti 构建的 Agent 驱动商业信任基础设施，详见 Graviti。这个仓库的存在，是为了让网站的核心主张（“评分接受公开审计”）可以被验证，而不只是口头声明：这里的 src/engine.ts 是生产环境中为每条推荐排序的确切模块——MCP 服务、Web 控制台和公共端点都导入这同一个文件。不存在私有的排序路径。

不到一分钟即可在任意 Agent 中使用

Graviti 通过两种路径提供 MCP 服务；两种路径都通过这个确切的引擎提供相同的七种工具（match_intent、get_verified_claims、category_landscape、get_accountability_log、get_ledger、get_gap_report、report_conversion）。

远程（最快）——托管的 Streamable HTTP 端点，无需身份验证，无需账户：

{ "mcpServers": { "graviti": { "url": "https://graviti.thesingulariti.ai/api/mcp" } } }

本地——通过标准输入/输出使用 graviti-mcp npm 包：

{ "mcpServers": { "graviti": { "command": "npx", "args": ["-y", "graviti-mcp"] } } }

该软件包附带索引快照，并会在启动时获取最新发布的索引，并根据签名账本进行验证——固定密钥、两条独立的账本路径以及重放保护，采用的程序与下文的 scripts/verify-payload.mjs 相同。遭到篡改或重放的有效载荷绝不会被使用。（Claude Desktop：claude_desktop_config.json；Cursor：.cursor/mcp.json；其他客户端的接入说明见 graviti.thesingulariti.ai/use-graviti。）

两条准则

1. 验证收费，排序绝不收费。 品牌付费购买对其声明的持续独立审计。验证状态对排序的权重为零——阅读 matchIntent() 中拟合分数的构造，确认其中没有引入任何付款信号。
2. 付款换取速度，绝不影响结果。 品牌可以付费加快重新评估；付款只会缩短等待时间，绝不会改变判定结果。

与品牌信誉挂钩的评分调整仅有固定且公开的生命周期惩罚（LIFECYCLE_PENALTY）：被标记 −0.05、状态降级 −0.15。这些惩罚由受监控的质量信号触发，绝不取决于付款状态；被撤销资格的品牌则完全不会参与评分。

阅读此代码即可验证的内容

• 评分具有确定性。 引擎只对品牌索引执行纯函数运算——没有 I/O、网络、随机性或学习参数。引擎的输入只有索引、问题文本和可选的意图档案。相同输入，每次都会得到相同分数。
• 转化数据不会进入评分。 引擎没有转化数据输入——在此文件中搜索任何与转化相关的内容，都找不到。归因转化事件只存在于私有传输层中，纯粹用作账单记录（按真实获客收费）；从结构上说，它们不可能影响拟合分数，因为此模块根本不会接触这些事件。
• 可根据公开数据复现分数。 此引擎在生产环境中使用的完整索引是公开的。将引擎指向该索引，即可精确复现生产环境中的分数：
  • https://graviti.thesingulariti.ai/index.json — 清单（总数、披露信息、类别列表）
  • https://graviti.thesingulariti.ai/index-full.json — 一次请求即可获取完整索引；这是完整性账本进行哈希计算的确切内容
  • https://graviti.thesingulariti.ai/ledger.json — 只追加、哈希链式、由 Ed25519 签名并锚定于 Bitcoin 的版本历史
• 每个有效载荷都包含结构化披露信息。 参见 disclosure()：rank_influenced_by_payment: false、哪些人付了款、哪些人没有付，以及付款能换来什么——每个响应中都包含机器可读的信息。
• 超出范围的问题会得到拒绝答复，而非猜测。 参见 matchIntent() 中的 in_index: false 分支。

运行

npm install
npm run demo -- "best magnesium supplement"
npm run demo -- "cheapest cold plunge with a chiller"
npm run demo -- "best magnesium supplement" --json     # the full machine payload agents receive

该演示会在 data/sample-index.json 上运行引擎。这是公共索引中一小部分真实数据（五个类别、约 100 个品牌，包含声明、来源 URL 和问责日志）。如需查看完整内容，请获取 index-full.json 并替换该文件——引擎接受任意 BrandIndex。

运行金丝雀测试

npm run canary

Graviti 采用基于金丝雀的漂移检测：每次生产构建都会将已知真实情况的测试对象送入系统（面板 A——黄金路由查询、结构不变量，例如任何地方都不得出现 NaN 分数和目录层级的品牌绝不排名，以及著名答案绝不能胜出的对抗性案例），每个周期也会将其送入审计爬虫（面板 B——该网站控制的三个来源页面：一个保持稳定、一个刻意漂移、一个刻意消失）。面板 A 出现偏差会导致构建失败；面板 B 误读则意味着传感器本身出现故障，该爬取周期不会刷新任何真实声明。两个面板由不同团队独立维护，确保彼此都不会成为对方的真实依据。

scripts/canary-panel-a.ts 是面板 A 的公开子集——这些案例受示例索引支持，并在本仓库发布的原版引擎上运行，因此你无需任何密钥，就能运行构建时执行的相同金丝雀测试。两个面板的实时状态发布在 pulse.json 的 canaries 区块中（可在 /pulse 查看易读版本）。

验证账本

索引的版本历史记录采用哈希链：每条记录都会提交完整索引规范化内容的 SHA-256 哈希和前一条记录的哈希，使用已发布的公钥进行 Ed25519 签名（data/public-key.pem，也可在 /public-key.pem 获取），并通过 OpenTimestamps 锚定到 Bitcoin。改写任何历史记录都会导致其后的所有哈希失效——即使 Graviti 也无法修改该记录。

npm run verify:ledger           # verifies the committed ledger snapshot, then checks it against the live index
npm run verify:ledger -- --live # fetches and verifies the current live ledger instead

该脚本无需密钥，也不依赖 Graviti 运行的基础设施：它会重新计算每条记录的哈希，沿链追溯至创世记录，并使用公钥检查每个签名。可使用开源 OpenTimestamps 客户端，针对 /ots/v<N>.ots 中的证明独立重放 Bitcoin 锚定过程——说明见 llms.txt。

验证你收到的内容 — 传输完整性

账本可以证明哪些内容曾被发布。但它看不到传输管道：终止 TLS 的代理、CDN、缓存和负载均衡器位于 Graviti 的源站与进程之间，其中任何一个都可能更改负载，而账本不会记录这些差异。从账本 v25 开始，每条记录的签名核心都会固定一份涵盖所有已发布负载的 sha256 清单（files.artifacts），因此检查移到了管道的你这一侧。先验证，再信任：

npm run verify:payload                                             # /index-full.json
npm run verify:payload -- /index.json /data/categories/magnesium-supplements.json /llms.txt

scripts/verify-payload.mjs 无需依赖项（Node ≥ 20），任何验证失败都会以非零状态码退出。它会：

1. 从两条独立路径获取账本——此仓库在 raw.githubusercontent.com 上的快照，以及源站的 /ledger.json——验证两条链，并交叉检查头部（如果存在分叉，或源站提供的账本早于公共镜像，脚本会明确报错）；
2. 使用脚本中嵌入的固定签名密钥验证每个 Ed25519 签名——脚本会将提供的 /public-key.pem 与固定密钥交叉核对；如不匹配，就会判定失败，绝不会将其视为信任来源；
3. 重新计算你实际收到的负载的 sha256，并与头部记录中的签名清单进行比较；
4. 防范重放攻击：如果负载与较早记录的清单匹配，而不是与头部记录匹配，那么它虽有有效签名却已过时——脚本会将其报告为单独的失败，因为重放昨天的内容是一种隐蔽攻击。

没有 Node？核心检查只需使用 curl、jq 和 sha256sum 执行两条命令——预期哈希值来自镜像快照（独立路径），实际哈希值则来自到达你的字节：

curl -s https://raw.githubusercontent.com/sclaytonmyosin/graviti-engine/main/data/ledger.json \
  | jq -r '.entries[-1].files.artifacts["/index-full.json"]'
curl -s https://graviti.thesingulariti.ai/index-full.json \
  | jq -cjS 'del(.generated_at, .integrity)' | sha256sum

两个哈希值必须一致。（JSON 负载会先转换为规范形式后再计算哈希——递归排序键、不含空白字符——并删除两个易变的信封字段 generated_at 和 integrity，因为它们分别携带构建时间戳和固定条目自身的哈希，因此不能包含在固定内容中。/llms.txt 则直接对原始字节计算哈希，不经过 jq。）要获得完整保证，还需确认镜像与源站的账本一致，且签名链验证通过——也就是上面的步骤 1–2，或运行 npm run verify:ledger。

坦诚说明边界： 验证通过只能证明到达你进程边缘的字节与 Graviti 签名并锚定到 Bitcoin 的记录一致。验证通过后，没有任何密码学机制能保证数据在你的运行时内部或模型的上下文窗口中仍然不变——如果你自己的技术栈之后修改了数据，发布方一侧的机制无法察觉。请尽可能在接近实际使用的位置进行验证；最后一跳由你负责。

验证 Graviti 流量 — 外发来源归因（适用于品牌）

Graviti 为品牌生成的每个指向其自有网站的推荐链接都会携带确定性的 UTM 参数（utm_source=graviti、utm_medium=<surface: agent|console|scan|landscape|report>、utm_campaign=<category>、utm_content=<brand>），以及经过签名的 gvt 令牌，因此接收流量的品牌可以证明引荐来自 Graviti，而不必信任容易伪造的 UTM 字符串。该令牌（gvt1.<surface>.<category>.<brand>.<YYYYMMDD>.<sig>）使用与账本相同的密钥进行 Ed25519 签名，用于标识推荐的展示场景，而非用户——不包含用户标识符、点击 ID 或单次点击值。完整规范见：docs/ATTRIBUTION.md。

node scripts/verify-attribution.mjs 'gvt1.agent.magnesium-supplements.bioptimizers.20260829.<sig>'
# or paste the full landing URL — the script extracts the gvt parameter

无需依赖项（Node ≥ 20），使用固定密钥，只有签名有效时才会以退出码 0 结束。规范中提供了等效的 openssl 命令。

同步溯源

src/engine.ts、scripts/verify-ledger.mjs（其文件头中注明的实时抓取适配除外）、data/ledger.json 和 data/public-key.pem 与私有 Graviti monorepo 在提交 cf24943（2026-08-26）时的内容保持一致。引擎文件是逐字复制的——重新同步只需复制文件并更新本行；现在每次同步账本快照时都会自动完成。此次同步包含固定评分标准的版本发布：从账本 v26 起，每个条目的签名核心都包含一个 rubric 字段，其中记录了对该条目下发布的每个排名进行评分时所用的确切已提交 src/engine.ts 的 sha256 和 git blob sha1，以及固定该版本的私有仓库提交和本仓库的 URL。这样一来，同步溯源便是可验证的，而非仅仅声明的：

# The engine in this repo must hash to exactly what the signed ledger head pins:
git hash-object src/engine.ts
curl -s https://graviti.thesingulariti.ai/ledger.json | jq -r '.entries[-1].rubric.engine_git_blob_sha1'
# — the two must match byte for byte. Equivalently, with no git:
sha256sum src/engine.ts   # must equal .entries[-1].rubric.engine_sha256

blob 哈希由 git hash-object 根据已提交文件的原始字节计算（不做规范化），因此任何此镜像的检出版本——或固定提交时的私有仓库——都能重现该哈希。因此，评分变更会成为公开且可比较的事件：包含该变更的账本条目会固定新的哈希，而本文件的历史记录则会显示差异。如果此仓库中的引擎未通过该检查，说明镜像不同步（或者你对比的是比当前检出版本更新的账本）；npm run verify:ledger 会执行相同的交叉检查并说明原因。此版本还引入了声明衰减类别：针对每项声明的新鲜度策略（引擎中的 CLAIM_DECAY_CLASSES / CLAIM_DECAY_RULES——快速 45d、中速 120d、缓慢 365d、静态），若声明超过其公开说明的有效期，则会在每个负载中标记为“已过时——待重新验证”，并在声明深度参与评分时按半权重计入——其权重会明显降低，但不会归零，因为过时不等于虚假。

目录结构

src/engine.ts            the engine — types, laws, scoring, disclosure (verbatim production module)
data/sample-index.json   real slice of the public index so the demo runs offline
data/ledger.json         committed snapshot of the public integrity ledger
data/public-key.pem      Ed25519 public key the ledger signatures verify against
demo/run.ts              CLI demo — question in, ranked disclosure-carrying answer out
scripts/verify-ledger.mjs  no-secrets ledger verification (chain, signatures, live index hash)
scripts/verify-payload.mjs client-side transport-integrity check — pinned key, two ledger paths, replay guard
src/attribution.ts       shared outbound-attribution module (UTM scheme, gvt token format, pinned key)
scripts/verify-attribution.mjs  brand-side gvt token verifier — prove a referral came from Graviti
docs/ATTRIBUTION.md      the attribution spec: scheme, token format, signing model, privacy stance

许可证

Apache-2.0 — Copyright 2026 Singulariti.