前言¶

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