本機知識庫

本機知識庫是一個一般的資料夾，存放您在 VelaTerm 中撰寫與整理的 Markdown 檔案。筆記與附件都保留在該資料夾中，因此您也可以繼續使用其他編輯器編輯。英文介面中的部分選單項目將本機知識庫稱為「notebook」，兩者指的是同一個資料夾。

內建的「工作階段知識庫」與您的本機知識庫並列。它存放智慧體從您的會話中整理出的知識，並有自己的條目、來源與修訂紀錄；請參閱工作階段知識庫。

開啟知識庫

點選右側面板中的知識庫圖示（工具提示為「知識庫」）。中央區域會開啟「知識庫」分頁並顯示首頁：

搜尋框（「搜尋工作階段知識與本機筆記…」；請參閱下方的「搜尋」一節）；
「工作階段知識庫」；
您的「本機知識庫」；
「開啟知識庫」與「新增知識庫」按鈕。

右側面板會顯示一個樹狀結構，包含三個根節點：「工作階段知識庫」、「已封存會話」與「本機知識庫」。點選箭頭可就地展開資料夾，也可以同時展開多個知識庫。點選資料夾名稱可顯示其內容，點選筆記則會開啟該筆記。樹狀結構頂端的「知識庫」連結會回到首頁；頁面標頭中的「返回上一層」按鈕則會前往上一層頁面，且不會離開知識庫。

筆記會在一般的文件分頁中開啟，與其他 Markdown 檔案一樣提供編輯、儲存、搜尋與匯出 PDF 功能（請參閱文件與瀏覽器分頁）。「知識庫」分頁會保留在分頁列中，方便您回到先前的位置。

開啟或建立本機知識庫

開啟： 點選「開啟知識庫」並選擇資料夾。桌面版會顯示系統的資料夾選擇器；瀏覽器用戶端則會顯示所連線電腦的資料夾瀏覽器。既有的 Obsidian 儲存庫（vault）可以直接開啟：檔案會留在原處，.obsidian 等隱藏資料夾不會建立索引，也不會被變更。
建立： 點選「新增知識庫」，輸入「名稱」，選擇「資料夾」（或點選「瀏覽」；預設建議為 ~/Notes），然後確認。VelaTerm 會建立該資料夾並開啟。上層資料夾必須已存在，且不能已有同名的資料夾；否則 VelaTerm 會顯示「目標已存在，請更換名稱或資料夾。」如要使用既有的資料夾，請改用「開啟知識庫」。
重新命名： 在樹狀結構中的知識庫上按右鍵，選擇「重新命名」。這會重新命名磁碟上的資料夾。
關閉： 點選知識庫工具列中的「關閉知識庫」，或在樹狀結構中的知識庫上按右鍵執行相同操作。關閉只會將資料夾從清單中移除，其檔案仍保留在磁碟上。再次開啟同一個資料夾時，其回收站與匯入記錄仍然存在。

「本機」指的是執行您所連線之 VelaTerm 後端的電腦。在瀏覽器用戶端中，「開啟知識庫」會瀏覽該電腦上的資料夾，而匯入時則會將您在瀏覽器中選擇的檔案上傳到該電腦。

匯入檔案與資料夾

開啟目標知識庫，點選其工具列中的「匯入」。
選擇目的地「資料夾」，然後點選「選擇檔案」或「選擇資料夾」，或將檔案與資料夾拖曳到匯入區域。
檢查清單後確認。

匯入會在背景執行，因此複製期間您可以切換頁面或開啟筆記。匯入進度會顯示在知識庫工具列與首頁上，並可從匯入對話方塊或「匯入記錄」中取消。完成後，橫幅會顯示已匯入與已略過的檔案數量；如果視窗不在前景，則會顯示系統通知（「匯入完成」或「匯入失敗」）。每個知識庫一次只能執行一項匯入。

匯入會依原樣複製檔案，包括非 ASCII 的檔名、相對的資料夾結構與附件，且一律不會修改原始檔案。匯入資料夾時會包含該資料夾本身。只要有任何檔案會覆寫既有檔案，整批匯入就會遭到拒絕。隱藏檔案與隱藏的設定資料夾會被略過。瀏覽器的檔案選擇器不會提供空資料夾，因此空資料夾不會被匯入。

單次匯入最多可包含 5,000 個檔案（遭略過的隱藏檔案也計入此上限），總大小上限為 1 GiB，每個檔案最大 100 MiB。檔案會先暫存，等整批檔案全部送達後才會出現在目的地，因此中斷的上傳絕不會以寫到一半的筆記形式出現。

「匯入記錄」會列出每次匯入的時間、目的地（頂層資料夾顯示為「知識庫根目錄」）、狀態（「正在匯入」、「已完成」、「失敗」、「已取消」或「已中斷」）、已匯入與已略過的檔案數量、大小與耗時。點選「檔案清單（N）」可查看每個檔案，以及檔案遭略過的原因。「刪除記錄」會從記錄中移除該筆項目，但不會移除已匯入的檔案。進度停止超過兩分鐘的匯入（例如應用程式意外結束時）會標示為「已中斷」；刪除其記錄時，也會一併移除為該次匯入暫存的檔案。

撰寫與整理筆記

知識庫頁面提供「最近的筆記」、「回收站」與「匯入記錄」三個檢視、「新增筆記」按鈕，以及工具列中的「新增資料夾」、「匯入」與「關閉知識庫」按鈕。筆記清單可依標籤篩選（「所有標籤」），排序方式可選擇「最近更新」或「依標題排序」。

顯示知識庫頁面時，⌘N／Ctrl+N 會執行「新增筆記」，⌘O／Ctrl+O 會開啟「快速開啟」（依路徑尋找筆記），⌘⇧F／Ctrl+Shift+F 則會將焦點移到「搜尋筆記…」搜尋框。
如要重新命名筆記，請在樹狀結構中的筆記上按右鍵並選擇「重新命名」。如要移動筆記，請將其拖曳到同一個知識庫中的另一個資料夾。「刪除」會將筆記移至該知識庫的回收站。
開啟資料夾時，「重新命名或移動」會將資料夾移到相對於知識庫根目錄的路徑；上層資料夾必須已存在。筆記或資料夾移動時，同一個知識庫中其他筆記裡的連結會隨之更新，連結文字保持不變，程式碼也不受影響。
刪除的項目會移至知識庫中的 .vkb-trash 資料夾。開啟「回收站」並點選「還原」即可復原項目；還原時絕不會覆寫同名的既有檔案。
標籤來自內文中的 #tag，以及 YAML 的 tags 清單或陣列。
貼到筆記中的圖片會儲存在筆記旁的 assets 資料夾中。

頁面顯示期間，樹狀結構與清單約每五秒重新整理一次，視窗重新取得焦點時也會重新整理。已開啟的文件分頁會偵測其他程式所做的變更，並提供重新載入的選項。

知識庫頁面、對話方塊、匯入記錄、搜尋、搜尋範圍、標籤、排序與快速開啟都有各自的網址，因此您可以重新整理頁面，或使用瀏覽器的上一頁與下一頁按鈕。尚未儲存的文字與表單輸入內容不會包含在網址中。

搜尋

首頁： 同時搜尋工作階段知識庫與所有本機知識庫，並依來源將結果分組。搜尋範圍不包含已封存的會話。
右側面板： 樹狀結構上方的「搜尋筆記…」會搜尋所有本機知識庫。
知識庫頁面： 「搜尋筆記…」會搜尋筆記名稱、路徑與內文。「搜尋範圍」可在「目前知識庫」與「全部知識庫」之間切換。

輸入多個詞語時，所有詞語都必須符合。每筆結果會顯示其所屬的知識庫或會話群組、內容片段、行號、符合次數，以及該筆記所連結的「相關筆記」；點選其中任一項即可開啟。使用上下方向鍵選取結果，按 Enter 開啟，按 Esc 清除搜尋。結果依序以名稱或路徑是否符合、符合次數，以及最近更新時間排序。最多列出 100 筆結果；超過時，清單最後會顯示「僅列出前面的結果，縮小關鍵字即可看到其餘命中。」

VelaTerm 會先尋找完全符合的結果，只有在沒有任何完全符合的結果時，才會改用近似比對，並顯示「沒有精確符合的結果，以下為近似結果。」近似比對適用於由拉丁字母與數字組成的詞語：依序出現的字母（knwl 可找到 knowledge）、首字母（kb 可找到 knowledge base），以及輕微的拼寫錯誤（四個字元以上的詞語容許一個錯誤，八個字元以上容許兩個；knoledge 可找到 knowledge）。中文與其他非拉丁文字一律採用完全比對。

連結與既有檔案的相容性

VelaTerm 可辨識常見的 [[note]]、[[folder/note|label]] 與 [[note#heading]] 格式、標準的相對 Markdown 連結，以及 ![[image.png]]。這些連結可用於在筆記移動時更新連結、在搜尋結果中列出「相關筆記」，以及供下方的 vkb 指令使用。在編輯器中，[[…]] 連結會以純文字顯示。多個檔案同名時，只有在目標唯一的情況下才會解析簡短連結；否則請寫出資料夾路徑。

檔案仍為純 Markdown，YAML front matter 也會保留在檔案中；編輯器的原始碼模式會依原樣完整顯示。非 UTF-8 或大於 5 MiB 的 Markdown 檔案不會列為筆記，並計入「已略過」。一個知識庫最多可包含 50,000 個檔案與資料夾；超過此數量的資料夾無法開啟，並會顯示「檔案或所選內容超出知識庫限制。」VelaTerm 不會追蹤符號連結。

這些功能涵蓋本機檔案、資料夾、Markdown、連結與搜尋的日常使用情境。Obsidian 的外掛程式、佈景主題、Canvas、區塊參照、嵌入筆記與 YAML 別名均不受支援；相關檔案會維持原狀。檔案模型與連結語法請參閱 Obsidian 關於儲存庫、內部連結與附件的說明文件。

從工作階段知識庫複製與智慧體查詢

在工作階段知識庫中開啟條目，選擇「複製到本機知識庫」，然後選取目標知識庫與檔名。複本是一則獨立的 Markdown 筆記；原始條目、其來源快照與修訂紀錄都會保留在原處。

在 VelaTerm 會話中，您或智慧體可以使用 vkb 讀取已加入的本機知識庫：

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes 會搜尋目前後端中已加入的所有本機知識庫。每筆結果包含 vaultId、vaultName、path、absolutePath、line、matches、score、matched（實際符合的文字）、related（此筆記所連結的筆記）與 summary（符合處前後的文字）。回應還會回報 total、hasMore、unavailable（無法讀取的知識庫）與 fuzzy（結果是否為近似比對）。最多傳回 100 筆結果。
note 會傳回筆記的內文、大綱、連結、反向連結與標籤。
search 會傳回工作階段知識庫與本機筆記中的符合結果；已有程式碼索引時，也會一併傳回程式碼圖譜的結果（請參閱程式碼圖譜與知識庫）。

這些指令為唯讀，一律不會變更筆記，VelaTerm 也不會自動將知識庫內容加入會話。

儲存與日誌

磁碟上的檔案才是筆記與附件的正式版本。應用程式資料庫（kb_* 資料表）只儲存已加入的知識庫清單、回收站記錄、匯入記錄，以及可重建的搜尋快取。工作階段知識庫使用自己的 memory_* 資料表。

開啟、寫入、移動、刪除、還原與匯入操作會記錄在執行階段日誌中，內容包括操作 ID、數量與耗時，但絕不包含筆記內容。這些記錄使用 knowledge 事件；未設定 VLX_LOG_DIR 時，由 VLX_KNOWLEDGE_LOG_DIR 設定其目錄。匯入記錄儲存在資料庫中，並顯示在「匯入記錄」頁面上。如要完整備份知識庫，請同時保留其資料夾與應用程式資料，後者保存了知識庫的回收站與匯入記錄。