---
description: 配置与设备模块的改动规则（site.yaml 分层、devices 布局、权重归位）
globs: config/**,devices/**,models/**,src/arm_interfaces/**
---

# 配置与设备改动规则

权威全文：`docs/FRAMEWORK_RULES.md` 第 1 节（R1.1–R1.5）。

## 配置分层

- 优先级固定：**命令行 > `config/site.yaml` > 包内默认值**。
- `config/site.yaml` 是站点数据（SN / IP / 序列号 / 锁高 / 权重路径），**不进 git**；
  改过它之后必须重跑 `python3 scripts/gen_site_example.py`，否则模板漂移
  （有一条 parity 测试会红）。
- **禁止硬编码站点值到代码里**。历史反例：15 处硬编码的 `Rizon4-063989`，
  换一台臂就会静默连错机器。
- 新增 `site.yaml` 键时二选一：**真的接线**，或在启动时**告警**。
  声明了却没接线、也不告警，是最难查的一类问题（用户改了配置毫无反应）。
  注意 `wired:` 只是 manifest 里的注释性约定，`arm_interfaces.manifest` 不解析它 ——
  保障要靠代码里的告警函数（如 `sim_site.unwired_warnings()`），别指望清单。

## 设备模块布局

```
devices/<kind>/<brand>/
├── manifest.yaml   # id/label/kind/vendor/version + assets + driver + capabilities + models + config_schema
├── driver/         # 与厂商 SDK 对接的实现（可替换）
└── models/<型号>/  # 该品牌的型号专属文件
```

- `kind` 用固定那几个（`robots`/`grippers`/`cameras`/`sensors`/`sim`），目录名要与
  `arm_interfaces.KIND_FOLDERS` 一致。
- **换品牌 = 新增目录**，不是改现有目录；上层按 `manifest.yaml` 选型，不认品牌名。
- `assets[]` 里标 `required: true` 的物料缺失时，报错信息要给出**格式与命名要求**，
  不能只说"文件不存在"。

## 权重

- 二进制（`.pt/.onnx/.engine`）**不进 git**，`.labels.yaml`（文本标签）**要进**。
- 转换链：`models/staging/` → `weights.sh convert` → 自动改名归位 + 固化标签。
- 配置里指向不存在的模型（悬空引用）必须修掉：`bash scripts/weights.sh doctor`。