Reveriel：一个交互式知识系统的设计

问题：为什么书本不够好

书本三大罪状

• 死的，没有更新，或者更新极慢，以年为单位
• 死的，没有交互，只是单方面的向你传递信息，不需要读者的反馈。
• 单媒体的，只有文字和静态图片，无法充分刺激人的大脑，难以被记忆、理解。

另一方面，一个好的游戏——比如《传送门》或《Baba Is You》——根本不会给你一本规则手册。它给你一个安全的、可以试错的环境，让你通过做来学习。失败没有惩罚，成功有即时的反馈。难度逐步增加，每一个新关卡都建立在上一个关卡学到的技能之上。

这个博客的信仰是：游戏是比死书本更先进的知识载体。 它不是一个”技术博客”——它是一个交互式知识系统，伪装成博客的样子。

总有一天，世界上几乎所有的知识都来自 AI， 而对于人类来说，理解知识会成为最重要的事情。

整体架构：一个目录 + 一个构建脚本

这个框架没有数据库，没有管理后台，没有黑盒。它的全部输入是文件系统上的一个目录，输出是一堆可以用浏览器打开的 HTML 文件。

作者写的（输入）              框架处理的              读者看到的（输出）
─────────────────      ────────────────      ─────────────────

src/content/posts/                             https://reveriel.com/
  shader-intro/                               /posts/shader-intro/
    index.mdx         →  MDX → HTML       →   带有交互组件的页面
    demos/                                    ShaderPlayground 可编辑
      circle.wgsl     →  资源打包         →   WGSL 代码嵌入页面
      sim.py          →  Pyodide 引用     →   读者浏览器里跑 Python

核心原则只有四个：

1. 文件即文章。 一个目录 = 一篇文 = 一个自包含的知识单元。目录名就是 URL。
2. 组件即交互。 需要互动的地方，插入一个组件标签（如 <ShaderPlayground />），而不是写一堆 <script> 标签。
3. 按需加载。 WASM、shader、Pyodide 只在使用时加载。首页的速度和纯文本博客一样快。
4. 对搜索引擎友好。 静态生成 + 语义 HTML + Open Graph 标签 + sitemap，让知识能被发现。

目录结构：每篇文章是一个项目

src/content/posts/
  shader-intro/                  ← 目录名 = 文章 slug = URL
    index.mdx                    ← 正文（唯一必需的文件）
    demos/                       ← 属于这篇文章的交互式 demo 代码
      circle.wgsl                ← ShaderPlayground 引用的 shader
      raymarch.wgsl
      attention-viz.ts           ← Canvas 2D 可视化脚本
      ml-sim.py                  ← Pyodide 跑的 Python
    assets/                      ← 静态资源
      diagram.png
      model.glb                  ← 3D 模型

每篇文章的代码资源和文章放在一起，不是散落在全局的 /static/ 或 /public/ 里。这样你写完一篇文章后，它就是一个完整的、可以独立理解的知识包。

为什么这样设计

传统的 CMS（比如 WordPress）把内容和资源分开：文章在数据库里，图片在一个媒体库，代码片段嵌在 HTML 里。时间长了，它们之间的关系就丢了——你没法把一篇文章的完整上下文（文字 + 代码 + 资源）打包成一个目录复制给别人。

把文章目录当作项目的根意味着：

• Git 可以精确追踪一篇文章的所有修改（包括代码）
• 你可以把一篇文章的目录整个复制给别人，对方就能构建和运行
• 不会有”这张图到底在哪个文章用到了”的问题

内容管线：从 MDX 到交互式页面

数据流是这样的：

index.mdx (你写的)
    │
    ├── YAML frontmatter    →  元数据（title, stage, tags...）
    │
    ├── Markdown 正文       →  Astro MDX 解析器
    │                         →  Shiki 语法高亮
    │                         →  HTML
    │
    └── 组件标签             →  Astro 组件渲染
        <ShaderPlayground />  →  WebGPU 初始化脚本
        <CodeCell />          →  Pyodide / JS 运行时
        <QuizChain />         →  交互式测验逻辑
        <ProofStep />         →  可折叠的 <details>
        <GiscusComments />    →  GitHub Discussions 评论区

构建时（npm run build），Astro 遍历所有 .mdx 文件，提取 frontmatter，渲染 Markdown 为 HTML，把组件标签替换为真实的交互式组件代码，然后输出纯静态文件到 dist/ 目录。

关键点：输出的是静态 HTML + CSS + JS，不需要服务器。 部署到 GitHub Pages、Cloudflare Pages 或任何一个能托管静态文件的地方就行。

组件系统：交互是怎么工作的

这个框架提供了一套交互式组件库。每个组件解决一类特定的教学需求：

下面是一个 Shader Playground。试着改里面 WGSL 代码的最后一行的 0.5，改成 0.0，然后按 Ctrl+Enter。

你刚才改的是一个 fragment shader 的代码。ShaderPlayground 组件在读者的浏览器里做三件事：

1. 请求 WebGPU 设备
2. 把你写的 WGSL 编译为 GPU shader module
3. 渲染一个全屏四边形，把 shader 的结果画到 canvas 上

如果读者的浏览器不支持 WebGPU，组件会显示降级信息。如果读者根本没有滚动到这个组件的位置，它不会初始化——IntersectionObserver 懒加载。

组件一览

一个 CodeCell 的实例——不只是展示代码，读者可以编辑和运行：

点击"运行"以执行代码

什么是 Astro 组件？

你可能会问：ShaderPlayground、CodeCell 这些标签是从哪来的？

它们是 Astro 组件——后缀为 .astro 的文件，存放在 src/components/ 目录下。一个 .astro 文件长这样：

---
// 前半部分（--- 之间）：JavaScript / TypeScript，在构建时运行
interface Props {
  width?: number
  height?: number
}
const { width = 640, height = 360 } = Astro.props
---

<!-- 后半部分：HTML 模板，构建时输出为静态 HTML -->
<div class="interactive-block">
  <canvas id="my-canvas" width={width} height={height}></canvas>
</div>

<script>
  // <script> 标签里的 JS 在读者浏览器里运行
  const canvas = document.getElementById('my-canvas')
  // ... WebGPU 初始化 ...
</script>

关键理解： Astro 组件有两个执行环境——

构建完成后，<script> 之外的模板部分已经变成了纯 HTML 字符串。这也是为什么这个博客不需要服务器——所有的逻辑要么在构建时执行完了，要么在读者浏览器里按需加载。

WASM：在浏览器里跑 Rust

当交互需要的计算量超过 JavaScript 的能力范围时（比如物理模拟、图像处理、数值计算），可以把 Rust 代码编译为 WebAssembly，直接在浏览器里运行。

下面是一个 Mandelbrot 集的 WASM 渲染器。核心计算用 Rust 写，编译为 .wasm 文件，通过 <WasmDemo> 组件加载：

WASM 的构建流程：

# 1. 在文章目录下创建 Rust 项目
src/content/posts/hello-interactive-world/demos/mandelbrot/
  ├── Cargo.toml
  └── src/lib.rs

# 2. 编译
cd demos/mandelbrot
wasm-pack build --target web --out-dir ../pkg

# 3. 在 MDX 中引用产物
<WasmDemo wasm="./demos/pkg/xxx_bg.wasm" js="./demos/pkg/xxx.js" />

WASM 模块也是懒加载的——只有读者滚动到它的位置时才开始下载和初始化。

SEO：让知识被找到

一个博客如果没有人读到，交互做得再好也没有意义。Reveriel 从第一天起就内置了 SEO 基础设施：

每篇文章自动生成：

• <title> 和 <meta description>（从 frontmatter summary 读取）
• Open Graph 标签（og:title, og:description, og:image, og:type: article）—— 决定分享到社交媒体的卡片
• Twitter Card（summary_large_image）—— Twitter / Slack / Telegram 的链接预览
• article:published_time 和 article:tag —— 搜索引擎的结构化时间 + 标签
• 语义 HTML（<article>, <header>, <time>, <nav>）—— 搜索引擎理解页面结构

待规划：

• sitemap.xml — @astrojs/sitemap 自动生成
• RSS Feed — @astrojs/rss 让文章被 RSS 阅读器抓取
• JSON-LD 结构化数据 — Google Rich Results（Article, BreadcrumbList）

评论区：知识需要讨论

每篇文章底部集成了 Giscus——一个基于 GitHub Discussions 的评论系统：

• 读者用 GitHub 账号登录 → 在文章下留言
• 评论数据存在你的 GitHub repo 的 Discussions 里（不依赖第三方数据库）
• 通过 IntersectionObserver 懒加载——不滚动到评论区不加载脚本
• 暗色主题，中文界面

如果没有配置 Giscus，评论区显示提示文字，不影响页面。

递进式难度：Stage 系统

不是所有知识都应该用同样的交互密度呈现。框架定义了 5 个 Stage：

Stage 1 🌱:  90% 阅读 + 10% 演示          （读者刚入门，先看）
Stage 2 🌿:  70% 阅读 + 20% 交互 + 10% 挑战  （开始动手）
Stage 3 🌳:  40% 阅读 + 40% 交互 + 20% 挑战  （动手为主）
Stage 4 ⚡:  20% 阅读 + 50% 交互 + 30% 挑战  （综合运用）
Stage 5 🔥:  10% 方向 + 70% 自由探索 + 20% 创造 （读者自己探索前沿）

脚手架的逐渐撤走是游戏设计的核心原则：

• Stage 1 的文章几乎没有背景要求，交互以”看”为主
• Stage 3 的文章开始组合多个知识点，交互以”做”为主
• Stage 5 的文章给出方向而不是答案——读者应该能自己写一个 path tracer，而不是跟着教程敲

这篇文章本身是 Stage 1。它不需要任何背景知识，交互密度很低——你只需要读。

一个完整的文章是怎么写出来的

假设你要写一篇”Shader 入门：从像素理解 GPU”。你做的事情：

第一步：创建目录

mkdir -p src/content/posts/shader-from-pixels/demos
touch src/content/posts/shader-from-pixels/index.mdx

第二步：写 frontmatter

---
title: "Shader 入门：从像素理解 GPU"
date: 2026-07-30
stage: 1
tags: [graphics, shader]
summary: "每一个像素都是一个独立的小程序。理解这一点是图形学的第一道门。"
---

第三步：写正文 + 嵌入组件

import ShaderPlayground from '@components/ShaderPlayground.astro'

## 像素是并行的

当你在屏幕上看到 1920×1080 个像素时，GPU 并没有一个一个地计算它们的颜色。
每个像素有自己的"微型程序"在同时运行。

<ShaderPlayground shader="./demos/first-pixel.wgsl" editable />

第四步：把 shader 代码放在 demos/ 里

// demos/first-pixel.wgsl
@fragment
fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
  let uv = coord.xy / vec2f(1920.0, 1080.0);
  return vec4f(uv.x, uv.y, 0.5, 1.0);
}

第五步：npm run build → 部署

证明：这个设计是正确的

接下来

以下是网站的路线图：