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

Canonical source: https://maguyva.ai/zh-hans/blog/ground-truths-anchoring-ai-to-reality

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-13 · Author: Maguyva Team

> AI 智能体会自信满满地产生幻觉。基准事实是带版本、有明确作用域的事实，能把智能体的行为锚定在现实之中。以下是我们如何构建并落实它们。

> *本文中的数字反映的是发布时（2026 年 1 月）的系统状态。如需查看最新数据，请参阅我们的 [团队页面](/zh-hans/team)。*

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

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

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

我们把它称为基准事实。

## 什么是基准事实？

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

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

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

```yaml
- 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 注册表中。每个包或领域都可以拥有自己的注册表。其结构如下：

```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:

```python
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:

```bash
uv run orkestra sync
```

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

```markdown
## 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 访问权限的智能体，可以通过编程方式搜索基准事实：

```bash
uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current
```

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

```python
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 定义渲染出来时，它们的上下文可以引用基准事实注册表：

```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（暂定）
一条正在评估中的拟议事实。该陈述会被记录下来，但仍可能发生变化：

```yaml
- 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（现行）
一条已被核实、智能体必须遵守的事实。其证据已经过验证：

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

### Deprecated（已废弃）
一条不再适用的事实。出于历史参考的目的被保留下来，并附有指向其替代内容的指引：

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

## 为什么不干脆只用文档？

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

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

来看看这种区别：

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

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

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

## 智能体指引：该做与该避免

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

```yaml
- 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 检查、架构评审，或事后复盘所得的教训）

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

## 来自生产环境的真实示例

### 安全边界
```yaml
- 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.
```

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

### 提取阶段的准确性
```yaml
- 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 配置、查询，或处理器本身。

### 多层过滤
```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 智能体会产生幻觉，这是它们的天性。但我们可以创造出这样的环境：幻觉被约束住，某些事实是不容商量的，智能体可以拿自己的假设去对照已验证的现实。

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

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

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

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