基准事实:把 AI 智能体锚定在现实之中

本文中的数字反映的是发布时(2026 年 1 月)的系统状态。如需查看最新数据,请参阅我们的 团队页面。

AI 智能体的能力相当出色,它们能推理、能综合、能生成。但它们有一个根本性的弱点:会编造东西。不是出于恶意,而是自信满满地编造。一个智能体可能会凭空发明并不存在的 API 参数,引用从未被定义过的配置,或者套用训练数据里的某种模式——而这种模式恰恰与你真实的架构相矛盾。

标准的应对办法是“给智能体更多上下文”。但上下文本身也可能是自相矛盾的:文档会与实现产生偏差,注释会撒谎,甚至代码本身,如果脱离了对意图的理解去阅读,也会产生误导。

我们需要一种更明确的东西——一种无法被忽略、也无法被曲解的东西,一种能把智能体锚定在可验证现实之上的东西。

我们把它称为基准事实。

什么是基准事实?

一条基准事实,是一条智能体必须遵守的、明确的、带版本的事实陈述。它不是文档,也不是注释,而是系统中的一等实体,具备:

• 唯一标识符(例如 GT-MAG-015 或 GT-MAG-036)
• 生命周期状态(current、tentative 或 deprecated)
• 作用域(全平台、特定包,或限定在某个领域内)
• 证据(能证明该陈述的文件路径、URL 或引用)
• 智能体指引(明确的“该做”与“该避免”指示)

下面是一个来自我们 Maguyva 代码智能平台的示例:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

这不是散文,而是一份契约。当智能体遇到这条基准事实时,它就知道:

1. 默认行为是确定性的(返回空结果,而不是模糊猜测)
2. 存在具体的参数(find_similar、exact_match),各自有明确定义的行为
3. 证据存在于可以核实的具体文件中
4. 该陈述是在某个具体日期被核实过的

一份基准事实注册表的结构

基准事实存放在 ai_assets/reference/ground_truths.yaml 下的 YAML 注册表中。每个包或领域都可以拥有自己的注册表。其结构如下:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

这份注册表包含关于集合本身的元数据、用于生成文档的渲染配置,以及陈述内容本身。每条陈述都遵循一套由 Pydantic 模型校验的严格 Schema:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

智能体如何访问基准事实

基准事实通过多个渠道对外暴露:

1. 渲染后的文档

orkestra sync 命令会把 YAML 注册表转换成可读的 Markdown:

uv run orkestra sync

这会生成 GROUND_TRUTHS.md 文件,并被纳入智能体的上下文中。渲染后的输出会按状态和类别对陈述进行分组:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI 搜索

拥有 Shell 访问权限的智能体,可以通过编程方式搜索基准事实:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

搜索函数会在多个字段上按加权相关度为匹配结果打分:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. 上下文组合

当智能体从 YAML 定义渲染出来时,它们的上下文可以引用基准事实注册表:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

这确保了相关的基准事实,会在智能体开始工作之前就已经加载完毕。

基准事实的分类

纵观我们的各个注册表,基准事实大致可以归纳为几种模式:

产品原则

界定产品是什么、不是什么的约束:

“Maguyva 相对于用户代码仓库是只读的;唯一不可重建的资产是付费的 Embedding 缓存。”(GT-MAG-001)

架构边界

职责归属何处、为什么如此划分:

“Pipeline 与 Maguyva 之间的边界是刻意设计的:Pipeline 是可复用的,Maguyva 承载特定于代码的逻辑,而 CQRS 把阶段性写入和服务端读取分离开来。”(GT-MAG-006)

反幻觉规则

让工具契约保持确定性、而非靠推断的明确规定:

“模糊符号匹配需要通过 find_similar=true 主动开启。默认行为对不存在的符号返回空结果;exact_match=true 强制执行严格匹配,并禁用所有模糊回退。”(GT-MAG-015)

质量门禁

必须持续维持的标准:

“对共享基础设施(post_filters.py、关系提取器、共享处理器)的改动,提交前必须通过全量清单生成,针对所有支持的语言进行验证。仅针对单一语言的验证,对共享代码来说是不够的。”(GT-MAG-036)

代码模式

实现层面的要求:

“在异步上下文中处理 CPU 密集型工作时使用 asyncio.to_thread();已废弃的 loop.run_in_executor() 模式不应再用于新代码。”(GT-MAG-018)

基准事实的生命周期

基准事实并非一成不变,它们会经历一个明确定义的生命周期:

Tentative(暂定)

一条正在评估中的拟议事实。该陈述会被记录下来,但仍可能发生变化:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current(现行)

一条已被核实、智能体必须遵守的事实。其证据已经过验证:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated(已废弃)

一条不再适用的事实。出于历史参考的目的被保留下来,并附有指向其替代内容的指引:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

为什么不干脆只用文档?

文档服务于另一个目的:它负责解释,负责教学,可以是含糊的,可以使用“通常”“一般来说”这类限定词。

基准事实不能含糊。它们是断言,要么适用,要么不适用。

来看看这种区别:

文档:“当找不到某个符号时,API 通常会返回空结果,不过在某些配置下可能会启用模糊匹配。”

基准事实:“默认行为对不存在的符号返回空结果;exact_match=true 强制执行严格匹配,并禁用所有模糊回退。”

第一种说法,对正在学习这套系统的人类很有帮助;第二种说法,对正在做决策的智能体是可以直接采取行动的。

智能体指引:该做与该避免

一些基准事实会包含明确的智能体指引:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

这消除了歧义。读到这条内容的智能体,不仅知道什么是事实,还知道这个事实意味着该采取什么行动。

验证与维护

基准事实需要持续维护。我们会追踪:

• last_verified:上一次有人确认该陈述仍然成立的时间
• evidence:能证明该陈述的文件(可以核实其是否存在)
• source:这条事实的来源(CLI 检查、架构评审,或事后复盘所得的教训)

如果一条基准事实的验证日期已经过时,或者证据链接已经失效,这就是一个需要排查的信号——要么这条事实依然成立、只是需要重新核实,要么现实已经发生了变化、这条事实需要更新。

来自生产环境的真实示例

安全边界

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

这条基准事实,防止了一整类会破坏产品的、方向搞错了的“安全改进”。

提取阶段的准确性

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

这是一条来自痛苦经验的教训。智能体曾经会通过添加仅作用于校验器的过滤器,来“修补”失败的语言包,让测试框架看起来更绿了,但线上真正运行的 Maguyva 提取器,依然在产出错误的边。这条规则强制把修复推回真正的路径上:YAML 配置、查询,或处理器本身。

多层过滤

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

这防止了智能体在错误的位置添加过滤器——这是一个常见的错误,曾经导致过准确率的回归。

与编排系统的集成

基准事实是一套更广泛上下文体系中的一层:

1. 架构决策(ADR) —— 记录我们为什么选择方案 A 而非方案 B
2. 基准事实 —— 陈述此刻确凿为真的事实
3. 领域模式(Domain Patterns) —— 描述如何把事情做对
4. 反模式(Anti-Patterns) —— 描述应该避免什么、为什么要避免

在系统中工作的智能体,能够访问全部这四层。基准事实提供事实层面的锚点,决策解释历史脉络,模式指导具体实现,反模式则警示可能踩到的陷阱。

衡量成效

自从引入基准事实以来,我们观察到:

• “修复那个基于幻觉的修复”这类循环变少了
• 当事实清晰时,智能体的决策会更有把握
• PR 评审质量提升了,因为预期变得明确
• 新智能体(以及新人类)的上手时间缩短了

维护基准事实所投入的成本,换来了更少的调试和更清晰的系统边界。

快速上手

要为你的系统添加一条基准事实:

1. 在你的包的 ai_assets/reference/ 目录下创建一个 ground_truths.yaml
2. 定义元数据和渲染配置
3. 按照 Schema 添加陈述内容
4. 运行 uv run orkestra sync 生成文档
5. 把这份注册表纳入智能体的上下文组合中

先从那些最容易引起混淆的事实、或者最常被违反的约束入手,那些才是你价值最高的基准事实。

结语

AI 智能体会产生幻觉,这是它们的天性。但我们可以创造出这样的环境:幻觉被约束住,某些事实是不容商量的,智能体可以拿自己的假设去对照已验证的现实。

基准事实并非一个完整的解决方案。它们需要维护,可能会过时,也会给开发流程增加一些开销。

但它们提供了一样宝贵的东西:一套人类和智能体都能信任的、共享的事实词汇表。在一个智能体日益深度参与软件开发的世界里,这个共享的基础变得至关重要。

另一种选择,是让智能体不断自信满满地犯错、再让人类不断去纠正,循环往复。基准事实打破了这个循环,让纠正变得明确、持久。

你的智能体值得知道什么是真的。那就告诉它们。