P5a 框架规则文档：M1-M3 元规则 + R1-R6 分领域规矩 + 反例清单
背景：这个框架踩过的坑几乎都是同一类——"没报错但结果是错的"。
之前这些教训只存在于聊天记录和零散注释里，改一次代码就要重踩一遍。
现在收敛成一份可引用的文档，并压缩成 .cursor/rules/ 常驻规则。
docs/FRAMEWORK_RULES.md（414 行）
第 0 节 三条元规则：M1 静默失效是头号敌人 / M2 单一数据源 / M3 口径必须显式
第 1 节 配置与数据 R1.1-R1.5（分层优先级、site.yaml 新键必须接线或告警、设备走 devices/、权重走 models/）
第 2 节 几何/单位/坐标系 R2.1-R2.7（米与弧度、frame_id 必须是光学系、深度 mm↔m、
rpy=Rz·Ry·Rx、Gazebo camera_info 不可信、像素门槛绑图幅、位姿容差要写理由）
第 3 节 触觉与力 R3.1-R3.6（力是相对基线的增量、fnormal 压为正、轴向映射必须实测、
接触布尔要用超时、force_scale 口径、仿真图像只能占位）
第 4 节 仿真 R4.1-R4.10（唯一 site.yaml、world 里写 plugin 会挤掉默认系统、搜索路径要在
launch 前设好、上游 description 不许改、场景走 scene.yaml、校验要逐碰撞体、
不用"有话题就算通"验收、停仿真用 stop_sim_gz.sh）
第 5 节 代码与测试 R5.1-R5.7（纯逻辑抽纯函数、校验要有测试证明有效、不许把降级写成通过、
解析外部输出先确认真实格式、删除前扫全仓库引用、别在中文路径 colcon build、真机仿真产物隔离）
第 6 节 文档与提交 R6.1-R6.4（文档与实现不一致立刻修文档、每份文档说明记录什么事实、
结论数字要可复现、提交信息讲为什么并附实测数据）
第 7 节 改动前检查清单
第 8 节 历史反例清单——按"你看到的症状"查表，不是按道理排序
第 9 节 给 AI 的具体指令
.cursor/rules/*.mdc 三份压缩版（常驻）
framework-core.mdc alwaysApply，元规则 + 检查清单 + 禁止项
sim-gazebo.mdc globs=devices/sim/**,src/arm_sim_gazebo/**
config-and-devices.mdc globs=config/**,devices/**,models/**,src/arm_interfaces/**
顺手修掉文档与实现不一致（R6.1）
docs/WORKSPACE.md 此前【完全没有 devices/ 这一层】——通用化落点却没进目录总表。
补 devices/ 一节（kind/brand 目录约定、registry.yaml 与 manifest.yaml 分工、
assets[].required 缺失会报错），补 build_sim/install_sim/log_sim 与 .cursor/rules/，
并把 FRAMEWORK_RULES.md 标为 docs/ 首行
README.md 文档表首行加 FRAMEWORK_RULES.md
顺手删死代码（R5.5：先扫引用）
src/arm_interfaces/arm_interfaces/paths.py 删 assets_root()
它返回 ros2_root()/"assets"，而仓库里从来没有 assets/ 这个目录——实际权重树是 models/，
且 models/ 的定位已由 arm_application.weights_layout.default_weights_root() 负责
（带 SITE_WEIGHTS_ROOT 覆盖，且能从 install/ 反查仓库根）。
两个实现并存违反 M2，且这个还指向不存在的路径，属于"照着名字用就踩空"。
src/arm_interfaces/test/test_real_devices.py 从清环境变量列表里去掉 SITE_ASSETS_ROOT
验收
src/arm_application 233 passed / arm_driver_flexiv 69 / arm_interfaces 46 /
arm_kinematics 24 / arm_sim_gazebo 236 = 608 passed
（flexiv_rdk 的 test 需装厂商 flexivrdk 包，仿真环境无此依赖，与本改动无关）
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
arm_dev
+34
-2
@@ -15,20 +15,51 @@
|
||||
| 路径 | 进 git？ | 做什么 |
|
||||
|------|----------|--------|
|
||||
| `README.md` | 是 | 克隆后怎么跑 |
|
||||
| `docs/` | 是 | 说明文档（本文件是目录总表） |
|
||||
| `docs/` | 是 | 说明文档（本文件是目录总表）；**规矩在 [`FRAMEWORK_RULES.md`](FRAMEWORK_RULES.md)** |
|
||||
| `config/site.example.yaml` | 是 | 现场配置模板 |
|
||||
| `config/site.yaml` | **否** | 本机 SN / IP / 相机 / 锁高 |
|
||||
| `config/fastdds_visual_servo.xml` | 是 | 可选 FastDDS；默认不用 |
|
||||
| `scripts/` | 是 | 唯一操作入口 |
|
||||
| `src/` | 是 | ROS 2 包源码 |
|
||||
| `devices/` | 是 | **设备模块树**（机器人/夹爪/相机/传感器/仿真），见下节 |
|
||||
| `handeye/` | 目录是；`tmp/` 内容 **否** | 手眼标定配置 / 采点 / 结果，见 `handeye/README.md` |
|
||||
| `models/` | 目录与 `.labels.yaml` 是；权重二进制 **否** | 算法权重模块，见 `models/README.md` |
|
||||
| `build/` `install/` `log/` | **否** | `colcon` 产物，本地编译生成 |
|
||||
| `build/` `install/` `log/` | **否** | 真机环境的 `colcon` 产物 |
|
||||
| `build_sim/` `install_sim/` `log_sim/` | **否** | **仿真环境**的产物（`scripts/build_sim.sh`）。两套并存是刻意的：同一份源码、两个环境的依赖路径不同，共用 `install/` 会互相覆盖 |
|
||||
| `.cursor/rules/` | 是 | 给 AI 的常驻规则（`FRAMEWORK_RULES.md` 的压缩版，权威仍是那份文档） |
|
||||
| `thirdparty/` `vendor/` | **否** | 可选离线 RDK / Isaac 克隆 |
|
||||
| `.gitignore` | 是 | 上面「否」的规则 |
|
||||
|
||||
---
|
||||
|
||||
## `devices/` — 设备模块树（换品牌 = 加目录，不改代码）
|
||||
|
||||
这一层是"通用化"的落点：上层按 `manifest.yaml` **选型**，不认具体品牌名。
|
||||
所以换一台机器人/夹爪/相机/传感器，是**新增一个 `<品牌>` 目录**，
|
||||
而不是改现有目录或改应用代码。
|
||||
|
||||
```
|
||||
devices/<kind>/<brand>/
|
||||
├── manifest.yaml # id/label/kind/vendor/version + assets + driver + capabilities + models + config_schema
|
||||
├── driver/ # 与厂商 SDK 对接的实现（可替换）
|
||||
└── models/<型号>/ # 该品牌的型号专属文件
|
||||
```
|
||||
|
||||
| kind | 现有品牌 | 说明 |
|
||||
|------|----------|------|
|
||||
| `robots/` | `flexiv` | Flexiv Rizon / AICO（RDK） |
|
||||
| `grippers/` | `dh_pgea` | 大寰 PGEA 平行爪 / RGI 旋转爪 |
|
||||
| `cameras/` | `realsense` | Intel RealSense D405 / D435 |
|
||||
| `sensors/` | `orisys` | Orisys 视触觉（三向力 + 深度图 + 力矢量图） |
|
||||
| `sim/` | `gazebo` | Gazebo 物理仿真平台，手册见 `devices/sim/gazebo/README.md` |
|
||||
|
||||
`devices/registry.yaml` 声明"本仓库装了哪些品牌"；`manifest.yaml` 里
|
||||
`assets[].required: true` 的物料缺失时框架会报错，并给出**格式与命名要求**。
|
||||
|
||||
> 选型与接线细节见 [`FRAMEWORK_RULES.md`](FRAMEWORK_RULES.md) 第 1 节（R1.3）。
|
||||
|
||||
---
|
||||
|
||||
## `config/` — 现场配置
|
||||
|
||||
| 文件 | 作用 |
|
||||
@@ -147,6 +178,7 @@
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `FRAMEWORK_RULES.md` | **框架规则**（硬规矩，改代码前先读；第 8 节是按症状查的反例表） |
|
||||
| `WORKSPACE.md` | 本页，目录与职责 |
|
||||
| `QUICKSTART.md` | 环境、编译、第一次实机 |
|
||||
| `ARCHITECTURE.md` | 进程与数据流 |
|
||||
|
||||
Reference in New Issue
Block a user