机器人实验台 dingkaihu63/dsh-robotic-harness

🤖 Robotic Harness

面向 DeepSeek Harness 的具身智能研究插件套件

把机器人资产、仿真、能力编排和故障证据串进同一条智能体工作流——从 CAD/URDF 检查，到 MuJoCo 抓取放置、故障注入、基于证据的诊断，再到可复现的实验包。

🧪 测试者与贡献者请注意：这个项目还处在早期的 Demo 阶段。目前只在有限的本地环境里验证过（Windows + Anaconda Python 3.10 + DSH 0.1.0-rc.6）。ROS 2、CAD、真机以及其他操作系统和硬件组合都没有充分测试——粗糙之处请多包涵，遇到问题欢迎反馈。
欢迎所有人测试、修改和扩展这套插件，也欢迎把你自己的机器人相关插件（ROS 2 / CAD / 视觉 / 控制 / VLA / ...）和本套件组合起来，一起搭出一个更大、更完整的机器人插件包——每个独立模块都可以单独发布、单独贡献。详见 CONTRIBUTING.md。

📑 目录

- ✨ 功能特性
- 📸 截图
- 🚀 快速开始（30 秒）
- 🏗️ 架构
- 📦 作为 DSH 插件安装
- 🧩 工具与技能一览
- 🎯 演示（MuJoCo 抓取放置）
- ⚠️ 已知限制
- 🌊 未来愿景
- 📂 仓库结构
- 📚 文档
- 🤝 贡献
- 📄 许可证

✨ 功能特性

| 🔍 资产与 CAD | URDF / MJCF / SDF 检查，惯量与拓扑校验，网格统计，SVG 预览，URDF→MJCF 转换，SDF 兼容导出，CAD 清单与版本对比 |
| 🎮 仿真 | MuJoCo 抓取放置，支持 6 种故障注入模式，批量基准测试，只读回放，仿真与真机差距报告 |
| 🧮 控制 | 跟踪指标（上升时间/稳定时间/超调/稳态误差），轨迹校验，规划与实际对比，PID 模板与配置对比，系统辨识 |
| 👁️ 视觉 | 颜色/通用感知路由、相机健康检查、标定检查、位姿检查、感知对比、失败帧标注 |
| 🧠 具身模型 | 模型注册表、内置演示适配器（真实运行）、诚实的后端探测、基于规则的能力路由、策略 rollout 对比 |
| 📡 遥测与诊断 | 确定性规则引擎（事实 / 规则 / 假设）、异常扫描、失败证据收集、运行对比 |
| 🧬 数据流水线 | 清单、schema、时间同步、对齐、非破坏性变换、episode、防泄漏切分、去标识化、rosbag 转换、LeRobot 导出、数据集版本与卡片 |
| 🔬 实验 | 规格 → 矩阵 → 基准 → 指标 → 消融 → 报告 |
| 🤖 真机流程 | 预检清单 + 实验状态机（没有适配器时，硬件项如实跳过） |
| 📚 知识 | 文档索引/搜索、错误码查询、诊断案例搜索、项目记忆（检索/写入） |
| 📖 研究 | 文献搜索（arXiv / Semantic Scholar）+ 面向任意阶段的问题→方案建议，附带证据 |
| 🚀 自主训练 | 服务器检查 → 训练计划 → 补充数据集发现 → 任务准备（默认 dry-run）→ 确认后远程提交 → 状态 → 报告 |
| 📊 报告 | 证据包（哈希清单）、Markdown 报告、独立时间线与仪表盘查看器 |

📸 截图

一次真实演示运行（从左到右）：场景渲染 · 关节跟踪 · 带目标区域的轨迹 · 跟踪误差。

MuJoCo scene (offscreen render)
Joint positions: target vs actual

Trajectory & target zone
Tracking error over time

🚀 快速开始（30 秒）

不需要 DSH —— 纯 Python。要求：Python ≥ 3.10，并安装 mujoco、numpy、opencv-python、matplotlib、pytest（推荐用 Anaconda 的 python3.10 环境）。

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

1) run the test suite (per-file process isolation avoids native DLL
collisions between mujoco/cv2/pyarrow — matches the one-shot worker)
cd python && python run_tests.py && cd ..

2) run the end-to-end demo: happy run + fault run + diagnostics +
evidence bundle + Markdown report + timeline + dashboard
PYTHON=<your python3.10> node scripts/demo.mjs

输出落在 examples/demo-output/：

| 产物 | 说明 |
| report-run-.md | 实验报告，包含证据与假设 |
| timeline-run-.html | 独立时间线查看器（用任意浏览器打开，无需服务器） |
| bundle-run-/ | 自包含证据包（manifest + sha256 哈希 + 遥测 + 图表） |
| dashboard.html | 单文件仪表盘，基于 run store |
| .rh/runs//artifacts/.png | 上面展示的图表 |

🏗️ 架构

flowchart TB
subgraph DSH["DeepSeek Harness"]
AGENT["Agent Loop"]
REG["Tool / Skill Registry"]
WEB["Web UI"]
end
subgraph RH["@robotic-harness/dsh-bundle"]
CORE["rh-core · project/run store (.rh/)"]
RTOOLS["rh-tools · ~100 tools"]
RSKILLS["rh-skills · 25 SKILL.md"]
end
subgraph W["robotic_harness_worker (Python ≥3.10, shipped inside the bundle)"]
M1["assets · cad"]
M2["simulation"]
M3["vision · vision_extra"]
M4["control"]
M5["models"]
M6["diagnostics · telemetry"]
M7["robots"]
M8["data_pipeline"]
M9["experiment"]
M10["ros"]
M11["knowledge"]
end
subgraph OUT["External backends"]
B1["MuJoCo"]
B2["ros2 CLI / rosbag2 (ROS-free)"]
B3["SolidWorks files (registered only)"]
B4["VLA / model endpoints"]
end
AGENT --> RTOOLS
WEB --> AGENT
RTOOLS --> CORE
RSKILLS --> AGENT
RTOOLS -- "stdio JSON (one-shot process)" --> W
M2 --> B1
M10 --> B2
M1 --> B3
M5 --> B4

bundle 里每个工具都通过 stdio 委托给 Python worker（python -m robotic_harness_worker <command> --input -）。运行记录、遥测、图表和报告默认写入工作区的 .rh/ 目录。一次性进程带来崩溃隔离：worker 挂了也不会拖垮 DSH。

📦 作为 DSH 插件安装

要求：DSH 命令行（@deepseek-ai/dsh ≥ 0.1.0-rc.6）、pnpm、Python 3.10 环境。

0) environment (example: keep everything on the F: drive)
export DSH_HOME=/f/dsh/.dsh-home
export PATH="/f/dsh/.tools:$PATH" # directory containing pnpm

1) create a profile and install the bundle
dsh plugin --profile rh-demo add ./packages/dsh-bundle

2) enable the Web UI
Note: the upstream npm release of @deepseek-ai/dsh-web-app depends on the
private package @deepseek-ai/dsh-frontend (registry 404), so pnpm add
fails. Built-in bundles resolve from the dsh install directory, so edit
$DSH_HOME/profiles/rh-demo/package.json instead:
dsh.profile.bundles = ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app",
"@robotic-harness/dsh-bundle"]
(save as UTF-8 without BOM)

3) point rh-tools.pythonPath at your Python 3.10 interpreter in the
profile's cordis.patch.yml (a patch replaces the whole row config,
so restate every key)

4) start the Web UI (pick any free port; 3090 is used here so it never
与 DSH Web 默认端口 3080 或其他应用冲突）
dsh --profile rh-demo --port 3090

其他安装方式：这个 bundle 也能从 tarball 安装（dsh plugin add ./robotic-harness-dsh-bundle-0.1.0.tgz），从 git 安装（dsh plugin add github:dingkaihu63/dsh-robotic-harness），或者发布后从 npm 安装。打包与发布步骤和检查项见 docs/publishing.md。

然后直接对智能体说：

“Run the Robotic Harness pick-place demo: inspect the demo arm, run one clean simulation and one fault-injected simulation, diagnose the failure, export the evidence bundle and generate the report.”

智能体会一步步驱动 rh_ 工具，并把每个结果都留作证据。

🧩 工具与技能面

十四个领域，约 110 个 rh_ 工具和 27 个技能。 完整表格（工具 → worker 命令 → 风险等级）见 docs/tool-inventory.md。快速一览：

| 领域 | 示例工具 |
| 资产与 CAD | rh_robot_asset_inspect · rh_urdf_validate · rh_urdf_to_mjcf · rh_sdf_validate · rh_cad_inventory · rh_mesh_inspect · rh_inertia_validate · rh_robot_topology_validate · rh_urdf_preview · rh_export_sim_asset |
| ROS 2 | rh_ros_graph_snapshot · rh_ros_topic_profile · rh_ros_qos_check · rh_ros_tf_audit · rh_rosbag_inspect (ROS-free)* · rh_rosbag_start/stop · rh_ros_call_whitelisted_action |
| 控制 | rh_control_trace_analyze · rh_trajectory_validate · rh_planned_actual_compare · rh_pid_experiment_prepare · rh_controller_config_compare · rh_system_identification_job |
| 视觉 | rh_camera_health_check · rh_calibration_inspect · rh_perception_run · rh_perception_compare · rh_pose_transform_validate · rh_annotate_failure_frame |
| 模型 | rh_model_inventory · rh_model_health · rh_model_infer_job · rh_model_benchmark · rh_capability_route_explain · rh_policy_rollout_compare |
| 仿真 | rh_sim_run · rh_sim_fault_inject · rh_sim_batch_benchmark · rh_sim_replay · rh_sim_real_gap_report · rh_sim_validate_scenario |
| 机器人 | rh_robot_preflight · rh_experiment_prepare · rh_experiment_request_approval · rh_experiment_start · rh_experiment_pause · rh_experiment_safe_cancel · rh_experiment_status · rh_experiment_finalize |
| 遥测 | rh_telemetry_channels · rh_telemetry_window · rh_anomaly_scan · rh_failure_evidence_collect · rh_run_compare · rh_diagnose_run · rh_timeline_export |
| 数据 | rh_data_inventory · rh_data_time_sync_estimate · rh_data_align_streams · rh_data_transform_apply · rh_data_split_create · rh_data_leakage_check · rh_data_deidentify · rh_data_convert_rosbag · rh_data_export_lerobot · rh_dataset_version_create · rh_dataset_card_generate |
| 实验 | rh_experiment_spec_create · rh_experiment_matrix_expand · rh_benchmark_start · rh_metrics_compute · rh_ablation_compare · rh_benchmark_report |
| 知识与记忆 | rh_docs_index · rh_manual_search · rh_error_code_lookup · rh_case_search · rh_memory_retrieve · rh_memory_ingest |
| 研究与文献 | rh_literature_search · rh_problem_solutions —— 检索公开文献，解决你当前遇到的问题（任何阶段都行），拿到有证据支撑的备选方案，供你挑选 |
| 自主训练 | rh_train_server_check · rh_train_plan_create · rh_train_data_discovery · rh_train_job_prepare · rh_train_job_status · rh_train_report —— 规划一次训练，找补充数据集，在本地准备好任务，只有你明确确认后，才提交到已配置的服务器 |
| 报告 | rh_evidence_export · rh_report_generate · rh_dashboard_generate |

实现状态

完整方案里的工具／技能接口，都以 demo 级适配器的形式实现：

- ✅ 纯软件模块 —— 已完成并测试（资产、CAD、仿真、控制、视觉、模型、诊断、遥测、数据、实验、知识、记忆、研究、训练）。
- 🔌 依赖后端的模块 —— ROS 2 实时探测、SolidWorks 解析、真机适配器、重型 VLA 模型，都以诚实的适配器形式存在：后端缺失时，它们返回结构化的 backend: "unavailable" 诊断信息，并附上安装说明，绝不伪造通过。rosbag2 的检查／转换无需 ROS 即可运行。

🎯 演示（MuJoCo 抓取放置）

- 场景：平面 3 自由度机械臂，带吸盘，从桌上抓起红色方块，放进目标区域（MuJoCo，用基本几何体搭建，不依赖外部网格）。
- 感知路由：颜色分割（低延迟）→ 失败或遮挡时改用通用显著性分割；路由原因会被记录下来。
- 故障注入（确定性，由种子控制）：perception_offset_px、gripper_slip、tf_offset、sensor_noise、model_timeout_s、occlusion。
- 遥测：关节目标值／实际值／误差、吸盘状态、物体位姿、感知估计值与真值对比；图表和场景渲染。
- 诊断：规则引擎产出分层证据 —— 事实（时间戳和数值）、规则发现（阈值／状态机）、候选根因（按感知／标定／机械／控制／系统层分组，附可能性和缺失证据）。最终结论留给人来判断。
- 证据：自包含的证据包（哈希清单 + 全部记录）+ Markdown 报告 + timeline.html。

⚠️ 已知限制

如实说明，免得测试的人措手不及。

- 吸盘抓取是运动学实现（吸附期间物体跟随吸盘移动）—— 运行配置和报告中都会注明。
- 渲染器可用时，感知走真实的离屏渲染；否则退化为 ground-truth + 噪声模拟（记录在 telemetry 中）。如果 OpenCV 原生崩溃（例如特殊环境下的 DLL 冲突），感知同样退化为这套兜底方案，而不是让整轮运行失败。无头 Linux 需要软件 GL（sudo apt install libosmesa6 libgl1 + MUJOCO_GL=osmesa）才能离屏渲染；CI 就是这么跑的。
- 实时 ROS 2 工具依赖 ros2 命令行；没有它时返回结构化的 backend: "unavailable" 诊断信息。rosbag2 的检查与转换不依赖 ROS，照常可用。
- 真机工具只有状态机 + 预检：在硬件适配器出现之前，硬件相关条目一律报告为 skip（绝不伪造）。仿真结果不算真机证据；不支持任意话题发布、真机写入或解除急停。
- SolidWorks 文件会登记进清单，但不做解析（商业软件）；FreeCAD 深度集成是可选项。
- RLDS 导出生成清单骨架（完整 TFDS 导出需要 tensorflow）；LeRobot 导出在有 pyarrow 时用 parquet，否则用 CSV。
- 文献检索与数据集发现是尽力而为的网络调用：API 不可达时返回结构化的 backend: "unavailable" 结果，绝不编造论文或数据集。
- 训练工具是工作流脚手架：生成的训练脚本是确定性模板占位符（不是真实模型代码），远程提交需要显式配置服务器并经你确认，且只有白名单内的命令才会在远端执行。

🌊 未来愿景

Robotic Harness 目前只是一个人用有限的时间和资源做出来的尝试。它边角粗糙，很多模块还等着在真实环境里验证，也一定藏着 bug。正因如此，社区的参与才比什么都重要：

- 用它 —— 真实使用是最好的测试，也是决定下一步做什么最有说服力的依据；
- 修它 —— 报 bug、补边界情况、纠正文档；每一次修复都让后来者的路更顺；
- 扩展它 —— 新技能、新场景、新失败案例、新数据适配器、ROS 2 实时验证、新领域；

我们希望抵达的终点不是「一个人的插件」，而是一个开放平台：建立在开源 DeepSeek Harness 基础之上，经一代代社区贡献打磨，更贴合机器人学与具身智能开发 —— 模型负责编排，各类专门能力各司其职，每次实验都留下完整证据，每份贡献都被记录并复用。

正因有涓涓细流，才铸就了大江大河。 —— every great river begins as trickling streams; open source is how those streams find each other.

欢迎任何形式的贡献。 🌊

📂 仓库结构

packages/dsh-bundle/ the installable DSH bundle (TS plugins, skills/, worker copy, fixtures, scenarios)
python/ robotic_harness_worker Python 包 + 测试（run_tests.py） fixtures/ URDF/SDF 测试资源 + 一个演示用 rosbag2（不需要 ROS） scenarios/ MuJoCo 场景定义（JSON） scripts/ sync-worker / demo / smoke-worker docs/ 架构、安全边界、路线图、演示指南、工具清单、worker 契约 examples/demo-output/ 一条命令跑演示的示例输出

📚 文档

- 架构与领域模型
- 安全边界
- 路线图
- 演示指南
- 工具清单
- Worker 模块契约 —— 给要添加新领域的贡献者
- 贡献指南 · 安全策略 · 第三方声明
- 中文文档：README.zh.md

🤝 贡献

欢迎测试者、bug 报告和贡献者 —— 模块契约、测试工作流和贡献规范见 CONTRIBUTING.md。适合上手的贡献：新增技能、新增场景、新增失败用例、数据导入/导出工具，或在真实硬件上验证 ROS 2 实时后端。

📄 许可证

MIT。第三方组件和资源各自适用自己的许可证（见 THIRD_PARTY_NOTICES.md）。
本仓库与 DeepSeek 无关；DSH 是独立项目（MIT，deepseek-harness）。