构建可信的AI知识消费端:open-knowledge-format信任分层、新鲜度门控与attestation拦截完整教程

原创2026-10-19 10:48:471,457 阅读

构建可信的AI知识消费端:open-knowledge-format信任分层、新鲜度门控与attestation拦截完整教程

当 AI Agent 消费知识时,如何判断一段内容是否可信、是否过期、那个数字是否真的由"规定的方式"算出来?open-knowledge-format(OKF)用纯 Markdown + YAML frontmatter 给出了完整答案:verified 字段驱动三级信任分层,stale_after 字段实现新鲜度门控,Attested Computation 概念配合 attester 代码完成 attestation 拦截。本文以仓库内置的 bundles/acme_retail/ 示例为线索,带你一步步看懂消费端该如何"先验证、再展示"。

为什么 AI 消费知识需要"信任机制"

OKF 的定位是让知识语料由 Agent 持续写入、人类与 Agent 共同消费(详见 SPEC.md 第 1 节)。当语料大多是机器生成的,消费端必须回答四个问题:

  • 来源:这段内容从哪来、如何被验证?(provenance)
  • 信任:我该信几分?(trust)
  • 新鲜度:它现在还成立吗?(freshness)
  • 证明:这个数字是按我们规定的方式算出来的吗?(attestation)

OKF v0.2 把前三个问题全部做成 frontmatter 里"可查询的信号",第四个问题做成了一个独立的概念类型 Attested Computation——不需要任何专有运行时,一个会读 YAML 的消费端就能实现完整的信任判断。

信任分层:从 verified 字段推导三个等级

信任分层的原料是 frontmatter 中的 verified 字段(SPEC.md §5.2–5.3)。它是一组"验证事件",每个事件记录谁(actor)在什么时间确认过内容:

verified:
  - { by: human:jsmith@acme, at: 2026-07-01T09:00:00Z }
  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }

注意 generated(谁写的)与 verified(谁确认的)是刻意分开的——写文档的 Agent 和确认文档的人可以不是同一个。OKF 还规定了统一的 actor 写法:Agent 用 <producer>/<version>(如 reference_agent/gemini-2.5-pro),人类用 human:<id>,自动流程用 process:<id>。

三级信任等级的判定规则

信任等级 判定条件 含义
unverified 没有 verified 字段 从未被确认,只能参考
machine-confirmed verified 里只有非 human: 的 actor 被自动化流程确认过
human-reviewed verified 里存在 human:<id> actor 有真人签核,最高等级

消费端如何落地这套规则?参考实现就在 src/reference_agent/bundle/document.py 的 trust_tier():它先做一件容易踩坑的事——把裸映射形式的 verified 归一化成单元素列表(规范 §5.2 要求消费端必须兼容 verified: { by: ..., at: ... } 这种不带列表 - 的写法),然后扫描所有事件,只要出现 human: 前缀就直接返回 human-reviewed,否则返回 machine-confirmed。

仓库里的真实例子:bundles/acme_retail/metrics/revenue.md 中 verified: <a href="https://link.gitcode.com/i/768c5ef71fe7bf629d533b995b28c051" target="_blank">{ by: human:jsmith@acme, ... }] 由 VP Finance 签核,因此这个 Revenue 指标是最高等级 human-reviewed;而 [bundles/acme_retail/computations/gross-margin-period.md 同样是 human:jsmith@acme 确认。一个对照示例是附录中的 profit 计算,verified 由 process:finance-nightly 确认,只能拿到 machine-confirmed(见 SPEC.md 附录 A)。

⚠️ 一个关键原则(规范 §5.3、§11):信任等级是建议性信号,不是访问控制。缺少 verified 的概念仍然可以消费,消费端 MUST NOT 因为它而拒绝文档。

新鲜度门控:一个时间戳比较就够了

OKF 用 stale_after 字段回答"这条知识现在还有效吗"(§5.5):

stale_after: 2026-12-31T00:00:00Z   # 从这一刻起内容视为过期

设计上有两个巧妙之处:

  1. 用绝对时刻而不是相对 TTL。判断逻辑只是 now >= stale_after,不需要关心"这份文档是什么时候被读到的",任何消费端做同一个普通比较即可。
  2. 语义与业务评审周期绑定。在 bundles/acme_retail/computations/revenue-ytd.md 里,stale_after: 2026-12-31T00:00:00Z 直接镜像了收入确认政策的年度评审周期——2027-01-01 之后,消费端运行这份计算就应该提示"先重新验证再对外服务"。

消费端的新鲜度判断实现

参考实现在 src/reference_agent/bundle/document.py 的 is_stale(),它比"取个日期比一下"更严格:

  • 只接受带 T 分隔符的完整 ISO 8601 时间戳;
  • 必须带显式 UTC 偏移——因为 2026-12-31 这种"光日期"在每个时区都指向不同时刻,宁可直接忽略也不瞎猜;
  • 解析失败或字段缺失一律返回"新鲜"(返回 False),保证不会因为格式问题误伤正常文档。

让新鲜度"看得见":viz.html 的门控徽章

本仓库自带的可视化工具就是一个"消费端"的完整示范。生成器 src/reference_agent/viewer/generator.py 在扫描每个概念时同时调用 trust_tier(fm) 和 is_stale(fm),把两个信号写进节点数据;前端 src/reference_agent/viewer/static/viz.js 随即渲染出徽章:

  • status 徽章:draft / stable / deprecated(缺省视为 stable);
  • 信任徽章:unverified / machine confirmed / human reviewed;
  • 新鲜度徽章:已过期时显示 stale (since 2026-12-31T00:00:00Z),未过期则显示 stale after ... 的"保鲜期"。

用 visualize 子命令生成(输出到 bundles/acme_retail/viz.html),点选任意概念就能看到它的完整信任画像——这正是"把门控结果暴露给用户"的规范建议(§10.5 第 6 步)。

生命周期还有一个姊妹字段 status(§5.4):draft / stable / deprecated。看 bundles/acme_retail/metrics/gross-margin-legacy.md 就是典型用法——旧版毛利率定义被标记为 status: deprecated,保留文档是为了历史报表可复现,但正文明确写着 "Do not use for new analyses",而且它没有对应的 Attested Computation:退役时其 SQL 已从授权计算集中删除。新旧版本各管一段,靠 status 和链接互相指向。

attestation 拦截:Attested Computation 与 executor / attester

前面两层解决"文档可信吗、还新鲜吗",但还有个更锋利的问题:Agent 报出的那个数字,真的来自授权的计算吗? 还是它随手即兴写了一段 SQL?

这就是 OKF v0.2 引入 type: Attested Computation 概念的原因(§10)。一次"授权计算"是一个独立概念,frontmatter 里携带完整的执行契约:

  • runtime:如何运行(bigquery、dbt、python……),它决定了 parameters 的绑定语义;
  • parameters:Agent 允许填写的类型化"洞",Agent 只能给参数填值,绝不能改写计算本身;
  • computation(可选):计算体所在文件路径,缺省则取正文 # Computation 代码块;
  • executor:指向执行说明/代码,receipt 声明本次运行必须返回的凭据字段;
  • attester:指向确定性、无 LLM 的检查代码,在消费端运行。

一次完整的 attestation 流程(以 Revenue 为例)

以 bundles/acme_retail/computations/revenue-ytd.md 为主线,整个流程是六步(规范 §10.5):

  1. 发现(Discover):通过 type: Attested Computation 检索,或顺着 metrics/revenue.md 里的链接走到它——指标文档明确要求"消费端 MUST 运行并验证该计算,而不是自己拼一个 SUM"。
  2. 加载(Load):从 frontmatter 读契约,从 # Computation 代码块读授权 SQL(这里实现了 FY2026 收入确认政策的四条规则,政策原文见 policies/revenue-recognition.md)。
  3. 参数化(Parameterize):Agent 只填声明过的参数,本例唯一参数是 year。
  4. 执行(Execute):executor 指向 skills/run-on-bq.md——一份"如何提交 BigQuery 作业"的 Skill 说明,要求用命名参数绑定(禁止字符串拼接)、等待作业完成,最后严格按 receipt: [job_id, executed_sql, result] 返回凭据,其中 executed_sql 必须是作业实际执行的 SQL。
  5. 验证(Attest):消费端运行 attesters/sql_equality.py,做两项机械检查:
    • Provenance(来源):把 receipt 里的 executed_sql 与授权 SQL 各自"规范化"(去注释、折叠空白、SQL 关键字统一大写)后做相等比较。换表、加过滤条件、丢掉一个 JOIN,都会失败;
    • Fidelity(保真):即将展示给用户的值必须等于 receipt.result 的第一个单元格——数字以凭据为准,不取 Agent 的文本描述。
  6. 门控(Gate):verdict.ok 为 False 时,消费端 MUST 拒绝展示该值;若 now >= stale_after,则警告或拒绝服务。成功时把判定依据(如 job_id 链接到作业日志)展示出来,让信任可见。

为什么"参数化 + 规范化比较"能拦下篡改

规范 §10.3 点出了精髓:消费端拿参数值把授权计算绑定成可执行工件,而 attester 独立地重新推导同一个绑定,再与 receipt 里实际运行的 executed_sql 比较。比较发生在展开编译后的工件上,所以"改写查询、偷换计算文件、篡改依赖"任何一种操作都过不了这一关。类型化、只允许传参的接口,把"授权的计算真的跑了吗"从判断题变成了机械比较。

另外注意 §10.6 的重要区分:verified 确认的是定义是否仍符合政策(文档级、慢、记录在 bundle 里);attestation 确认的是单次运行是否以授权方式产出了数值(每次调用、运行时、不存 bundle)。两者独立,缺一不可——定义过期的概念仍可干净地通过 attestation,而刚签核过的定义每次运行照样要验证。

消费端实现清单:MUST / SHOULD 速查

写消费端时,规范(§11、§10.5)划了明确的红线,这里整理成清单:

  • ] 裸映射形式的 verified 必须当作单元素列表处理(参考 [document.py 的 normalize_verified())
  • [ ] 不因缺少任何可选字段(trust/lifecycle/provenance 家族)而拒绝概念
  • [ ] 信任等级与过期状态只从本规范指定的字段推导
  • [ ] attestation 失败时暴露失败而不是静默丢弃("surface, not silently drop")
  • [ ] stale_after 只认带时区的 ISO 8601 时刻
  • [ ] 容忍未知 type、未知扩展字段、断链、缺失的 index.md

更多工程细节可以参考测试 tests/test_document.py 与 tests/test_viewer.py,它们覆盖了文档解析、frontmatter 处理与可视化信号生成的行为边界。

小结

open-knowledge-format 的"信任栈"可以浓缩为一句话:provenance 回答"从哪来",trust 分层回答"信几分",stale_after 回答"还新吗",attestation 回答"这个数是不是按规定算的"——全部落在纯 Markdown 与 YAML 里,消费端无需任何专有基础设施。

想动手验证的话,仓库已经备好了一切:从 bundles/acme_retail/index.md 出发,逐层看 metrics → computations → skills → attesters 的引用链;或用 visualize 子命令生成 bundles/acme_retail/viz.html,直观看到每个概念上的 trust / stale 徽章。规范全文在 SPEC.md,尤其是 §5(信任与生命周期)与 §10(Attested Computation),附录 A 的利润表实战示例更是把四个信号家族一次用全了。

登录后查看全文
open-knowledge-format