建本地優(yōu)先的個人知識庫)
Foam for VS Code 深度指南用 Markdown Wikilinks 構(gòu)建本地優(yōu)先的個人知識庫【免費下載鏈接】foamA personal knowledge management and sharing system for VSCode項目地址: https://gitcode.com/gh_mirrors/fo/foamFoam 是一款運行在 VS Code 之內(nèi)的筆記工具它把 Markdown 文件、[[wikilink]]雙向鏈接、圖譜可視化與發(fā)布能力整合進一個本地優(yōu)先local-first的個人知識管理系統(tǒng)。本文以倉庫中 packages/foam-vscode/README.md 為主線結(jié)合 foam-vscode 擴展的源碼與配置清單系統(tǒng)講解它的核心功能、命令、配置項與擴展機制幫助你在 VS Code 中搭建一套可定制、可發(fā)布、可持續(xù)演進的知識庫。一、Foam 是什么在 VS Code 里長出來的知識庫Foam 不是一個獨立應(yīng)用而是一個“住在 VS Code 里的筆記工具”。它的設(shè)計有三個關(guān)鍵定位本地優(yōu)先筆記就是磁盤上的 Markdown 文件數(shù)據(jù)完全由你掌控不依賴任何云服務(wù)基于 Markdown你可以繼續(xù)使用 VS Code 里任何你喜歡的擴展拼寫檢查、圖表、剪貼板貼圖等來增強編輯體驗可擴展extensibleFoam 的 API 與內(nèi)部結(jié)構(gòu)是開放的你可以深入集成它的內(nèi)部機制來定制自己的知識庫可發(fā)布借助 link reference definitions 等功能筆記可以在非 Foam 環(huán)境下如 GitHub UI、GitHub Pages保持可導(dǎo)航。從源碼結(jié)構(gòu)看foam-vscode 擴展并非“單文件玩具”它依賴 foam/core核心數(shù)據(jù)模型、解析器、圖譜與查詢引擎與 foam/graph-view圖譜 Webview自身則負(fù)責(zé)把這兩者接入 VS Code 的 API。擴展的激活入口在 src/extension.ts它依次完成日志初始化、工作區(qū)掃描include/exclude 規(guī)則、Markdown 解析器與緩存創(chuàng)建、圖譜 bootstrap最后通過Promise.allSettled逐個激活src/vscode/features下的全部功能模塊——單個功能模塊失敗只降級該功能不會中斷整個擴展的激活。二、快速開始三步建好你的 Foam 工作區(qū)已經(jīng)在用 ObsidianObsidian 的 vault 通常直接就是一個 Foam 工作區(qū)可參考倉庫文檔 docs/user/recipes/migrating-from-obsidian.md 遷移。官方推薦的起步方式非常直接從 foam-template 創(chuàng)建倉庫在 GitHub 上基于foam-template模板創(chuàng)建倉庫。如果不想公開記得把倉庫設(shè)為 private?？寺〔⒋蜷_把倉庫克隆到本地用 VS Code 打開。安裝推薦擴展VS Code 彈出“推薦擴展”提示時點擊Install all或者點擊Show Recommendations逐條審查后安裝。這一步會順帶安裝 Foam 擴展本身如果你已經(jīng)裝過請確保更新到最新版本。用這種方法起步你會得到一套現(xiàn)成的.foam/目錄結(jié)構(gòu)存放模板、查詢等、每日筆記模板、圖譜視圖等基礎(chǔ)設(shè)施無需手動配置即可體驗完整功能。三、核心功能詳解1. 圖譜可視化Graph Visualization使用Foam: Show Graph命令可以直觀看到筆記之間如何通過鏈接連成一張網(wǎng)絡(luò)圖。命令的實現(xiàn)位于 src/vscode/features/graph-webview/index.tsfoam-vscode.show-graph會創(chuàng)建或復(fù)用并置前一個名為 “Foam Graph” 的 Webview 面板面板數(shù)據(jù)由buildGraphData(foam.workspace.list(), foam.graph.getAllConnections(), ...)生成并且監(jiān)聽foam.graph.onDidUpdate—— 只要筆記或鏈接發(fā)生變化圖譜會實時刷新。點擊節(jié)點時默認(rèn)用vscode.open打開筆記源文件如果開啟foam.graph.navigateToPreview則會改用markdown.showPreview打開 Markdown 預(yù)覽。圖譜還支持foam.graph.titleMaxLength節(jié)點標(biāo)題超長時截斷顯示默認(rèn) 24 字符0或負(fù)數(shù)表示不截斷截斷邏輯見 graph-webview/index.tsfoam.graph.style自定義節(jié)點顏色、分組規(guī)則、背景等樣式foam.graph.views定義多個命名視圖如Default、按目錄著色、按類型著色并可通過帶{ view: name }參數(shù)的鍵綁定打開視圖配置會在 resolveViewStyle 中與foam.graph.style合并foam.graph.onStartup設(shè)為true時擴展啟動即自動打開圖譜。2. Foam Queries把查詢“嵌入”筆記Foam Queries 允許你直接在 Markdown 預(yù)覽中嵌入動態(tài)、自動更新的列表、表格和計數(shù)只需在代碼塊中聲明foam-queryDQL 語法或foam-query-jsJavaScript 語法foam-query SELECT ... WHERE ...[](https://link.gitcode.com/i/829107ad8ae029f11003d355ea9026b7) 渲染邏輯在 [src/vscode/features/preview/foam-query-renderer.ts](https://link.gitcode.com/i/433433589cf41179e316585fb7fbfc48)它劫持 markdown-it 的 fence 規(guī)則遇到 foam-query / foam-query-js 代碼塊時分別調(diào)用 renderDqlQuery / renderJsQuery 渲染為 HTML出錯時輸出 foam-query-error 樣式的錯誤塊不影響預(yù)覽整體渲染。查詢中引用的筆記若含 [[wikilink]]會先被重寫為相對工作區(qū)根目錄的鏈接再渲染保證鏈接可點擊。完整的查詢語法參考見倉庫文檔 [docs/user/features/foam-queries.md](https://link.gitcode.com/i/e926486de27b26393fef2b3ffb099f99)。 ### 3. Block IDs鏈接到筆記內(nèi)部的“塊” [[note#^blockid]] 語法可以讓你鏈接或嵌入一篇筆記中的**段落、列表項、標(biāo)題、引用塊**。用法是先在目標(biāo)塊元素后加一個 ^id 標(biāo)記 md 這是一個可以錨定的段落。 ^my-block-id然后在知識庫的任何位置用[[note#^my-block-id]]引用它。塊級錨點讓知識庫的粒度從“篇”細(xì)化到“段”是構(gòu)建精確引用關(guān)系的基礎(chǔ)。相關(guān)實現(xiàn)與既有鏈接改寫邏輯可參見 src/vscode/features/preview/wikilink-embed.ts 與文檔 docs/user/features/block-anchors.md。4. 筆記嵌入Note Embed除了鏈接你還可以嵌入其他筆記的內(nèi)容——整篇、某個章節(jié)甚至某個塊都可以。結(jié)合 Block IDs 與章節(jié)支持可以在一個頁面里聚合多個來源的內(nèi)容形成“儀表盤式”的筆記。渲染細(xì)節(jié)由預(yù)覽側(cè)插件wikilink-embed完成src/vscode/features/preview/wikilink-embed.ts嵌入的呈現(xiàn)風(fēng)格可通過配置foam.preview.embedNoteType控制見下文配置表。5. 鏈接自動補全Link AutocompletionFoam 幫助你在筆記之間以及 placeholder 之間建立連接輸入[[時會彈出補全候選候選標(biāo)簽?zāi)J(rèn)使用筆記路徑也可切換為標(biāo)題或標(biāo)識符。相關(guān)配置foam.completion.label補全項的標(biāo)簽取什么屬性path/title/identifierfoam.completion.useAlias何時自動使用別名never/whenPathDiffersFromTitlefoam.completion.linkFormat補全產(chǎn)出的是 wikilink[[note-name]]還是標(biāo)準(zhǔn) Markdown 鏈接Note Name。6. 重命名時同步鏈接Sync links on file rename重命名文件后指向該文件的所有鏈接會被自動更新筆記之間的一致性得到保障。開關(guān)為foam.links.sync.enable默認(rèn)true。對于標(biāo)準(zhǔn) Markdown 鏈接README 建議額外開啟 VS Code 內(nèi)置的markdown.updateLinksOnFileMove.enabled設(shè)置兩者配合效果最佳。7. 跨目錄唯一標(biāo)識符Unique identifiers across directoriesFoam 支持多個目錄中存在同名文件。它會使用“能滿足唯一性要求的最小標(biāo)識符”來引用目標(biāo)并且能報告并修復(fù)已有歧義的 wikilink歧義鏈接會被診斷標(biāo)出并提供快速修復(fù)Quick Fix選擇要鏈接的具體文件——診斷邏輯見 src/vscode/features/lint/wikilink-diagnostics.ts其中AMBIGUOUS_IDENTIFIER_CODE對應(yīng)的修復(fù)會調(diào)用FoamWorkspace.getShortestIdentifier計算出最短唯一標(biāo)識符并替換鏈接wikilink-diagnostics.ts未知章節(jié)[[note#Section]]、未知塊[[note#^block]]、重復(fù)塊 ID 同樣會以診斷 快速修復(fù)的形式呈現(xiàn)UNKNOWN_SECTION_CODE、UNKNOWN_BLOCK_CODE、DUPLICATE_BLOCK_ID_CODE。8. 鏈接預(yù)覽與導(dǎo)航Link Preview and Navigation把鼠標(biāo)懸停在 wikilink 上即可預(yù)覽目標(biāo)筆記內(nèi)容點擊即可跳轉(zhuǎn)。預(yù)覽開關(guān)為foam.links.hover.enable默認(rèn)true。相關(guān)實現(xiàn)見 src/vscode/features/navigation/hover-provider.ts 與 navigation-provider.ts。9. 跳轉(zhuǎn)到定義、查看引用Go to definition, Peek ReferencesCtrlClick或?qū)?yīng)鍵位可以從任意 wikilink 跳到目標(biāo)筆記同時可以Peek References查看當(dāng)前筆記在知識庫中被哪些地方引用——這是反向鏈接能力的編輯器側(cè)形態(tài)實現(xiàn)見 src/vscode/features/navigation/navigation-provider.ts。10. Preview 內(nèi)導(dǎo)航Navigation in Preview在 VS Code 的 Markdown 預(yù)覽面板中也可以點擊 wikilink 完成導(dǎo)航讓“渲染后的閱讀態(tài)”同樣具備鏈接能力。這依賴擴展對 markdown-it 的擴展extendMarkdownIt鉤子由各 feature 模塊統(tǒng)一向extension.ts注冊。11. 章節(jié)支持Support for sectionsFoam 對筆記章節(jié)提供了完整的支持鏈條自動補全、導(dǎo)航、嵌入、診斷。語法就是標(biāo)準(zhǔn) wiki 語法[[resource#Section Title]]12. 鏈接別名Link AliasFoam 支持鏈接別名[[wikilink]] [[wikilink|alias]]別名讓引用在正文中讀起來更自然同時不破壞鏈接的目標(biāo)解析。13. 模板Templates使用自定義模板避免重復(fù)勞動Foam: Create New Template創(chuàng)建模板Foam: Create New Note from Template基于模板建筆記。模板目錄默認(rèn)是.foam/templates配置項foam.templates.folder。命令實現(xiàn)見 src/vscode/features/notes/create-note-from-template.ts它最終復(fù)用createNote({ askForTemplate: true }, foam)流程create-note.ts。模板里支持FOAM_TITLE、FOAM_DATE_*等變量日期變量所用 locale 由foam.dateLocale控制默認(rèn)跟隨系統(tǒng)也可用 BCP 47 語言標(biāo)簽如en-US、ja-JP。完整模板語法見文檔 docs/user/features/templates.md。14. Backlinks 面板Backlinks Panel在資源管理器側(cè)邊欄的Connections視圖中可以快速查看哪些筆記引用了當(dāng)前激活的筆記每個引用都展示其所在上下文并附帶筆記預(yù)覽。實現(xiàn)見 src/vscode/features/notes/connections.ts面板監(jiān)聽foam.graph.onDidUpdate與活動標(biāo)簽頁變化實時刷新工具欄支持在全部鏈接 / 反向鏈接Backlinks/ 正向鏈接Links之間切換并可過濾為“僅筆記”notes-only。15. Tag Explorer 面板Tag Explorer Panel用標(biāo)簽組織并瀏覽筆記Tag Explorer面板支持層級標(biāo)簽hierarchical tags。給筆記打標(biāo)簽的方式有兩種——正文中寫#tag或在 front matter 中聲明--- tags: tag1, tag2 ---面板還提供Foam: Search Tag與Foam: Rename Tag命令重命名標(biāo)簽會同步更新所有引用。相關(guān)實現(xiàn)見 src/vscode/features/tags/完整說明見文檔 docs/user/features/tags.md。16. Orphans 與 Placeholders 面板這兩個面板幫助你保持知識庫的健康狀態(tài)Orphans孤兒筆記既沒有入鏈也沒有出鏈的筆記——它們游離于知識網(wǎng)絡(luò)之外Placeholders占位符懸空鏈接dangling links或“有鏈接但沒有內(nèi)容”的筆記。在Orphans/Placeholders面板中集中查看并處理它們能讓知識庫始終處于更有序的狀態(tài)。兩個面板都支持“僅當(dāng)前文件 / 全部工作區(qū)”與“按文件夾分組 / 平鋪”切換還可以通過foam.orphans.exclude、foam.placeholders.exclude配置 glob 將特定路徑排除在報告之外。相關(guān)實現(xiàn)見 src/vscode/features/notes/orphans.ts 與 placeholders.ts。17. 語法高亮Syntax highlightFoam 對 wikilink 與 placeholder 使用不同的高亮讓你在編輯時一眼區(qū)分“已建立的鏈接”與“懸空鏈接/待創(chuàng)建的筆記”。這是通過注入語法實現(xiàn)的擴展聲明了foam.wikilink.injection語法注入到text.html.markdown見 package.json語法定義在 syntaxes/injection.json。placeholder 的前景色由主題色foam.placeholder控制默認(rèn)跟隨編輯器的editorWarning.foreground。18. 每日筆記Daily Note用Foam: Open Daily Note默認(rèn)快捷鍵AltD或Foam: Open Todays Note創(chuàng)建日記。每日筆記的命名、目錄等現(xiàn)在通過 daily-note 模板配置舊的foam.openDailyNote.*配置項已標(biāo)記為 deprecated建議遷移到模板方案詳見文檔 docs/user/features/daily-notes.md。還可以用Foam: Open Random Note隨機打開一篇筆記適合“回顧式”瀏覽。19. 為 wikilink 生成引用定義Generate referencesFoam: Update Wikilink Definitions命令可以為[[wikilinks]]生成 Markdown 引用定義link reference definitions使筆記能在非 Foam 環(huán)境下使用。有了這些引用定義筆記在 GitHub UI 以及 GitHub Pages 上都能保持可導(dǎo)航。生成策略由foam.edit.linkReferenceDefinitions控制withExtensionswikilink 路徑中保留擴展名withoutExtensions移除擴展名off關(guān)閉生成。文檔見 docs/user/features/link-reference-definitions.md。四、命令參考從命令面板出發(fā)的工作流除上述功能內(nèi)嵌的命令外擴展在命令面板中注冊了以下主要命令完整清單見 package.json命令作用Foam: Show Graph打開/聚焦筆記圖譜視圖Foam: Open Random Note隨機打開一篇筆記Foam: Open Todays NoteAltD打開/創(chuàng)建今天的每日筆記Foam: Open Daily NoteAltH打開指定日期的每日筆記Foam: Create New Note新建筆記可配合模板與Create New Note from Template使用Foam: Create New Note From Template選擇模板創(chuàng)建筆記Foam: Create New Template新建模板文件Foam: Update Wikilink Definitions為 wikilink 生成引用定義Foam: Convert Wikilink to Markdown Link把 wikilink 轉(zhuǎn)換為 Markdown 鏈接Foam: Convert Markdown Link to Wikilink反向轉(zhuǎn)換Foam: Copy To Clipboard Without Brackets復(fù)制不帶方括號的鏈接文本Foam: Search Tag/Foam: Rename Tag標(biāo)簽檢索與重命名Foam: Lint Workspace (Experimental)工作區(qū) lint 檢查Foam: Clear Cache清空解析緩存Foam: Set Log Level調(diào)整日志級別Foam: Show Whats New查看版本更新說明完整命令說明見文檔 docs/user/features/commands.md。五、配置參考按需定制你的知識庫擴展在 VS Code 設(shè)置中暴露了以foam.為前綴的完整配置樹聲明于 package.json下表整理了最常用的配置項文件與范圍配置項默認(rèn)值說明foam.files.include[**/*]納入 Foam 的 glob 規(guī)則可用它把范圍限定到特定目錄如[notes/**]或文件類型如[**/*.md]foam.files.exclude見 package.json從 Foam 中排除的 glob如**/node_modules/**/*、**/dist/**/*等排除整個文件夾用folderName/**/*foam.files.attachmentExtensionspdf mp3 webm wav m4a mp4 avi mov rtf txt doc docx pages xls xlsx numbers ppt pptm pptx視為附件的擴展名列表空格分隔foam.files.notesExtensions額外視為文本筆記的擴展名如mdx txt markdownfoam.files.defaultNoteExtensionmd新建筆記的默認(rèn)擴展名foam.files.newNotePathroot新筆記創(chuàng)建位置root工作區(qū)根目錄或currentDir當(dāng)前編輯器所在目錄會被模板或命令參數(shù)覆蓋foam.supportedLanguages[markdown]視為 Markdown 類文檔的語言列表注意修改foam.files.*系列配置后擴展會提示Reload the window使設(shè)置生效見 src/extension.ts。舊配置foam.files.ignore已廢棄請改用foam.files.exclude。鏈接與編輯配置項默認(rèn)值說明foam.links.sync.enabletrue重命名/移動筆記時自動更新 wikilinkfoam.links.hover.enabletrue懸停鏈接時顯示筆記內(nèi)容foam.links.directory.moderesolve指向目錄名的鏈接[[bar]]如何解析resolve查找目錄內(nèi)的 index 文件index.ext或README.extdisabled恢復(fù)嚴(yán)格的文件精確匹配foam.completion.labelpath補全項標(biāo)簽來源path/title/identifierfoam.completion.useAliasnever何時為 wikilink 使用別名foam.completion.linkFormatwikilink補全產(chǎn)物格式wikilink或link標(biāo)準(zhǔn) Markdown 鏈接foam.edit.linkReferenceDefinitionsoffwikilink 引用定義生成策略withExtensions/withoutExtensions/offfoam.preview.embedNoteTypefull-card嵌入筆記的渲染風(fēng)格是否帶標(biāo)題full/content以及是否置于容器卡片中inline/cardfoam.dateLocaledefault日期變量如FOAM_DATE_DAY_NAME所用 locale可用 BCP 47 標(biāo)簽面板與圖譜配置項默認(rèn)值說明foam.orphans.exclude[]從 Orphans 報告中排除的 globfoam.placeholders.exclude[]從 Placeholders 報告中排除的 globfoam.graph.titleMaxLength24圖譜節(jié)點標(biāo)題最大長度超出截斷0關(guān)閉截斷foam.graph.style{}圖譜自定義樣式節(jié)點顏色、分組等foam.graph.views[]命名圖譜視圖名為Default的視圖會在圖譜無參數(shù)打開時自動應(yīng)用foam.graph.onStartupfalse啟動時是否自動打開圖譜foam.graph.navigateToPreviewfalse點擊圖譜節(jié)點時打開 Markdown 預(yù)覽而非源文件實驗性功能與日志配置項默認(rèn)值說明foam.experimentalfalse啟用實驗性功能AI 相似/相關(guān)筆記、導(dǎo)出 HTML 頁面等。實驗功能可能隨時變更或移除foam.logging.levelinfo日志級別off/debug/info/warn/error啟用foam.experimental后資源管理器中會出現(xiàn)Related Notes (AI)面板基于 Ollama 嵌入見 src/ai/providers/ollama/ollama-provider.ts命令面板中也會出現(xiàn)Foam: Show Similar Notes、Foam: Build Embeddings Index、Foam: Export to HTML page等命令。六、倉庫結(jié)構(gòu)讀懂 Foam 的代碼地圖如果你想深入擴展甚至貢獻代碼可以按下面的路徑探索本倉庫根目錄即 Foam 的 monorepo擴展本體packages/foam-vscode/——VS Code 擴展包含src/vscode/features/下的全部功能模塊導(dǎo)航、預(yù)覽、lint、標(biāo)簽、每日筆記、智能文件夾等核心引擎packages/foam-core/——數(shù)據(jù)模型model/、Markdown 解析services/markdown-parser.ts、圖譜model/graph.ts、查詢引擎query/含 DQL 與 JS 查詢、模板系統(tǒng)templates/與導(dǎo)出export/圖譜視圖packages/foam-graph/——在 Webview 中渲染圖譜的前端實現(xiàn)MCP 服務(wù)器packages/foam-mcp/——把 Foam 的圖譜、搜索、標(biāo)簽?zāi)芰Ρ┞稙?Model Context Protocol 工具CLI 工具packages/foam-cli/——提供daily、grep、links、lint、note、search、tag等命令行能力擴展激活流程src/extension.ts——展示了“核心引擎 bootstrap → 功能模塊逐個注冊 → 統(tǒng)一extendMarkdownIt聚合”的架構(gòu)模式也是理解 Foam 可擴展性的最佳入口。由于擴展將extendMarkdownIt作為各 feature 的統(tǒng)一出口src/extension.ts預(yù)覽側(cè)的 wikilink 導(dǎo)航、嵌入、查詢渲染、腳注等能力都是通過該鉤子注入 markdown-it 的這為第三方擴展復(fù)用 Foam 的解析與渲染能力提供了穩(wěn)定的集成點。七、常見問題、已知問題與版本信息已知問題Known Issues可查看倉庫 GitHub Issues 頁面跟蹤。版本更新Release Notes見 packages/foam-vscode/CHANGELOG.md。調(diào)試日志通過Foam: Set Log Level調(diào)整日志級別輸出日志幫助定位問題更詳細(xì)的日志說明見文檔 docs/user/tools/foam-logging-in-vscode.md。此外Foam 生態(tài)里還有大量來自社區(qū)的使用場景recipes——自動 Git 同步、從移動端記錄、PDF 導(dǎo)出、實時協(xié)作、剪藏網(wǎng)頁等可按需查閱 docs/user/recipes/recipes.md 尋找靈感把 Foam 塑造成適合你自己的知識工作流?！久赓M下載鏈接】foamA personal knowledge management and sharing system for VSCode項目地址: https://gitcode.com/gh_mirrors/fo/foam創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Foam for VS Code 深度指南：用 Markdown + Wikilinks 構(gòu)建本地優(yōu)先的個人知識庫
Foam for VS Code 深度指南用 Markdown Wikilinks 構(gòu)建本地優(yōu)先的個人知識庫【免費下載鏈接】foamA personal knowledge management and sharing system for VSCode項目地址: https://gitcode.com/gh_mirrors/fo/foamFoam 是一款運行在 VS Code 之內(nèi)的筆記工具它把 Markdown 文件、[[wikilink]]雙向鏈接、圖譜可視化與發(fā)布能力整合進一個本地優(yōu)先local-first的個人知識管理系統(tǒng)。本文以倉庫中 packages/foam-vscode/README.md 為主線結(jié)合 foam-vscode 擴展的源碼與配置清單系統(tǒng)講解它的核心功能、命令、配置項與擴展機制幫助你在 VS Code 中搭建一套可定制、可發(fā)布、可持續(xù)演進的知識庫。一、Foam 是什么在 VS Code 里長出來的知識庫Foam 不是一個獨立應(yīng)用而是一個“住在 VS Code 里的筆記工具”。它的設(shè)計有三個關(guān)鍵定位本地優(yōu)先筆記就是磁盤上的 Markdown 文件數(shù)據(jù)完全由你掌控不依賴任何云服務(wù)基于 Markdown你可以繼續(xù)使用 VS Code 里任何你喜歡的擴展拼寫檢查、圖表、剪貼板貼圖等來增強編輯體驗可擴展extensibleFoam 的 API 與內(nèi)部結(jié)構(gòu)是開放的你可以深入集成它的內(nèi)部機制來定制自己的知識庫可發(fā)布借助 link reference definitions 等功能筆記可以在非 Foam 環(huán)境下如 GitHub UI、GitHub Pages保持可導(dǎo)航。從源碼結(jié)構(gòu)看foam-vscode 擴展并非“單文件玩具”它依賴 foam/core核心數(shù)據(jù)模型、解析器、圖譜與查詢引擎與 foam/graph-view圖譜 Webview自身則負(fù)責(zé)把這兩者接入 VS Code 的 API。擴展的激活入口在 src/extension.ts它依次完成日志初始化、工作區(qū)掃描include/exclude 規(guī)則、Markdown 解析器與緩存創(chuàng)建、圖譜 bootstrap最后通過Promise.allSettled逐個激活src/vscode/features下的全部功能模塊——單個功能模塊失敗只降級該功能不會中斷整個擴展的激活。二、快速開始三步建好你的 Foam 工作區(qū)已經(jīng)在用 ObsidianObsidian 的 vault 通常直接就是一個 Foam 工作區(qū)可參考倉庫文檔 docs/user/recipes/migrating-from-obsidian.md 遷移。官方推薦的起步方式非常直接從 foam-template 創(chuàng)建倉庫在 GitHub 上基于foam-template模板創(chuàng)建倉庫。如果不想公開記得把倉庫設(shè)為 private?？寺〔⒋蜷_把倉庫克隆到本地用 VS Code 打開。安裝推薦擴展VS Code 彈出“推薦擴展”提示時點擊Install all或者點擊Show Recommendations逐條審查后安裝。這一步會順帶安裝 Foam 擴展本身如果你已經(jīng)裝過請確保更新到最新版本。用這種方法起步你會得到一套現(xiàn)成的.foam/目錄結(jié)構(gòu)存放模板、查詢等、每日筆記模板、圖譜視圖等基礎(chǔ)設(shè)施無需手動配置即可體驗完整功能。三、核心功能詳解1. 圖譜可視化Graph Visualization使用Foam: Show Graph命令可以直觀看到筆記之間如何通過鏈接連成一張網(wǎng)絡(luò)圖。命令的實現(xiàn)位于 src/vscode/features/graph-webview/index.tsfoam-vscode.show-graph會創(chuàng)建或復(fù)用并置前一個名為 “Foam Graph” 的 Webview 面板面板數(shù)據(jù)由buildGraphData(foam.workspace.list(), foam.graph.getAllConnections(), ...)生成并且監(jiān)聽foam.graph.onDidUpdate—— 只要筆記或鏈接發(fā)生變化圖譜會實時刷新。點擊節(jié)點時默認(rèn)用vscode.open打開筆記源文件如果開啟foam.graph.navigateToPreview則會改用markdown.showPreview打開 Markdown 預(yù)覽。圖譜還支持foam.graph.titleMaxLength節(jié)點標(biāo)題超長時截斷顯示默認(rèn) 24 字符0或負(fù)數(shù)表示不截斷截斷邏輯見 graph-webview/index.tsfoam.graph.style自定義節(jié)點顏色、分組規(guī)則、背景等樣式foam.graph.views定義多個命名視圖如Default、按目錄著色、按類型著色并可通過帶{ view: name }參數(shù)的鍵綁定打開視圖配置會在 resolveViewStyle 中與foam.graph.style合并foam.graph.onStartup設(shè)為true時擴展啟動即自動打開圖譜。2. Foam Queries把查詢“嵌入”筆記Foam Queries 允許你直接在 Markdown 預(yù)覽中嵌入動態(tài)、自動更新的列表、表格和計數(shù)只需在代碼塊中聲明foam-queryDQL 語法或foam-query-jsJavaScript 語法foam-query SELECT ... WHERE ...[](https://link.gitcode.com/i/829107ad8ae029f11003d355ea9026b7) 渲染邏輯在 [src/vscode/features/preview/foam-query-renderer.ts](https://link.gitcode.com/i/433433589cf41179e316585fb7fbfc48)它劫持 markdown-it 的 fence 規(guī)則遇到 foam-query / foam-query-js 代碼塊時分別調(diào)用 renderDqlQuery / renderJsQuery 渲染為 HTML出錯時輸出 foam-query-error 樣式的錯誤塊不影響預(yù)覽整體渲染。查詢中引用的筆記若含 [[wikilink]]會先被重寫為相對工作區(qū)根目錄的鏈接再渲染保證鏈接可點擊。完整的查詢語法參考見倉庫文檔 [docs/user/features/foam-queries.md](https://link.gitcode.com/i/e926486de27b26393fef2b3ffb099f99)。 ### 3. Block IDs鏈接到筆記內(nèi)部的“塊” [[note#^blockid]] 語法可以讓你鏈接或嵌入一篇筆記中的**段落、列表項、標(biāo)題、引用塊**。用法是先在目標(biāo)塊元素后加一個 ^id 標(biāo)記 md 這是一個可以錨定的段落。 ^my-block-id然后在知識庫的任何位置用[[note#^my-block-id]]引用它。塊級錨點讓知識庫的粒度從“篇”細(xì)化到“段”是構(gòu)建精確引用關(guān)系的基礎(chǔ)。相關(guān)實現(xiàn)與既有鏈接改寫邏輯可參見 src/vscode/features/preview/wikilink-embed.ts 與文檔 docs/user/features/block-anchors.md。4. 筆記嵌入Note Embed除了鏈接你還可以嵌入其他筆記的內(nèi)容——整篇、某個章節(jié)甚至某個塊都可以。結(jié)合 Block IDs 與章節(jié)支持可以在一個頁面里聚合多個來源的內(nèi)容形成“儀表盤式”的筆記。渲染細(xì)節(jié)由預(yù)覽側(cè)插件wikilink-embed完成src/vscode/features/preview/wikilink-embed.ts嵌入的呈現(xiàn)風(fēng)格可通過配置foam.preview.embedNoteType控制見下文配置表。5. 鏈接自動補全Link AutocompletionFoam 幫助你在筆記之間以及 placeholder 之間建立連接輸入[[時會彈出補全候選候選標(biāo)簽?zāi)J(rèn)使用筆記路徑也可切換為標(biāo)題或標(biāo)識符。相關(guān)配置foam.completion.label補全項的標(biāo)簽取什么屬性path/title/identifierfoam.completion.useAlias何時自動使用別名never/whenPathDiffersFromTitlefoam.completion.linkFormat補全產(chǎn)出的是 wikilink[[note-name]]還是標(biāo)準(zhǔn) Markdown 鏈接Note Name。6. 重命名時同步鏈接Sync links on file rename重命名文件后指向該文件的所有鏈接會被自動更新筆記之間的一致性得到保障。開關(guān)為foam.links.sync.enable默認(rèn)true。對于標(biāo)準(zhǔn) Markdown 鏈接README 建議額外開啟 VS Code 內(nèi)置的markdown.updateLinksOnFileMove.enabled設(shè)置兩者配合效果最佳。7. 跨目錄唯一標(biāo)識符Unique identifiers across directoriesFoam 支持多個目錄中存在同名文件。它會使用“能滿足唯一性要求的最小標(biāo)識符”來引用目標(biāo)并且能報告并修復(fù)已有歧義的 wikilink歧義鏈接會被診斷標(biāo)出并提供快速修復(fù)Quick Fix選擇要鏈接的具體文件——診斷邏輯見 src/vscode/features/lint/wikilink-diagnostics.ts其中AMBIGUOUS_IDENTIFIER_CODE對應(yīng)的修復(fù)會調(diào)用FoamWorkspace.getShortestIdentifier計算出最短唯一標(biāo)識符并替換鏈接wikilink-diagnostics.ts未知章節(jié)[[note#Section]]、未知塊[[note#^block]]、重復(fù)塊 ID 同樣會以診斷 快速修復(fù)的形式呈現(xiàn)UNKNOWN_SECTION_CODE、UNKNOWN_BLOCK_CODE、DUPLICATE_BLOCK_ID_CODE。8. 鏈接預(yù)覽與導(dǎo)航Link Preview and Navigation把鼠標(biāo)懸停在 wikilink 上即可預(yù)覽目標(biāo)筆記內(nèi)容點擊即可跳轉(zhuǎn)。預(yù)覽開關(guān)為foam.links.hover.enable默認(rèn)true。相關(guān)實現(xiàn)見 src/vscode/features/navigation/hover-provider.ts 與 navigation-provider.ts。9. 跳轉(zhuǎn)到定義、查看引用Go to definition, Peek ReferencesCtrlClick或?qū)?yīng)鍵位可以從任意 wikilink 跳到目標(biāo)筆記同時可以Peek References查看當(dāng)前筆記在知識庫中被哪些地方引用——這是反向鏈接能力的編輯器側(cè)形態(tài)實現(xiàn)見 src/vscode/features/navigation/navigation-provider.ts。10. Preview 內(nèi)導(dǎo)航Navigation in Preview在 VS Code 的 Markdown 預(yù)覽面板中也可以點擊 wikilink 完成導(dǎo)航讓“渲染后的閱讀態(tài)”同樣具備鏈接能力。這依賴擴展對 markdown-it 的擴展extendMarkdownIt鉤子由各 feature 模塊統(tǒng)一向extension.ts注冊。11. 章節(jié)支持Support for sectionsFoam 對筆記章節(jié)提供了完整的支持鏈條自動補全、導(dǎo)航、嵌入、診斷。語法就是標(biāo)準(zhǔn) wiki 語法[[resource#Section Title]]12. 鏈接別名Link AliasFoam 支持鏈接別名[[wikilink]] [[wikilink|alias]]別名讓引用在正文中讀起來更自然同時不破壞鏈接的目標(biāo)解析。13. 模板Templates使用自定義模板避免重復(fù)勞動Foam: Create New Template創(chuàng)建模板Foam: Create New Note from Template基于模板建筆記。模板目錄默認(rèn)是.foam/templates配置項foam.templates.folder。命令實現(xiàn)見 src/vscode/features/notes/create-note-from-template.ts它最終復(fù)用createNote({ askForTemplate: true }, foam)流程create-note.ts。模板里支持FOAM_TITLE、FOAM_DATE_*等變量日期變量所用 locale 由foam.dateLocale控制默認(rèn)跟隨系統(tǒng)也可用 BCP 47 語言標(biāo)簽如en-US、ja-JP。完整模板語法見文檔 docs/user/features/templates.md。14. Backlinks 面板Backlinks Panel在資源管理器側(cè)邊欄的Connections視圖中可以快速查看哪些筆記引用了當(dāng)前激活的筆記每個引用都展示其所在上下文并附帶筆記預(yù)覽。實現(xiàn)見 src/vscode/features/notes/connections.ts面板監(jiān)聽foam.graph.onDidUpdate與活動標(biāo)簽頁變化實時刷新工具欄支持在全部鏈接 / 反向鏈接Backlinks/ 正向鏈接Links之間切換并可過濾為“僅筆記”notes-only。15. Tag Explorer 面板Tag Explorer Panel用標(biāo)簽組織并瀏覽筆記Tag Explorer面板支持層級標(biāo)簽hierarchical tags。給筆記打標(biāo)簽的方式有兩種——正文中寫#tag或在 front matter 中聲明--- tags: tag1, tag2 ---面板還提供Foam: Search Tag與Foam: Rename Tag命令重命名標(biāo)簽會同步更新所有引用。相關(guān)實現(xiàn)見 src/vscode/features/tags/完整說明見文檔 docs/user/features/tags.md。16. Orphans 與 Placeholders 面板這兩個面板幫助你保持知識庫的健康狀態(tài)Orphans孤兒筆記既沒有入鏈也沒有出鏈的筆記——它們游離于知識網(wǎng)絡(luò)之外Placeholders占位符懸空鏈接dangling links或“有鏈接但沒有內(nèi)容”的筆記。在Orphans/Placeholders面板中集中查看并處理它們能讓知識庫始終處于更有序的狀態(tài)。兩個面板都支持“僅當(dāng)前文件 / 全部工作區(qū)”與“按文件夾分組 / 平鋪”切換還可以通過foam.orphans.exclude、foam.placeholders.exclude配置 glob 將特定路徑排除在報告之外。相關(guān)實現(xiàn)見 src/vscode/features/notes/orphans.ts 與 placeholders.ts。17. 語法高亮Syntax highlightFoam 對 wikilink 與 placeholder 使用不同的高亮讓你在編輯時一眼區(qū)分“已建立的鏈接”與“懸空鏈接/待創(chuàng)建的筆記”。這是通過注入語法實現(xiàn)的擴展聲明了foam.wikilink.injection語法注入到text.html.markdown見 package.json語法定義在 syntaxes/injection.json。placeholder 的前景色由主題色foam.placeholder控制默認(rèn)跟隨編輯器的editorWarning.foreground。18. 每日筆記Daily Note用Foam: Open Daily Note默認(rèn)快捷鍵AltD或Foam: Open Todays Note創(chuàng)建日記。每日筆記的命名、目錄等現(xiàn)在通過 daily-note 模板配置舊的foam.openDailyNote.*配置項已標(biāo)記為 deprecated建議遷移到模板方案詳見文檔 docs/user/features/daily-notes.md。還可以用Foam: Open Random Note隨機打開一篇筆記適合“回顧式”瀏覽。19. 為 wikilink 生成引用定義Generate referencesFoam: Update Wikilink Definitions命令可以為[[wikilinks]]生成 Markdown 引用定義link reference definitions使筆記能在非 Foam 環(huán)境下使用。有了這些引用定義筆記在 GitHub UI 以及 GitHub Pages 上都能保持可導(dǎo)航。生成策略由foam.edit.linkReferenceDefinitions控制withExtensionswikilink 路徑中保留擴展名withoutExtensions移除擴展名off關(guān)閉生成。文檔見 docs/user/features/link-reference-definitions.md。四、命令參考從命令面板出發(fā)的工作流除上述功能內(nèi)嵌的命令外擴展在命令面板中注冊了以下主要命令完整清單見 package.json命令作用Foam: Show Graph打開/聚焦筆記圖譜視圖Foam: Open Random Note隨機打開一篇筆記Foam: Open Todays NoteAltD打開/創(chuàng)建今天的每日筆記Foam: Open Daily NoteAltH打開指定日期的每日筆記Foam: Create New Note新建筆記可配合模板與Create New Note from Template使用Foam: Create New Note From Template選擇模板創(chuàng)建筆記Foam: Create New Template新建模板文件Foam: Update Wikilink Definitions為 wikilink 生成引用定義Foam: Convert Wikilink to Markdown Link把 wikilink 轉(zhuǎn)換為 Markdown 鏈接Foam: Convert Markdown Link to Wikilink反向轉(zhuǎn)換Foam: Copy To Clipboard Without Brackets復(fù)制不帶方括號的鏈接文本Foam: Search Tag/Foam: Rename Tag標(biāo)簽檢索與重命名Foam: Lint Workspace (Experimental)工作區(qū) lint 檢查Foam: Clear Cache清空解析緩存Foam: Set Log Level調(diào)整日志級別Foam: Show Whats New查看版本更新說明完整命令說明見文檔 docs/user/features/commands.md。五、配置參考按需定制你的知識庫擴展在 VS Code 設(shè)置中暴露了以foam.為前綴的完整配置樹聲明于 package.json下表整理了最常用的配置項文件與范圍配置項默認(rèn)值說明foam.files.include[**/*]納入 Foam 的 glob 規(guī)則可用它把范圍限定到特定目錄如[notes/**]或文件類型如[**/*.md]foam.files.exclude見 package.json從 Foam 中排除的 glob如**/node_modules/**/*、**/dist/**/*等排除整個文件夾用folderName/**/*foam.files.attachmentExtensionspdf mp3 webm wav m4a mp4 avi mov rtf txt doc docx pages xls xlsx numbers ppt pptm pptx視為附件的擴展名列表空格分隔foam.files.notesExtensions額外視為文本筆記的擴展名如mdx txt markdownfoam.files.defaultNoteExtensionmd新建筆記的默認(rèn)擴展名foam.files.newNotePathroot新筆記創(chuàng)建位置root工作區(qū)根目錄或currentDir當(dāng)前編輯器所在目錄會被模板或命令參數(shù)覆蓋foam.supportedLanguages[markdown]視為 Markdown 類文檔的語言列表注意修改foam.files.*系列配置后擴展會提示Reload the window使設(shè)置生效見 src/extension.ts。舊配置foam.files.ignore已廢棄請改用foam.files.exclude。鏈接與編輯配置項默認(rèn)值說明foam.links.sync.enabletrue重命名/移動筆記時自動更新 wikilinkfoam.links.hover.enabletrue懸停鏈接時顯示筆記內(nèi)容foam.links.directory.moderesolve指向目錄名的鏈接[[bar]]如何解析resolve查找目錄內(nèi)的 index 文件index.ext或README.extdisabled恢復(fù)嚴(yán)格的文件精確匹配foam.completion.labelpath補全項標(biāo)簽來源path/title/identifierfoam.completion.useAliasnever何時為 wikilink 使用別名foam.completion.linkFormatwikilink補全產(chǎn)物格式wikilink或link標(biāo)準(zhǔn) Markdown 鏈接foam.edit.linkReferenceDefinitionsoffwikilink 引用定義生成策略withExtensions/withoutExtensions/offfoam.preview.embedNoteTypefull-card嵌入筆記的渲染風(fēng)格是否帶標(biāo)題full/content以及是否置于容器卡片中inline/cardfoam.dateLocaledefault日期變量如FOAM_DATE_DAY_NAME所用 locale可用 BCP 47 標(biāo)簽面板與圖譜配置項默認(rèn)值說明foam.orphans.exclude[]從 Orphans 報告中排除的 globfoam.placeholders.exclude[]從 Placeholders 報告中排除的 globfoam.graph.titleMaxLength24圖譜節(jié)點標(biāo)題最大長度超出截斷0關(guān)閉截斷foam.graph.style{}圖譜自定義樣式節(jié)點顏色、分組等foam.graph.views[]命名圖譜視圖名為Default的視圖會在圖譜無參數(shù)打開時自動應(yīng)用foam.graph.onStartupfalse啟動時是否自動打開圖譜foam.graph.navigateToPreviewfalse點擊圖譜節(jié)點時打開 Markdown 預(yù)覽而非源文件實驗性功能與日志配置項默認(rèn)值說明foam.experimentalfalse啟用實驗性功能AI 相似/相關(guān)筆記、導(dǎo)出 HTML 頁面等。實驗功能可能隨時變更或移除foam.logging.levelinfo日志級別off/debug/info/warn/error啟用foam.experimental后資源管理器中會出現(xiàn)Related Notes (AI)面板基于 Ollama 嵌入見 src/ai/providers/ollama/ollama-provider.ts命令面板中也會出現(xiàn)Foam: Show Similar Notes、Foam: Build Embeddings Index、Foam: Export to HTML page等命令。六、倉庫結(jié)構(gòu)讀懂 Foam 的代碼地圖如果你想深入擴展甚至貢獻代碼可以按下面的路徑探索本倉庫根目錄即 Foam 的 monorepo擴展本體packages/foam-vscode/——VS Code 擴展包含src/vscode/features/下的全部功能模塊導(dǎo)航、預(yù)覽、lint、標(biāo)簽、每日筆記、智能文件夾等核心引擎packages/foam-core/——數(shù)據(jù)模型model/、Markdown 解析services/markdown-parser.ts、圖譜model/graph.ts、查詢引擎query/含 DQL 與 JS 查詢、模板系統(tǒng)templates/與導(dǎo)出export/圖譜視圖packages/foam-graph/——在 Webview 中渲染圖譜的前端實現(xiàn)MCP 服務(wù)器packages/foam-mcp/——把 Foam 的圖譜、搜索、標(biāo)簽?zāi)芰Ρ┞稙?Model Context Protocol 工具CLI 工具packages/foam-cli/——提供daily、grep、links、lint、note、search、tag等命令行能力擴展激活流程src/extension.ts——展示了“核心引擎 bootstrap → 功能模塊逐個注冊 → 統(tǒng)一extendMarkdownIt聚合”的架構(gòu)模式也是理解 Foam 可擴展性的最佳入口。由于擴展將extendMarkdownIt作為各 feature 的統(tǒng)一出口src/extension.ts預(yù)覽側(cè)的 wikilink 導(dǎo)航、嵌入、查詢渲染、腳注等能力都是通過該鉤子注入 markdown-it 的這為第三方擴展復(fù)用 Foam 的解析與渲染能力提供了穩(wěn)定的集成點。七、常見問題、已知問題與版本信息已知問題Known Issues可查看倉庫 GitHub Issues 頁面跟蹤。版本更新Release Notes見 packages/foam-vscode/CHANGELOG.md。調(diào)試日志通過Foam: Set Log Level調(diào)整日志級別輸出日志幫助定位問題更詳細(xì)的日志說明見文檔 docs/user/tools/foam-logging-in-vscode.md。此外Foam 生態(tài)里還有大量來自社區(qū)的使用場景recipes——自動 Git 同步、從移動端記錄、PDF 導(dǎo)出、實時協(xié)作、剪藏網(wǎng)頁等可按需查閱 docs/user/recipes/recipes.md 尋找靈感把 Foam 塑造成適合你自己的知識工作流?！久赓M下載鏈接】foamA personal knowledge management and sharing system for VSCode項目地址: https://gitcode.com/gh_mirrors/fo/foam創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考