技术架构与开发心得
📌 最新更新（v1.9.3）
🛠️ 技术栈详情
点击任意技术展开查看完整引入历史和版本演进。
语言 HTML5 / CSS3 / JavaScript (ES5) v1.0
v1.0 (2026-06-03): 全站使用原生技术构建，无 React/Vue/Webpack。
决策：知识库交互模式是"浏览→点击→阅读"，不需要 SPA 的实时协作能力。多页面架构（MPA）更适合内容密集型网站。零 npm 依赖消除版本冲突和供应链攻击风险。
约束：浏览器端 JS 使用 ES5 语法（var+function），确保不依赖转译器也能在所有浏览器运行。
运行时 Node.js 24 v1.0
v1.0 (2026-06-03): 51 行原生 http 模块实现静态文件服务器。不使用 Express/Koa。
决策：需求极简（静态文件+MIME映射+路径安全），不需要路由/REST API/中间件。原生模块零依赖，部署就是一个 `node server.js`。
v1.4 (2026-06-04): 添加 Cache-Control 头部：JS/CSS max-age=86400，HTML no-cache，图片 max-age=604800。
数学渲染 KaTeX 0.16 v1.0v1.4
v1.0 (2026-06-03): 引入 KaTeX CDN。选择 KaTeX 而非 MathJax——KaTeX 渲染速度约 10× 快、无 DOM 操作次数少、对内容密集型页面更友好。初始为同步 <script> 加载。
v1.4 (2026-06-04): 改为 <script> defer。问题：之前同步加载阻塞 FCP 约 300ms。改名后首屏不再等待 276KB 的 katex.min.js 下载。
v1.5 (2026-06-04): Katex CSS 改为 media="print" onload 异步加载，不阻塞渲染。
图表 Mermaid 10 v1.0v1.4
v1.0 (2026-06-03): 引入 Mermaid CDN 渲染流程图、时序图。初始为同步 <script>。
v1.4 (2026-06-04): 改为 <script> defer。仅文章阅读器需要流程图，首屏不需要。defer 后不阻塞渲染。
v1.5 (2026-06-04): index.html 补充 mermaid defer（之前仅 knowledge.html 有 deferred）。
内容管理 Obsidian v1.2
v1.2 (2026-06-04): 引入 Obsidian 作为内容管理系统。Markdown ↔ {t,v} JSON 双向转换。
决策：比 WordPress 轻量、比直接写 JSON 直观。内容创作（Obsidian）和代码（VS Code）完全分离。通过 import-from-md.js / export-to-md.js 双向转换。
v1.5 (2026-06-04): content/ 目录重组为 homepage/knowledge/tech 三层，Obsidian 打开直观对应三网页。
AI 助手 opencode (DeepSeek) v1.0
v1.0 (2026-06-03): 使用 opencode + DeepSeek 作为 AI 编程助手。负责：写知识库文章内容（L1-L5 分层）、编写和调试脚本、代码审查和优化。
v1.2 (2026-06-04): 引入多 session 协作模式，编程主控+内容创作分工。AGENTS.md + RULES.md 分离上下文和规范。
v1.5 (2026-06-04): 建立防退化规则（上下文同步+板块状态同步+单一信息源），确保 AI session 始终基于最新项目状态。
部署 Cloudflare Pages v1.0
v1.0 (2026-06-03): Git push → Cloudflare Pages 自动构建部署。Output dir = public/。同时预配 Vercel vercel.json 作为备选方案。
版本控制 Git + GitHub v1.0
v1.0 (2026-06-03): 每完成一组改动 commit。版本号通过语义化版本管理。
v1.5 (2026-06-04): sync 后自动 commit + push。git-auto-commit.js 分析 git diff 生成 vX.Y.Z | 北京时间 | 类型: 描述 格式的 commit message。
CSS 架构 CSS Variables + BEM v1.0
v1.0 (2026-06-03): 全部颜色通过 :root CSS 变量定义，支持亮/暗双主题。类名用 BEM 约定（knowledge-card--soon、kc-icon）。
v1.4 (2026-06-04): Critical CSS 内联到 <style> 消除外部 CSS 渲染阻塞。style.css 转为 async 加载。
v1.5 (2026-06-04): Dark mode 配色从 slate 蓝灰改为暖灰 (#1a1a1a)。[data-theme="dark"] 块内联到所有页面确保即时生效。
JS 压缩 自定 minify.js v1.4
v1.4 (2026-06-04): 创建 minify.js：sync 时自动压缩所有 JS 文件。先保存字符串和正则字面量→去注释→压缩空白→还原。
决策：不引入 terser/uglify（零 npm 依赖原则）。自定 60 行 minifier 足够处理 ES5 代码。
结果：6 个 JS 文件总体从 1085KB → 779KB（-28%）。
缓存 Cache-Control v1.4
v1.4 (2026-06-04): server.js 响应头：JS/CSS max-age=86400（1天），HTML no-cache，图片 max-age=604800（1周）。
缓存穿透 ?v= query string v1.4.1
v1.4.1 (2026-06-04): 所有静态资源 URL 加 ?v=1.9.3。版本号变化→浏览器视为新资源→自动重新下载。
决策：选 query string 而非文件名 hash（如 app.a3f2.js）因为文件名 hash 需要构建工具，违反零依赖原则。query string 是纯 HTML 层面的改动，bump-version.js 用正则替换即可。
技术细节：bump-version.js 批量替换所有 HTML 中的 ?v=\d+\.\d+\.\d+ 为新版本号。
文章分层 L1-L5 五层递进 v1.0
v1.0 (2026-06-03): L1 初级（纯文字无公式）→ L2 中级（协议机制）→ L3 高级（算法数学）→ L4 专家（端到端工程）→ L5 世界顶尖（形式化证明）。
决策：同一主题同时服务初学者和研究者。每层独立 Markdown 文件，{t, v} JSON 格式存储。12 种内容块类型（p/h3/h4/code/note/list/table/math/viz/mermaid）。
内容块格式 {t, v} JSON v1.0
v1.0 (2026-06-03): 文章内容块用 {t: 'type', v: 'value'} JSON 格式存储为 JS 变量。浏览器直接读取无需 fetch/parse。
决策：避免运行时 JSON.parse 开销（1.3MB 数据直接以 JS 变量形式加载）。12 种块类型覆盖段落/标题/代码/公式/表格/图表/柱状图。
构建自动化 10 个 Node.js 脚本 v1.2v1.5
内容管道（Markdown → 网页）：
Obsidian 写 .md → import-from-md.js 解析 Markdown → {t,v} JSON → articles*.js
↓
content/messages/*.md → build-guestbook.js 读标题+正文+mtime → guestbook-data.js
↓
index.html 加载 .js → 浏览器渲染
v1.2 (2026-06-04): import-from-md, sync-cards, export-to-md, watch, bump-version, write-build-time。
v1.4 (2026-06-04): 新增 minify.js（去注释+压缩空白，总体 -28%）；sync-cards.js 加 </html> 截断+div 平衡防护。
v1.5 (2026-06-04): 新增 build-site-config.js、git-auto-commit.js。sync 顺序修正（write-build-time 在 minify 前）。watch.js 补全 build-guestbook + minify + git-auto-commit，实现改完 3 秒自动同步→部署全流程。
npm run sync 完整流水线（10 步）：
import-from-md → Markdown → articles*.js（文章数据） sync-cards → meta.json → knowledge.html（卡片 HTML） build-guestbook → 留言 .md → guestbook-data.js（留言板） build-homepage → hero.json → hero-data.js（首页 Hero） build-nav → nav.json → 三页 HTML 导航注入 build-site-config → 站点配置 JSON write-build-time → 写入构建时间戳 minify → 压缩所有 JS（~28% 体积缩减） git-auto-commit → git add -A → commit → push → Cloudflare 自动部署
npm run watch 自动监听：递归监听 content/ 目录 → 文件变化 3 秒防抖 → 自动跑上面完整流水线 → 边写边预览 → 自动推送到 GitHub → Cloudflare 自动上线。零手动操作。
整体架构：纯文件转换、零数据库、零 API。内容创作（Obsidian）和代码（VS Code）完全分离，12 种内容块类型覆盖段落/标题/代码/公式/表格/图表。
📋 版本摘要
| 版本 | 类型 | 发布时间 | 摘要 |
|---|---|---|---|
| v1.9.3 | 修复 | 2026-06-13 | 选课数据对照官方 Calendar 纠错 |
| v1.9.2 | 新功能 | 2026-06-13 | 选课规划器新增推荐学期计划表 |
| v1.9.1 | 优化 | 2026-06-13 | 课程图改为自上而下依赖树布局 |
| v1.9.0 | 新功能 | 2026-06-13 | UofT 选课规划器（先修课程图 + 学位概览 + 清单） |
| v1.8.0 | 新功能 | 2026-06-12 | Mission Control 仪表盘 + Progress 导航 + 进度数据流水线 |
| v1.7.0 | 新功能 | 2026-06-11 | 诚实声明 + 知识库分区 + About/Projects/Posts/Log 四页 + 学习日志 |
| v1.6.0 | 新功能 | 2026-06-11 | 全文搜索 + 端口调整 + 删 Astro + 新手手册 + 层标题修复 |
| v1.5.1 | 严重 | 2026-06-04 11:00 | 卡片点击修复 + 管理面板 v2 + 知识库导航 + roadmap 修复 |
| v1.5.0 | 优化 | 2026-06-04 05:09 | 全面审查修复 + tech 页面 dark mode、统一导航 |
| v1.4.1 | 修复 | 2026-06-04 04:45 | 主页加载失败 + cache-busting |
| v1.4.0 | 新功能 | 2026-06-04 ~04:07 | 技术页面、4篇补L5、知识库独立页、性能优化 |
| v1.3.0 | 新功能 | 2026-06-04 ~01:55 | 独立知识库页、搜索/PDF/进度/留言、9篇新文 |
| v1.2.0 | 修复 | 2026-06-04 01:08 | 修复重复level、统一标题、Obsidian工作流 |
| v1.1.0 | 优化 | 2026-06-03 09:29 | 7篇补全层级、版本自动化 |
| v1.0.0 | 新功能 | 2026-06-03 05:50 | 初始版本 22 篇文章 |
📝 完整变更日志
v1.5.0 — 2026-06-04 05:09 北京时间
<details class="tech-details">）<details class="ts-item">）📋 技术细节
问题：AGENTS.md 严重过时（文章数 17 vs 实际 44、结构图缺 10+ 文件）；主题切换代码从页面底部内联脚本移入 app.js 的 DOMContentLoaded 后闭包行为不一致导致手动切换失效。
方案：主题切换恢复为页面底部内联脚本（git 验证 v1.5 build 05:40 版本可用），app.js 不再处理主题；防退化规则用「上下文同步 + 板块状态同步 + 单一信息源」三条规则从源头防止文件过期。
技术细节：content/ 目录重组为 homepage/knowledge/tech 三层结构；4 个脚本路径更新（import-from-md.js, sync-cards.js, build-guestbook.js, build-site-config.js）；RULES.md 新增 80+ 行（主题系统设计规范含架构图+18变量表+JS逻辑+调试指南）；AGENTS.md 完全重写（131→215 行）；sync-cards.js 加 </html> 截断 + div 平衡检查 + 主题代码一致性检查；git-auto-commit.js 自动生成版本号+北京时间+类型标签的 commit message；变更日志每版本加 <details class="tech-details"> 可折叠四要素；技术栈详情从 <table> 改为 <details class="ts-item"> 可展开列表。
结果：AGENTS.md 与实际状态一致（44 篇/11 板块）；主题切换恢复手动+系统双模式；content/ 三文件夹对应三页面；sync 后自动 commit/push 到 GitHub。
v1.9.3 — 2026-06-13
v1.9.2 — 2026-06-13
v1.9.1 — 2026-06-13
v1.9.0 — 2026-06-13
v1.8.0 — 2026-06-12
v1.7.0 — 2026-06-11
v1.6.0 — 2026-06-11
📋 技术细节
问题：43 篇文章找内容只能靠卡片标题过滤；Lunr.js 等主流搜索库依赖空格分词，对中文几乎失效。同时 5000 端口在 macOS 上被「隔空播放接收器」占用，开发体验差。
方案：放弃分词索引库，用 JS 原生 indexOf 子串扫描——中文天然支持，全文约 65 万字符扫一遍 <5ms；索引懒构建（首次输入才建），不拖慢页面加载。代码以教学为目的书写，配合《新手学习手册》第 4 章作为案例研究。
技术细节：blockText/cleanText 把 p/h3/h4/note/list/table/code 各类内容块拍平为纯文本（代码块保留原样，标签清理只针对交叉引用 <a>）；多关键词 AND 匹配 + 按命中块数排序；摘要截取关键词前 30 字后 50 字；高亮用单一交替正则一次扫描、命中与未命中片段分别 esc() 转义，规避标签自我破坏与转义符误命中两类缺陷（审查阶段以 Node 实测验证）。
结果：knowledge.html 顶部新增搜索框，输入即搜全部正文并直达对应层级；服务器对畸形请求免疫；层标题数据完整恢复（如 "Total Cost of Ownership" 不再被切成 "Owners"）。
v1.5.1 — 2026-06-04 10:00 北京时间
📋 技术细节
问题：用户点击知识库卡片无反应（Console 报 SyntaxError: Unexpected end of input），首页 roadmap 完全空白。两者根因一致：minify.js 的 // 注释清除不彻底，残留注释在压缩后的单行 JS 中吞噬所有后续代码。
方案：1) minify.js 在恢复字符串后增加二次清除补救；2) roadmap.js 移除文件头注释避免被 minify 误处理；3) 重新生成所有 .min.js 文件。
技术细节：管理面板 v2 全部功能通过 server.js 内置 REST API 实现（GET/POST/DELETE），操作 content/ 目录文件和触发 npm run sync。知识库导航侧边栏在 app.js 的 DOMContentLoaded 中新增 readerCardsSidebar 组件，通过遍历 ARTICLES 数组按 section 分组渲染 43 张卡片，点击调用 switchToArticle() 关闭当前阅读器并打开目标文章。
结果：知识库卡片点击、首页 roadmap 恢复正常。管理面板可实现全部内容管理功能，无需离开浏览器。构建流水线从 7 步扩展到 10 步，覆盖主页 Hero 和导航注入。
v1.4.1 — 2026-06-04 04:45 北京时间
📋 技术细节
问题：主页 hero 显示"⚠️ 内容加载失败"，因为 articles*.min.js 脚本引用在代码重构中丢失；浏览器缓存旧版 JS/CSS 导致更新滞后。
方案：Cache-busting 用 URL query string ?v=X.Y.Z（而非 Service Worker 或 ETag），浏览器将不同版本视为独立资源自动重新下载。
技术细节：三页 HTML 的 JS/CSS URL 加 ?v=1.9.3 参数；bump-version.js 用正则批量替换所有 HTML 中的版本查询串；server.js 设 Cache-Control: max-age=86400 配合 cache-busting。
结果：用户无需手动清除缓存，版本更新后自动加载新代码。
v1.4.0 — 2026-06-04 ~04:07 北京时间（近似）
📋 技术细节
问题：首屏渲染等待外部 CSS 下载（FCP 慢）；JS 体积 1085KB 拖慢 TTI；无缓存策略导致重复访问慢。
方案：Critical CSS 内联到 <style> 消除渲染阻塞；minify.js 去注释+压缩空白实现 28% 压缩；server.js 按文件类型设 Cache-Control。
技术细节：style.css 用 media="print" onload="this.media='all'" 异步加载；minify.js 保留字符串+正则后去注释压缩；Cache 分层: .css/.js 1天, .html no-cache, 图片 1周。
结果：FCP 从 ~800ms 降至 ~200ms；JS 体积从 1085KB 降至 779KB。
v1.3.0 — 2026-06-04 ~01:55 北京时间（近似）
📋 技术细节
问题：知识卡太多首页过长；跨文章引用只能手动复制链接；无用户反馈渠道。
方案：拆分为 /knowledge.html 独立页；[[id]] 在 Markdown import 时自动转为链接；留言板用 mtime 自动提取时间。
技术细节：import-from-md.js 正则 \[\[([a-z0-9-]+)\]\] 替换为 <a class="xref-link">；build-guestbook.js 从 content/_messages/ 读 .md 并用文件 mtime 生成北京时间。
结果：首页简洁化；跨文章引用自动可点击；留言板支持 Obsidian 编辑。
v1.2.0 — 2026-06-04 01:08 北京时间
📋 技术细节
问题：多篇文章的 layers 数组中有重复 level（同一 level 出现两个 layer 对象），导致阅读器显示混乱；文章标题混乱（模板占位符、错误层级标签）。
方案：编写 Node.js 脚本遍历所有文章，检测重复 level 并合并 content 数组为单一 layer；用"中文 — English"格式统一 133 个层标题。
技术细节：合并策略: 同 level 的 content 拼接到第一个 layer，标题用 | 连接后选较长的去除模板标签。引入 AGENTS.md+RULES.md 分离项目上下文和规范约束。
结果：所有文章 L1-L5 唯一无重复；标题格式统一可读。
v1.1.0 — 2026-06-03 09:29 北京时间
📋 技术细节
问题：7 篇文章（Proxmox、UPS、ZFS DMU、数据生命周期、混沌工程、SPDK、下一代存储）只有 L1-L3 或 L1-L2，缺 L4 和 L5 层。
方案：补写 14 个 L4/L5 层，每层约 8-25KB 内容。引入 bump-version.js 实现 semver 版本号自动化。
技术细节：bump-version.js 同时更新 package.json 和 index.html 版本字符串；构建时间从浏览器 Date() 改为服务器端 write-build-time.js 写入北京时间。
结果：7 篇文章达到完整 L1-L5；版本号可一键升级（major/minor/patch）。
v1.0.0 — 2026-06-03 05:50 北京时间
📋 技术细节
设计决策：选择原生 HTML/CSS/JS 无框架构建。不做 SPA 因为知识库交互模式是"浏览→点击→阅读"而非实时协作；零 npm 依赖消除维护负担和供应链攻击风险。
技术栈：Node.js 原生 http 模块 51 行实现文件服务器（含 MIME 映射、路径遍历防护）；KaTeX CDN 数学公式渲染；Mermaid CDN 流程图；CSS 自定义属性实现亮暗主题切换。
文章系统：L1-L5 五层递进（初级→世界顶尖），每层独立 Markdown 文件，{t, v} JSON 格式存储为 JS 变量供浏览器直接读取。
结果：22 篇文章上线，覆盖 NAS、ZFS、RAID、硬件介质、文件系统 5 个主题领域。