docs: 按 humanizer 重写项目文档并同步 RMIC::2026 现状

2026-10-19 10:47:00 +08:00
parent d9a27b69f3
commit e3acb37d32
22 changed files with 3029 additions and 203 deletions
@@ -1,24 +1,41 @@
-# ESP32-S3 摄像头图传系统
+# RMIC::2026 视野链路系统

-基于 **Rust + ESP-IDF** 的局域网实时图传系统。ESP32-S3 采集摄像头输出的 JPEG，通过 UDP 向桌面客户端推流；桌面端提供队伍端与裁判端界面，并接收 ESP32-C3 装甲板的血量广播。
+黑龙江大学 602 实验室 · Simba Robotics 的机器人对抗赛视野链路。ESP32-S3 采集 OV5640 输出的硬件 JPEG，经 UDP 推给局域网内的桌面端；桌面端 RMIC::2026 提供队伍端与裁判端两套界面，接收 ESP32-C3 装甲板的血量广播，并负责固件维护。

-## 功能与架构
-
- 摄像头自动探测、JPEG 采集、UDP 分片发送与完整帧重组。
- 局域网广播发现与订阅，单块图传板最多向 4 个客户端发送画面。
- 运行中 Wi-Fi 断开后自动重连，重新获得 IP 后重建 UDP socket 并恢复订阅。
- 使用 MAC 派生的稳定设备 ID；两块图传板可烧录同一固件，在客户端绑定队伍。
- Tauri v2 + React 桌面端：视频显示、双方血量、设备绑定与录制。
- 独立 ESP32-C3 装甲板固件：四路受击检测、WS2812 灯带及血量上报。
+当前版本 **v0.2.1**（构建号 35，线路协议 1）。仓库已从 `ESP32S3_vt` 改名为 `simba-rmic-2026`，旧地址会重定向到新地址：

 ```text
-ESP32-S3 图传板 A ─┐                   ┌─ 队伍客户端
-                  ├─ 同一局域网 / UDP ─┼─ 裁判客户端
-ESP32-S3 图传板 B ─┤                   └─ 队伍客户端
-ESP32-C3 装甲主板 ─┘
+git@git.simba-robotics.com:PRAM/simba-rmic-2026.git
 ```

-图传使用 UDP **5600**，装甲板血量使用 UDP **5601**。板卡与客户端需在可互相通信、允许广播的网络中；关闭 AP 客户端隔离，并允许客户端程序通过防火墙。
+## 组成与数据流
+
+```text
+ESP32-S3 图传板 A ─┐                   ┌─ 队伍端（绑定本队板卡）
+                   ├─ 同一局域网 / UDP ─┼─ 裁判端（双路画面 + 装甲板表）
+ESP32-S3 图传板 B ─┤                   └─ 队伍端
+ESP32-C3 装甲板 ───┘
+```
+
+视频使用 UDP **5600**，装甲板血量使用 UDP **5601**。板卡与客户端要在可互相通信、允许广播的网络里；关闭 AP 客户端隔离，并允许客户端程序通过防火墙。
+
+| 部分 | 作用 | 技术栈 |
+| --- | --- | --- |
+| 根目录固件 | 图传板：相机采集、JPEG 分片、UDP 发送、发现与订阅、Wi-Fi 重连 | Rust `std` + ESP-IDF |
+| `protocol/` | 视频与血量的线路格式、帧重组 | 纯 Rust，主机可测 |
+| `desktop/` | RMIC::2026：队伍端 / 裁判端、录制、固件维护 | Tauri v2 + React + Rust |
+| `armor/` | 装甲板：四路受击检测、WS2812 灯带、血量上报 | Rust + ESP-IDF（ESP32-C3） |
+| `components/` | 本地相机驱动与 C/Rust 接口封装 | C + Rust FFI |
+
+## 当前状态
+
+图传板跑 VGA 640×480 彩色，完整接收约 **30 fps**，发射功率 **15 dBm**，三块 PSRAM 采集缓冲。发送端只保留当前一张完整 JPEG，拥塞时按有限预算重试，过期就转向新帧；原生视频通道和 WebView 都会拒绝滞留超过 100 ms 的旧帧。具体策略和五分钟实测见 [REALTIME.md](REALTIME.md)。
+
+桌面端已经换成 Tauri v2 + React，不再是 Slint 客户端。队伍端有装甲条、瞄准器、命中反馈和密码闸门，裁判端有双路画面、可改队名、装甲板发现表、槽位分配和录制回放；两侧共用同一份快照。固件维护页支持选择编译后打出的 `.zip` 固件包，在坏块板上搜索可写槽位并回读校验，不需要重新编译。
+
+装甲板是独立的 ESP32-C3 工程：主板负责四路压电片和四路灯带，整车 100 血，每次受击扣 3 点，每 200 ms 广播四条血量。
+
+版本号和改动日志都从 git 历史算出。板子每 2 秒广播的 `Hello` 里带着语义化版本、构建号和编译进去的线路协议号；客户端会把它显示在绑定列表和裁判端每一格下面，协议不匹配时直接说明原因，而不是只表现为没有画面。

 ## 项目结构

@@ -29,10 +46,11 @@ ESP32-C3 装甲主板 ─┘
 | `protocol/` | 共享 UDP 协议与帧重组，支持主机测试 |
 | `armor/` | 独立 ESP32-C3 装甲板 workspace |
 | `desktop/` | Tauri + React 客户端及独立网络核心 `core/` |
-| `scripts/` | 构建、烧录与探测脚本 |
+| `scripts/` | 构建、烧录、打包与探测脚本 |
 | `reference/armor/` | 早期 C 版装甲板工程 |
+| `docs/` | 固件维护、自动烧录评估与界面重构设计稿 |

-各子项目的构建目标不同。以下编译、烧录流程针对**根目录的 ESP32-S3 图传固件**。
+各子项目的构建目标不同。下面的编译、烧录流程针对根目录的 ESP32-S3 图传固件。

 ## 硬件要求

@@ -46,17 +64,17 @@ ESP32-C3 装甲主板 ─┘

 默认采集 VGA（640 × 480）、彩色 JPEG quality 12，按传感器节拍发送。相机引脚、Flash 分区和 PSRAM 配置见 [HARDWARE.md](HARDWARE.md)。换板型前必须核对接线，避免占用 Flash / PSRAM 引脚。

-## ESP Rust 工具链入门
+## 固件开发环境

-本项目使用 Rust `std` 和 ESP-IDF。ESP32-S3 属于 **Xtensa** 架构，需要通过 `espup` 安装 Espressif Rust 工具链；普通 `rustup target add` 不能替代这一步。根目录固定选择名为 `esp-1.97.0.0` 的工具链，避免浮动版本影响构建。
+本项目使用 Rust `std` 和 ESP-IDF。ESP32-S3 属于 Xtensa 架构，需要通过 `espup` 安装 Espressif Rust 工具链；普通 `rustup target add` 不能替代这一步。根目录固定使用名为 `esp-1.97.0.0` 的工具链，避免浮动版本影响构建。

 ### 1. 安装基础依赖与 Rust 工具

 先安装 [Rust / rustup](https://rustup.rs/)、[Git](https://git-scm.com/downloads)、[Python 3](https://www.python.org/downloads/)（建议 3.11）、[CMake](https://cmake.org/download/) 与 [Ninja](https://ninja-build.org/)，确保命令在 `PATH` 中。

- **Windows**：使用 PowerShell 7.5 或更新版本，安装 Visual Studio Build Tools 的“使用 C++ 的桌面开发”和 Windows SDK，使用 MSVC Rust 主机工具链。仓库和工具链尽量使用较短、无空格和中文的路径。
- **Linux（Debian / Ubuntu）**：安装 `build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build git curl`。
- **macOS**：安装 Xcode Command Line Tools（`xcode-select --install`），以及 Python、CMake 和 Ninja。
+- Windows：使用 PowerShell 7.5 或更新版本，安装 Visual Studio Build Tools 的“使用 C++ 的桌面开发”和 Windows SDK，使用 MSVC Rust 主机工具链。仓库和工具链尽量使用较短、无空格和中文的路径。
+- Linux（Debian / Ubuntu）：安装 `build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build git curl`。
+- macOS：安装 Xcode Command Line Tools（`xcode-select --install`），以及 Python、CMake 和 Ninja。

 以下命令显式使用 `+stable`，即使在仓库内执行，也不会要求事先已有 `esp`：

@@ -89,7 +107,7 @@ espflash --version

 ### 2. 准备 ESP-IDF

-默认使用 **ESP-IDF v5.5.5**。首次构建时，`esp-idf-sys` 下载 SDK、对应 C 工具链及 Python 依赖，默认缓存到用户目录的 `.espressif/`；需要网络、磁盘空间及缓存目录写入权限。
+默认使用 ESP-IDF v5.5.5。首次构建时，`esp-idf-sys` 下载 SDK、对应 C 工具链及 Python 依赖，默认缓存到用户目录的 `.espressif/`；需要网络、磁盘空间及缓存目录写入权限。

 已有匹配版本 SDK 时可在终端设置 `IDF_PATH`，不要提交个人绝对路径：

@@ -142,6 +160,8 @@ WIFI_PASS='你的Wi-Fi密码'
 #CAM_THERMAL_LIMIT_C=75
 #CAM_VSYNC_INVERT=1
 #WIFI_AUTH=wpa2
+#WIFI_TX_POWER_DBM=15
+#WIFI_TEST_DROP_AFTER_S=0
 ```

 | 变量 | 默认值 | 说明 |
@@ -149,7 +169,7 @@ WIFI_PASS='你的Wi-Fi密码'
 | `WIFI_SSID` | 无，必填 | 2.4 GHz 网络名称，最多 32 字节 |
 | `WIFI_PASS` | 空字符串 | Wi-Fi 密码；开放网络可留空 |
 | `CAM_RES` | `vga` | `qqvga` / `qvga` / `cif` / `hvga` / `vga` / `svga` / `xga` / `sxga` / `uxga` |
-| `CAM_QUALITY` | `12` | 0–63，越小通常画质越好、JPEG 越大 |
+| `CAM_QUALITY` | `12` | 0–63，越小通常画质越好、JPEG 越大；当前交付使用 18 |
 | `CAM_QUALITY_MAX` | `0` | `0` 固定画质；设为 `CAM_QUALITY`–63 时按发送回压在两者之间调节压缩，保留彩色和分辨率。拥塞时每 5 秒增大最多 3 档，连续稳定 15 秒才恢复 1 档 |
 | `CAM_MAX_FPS` | `0` | 取帧与发送的最高节拍，1–60；`0` 不限帧。仅限制消费节拍，不修改传感器时钟 |
 | `CAM_CLOCK_PROFILE` | `default` | `default` 保留驱动时钟；`vga30` 使用 OV5640 VGA 约 30.09 fps PLL 配置，保持 HTS/VTS 和读出窗口，SYSCLK 61 MHz / PCLK 15.25 MHz。切换后需重新核对曝光行数 |
@@ -165,8 +185,9 @@ WIFI_PASS='你的Wi-Fi密码'
 | `UDP_RETRY_BUDGET_US` | `8000` | 每帧、所有分片及订阅者共用的让出调度重试预算，0–25000 μs，须为 tick 整数倍；`0` 为非阻塞失败即弃。总发送检查期限为 25 ms，采集帧龄期限为 100 ms；分片间隔也计入期限，不会额外延长 |
 | `CAM_THERMAL_LIMIT_C` | `75` | 芯片内部温度达到该值时减半帧率（向上取整），下降 5°C 后恢复；40–95，`0` 禁用。原先不限帧时降至 8 fps |
 | `CAM_VSYNC_INVERT` | `1` | 驱动反相 VSYNC；硬件已反相时填 `0` |
-| `WIFI_AUTH` | 自动选择 | `none` / `wep` / `wpa` / `wpa2` / `wpawpa2` / `wpa3` / `wpa2wpa3` / `wapi` |
+| `WIFI_AUTH` | 自动选择 | `none` / `wep` / `wpa` / `wpa2` / `wpawpa2` / `wpa3` / `wpa2wpa3` / `wapi`；只在扫描看不到 AP（如隐藏 SSID）时才需要 |
 | `WIFI_TX_POWER_DBM` | SDK 默认上限 | 可选整数 2–20 dBm；当前交付请求 15 dBm，本板驱动回读 15.00 dBm；启动及重连时应用，拥塞和温控逻辑不降低此上限 |
+| `WIFI_TEST_DROP_AFTER_S` | `0` | 仅诊断构建：运行指定秒数后主动断网一次并保持 5 秒，用来验证运行时恢复。正式构建保持 `0` |

 `.env` 使用简单的 `KEY=value`；值含空格、`#` 或 `$` 时用单引号包围，不使用变量展开或命令替换。脚本会加载 `.env`，直接 `cargo build` 不会自动读取它。上述参数在编译时写入固件，修改后需要重新编译和烧录。`.env` 已被 Git 忽略；固件也包含凭据，分享前应重新配置。

@@ -187,7 +208,7 @@ $env:CARGO_TARGET_DIR = 'C:\s3vt'
 ./scripts/build.sh
 ```

-脚本执行 `cargo build --release --locked`，目标为 `xtensa-esp32s3-espidf`。首次编译包含 Rust 标准库、ESP-IDF 和相机组件，耗时较长。
+脚本执行 `cargo build --release --locked`，目标为 `xtensa-esp32s3-espidf`。首次编译包含 Rust 标准库、ESP-IDF 和相机组件，耗时较长。构建完成后可用 `-Package` / `--package` 再打一个 `.zip` 固件包，供桌面端维护页使用。

 Windows 的 ESP-IDF 构建输出路径需不超过 88 字符，因此示例使用短目录 `C:\s3vt`（需可写，且不与其他项目共用）。`subst` 不能绕过该检查。下表的 `<TARGET_DIR>` 在 Windows 示例中为 `C:/s3vt`，Linux / macOS 默认是仓库的 `target`。每次新开 Windows 终端都要设置相同的 `CARGO_TARGET_DIR`。

@@ -224,7 +245,7 @@ target_dir="${CARGO_TARGET_DIR:-target}"
 espflash flash --chip esp32s3 --port /dev/ttyACM0 --flash-size 16mb --flash-mode dio --flash-freq 40mhz --partition-table partitions.csv --bootloader "$target_dir/xtensa-esp32s3-espidf/release/bootloader.bin" --monitor "$target_dir/xtensa-esp32s3-espidf/release/esp32"
 ```

-连接失败时按住 **BOOT**，点按 **RESET / EN**，松开 BOOT 后重试。正常启动应看到相机识别、Wi-Fi 获取 IP 和 `ESP32 camera is live` 日志。没有客户端时，`0 clients subscribed` 属于正常状态。
+连接失败时按住 BOOT，点按 RESET / EN，松开 BOOT 后重试。正常启动应看到相机识别、Wi-Fi 获取 IP 和 `ESP32 camera is live` 日志。没有客户端时，`0 clients subscribed` 属于正常状态。

 仅查看日志：

@@ -236,11 +257,11 @@ espflash monitor --port COM5

 `espflash save-image --merge` 可导出从 `0x0` 写入的合并镜像。完整命令、独立镜像偏移与测试方法见 [DEVELOPMENT.md](DEVELOPMENT.md)。

-保留的 `scripts/flash.sh` 针对**特定坏 Flash 模组**，依赖 macOS 环境，会修改分区并重编译。普通板卡使用上述标准流程；坏板限制见 [HARDWARE.md](HARDWARE.md#损坏-flash-模组的兼容处理)。
+保留的 `scripts/flash.sh` 针对特定坏 Flash 模组，依赖 macOS 环境，会修改分区并重编译。普通板卡使用上述标准流程；坏板限制见 [HARDWARE.md](HARDWARE.md#损坏-flash-模组的兼容处理)。

-## 客户端与装甲板
+## 桌面端 RMIC::2026

-桌面端入口如下。安装依赖、主机 target 设置与功能说明见 [desktop/README.md](desktop/README.md)：
+安装依赖并启动开发模式：

 ```text
 cd desktop
@@ -248,7 +269,26 @@ pnpm install
 pnpm app
 ```

-装甲板是独立的 **ESP32-C3 / RISC-V** 工程，不能使用 S3 的 ELF。`ARMOR_TEAM=0/1` 在编译期决定红 / 蓝队伍。接线、规则与构建烧录见 [armor/README.md](armor/README.md)。
+`pnpm app` 等价于 `tauri dev`：起 Vite、编 Rust、开窗口。只构建前端用 `pnpm build`，打包用 `pnpm tauri build`。Windows x64 需要 Node.js 22.12+、pnpm、Rust stable MSVC、Visual Studio Build Tools 的 C++ 组件和 WebView2 Runtime；安装包用 NSIS，产物在 `src-tauri/target/x86_64-pc-windows-msvc/release/`。
+
+没有板子也能跑演示模式：
+
+```text
+cd desktop
+CAM_DEMO=1 pnpm app
+```
+
+演示模式合成协议数据报，从真实的接收与重组路径进入界面，不是给界面塞假数据。界面配置、密码、绑定、录制、裁判端槽位、防作弊和固件维护的细节见 [desktop/README.md](desktop/README.md)。固件维护页的实现、`.zip` 包格式与实机验证范围见 [docs/firmware-maintenance.md](docs/firmware-maintenance.md)。
+
+## 装甲板
+
+装甲板是独立的 ESP32-C3 / RISC-V 工程，不能使用 S3 的 ELF。`ARMOR_TEAM=0/1` 在编译期决定红 / 蓝队伍。接线、规则与构建烧录见 [armor/README.md](armor/README.md)。
+
+```bash
+scripts/build_armor.sh                 # 编译
+scripts/flash_armor.sh                 # 烧录并看 20 秒日志
+python3 scripts/armor_probe.py 15      # 不打开界面时核对血量广播
+```

 ## 常见问题

@@ -263,6 +303,7 @@ pnpm app
 | 相机无输出 / 初始化失败 | 核对板型接线、供电与 Octal PSRAM |
 | `NO-EOI`、几帧后停止 | 确认 `CONFIG_CAMERA_PSRAM_DMA=n` |
 | 在线但没有画面 | 检查客户端订阅、UDP 5600、防火墙及 AP 隔离 |
+| 界面提示协议不匹配 | 板子与客户端的线路协议号不同；按提示重新烧录同版本的固件 |
 | 开启 VPN / 虚拟网卡后设备在线但无画面 | 使用支持按已发现设备 IP 定向续订的客户端；仅发送 `255.255.255.255` 广播可能走错网卡 |
 | 改 C 组件后无变化 | 清理 `esp-idf-sys` 构建缓存后重编，见开发说明 |
 | 主机项目被编为 Xtensa | 显式指定宿主 target，见各子项目说明 |
@@ -277,7 +318,7 @@ python scripts/perf_probe.py 192.168.1.139 --seconds 30 --json perf.json

 脚本定向续订，支持保留 VPN / TUN 的环境。输出包含完整帧率、帧损失率、接收间隔和组装耗时；这些时间不等于摄像头到屏幕的端到端延迟。

-运动图传保持 `CAM_GRAYSCALE=0`，优先使用自动曝光上限和自动增益协同控制拖影。室内强制 −1 EV / 固定短快门在本机过暗，已撤回；提高增益上限也会增加噪点。需要限流时可设置 `CAM_MAX_FPS=15`，追求帧率时使用 `0`；可启用有界 JPEG 压缩调节应对发送回压，分片间隔按网络实测选择。灰度效果仍保留硬件 JPEG，不是改为 RGB565 或降低 JPEG 采样位数。75°C 是主动减载阈值，温度来自 ESP 芯片内部，不能代表摄像头或环境温度，也不是芯片损坏温度规格。五分钟彩色对照与此前中止的灰度长测见 [STABILITY.md](STABILITY.md)。
+运动图传保持 `CAM_GRAYSCALE=0`，优先使用自动曝光上限和自动增益协同控制拖影。室内强制 −1 EV / 固定短快门在本机过暗，已撤回；提高增益上限也会增加噪点。需要限流时设 `CAM_MAX_FPS=15`，追求帧率时用 `0`；可启用有界 JPEG 压缩调节应对发送回压，分片间隔按网络实测选择。灰度效果仍保留硬件 JPEG，不是改为 RGB565 或降低 JPEG 采样位数。75°C 是主动减载阈值，温度来自 ESP 芯片内部，不能代表摄像头或环境温度，也不是芯片损坏温度规格。五分钟彩色对照与此前中止的灰度长测见 [STABILITY.md](STABILITY.md)。

 ## 版本号与改动日志

@@ -288,29 +329,29 @@ node scripts/version.mjs --write   # 计算并写回 version.json / CHANGELOG /
 node scripts/version.mjs --check   # 只校验（CI 与发布前用）
 ```

- 版本号由提交类型决定：`BREAKING CHANGE:` → major，`feat` → minor，`fix`/`perf` → patch。
+- 版本号由提交类型决定：`BREAKING CHANGE:` → major，`feat` → minor，`fix` / `perf` → patch。
 - 构建号 = `git rev-list --count HEAD`，单调、不撞车。
- 同一次计算还产出 `version.json`（固件 `build.rs` 读它）、`CHANGELOG.json`、
-  `desktop/src/lib/version.ts`。
+- 同一次计算还产出 `version.json`（固件 `build.rs` 读它）、`CHANGELOG.json`、`desktop/src/lib/version.ts`。

-**固件与客户端的版本是联动过的**：板子每 2 秒广播的 `Hello` 里带着语义化版本、构建号与
-它编译进去的线路协议号；客户端读出来显示在设置与裁判端每一格下面，协议对不上时直接说明
-原因（"板子是协议 2，客户端是协议 1，画面会被丢弃，请重新烧录"），而不是只表现为没有画面。
+固件与客户端的版本是联动的：板子每 2 秒广播的 `Hello` 里带着语义化版本、构建号与它编译进去的线路协议号；客户端读出来显示在设置与裁判端每一格下面，协议对不上时直接说明原因（“板子是协议 2，客户端是协议 1，画面会被丢弃，请重新烧录”），而不是只表现为没有画面。
+
+细节见 [desktop/README.md](desktop/README.md#版本与改动日志算出来的不是写出来的) 与 [protocol/README.md](protocol/README.md#通告里的版本信息)。

-细节见 [`desktop/README.md`](desktop/README.md#版本与改动日志算出来的不是写出来的) 与
-[`protocol/README.md`](protocol/README.md#通告里的版本信息)。
 ## 文档索引

- [CHANGELOG.md](CHANGELOG.md)：改动记录与历史修复。
+- [CHANGELOG.md](CHANGELOG.md)：改动记录，由脚本从 git 历史生成。
 - [HARDWARE.md](HARDWARE.md)：接线、内存、Flash 与驱动限制。
 - [DEVELOPMENT.md](DEVELOPMENT.md)：镜像导出、测试、协议与性能测量。
 - [PERFORMANCE.md](PERFORMANCE.md)：保留 TUN 的图传排查、参数取舍与实际测试结果。
 - [STABILITY.md](STABILITY.md)：限帧、灰度与温度减载，长时间运行测试。
 - [REALTIME.md](REALTIME.md)：阻塞时取最新帧、超期丢弃和客户端积压处理。
 - [POWER.md](POWER.md)：15 dBm 回退、功率与距离的关系，以及发送拥塞证据。
- [LATENCY.md](LATENCY.md)：当前约 30 fps 配置、Wi-Fi 重连及实际画面链路延迟对照。
+- [LATENCY.md](LATENCY.md)：约 30 fps 配置、Wi-Fi 重连及实际画面链路延迟对照。
+- [FLASH-CLIENT-ARCH.md](FLASH-CLIENT-ARCH.md)：烧录 / 维护客户端的架构提议稿。
 - [protocol/README.md](protocol/README.md)：UDP 线路格式及帧重组。
 - [armor/README.md](armor/README.md)：装甲板固件与规则。
- [desktop/README.md](desktop/README.md)：桌面端配置、录制与排查。
- [docs/firmware-provisioning-evaluation.md](docs/firmware-provisioning-evaluation.md)：自动烧录、坏区规避与 SSID 配置 patch 的工具评估、MVE 与测试矩阵。
+- [desktop/README.md](desktop/README.md)：RMIC::2026 的配置、录制与排查。
 - [docs/firmware-maintenance.md](docs/firmware-maintenance.md)：已实现的固件维护页、官方 bundle 格式、坏块规避流程与实机验证记录。
+- [docs/firmware-provisioning-evaluation.md](docs/firmware-provisioning-evaluation.md)：自动烧录、坏区规避与 SSID 配置 patch 的工具评估、MVE 与测试矩阵。
+- [docs/desktop-ui-redesign.md](docs/desktop-ui-redesign.md)：RMIC::2026 界面、比赛控制与直播包装的重构设计稿。
+- [docs/CHANGELOG-legacy.md](docs/CHANGELOG-legacy.md)：建立自动版本机制之前的人工改动记录。