又一 VSCode 神器诞生！用 Foam 把 Markdown 笔记一键发布到 GitHub Pages 并接入 TaoToken

1. 为什么我又折腾起了 Foam从本地笔记到线上知识库Foam 是一款跑在 VSCode 里的 Markdown 知识库插件它能把你散落一地的.md文件变成一张可点击、可跳转、可预览的节点图还能顺手把内容发布到 GitHub Pages 上。适合谁适合那些已经在用 VSCode 写笔记、写文档、写教程但受够了「本地写完就吃灰」的开发者。我自己的痛点很具体笔记越攒越多文件夹层级越挖越深想找半年前写的一段配置说明得靠全局搜索硬翻更别说分享给同事只能截图或者打包发压缩包。Foam 解决的就是这两件事。第一它用[[双链]]语法把笔记之间的引用关系显式化右侧自动生成关系图和预览你点一下就能跳过去思路不会断。第二它内置了发布到 GitHub Pages 的工作流本地写完 push 一下线上就能访问等于白嫖一个静态站点托管。这套组合下来Markdown 笔记不再是死文件而是一个能对外访问的小型知识站。但这里有个现实问题当你想在 Foam 工作区里接入 AI 能力比如自动补全笔记、生成摘要、或者让 Agent 帮你整理目录结构时你会发现每个工具都要单独配 Key、单独填 Base URL管理起来很碎。我试过在settings.json里塞三四个不同的 API 配置改一个忘一个最后自己都搞不清哪个 Key 对应哪个服务。所以这篇的重点除了 Foam 本身的搭建和发布还会给出一套在 VSCode 里统一接入 TaoToken 的配置骨架让 Key 和通道收敛到一处。2. 从零搭建 Foam 工作区插件、目录与双链语法2.1 安装 Foam 插件打开 VSCode进入扩展面板搜索Foam认准发布者是foambubble的那个。安装完成后VSCode 会提示你「Foam 需要初始化工作区」你可以直接点它给的按钮也可以手动来。手动方式更可控。新建一个空文件夹比如my-knowledge-base用 VSCode 打开这个文件夹然后按CtrlShiftPmacOS 是CmdShiftP调出命令面板输入Foam: Create New Workspace回车。Foam 会自动生成一套初始结构my-knowledge-base/ ├── .vscode/ │ └── settings.json ├── .foam/ │ └── templates/ │ └── daily-note.md ├── attachments/ ├── getting-started.md └── readme.md.vscode/settings.json是 Foam 写进去的推荐配置后面我们要在这里追加 TaoToken 的接入参数。.foam/templates放的是笔记模板attachments用来存图片等附件。2.2 双链语法与关系图Foam 的核心语法就一个[[文件名]]。比如你在getting-started.md里写今天开始整理我的 API 调试笔记先记一下 [[TaoToken 接入配置]] 的要点。保存后Foam 会自动在右侧的Foam: Graph面板里生成一个节点并且把TaoToken 接入配置这个文件标记为「未创建」。你点一下这个链接Foam 就会帮你新建同名文件双链关系自动建立。这个体验很像 Obsidian但完全跑在 VSCode 里不用切编辑器。右侧面板除了关系图还有Foam: Preview能实时渲染 Markdown。我习惯把关系图放在右上角预览放在右下角左边写正文三栏布局写笔记的时候引用关系一目了然。2.3 目录组织建议Foam 不强制目录结构但为了后面发布到 GitHub Pages 时路径清晰建议按主题分文件夹my-knowledge-base/ ├── notes/ │ ├── api/ │ ├── frontend/ │ └── devops/ ├── posts/ │ └── 2025-01-foam-guide.md └── index.mdindex.md作为首页posts放准备发布的文章notes放日常笔记。这样 GitHub Pages 构建出来的站点结构也干净。3. 配置 GitHub Pages 自动发布Actions 工作流拆解3.1 仓库准备与 Pages 设置先在 GitHub 上新建一个仓库名字随意比如foam-notes。本地工作区初始化 git 并关联cd my-knowledge-base git init git add . git commit -m init foam workspace git branch -M main git remote add origin gitgithub.com:yourname/foam-notes.git git push -u origin main推送完成后进入仓库的Settings→Pages在Build and deployment里把Source选成GitHub Actions。注意不要选Deploy from a branch因为我们要用自定义工作流来控制构建过程。3.2 编写发布工作流在项目根目录新建.github/workflows/publish.yml内容如下name: Publish Foam to GitHub Pages on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install Foam CLI run: npm install -g foamnotes/foam-cli - name: Build static site run: foam export --output _site - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: _site deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这个工作流做了三件事检出代码、安装 Foam CLI、执行foam export把 Markdown 导出成静态 HTML最后上传并部署到 Pages。foam export会自动处理双链跳转和关系图生成的_site目录就是最终站点。3.3 触发发布与验证提交这个工作流文件git add .github/workflows/publish.yml git commit -m add pages workflow git push推送后进入仓库的Actions标签页能看到Publish Foam to GitHub Pages正在运行。等它跑完回到Settings→Pages顶部会显示你的站点地址格式是https://yourname.github.io/foam-notes/。打开这个地址应该能看到 Foam 导出的首页和笔记列表。如果构建失败最常见的原因是foam export命令不存在或者参数不对。可以在本地先跑一遍npx foamnotes/foam-cli export --output _site确认命令可用再推到 Actions 里。4. 在 settings.json 中接入 TaoToken 统一 Key/API 通道4.1 为什么要在 VSCode 里统一接入Foam 本身不依赖 AI但你在写笔记时可能会用到 Copilot 类的补全、或者用 Agent 插件做摘要。这些工具各自要填 API Key 和 Base URL配置分散。TaoToken 提供的是统一的 Key 和 API 通道你只需要在settings.json里配一次后续换模型或者换工具时改一处就行。官网地址是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endAPI 入口是https://taotoken.net/api。4.2 可复制的配置骨架打开.vscode/settings.json在原有 Foam 配置的基础上追加以下内容{ foam.files.ignore: [ **/.git/**, **/node_modules/**, _site/** ], foam.graph.style: { background: #1e1e1e, fontSize: 12 }, taotoken.apiBase: https://taotoken.net/api, taotoken.apiKey: ${env:TAOTOKEN_API_KEY}, taotoken.defaultModel: claude-3-5-sonnet, taotoken.timeout: 60000, editor.inlineSuggest.enabled: true, editor.quickSuggestions: { other: true, comments: false, strings: true } }这里有几个点要注意。taotoken.apiKey我用了环境变量引用${env:TAOTOKEN_API_KEY}而不是把 Key 明文写进文件。你可以在本地终端里设置export TAOTOKEN_API_KEY你的KeyWindows 用户用setx TAOTOKEN_API_KEY 你的Key。这样settings.json可以安全地提交到仓库不会泄露 Key。taotoken.apiBase指向https://taotoken.net/api这是统一的 API 入口。defaultModel可以先填一个你常用的模型名后续在具体工具里覆盖。4.3 获取 Key 与文档入口如果你还没有 Key去 TaoToken 控制台创建一个。入口是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite。创建后在 API Keys 页面复制存到环境变量里。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言的调用示例和参数说明。5. 验证请求从 curl 到 VSCode 内实测5.1 用 curl 验证通道配置写完后先别急着在插件里试用 curl 确认通道通不通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-3-5-sonnet, messages: [ {role: user, content: 用一句话解释 Foam 的双链语法} ], max_tokens: 100 }如果返回 JSON 里choices[0].message.content有内容说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整返回 404检查apiBase是否写成了https://taotoken.net/api而不是带/v1的路径。5.2 在 VSCode 内触发补全回到 VSCode打开任意一个.md文件在正文里输入一段注释或者半句话比如Foam 的发布流程主要依赖然后停顿一下。如果editor.inlineSuggest.enabled生效并且你装了支持 TaoToken 的补全插件应该能看到灰色的补全建议。按Tab接受。如果没有反应按CtrlShiftP打开命令面板输入Developer: Reload Window重载窗口让settings.json的改动生效。然后再试一次。5.3 验证发布后的站点本地验证通过后把改动提交并推送git add . git commit -m add taotoken config and notes git push等 Actions 跑完打开你的 Pages 地址确认新笔记已经出现在站点上。如果笔记里有双链点进去应该能正常跳转。到这一步本地写作、AI 辅助、线上发布这条链路就通了。6. 本篇常见错排查6.1 Foam 关系图不显示节点最常见的原因是文件没有被 Foam 索引。检查.vscode/settings.json里的foam.files.ignore是否把当前目录排除了。另外Foam 只索引工作区根目录下的文件如果你把笔记放在工作区外面它看不到。解决方法是把笔记移进工作区或者用 VSCode 的多根工作区功能把外部目录加进来。6.2 GitHub Actions 构建报错foam: command not found说明npm install -g foamnotes/foam-cli这一步没成功或者 Node 版本不对。检查工作流里的node-version是否写成了20以及npm install那一步有没有报错。如果 npm 源慢可以在工作流里加一步npm config set registry https://registry.npmmirror.com再安装。6.3 TaoToken 请求返回 401 或 403先确认环境变量TAOTOKEN_API_KEY在当前终端里能echo出来。如果是在 VSCode 里启动的终端可能需要重启 VSCode 让环境变量生效。另外检查settings.json里taotoken.apiKey的引用写法是否正确${env:TAOTOKEN_API_KEY}是 VSCode 的变量替换语法不是 shell 语法。6.4 发布后样式丢失或双链 404foam export默认会生成相对路径的链接。如果你的 Pages 站点部署在子路径下比如https://yourname.github.io/foam-notes/需要在导出时指定--base-url /foam-notes/。修改工作流里的构建命令- name: Build static site run: foam export --output _site --base-url /foam-notes/这样生成的 HTML 里资源路径和双链跳转都会带上正确的子路径前缀。6.5 笔记里的图片不显示Foam 默认把附件放在attachments目录引用时用。如果图片在导出后不显示检查attachments目录是否被foam.files.ignore排除了。另外GitHub Pages 对文件名大小写敏感确保引用路径和实际文件名完全一致。整套流程跑下来你会发现 Foam 的价值不在于某个单点功能而在于它把「写」和「发」串成了一条线。本地用 VSCode 写 Markdown双链组织知识push 后自动发布到 PagesAI 能力通过 TaoToken 统一接入不用在多个 Key 之间来回切换。如果你也在用 VSCode 管理笔记这套配置可以直接复制过去改改就用。