docs: 新增 actpred 效果评估报告，移除 INDEX.md

2026-08-09 18:38:24 +00:00
1 parent 6089e7427d
commit 26c91c6036
@@ -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/) |
@@ -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 部署测试**。