# 架构图与系统流向：Maplen 是如何运转的

> 从 4N 正交体系到静态优先流水线，用 Mermaid 图表全景解析我为 Maplen 搭建的底层逻辑

- HTML: /nodes/architecture-showcase/
- Markdown: /nodes/architecture-showcase.md
- Section: Nodes / 实践
- Published: 2026.11.01
- Column: Maplen
- Tags: 功能展示

---

export const contentArchitecture = `
flowchart TB
  subgraph 4N["4N 内容分类（单篇文章的主要语气）"]
    direction LR
    N1["Narrative · 纪事<br/>(自我 · 经历 · 成长)"]
    N2["Nebula · 光影<br/>(作品 · 故事 · 感悟)"]
    N3["Notes · 随笔<br/>(观察 · 探究 · 思考)"]
    N4["Nodes · 实践<br/>(技术 · 探索 · 创造)"]
  end

  subgraph Columns["Columns 专栏体系（横向贯穿的探索主线）"]
    direction TB
    C1["专栏 A：Maplen (创造手记)"]
    C2["专栏 B：某项目从构想到落地的完整记录"]
    C3["专栏 C：关于某主题在不同时期的思考演变"]
  end

  C1 -.->|"跨栏目收录"| N4
  C2 -.->|"叙事复盘"| N1
  C2 -.->|"技术实现"| N4
  C2 -.->|"灵感共鸣"| N2
  C3 -.->|"现象观察"| N3
  C3 -.->|"哲学追问"| N3
`;

export const staticPipeline = `
flowchart TD
  subgraph In["一、源文本输入 (Input)"]
    direction LR
    MD[".md 纯文本文章"]
    MDX[".mdx 交互手记"]
    Wiki["Wiki 概念词条"]
  end

  subgraph Pipe["二、静态预编译管线 (Pipeline)"]
    direction TB
    P1["1. Zod Schema 强类型约束"] --> P2["2. Remark 语法树解析 (Wikilinks / 句锚点)"]
    P2 --> P3["3. KaTeX 数学公式静态渲染 (MathML / SVG)"]
    P3 --> P4["4. Shiki 服务端双主题着色 (Diff / 焦点高亮)"]
  end

  subgraph Out["三、全景产出交付 (Output)"]
    direction LR
    O1["纯净 HTML (零首屏 JS)"]
    O2["按需水合 Islands"]
    O3["分级 RSS / Sitemap"]
    O4["llms.txt 知识镜像"]
  end

  In ==>|"提交构建流水线"| Pipe
  Pipe ==>|"生成交付产物"| Out
`;

export const hydrationSequence = `
sequenceDiagram
  autonumber
  actor User as 访客浏览器
  participant CDN as 边缘网络 (Cloudflare Workers)
  participant DOM as 页面 DOM 树
  participant Island as React Island (如物理模拟)

  User->>CDN: 发起页面请求 GET /nodes/architecture-showcase/
  CDN-->>User: 极速返回静态 HTML + CSS
  Note over User,DOM: 页面即刻可读（首屏零 JS 阻塞）
  User->>DOM: 向下滚动，浏览技术手记
  Note over DOM: 遇到带 client:visible 指令的交互组件
  DOM->>Island: 触发 IntersectionObserver，动态拉取组件代码
  Island-->>DOM: 完成水合 (Hydration)，激活交互画布
  DOM-->>User: 用户可流畅拖拽参数滑块与物理振子
`;

export const lifecycle = `
stateDiagram-v2
  [*] --> 灵感发端: 日常观察 / 偶发疑问 / 造物冲动
  灵感发端 --> 初稿写作: 确定表达语气 (4N 之一)
  初稿写作 --> 独立发表: 单篇成文，具备独立可读性
  初稿写作 --> 编入专栏: 与其他文章构成完整探索线索 (Columns)
  编入专栏 --> 交叉引证: 通过 Wikilinks 形成概念网络
  独立发表 --> 持续重构: 随认识加深迭代演进
  交叉引证 --> [*]
`;

在写技术实践手记时，我经常需要表达复杂的系统结构、通信协议和业务流向。

但我非常抗拒在文章里插入大量由外部绘图工具截取的位图图片。那些图片不仅体积沉重，而且无法根据「褐页」与「暖墨」双主题自动调色；更致命的是，图片里的文字无法搜索，一旦架构微调就必须重新截图替换。

因此，我将 [Mermaid](/wiki/mermaid.md) 深度集成到了 [Maplen](/wiki/maplen.md) 的 [Markdown](/wiki/md.md) / [MDX](/wiki/mdx.md) 渲染管线中。所有的流程图、序列图与状态机都直接以文本代码的形式存在，受 Git 统一版本控制，并在构建与主题切换时实时矢量渲染。

这篇手记通过四个直观的架构视图，为你展示 Maplen 整个站点的骨架与运转机理。

---

## 一、4N 与 Columns 的正交内容模型

Maplen 最核心的内容哲学，在于解开文章类别与主题探索之间的死结。

- **4N** 决定单篇文章的**表达语气**：无论是直抒胸臆的经历复盘（Narrative），对光影佳作的触动（Nebula），对复杂问题的理性思辨（Notes），还是亲手构筑代码与电路的实践（Nodes）；
- **Columns（专栏）** 则打破分类的边界，沿着时间、项目或主题的脉络，将散落在不同栏目中的文章串联成一条完整的认知线索。



这种正交设计让写作获得了极大的自由：一个持续半年的硬件项目，可以同时包含架构图解（Nodes）、人机关系随笔（Notes）、科幻电影共鸣（Nebula）和结项纪事（Narrative），它们共同编织成了专栏的骨肉。

---

## 二、静态优先：从源文本到发布产物

Maplen 没有复杂的后端服务、数据库或管理后台。所有文章都保存在项目仓库中，通过 [Astro](/wiki/astro.md) 的 Content Layer 进行强类型校验与预编译。



整个管线遵循清晰的 **输入 · 转换 · 交付** 三栏式分工，设计原则是：**能在构建期完成的事情，绝不留到浏览器去算**。

| 输入层（Input） | 核心转换管线（Pipeline） | 交付物矩阵（Output） |
| :--- | :--- | :--- |
| **[Markdown (.md)](/wiki/md%5C.md)**<br/>承载沉浸长篇叙事 | **Zod Schema 校验**<br/>严格校验 frontmatter 标题、标签、日期约束 | **纯净 HTML 页面**<br/>极速秒开，双主题预载零闪白 |
| **[MDX (.mdx)](/wiki/mdx%5C.md)**<br/>引入局部图表与仿真 | **Remark + Rehype**<br/>[KaTeX](/wiki/katex%5C.md) 公式预渲染、Wiki 双向链接解析 | **按需水合 Islands**<br/>滚动到视口触发微量 React 运行时 |
| **Wiki 概念词条**<br/>数字花园词条定义 | **[Shiki](/wiki/shiki%5C.md) 高亮引擎**<br/>双主题色彩映射、代码 Diff 与焦点行 | **RSS / llms.txt**<br/>面向人类订阅与 AI Agent 的全景分发 |

- 数学公式通过 [KaTeX](/wiki/katex%5C.md) 预渲染为静态 MathML / HTML，彻底消除了客户端 MathJax 闪烁问题；
- 代码块由 [Shiki](/wiki/shiki%5C.md) 在服务端直接完成语法高亮与行号着色，开箱即支持双主题与代码 Diff；
- 生成物除了标准的静态网页，还包括全站与各分栏的 RSS、Sitemap 以及面向现代 AI 工具的 `llms.txt`。

---

## 三、渐进水合：静态首屏与交互岛屿

技术文章有时需要动态实验——比如后面会展示的阻尼振子模拟与交互式函数图像。但我绝不希望为了局部的交互功能，让整站变成一个体积庞大的单页应用（SPA）。

我采用了 [Astro](/wiki/astro.md) 的 **React Islands** 架构，并配置了 `client:visible` 懒加载策略：



首屏加载时，页面纯净得只有骨架 HTML 和样式文件，加载速度以毫秒计。只有当读者真正把页面滚动到交互图表附近时，浏览器才会异步拉取对应的微型 React 运行时与组件代码，完成原地水合。


  Mermaid 渲染引擎本身具有一定体积。在 Maplen 中，Mermaid 脚本只在正文中检测到图表标签时才会动态按需加载，绝不污染无图表文章的加载速度。


---

## 四、生命周期：一篇文章在 Maplen 的演进

文章不是一次性的快餐消费品。在我的设想中，Maplen 里的每一篇文字都像园子里的植物，会随着时间持续生长。



一个灵感可能最初只是 Notes 里的几句片段；随着亲手编码验证，它演变成 Nodes 里的实践手记；当多个相关探索汇聚，便自然升华为一个 Columns 专栏；再通过 `[wikilinks](/wiki/wikilinks.md)` 与其他概念词条相互引证，最终织就一张能够长期生长的知识之网。

---

## 五、在 Markdown 中编写图表

在实际写作中，我只需要在 Markdown/MDX 文件中书写标准的 Mermaid 代码块，或者调用封装好的 `` 组件：

```mdx
export const flow = `
flowchart TB
  A["源文本"] --> B["Astro 构建"]
  B --> C["静态 HTML"]
`;

<Mermaid
  chart={flow}
  caption="图 1：内容管线。"
/>
```

代码即图表，图表即思考。这正是让写作回归纯粹与坚固的技术方式。