# Lumen Code 开发者指南

[English](README.md) · [协议规范](../PROTOCOL.zh-CN.md) · [项目首页](../../README.zh-CN.md)

协议规范是写给"要做一个兼容实现"的人看的：精确，但读起来累。这几篇指南是写给"想先弄明白它怎么工作"的人看的：讲直觉、讲为什么，配图和数字，不追求逐字节的完整。读完再去看规范，会轻松很多。

| # | 指南 | 适合谁 | 你会知道 |
|---|---|---|---|
| 1 | [工作原理](01-how-it-works.zh-CN.md) | 所有人 | 一帧长什么样；文件如何变成格子、再变回文件；喷泉码为什么让丢帧无所谓 |
| 2 | [接收端如何读出一帧](02-scanner.zh-CN.md) | 想改进识别、移植识别器的人 | 从一张相机照片到数据包的十个步骤，以及每一步应对哪种现实问题 |
| 3 | [接入指南](03-integration.zh-CN.md) | 要在自己的应用里用它的人 | JS、WASM、Rust、C ABI（Android / iOS / 桌面）的最小示例与参数选择 |
| 4 | [性能：速度从哪里来](04-performance.zh-CN.md) | 关心吞吐量的人 | 比动态二维码快在哪里（逐项量化），什么在限制速度，下一步还能怎么提速 |
| 5 | [仪表解读](05-dashboard.zh-CN.md) | 使用演示页面、排查"为什么慢"的人 | 发送端、接收端每个数字的含义，健康值范围，看到什么该调什么 |

建议的阅读顺序：1 → 5 → 4，需要动手时再读 3，需要改识别器时读 2。

## 三十秒版本

- 发送端把文件切成小块，用**喷泉码**生成一个永不重复的数据包流；每个数据包加 CRC、再加 **Reed–Solomon** 纠错，变成一个**码字**。
- 每一帧是一个彩色格子网格（默认每格 2 比特），装着十几到几十个码字。网格自适应宽高、铺满屏幕，格子大小跟随屏幕的物理尺寸。
- 接收端拍到任意一帧，就把其中解得出的码字收下；码字之间互相独立，半张模糊的帧也有用。
- 不论丢了哪些帧，只要收到的不同数据包总数比文件的符号数多两三个，文件就能还原。没有"等下一轮补那一帧"。