Uni-Lab-OS/.cursor/skills/validate-device/SKILL.md

name, description

name

description

validate-device

Validate Uni-Lab-OS device or workstation implementations against interface contracts and project rules. Use when users ask to validate device code, audit compliance, check contract compatibility, review registry alignment, or mention 验证设备/检查设备/设备审计/接口对齐/device validation/check compliance/audit device/workstation validation. Prioritize docs/ai_guides/add_device.md and unilabos/registry/devices/ as validation baselines.

设备合规验证 (Device Validation)

验证设备实现是否符合 Uni-Lab-OS 的接口契约和编码标准。

第一步：确定验证目标

先确定验证范围：

• 单文件：unilabos/devices/.../*.py
• 同类别批量：如 pump_and_valve、temperature
• 自动检测：用户刚改动设备代码时，从上下文与 git 变更推断目标

第二步：读取必要文件（按优先级）

使用 ReadFile 工具读取以下文件，并按优先级作为验证基线：

1. 设备实现文件 - 待验证的 Python 设备类
2. 对应的 YAML 注册表 - unilabos/registry/devices/ 下的对应文件
3. 设备接入指南 - docs/ai_guides/add_device.md（权威规则与接口快照）
4. CLAUDE.md / AGENTS.md - 项目规则（关键硬约束）
5. 同类设备参考 - unilabos/registry/devices/ 中同类别设备（优先最新仓库内容）

如果规则冲突，优先级为：仓库当前注册表与 add_device.md > CLAUDE.md/AGENTS.md 中通用约束 > 历史示例。

第三步：执行验证检查

按顺序执行并记录证据（文件路径 + 关键信息）：

检查 1：参数名契约验证

规则： 动作方法的参数名是接口契约，不可重命名。

检查内容：

• 扫描公开动作方法（不以 _ 开头）
• 从 YAML action_value_mappings 提取动作参数名
• 对比 Python 方法签名参数名是否完全一致（不能改名）

检查 2：status 字符串一致性

规则： status 字符串必须与同类已有设备一致。

检查内容：

• 收集 self.data["status"] 所有赋值
• 对比同类设备与注册表中的标准值
• 标记中文状态、大小写不一致和自定义状态

检查 3：self.data 初始化完整性

规则： self.data 必须在 __init__ 中预填充所有属性字段。

检查内容：

• 检查 __init__ 中 self.data 初始化
• 提取 @property 与 YAML status_types 字段
• 校验 self.data 已预填充全部字段，且不是空字典

检查 4：异步 sleep 使用规范

规则： 异步方法中使用 await self._ros_node.sleep()，禁止 time.sleep() 和 asyncio.sleep()。

检查内容：

• 扫描所有 async def
• 禁止：time.sleep(...) / asyncio.sleep(...)
• 正确：await self._ros_node.sleep(...)

检查 5：YAML 与代码接口对齐

规则： 设备实现必须与 YAML 注册表定义的接口完全匹配。

检查内容：

• 属性对齐：status_types 字段都有对应 @property
• 动作对齐：action_value_mappings 中非 auto- 动作都有实现
• 返回值检查：优先 bool 或 Dict[str, Any]

检查 6：串口响应解析健壮性（按需适用）

规则： 禁止用硬编码索引解析串口响应，必须先定位帧起始标记。

检查内容：

• 仅在存在串口/二进制协议代码时执行
• 禁止直接按固定索引解析原始响应
• 必须先定位帧起始标记（如 /、0xFE）

检查 7：代码质量检查（补充项，不计入强制合规）

可选检查项：

• 是否有 post_init 方法接收 ros_node
• 是否有 initialize 和 cleanup 方法
• 类型转换：参数是否显式转换（float(temp)、int(position)）
• 错误处理：是否有基本的异常捕获
• 日志记录：是否使用 self.logger

第四步：生成合规报告

使用以下结构输出（简洁、可执行）：

# 设备验证报告

**设备：** unilabos/devices/pump_and_valve/my_pump.py
**类名：** MyPump
**类别：** pump_and_valve
**验证时间：** {{date}}

## 总体评分（仅统计适用检查）

- ✅ 通过检查：5/6（Applicable）
- ❌ 失败检查：1/6
- ⏭️  跳过检查：1 项（Not Applicable）
- ⚠️  警告：3 项

## 详细结果

### ❌ 必须修复（Blocking）
1. [检查名] 问题描述（文件与位置）
   - 当前：`...`
   - 应改：`...`

### ⚠️ 建议修复（Non-blocking）
1. [检查名] 问题描述（文件与位置）
   - 建议：`...`

### ✅ 通过项
- 检查 1：...
- 检查 3：...

## 结论

该设备实现存在 **N 个必须修复问题**。修复后复检。

第五步：询问是否自动修复

如果发现了问题，询问用户：

发现了 2 个必须修复的问题。是否需要我自动修复这些问题？

选项：
1. 自动修复所有问题
2. 仅修复高优先级问题
3. 手动修复（我会提供详细指导）
4. 仅查看报告，不修复

如果用户选择自动修复，使用当前环境可用的编辑工具（优先 ApplyPatch）逐个修复问题，并在修复后重新验证。

注意事项

1. 不要过度严格 - 某些警告可能是合理的设计选择，询问用户确认
2. 提供上下文 - 解释为什么某个规则很重要
3. 批量验证 - 如果验证多个设备，提供汇总报告
4. 版本兼容 - 旧设备可能使用旧的约定，注意区分

常见问题

Q: 如果找不到对应的 YAML 文件怎么办？ A: 提示用户可能需要先创建 YAML 注册表，或者仅执行不依赖 YAML 的检查（如 status 字符串、async sleep）。

Q: 如果设备是工作站（workstation）怎么办？ A: 工作站有不同的验证规则，检查是否继承自 WorkstationBase，是否有 deck 配置等。

Q: 如何处理虚拟设备（mock）？ A: 虚拟设备可以放宽某些要求（如串口解析），但接口契约仍需遵守。

触发示例

用户可能这样说：

• "验证一下这个设备代码"
• "检查 my_pump.py 是否符合规范"
• "这个设备实现有什么问题吗"
• "帮我 audit 一下设备接口"
• "检查设备合规性"
• "validate device implementation"
• "验证这个 workstation 是否合规"
• "帮我检查设备实现和 registry 是否对齐"
• "做一次设备接口审计"