程式碼圖譜與知識庫

程式碼圖譜為實驗性功能。其介面、資料格式與索引行為可能會在後續版本中變更。

程式碼圖譜使用 CodeGraph 分析專案中的符號及其彼此之間的關係。工作階段知識庫則儲存設計決策、限制條件與經驗教訓。程式碼參照將兩者連結起來，讓您既能看到程式碼目前的結構，也能了解其背後的原因。

頁面

程式碼圖譜會以對話方塊開啟，包含「概覽」、「符號」、「程式碼探索」與「檔案」分頁。其中的「知識庫」按鈕會開啟知識庫。

概覽： 檔案、符號與關係的數量，語言與符號類型的分布，以及同步狀態（「自動同步已啟用」或「查詢前同步」）。點選分布中的項目可查看符合的結果。
符號： 依名稱或檔案路徑搜尋（「搜尋符號或檔案路徑…」）。符號頁面會顯示具語法醒目提示的原始碼，以及依關係類型與檔案分組的「傳入關係」與「傳出關係」。由分析推斷出的關係會標示為「推斷關係」，點選行號即可跳至呼叫所在的位置。
程式碼探索： 描述某項功能或流程，或指定檔案或符號名稱，即可查看相關的原始碼與關係。此查詢在本機執行，不使用 AI 模型。
檔案： 瀏覽已建立索引的檔案；點選檔案可列出其中的符號。
呼叫者與被呼叫者：在符號頁面上顯示多層呼叫。「遍歷深度」預設為 3，最大為 6。最多顯示 500 筆結果；超過時會顯示總數與提示。
影響分析： 在符號頁面上顯示變更可能影響的符號與檔案，範圍取決於所選的深度（預設為 3，最大為 6）。最多顯示 500 個符號與 2,000 筆關係；結果遭截斷時，會顯示總數與提示。
呼叫路徑： 在符號頁面上搜尋目標符號（「搜尋目標符號…」），即可查看沿呼叫關係的最短路徑。「索引中找不到有向呼叫路徑。」僅表示索引中沒有這樣的路徑。

可從目錄選單切換工作目錄，該選單也會顯示完整路徑。頁面、程式碼探索中的問題、符號、深度、目標與原始碼行號都會包含在網址中，因此您可以重新整理頁面、在新分頁中開啟，或使用瀏覽器的上一頁與下一頁按鈕。在同一個後端上且登入有效時，連結即可使用。

為專案啟用索引

在側邊欄中的專案或集合上按右鍵，選擇「實驗性功能」→「程式碼圖譜」。
第一次使用時，請點選「下載 CodeGraph」。您所連線的後端會從 GitHub 下載固定版本的 CodeGraph 1.6.0，並以內建的 SHA-256 校驗值進行檢查（「下載檔案的校驗值不符，未安裝執行環境。」表示檢查失敗）。無須另外安裝 Node.js。
選擇「工作目錄」，然後點選「啟用索引」。專案目錄與其會話及群組所使用的其他工作目錄會分別列出；每個 Git worktree 都有自己的索引。集合中至少需要有一個具備有效工作目錄的會話。
等待狀態變為「可用」，然後搜尋符號或檔案路徑。索引會在背景執行（「索引工作正在執行。可以關閉此頁面，或停用索引以停止工作。」），關閉頁面不會取消索引。

「同步索引」可手動更新索引，或在失敗後重試。每次查詢程式碼之前，VelaTerm 也會先將索引更新到最新狀態。對於同一個後端與工作目錄，會重複使用同一個查詢處理程序，且該處理程序執行期間會即時接收檔案變更。連續五分鐘沒有查詢時，該處理程序會結束；下一次查詢會重新開啟索引並補上期間的變更。「概覽」每 30 秒重新整理一次同步狀態；無法使用自動同步時，VelaTerm 仍會在每次查詢前進行同步，絕不會將過時的結果當作最新結果呈現。

「停用索引」會停止執行中的索引工作，並保留索引檔案與知識條目的連結，因此之後可以再次啟用。工作中斷時，其狀態會在約兩分鐘內變為可重試的失敗狀態（「上一次工作已中斷。請同步索引以重試。」）。單一索引工作最多可執行 30 分鐘。

索引儲存在每個工作目錄中的 .codegraph/ 資料夾，並由 CodeGraph 管理。VelaTerm 會自行執行索引作業；不會執行 CodeGraph 的智慧體安裝程式，也不會安裝 Git hook。如果專案目錄是某個儲存庫的子資料夾，則只會為該資料夾建立索引。

檢視程式碼關係

搜尋結果會顯示每個符號的名稱、類型與位置。符號頁面會顯示其原始碼、傳入與傳出關係，以及已連結的知識條目；點選相鄰的符號即可繼續瀏覽。

頁面會提示「關係來自靜態分析，可能不完整或存在不確定性。」這些關係無法取代實際執行程式碼。符號頁面在每個方向最多顯示 200 筆關係與 600 行原始碼，超過時會顯示提示。大於 4 MiB 的原始碼檔案不會顯示。如果檔案在您檢視期間有所變更，VelaTerm 會要求您先重新同步，再依據其中的行號進行判斷。

連結與檢閱條目

在符號頁面上選擇「連結知識條目」，選取既有的條目，將其內容與程式碼比對後儲存。在條目頁面上，「程式碼參照」可回到程式碼，而程式碼圖譜中的條目連結則會開啟完整的條目。

連結會儲存專案、工作目錄、檔案路徑、符號識別資訊，以及檢閱當時檔案的 SHA-256 摘要。檔案變更時，連結會顯示「需要檢閱」；檔案已無法讀取或已刪除時，會顯示「無法使用」；其他情況則顯示「未變更」。檢查以檔案為單位，因此同一個檔案中的任何變更都會觸發重新檢閱。已開啟的條目頁面會定期檢查其參照。

選擇「核對程式碼與條目」可查看目前的程式碼；條目內容仍然成立時，請選擇「確認已檢閱」。後端會再次確認檔案與條目在這段期間內沒有變更，如有變更，則會要求您重新載入。確認只會更新程式碼參照，不會變更條目的文字。如要修改結論，請照常編輯條目。

符號遭刪除或重新命名時，連結不會轉移到另一個同名的符號。請使用「移除連結」，再連結正確的符號。刪除條目會移除其連結；刪除專案會移除其索引記錄與連結，但不會移除其他條目，也不會移除工作目錄中的索引檔案。

從會話查詢

VelaTerm 啟動的每個終端機與智慧體會話都提供 vkb 指令。其他能執行終端機指令的智慧體也可以使用。如果更新後既有會話找不到 vkb，請重新啟動該會話。

安裝「Vela 技能」後（設定 ▸ 一般），Claude 可以使用 /vkb，Codex 則可以使用 $vkb。此技能只有在您明確要求時才會執行；智慧體在進行其他工作時不會自行呼叫。如果更新後智慧體沒有列出此技能，請點選「重新安裝」，並重新啟動該智慧體的會話。

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore 傳回的結果與「程式碼探索」相同。
callers、callees 與 impact 可接受選用的深度參數；其結果包含 relations、total、depth 與 truncated。
path 需要兩個取自搜尋結果的確切符號 ID，files 則可依路徑篩選。
search 會分別傳回程式碼結果（依相關性排序，有更多結果時會附上 hasMore）、知識條目與本機筆記。
node 會傳回符號的原始碼、關係與已連結的條目。
memories 與 memory 可搜尋與讀取工作階段知識庫的條目，包括來源、修訂版本與程式碼參照。
notes 與 note 可搜尋與讀取本機知識庫（請參閱本機知識庫）。

程式碼查詢會使用指令執行所在目錄的索引。子資料夾會使用其所屬專案的索引，而巢狀的獨立 worktree 絕不會借用主要簽出目錄的索引。未啟用索引或查詢失敗時，結果會說明無法取得程式碼，但知識查詢仍可正常運作。這些指令不會安裝任何項目、啟用索引或變更條目。

資料儲存位置

CodeGraph 執行環境安裝在應用程式資料目錄的 codegraph/1.6.0/ 中。索引工作與條目連結儲存在應用程式資料庫中（knowledge_* 資料表）。索引作業在程式碼所在的後端執行；瀏覽器用戶端與 SSH 連線會透過既有的連線讀取結果，因此不會開啟額外的連接埠。每個後端都保有各自的索引設定與知識庫。

CodeGraph 的遙測、更新檢查與獨立背景服務均已關閉。VelaTerm 會管理查詢處理程序，並透過私有的標準輸入與輸出通道與其通訊，不會監聽任何連接埠。索引作業本身不使用 AI。智慧體透過 vkb 讀取的程式碼或條目，可能會傳送到該智慧體所設定的模型服務，與智慧體讀取原始碼檔案時的情況相同。

程式碼圖譜的事件會寫入應用程式資料目錄的 logs/runtime-*.log。未設定 VLX_LOG_DIR 時，由 VLX_KNOWLEDGE_LOG_DIR 設定其目錄。VLX_KNOWLEDGE_LOG_LEVEL 可篩選這些事件（例如 error 或 off）。日誌不包含原始碼、查詢文字、條目文字或憑證。

CodeGraph 由 github.com/colbymchenry/codegraph 開發，並以 MIT 授權條款發布。