Tree of Wisdom · 全链工作流

版本：v3 | 定稿日：2026-05-24 | 执笔：伯喈（整合审固 v3 + 六轮技术验证）读者：主公、严律、审固、伯喈

零、项目前因

缘起

主公（GitHub: hhaya-xu）在 D:\ai 搭建了一个知识库系统：

Obsidian 本地写笔记
Quartz v4 将 Markdown 生成静态网站（含知识图谱、反向链接、搜索）
GitHub Pages 免费托管发布

仓库：https://github.com/hhaya-xu/Tree-of-Wisdom 站点：https://hhaya-xu.github.io/Tree-of-Wisdom/

当前项目

「入流亡所群聊录」——观世音菩萨耳根圆通法门的现代实修记录。5 人群聊对话（呆呆酱/真维主述，真正/真湛/真恒/真贞交流见证），按时间线展开。

核心需求

网站有独特视觉风格（暗底暖金 Atmospheric 调性，参考 bianjing-hours.art + usehallmark.com）
知识图谱在右侧栏，有视觉冲击力，可交互
左栏固定导航，右栏可切换内容区/图谱区的大小
主公只写 Obsidian MD，不改代码
伯喈负责所有技术实现
严律负责阶段 4 代码审查

一、架构总览

┌─────────────────────────────────────────────────┐
│                   主公（内容）                     │
│          Obsidian 写 MD → Git 自动推送            │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│                  伯喈（技术）                      │
│   CSS 壳 + Hallmark 美学 + Quartz 构建 + 部署     │
│                                                  │
│   ┌──────────┐   ┌──────────┐   ┌────────────┐  │
│   │ custom.  │   │ variables│   │ sidebar-   │  │
│   │ scss     │   │ .scss    │   │ toggle.js  │  │
│   └──────────┘   └──────────┘   └────────────┘  │
│                                                  │
│   ┌──────────────────────────────────────────┐   │
│   │           Quartz v4.5.2                    │   │
│   │   MD → HTML + 图谱 + 反向链接 + 搜索       │   │
│   └──────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│               GitHub Pages（发布）                │
│     https://hhaya-xu.github.io/Tree-of-Wisdom/   │
└─────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│                  严律（审查）                      │
│      阶段 4 审查 TSX 补丁 + 关键 CSS 规则          │
└─────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│                  审固（批评）                      │
│           阶段间挑刺 + 方法回收日志                 │
└─────────────────────────────────────────────────┘

二、角色分工

角色	做什么	不做什么	介入时机
主公	写 MD 内容、审核预览、确认发布	不写代码	全程
伯喈	CSS 壳、Hallmark、Quartz 构建、GitHub 部署	不决定内容	全程
严律	阶段 4 审查 TSX 逻辑 + 关键 CSS 规则	不参与前期	阶段 4
审固	阶段间挑刺、方法回收日志	不执行	阶段边界

三、主公操作手册

你需要做的

在 Obsidian 里写笔记，保存即可
Obsidian Git 插件每隔 10 分钟自动 commit + push
浏览器打开站点看效果，不满意就描述给我
确认发布——说”可以了”我就 push

MD 文件规范（三条规则）

规则 1：文件放在正确位置

content/
├── 入流亡所策展/
│   ├── 定题说明.md              ← 项目说明
│   ├── 策展文本/                ← 放策展页 MD
│   │   ├── Day1-2026-04-14-入流.md
│   │   ├── Day2-2026-04-16.md
│   │   └── ...
│   ├── 术语库/                  ← 放术语条目 MD
│   │   ├── 入流亡所.md
│   │   ├── 三摩地.md
│   │   └── ...
│   └── 原始材料/                ← 群聊录原文（不改动）
│       └── 入流亡所群聊录-原文.md
├── 系统/                        ← 系统文件
│   ├── 伯喈.md                  ← 伯喈人物档案
│   └── 全链工作流.md            ← 本文档
└── 日常笔记/                    ← 非策展内容的普通笔记

规则 2：frontmatter 写三行

---
title: "Day1 · 2026年4月14日"
date: 2026-04-14
description: "凌晨病发，呆呆酱初入流亡所的体验记录"
---

title：显示在页面顶部和浏览器标签
date：用于时间线排序
description：显示在右栏内容区顶部（简介文字，可选）

规则 3：术语用 [[wikilink]]

正文中首次出现的佛法术语，用 [[入流亡所策展/术语库/入流亡所|入流亡所]] 创建双向链接。

写完就完——不需要手动登记索引、不需要填映射表、不需要跑任何命令。

四、伯喈工作清单

阶段 1：CSS 布局壳（当前）

1.1 右栏 Flex 双区 + expand/collapse 交互

技术背景：

Quartz DOM 结构：#quartz-body（CSS Grid 容器）→ .left.sidebar + .center + .right.sidebar
右栏内现有元素：.graph（关系图谱）+ .toc（目录）+ .backlinks（反向链接）
body[data-slug] 包含页面路径，且 SPA 导航时 micromorph 会更新该属性 → CSS 选择器安全

实现方案：

右栏改为 Flex 列布局，分两个 zone：.sidebar-content-zone（内容区）+ .sidebar-graph-zone（图谱区）
初始状态：图谱区 flex-grow: 3，内容区 flex-grow: 1
点击标题栏切换：目标区 flex-grow: 5，另一区 flex-grow: 0.5
CSS transition：transition: flex-grow 0.35s ease
JS 事件：document.body 事件委托（SPA 安全）+ nav 事件兜底重置

1.2 桌面端 Grid 锁定

@media (min-width: 1200px) {
  #quartz-body {
    grid-template-columns: 260px 1fr 300px;
  }
  .left.sidebar {
    position: sticky;
    top: 0;
    height: 100vh;
    overflow-y: auto;
  }
}

1.3 正文行宽

@media (min-width: 1200px) {
  .center article {
    max-width: 62ch;
    margin: 0 auto;
  }
}

1.4 空右栏隐藏

@media (min-width: 1200px) {
  /* tag / folder / 404 页右栏为空，隐藏 */
  .right.sidebar:not(:has(.graph, .backlinks)) {
    display: none;
  }
  #quartz-body:has(.right.sidebar:not(:has(.graph, .backlinks))) {
    grid-template-columns: 260px 1fr 0;
  }
}

1.5 Hallmark 美学贯穿

全色值 OKLCH（已在 quartz.config.ts darkMode + custom.scss 中完成）
字重：display 800（标题）/ body 300（正文）
字距：h1 .article-title 收紧 -0.02em
字体：Noto Serif SC（标题）+ Noto Sans SC（正文）+ Geist Mono（代码/时间戳）
正文行宽 62ch
字体加载淡入动画（CSS keyframes，0.4s）
暗底暖金底纹（径向渐变 + 网格纹理）
五人物颜色：呆呆酱 oklch(78% 0.075 82) / 真贞 oklch(63% 0.06 180) / 白羊 oklch(66% 0.07 35) / 真湛 oklch(67% 0.08 130) / 宏亮 oklch(62% 0.06 260)

1.6 自定义 JS 文件位置

新建 quartz/components/scripts/sidebar-toggle.inline.ts，通过组件 afterDOMLoaded 引用。

阶段 2：术语页原型

术语页保留右栏（有反向链接），正文 58ch
Hallmark audit 术语页样式
主公确认

阶段 3：批量内容

主公写后续 Day MD + 术语条目
伯喈每次新内容 build 后跑 Hallmark audit 快速检查

阶段 4：技术收尾 + 严律审查

4.1 TSX 右栏子组件条件渲染（严律重点审查项）

当前用 CSS display:none 隐藏空右栏——DOM 中仍存在。需要改为组件级条件渲染：

// PageLayout.tsx 右栏渲染区域
// 判断依据：page slug 模式
// - tag/404 页：不渲染右栏任何子组件
// - 策展文本：渲染 Graph + Backlinks
// - 术语条目：渲染 Graph + Backlinks
// - folder 索引：不渲染右栏

改动位置：quartz/components/PageLayout.tsx 判断条件：fileData.slug 字符串匹配改动量：约 15 行

4.2 性能备注

在 custom.scss 中 :has() 嵌套链处添加注释：

/* perf: :has() chain <1ms @ ~100 pages; if >500 pages, switch to JS class toggling */

4.3 移动端验证

所有 Grid 规则包 @media (min-width: 1200px)
移动端布局使用 Quartz 默认堆叠（已确认兼容）

4.4 严律审查清单

审查项	文件	关键点
右栏条件渲染逻辑	`PageLayout.tsx`	slug 匹配是否正确、是否遗漏页面类型
Grid 列定义	`custom.scss`	`grid-template-columns` 值、`@media` 边界
`:has()` 嵌套链	`custom.scss`	选择器是否过于宽泛、性能备注是否到位
右栏 JS 交互	`sidebar-toggle.inline.ts`	SPA 安全、事件清理、无内存泄漏
Hallmark 色值	`custom.scss` + `quartz.config.ts`	全部 HEX 已转 OKLCH
移动端	`custom.scss`	无 media query 遗漏

4.5 Hallmark 印记

在 custom.scss 底部添加 Hallmark 注释标记。

阶段 5：发布 + 回收

首次 push → GitHub Actions 自动部署
主公确认线上站点
审固写方法回收日志

五、技术上下文（供严律参考）

项目路径

组件	路径
Obsidian Vault	`D:\ai\my-knowledge-base\content\`
Quartz 根	`D:\ai\my-knowledge-base\`
自定义样式	`D:\ai\my-knowledge-base\quartz\styles\custom.scss`
Grid 变量	`D:\ai\my-knowledge-base\quartz\styles\variables.scss`
Quartz 配置	`D:\ai\my-knowledge-base\quartz.config.ts`
GitHub 仓库	`git@github.com:hhaya-xu/Tree-of-Wisdom.git`
站点 URL	`https://hhaya-xu.github.io/Tree-of-Wisdom/`

关键 DOM 结构

<body data-slug="入流亡所策展/策展文本/Day1-2026-04-14-入流">
  <div id="quartz-root" class="page">
    <div id="quartz-body">
      <div class="left sidebar">       ← 导航、搜索、Explorer
      <div class="center">              ← 正文内容（article）
      <div class="right sidebar">       ← 图谱 .graph + 目录 .toc + 反向链接 .backlinks
    </div>
  </div>
</body>

SPA 路由行为

Quartz 使用 micromorph 做 DOM morphing
document.body 元素本身保持不变（事件委托安全）
body[data-slug] 随导航自动更新
图谱组件监听 nav 事件重新渲染
window.addCleanup(fn) + window.spaNavigate(url) 是 Quartz 公开 API

注意： quartz.config.ts 中 lightMode/darkMode 使用 HEX 值（#0d0c0a 等），非 OKLCH。原因是 CustomOgImages 插件不支持 OKLCH 解析。实际渲染色彩由 custom.scss 中 OKLCH 规则控制，config 仅用于 Quartz CSS 变量兜底。

色彩体系

全部使用 OKLCH 色彩空间（Hallmark 方法论）。暗色模式基准值：

CSS 变量	OKLCH 值	用途
`--light`	`oklch(12% 0.005 80)`	最深背景
`--lightgray`	`oklch(20% 0.005 82)`	次深背景
`--gray`	`oklch(35% 0.018 82)`	分割线、次要文字
`--darkgray`	`oklch(84% 0.028 86)`	正文颜色
`--dark`	`oklch(92% 0.022 86)`	标题、强调
`--secondary`	`oklch(78% 0.075 82)`	链接、琥珀金
`--tertiary`	`oklch(85% 0.08 85)`	悬停、高亮

页面类型与右栏策略

页面类型	slug 匹配	图谱	反向链接	正文宽度	右栏
策展文本	`策展文本`	✅	✅	62ch	显示
术语条目	`术语库`	✅	✅	58ch	显示
人物页	待建	❌	✅	62ch	显示
索引页	`*/index`	❌	❌	默认	隐藏
Tag 页	`tags/*`	❌	❌	默认	隐藏
404	`404`	❌	❌	默认	隐藏

五人物颜色

人物	CSS 类	OKLCH 颜色
呆呆酱（真维）	`.speaker-ddj`	`oklch(78% 0.075 82)` 琥珀金
真贞师兄（许涛）	`.speaker-zz`	`oklch(63% 0.06 180)` 暖青
白羊（真正/杨军）	`.speaker-baiyang`	`oklch(66% 0.07 35)` 暖玫
湛然常寂（真湛）	`.speaker-zhan`	`oklch(67% 0.08 130)` 苔绿
宏亮（真恒）	`.speaker-hongliang`	`oklch(62% 0.06 260)` 钢蓝
孟拥	`.speaker-mengyong`	`oklch(63% 0.05 310)` 灰紫

六、文件映射

主公写的 MD	Quartz 输出的 URL	页面类型
`入流亡所策展/策展文本/Day1-...md`	`/入流亡所策展/策展文本/Day1-...`	策展文本
`入流亡所策展/术语库/三摩地.md`	`/入流亡所策展/术语库/三摩地`	术语条目
`入流亡所策展/定题说明.md`	`/入流亡所策展/定题说明`	项目首页
`系统/全链工作流.md`	`/系统/全链工作流`	系统文档

路由规则：文件夹路径 = URL 路径；index.md = 目录索引页。Quartz 自动处理，无需手动配路由。

七、数字策展技能去向

原 research-digital-curation-skills 的 7 层管线：

① topic-framing ② terminology ③ curation-text ④ visual-language ⑤ prototype ⑥ log-method ⑦ workflow

当前状态：

④ visual-language → Hallmark 替代
⑤ prototype → 本 CSS 壳方案替代
⑦ workflow → Obsidian Git + GitHub Actions 替代
①②③⑥ → 降级为 content/系统/curation-skills/ 下的方法论参考文档

不被任何角色主动调用。 主公或伯喈遇到方法论困惑时可查阅，但不作为执行指令。

八、常用命令（伯喈用）

# 构建
cd D:\ai\my-knowledge-base
npx quartz build
 
# 本地预览
npx quartz build --serve
 
# 推送
cd D:\ai\my-knowledge-base
git add .
git commit -m "描述"
git push origin main
 
# 站点
# https://hhaya-xu.github.io/Tree-of-Wisdom/

本文档随项目进展持续更新

九、双速内容管线

简单内容（日常笔记、术语）
  主公写 MD → Obsidian Git 推送 → 壳渲染 → 上线

复杂内容（群聊录、策展文本）
  主公写 MD → Hallmark audit → CSS 调优 → 上线
                    ↑
            （可启动玄策的内容拆解层）
```。最新版本位于 `content/系统/全链工作流.md`。

浏览