picoclaw/docs/design/current-hardware-support-and-serial.zh.md

当前硬件支持现状与串口 Tool 方案

现状结论

当前项目已有的硬件相关能力主要分为两条线：

1. 设备事件监控

   • pkg/devices 已实现设备事件服务。
   • 当前只有 Linux USB 热插拔事件源 pkg/devices/sources/usb_linux.go。
   • 能力定位是“发现和通知”，不是“总线读写控制”。

2. 硬件控制 Tool

   • pkg/tools/hardware/i2c*.go：I2C Tool，支持 detect、scan、read、write。
   • pkg/tools/hardware/spi*.go：SPI Tool，支持 list、transfer、read。
   • 这两类 Tool 当前都只在 Linux 主机上启用，直接依赖 /dev/i2c-* 与 /dev/spidev*。

因此，项目在“硬件支持能力”上已经具备：

• Linux USB 设备插拔感知
• Linux I2C 总线控制
• Linux SPI 总线控制

但还缺少：

• 串口/UART 控制
• macOS / Windows 下可直接使用的硬件控制 Tool
• 面向统一硬件抽象的跨总线能力模型

本次新增

本次新增内建 serial Tool，并接入现有 Tool 体系：

• 配置项：tools.serial.enabled
• Tool 注册：pkg/agent/agent_init.go
• Web 工具页：/api/tools 能展示与切换 serial
• 前端状态文案：新增 requires_serial_platform

Serial Tool 设计

serial 采用无状态调用模型，每次请求都自行打开和关闭端口，避免在 agent 回合之间维护串口会话状态。

支持动作：

• list：枚举主机串口
• read：从串口读取指定长度字节
• write：向串口写入字节或文本

公共参数：

• port
• baud
• data_bits
• parity
• stop_bits
• timeout_ms

当前波特率实现边界：

• Windows 允许配置工具层接受的范围 50-4000000
• Linux / macOS 当前仅支持标准 termios 波特率，实际支持到 230400
• 因此 baud 的跨平台可移植取值应优先使用 230400 及以下的常见标准速率

安全约束：

• write 必须显式传 confirm: true
• 单次读写负载限制为 4096 字节
• port 只接受白名单串口名：
  • Linux / macOS 仅允许 /dev/tty*、/dev/cu.* 及对应简写设备名
  • Windows 仅允许 COM\d+ 或 \\.\COM\d+
  • 明确拒绝 ..、普通文件绝对路径、盘符路径等非串口设备路径，避免路径穿越或误打开任意文件

跨平台实现边界

• Linux / macOS：

  • 基于 golang.org/x/sys/unix 和 termios 配置串口参数。
  • 当前仅接入标准 termios 波特率映射，最高到 230400，尚未扩展 460800、921600、1000000、2000000 等更高速率。
  • 通过 /dev/... 枚举和访问设备。

• Windows：

  • 基于 kernel32 串口 API 配置 DCB 和 COMMTIMEOUTS。
  • 当前读写仍使用同步 ReadFile / WriteFile；一旦 syscall 已进入执行，turn context cancellation 不能立即打断，只能等待 COMMTIMEOUTS 触发后返回。
  • 通过注册表 HARDWARE\\DEVICEMAP\\SERIALCOMM 枚举端口。

• 其他平台：

  • serial Tool 显式返回 unsupported，不做静默降级。

后续建议

1. 如果需要持续交互式串口会话，建议再增加 session 型 Tool，而不是让 LLM 反复做短连接轮询。
2. 如果后续要支持 CAN、GPIO、PWM，建议抽出统一的硬件 capability 描述层，而不是继续只靠 Tool 名称区分。
3. 若需要生产级稳定性，建议补真实串口回环测试，至少覆盖 Linux PTY 和 Windows COM 模拟场景。