本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。英文原文

語意層

狀態：現行範圍：現行狀態上次審閱：2026-05-03 負責人：ax-code runtime

本文件描述 AX Code 目前存在的語意層。它是現行狀態契約，不是路線圖。

真相來源

本頁記載已發行的語意行為，不是未來的程式碼圖願景。行為變更時，請對照下列項目驗證：

packages/ax-code/src/tool/lsp.ts 與相關 LSP 模組，用於即時語意操作。
packages/ax-code/src/code-intelligence/，用於已索引的圖行為。
packages/ax-code-reason/，用於以圖為後盾的除錯／重構分析（影響、錯誤路徑、競爭、生命週期、重複、寫死的值、安全性發現，以及有閘門的重構套用）。
在聲稱持久來源保證之前，先做重播、匯出與稽核測試。

若某項能力是計畫中或實驗性，請把該狀態寫清楚。

目的

AX Code 透過兩個明確來源暴露語意回答：

lsp：即時語言伺服器查詢
graph：持久的程式碼智慧查詢

系統不會悄悄把其中一個導向另一個。呼叫端依新鮮度、延遲與決定性需求選擇介面。

目前的語意介面

介面	後盾來源	目前角色
`lsp` 工具	即時 LSP 用戶端	最新的語意回答、明確的即時查詢介面
`code_intelligence` 工具	已索引的 SQLite 程式碼圖	對已索引符號、引用與呼叫關係的決定性圖查詢

lsp 工具是即時語意介面。code_intelligence 工具是已索引的語意介面。兩者都不是對方的隱藏後備。

目前的閘門：

code_intelligence 預設啟用，但可以用功能旗標停用
lsp 目前需要實驗性 LSP 工具旗標

信封契約

語意回答帶有來源中繼資料，讓下游消費者可以判斷信任與新鮮度。

共通欄位：

source：lsp、graph 或 cache
completeness：full、partial 或 empty
timestamp：底層回答被解析的時間
degraded：選用訊號，表示應謹慎看待該回答

以 LSP 為後盾的信封也可以包含：

serverIDs：哪些語言伺服器有貢獻
cacheKey：指向 LSP 回應快取列的穩定引用

稽核與重播

目前行為：

透過 lsp 工具的即時語意呼叫會寫入 audit_semantic_call 列
工具重播現在會保留 tool.result.metadata，因此以圖為後盾的語意中繼資料在重播／匯出期間不會遺失
決定性重播比較的是決策路徑中繼資料，不是每個回傳符號清單的語意相等

這讓以 LSP 為後盾與以圖為後盾的語意回答有可比較的稽核能見度，即使它們仍來自不同的儲存／執行環境路徑。

目前暴露的操作

`lsp`

即時 lsp 介面包含以信封為後盾的操作：

定義
引用
懸停
文件符號
工作區符號
實作
呼叫階層
彙總的診斷

當新近程度比可重複性更重要時，這是正確的介面。

`code_intelligence`

圖介面包含：

符號查詢
檔案符號
引用
呼叫者
被呼叫者

當可重複性與較低延遲比立即的編輯器狀態新鮮度更重要時，這是正確的介面。

第三個選用的知識介面是 .ax-wiki/ 下的原生語意儲存庫 wiki，由 ax-code wiki 編譯。它不是上面結構圖／LSP 信封契約的一部分。

介面	角色
`lsp`／`code_intelligence`	結構精確度（本文件）
`.ax-wiki/`	供代理程式使用、有原始碼根據的架構敘事

CLI、路由與非目標請見AX Wiki。Wiki 合成不得被當成呼叫者／被呼叫者／引用的替代品。

重要的非目標

目前的語意層不做這些事：

沒有隱藏的圖優先路由，也不會自動退回 LSP
不聲稱圖的新鮮度等於即時 LSP 的新鮮度
不聲稱每一個內部語意輔助函式都透過 HTTP 或 SDK 暴露
目前的實作沒有 Rust 語意執行環境分割
不聲稱 AX Wiki markdown 是結構上的真相來源（請見AX Wiki）

整合指引

撰寫文件、SDK 繫結或較高階工作流程時：

把 lsp 與 code_intelligence 描述為分開的語意介面
區分公開工具操作與內部輔助函式
只描述目前結構描述中真正保留的稽核／重播保證
當語意介面不是一律啟用時，提及旗標
提到 AX Wiki 時，把 wiki 與圖的職責寫清楚

語意層