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

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

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

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

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

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

什麼是根基真相？

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

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

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

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

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

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

根基真相的生命週期

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

暫定

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

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

現行

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

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

已淘汰

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

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

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

衡量成效

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

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

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

開始使用

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

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

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

結語

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

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

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

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

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