硬件安全守卫xychendave/dsh-hardware-guard

DSH Hardware Guard

Agent、MCP、硬件安全契约与双机械臂的分层关系

面向 DeepSeek Harness 的物理硬件工具安全插件：审批、短时会话、并发限制、速率限制与可校验审计。

CI
License
DeepSeek Harness

DSH Hardware Guard 是一个独立社区插件，在 DeepSeek Harness 的工具执行管线中保护机械臂、实验仪器和其他物理设备。它可以包住官方 MCP Client 注册的硬件工具，但不修改 MCP Server，也不进入电机实时控制环。

本项目不是 DeepSeek AI 或 Anthropic 的官方项目，也不是官方 MHS 实现。

它解决什么问题

一个普通 MCP 工具可以叫 move_arm 或 write_device，但 MCP 本身不理解这个调用是否会引发真实运动。本插件在 Harness 内增加第二道策略边界：

- 读取、设备发现、规划和 dry-run 默认放行；
- 未分类的硬件工具默认拒绝；
- allowLive 默认关闭；
- 真实动作必须同时包含 apply=true 和 confirmed=true；
- 操作者需要先批准一个短时 live session；
- 每次真实动作仍需 Harness 的一次性人工批准；
- 同一设备默认只允许一个运动调用进行中；
- 限制 Agent 发起真实动作的速率；
- 急停调用不要求打开 live session，并立即关闭本地 session；
- 每次受保护调用写入 SHA-256 链式、可检测篡改的 JSONL 审计记录；
- 审计不可用时，新的真实动作 fail closed。

这些检查只是 defense in depth。关节限位、速度/扭矩限制、反馈看门狗、碰撞检查和物理急停必须由设备 Driver 或控制器强制执行。

架构

DeepSeek model
→ DeepSeek Harness
→ DSH Hardware Guard
├─ tool risk classification
├─ operator approval + short-lived session
├─ apply / confirmation / rate / concurrency guard
└─ tamper-evident audit
→ official @deepseek-ai/dsh-mcp-client
→ hardware MCP server
→ device-side safety supervisor
→ simulator or physical hardware

Harness 插件永远不应成为实时电机控制循环。高频轨迹应交给确定性控制器或本地策略执行。

兼容基线

当前版本针对以下上游版本测试：

- DeepSeek Harness 0.1.2-alpha.5
- @deepseek-ai/dsh-tools 0.1.2-alpha.5
- @deepseek-ai/cordis 4.0.2
- DeepSeek Harness commit 49a606bc5b5934603f22a26957a07dc799ab0291

Harness 仍处于预览阶段。精确版本记录见 upstream.lock.json。

安装

要求 Node.js 22.19+ 或 24+。

在已经安装 DeepSeek Harness 的项目中安装这个 GitHub 包：

npm install github:xychendave/dsh-hardware-guard#v0.1.1

也可以克隆后本地构建：

git clone https://github.com/xychendave/dsh-hardware-guard.git
cd dsh-hardware-guard
npm ci
npm run check

安全起步配置

把 examples/cordis.patch.yml 作为 Harness profile patch 加载。它只保护 mcp__rebot__，并保持 allowLive: false：

- insert:
- id: hardware-guard
name: dsh-hardware-guard
config:
allowLive: false
hardwareTools: ['mcp__rebot__']
auditPath: '.dsh/hardware-audit.jsonl'

在这个默认配置下，Agent 可以发现设备、读取状态、生成计划和提交 dry-run，但不能打开 live session，也不能执行 apply=true 的操作。

受监督的真实硬件流程

只有在 Driver 已完成单元测试、仿真、只读连接和 disabled-write dry-run 后，才把 allowLive 改成 true。

1. 操作者准备物理急停、固定设备并清空工作区。
2. Agent 调用 hardware_guard_status 检查本地状态。
3. Agent 调用 hardware_guard_open(reason="...")。
4. Harness UI 要求操作者批准，成功后得到一个默认五分钟的 session。
5. 动作工具必须提交 apply=true、confirmed=true。
6. Harness 再次要求操作者批准这一条具体动作。
7. 调用仍会经过 Driver 的校准、限位、碰撞和反馈健康检查。
8. 完成后调用 hardware_guard_close；任何急停调用也会关闭 session。

关闭 session 不会清除设备急停，也不会重新使能执行器。

默认风险分类

| 类别 | 默认行为 | 示例 |
|---|---|---|
| read | 放行 | discover、read、status、health |
| plan | 放行 | plan、preview、simulate |
| dry-run | 放行 | write 且 apply 不为 true |
| emergency-stop | 不要求 session；关闭已有 session | trigger_emergency_stop |
| motion | session + apply + confirmed + 单次审批 | write(apply=true)、move、enable、home |
| unknown | 拒绝 | 未配置的新硬件操作 |

clear/reset/release estop 被视为 motion，而不是急停；它不会获得无条件放行。

所有模式都可以通过 Cordis config 修改。新增硬件工具时，应先显式分类，再暴露给 Agent。

审计

默认写入 .dsh/hardware-audit.jsonl。每条记录包括：

- 工具名、调用 ID、风险类别和设备 ID；
- 是否请求 apply、是否带确认、session 是否有效；
- Harness 侧策略判断和最终错误状态；
- 已脱敏、限制大小的调用参数；
- 单调序号、前一条哈希和当前 SHA-256 哈希。

这是一份“可检测篡改”的本地日志，不是不可删除的远程账本。生产环境应把日志发送到权限隔离、追加写入的审计存储。

可以在代码中验证日志：

import { verifyAuditFile } from 'dsh-hardware-guard'

const result = await verifyAuditFile('.dsh/hardware-audit.jsonl')
if (!result.valid) throw new Error(result.error)

开发

npm ci
npm run typecheck
npm test
npm run test:loader

测试覆盖默认禁用真实动作、dry-run、未知操作 fail-closed、审批缺失、单调 Guard、急停关闭 session、同设备并发拒绝、审计脱敏和哈希链校验。

项目边界

- 不提供真实机械臂 Driver。
- 不包含关节、速度、扭矩或碰撞参数。
- 不把模型或 Harness 放入实时控制环。
- 不声称兼容尚未公开的 MHS 规范。
- 不允许提示词绕过设备端安全限制。

安全模型与设计选择见 Architecture、Threat model 和 ADR 0001。

License

Apache License 2.0。详见 LICENSE。