diff --git a/docs/INDEX.md b/docs/INDEX.md deleted file mode 100644 index 723484e..0000000 --- a/docs/INDEX.md +++ /dev/null @@ -1,165 +0,0 @@ -# micro_servers 文档索引 - -所有项目文档的统一入口。 - -## 目录结构 - -``` -docs/ -├── INDEX.md # 本文件（文档总索引） -├── security/ # 安全审计与加固（29 篇） -├── reviews/ # 代码审查日志（4 篇） -└── reports/ # 分析报告与开发规划（14 篇） -``` - ---- - -## 一、项目总览 - -| 文档 | 路径 | 说明 | -|------|------|------| -| 项目 README | [../README.md](../README.md) | 架构总览、服务说明、安装运行指南 | - ---- - -## 二、安全文档 (`security/`) - -### 全局审计与加固 - -| 文档 | 说明 | -|------|------| -| [DEPLOY_SECURITY_AUDIT_20260801.md](security/DEPLOY_SECURITY_AUDIT_20260801.md) | 部署配置安全审计（docker-compose、systemd、防火墙、TLS 等） | -| [DEPS_SECURITY_AUDIT_20260801.md](security/DEPS_SECURITY_AUDIT_20260801.md) | 依赖安全审计（第三方库版本、已知漏洞、许可证） | -| [SECURITY_HARDENING_PLAN_20260803.md](security/SECURITY_HARDENING_PLAN_20260803.md) | 安全加固计划（内网通信安全加固开发计划） | - -### 各模块安全审计报告 - -| 模块 | 文档 | 审计范围 | -|------|------|----------| -| waf | [waf_SECURITY_AUDIT_20260801.md](security/waf_SECURITY_AUDIT_20260801.md) | Go WAF 网关（TLS、coraza、反向代理） | -| gateway | [gateway_SECURITY_AUDIT.md](security/gateway_SECURITY_AUDIT.md) | C++20 应用网关安全审计合并文档（v0.8.0 三轮审计合并：初版/复审/增量复审；v0.9.0 纯转发，认证迁 ca） | -| ca | [ca_SECURITY_AUDIT.md](security/ca_SECURITY_AUDIT.md) | C++20 中央认证服务（Central Auth，v1.0.0），承接原 gateway 认证职责；含迁移接收项与 ca 相关开放项 | -| core | [core_SECURITY_AUDIT_20260801.md](security/core_SECURITY_AUDIT_20260801.md) | C++20 进程托管服务（PMC/Nidus） | -| db | [db_SECURITY_AUDIT_20260801.md](security/db_SECURITY_AUDIT_20260801.md) | Python 数据库服务（pymsg、SQLAlchemy、日志收集） | -| db2 | [db2_SECURITY_AUDIT_20260806.md](security/db2_SECURITY_AUDIT_20260806.md) | C++20 数据库 RPC 服务（db 的 C++ 重实现，SQLite C API） | -| pymsg | [pymsg_SECURITY_AUDIT_20260801.md](security/pymsg_SECURITY_AUDIT_20260801.md) | Python RPC 基础库（长度前缀帧、MsgClient/Server） | -| dnfs | [dnfs_SECURITY_AUDIT_20260801.md](security/dnfs_SECURITY_AUDIT_20260801.md) | Python 树状网络文件系统（**已废弃，生产用 dnfs2**；2026-08-10 复核为全量 16 项发现） | -| dnfs2 | [dnfs2_SECURITY_AUDIT_20260808.md](security/dnfs2_SECURITY_AUDIT_20260808.md) | C++20 树状网络文件系统（dnfs 重实现，**生产在跑**，评级 A） | -| static | [static_SECURITY_AUDIT_20260801.md](security/static_SECURITY_AUDIT_20260801.md) | Python 前端托管/文件服务 | -| fsys | [fsys_SECURITY_AUDIT_20260808.md](security/fsys_SECURITY_AUDIT_20260808.md) | Python 文件系统服务 | -| ai_review | [ai_review_SECURITY_AUDIT_20260801.md](security/ai_review_SECURITY_AUDIT_20260801.md) | Python AI 内容审核（DeepSeek + RAG） | -| smtp | [smtp_SECURITY_AUDIT_20260801.md](security/smtp_SECURITY_AUDIT_20260801.md) | Python 邮件服务（验证码发送/校验）初版 + 0809 复审合并版 | -| smtp3 | [smtp3_SECURITY_AUDIT_20260809.md](security/smtp3_SECURITY_AUDIT_20260809.md) | C++20 邮件服务（smtp 重写），2 项 P0 + P1-2 + 全部 P3 当日已修复，仅剩 P1-1（TLS 校验）待修 | -| captcha | [captcha_SECURITY_AUDIT_20260801.md](security/captcha_SECURITY_AUDIT_20260801.md) | Python 验证码服务 | -| captcha2 | [captcha2_SECURITY_AUDIT_20260809.md](security/captcha2_SECURITY_AUDIT_20260809.md) | C++20 验证码服务（captcha 重写，FreeType + stb，含 P0 大小写缺陷发现） | -| confs | [confs_SECURITY_AUDIT_20260801.md](security/confs_SECURITY_AUDIT_20260801.md) | Python 统一配置服务 | -| libmsg | [libmsg_SECURITY_AUDIT_20260806.md](security/libmsg_SECURITY_AUDIT_20260806.md) | C++ RPC 基础库（pymsg 协议帧、MsgClient/Server、RpcClient/Server） | -| libhttp | [libhttp_SECURITY_AUDIT_20260803.md](security/libhttp_SECURITY_AUDIT_20260803.md) | C++ HTTP/WebSocket 库（请求/响应/WS/静态文件） | -| libsqlite3 | [libsqlite3_SECURITY_AUDIT_20260806.md](security/libsqlite3_SECURITY_AUDIT_20260806.md) | C++ SQLite3 封装（Header-only） | -| libth | [libth_SECURITY_AUDIT_20260804.md](security/libth_SECURITY_AUDIT_20260804.md) | C++ 线程库（Thread、Cv_wait、Fsm） | -| aibox | [aibox_SECURITY_AUDIT_20260801.md](security/aibox_SECURITY_AUDIT_20260801.md) | Python AI 智能体系统（WebSocket） | -| BotOps | [BotOps_SECURITY_AUDIT_20260801.md](security/BotOps_SECURITY_AUDIT_20260801.md) | BotOps 运维控制面板 | -| actpred | [actpred_SECURITY_AUDIT_20260808.md](security/actpred_SECURITY_AUDIT_20260808.md) | Python 动作预测模块（PyTorch 训练/推理、.mt 解析、ONNX 导出） | - ---- - -## 三、代码审查 (`reviews/`) - -| 文档 | 说明 | -|------|------| -| [core_CODE_REVIEW_LOG_20260730.md](reviews/core_CODE_REVIEW_LOG_20260730.md) | Core 模块代码审查日志（2026-07-30，自动化审查） | -| [DEPLOY_DEFECT_AUDIT_20260806.md](reviews/DEPLOY_DEFECT_AUDIT_20260806.md) | 部署缺陷审查（2026-08-06，首次原生部署实录，含修复记录） | -| [actpred_CODE_AUDIT_20260808.md](reviews/actpred_CODE_AUDIT_20260808.md) | actpred 模块代码审计（2026-08-08，两轮合并：第 1 轮 16 项 + 第 2 轮复审 11 项，共 27 项全部修复） | -| [bot4cj_CODE_AUDIT_20260808.md](reviews/bot4cj_CODE_AUDIT_20260808.md) | bot4cj 模块代码审计（2026-08-08，仓颉机器人硬件脚本解析器，15 项发现，待修复） | - ---- - -## 四、分析报告与开发规划 (`reports/`) - -| 文档 | 说明 | -|------|------| -| [blackbird_research_report.md](reports/blackbird_research_report.md) | blackbird 项目研究报告（安全架构分析、改进建议、里程碑规划） | -| [core_service_registry_dev_doc.md](reports/core_service_registry_dev_doc.md) | Core 模块注册中心功能扩展开发文档（服务注册/发现/健康守护/自动重启） | -| [auth_service_plan.md](reports/auth_service_plan.md) | 认证独立化（CA 模块）开发文档（waf→ca→gateway 前置拓扑；gateway 退 8445 纯转发不验签；下游/WAF/前端零改动） | -| [aibox_open_dev_plan.md](reports/aibox_open_dev_plan.md) | aibox 开放版开发计划（命令注入漏洞修复、安全沙箱方案） | -| [aibox_file_network_cli_refactor.md](reports/aibox_file_network_cli_refactor.md) | aibox 文件/网络操作命令行化重构计划 | -| [blackbird_promo_full.md](reports/blackbird_promo_full.md) | blackbird 项目完整版宣传文案 | -| [bot4cj_analysis_20260525_00.md](reports/bot4cj_analysis_20260525_00.md) | bot4cj 机器人模块分析报告（Markdown） | -| [libcrypt_CBC_deprecation_dev_doc.md](reports/libcrypt_CBC_deprecation_dev_doc.md) | libcrypt CBC 模式缺陷分析与 AES-GCM 迁移开发文档 | -| [bot4cj_analysis_20260525_00.html](reports/bot4cj_analysis_20260525_00.html) | bot4cj 机器人模块分析报告（HTML） | -| [actpred_pretrain_test_20260808.md](reports/actpred_pretrain_test_20260808.md) | actpred 预训练与推理测试报告（action_dim=18 变更、.mt 解析器、预训练、推理基准、NPU 调研） | -| [captcha_cpp_rewrite_dev_doc.md](reports/captcha_cpp_rewrite_dev_doc.md) | captcha 模块 C++20 重写开发方案（FreeType + stb_image_write 替代 Pillow，协议兼容零改动） | -| [smtp_cpp_rewrite_dev_doc.md](reports/smtp_cpp_rewrite_dev_doc.md) | smtp 模块 C++20 重写开发方案（SMTP_SSL 客户端手写，审计 7 项遗留一并在重写中修复，零新增系统依赖） | -| [libhttp_remote_addr_dev_doc.md](reports/libhttp_remote_addr_dev_doc.md) | libhttp 对端地址透传开发方案（X-Remote-Addr 可信头注入，非破坏；gateway trust_xff 配套，闭环审计 A4） | -| [confs2_cpp_rewrite_dev_doc.md](reports/confs2_cpp_rewrite_dev_doc.md) | confs 模块 C++20 重写开发方案（libmsg RpcServer 替代 pymsg，协议兼容零改动，审计 7 项遗留一并修复，零新增系统依赖，未来可合入 core 注册中心） | -| [fsys_public_frontend_research_20260810.md](reports/fsys_public_frontend_research_20260810.md) | fsys/public 前端研究报告（Vanilla 技术栈、HttpOnly Cookie 认证体系、dnfs/aibox/view/mgmt 页面分析、8 项问题与改进建议） | - ---- - -## 五、各模块 README（保留在原目录） - -各模块根目录的 `README.md` 保留在原位，方便 GitHub 直接浏览： - -### 核心服务 - -| 模块 | 路径 | 说明 | -|------|------|------| -| core | [../core/README.md](../core/README.md) | 进程托管服务（PMC/Nidus） | -| waf | [../waf/README.md](../waf/README.md) | WAF 网关（Go, coraza） | -| gateway | [../gateway/README.md](../gateway/README.md) | 应用层网关（C++20） | -| db | [../db/README.md](../db/README.md) | 通用数据库服务（pymsg） | -| db2 | [../db2/README.md](../db2/README.md) | C++20 数据库 RPC 服务（db 重实现） | -| confs | [../confs/README.md](../confs/README.md) | 统一配置服务 | -| static | [../static/README.md](../static/README.md) | 前端托管服务 | -| dnfs | [../dnfs/README.md](../dnfs/README.md) | 树状网络文件系统 | -| dnfs2 | [../dnfs2/README.md](../dnfs2/README.md) | C++20 树状菜单服务（dnfs 重实现） | -| ai_review | [../ai_review/README.md](../ai_review/README.md) | AI 内容审核 | -| captcha | [../captcha/README.md](../captcha/README.md) | 验证码服务 | -| smtp | [../smtp/README.md](../smtp/README.md) | 邮件服务 | -| redirect80 | [../redirect80/README.md](../redirect80/README.md) | HTTP 重定向服务 | - -### 共享库 - -| 库 | 路径 | 说明 | -|----|------|------| -| pymsg | [../pymsg/README.md](../pymsg/README.md) | Python RPC 基础库 | -| libhttp | [../libhttp/README.md](../libhttp/README.md) | C++ HTTP/WebSocket 库 | -| libcrypt | [../libcrypt/README.md](../libcrypt/README.md) | C++ 加密库 | -| libth | [../libth/README.md](../libth/README.md) | C++ 线程库 | -| libsqlite3 | [../libsqlite3/README.md](../libsqlite3/README.md) | C++ SQLite3 封装 | -| libmsg | [../libmsg/README.md](../libmsg/README.md) | C++ RPC 基础库（pymsg 协议 C++ 实现） | -| libtry | [../libtry/](../libtry/) | 嵌入式脚本解释器 | - -### 其他模块 - -| 模块 | 路径 | 说明 | -|------|------|------| -| aibox | [../aibox/README.md](../aibox/README.md) | AI 智能体系统 | -| bot4cj | [../bot4cj/README.md](../bot4cj/README.md) | 机器人硬件脚本解析器（仓颉） | -| BotOps | [../BotOps/README.md](../BotOps/README.md) | aibox 智能体 TUI 前端（Textual） | -| actpred | [../actpred/README.md](../actpred/README.md) | 动作预测神经网络（PyTorch） | -| lci | [../lci/README.md](../lci/README.md) | 嵌入式帧缓冲图形界面 | -| fsys | [../fsys/README.md](../fsys/README.md) | 文件系统服务 | -| tests | [../tests/blackbox/README.md](../tests/blackbox/README.md) | 黑盒测试套件 | - -### Robot 文档 (README.robot.md) - -| 模块 | 路径 | -|------|------| -| pymsg | [../pymsg/README.robot.md](../pymsg/README.robot.md) | -| libhttp | [../libhttp/README.robot.md](../libhttp/README.robot.md) | -| libtry | [../libtry/README.robot.md](../libtry/README.robot.md) | -| aibox | [../aibox/README.robot.md](../aibox/README.robot.md) | -| bot4cj | [../bot4cj/README.robot.md](../bot4cj/README.robot.md) | - ---- - -## 六、aibox 技能与任务文档 - -aibox 模块的技能提示词和任务模板属于运行时数据，保留在原目录： - -| 类型 | 路径 | -|------|------| -| 技能格式说明 | [../aibox/SKILLS_FORMAT.md](../aibox/SKILLS_FORMAT.md) | -| 技能目录 | [../aibox/skills/](../aibox/skills/) | -| 任务目录 | [../aibox/tasks/](../aibox/tasks/) | diff --git a/docs/reports/actpred_effectiveness_evaluation_20260809.md b/docs/reports/actpred_effectiveness_evaluation_20260809.md new file mode 100644 index 0000000..f2d04ae --- /dev/null +++ b/docs/reports/actpred_effectiveness_evaluation_20260809.md @@ -0,0 +1,265 @@ +# actpred 模块效果评估报告 + +> 日期：2026-08-09 +> 评估范围：actpred 模块架构、代码质量、预训练模型实际预测能力、部署就绪度 +> 评估方法：源码审阅 + 单元测试 + 预训练 checkpoint 全量滑动窗口定量评估 + +--- + +## 一、模块定位 + +actpred 是 micro_servers 的独立/边缘模块，纯离线 CLI 工具，不参与微服务调用链。 +核心功能：输入多帧摄像头图像 + 历史动作序列 → 预测下一时间步的连续动作（回归）。 +面向树莓派 Dashun 蜘蛛机器人（配合 bot4cj 模块），目标部署场景为嵌入式机器人实时控制。 + +--- + +## 二、架构评估 + +### 2.1 模型架构 + +多帧 Transformer 注意力融合（2026-08 重写）： + +``` +F 帧图像 (F×3×64×64) → 共享 CNN 编码器 → F 个 token → proj → d_model ┐ + ├→ [img×F, act×H, PRED] + 位置编码 +动作历史 (H×D) → Linear proj → d_model → H 个 token ─┤ │ +可学习 [PRED] token ─────────────────────────────────────────┘ ▼ + TransformerEncoder (pre-LN, 2层, 4头, d=128) + │ + 取 PRED 位置输出 → MLP 头 → 预测动作 +``` + +### 2.2 关键指标 + +| 指标 | 数值 | +|------|------| +| 参数量 | ~450K | +| CPU 端到端推理 | 4.25 ms（235 FPS） | +| CPU 纯 forward | 2.77 ms | +| image_encoder 占比 | 47%（pure forward） | +| ONNX 导出 | opset 17，仅 batch 维动态 | +| ONNX 一致性 | max diff ~1.5e-8 | +| 单元测试 | 56 个，全部通过 | + +### 2.3 架构评价 + +| 维度 | 评级 | 说明 | +|------|------|------| +| 模型设计 | A | 多帧注意力融合合理，token 序列固定长度 F+H+1，NPU 友好 | +| 推理速度 | A | 4.25ms 端到端，满足实时控制需求（>100 FPS） | +| ONNX 部署 | A- | 静态 shape 导出正确，版本转换有轻微告警不影响功能 | +| 安全性 | A | 零网络攻击面 + weights_only + 完整配置校验链 | + +--- + +## 三、代码质量评估 + +### 3.1 代码规模 + +| 文件 | 行数 | 职责 | +|------|------|------| +| config.py | 205 | 三层 dataclass 配置 + CLI + 校验 | +| model.py | 130 | SimpleCNN / MobileNetV2 / Transformer 模型 | +| dataset.py | 151 | 数据集加载 + DataRecorder | +| train.py | 187 | 训练入口（episode 级划分） | +| pretrain_mt.py | 289 | .mt 预训练入口（文件级划分） | +| predict.py | 138 | 推理封装 + CLI | +| export_onnx.py | 58 | ONNX 导出 + 一致性验证 | +| mt_parser.py | 133 | .mt @Action 矩阵解析器 | +| test_actpred.py | 722 | 单元测试（56 cases） | +| **合计** | **2013** | | + +### 3.2 优点 + +1. **安全性设计扎实** + - `torch.load(..., weights_only=True)` 全局使用 + - `parse_checkpoint_config` 实现键集合 + 值域 + 整除性三重校验 + - 旧架构 checkpoint 被未知键检查拒载 + +2. **数据泄漏已修复** + - pretrain_mt.py 采用文件级 train/val 划分（非样本级滑动窗口） + - train.py 采用 episode 级划分，归一化统计量仅用训练集计算 + +3. **工程化成熟** + - Config dataclass 三层结构 + CLI override + checkpoint roundtrip + - DataRecorder 原子 mkdir 防并发竞态 + - mt_parser `-` 前向填充取 @Servo 初始角度 + +4. **测试覆盖全面** + - 56 单元测试，覆盖前向传播、数据加载、配置校验、mt 解析、推理端到端、ONNX 导出 + - 边界条件充分（空数据集、维度不匹配、帧数不一致、未知键、旧 checkpoint 拒载等） + +### 3.3 可改进项 + +1. image_encoder 仍为推理瓶颈（占 pure forward 的 47%），后续可 INT8 量化 +2. 训练仅用 CosineAnnealingLR，未配置 warmup +3. ONNX 导出 opset 17 版本转换有告警（`axes_input_to_attribute` 断言失败后 fallback），不影响正确性但值得跟进 +4. `requirements.txt` 版本范围宽松（`torch>=2.0,<3.0`），生产环境建议锁定 + +--- + +## 四、预训练模型定量评估 + +### 4.1 训练数据概况 + +``` +.mt 脚本文件数: 13 +总动作行数: 77 +训练数据列数: 12（补零到 18） +文件级划分后: ~10 文件训练 / ~3 文件验证 +训练样本数: ~50（滑动窗口） +模型参数量: 450K +样本/参数比: 1:9000（严重欠定） +``` + +各 .mt 文件数据量： + +| 文件 | 行数 | 动作范围 | +|------|------|----------| +| jump.mt | 5 | [-180, 200] | +| left-hand.mt | 4 | [-180, 1000] | +| left-turn.mt | 11 | [-180, 200] | +| lie-down.mt | 6 | [-180, 200] | +| rght-hand.mt | 4 | [-180, 1000] | +| std.mt | 1 | [-180, 200] | +| stdd.mt | 7 | [-180, 200] | +| t0.mt | 10 | [-180, 500] | +| t1.mt | 1 | [10, 20] | +| tilt-b/f/l/r.mt | 各 7 | [-180, 200] | + +### 4.2 全量滑动窗口评估 + +使用预训练 checkpoint `pretrain_best_inference.pt`，对所有 .mt 文件做 history_len=5 滑动窗口预测： + +| 脚本 | 预测数 | 平均 L2 误差 | +|------|--------|-------------| +| left-turn.mt | 6 | 117.9 | +| lie-down.mt | 1 | 107.8 | +| stdd.mt | 2 | 138.7 | +| t0.mt | 5 | 239.1 | +| tilt-b.mt | 2 | 193.9 | +| tilt-f.mt | 2 | 201.4 | +| tilt-l.mt | 2 | 210.9 | +| tilt-r.mt | 2 | 183.4 | + +### 4.3 与 Baseline 对比 + +| 方法 | Mean L2 Error | 相对比率 | +|------|---------------|----------| +| **模型预测** | **175.8** | **0.76x** | +| Naive（复制上一步） | 230.0 | 1.0x（基准） | +| 全局均值预测器 | 251.2 | 1.09x | + +模型比 "复制上一步" 好 24%，比 "全局均值" 好 30%。但评估集仅 22 个预测点，统计意义有限。 + +### 4.4 预测分布分析 + +| 指标 | 预测 | 实际 | +|------|------|------| +| 数值范围 | [-164.5, 176.3] | [-180.0, 500.0] | +| 各维 std（舵机 0-9） | 12~57 | 0~95 | +| 各维 std（扬声器/延时 10-11） | 4~58 | 4~139 | +| 各维 std（预留 12-17） | 1~6 | 0 | + +**核心问题**：预测严重趋于均值（regression to the mean），预测 std 仅为实际 std 的 ~50%。极端值（如扬声器频率 1000Hz、延时 200ms）完全无法捕获。 + +### 4.5 典型预测案例 + +left-turn.mt 滑动窗口预测（前 6 维）： + +``` +t=5: pred=[18.0, 10.3, 17.1, -1.3, 16.5, 11.2] actual=[45, 0, 45, 45, 45, 0] L2=129.4 +t=6: pred=[16.2, 8.5, 15.5, -0.4, 15.1, 8.9] actual=[45, 0, 0, 45, 45, 0] L2=127.3 +t=7: pred=[15.7, 8.0, 15.0, -0.3, 14.7, 8.3] actual=[45, 0, 0, 0, 45, 0] L2=109.1 +``` + +预测值集中在 8~18 附近，而实际动作在 0~45 之间跳变，模型未能跟踪动作变化趋势。 + +--- + +## 五、分场景效果预测 + +### 场景 A：当前预训练模型直接部署 + +**评级：不可用** + +- image_encoder 在零图像上训练，真实摄像头输入产生随机特征 +- 预测值被压缩到均值附近 ±15°，无法执行跳变动作 +- 扬声器频率预测几乎为 0 +- 预期表现：蜘蛛机器人缓慢无规律蠕动，无法完成有意义动作 + +### 场景 B：初步采集真实数据微调（~1K 帧，1-2 episodes） + +**评级：有限可用** + +- 450K 参数在 1K 帧上可学到基本运动模式 +- 平滑动作（站立→缓走）MAE ~15-25°/关节 +- 急变动作（跳跃、急转）MAE ~40-60°/关节 +- image_encoder 开始学习真实视觉特征 + +### 场景 C：充分数据采集（~10K 帧，10+ episodes，多场景） + +**评级：基本可用** + +- 平滑动作 MAE ~5-15°/关节 +- 急变动作 MAE ~20-40°/关节 +- 配合 noise_std 数据增强和早停，泛化可接受 +- SimpleCNN 表达力上限开始制约视觉理解 + +### 场景 D：场景 C + MobileNetV2 + 归一化动作 + +**评级：较好** + +- MobileNetV2 ImageNet 预训练权重提供强视觉先验 +- 归一化动作空间让 MSE loss 对各维度公平 +- 平滑动作 MAE ~3-8°/关节 + +### 场景 E：理想状态（~100K 帧，充分多样性） + +**评级：生产可用** + +- MAE ~1-5°/关节 +- 可完成绝大部分预设动作 + +--- + +## 六、核心瓶颈排序 + +| 优先级 | 瓶颈 | 严重度 | 说明 | +|--------|------|--------|------| +| 1 | 数据量 | 致命 | 77 行 / 13 文件，450K 参数 vs ~50 样本，样本/参数比 1:9000 | +| 2 | 零图像预训练的 image_encoder | 严重 | 47% 推理算力浪费在未训练的随机 CNN 上 | +| 3 | 动作空间异质性 | 中等 | dim 0-9 角度 [0-200°]、dim 10-11 频率/延时 [0-1000]、dim 12-17 全零，未归一化导致 MSE 被大数值维度主导 | +| 4 | 编舞脚本 vs 反应式行为 | 中等 | .mt 是预设动作编排，不含视觉反馈逻辑，模型学到的是 "动作惯性" 而非 "视觉→动作" 映射 | +| 5 | SimpleCNN 表达力 | 轻微 | 4 层 Conv 对细粒度空间信息编码不足 | + +--- + +## 七、量化预测总结 + +| 阶段 | 数据量 | 可用度 | 舵机 MAE | 能否完成预设动作 | +|------|--------|--------|----------|-----------------| +| 当前预训练 | 77 行 / 零图像 | 不可用 | >50° | 不能 | +| 初步采集 | ~1K 帧 | 有限 | 15-40° | 部分（简单动作） | +| 充分采集 | ~10K 帧 | 基本可用 | 5-20° | 大部分 | +| 充分 + MobileNet | ~10K 帧 | 较好 | 3-10° | 大部分 | +| 理想状态 | ~100K 帧 | 生产可用 | 1-5° | 绝大部分 | + +--- + +## 八、建议优先级 + +1. **最高优先**：实现遥操作/示教采集，尽快积累真实 (图像, 动作) 配对数据 +2. **高优先**：采集前开启 `--normalize-actions`，平衡各维度 loss 权重 +3. **中优先**：用真实数据微调后再评估，决定是否换 backbone +4. **低优先**：考虑预训练时冻结 image_encoder（减少无效梯度），或换恒等映射替代零图像 + +--- + +## 九、结论 + +actpred 模块架构设计合理，代码质量高，安全防护到位，推理速度满足实时需求。 +当前最大短板是 **数据量严重不足**（77 行零图像预训练），导致模型预测趋于均值、直接部署不可用。 +采集 10K 帧以上真实数据微调后，预计可达实用水平。 +模块已具备从 "实验原型" 向 "生产部署" 过渡的架构基础，下一步关键路径是 **数据采集 → 微调验证 → NPU 部署测试**。