前言¶

DeepSeek Harness（dsh）把模型、工具、技能、会话和界面都做成插件，官方说法是「Everything is a plugin」。对写代码的智能体来说，装一个搜索或视觉插件就能立刻干活；对机器人、具身智能这条线，缺口更具体：URDF 对不对、仿真有没有跑通、抓取失败到底是感知偏了还是吸盘打滑，证据往往散落在 CAD 文件、MuJoCo 日志和几张曲线图里，Agent 很难把它们收进同一次工作流。

dsh-robotic-harness 就是冲着这件事来的。它是社区维护的 DSH 插件，把机器人资产检查、MuJoCo 抓取放置仿真、故障注入和带哈希的证据包接到 Agent 循环里。本文按插件目录页、GitHub 仓库 README / 中文说明、docs/demo.md、docs/safety-boundary.md 以及 DeepSeek Harness 官方仓库交叉核对后整理：它是什么、能做什么、怎么装、怎么跑 Demo，以及当前明确做不到的事。

需要先说清楚两件事。DeepSeek Harness 本身是 DeepSeek AI 的开源 Agent 运行时；本文介绍的插件来自维护者 dingkaihu63 的社区仓库，许可证写明与 DeepSeek 官方无隶属关系。插件目录站点 deepseek-harness-plugin.com 是独立的社区索引，不是 DeepSeek / 幻方的官方应用商店。

这是什么¶

dsh-robotic-harness（仓库里也叫 Robotic Harness）是一款面向 DeepSeek Harness 的具身智能研究工具，目录分类为「工具与能力」，由 dingkaihu63 维护。可安装包名是 @robotic-harness/dsh-bundle，当前版本 0.1.0，许可证 MIT，主要语言 Python。目录页一句话概括是：机器人资产检查与 MuJoCo 抓取放置仿真。GitHub 仓库当前 13 星（目录页收录时显示 12 星）。

它要解决的问题很直接：把下面几件事放进同一个 Agent 工作流，而不是在仿真器、脚本和报告之间来回拷文件。

• 检查 URDF / MJCF / SDF 这类机器人资产
• 跑 MuJoCo 抓取放置仿真，并可按固定 seed 注入故障
• 用规则引擎收集事实、规则判定和候选根因
• 导出带 sha256 清单的证据包、Markdown 报告和可离线打开的时间线

架构上，DSH 侧注册一批 rh_* 工具和若干 Skill；真正干活的是随包分发的 Python worker（python -m robotic_harness_worker --input -），通过 stdio 一次性进程调用。Run、遥测、图表默认写到工作区的 .rh/ 目录。一次性进程的目的是崩溃隔离：worker 挂了，不会把 dsh 进程一起带走。

仓库 README 把当前状态标成 Demo 阶段。作者写明：目前只在有限本地环境验证过（Windows + Anaconda Python 3.10 + DSH 0.1.0-rc.6）；ROS 2、CAD、真机以及其他操作系统 / 硬件环境尚未充分试验。徽章上写了 Windows / Linux / macOS，那是目标平台声明，不能当成已经全面测过。

核心功能¶

仓库 README 把工具面写成约 110 个 rh_* 工具，覆盖十多个领域。下面只写已经在 README 和 Demo 文档里核对过的能力，不把路线图里的愿景当成现成功能。

资产检查¶

面向 URDF / MJCF / SDF：检查、惯量与拓扑校验、网格统计、SVG 预览、URDF 转 MJCF、SDF 兼容导出，以及 CAD 清单与版本对比。代表工具包括 rh_robot_asset_inspect、rh_urdf_validate、rh_urdf_to_mjcf、rh_sdf_validate、rh_mesh_inspect、rh_inertia_validate。SolidWorks 文件目前只登记进清单，不解析（商业软件）。

MuJoCo 抓取仿真与故障注入¶

内置 Demo 场景是平面 3 自由度机械臂加吸盘：桌上红色方块抓取后放到目标区。场景用几何基元搭建，不依赖外部网格。仿真侧提供 rh_sim_run、rh_sim_fault_inject、批量基准、只读回放，以及仿真与真机差距报告（真机证据目前并不存在，见后文限制）。

故障注入是确定性的、seed 可控，文档列出 6 种：

• perception_offset_px：感知像素偏移
• gripper_slip：夹持 / 吸盘滑落
• tf_offset：坐标变换偏移
• sensor_noise：传感器噪声
• model_timeout_s：模型超时
• occlusion：遮挡

感知路由是：先走颜色分割（延迟低），失败或遮挡时再走通用显著度分割，并把路由原因记下来。

诊断、证据和报告¶

遥测包括关节目标 / 实际 / 误差、吸盘状态、物体位姿、感知估计与真值，以及场景渲染图。诊断走确定性规则引擎，输出分三层，文档要求不要混着读：

1. 事实：带时间戳的数值，例如感知估计与真值差了多少毫米
2. 规则判定：阈值或状态机触发的发现
3. 候选根因：按感知 / 标定 / 机械 / 控制 / 系统分层，标注可能性与缺失证据

最终结论留给人。证据包是自包含的：manifest.json（文件列表 + sha256 + 环境快照）、遥测、图表，再加 Markdown 报告和单文件 timeline.html（浏览器直接打开，不需要再起服务）。

其它已实现、但后端可能缺失的模块¶

README 把实现状态分成两类：

• 纯软件模块：资产、仿真、控制、视觉、模型、诊断、遥测、数据、实验、知识、文献、训练等，文档称完整且有测试（README 徽章写 274 项测试通过）。
• 后端依赖模块：ROS 2 实机探测、SolidWorks 解析、真机适配器、重型 VLA。后端不在时返回结构化 backend: "unavailable"，并附安装指引，不假装通过。rosbag2 的检查与转换不需要安装 ROS。

真机相关工具目前是 preflight 清单加实验状态机：没有硬件适配器时，真机项如实标 skip。docs/safety-boundary.md 写得更硬：当前版本 不包含 真机硬件适配器、真机写工具或任意 Topic 发布；也不提供急停解除。仿真通过不能写成真机安全。

安装与启用¶

目录页给出的安装命令如下，在 DeepSeek Harness 终端里运行即可。以页面原文为准，不要自己拼仓库名。

dsh plugin add github:dingkaihu63/dsh-robotic-harness

需要可复现安装时，把 commit 哈希钉死（把 commit 换成实际哈希）：

dsh plugin add github:dingkaihu63/dsh-robotic-harness#commit

目录页同时提示：插件以当前 dsh 进程的权限运行，安装时可能执行代码。安装前应检查源代码仓库和许可证。

仓库自己的安装说明更细，要求：

• DSH CLI：@deepseek-ai/dsh ≥ 0.1.0-rc.6
• pnpm
• Python 3.10 环境（推荐 Anaconda 的 python3.10，并安装 mujoco、numpy、opencv-python、matplotlib、pytest）

从本地 clone 安装 bundle 的写法是：

git clone https://github.com/dingkaihu63/dsh-robotic-harness.git
cd dsh-robotic-harness

# 示例：指定 profile 后从本地包安装
dsh plugin --profile rh-demo add ./packages/dsh-bundle

README 还要求在 profile 的 cordis.patch.yml 里把 rh-tools.pythonPath 指到你的 Python 3.10 解释器。它特别注明：patch 会整行替换配置，需要把该行其它键一并重写，不能只改一个字段。安全文档把 pythonPath 标成受信配置：worker 用这个解释器执行随包代码，改它等于信任任意代码执行。

启用 Web UI 时，仓库记录了一个已知坑：上游 npm 上的 @deepseek-ai/dsh-web-app 依赖私有包 @deepseek-ai/dsh-frontend，直接 pnpm add 会 404。作者给出的变通是编辑 $DSH_HOME/profiles/rh-demo/package.json，把内置 bundle 写成从 dsh 安装目录解析，例如：

dsh.profile.bundles = ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@robotic-harness/dsh-bundle"]

文件需保存为 UTF-8 无 BOM。然后用空闲端口启动，README 示例用 3090，避免和 DSH 默认的 3080 冲突：

dsh --profile rh-demo --port 3090

也可以从 tarball 安装：dsh plugin add ./robotic-harness-dsh-bundle-0.1.0.tgz。npm 发布后的安装方式仓库写了「once published」，当前 package.json 版本仍是 0.1.0，是否已上 npm 以当时注册表为准，这里不写成已经能 pnpm add。

典型用法¶

下面两套路径都来自仓库文档，可以按原文复现。一套不依赖 DSH，一套走 Agent。

1. 不装 DSH，先跑通 Python Demo¶

要求 Python ≥ 3.10，以及前面列出的依赖。

git clone https://github.com/dingkaihu63/dsh-robotic-harness.git
cd dsh-robotic-harness

# 测试按文件分进程跑，避开 mujoco / cv2 / pyarrow 的原生库冲突
cd python && python run_tests.py && cd ..

# 端到端 Demo：正常 Run + 故障 Run + 诊断 + 证据包 + 报告 + 时间线
PYTHON=<你的 python3.10> node scripts/demo.mjs

docs/demo.md 写明 Demo 会依次做：

1. 正常 Run（seed 42，无故障），期望 success: true，物体落在目标区 [-0.16, 0, 0.17] ± 0.05
2. 故障 Run（seed 43，同时注入 perceptionOffsetPx [18,6]、gripperSlip、tfOffset [0.015, 0]），期望 success: false，异常含 grasp_missed / gripper_slip
3. 每个 Run 做规则诊断、导出证据包、生成 Markdown 报告和 timeline.html
4. 文献检索与训练流默认离线安全：train-job-prepare 是 dry-run，只生成本地产物；网络不可用时文献检索返回 backend:"unavailable"，不伪造论文

产物默认在 examples/demo-output/：

故障 Run 的诊断示例（来自 docs/demo.md，不是笔者实测）：感知估计约 [0.354, 0, 0.19]，真值 [0.30, 0, 0.19]，偏移大约 54 mm；规则会打出感知偏离真值、运输过程中物体丢失；假设层可能给出「感知误差导致抓空」和「夹持面滑落」，并标明缺失证据（例如抓取时刻的分割 mask）。文档强调：假设不是结论，改故障配置重跑对照才能看各因素贡献。

2. 在 DSH 里让 Agent 驱动同一条流水线¶

装好 bundle 之后，README 给的入口句是：

运行 Robotic Harness 的 pick-place demo：检查 demo 机械臂，跑一次正常仿真和一次带故障的仿真，诊断失败原因，导出证据包并生成报告。

docs/demo.md 里还有更贴工具名的说法：

运行 rh-pick-place-demo Skill：检查 demo 机械臂 → rh_sim_status → 正常 sim-run → 带故障 sim-run → rh_diagnose_run → rh_evidence_export → rh_report_generate，然后解释失败原因并指出哪些是事实、哪些是假设。

Agent 会按 Skill 顺序调用 rh_* 工具，中间结果留在 .rh/ 下，可以用普通文件工具打开。无头 Linux 若要离屏渲染，文档要求软件 GL：sudo apt install libosmesa6 libgl1，并设置 MUJOCO_GL=osmesa。渲染器不可用时，感知会退化成「真值 + 噪声」的模拟，并在遥测里记录，而不是把 Run 直接打挂。

适用场景与注意事项¶

比较对口的人：

• 已经在用 DeepSeek Harness，想把机器人 / 具身智能实验接到 Agent 循环里
• 需要检查 URDF / MJCF / SDF，或把资产转成 MuJoCo 能跑的形式
• 想用固定 seed 做抓取失败的对照实验，并留下可哈希核对的证据包
• 研究仿真里的感知、标定、滑落等问题，但暂时没有真机适配器

使用前把下面几条当成硬约束，都来自仓库自己的披露，不是额外发挥。

1. 这是 Demo，不是产线工具。 验证环境目前主要是 Windows + Anaconda Python 3.10 + DSH 0.1.0-rc.6。ROS 2 实机、CAD 深度解析、真机和其它操作系统都还没充分试验。
2. 吸盘是运动学实现。 吸附后物体位姿由代码跟着吸盘走，不模拟真实吸力或接触力学。这一点写在 run 配置和报告里。
3. 仿真结果不是真机证据。 没有功能安全认证（文档点名 IEC 61508 / ISO 10218 / ISO/TS 15066 等均未做）。不要用它替代急停、安全门、限位。权限分级里，纯读取、本地派生、本地 MuJoCo 仿真已实现；受控真机动作未实现；急停解除等永不作为普通 Tool 暴露。
4. 后端缺失时会诚实失败。 没有 ros2 CLI、没有配置训练服务器、文献 API 不可达，都会返回 backend: "unavailable"。训练模块默认 dry-run；远程提交必须同一次调用里同时给 dryRun:false 和 confirm:true，并且只跑白名单命令。生成的训练脚本是确定性模板占位，不是真实模型代码。
5. MuJoCo 结果同一机器可复现，跨平台 / 版本不一定相同。 文档写的是默认积分器加固定 seed。
6. 插件以当前 dsh 进程权限运行。 目录页和 docs/safety-boundary.md 都要求：安装前检查源码与许可证；从 git 安装时 pnpm 可能要求授权 prepare 脚本，只对源码可信的包授权，并锁定 commit。本仓库遥测和日志不上传，worker 在本地执行。
7. 第三方组件有自己的许可证。 见仓库 THIRD_PARTY_NOTICES.md。

小结¶

dsh-robotic-harness 把机器人资产检查、MuJoCo 抓取放置、故障注入和分层诊断收进 DeepSeek Harness 的插件树里。对已经在用 dsh、又需要把仿真失败变成可核对证据的人，它提供的是一条从 rh_sim_run 到证据包的 Agent 工作流，而不是又一个孤立的仿真脚本。它目前仍是 Demo：真机能力没有，部分后端靠「不可用」诊断撑着，吸盘也不是接触力学。按目录页命令安装、先在本地把 scripts/demo.mjs 跑通，再决定要不要接进自己的 profile，会比直接对着真机试更稳妥。

目录页与源码：

• 插件目录：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-robotic-harness/
• GitHub：https://github.com/dingkaihu63/dsh-robotic-harness
• DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness