# 根基真相：讓 AI 代理扎根於現實

Canonical source: https://maguyva.ai/zh-hant/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-hant/team)。*

AI 代理的能力令人驚豔，能夠推理、統整、生成內容。但它們有一個根本弱點：會憑空捏造。不是出於惡意，而是自信滿滿地捏造。代理可能會發明根本不存在的 API 參數、引用從未定義過的設定，或是套用訓練資料中與你實際架構相牴觸的模式。

常見的緩解方式是「給代理更多情境資訊」。但情境資訊本身可能自相矛盾：文件會與實作脫節，註解可能說謊，就連程式碼本身，若不理解其意圖，讀起來也可能誤導人。

我們需要更明確的東西——一種無法被忽略、也難以被誤解的東西，能讓代理扎根於可驗證的現實。

我們稱之為根基真相（Ground Truths）。

## 什麼是根基真相？

根基真相是一項明確、經過版本控管的事實陳述，代理必須予以尊重。它不是文件，也不是註解，而是系統中的一級實體，具備：

- **唯一識別碼**（例如 `GT-MAG-015` 或 `GT-MAG-036`）
- **生命週期狀態**（現行、暫定或已淘汰）
- **範圍**（平台全域、特定套件或特定領域）
- **佐證**（能證明該陳述的檔案路徑、網址或參照）
- **代理指引**（明確的「該做」與「該避免」指示）

以下是我們 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 模型驗證的嚴格結構描述：

```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 搜尋

具備殼層存取權的代理可以透過程式化方式搜尋根基真相：

```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 對使用者的程式碼庫僅有唯讀權限；唯一無法重建的資產是付費的嵌入快取。」（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）

## 根基真相的生命週期

根基真相並非一成不變，而是會經歷明確定義的生命週期：

### 暫定
一項尚在評估中的擬議真相，陳述已被記錄，但仍可能變動：

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

### 現行
一項代理必須遵守的已驗證真相，佐證已通過驗證：

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

### 已淘汰
一項已不再適用的真相，出於歷史紀錄目的而保留，並附上指向其後繼者的指引：

```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. **領域模式** — 描述如何正確完成某件事
4. **反模式** — 描述該避免什麼、以及原因

在此系統中作業的代理可以取用以上全部四種資訊。根基真相提供事實錨點，決策說明歷史脈絡，模式引導實作，反模式則提醒陷阱所在。

## 衡量成效

自導入根基真相以來，我們觀察到：

- 「修正幻覺出的修正」這種循環變少了
- 事實明確時，代理做決策更有信心
- PR 審查品質更好，因為期望被明確寫出
- 新進代理（以及新進人類）的上手時間縮短

維護根基真相所投入的成本，換來了更少的除錯時間與更清晰的系統邊界，物有所值。

## 開始使用

要在你的系統中加入一條根基真相：

1. 建立一個 `ground_truths.yaml`，置於你套件的 `ai_assets/reference/` 目錄下
2. 定義中繼資料與渲染設定
3. 依照結構描述加入陳述
4. 執行 `uv run orkestra sync` 以產生文件
5. 將該登錄檔納入代理情境組成中

從最容易引發混淆的事實、或最常被違反的限制開始著手，這些正是你價值最高的根基真相。

## 結語

AI 代理終究會產生幻覺，這是它們的本性。但我們可以打造一種環境，讓幻覺受到約束、讓某些事實不容妥協、讓代理能夠對照已驗證的現實來檢查自己的假設。

根基真相並非萬靈丹，它需要維護、可能會過時，也會為開發流程增加額外負擔。

但它提供了一項寶貴的東西：一套人類與代理都能信任的共同事實詞彙。在一個代理日益深度參與軟體開發的世界裡，這樣的共同基礎變得不可或缺。

另一種選擇，是代理不斷自信地犯錯、人類不斷收拾善後的無盡循環。根基真相打破了這個循環，讓修正變得明確而持久。

你的代理值得知道什麼是真的。告訴它們。