看板自动分层管线（Dashboard Tiering Pipeline）建设复盘与操作手册

本文从”首页到底用的哪个 index.md”这个看似琐碎的排查出发，完整记录了从手动硬编码到 JSON 数据驱动、从无限堆叠到限额分层、从单页到首页+归档双页的架构演进全过程。前半段是复盘逻辑，后半段是操作手册。

一、背景与动因

1.1 引子：两个 index.md 的迷局

数字花园网站（notes.zhuzg.com）的最初首页设计，采用的是 D:\个人知识库\网站展示\index.md——一篇名为”Welcome”的知识矩阵入口页，包含 DacAI 专栏、行业研究、基础设施等五个分类的 Wiki 链接列表。

但在某次迭代中，我让 Hermes 将首页替换为看板展示风格。Hermes 的理解与实际意图之间存在偏差：

我的意图：把 网站展示\index.md 的内容重新编辑，替换为看板展示的 HTML 卡片内容
Hermes 的执行：将 网站展示\交互式可视化看板\index.md 直接复制到 Quartz 的 content/index.md

两个 index.md 都保留在源文件夹中。但因为部署到网站上”看起来都是看板卡片”，直观差异不大，没有追究。

这个”误解”暴露了两个深层问题：

源文件与部署文件之间是手动搬运关系——没有统一的”源数据 → 生成”链路，每次更新都可能出现版本错位
每加一个新看板都要手动搬运、手动转换链接格式（./xxx.html → /static/xxx.htm、../xxx/ → ./xxx/）——极易出错且效率低下

1.2 触发事件：发现看板缺少 + 手动维护的崩溃

后续迭代中，我注意到 MLCC 行业研究的 3 个交互式看板没有出现在首页。这意味着每次新增看板都要：

找到 index.md 中卡片列表的位置
手动写一段 20+ 行的 HTML 卡片代码
确保 emoji、颜色、描述、两个链接都正确无误
检查链接是否需要格式转换

这属于典型的硬编码技术债——当下 12 个看板还能忍受，但 Gemini 一天能生成 N 个看板，边际维护成本只会指数级上升。

1.3 方案评估：为什么否决 Gemini 的两种建议

针对”手工维护不可持续”的问题，我向 Gemini 提出了方案征询。Gemini 给出了两条管线升级方案：

方案 A：Quartz 组件级自动化（推荐）

原理：利用 Quartz 4 的 Preact/JSX 自定义组件，遍历带 tags: [dashboard] 的节点，动态生成卡片网格
否决理由：
- 需要掌握 Preact/JSX + Quartz 内部路由 API，学习成本高
- Quartz 升级可能导致组件接口变更，产生新维护负担
- 每张卡片的视觉元素（emoji、描述文案）是感性决定的，程序化生成”各有特色的卡片”比手动写更复杂
- 杀鸡用牛刀

方案 B：CI/CD 预处理管线

原理：在 GitHub Actions 中注入 Python 脚本作为 build 前置钩子，自动扫描目录、提取元数据、覆写 index.md
否决理由：
- 部署流程是”git push → Cloudflare 自动构建”，没有现成 GitHub Actions
- 整套 CI 管线要新搭，额外引入一个运维维度
- 看板数量尚在可控范围，搭 CI 的投入产出比不划算

二、最终架构决策

2.1 技术选型：JSON 数据文件 + 单文件 Python 生成脚本

dashboards.json (数据) → generate_index.py (引擎) → index.md (首页) + 看板归档.md (归档页)

选择理由：

零框架依赖：不碰 Quartz 内核，不搭 CI，单文件 Python 无外部依赖
极低维护成本：脚本总共 ~200 行，逻辑清晰到一眼能懂
可渐进升级：从 v1.0 的”循环输出”到 v2.0 的”分层分流”，改脚本即可，数据文件结构微调兼容
你只改 JSON，我（Hermes）跑脚本——人机分工明确

2.2 v1.0：简单循环输出

第一版脚本只是将 JSON 中的每条数据渲染为统一的 HTML 卡片模板，写入 index.md。功能等价于”用模板替代手写”，解决了链接格式转换和重复劳动问题。

但很快发现一个新问题——首页不可能无限堆叠。

2.3 v2.0：从”全量展示”到”分层架构”

我再次向 Gemini 提出了”无限堆叠导致人设崩塌”的疑问。Gemini 这次给出了一套成熟的信息架构方案，核心思想是：

“首页是核心展厅，不是全量仓库。“

2.3.1 三条铁律

规则	内容	原因
限额制	首页硬性限制 6-8 个卡片	专业纵深的核心展示区，拒绝堆砌
核心锁定	3 个标杆看板永久常驻首页，带 ⭐ 标签	建立极致的专业壁垒与信任锚点
自动归档	超额非核心看板自动降级到归档页	保证首页始终是”精选”，不是”全集”

2.3.2 核心标杆的筛选逻辑

从当时已有的 12 个看板中，筛选出 3 个绝对核心：

看板	入选逻辑	代表什么
📊 存贷双高穿透扫描	绝对专业壁垒。财务造假审计中最经典、穿透难度最高的模型	CFA 基因的数字化顶层设计
🔍 DeepSeek 风险穿透	前沿技术耦合。大模型 + 财务风控的双盲推演	AI + CPA 的应用前沿
🧠 Hermes 记忆映射	物理基建溯源。底层数据流转与分层架构的直观展示	全栈自动化运维实力

排除逻辑： MLCC 系列属于高度垂直的单点行业研究，受众面过于狭窄；MACD 战法 / 哨兵控制台属于量化红海工具，技术门槛相对较低；商誉减值 / 经营贷缺口与”存贷双高”在审计维度存在标签重叠，让渡权重有助于集中兵力。

2.3.3 自动分流机制

读取 dashboards.json
    ↓
分离 core=true / core=false
    ↓
core=true → 锁定首页 (带 ⭐ 核心标签)
    ↓
core=false → 按 date 降序
    ↓
配额 = 8 - core数量
    ↓
取最新的补满 → 首页
    ↓
剩余的 → 归档页 (紧凑表格)
    ↓
首页底部自动生成入口按钮

2.3.4 字段设计

{
  "date": "2026-04-30",     // 📅 发布日期，用于排序
  "is_core": false,          // ⭐ true=锁在首页，false=可被淘汰
  "emoji": "🔬",              // 卡片图标
  "title": "MLCC Broker 实战全景",  // 卡片标题
  "bold_desc": "...",         // 粗体描述（核心能力句）
  "normal_desc": "...",       // 细体描述（补充说明）
  "dashboard": "/static/xxx.htm",  // 看板链接（部署后路径）
  "article": "./xxx/xxx.md"        // 关联原文（Quartz Wiki 链接）
}

三、系统架构详解

3.1 文件职责边界

文件	路径	谁维护	作用
`dashboards.json`	`scripts/dashboards.json`	你 / Hermes	唯一数据源。每条看板一行 JSON
`generate_index.py`	`scripts/generate_index.py`	Hermes	读取 JSON → 渲染首页 + 归档页
`index.md`	`content/index.md`	自动生成	数字花园首页，限额 8 张精选卡片
`看板归档.md`	`content/看板归档.md`	自动生成	全量看板的紧凑表格归档

3.2 数据流图

你从 Gemini 得到新看板 (HTML + .md)
    ↓
Hermes 把 HTML 放入 static/ (改 .htm)
Hermes 把 .md 放入对应 content/ 子目录
Hermes 在 dashboards.json 末尾加一行 (含 date + is_core)
    ↓
python3 scripts/generate_index.py
    ↓
自动：
  ✅ 首页 index.md 重新生成 (限额+核心+最新)
  ✅ 归档页 看板归档.md 刷新 (全量表格)
  ✅ 最旧的非核心自动降级
    ↓
git push
    ↓
Cloudflare Pages 重新构建
    ↓
你 Ctrl+F5 硬刷新查看

四、操作手册

4.1 新增一个看板（标准流程）

步骤 1：准备好两个文件

看板 HTML 文件（Gemini 生成）
关联文章的 .md 文件（如果有）

步骤 2：告诉 Hermes，执行以下操作

Hermes 会依次完成：

① 将 HTML 复制到 /home/zzgsh/quartz/static/，扩展名改为 .htm
② 将 .md 复制到 /home/zzgsh/quartz/content/ 对应子目录
③ 在 dashboards.json 末尾添加一条数据：
   {"date": "2026-05-01", "is_core": false, "emoji": "📡", ...}
   (如果是核心标杆，is_core: true)
④ 运行：cd /home/zzgsh/quartz && python3 scripts/generate_index.py
⑤ 运行：git add ... && git commit -m "♻️ 新增看板：xxx" && git push

步骤 3：你

Ctrl+F5 硬刷新浏览器

4.2 JSON 字段速查

字段	必填	说明	示例
`date`	✅	发布日期，格式 `YYYY-MM-DD`	`"2026-05-01"`
`is_core`	✅	`true`=核心标杆，锁定首页；`false`=常规，可被淘汰	`false`
`emoji`	✅	卡片图标的 emoji 字符	`"🧠"`
`title`	✅	卡片标题	`"Hermes 记忆映射"`
`bold_desc`	✅	粗体描述句（核心能力）	`"冷热数据存储体系的实战演习。"`
`normal_desc`	✅	细体描述句（补充说明）	`"通过交互式界面，复现 Obsidian 到网页端的自动化分层逻辑。"`
`dashboard`	✅	看板部署后的 URL 路径，`/static/xxx.htm`	`"/static/Hermes记忆vs技能：可视化全解指南.htm"`
`article`	✅	关联文章的 Quartz Wiki 链接，`./分类/文件名.md`	`"./基础设施/Hermes 记忆 vs 技能：可视化全解指南.md"`

4.3 链接规则备忘

场景	源文件中的链接	部署后的链接
看板打开按钮	`./xxx.html`	`/static/xxx.htm`
关联原文按钮	`../分类/xxx.md`	`./分类/xxx.md`

⚠️ 注意：中文文件名中的空格会被 Quartz 保留，但文件名中不要使用特殊符号。所有看板 HTML 的扩展名统一为 .htm（不是 .html），因为静态资源是通过文件名直接引用的。

4.4 运行命令速查

# 生成首页 + 归档页
cd /home/zzgsh/quartz
python3 scripts/generate_index.py
 
# 推送上线
git add content/index.md content/看板归档.md scripts/dashboards.json
git commit -m "♻️ 更新看板"
git push
 
# 如果同时改了脚本
git add scripts/generate_index.py

4.5 Hermes 指令模板

下次你要加新看板，只需要说类似这样的话：

“Zack，我在 D:\个人知识库\网站展示\交互式可视化看板\ 下面放了一个新的 [看板名称]，帮我部署到数字花园。这是一个 [核心标杆/常规产出]，发布日期是今天。”

Hermes 收到后会自动完成：文件搬运 → JSON 追加 → 脚本生成 → git push 全流程。

五、扩展与未来

5.1 何时需要重新评估架构

触发条件	动作
看板总数超过 25 个	归档页表格开始变长，考虑改为折叠分类
单个分类文章超过 15 篇	知识矩阵引入 `<details>` 折叠
核心看板超过 5 个	重新审视”核心”的定义标准，收紧筛选
过了 2026 年	知识矩阵按年份切割，首页仅保留当年内容

5.2 仍在白名单上的改进项（未实施）

知识矩阵折叠：当前 5 个分类 ~25 条链接，直接用 <details> 折叠次要分类。但尚未达到”不可读”的临界点，暂不行动
按年份归档：同理，这是”明年才可能遇到的问题”
半自动末位淘汰确认：当前是纯算法驱动，未来可考虑在降级前发一次确认——“xxx 即将从首页降级到归档，同意吗？“

六、总结

从”两个 index.md 的迷局”到”JSON 数据驱动的分层管线”，这条路径的本质是：

从手工操作 → 模板生成 → 数据驱动的分层架构。

三步走，每一步解决一个特定的问题：

阶段	解决的问题	交付物
手动编辑	什么都没有	index.md 手写 150 行 HTML
v1.0 模板化	重复劳动 + 链接错误	JSON + 循环渲染脚本
v2.0 分层	无限堆叠 + 信息架构崩塌	限额制 + 核心锁定 + 自动归档

核心资产圈定（3 个标杆看板）的筛选逻辑——极致的专业壁垒、前沿的技术耦合、稳定的物理底座——本身就是数字花园的定位宣言。它不是技术决策，是品牌定位。

本文写于 2026-05-01 · 基于 Hermes Agent + Quartz 数字花园平台 · 全文由 AI 辅助撰写并经人工逻辑复核

DacAI实验室

探索

看板自动分层管线（Dashboard Tiering Pipeline）建设复盘与操作手册

看板自动分层管线（Dashboard Tiering Pipeline）建设复盘与操作手册

一、背景与动因

1.1 引子：两个 index.md 的迷局

1.2 触发事件：发现看板缺少 + 手动维护的崩溃

1.3 方案评估：为什么否决 Gemini 的两种建议

二、最终架构决策

2.1 技术选型：JSON 数据文件 + 单文件 Python 生成脚本

2.2 v1.0：简单循环输出

2.3 v2.0：从”全量展示”到”分层架构”

2.3.1 三条铁律

2.3.2 核心标杆的筛选逻辑

2.3.3 自动分流机制

2.3.4 字段设计

三、系统架构详解

3.1 文件职责边界

3.2 数据流图

四、操作手册

4.1 新增一个看板（标准流程）

4.2 JSON 字段速查

4.3 链接规则备忘

4.4 运行命令速查

4.5 Hermes 指令模板

五、扩展与未来

5.1 何时需要重新评估架构

5.2 仍在白名单上的改进项（未实施）

六、总结

关系图谱