朱志刚的数字花园

Hermes+Quartz 个人知识库全流程从零跑通指南 (V2.2-终极稳定版)

12 min read

《Hermes+Quartz 个人知识库：全流程从零跑通指南》

第一阶段：底层地基（环境构建与 Quartz 核心安装）

本章目标：在 Windows 宿主环境内激活 WSL2 虚拟化子系统，完成 Ubuntu 初始化，并安装 Quartz 印刷机核心引擎。

一、 开启 Windows 的 Linux 潜能 (WSL2)

  1. 打开 PowerShell：
    • 在 Windows 任务栏搜索框输入 PowerShell。
    • 右键点击”以管理员身份运行”。
  2. 执行安装指令： 
    wsl --install
  3. 重启电脑：完成组件激活。
  4. 初始化 Ubuntu：
    • 重启后自动弹出的黑色窗口中，按提示输入：
    • Enter new UNIX username: 建议使用小写英文（如 zzg）。
    • New password: 设置密码（输入时屏幕不显示字符）。
    • Retype new password: 再次确认。

二、 安装”印刷机”燃料 (Node.js)

Quartz 依赖 Node.js 环境运行。在 Ubuntu 终端内依次执行：

  1. 更新包列表： 
    sudo apt update
  2. 安装 Node.js 与 NPM： 
    sudo apt install nodejs npm -y
  3. 版本核验： 
    node -v
    注：若显示 v18 或更高版本号，则环境就绪。

三、 创建 Quartz 项目

  1. 进入主目录： 
    cd ~
  2. 创建项目文件夹： 
    mkdir quartz
  3. 进入文件夹： 
    cd quartz
  4. 初始化 Quartz： 
    npx quartz create

四、 关键交互决策 (Manual Choices)

在执行 npx quartz create 过程中，必须手动处理以下两次选择：

1. 初始化内容方式 (Initialize content)

  • 屏幕显示：Choose how to initialize the content in '...'
  • 操作：使用方向键选择 Empty Quartz。
  • 逻辑：避免导入冗余的样例文档。
  • 屏幕显示：Choose how Quartz should resolve links...
  • 操作：选择 Treat links as shortest path。
  • 逻辑：匹配 Obsidian 的默认双链链接规则。

五、 预览服务器首航测试

  1. 启动指令： 
    npx quartz build --serve
  2. 状态检查：
    • 终端输出：Started a Quartz server listening at http://localhost:8080。
    • 此时浏览器访问该地址应显示 404（因为尚未挂载 D 盘内容）。
  3. 停止服务：
    • 按下 Ctrl + C。

🛠️ 第一阶段：故障诊断手册

现象原因分析修复动作
输入密码无字符显示Linux 标准安全机制。盲打密码后直接回车。
npx: command not foundNPM 工具未正确安装。执行 sudo apt install npm。
npx quartz create 报错网络延迟或权限受限尝试添加 sudo 或更换网络环境

第二阶段：物理链路与云端对接（GitHub & Cloudflare）

本章目标：让 Linux 里的印刷机读到 D 盘的笔记，并建立起”本地—GitHub—Cloudflare”的自动化发布链路。

一、 打通物理链路（让印刷机看到纸张）

Quartz 默认在 Linux 内部寻找内容，而你的笔记在 Windows D 盘。我们需要建立一个特殊的”物理映射”。

  1. 进入项目目录： 
    cd ~/quartz
  2. 删除原有的内容文件夹（如果有）： 
    rm -rf content
  3. 创建一个新的真实挂载点： 
    mkdir content
  4. 执行物理挂载指令（请完整复制，包含引号）： 
    sudo mount --bind "/mnt/d/个人知识库/网站展示" ~/quartz/content
    • 动作说明：系统会提示 [sudo] password，输入你的 Ubuntu 密码并回车。
    • 逻辑原理：这一步是把 D 盘的文件夹直接”映射”进 Linux，Quartz 会认为这些文件就在它身边。

二、 建立 GitHub 云端仓库（创建接收容器）

这一步需要在浏览器中操作。

  1. 打开 GitHub 并登录。
  2. 点击右上角 + 按钮，选择 New repository。
  3. Repository name：填入 notes。
  4. 公开性选择：务必勾选 Private (私有)，防止个人笔记泄露。
  5. 点击底部的 Create repository。
  6. 获取地址：在生成的页面点击 SSH 选项卡，复制那串以 [email protected]... 开头的地址。

三、 推送代码上云（建立传送门）

回到 Ubuntu 终端，依次执行以下指令。

  1. 初始化本地 Git 仓库： 
    git init
  2. 将当前所有文件加入打包清单： 
    git add .
  3. 创建第一个版本记录： 
    git commit -m "🚀 部署 V2.2 自动化架构"
  4. 强制将分支重命名为 main（与 GitHub 对齐）： 
    git branch -M main
  5. 关联远程地址（请将下方地址替换为你刚才在 GitHub 复制的真实地址）： 
    git remote add origin [email protected]:你的用户名/notes.git
  6. 正式推送代码： 
    git push -u origin main

四、 配置 Cloudflare Pages（全球发布）

  1. 登录 Cloudflare 控制台。
  2. 进入 Workers & Pages → Create application → Pages → Connect to Git。
  3. 关键选项：在仓库列表中选择刚才创建的 notes。
    • 如果找不到，点击下方的 Cloudflare Pages 蓝色链接，在 GitHub 权限页将 notes 加入授权名单。
  4. 配置构建参数（最关键）：
    • Framework preset：选择 None。
    • Build command：手动输入 npx quartz build。
    • Build output directory：手动输入 public。
  5. 点击 Save and Deploy。
  6. 绑定子域名：
    • 部署成功后，点击 Custom domains。
    • 点击 Set up a custom domain。
    • 输入 notes.zhuzg.com 并保存。

🛠️ 第二阶段：常见错误与解决方法

现象原因分析解决方法
remote origin already exists之前已经关联过别的地址。执行 git remote set-url origin [新地址]。
src refspec main does not match本地分支不叫 main。执行 git branch -M main 强制更名。
Cloudflare 找不到 notes 仓库GitHub 授权范围不足。点击提示链接，在 GitHub 中添加该仓库的访问权限。
网页打开显示 404挂载失效或 index.md 缺失重新运行 sudo mount --bind 指令，并检查 D 盘是否有 index.md

第三阶段：Hermes 自动化与日常维护

本章目标：配置 Hermes 的”大脑”，设定快捷指令，并建立一套”安全第一”的发布工作流。

一、 设定”一字咒语” (Alias)

为了让你不需要记住那一长串 Linux 指令，我们要给系统设定一个快捷键，只需一个单词就能完成预览和自愈。

  1. 打开 Ubuntu 终端。
  2. 写入快捷指令（复制并运行这长长的一行）： 
    echo "alias fix='sudo mount --bind \"/mnt/d/个人知识库/网站展示\" ~/quartz/content && cd ~/quartz && npx quartz build --serve'" >> ~/.bashrc
  3. 刷新系统配置： 
    source ~/.bashrc
    • 效果：从现在起，只要你在终端输入 fix，系统就会自动帮你挂载 D 盘并开启本地预览。

二、 武装 Hermes — 系统指令配置 (V2.2-终极稳定版)

以下是完整的 Hermes 系统指令，覆盖到 Agent 的系统提示词中。这是区分”存笔记”和”推网站”两种意图的核心。

# Role: 知识库自动化架构师 (V2.2-终极稳定版)
 
## 一、 核心意图路由 (优先判定)
1. [网站同步模式]：若指令包含"同步网站/发布更新"。
   - 执行：sudo mount --bind "/mnt/d/个人知识库/网站展示" ~/quartz/content && cd ~/quartz && npx quartz sync
   - 反馈：告知公网同步已下达。
2. [知识库存储模式]：若以"知识库："开头。
   - 分级：[手册] 全文保存；[笔记/复盘] 逻辑重构。
   - 元数据：顶部强制 YAML (date, tags)。
   - 文件操作：使用 execute_code 中的 Python open() 直接写入 Inbox。实测验证 Python open() 写入 /mnt/d/ 能正常触发 Windows NTFS 变更通知，Auto Note Mover 可自动捕获并分类。
   - 指令示例：with open("FILE_PATH", "w", encoding="utf-8") as f: f.write(content)
   - 注意：为确保 Auto Note Mover 触发，写入前请确保文件未被其他进程占用（勿重复写入同一文件），且 Obsidian 处于运行状态。若 Obsidian 关闭时写入，需在 Obsidian 设置中开启 Auto Note Mover 的 "Process existing files on startup" 选项。
   - 路径：/mnt/d/个人知识库/Inbox/
   - 命名：YYYYMMDD_HHMM_主题.md
   - 反馈：仅回复"指令已执行，文件已存入收件箱"。
3. [常规对话]：执行专业辅助对话。
 
## 二、 物理路径约束
- 私密：/mnt/d/个人知识库/Inbox/
- 公开：/mnt/d/个人知识库/网站展示/

三、“安全第一”的日常维护工作流

这是你作为架构师需要遵守的操作标准，确保任何敏感信息都不会误发。

  1. 采集 (AI 辅助)：
    • 随时随地发微信/网页内容给 Hermes，并在前面加 “知识库：”。
    • Hermes 会将其存入你的 Inbox。
  2. 脱敏 (人工审核)：
    • 在电脑上打开 Obsidian，找到 Inbox 里的新笔记。
    • 关键动作：若要公开，请将其复制一份到 网站展示 文件夹，并删掉里面的敏感信息（密码、私密想法等）。
  3. 发布 (一键上云)：
    • 确认无误后，直接对 Hermes 说：“同步网站”。
    • 它会执行同步指令，你的 notes.zhuzg.com 将在 1 分钟后更新。

四、 自愈与灾备 (404 快速修复)

当你重启电脑，或者网站打不开时，请对照下表操作：

现象处理动作
本地 http://localhost:8080 打不开在终端输入 fix 即可。
网站显示 404，没有内容对 Hermes 说 “同步网站”。这会重新触发物理挂载，让系统找回 D 盘的纸张。
同步时提示 Permission denied重新运行 fix 或 sudo mount 命令，并正确输入你的 Ubuntu 密码。

🏁 结语：你的数字花园已落成

现在，你拥有一套由 WSL2 驱动性能、Quartz 驱动美学、GitHub/Cloudflare 驱动分发、Hermes 驱动自动化的闭环系统。

  • 你是总控官：负责内容的安全与决策。
  • Hermes 是执行官：负责琐碎的 Linux 指令与排版。

Graph View