@lovedolove/veyra

dsh plugin --profile web add @lovedolove/veyra

Veyra

Veyra — 程式編寫代理的工程智能

Veyra 是 DeepSeek Harness（DSH）的插件，為程式編寫代理提供可靠、持久、可感知變更的工程記憶——有證據支撐、依專案隔離、並對照目前的儲存庫——外加一個選用的結構化代碼智慧層：雙腦（Dual-Brain）架構。




想深入了解？[技術白皮書](docs/WHITEPAPER.md) 涵蓋設計原則、雙腦架構、記憶生命週期、搜尋內部機制、安全與信任機制、評量結果與已知限制，並附有逐節對應的[繁體中文版](docs/WHITEPAPER.zh-TW.md)。

---

雙腦架構

Veyra 運作兩層互補的機制，各自回答不同的問題：

腦 · 存放內容 · 事實來源

Veyra 記憶 · 工程教訓、根因、決策、約束，以及因果鏈（symptom → rootCause → remedy → verifiedOutcome）——附證據錨點、驗證狀態與權威層級 · 跨會話累積的認知狀態

代碼智慧 · AST 級結構性事實：符號、檔案、呼叫圖、類別階層——永遠由即時儲存庫派生 · 儲存庫本身，透過 codebase-memory-mcp

這不是同一回事。 一條寫著「登入函式已重構改用 JWT」的 Veyra 記憶是工程教訓；今天 login() 的呼叫圖是結構性事實。當被參考的檔案變更時，代碼智慧可將該記憶標記為可能過期——它從不靜默覆寫 Veyra 記憶。

---

Veyra 能做什麼

• 持久的工程記憶。 每筆記錄都帶有證據錨點、驗證狀態（unverified → reviewed → verified）、權威層級（candidate → derived → canonical）與因果面向。你的儲存庫保持權威地位；Veyra 絕不寫入其中。
• 混合搜尋。 單一查詢、多個訊號：FTS5 BM25 ＋符號／路徑加權、token 級語意重疊、意圖親和度（why / how / what-changed）與關係圖凝聚力——並附透明的分數拆解。goal 參數可引導排序朝向你正在進行的工作（是方向，而非權威）。
• 代碼智慧。 當 codebase-memory-mcp 已安裝時，七個代理工具提供結構化呼叫圖追蹤、AST 級符號搜尋、檔案／元件架構摘要與以代碼為依據的搜尋。未安裝時，Veyra 記憶照常運作、不受中斷。
• 記憶新鮮度與信任。 代碼智慧監控變更過的檔案，把證據錨點指向已修改或已刪除代碼的記憶標記為過期，並對過期記錄套用檢索懲罰。讀取時，每筆被召回的記錄都會被分類為 trusted / review_required / stale / contradicted / insufficient_evidence，並附理由與建議動作——只是投影；絕不寫入，也不改變記錄的權威或驗證。
• 變更智能。 儲存庫變更會自動進入代理上下文——變更摘要置於召回區塊之首，並標註其信任影響——而 veyra_change_impact 可針對一組明確的變更檔案做分析：受影響的記憶、受影響的證據錨點、選用覆核候選、與各類別摘要計數。候選絕不會被自動提升為 canonical。
• 健康與維護。 veyra_health 與 /veyra health 以唯讀方式回報記憶健康發現；隨附的 memory-maintenance 技能僅在明確要求時套用生命週期動作（keep / supersede / invalidate / forget / tombstone / revalidate / defer），並附安全上限與前後對照報告。
• 人工介面。 /veyra 斜線指令、唯讀的知識觀測台（Knowledge Observatory），以及 DSH Web 中 /veyra 的可互動網路圖（Network Graph）。
• 一個執行時 npm 相依。 @lovedolove/dsh-codebase-memory-mcp——獨立的 Codebase Memory 橋接套件——驅動外部原生 daemon。其餘全部為純 ESM、無執行時相依；套件約 198 kB（打包後）。

---

目錄

• [安裝](#安裝)
• [快速入門](#快速入門)
• [記憶如何運作](#記憶如何運作)
• [代碼智慧](#代碼智慧)
• [功能](#功能)
• [指令](#指令)
• [工具](#工具)
• [技能](#技能)
• [記憶規則](#記憶規則)
• [設定](#設定)
• [架構](#架構)
• [疑難排解](#疑難排解)
• [開發](#開發)
• [相容性](#相容性)
• [授權](#授權)
• [白皮書](docs/WHITEPAPER.md) / [白皮書（zh-TW）](docs/WHITEPAPER.zh-TW.md)

---

安裝

dsh plugin --profile web add @lovedolove/veyra

重新啟動 DSH（或重載該 profile）——Veyra 會自動啟用。不需要 API 金鑰、不需要外部服務、不需要任何設定即可開始使用記憶。

---

快速入門

1. 在 DSH 中做真實工作。 Veyra 會自動觀察會話事件。

2. 回合結束時，Veyra 把該回合濃縮成一條候選（candidate）記憶。持久的教訓會成為衍生（derived）記憶，並與相鄰記憶建立連結。

3. 查看已儲存內容：

   /veyra recent

4. 把內容取回。 在同一專案的稍後會話中，自動召回會將最相關的記錄注入該回合——每筆都標有 not repository truth。也可以明確搜尋：

   /veyra recall sqlite wal

5. 檢視、整理、提升：

   /veyra inspect vey_…           深層證據、來源、因果面向
   /veyra forget vey_…            軟遺忘（離開召回、仍可檢視）
   /veyra promote vey_… canonical 永遠只能顯式、永遠只依你的指示

6. 以圖觀看。 在 DSH Web 位址列開啟 /veyra——有邊界的 workspace 總覽；/veyra?id=<record> 將 1-hop 本地圖置中。

7. 遇到不熟悉的倉庫？ 載入隨附的 legacy-onboarding 技能——它會在你做第一筆變更之前，先以證據建立專案記憶基線（Project Memory Baseline）。

---

記憶如何運作

1. Veyra 觀察會話活動，不觸碰你的檔案。

2. 回合結束時：Veyra 將該回合濃縮為一條候選——檔案、符號、測試結果、主張訊號，與結構化因果面向。持久且有實據的教訓成為衍生記憶，並連結到相鄰記憶（延伸、更新，或被矛盾）。近似重複不會被複製；重複的觀察與已驗證的結果會強化既有記錄，而非新增記錄。

3. 自動召回在每個回合開始時，把最相關的 top-N 記錄注入代理的 system-prompt 上下文，並附明確的 not repository truth 標示。

4. 隨著同一教訓在跨會話與測試結果中反覆被確認，驗證狀態會推進（unverified → reviewed → verified）。沒有明確的人為指示，任何記錄都不會成為 canonical。

---

代碼智慧

代碼智慧是結構層，將 Veyra 連接到外部的

codebase-memory-mcp 原生 daemon。橋接代碼——倉庫發現、圖譜 client、code-intelligence engine、watcher，以及 cbm_* 工具定義——放在獨立的

@lovedolove/dsh-codebase-memory-mcp

套件中，這是 Veyra 唯一宣告的執行時相依。Veyra 本身不附原生二進位、也不內含橋接內部：它只重新公開六個 cbm_* 工具加上 veyra_code_status / veyra_change_impact，並在自家樹中僅保留 src/code/linking.mjs（證據錨 ↔ 代碼新鮮度）與 src/code/retrieval.mjs（統一管線）。橋接、其安裝流程與原生 daemon 的細節，由該套件的 README 說明，本文件不重複。

原生 daemon 為選用：沒有它時 Veyra 記憶層完全可用；代碼智慧降級（見下方「二進位不存在時」）。

安裝原生引擎

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

上游安裝程式會把二進位放到 Linux/macOS 的 ~/.local/bin、Windows 的 %LOCALAPPDATA%\Programs\codebase-memory-mcp\。支援的平台與驗證細節見上游 README。

也可以設定 CBM_EXE=/path/to/codebase-memory-mcp 指向既有的二進位。

二進位不存在時

代碼智慧進入降級模式：六個 cbm_* 工具與 veyra_code_status 會回傳附安裝指引的結構化錯誤。所有 Veyra 記憶工具、觀測台、斜線指令與混合搜尋照常運作，不受任何中斷。

代碼智慧提供什麼

工具 · 功能

cbm_projects · 列出已索引專案

cbm_search · 依名稱／標籤找符號、函式、類別、檔案

cbm_snippet · 取得符號的精確定義與行上下文

cbm_trace · 自符號追蹤入向／出向呼叫圖

cbm_arch · 目錄層級的元件相依總覽

cbm_search_code · 對已索引倉庫檔案做常規式搜尋

veyra_code_status · 索引狀態與記憶新鮮度報告

/veyra code 指令

指令 · 功能

/veyra code status · 索引狀態與逐筆記憶新鮮度（FRESH / POTENTIALLY_STALE / INVALID）

/veyra code index · 觸發倉庫重新索引

/veyra code trace <symbol> · 追蹤符號的呼叫圖

/veyra code impact · 檢查哪些記憶參考了近期變更的代碼

代碼事實 vs. Veyra 記憶

這個區別很重要：

• 代碼智慧自即時 AST 回報結構性事實：誰呼叫 login()、AuthService 對外暴露什麼。這些就「儲存庫目前的狀態」而言是權威的。
• Veyra 記憶記錄工程知識：為什麼改動 login()、失敗模式是什麼、對未來呼叫者的約束是什麼。這些跨重構持續存在——而被參考檔案變更時，代碼智慧會將其標記為可能過期，提醒你去驗證。

兩個腦互不取代。

---

功能

功能 · 說明

環境記憶循環 · 觀察會話事件、把回合濃縮為候選、學習持久教訓、強化重複出現者、把漂移知識標記為過期。

混合搜尋 · FTS5 BM25 ＋符號／路徑加權、token 級語意重疊、意圖親和度、關係圖凝聚力——附透明的分數拆解。

統一 RAG · kind: 'knowledge' 記錄與工程記憶並列存放專案文件；兩者一起被搜尋。

因果知識 · 結構化的 symptom → rootCause → remedy → verifiedOutcome 面向、矛盾偵測與並列衝突檢視。

代碼新鮮度 · 證據錨點追蹤檔案與符號；檔案被變更或刪除時，記憶被標記為 POTENTIALLY_STALE 或 INVALID，並套用檢索懲罰。

變更智能 · 倉庫監視器

…(truncated)