 arm_dev
|
bda2fa7129
|
通止规装配：配置段进 site.yaml + 中文手册 + 成败判定「不看 $?」
配置（site.yaml → gauge_assembly:，38 键全部带中文注释）
------------------------------------------------------
- 键名/单位/类型/交叉矛盾由 gauge_config.py 校验：拼错键名报错并给最相近的候选，
单位后缀（_deg/_mm/_m/_s/_pct/_delta）逐条对表，`contact_safe_delta ≤
contact_tangential_delta` 这类矛盾启动就拦（R1.2：没接线的键不许静默存在）。
- 借机清掉 4 个**没接线**的键（require_preview / track_*_s / hover_m：前两个是
stage1 那层的、后两个是 servo 那层的，放在这里等于第二份真相），
并把 contact_speed_m_s / coarse_timeout_s / 夹爪力速 真的接上。
- site.example.yaml 由 site.yaml 生成（gen_site_example.py --check 通过）。
成败判定：`ros2 launch` 的退出码**恒为 0**
------------------------------------------
实测（Humble）：子进程 exit 3，`ros2 launch` 仍返回 0。用 `$?` 判成败的脚本会把
"装配失败"记成"成功"——没人会去查一个说成功的脚本。改成：
- 节点把结论**落盘**（--result-file，默认 /tmp/gauge_assembly_result.json，原子写、
先落盘再发话题），任何"没跑到收尾"的退出也会补一份 ok=false；
- 脚本读结论文件判成败：0=成功、1=失败、**文件不存在也算失败**并说清；
- 新增 test_gauge_result_gate.py：把脚本里那段判成败的 Python 抽出来，
对成功/失败/干跑/缺文件/坏 JSON 五种输入断言退出码 —— 判据本身也有测试。
顺带修掉两个"看着像玄学"的现象
------------------------------
- **流程打完了终端不回提示符**：launch 里的静态 TF 发布者是常驻的，主节点退出
带不走它 —— 挂 OnProcessExit → Shutdown。
- **"已装 1/2 孔"**：结果里 hole_index 是 0 基当前孔号，不是"装完几个"，
新增 holes_done 给人和脚本看。
文档（全部中文，含"怎么调参/还没做"）
------------------------------------
- 新增 docs/GAUGE_ASSEMBLY.md：状态机全图、每步判据表、E1 掉件处理（**按实现**：
掉件后该孔作废、换下一个孔；最后一个孔掉件则序号被夹住=重试本孔）、
话题契约、调参顺序、验收命令、踩过的坑。
- FRAMEWORK_RULES 新增 R5.8（同一份数学只许一份 + 守卫测试）、R5.9（自检的
期望类型与调用处同源）、R5.10（缺依赖 skip，别留常年红）、R6.9（硬退出前打
traceback）、R6.10（ros2 launch 退出码恒 0）＋ R5.7 补真机/仿真"生效方式不同"
（真机软链即改即生效，仿真拷贝必须重编）＋ 5 条症状反例、.cursor/rules 同步。
- WORKSPACE / INTERFACES / SITE_CONFIG / HANDBOOK / 两份 README 索引与决策表补齐。
验证（本机真跑）
----------------
pytest（仿真环境） 436 passed, 14 skipped（缺 onnx 跳过）
干跑 --sim --dry-run → 脚本退出码 0，结论 ok=true 已装 2/2 孔
不干跑 --sim → 脚本退出码 1，S00 拦住，未发任何运动指令
Co-authored-by: Cursor <cursoragent@cursor.com>
|
2026-09-24 10:30:11 +08:00 |
|
|
arm_dev
|
fac2d5384d
|
P5b 新手手册：这台机器在干什么 / 改哪里 / 怎么验 / 出问题查哪
此前仓库有规则文档（FRAMEWORK_RULES）、有目录表（WORKSPACE）、有各模块说明，
但**缺一份"从零进来的人读什么"**：业务目标没有一处讲清（"通止规装配"散落在
7 个文件里各提一句），测试怎么跑在 docs/ 里一次都没写过，改一个东西该动哪个文件
要靠翻源码猜。
docs/HANDBOOK.md（416 行，新增）
1. 这台机器在干什么 —— 通止规是检验螺纹的量具（通端应旋到底、止端应旋不进）；
为什么值得自动化（留下可追溯的力曲线）；三段主线的数据流；日志三行判进度。
★ 1.4 节是**承诺书**：逐项标 ✅/⚠️/❌，并给出"哪条命令能证明它已就绪"。
如实写明还没做的四项：自动拉起全部服务、夹爪持规自检、D435 手眼标定、
装配合格判定。指不出验证命令的，就老实标 ❌（R6.1）。
2. 系统长什么样 —— 三层各有硬边界；两块**独占资源**（RDK、D405 USB）
以及各自的冲突表现；从像素到关节的全链路加上"每步的口径写错会怎么表现"。
3. 我要改东西，改哪里 —— 决策表（改 X → 动 Y → 用 Z 验），覆盖换臂/悬高/夹爪/
入孔/触觉/相机/仿真场景/权重/新品牌设备/命名位姿。每行都外链权威文档，
不复制内容（M2）。
4. 怎么验 —— 三层验收（不报错不算验收 / 物理量命中真值 / 任务成功）+ 命令清单 +
**单元测试怎么跑**（此前 docs/ 里没有任何一处写过）。含 608 项分包清单。
4.4 节专讲"验收工具自己也会失效"，把 M1/R5.3/R6.6 串成一条线。
5. 出问题按现象查 —— 三处权威文档的分工表 + 15 行"现象 → 先怀疑什么"，
覆盖 8 条仿真坑与全部触觉坑（坑 1/2/5/6/7/9/10）。
6. 术语表 + 未做的事（按优先级）+ 往下读的路线。
顺带写进规则的（docs/FRAMEWORK_RULES.md）
R6.7 验收命令必须真跑过 —— 本仓库已经因此踩过两次（CRLF 死脚本被五处文档推荐）
R6.8 install/ 构建产物会互相污染 —— 见下面这个发现
第 7 节清单加两条（第 10 条真跑过命令、第 11 条构建环境对不对）
第 8 节反例表加三行症状
★ 顺带发现一个哑弹（R6.8，**已记录未修**）
colcon build 会把当时激活的那个 python 的绝对路径写进每个入口脚本的 shebang。
实测：install/ 里 31/59 条指向仿真环境 ros_gz_sim，install_sim/ 里 31/55 条
（后者是对的）—— 说明真机 install/ 是在仿真 conda 环境里构建出来的，违反 R5.7。
$ head -1 install/arm_interfaces/lib/arm_interfaces/device_check
#!/home/cc/anaconda3/envs/ros_gz_sim/bin/python3.11
为什么现在没炸：两个 conda 环境的 Python 依赖当前完全相同（pyrealsense2 / serial /
cv2 / numpy / torch / ultralytics / tensorrt 都在），指错了也照样 import 成功。
这是一颗哑弹 —— 哪天某个环境多装或少装一个包，真机栈就会以"模块找不到"的形式炸，
而人是不会想到去查 shebang 的。
修法（写进 R6.8，待执行）：在真机 conda 环境里重建 install/，再
`grep -l ros_gz_sim install/*/lib/*/* | wc -l` 应当变成 0。
预防：构建脚本开头应断言当前 conda 环境与目标一致（待补）。
验收
- 文档内所有相对链接与反引号路径引用均存在（脚本检查，0 坏链）
- 文档里给的每条命令都实际执行过：
ros2 run arm_interfaces device_check 通过
device_check --list-brands 列出 5 类设备
scripts/show_site_config.sh 存在
check_sim_cameras.py / check_sim_scene.py / check_text_only.py 存在
for d in src/*/test ... pytest 循环 608 passed
- 单测 608 passed，与改动前一致（本次只改文档）
Co-authored-by: Cursor <cursoragent@cursor.com>
|
2026-09-24 09:05:09 +08:00 |
|
|
arm_dev
|
72353f3773
|
注释与提示信息全面中文化：源码 66 个 .py + 脚本/配置 45 个文件
背景：现场读代码的人只读中文。此前代码里的 docstring 是英文、行内注释是中文，
一半英文一半中文反而更难看懂 —— 新手打开一个 .py 不知道这个模块为什么存在。
范围（本仓库自己的代码，厂商上游不动）
src/arm_application/** 37 个文件：servo_node / perception_node / handeye_* / dh_pgea /
yolo_detector / kalman_filter / goto_ee_plane / dual_gripper …
src/arm_interfaces/** 11 个文件：paths / manifest / loader / config_guard / errors …
src/arm_control/** 5 个文件
src/arm_bringup/** 3 个 launch
scripts/** 6 个 .py + 29 个 .sh（scripts/ 是"唯一操作入口"，用户屏幕上
看到的就是这些提示，所以提示信息也一并中文化）
config/ handeye/ devices/ src/arm_*/config/ 17 个 .yaml/.xml/.xacro/.cfg
口径（写进 docs/FRAMEWORK_RULES.md 新增的 R6.5，作为长期约束）
注释、docstring、print/日志/异常里给人看的句子 = 中文；
标识符、API 名、话题名、参数名、字段名、命令名 = 保留英文原文（用 `` `` 包起来）；
单位、十六进制、协议报文、CRC 值、命令示例 = 原样保留；
src/flexiv_*/ = 厂商上游代码，不许改也不许翻译（R4.4）。
翻译保原意与原有详细程度：那些"为什么不能用另一种做法""踩过什么坑"的说明
全部完整保留 —— 它们才是这份代码里最贵的部分。
新增 scripts/check_text_only.py：只改文字时的自证工具
人工 review 靠不住（115 个文件、3000 多行 diff）。这个脚本把改动前后的源码解析成
语法树，删掉 docstring、抹平字符串常量、把 f-string 只留"插值了几次 + 插值是什么"，
再比对：完全相同 = 改动范围内没有逻辑变化。
留了一个口子：f-string 的插值按内容排序后再比 —— 因为中文语序常常要和英文反着来
（f"on {port} read {idx} failed" → f"在 {port} 上读 {idx} 失败"），只换显示顺序不该判失败；
但多插一个、少插一个、换掉被插入的表达式，立刻会报出来。
本次 66 个 .py 全部通过该闸门。
验收
改动的 66 个 .py：scripts/check_text_only.py 全部通过（零逻辑变化）
45 个非 .py 文件：去注释后与 HEAD 逐字节相同（零配置变化）
docstring 总数：没有一个文件减少（不存在"翻译时顺手删了说明"）
单测：arm_application 233 / arm_driver_flexiv 69 / arm_interfaces 46 /
arm_kinematics 24 / arm_sim_gazebo 236 = 608 passed，与改动前一致
全部 .sh：bash -n 通过；并额外实际执行了 --help 验证（见下一个提交：
bash -n 对 CRLF 脚本会漏报，只有真跑才暴露）
Co-authored-by: Cursor <cursoragent@cursor.com>
|
2026-09-23 17:40:55 +08:00 |
|
|
arm_dev
|
d78e66ce98
|
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>
|
2026-09-23 17:16:47 +08:00 |
|