# 使用指南

每个 Demo 展示 Rust 编译到 WebAssembly 在浏览器中的不同应用场景。

## 快速开始

```bash
python3 scripts/build.py        # 构建全部演示的 WASM
python3 scripts/serve.py 8080   # 启动本地服务器（禁用缓存，重新构建后刷新即生效）
# 浏览器打开 http://localhost:8080/www/
```

首次使用需要先安装 Rust、wasm32 target 和 wasm-pack。完整步骤和常见问题（镜像 404、`wasm-pack` 卡住等）见 [docs/INSTALL.md](docs/INSTALL.md)。

---

## 🌀 曼德博集合（Mandelbrot）

2D 分形交互浏览器，WASM 计算每个像素。

| 操作 | 效果 |
|------|------|
| 🖱️ 滚轮 / 👆 双指缩放 | 缩放（自动增加迭代深度） |
| 🖱️ 拖拽 / 👆 单指拖动 | 平移视野 |
| 🖱️ 点击 / 👆 轻点 | 以该位置为中心 |
| ↺ 重置 | 恢复初始视角 |

---

## 📊 大数据表格（Data Table）

WASM 管理 10 万行数据，虚拟滚动只渲染可见行。

| 操作 | 效果 |
|------|------|
| 点击列头 | 排序（再次点击切换升序/降序） |
| 搜索框 | 全文搜索（150ms 防抖） |
| 滚动 / 手指滑动 | 虚拟滚动，按需获取可见行 |
| 行数下拉框 + 生成 | 重新生成数据 |

---

## 🎨 图像滤镜（Image Filter）

加载本地图片，WASM 逐像素应用滤镜，图片不会上传。

| 操作 | 效果 |
|------|------|
| 点击选择 / 拖入图片 | 加载 |
| 滤镜按钮 | 灰度 / 反色 / 模糊 / 边缘检测 / 浮雕 |

---

## 🔲 生命游戏（Game of Life）

康威生命游戏，260×180 个细胞由 WASM 计算。

| 操作 | 效果 |
|------|------|
| ▶ 播放 / ⏸ 暂停 | 自动演化 |
| 单步 | 手动前进一代 |
| 随机 / 清空 | 重新随机撒点 / 清空网格 |
| 🖱️ 点击拖拽 / 👆 手指拖动 | 绘制活细胞 |
| 空格键 | 切换播放/暂停 |
| 速度滑块 | 1-20 级速度 |

---

## 🌌 粒子物理（Particles）

N 体引力模拟，300 个粒子在 CPU 上由 WASM 计算。

| 操作 | 效果 |
|------|------|
| 引力滑块 | 引力常数 100-3000 |
| 阻尼滑块 | 速度衰减 |
| 重置 / +100 | 重新随机生成 / 中心添加粒子 |
| 🖱️ 点击 / 👆 轻点 | 在该位置添加粒子团 |

---

## 🌐 3D 曼德博球（Mandelbulb）

8 次幂分形的 3D 球体追踪，Rust 在 CPU 上光线步进，WebGL 负责显示。

| 操作 | 效果 |
|------|------|
| 🖱️ 拖拽 / 👆 单指拖动 | 旋转视角 |
| 🖱️ 滚轮 / 👆 双指缩放 | 缩放 |
| ↺ 重置 | 恢复初始视角 |

**技巧**：拖动或缩放时先用 200×200 的半分辨率预览，停下约 0.2 秒后再补一帧 400×400 的完整画面。底部显示每帧耗时和当前缩放倍数。

---

## 📹 实时视频滤镜（Video Filter）

WebRTC 摄像头 → Rust WASM 逐帧滤镜 → Canvas 显示。

| 操作 | 效果 |
|------|------|
| ▶ 开启摄像头 / ⏹ 停止 | 请求摄像头权限并开始 / 停止 |
| 滤镜按钮 | 切换 5 种实时滤镜 |

**技巧**：与图像滤镜用的是同一段 Rust 代码，只是输入从静态图片变成视频流。摄像头需要安全上下文：`localhost` 可以直接用，手机通过局域网 IP 访问需要 HTTPS。

---

## ⚡ WebGPU N 体模拟（N-body）

默认 5,000 个粒子（可调到 20,000）在 GPU 上做 N 体计算，WGSL 计算着色器。Rust 只生成初始数据。

| 操作 | 效果 |
|------|------|
| 引力滑块 | 引力常数 |
| 数量滑块 | 粒子数 1000-20000 |
| 重置 / +500 | 重新随机生成 / 中心添加粒子 |
| 🖱️ 点击 / 👆 轻点 | 在该位置添加粒子团 |

**技巧**：和粒子物理（CPU 300 个粒子）对比同一种算法在 CPU 和 GPU 上的规模差距。需要桌面 Chrome / Edge 113+、安卓 Chrome 121+ 或 iOS / iPadOS Safari 26+；不可用时页面会列出检测失败的原因。

---

## ⚖️ JS vs WASM 性能对比（Benchmark）

同一个算法用 JS 和 Rust 各写一遍，现场跑分对比，并校验两边结果完全一致。

| 操作 | 效果 |
|------|------|
| 规模下拉框 | 小 / 中 / 大三档数据量 |
| ▶ 运行全部 | 依次运行素数筛、递归斐波那契、排序、矩阵乘法 |
| 点击结果列的 ✓ | 展开查看两边算出的具体数值 |

**技巧**：差距通常在 2 倍以内，说明现代 JS 引擎的 JIT 已经很强；多换几种规模观察加速比的变化。

---

## 🚀 SIMD 加速对比（WebAssembly SIMD）

同一个算法写成普通标量版和 128 位 SIMD 版，现场跑分并核对两边结果。

| 操作 | 效果 |
|------|------|
| 规模下拉框 | 小 / 中 / 大三档数据量 |
| ▶ 运行全部 | 依次运行向量点积、图像叠加、曼德博集合 |
| 点击结果列 | 展开查看两边算出的具体数值 |

**技巧**：图像叠加（16 个字节一条指令）加速最明显；曼德博集合要等 4 个像素里最慢的那个，加速最少。需要 Chrome 91+、Firefox 89+ 或 Safari 16.4+。

---

## 🔺 三角剖分（Delaunay / Voronoi）

Bowyer-Watson 增量三角剖分和它的对偶 Voronoi 图，还能把图片变成低多边形。

| 操作 | 效果 |
|------|------|
| 🖱️ 点击 / 👆 轻点 | 加一个点 |
| 🖱️ 悬停 | 显示所在三角形的外接圆（圆里没有其他点） |
| 🎲 随机 100 点 / 清空 | |
| 显示 | Delaunay 三角形 / Voronoi 图 |
| 模式：图片转低多边形 | 按边缘强度撒点，三角形填平均色；可调点数、边缘权重，可上传图片 |

---

## 🔢 数独求解（Dancing Links）

把数独变成精确覆盖问题，用舞蹈链求解，并和朴素回溯比较搜索量。

| 操作 | 效果 |
|------|------|
| 题目 | 入门、中等、「世界最难」、AI Escargot、反暴力、多解、空盘 |
| ▶ 求解 | 用所选算法求解，显示是否唯一解、搜索节点数和耗时 |
| 🎬 动画演示 | 回放搜索过程（蓝色是正在尝试的格子，消失就是回溯） |
| ⚖️ 两种算法对比 | 同时运行两种算法，列出节点数和耗时 |
| 点格子 + 键盘 / 数字面板 | 自己出题（方向键移动，⌫ 删除） |

**技巧**：选「反暴力」对比一下：舞蹈链几十步，朴素回溯约 7000 万步。

---

## 🗺️ A* 迷宫寻路（Pathfinding）

递归回溯生成迷宫，A* 或 Dijkstra 逐步搜索最短路径。

| 操作 | 效果 |
|------|------|
| 算法下拉框 | A*（曼哈顿距离）/ Dijkstra |
| 速度滑块 | 每帧扩展 1 ~ 512 个格子 |
| ▶ 开始寻路 / 🔀 新迷宫 | 搜索 / 重新生成迷宫 |
| 点击 / 轻点画布 | 按所选模式切换墙壁、设置起点或终点 |

**技巧**：拆掉几堵墙让地图变开阔，再比较两种算法「已扩展」的格子数。

---

## 🌊 流体模拟（Stable Fluids）

Jos Stam 的 Stable Fluids 算法实时求解不可压缩流体方程。

| 操作 | 效果 |
|------|------|
| 🖱️ 拖拽 / 👆 手指拖动 | 搅动流体并注入染料 |
| 分辨率 | 64 / 128 / 192 网格（手机默认 64） |
| 粘度 / 消散 | 流体黏稠度 / 染料褪色速度 |
| 自动喷射 | 底部两个喷口持续注入 |

---

## 🎵 音频频谱（FFT）

手写快速傅里叶变换，实时显示波形、频谱和时频图。

| 操作 | 效果 |
|------|------|
| 音源 | 合成和弦 / 扫频信号（静音，无需权限）/ 麦克风 |
| FFT 长度 | 1024 / 2048 / 4096 点 |

**技巧**：选麦克风后吹口哨，顶部会显示峰值频率和对应音名。

---

## 🎹 音频合成器（Synthesizer）

8 复音减法合成器，Rust 编译的 `.wasm` 在 AudioWorklet 音频线程里实时发声。

| 操作 | 效果 |
|------|------|
| 🔊 启动音频 | 浏览器要求先点击一下才能出声 |
| 👆 按琴键（可多指、可滑动） | 发声；电脑键盘 `A`~`;` 是白键，`W E T Y U O P` 是黑键 |
| 波形 | 正弦 / 锯齿 / 方波 / 三角波 |
| 截止频率 / 共振 | 低通滤波器，调低截止频率声音变闷，调高共振出现「哇」声 |
| A / D / S / R | 起音、衰减、延音、释音包络 |
| ▶ 示例旋律 | 自动弹一段旋律 |

**技巧**：需要安全上下文，`localhost` 可以直接用，手机通过局域网 IP 访问需要 HTTPS；iPhone 静音开关打开时没有声音。

---

## ✂️ 智能缩放（Seam Carving）

动态规划找出最不重要的像素缝，缩放图片时主体不变形。

| 操作 | 效果 |
|------|------|
| 尺寸滑块 | 目标宽度（或高度），小于原图删缝，大于原图插缝 |
| 方向 | 改变宽度 / 改变高度 |
| 显示 | 结果 / 缝的位置 / 能量图 / 标记区域 |
| 🟩 保护 / 🟥 删除 / 橡皮 | 在「标记区域」里涂抹；涂红后自动缩到正好删掉红色区域 |
| 图片 | 示例或上传（大图先缩到 640×480 以内） |

**技巧**：把帆船涂红，它会从画面里消失；下方是普通缩放的对比。

---

## 🖼️ JPEG 编码器（JPEG Encoder）

手写的 baseline JPEG 编码器，看 DCT、量化和 Huffman 编码如何换来更小的文件。

| 操作 | 效果 |
|------|------|
| 质量 | 1~100，显示文件大小、压缩倍数和 PSNR |
| 色度采样 | 4:2:0（色度减半）/ 4:4:4 |
| 🖱️ 点击 / 👆 轻点图片 | 显示 4 倍放大，以及那个 8×8 块的像素 → DCT → 量化 → 还原 |
| ⬇ 下载 .jpg | 保存生成的文件（任何看图软件都能打开） |

**技巧**：质量调到 10 左右看块状和振铃；蓝底红字最能看出 4:2:0 的颜色渗出。

---

## 🔐 文件哈希（SHA-256）

手写 SHA-256，文件只在本地计算，不会上传。

| 操作 | 效果 |
|------|------|
| 文本框 | 输入时实时计算哈希 |
| 拖入 / 点击选择文件 | 4 MB 分块流式计算，显示进度 |
| 生成并计算 | 用 16 / 64 / 256 MB 测试数据跑一遍（手机上不提供 256 MB） |

**技巧**：结果会和浏览器内置的 Web Crypto 交叉验证，并对比两者速度。

---

## 📝 Markdown 渲染

手写的 Markdown 解析器，边输入边转成 HTML，代码块带语法高亮。

| 操作 | 效果 |
|------|------|
| 左侧输入 | 右侧实时预览 |
| 📄 示例文档 / 🛡️ XSS 测试 | 载入所有语法的示例 / 一组常见的攻击写法（都会被转义或改成无害链接） |
| ⏱ 测速 | 渲染约 1 MB 的文档 |
| 右侧显示 | 渲染结果 / HTML 源码 |

---

## 🔌 MCP 调试台（MCP Console）

浏览器里的 MCP 客户端（Rust 编译成 WASM），经本地桥接服务连接你的 MCP 服务端和命令行工具。**这是唯一需要本地服务的示例。**

启动：

```bash
cp mcp.config.example.json mcp.config.json    # 加入自己的服务端和工具（该文件不入库）
python3 scripts/serve.py 8080 --mcp mcp.config.json
# 在本机打开 http://localhost:8080/www/mcp/
```

自带四个功能相同的示例服务端：「示例服务端（stdio）」是 Python 写的（`scripts/mcp_demo_server.py`），直接可用；「示例服务端（Rust）」「（Go）」「（Zig）」分别在 `crates/tools/mcp/examples/demo_server.rs`、`examples/mcp-servers/go/`、`examples/mcp-servers/zig/`，要先编译一次（命令见 `docs/INSTALL.md` §3.2）。

| 操作 | 效果 |
|------|------|
| 点一个服务端 | 握手并列出工具、资源、提示词；显示协商的协议版本和服务端能力 |
| 工具 | 按 inputSchema 生成表单，参数不合法时逐项提示；结果显示文字、图片、资源和 structuredContent |
| 资源 / 提示词 | 读取资源、按模板填参数；填写参数获取提示词消息 |
| 原始报文 | 所有发出、收到和推送的 JSON-RPC 消息，可过滤；可以手写一条消息直接发送 |
| 重启 | 重启服务端进程（或重置 HTTP 会话） |

配置文件支持三种服务端：`command`（stdio 子进程，可设 `cwd`、`env`、`timeout_s`）、`url`（Streamable HTTP，可设 `headers`）、`cli`（一组命令行工具，每个有 `command` 模板、`input_schema`、可选 `stdin` 和 `timeout_s`）。模板里单独占一个元素的 `{占位符}` 如果收到以 `-` 开头的字符串，默认拒绝（防止被程序当成选项），可以给工具加 `"allow_option_values": true` 放开，或在位置参数前放一个 `"--"`；程序本身（模板第一个元素）不能是占位符。

配置里还可以加一个 `shell`（受限 shell）服务端：页面上输入一行命令，程序必须在白名单里，并且每条命令都要在运行 serve.py 的终端里输入 `y` 确认才会执行（详见 `docs/INSTALL.md` §3.2）。

**安全**：桥接服务只接受本机通过 localhost 打开本页后发出的请求（令牌放在 Cookie 里），浏览器只能调用配置文件里登记的程序，命令行工具和受限 shell 都不经过 shell 执行。

---

## 🏔️ 噪声地形生成（Perlin Noise）

Perlin 噪声叠加多个八度，实时生成无限大的地图。

| 操作 | 效果 |
|------|------|
| 🖱️ 拖拽 / 👆 手指拖动 | 平移地图（无边界，拖动时先显示半分辨率预览） |
| 缩放 / 八度 / 粗糙度 / 海平面 | 调整地形尺度、细节层数、起伏程度和水位 |
| 🎲 随机种子 | 生成新世界 |

**技巧**：把八度调到 1 再逐级增加，观察细节如何一层层叠加。

---

## 🧊 3D 软件光栅化（Software Rasterizer）

不用 WebGL，由 Rust 在 CPU 上完成顶点变换、背面剔除、光栅化、深度测试和着色。

| 操作 | 效果 |
|------|------|
| 🖱️ 拖拽 / 👆 单指拖动 | 旋转模型 |
| 🖱️ 滚轮 / 👆 双指缩放 | 缩放 |
| 模型 | 立方体 / 球体 / 圆环 / 三叶结 |
| 着色 | 平面着色 / Phong 着色 / 线框 / 深度缓冲 |
| ⏸ 停止旋转 / ↺ 重置 | 暂停自动旋转 / 恢复初始视角 |

**技巧**：切到「线框」看三角形，切到「深度缓冲」直接看 z-buffer（越近越亮）；底部统计显示被剔除的背面三角形数量。

---

## 💡 光线追踪（Path Tracing）

蒙特卡洛路径追踪：反射、折射、柔和阴影、墙面颜色互相「渗透」，采样越多越清晰。

| 操作 | 效果 |
|------|------|
| 🖱️ 拖拽 / 👆 单指拖动 | 转动视角（房间里原地转向，天空场景绕球旋转） |
| 🖱️ 滚轮 / 👆 双指缩放 | 前进 / 后退 |
| 场景 | 康奈尔盒子 / 天空下的球 |
| 分辨率 | 320×240 / 480×360 / 640×480 |
| 线程 | 单线程，或多线程（需要跨源隔离的页面和 `pathtracer-mt` 构建，不可用时会注明原因） |
| ⏸ 暂停 / ↺ 重置视角 | 暂停累积 / 恢复初始视角 |

**技巧**：视角一变就重新累积，停下来看噪点逐渐消失；累积到 2048 采样后自动停止。多线程版的构建方法见 [docs/INSTALL.md](docs/INSTALL.md)。

---

## 🔲 二维码生成（QR Code）

手写的二维码编码器：数据编码、Reed-Solomon 纠错、8 种掩码按惩罚分择优。

| 操作 | 效果 |
|------|------|
| 内容文本框 | 输入时实时生成 |
| 纠错等级 | L / M / Q / H（约 7% ~ 30% 可恢复） |
| 掩码 | 自动（惩罚分最低）或手动指定 0~7 |
| ⬇ 下载 PNG | 保存二维码图片 |

**技巧**：下方列出 8 种掩码的惩罚分；手动换一个掩码，看图案如何变化。

---

## 🗜️ 数据压缩（DEFLATE）

手写 DEFLATE（RFC 1951）压缩与解压，与浏览器内置的 `CompressionStream` 互相解压校验。

| 操作 | 效果 |
|------|------|
| 示例按钮 | 英文文章 / 中文 / JSON / 本页源码 / 随机字节 |
| 拖入 / 点击选择文件 | 压缩任意本地文件（不会上传） |
| 压缩级别 | 0（只存储）~ 9（搜索最充分） |
| 鼠标悬停高亮片段 | 查看它引用的前文位置 |

**技巧**：随机字节几乎压缩不了；对比中文和英文的压缩率。

---

## 🧩 波函数坍缩（Wave Function Collapse）

按相邻规则逐格坍缩，从几条规则或一张小样例图生成地图。

| 操作 | 效果 |
|------|------|
| 图块集 | 管道 / 地形（角点图块）/ 迷宫、湖泊（从样例学习） |
| 大小 | 24 / 40 / 64 格见方 |
| ⏸ 暂停 / 单步 / ⏭ 直接完成 / 🎲 重新生成 | |
| 速度 | 每帧确定的格子数 |
| 无缝平铺 | 左右、上下边缘也按相邻检查 |

**技巧**：模糊的格子还有多种可能，右边是规则的来源（全部图块或样例图）。

---

## 🧵 布料模拟（Cloth Simulation）

Verlet 积分和距离约束模拟一块可以拖拽、剪开、撕破的布。

| 操作 | 效果 |
|------|------|
| ✋ 拖拽 | 抓住最近的点拉扯，拉得太猛会撕破 |
| ✂️ 剪刀 | 划过布料把它剪开 |
| 固定 | 顶边每隔 4 个 / 整条顶边 / 只固定两角 |
| 风力 / 约束迭代 | 风可以向左或向右；迭代越多布越硬 |
| 可撕裂 | 连接拉长到 1.9 倍时断开 |

---

## 🕹️ CHIP-8 模拟器（Emulator）

逐条执行 1977 年的 CHIP-8 虚拟机指令，带调试面板和可编辑的汇编源码。

| 操作 | 效果 |
|------|------|
| 程序 | Pong / 弹跳标志 / 键盘测试，或加载本地 ROM 文件 |
| 电脑键盘 `1234` `QWER` `ASDF` `ZXCV` / 👆 右侧键盘 | CHIP-8 的 16 个按键（Pong：`1` 上、`Q` 下） |
| ⏸ 暂停 / 单步 / ↺ 重置 | 暂停后可以单步执行，调试面板显示寄存器和反汇编 |
| 速度 / 兼容性 / 余辉 | 每秒指令数；COSMAC VIP 或现代行为；减轻闪烁 |
| 汇编源码 | 修改后「汇编并运行」 |

---

## 🏖️ 落沙游戏（Falling Sand）

每个格子是一粒材料，沙、水、木头、火、烟按简单规则相互作用。

| 操作 | 效果 |
|------|------|
| 🖱️ 拖拽 / 👆 手指 | 撒下所选材料 |
| 材料按钮 | 沙子 / 水 / 木头 / 火 / 墙 / 橡皮 |
| 笔刷 | 1~12 格 |
| ⏸ 暂停 / 🏜️ 示例场景 / 清空 | 暂停模拟 / 载入示例场景 / 清空画面 |

**技巧**：用木头搭个架子再点火，旁边倒一桶水灭火。

---

## ⚫ 五子棋 AI（Gomoku）

和带 α-β 剪枝搜索的 AI 下五子棋（无禁手）。

| 操作 | 效果 |
|------|------|
| 🖱️ 点击 / 👆 轻点 | 在交叉点落子 |
| 先手 | 我执黑先行 / AI 执黑先行 |
| 难度 | 搜索 2 ~ 5 层 |
| ↶ 悔棋 / 新局 | 撤回你的上一步（连同 AI 的应手）/ 重新开始 |

**技巧**：底部显示 AI 每一步搜索的局面数和耗时。

---

## ✍️ 手写数字识别（MNIST）

在 MNIST 上训练的神经网络，边写边识别。

| 操作 | 效果 |
|------|------|
| 🖱️ 按住拖动 / 👆 手指 | 在黑色区域写一个 0~9 的数字 |
| 清空 | 重写 |

**技巧**：数字写大一点、居中效果最好；右边的小图是网络实际看到的 28×28 输入和 64 个隐藏神经元。

---

## 工程说明

项目是一个 Cargo workspace，每个演示是一个独立的 crate，按类别放在 `crates/<类别>/<演示>/`，各自编译成自己的 `.wasm`（大多 15~45 KB，gzip 后 6~25 KB；最大的是手写识别和 Markdown，约 75 KB）；页面只下载自己的那一个。视频滤镜复用图像滤镜的包。多个 crate 共用的小工具在 `crates/common`。

| 类别 | crate（目录 `crates/<类别>/`） |
|------|------|
| 🎨 图形渲染 `graphics` | `mandelbrot`、`mandelbulb`、`terrain`、`rasterizer`、`pathtracer`（另有多线程构建 `pathtracer-mt`）、`wfc` |
| ⚛️ 物理模拟 `simulation` | `particles`、`webgpu`、`fluid`、`game-of-life`、`cloth` |
| 🧮 算法与性能 `algorithms` | `data-table`、`pathfind`、`benchmark`、`simd`、`delaunay`、`sudoku` |
| 🎬 多媒体 `media` | `image-filter`（图像 + 视频滤镜）、`spectrum`、`synth`（不用 wasm-bindgen 的裸 `.wasm`）、`seam-carving`、`jpeg` |
| 🛠️ 实用工具 `tools` | `sha256`、`qrcode`、`compress`、`markdown`、`mcp`（MCP 调试台，需要本地桥接服务） |
| 🎮 游戏与 AI `games` | `falling-sand`、`gomoku`、`digits`、`chip8` |