docs: 整理项目文档并统一界面表述

将项目说明按主题集中到 docs，补齐根目录 README 和 AGENTS，移除弃用方案并保留有效测试记录与未实现提案。同步文档索引、引用及改动日志生成路径，README 增加 GitHub Markdown 导航和 Mermaid 图。 - fix(client): 统一状态与操作文案，录制和截图成功后再显示完成提示 - test(client): 按文件名核对媒体类型，避免依赖时间戳排序验证：23 份项目文档、144 处本地引用、27 条外链、2 张 Mermaid 图；前端构建和 12 项测试；截图与录制的 4 条异步反馈路径；Windows Rust 编译检查和后端测试。后端 40 项返回成功，其中 3 项 ffmpeg 集成用例因本机缺少工具而未实际执行。
2026-10-19 11:26:26 +08:00
parent ee22a82ecd
commit 6a0eb14b28
54 changed files with 2624 additions and 4752 deletions
@@ -0,0 +1,33 @@
+# 图传故障排查
+
+以下命令均在仓库根目录执行。
+
+## 常见问题
+
+| 现象 | 检查方法 |
+| --- | --- |
+| 提示缺少 `esp-1.97.0.0` | 按上述命令安装指定名称的工具链，重新打开终端后检查版本 |
+| `espup` 查询 GitHub 版本返回 403 | 对上述固定版本安装命令追加 `--skip-version-parse`，或稍后重试 |
+| 找不到 `ldproxy` / `libclang` | 安装链接工具；Unix 加载 `export-esp.sh`，Windows 重开终端 |
+| ESP-IDF 路径或版本错误 | 清除旧 `IDF_PATH` 或指向 v5.5.5 SDK |
+| Windows 路径过长 | 缩短仓库和工具链路径，见开发说明 |
+| Wi-Fi 连不上 | 核对 2.4 GHz、凭据和认证方式，再重新编译烧录 |
+| 相机无输出 / 初始化失败 | 核对板型接线、供电与 Octal PSRAM |
+| `NO-EOI`、几帧后停止 | 确认 `CONFIG_CAMERA_PSRAM_DMA=n` |
+| 在线但没有画面 | 检查客户端订阅、UDP 5600、防火墙及 AP 隔离 |
+| 界面提示协议不匹配 | 板子与客户端的线路协议号不同；按提示重新烧录同版本的固件 |
+| 开启 VPN / 虚拟网卡后设备在线但无画面 | 使用支持按已发现设备 IP 定向续订的客户端；仅发送 `255.255.255.255` 广播可能走错网卡 |
+| 改 C 组件后无变化 | 清理 `esp-idf-sys` 构建缓存后重编，见开发说明 |
+| 主机项目被编为 Xtensa | 显式指定宿主 target，见各子项目说明 |
+
+用 `python scripts/udp_probe.py 10` 可独立检查视频协议；装甲板用 `python scripts/armor_probe.py 15`。这些脚本需要板卡在线，构建通过不代表已完成硬件验证。
+
+测量帧率和丢帧可运行以下命令，将 IP 换成板卡实际地址。对照测试时先退出桌面客户端，避免额外订阅者增加无线负载：
+
+```text
+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)。