企业官网建设流程全解析

• 知识管理
• 知识库
• 开发工具
• MCP 服务

Foam 的个人知识管理（PKM）体系建立在"工作区"（Workspace）之上——一个存放 Markdown 笔记的文件夹，配合 VS Code 扩展即可获得 wikilinks、反向链接、图谱视图与每日笔记等能力。本文以 first-workspace.md 为主线，从工作区概念讲起，给出"模板创建"与"从零搭建"两种实战路径，并结合本仓库源码剖析工作区背后的模板引擎、每日笔记与配置解析机制，帮你快速搭建一个可长期扩展的数字花园。

理解 Foam 工作区：一个装满 Markdown 的文件夹

Foam 工作区的本质非常简单：一个包含 Markdown 文件（.md）的文件夹，也就是你的笔记本身。除此之外，它还可以（可选地）包含：

• 配置文件（Configuration files）——VS Code 设置与 Foam 偏好，典型如.vscode/settings.json
• 资产（Assets）——图片、附件与其他媒体文件
• 模板（Templates）——可复用的笔记结构，默认存放在.foam/templates/目录

从源码看，Foam 核心对工作区的识别是"文件夹 + Markdown 文件"这一极简模型。在 config.ts 的默认配置中，文件包含规则为**/*，默认笔记扩展名为.md，附件扩展名覆盖pdf mp3 webm wav m4a mp4 avi mov rtf txt doc docx pages xls xlsx numbers ppt pptm pptx等，模板文件夹默认为.foam/templates。也就是说，你不需要任何额外的初始化动作，Foam 会以零配置的方式把文件夹当作工作区启动。

单一工作区 vs 多个工作区

官方文档明确提示：多工作区方案已被标记为 deprecated，未来可能不再支持。如果你确实需要模拟复杂工作区结构，可以通过文件/文件夹链接（file/folder links）来实现，而不是创建多个 VS Code 工作区。这也是 Foam 强调"统一知识库"（unified knowledge base）理念的直接体现。

方法一：使用 Foam 模板创建（推荐）

对大多数用户而言，最快的方式是使用官方预配置的 foam-template 模板仓库。

第 1 步：从模板创建仓库

1. 打开foambubble/foam-template模板仓库主页（github.com/foambubble/foam-template）；
2. 点击"Use this template"（需要 GitHub 账号）；
3. 为仓库命名（例如john-knowledge-base、my-second-brain）；
4. 选择可见性：
   • Private（私有）——适合个人笔记（推荐）；
   • Public（公开）——如果你希望公开分享知识。

第 2 步：克隆到本地

git clone https://github.com/yourusername/your-repo-name.git cd your-repo-name

第 3 步：在 VS Code 中打开

1. 启动 VS Code；
2. 执行File > Open Folder；
3. 选择刚克隆的仓库文件夹。

模板仓库自带了一组开箱即用的.vscode/settings.json配置与推荐扩展清单，打开后 VS Code 会提示安装推荐扩展（见 recommended-extensions.md，其中包含 Foam for VSCode、Markdown All In One、Prettier 三项自动推荐的扩展），确认后即可开始写作。

方法二：从零开始搭建

如果你想要最小化配置，只需要：

1. 在电脑上新建一个文件夹；
2. 在 VS Code 中打开该文件夹（File > Open Folder）。

仅此而已——剩下的交给 Foam：你可以直接开始编写 Markdown 文件，wikilinks、反向链接、图谱等能力会自动生效。

已经拥有 Obsidian 仓库？可以直接在 VS Code 中打开它，无需迁移——参见 migrating-from-obsidian。Obsidian 的 vault 本质上就是 Markdown 文件夹，与 Foam 工作区结构一致，两者可以并存使用同一目录。

让你的知识库更实用：三种初始化实践

工作区建立后，官方文档推荐按以下三个方向做初始配置，让知识库从"能跑"走向"好用"。

1. 定制你的设置

打开.vscode/settings.json，按个人偏好调整：

• 每日笔记位置（Daily notes location）——每日笔记文件存放在哪个目录；
• 图片处理（Image handling）——粘贴的图片如何组织归档；
• 链接格式（Link format）——wikilinks 是否带文件扩展名。

这里值得一提的是链接格式的实际影响：Foam 的 wikilinks 支持"标识符链接"（如[[filename]]、[[folder/filename]]）与"路径链接"（如[[./file]]、[[../other/file]]），详见 wikilinks.md。若你的笔记需要与标准 Markdown 处理器兼容，Foam 还能自动生成 link-reference-definitions 到文件末尾。

2. 建立你的收件箱（Inbox）

创建inbox.md作为默认的快速捕获入口：

# Inbox Quick notes and ideas go here before being organized. ## Today's Captures - ## To Process - ## Ideas -

收件箱的价值在于"先捕获、后整理"：随手记下的想法先进入收件箱，再在定期回顾时归档到正式笔记，避免打断当前思路。

3. 创建核心结构笔记

Foam 不强制任何组织方法论（"Foam is not opinionated"），唯一的建议是先开始，再逐步改进。用户社区最常采用的两套方法是 PARA 与 Zettelkasten。

PARA 方法——围绕四个类别组织：

• Projects（项目）——有截止日期的事情；
• Areas（领域）——持续性的责任范围；
• Resources（资源）——未来参考的材料；
• Archive（归档）——不再活跃的内容。

Zettelkasten 方法——基于编号的原子化想法系统：

• 永久笔记（Permanent notes）——202501251030-idea-title.md这类带时间戳的命名；
• 文献笔记（Literature notes）——book-author-year.md；
• 索引笔记（Index notes）——index-topic.md。

两种方法可以混用：PARA 负责粗粒度的目录划分，Zettelkasten 负责笔记间的细粒度关联，最终都通过 wikilinks 连接成网。

配置每日笔记

每日笔记适合日常规划与反思、会议记录、日记、快速捕获等场景。工作区建好后，官方文档建议立即验证每日笔记是否工作正常：

1. 按Ctrl+Shift+P（macOS 为Cmd+Shift+P）打开命令面板；
2. 输入"Foam: Open Daily Note"；
3. 验证笔记是否创建在正确的位置。

更快的替代方式是快捷键：Alt+D打开今天的每日笔记，Alt+H打开其他日期的每日笔记。

从源码看，该命令由 open-daily-note.ts 注册为foam-vscode.open-daily-note，内部调用openDailyNoteFor(new Date(), foam)完成创建；同时它还支持openDailyNote.onStartup配置，在 VS Code 启动时自动打开每日笔记：

{ "foam.openDailyNote.onStartup": true }

默认情况下，每日笔记以yyyy-mm-dd.md命名并存放于工作区的journals文件夹。想要自定义位置与格式，最推荐的方式是创建.foam/templates/daily-note.md模板（旧版openDailyNote.*设置已弃用并将被移除，请改用模板）：

--- type: daily-note --- # Daily Note - $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE ## Tasks - [ ] ## Notes

模板中的FOAM_DATE_*系列变量由 variable-resolver.ts 统一定义与解析，包括FOAM_DATE_YEAR（四位年份）、FOAM_DATE_MONTH（两位月份）、FOAM_DATE_DATE（两位日期）、FOAM_DATE_WEEK（ISO 周数）、FOAM_DATE_DAY_ISO（ISO 星期编号，周一=1）等。与 VS Code 原生CURRENT_YEAR等变量相比，FOAM_DATE_*的一个重要优势是：当使用相对每日笔记片段（如/tomorrow）创建笔记时，变量会填充相对日期而非当前日期，行为符合直觉。

链接到上一篇每日笔记

$FOAM_PREVIOUS_DAILY_NOTE变量会展开为创建笔记之前最近存在的一篇每日笔记——它会跳过空缺日期，因此经过周末或假期后，它指向你实际写过的最后一篇笔记，而/yesterday总是严格指日历上的前一天：

--- type: daily-note --- # $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE Previously: [[$FOAM_PREVIOUS_DAILY_NOTE]]

第一篇每日笔记没有"上一篇"，该变量会展开为空。可以为其提供回退值：

Previously: ${FOAM_PREVIOUS_DAILY_NOTE:nothing yet}

该变量仅在每日笔记模板中可用，其实现原理相当精妙：Foam 通过逆向解析每日笔记模板的filepath模式来识别已有笔记。在 daily-note-path-pattern.ts 中，路径模式被解析为"字面量 + 日期 token"的序列，再编译成正则表达式反向读取日期；previous-daily-note.ts 则扫描整个工作区、按日期比较找出最接近的一篇。由此可以推导出几个使用约束：

• 模板路径必须用数字拼出年、月、日——/journal/$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE.md或$FOAM_TITLE均可；使用月份名称（$FOAM_DATE_MONTH_NAME）或周数（$FOAM_DATE_WEEK）的路径无法被反向解析，变量会保持为空、显示回退值；
• 修改过路径后，旧路径下已存在的每日笔记不再被识别；
• JavaScript 模板在运行时才决定路径，因此该变量在其中为空——JS 模板需要自行查找上一篇笔记。

日期片段（Date Snippets）

在任意笔记中输入以下片段可快速创建指向近期每日笔记的链接：

片段触发后默认直接创建对应笔记（配置项foam.dateSnippetsAfterCompletion可改为noop或navigateToNote，见 config.ts）。在终端环境中也可以使用foam daily命令操作每日笔记，详见 CLI daily 命令文档。

新工作区的最佳实践

1. 从小开始（Start Small）

• 只从几篇笔记起步；
• 不要一开始就过度组织；
• 让结构自然生长。

2. 使用模板（Use Templates）

• 为常见笔记类型创建模板；
• 保持同类笔记的一致性；
• 节省重复排版时间。

Foam 的模板体系完整支持 Markdown 模板（.md，含$FOAM_TITLE、$FOAM_SELECTED_TEXT、$FOAM_CURRENT_DIR、$FOAM_SLUG等变量与 tab stop）和 JavaScript 模板（.js，可基于星期几、触发上下文动态生成内容并自定义文件路径），两者统一由 note-creation-engine.ts 这一"统一引擎"处理——processTemplate根据模板类型分发到executeJSTemplate或executeMarkdownTemplate。默认模板的查找顺序是.foam/templates/new-note.js→.foam/templates/new-note.md，每日笔记模板则为daily-note.js→daily-note.md（见 template-discovery.ts）。完整语法请参考 templates.md。

3. 尽早且频繁地建立链接（Link Early and Often）

• 大胆使用[[wikilinks]]；
• 不必担心建立"完美"的链接；
• Foam 会优雅地处理坏链接。

这是 Foam 体验中非常独特的一点：指向不存在笔记的 wikilinks 会生成占位符（placeholder），在编辑器中以不同样式高亮，点击即可创建对应笔记。从 note-creation-triggers.ts 可以看到，Foam 将"从占位符创建笔记"建模为一种独立的触发类型placeholder（携带来源笔记的 URI、标题与位置），与命令触发（command）并列。因此你可以先规划知识结构、再逐步填充内容，占位符天然承担了"待办蓝图"的角色。

4. 定期回顾（Regular Reviews）

• 每周做一次工作区清理；
• 归档已完成的项目；
• 识别缺失的连接（孤儿笔记可通过 orphans 工具 发现）。

同步与备份

Foam 基于纯文件工作，因此你可以自由选择任何备份方案叠加其上。

Git 同步

你的工作区本身就是一个 Git 仓库：

git add . git commit -m "Add new notes and ideas" git push origin main

也可以借助其他 VS Code 扩展管理 Git 同步（例如 GitDoc 实现自动 Git 同步，或直接使用 VS Code 内置的Git: Commit All命令）。详细的同步实践可参考 sync-notes.md。

其他同步方式

• 云存储——Dropbox、OneDrive、Google Drive；
• 本地备份——Time Machine、File History；
• 手动导出——定期制作 ZIP 备份。

下一步

工作区搭建完成后，你可以继续学习：

1. note-taking-in-foam——掌握 Markdown 与高效笔记写作；
2. navigation——用 wikilinks 连接你的想法；
3. graph view——可视化你的知识网络；
4. templates——标准化你的笔记创建流程。

获取帮助

遇到搭建问题时的求助路径：

• 查看 Installation Guide 确认前置条件（VS Code 安装、Foam 扩展安装、推荐扩展与可选 Foam CLI：npm install -g foam-cli）；
• 阅读 frequently-asked-questions 排查常见工作区问题（如链接/图谱/反向链接不生效时，先确认推荐扩展是否齐全、是否执行过Developer: Reload Window、链接格式是否符合 wikilinks 规则）；
• 加入 Foam 社区 Discord 获取实时交流。

附录：源码延伸阅读

如果你想深入理解工作区背后的实现，以下仓库路径值得一读：

• note-creation-engine.ts——Markdown/JavaScript 模板的统一处理引擎与文件路径净化逻辑；
• variable-resolver.ts——FOAM_*系列变量的定义与解析（含全部FOAM_DATE_*变量）；
• daily-note-resolver.ts——每日笔记内容与路径的解析入口，无 VS Code 依赖，CLI 与扩展共用；
• daily-note-path-pattern.ts——每日笔记路径模式的正向生成与逆向识别；
• previous-daily-note.ts——FOAM_PREVIOUS_DAILY_NOTE的实现（扫描工作区、按天比较）；
• config.ts——全部 Foam 配置项的默认值与层级合并机制；
• daily-note-path-pattern.test.ts——路径逆向解析的测试用例，直观展示哪些路径模式可被识别。

理解了"工作区 = 文件夹 + Markdown 文件"这一核心模型，再结合模板与每日笔记机制，你就能在 Foam 中搭建一个既简单、又可随知识规模平滑扩展的个人知识管理系统。

• 知识管理
• 知识库
• 开发工具
• MCP 服务