技术架构与开发心得

v1.0 (2026-06-03): 全站使用原生技术构建，无 React/Vue/Webpack。

决策：知识库交互模式是"浏览→点击→阅读"，不需要 SPA 的实时协作能力。多页面架构（MPA）更适合内容密集型网站。零 npm 依赖消除版本冲突和供应链攻击风险。

约束：浏览器端 JS 使用 ES5 语法（var+function），确保不依赖转译器也能在所有浏览器运行。

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。

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 异步加载，不阻塞渲染。

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）。

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 打开直观对应三网页。

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 始终基于最新项目状态。

v1.0 (2026-06-03): Git push → Cloudflare Pages 自动构建部署。Output dir = public/。同时预配 Vercel vercel.json 作为备选方案。

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。

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"] 块内联到所有页面确保即时生效。

v1.4 (2026-06-04): 创建 minify.js：sync 时自动压缩所有 JS 文件。先保存字符串和正则字面量→去注释→压缩空白→还原。

决策：不引入 terser/uglify（零 npm 依赖原则）。自定 60 行 minifier 足够处理 ES5 代码。

结果：6 个 JS 文件总体从 1085KB → 779KB（-28%）。

v1.4 (2026-06-04): server.js 响应头：JS/CSS max-age=86400（1天），HTML no-cache，图片 max-age=604800（1周）。

v1.4.1 (2026-06-04): 所有静态资源 URL 加 ?v=1.4.1。版本号变化→浏览器视为新资源→自动重新下载。

决策：选 query string 而非文件名 hash（如 app.a3f2.js）因为文件名 hash 需要构建工具，违反零依赖原则。query string 是纯 HTML 层面的改动，bump-version.js 用正则替换即可。

技术细节：bump-version.js 批量替换所有 HTML 中的 ?v=\d+\.\d+\.\d+ 为新版本号。

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）。

v1.0 (2026-06-03): 文章内容块用 {t: 'type', v: 'value'} JSON 格式存储为 JS 变量。浏览器直接读取无需 fetch/parse。

决策：避免运行时 JSON.parse 开销（1.3MB 数据直接以 JS 变量形式加载）。12 种块类型覆盖段落/标题/代码/公式/表格/图表/柱状图。

内容管道（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 种内容块类型覆盖段落/标题/代码/公式/表格/图表。