trigsight

一个无法对其工作成果做出无法证实之主张的 AI 助手。

它生成的每一条陈述，在构建时都会绑定到支持该陈述的确切句子。 点击引用会滚动到源页面中的该句子并高亮显示。 如果被引用的段落不存在于源文档中，构建 失败 —— 无法验证的主张不可发布。

为什么存在

作品集聊天机器人会对其作者的胜任能力做出各种主张。读者没有理由 去信任这些主张，而且有充分的理由不去验证：经测量，通用 AI 搜索的引用错误率高于 60%，且仅有 51.5% 的生成句子能完全得到 其引用来源的支持。因此，这些主张会被打折扣，引用功能也沦为装饰。

常规的解决办法是让模型基于语料库生成内容并寄希望于结果。这能缓解 幻觉问题，但无法解决验证问题 —— 读者得到的仍然只是一个链接， 指向整个页面，还得自己费力寻找支持具体主张的句子。

本项目颠覆了信任模型。模型从不写链接，而是指明段落；构建 过程会对照文档实际内容的索引来解析这些段落，解析失败则拒绝 发布。

Related MCP server: CiteGuard

实测结果

JavaScript 体积减少 2.8 倍，且带有 3D 场景。两个数字均为线上 brotli 传输体积，使用同一测试工具测量，各运行三次 —— 详见 docs/05-results.md， 其中解释了为何不同的测量方式会得出 3.4 倍这一偏差数据。

检索效果，30 条人工编写的黄金查询，k=5：

真实嵌入使用 text-embedding-3-small，1536 维，余弦相似度，通过 Upstash Vector 提供。 三次运行结果完全一致。值得注意的变化是：召回率并未提升，提升的是排序。 在这个 语料库规模下，真实嵌入并不能找到更多相关块，而是将已找到的块排得 更靠前 —— 而这才是关键指标，因为只有排名前六的块会进入模型上下文。

保障机制如何运作

flowchart TB
  subgraph build["BUILD"]
    MDX["content/*.mdx"] --> N["normalise: collapse whitespace, casefold"]
    N --> IDX["passage index"]
    IDX --> VER{"every cited passage present exactly once?"}
    VER -->|no| FAIL["EXIT 1 — build fails"]
    VER -->|yes| OK["allowlist.json"]
  end
  subgraph run["REQUEST"]
    Q["question"] --> R["hybrid retrieve: BM25 + vector, RRF"]
    R --> M["model"]
    M -->|emits a cite token| RES{"in allowlist?"}
    OK --> RES
    RES -->|yes| CHIP["chip with text-fragment deep link"]
    RES -->|no| DROP["dropped"]
  end

模型没有任何机制去生成 URL，因此它不可能生成错误的 URL。 提示词中的指令只是请求；能力的缺失才是不变的保证。

比看起来更棘手的部分

浏览器对 #:~:text= 的匹配是基于渲染后的文本进行的，而指令的 每一部分都必须位于单个元素之内。这带来两个实际调试 成本：

• 直接对比原始源代码，7 个段落中有 3 个无法匹配，而浏览器却能正常匹配 —— 这些段落要么跨行，要么包含折叠的空白字符，要么大小写不一致。 一个会产生误报的验证器，会诱使你干脆禁用它。

• 跨越内联标记的段落会被渲染为多个独立的 DOM 节点，导致完全无法匹配， 即使将文本展平后内容确实存在。34 条引用中有 2 条属于 这种情况：报告为已绑定，实际却无法匹配。只有抓取每一个构建后的 页面并搜索其文本才能发现。

现在这两类问题都通过回归测试得到了强制约束。验证器还要求每个段落 恰好出现一次，当存在歧义时通过前缀来消解 —— 否则 浏览器会静默滚动到错误的出现位置，这是一个看起来正常 实则错误的正确性缺陷。

快速开始

npm ci
npm run dev          # http://localhost:3000

无需任何凭据。没有 AI_GATEWAY_API_KEY 时，聊天端点会返回 检索到的上下文而非答案，因此检索过程可以独立检查。

自行验证

npm run verify:citations                 # the gate: exits 1 on any unbound claim
npx tsx bench/citations/verify.ts --demo # watch it reject a fabricated passage
npm run eval:retrieval                   # recall@5 and MRR over the golden set
./bench/payload/measure.sh 3990 150      # initial JS against the budget
npm test                                 # 91 tests

上面每一个数字都来自这些脚本。bench/ 目录已被提交且从未被 gitignore —— 一个未提交的测试工具会让真实结果变成无法验证的主张。

MCP 服务器

POST /api/mcp —— 无状态 Streamable HTTP，规范版本 2026-07-28。四个只读 验证工具，而非描述性工具：

find_evidence 最初验证的是*“离子阱上的量子密码学研究”*这一说法。向量 检索本质上是最近邻搜索：它总是返回最接近的块，哪怕这些块 毫不相关。一个基于此构建的智能体会不断重复伪造的凭据。现在的实现 要求真正的词法重叠，以 8/10 的真阳性和 0/6 的假阳性为标准， 基于人工编写的声明集合进行校准。

局限性

直说吧，因为读起来像营销的局限性说明毫无价值。

• 相对于纯词法检索的优势仅为一个查询的差距。 在 34 个块和 30 条黄金查询中， 一个查询就价值 0.033 的召回率 —— 因此混合检索与词法检索之间 0.034 的召回率差距 仅仅是一条查询。不要将此表解读为混合检索在总体上更优。它只能说明 混合检索不差，并且在这个语料库上排序更好。

• 我之前的预测是错的，而这个错误很有启发性。 我曾预测真实 嵌入能修复那条未命中的查询。结果并没有。单独探查向量 检索后发现，正确的块从未进入其前 5 名 —— 因为该块长达 1,340 个字符，涵盖五个主题，而答案只是其中 871 个字符处的一个子句。它的 单一向量是五个主题的平均值。这是分块问题，而非嵌入 问题，任何模型都无法修复它。我选择记录这一事实而非修补它，因为修改 分块器会使本表所依赖的对比失去意义。 参见 bench/retrieval/results/real-embeddings-2026-08-21.md。

• 没有凭据时，向量检索会退化为确定性替代方案，这并非 语义模型。检索仍然通过 BM25 给出答案，但质量确实更低 —— 测试工具会在每次运行时记录后端类型，因此任何数字都不能脱离 其运行环境被引用。

• 文本片段本质上是脆弱的。 改写一个被引用的句子会破坏其 链接。这正是构建门禁的意义所在 —— 你不能带着损坏的引用发布 —— 但这 也意味着编辑文字时往往需要同步更新引用。

• 引用必须位于单个块级元素之内。 如果一个主张的最佳支持文本 跨越了表格行和段落，就无法将其作为单一引用段落来引用。

• 语料库很小（6 篇文档，34 个块）。这里的检索数字不应 被解读为大型语料库上的性能预测。

• 不支持流式引用解析。 引用标签在消息完整生成后才会渲染，而非 在流式输出过程中。

技术栈

Next.js 16.3.1 · React 19.2.8（锁定版本 —— R3F 9 的 peer 依赖为 >=19 <19.3）· TypeScript · Tailwind v4.3.3 · Velite + Zod · three 0.185.1 + R3F 9.7.0（锁定版本）· Vercel AI Gateway

许可证

MIT —— 参见 LICENSE。