Preface

When developing robots or ROS2-related projects in DSH (DeepSeek Harness), a common issue is not “can I write a prompt” but whether ROS2 toolchains can be safely executed on a real host: viewing packages, nodes, topics, TF, parameters, checking system health, executing colcon / rosdep / rosbag, managing RViz2 lifecycle, and even performing displayless visual analysis.

If developers write scripts manually each time, it leads to duplication; if write operations are directly handed to agents, there’s a lack of approval and safety boundaries. dsh-ros2 is a plugin for DeepSeek Harness (DSH) that bundles ROS2 debugging toolkits and robot-state vision analysis into the DSH plugin ecosystem, allowing agents to use these capabilities under layered permissions.

Below, we first introduce what it is, then examine its capabilities, installation commands, and typical usage.

What It Is

dsh-ros2 is maintained by StvLi and positioned as:

ROS2 debugging toolset and robot-state vision analysis for DeepSeek Harness (DSH), shipped as a plugin.

It targets hosts with a ROS2 environment, providing 51 ROS2 debugging scenario tools and dividing capabilities into four layers from L1 to L4. The materials indicate the license is MIT, and the README badge shows License: MIT.

In DSH’s plugin-oriented approach, such capabilities are not deployed as a separate service but are added to the current DSH session as profile plugins.

Core Capabilities

L1: Read-Only Diagnostics

L1 is read-only capability for quickly viewing system state without write operations. Coverage includes:

  • package / workspace / dependency checks
  • node / topic / service / action / param / interface enumeration
  • one-shot topic sampling
  • TF tree queries
  • whole-graph topology JSON
  • ros2doctor
  • bag summaries
  • MoveIt discovery

This layer is suitable for first answering “what is the current system state.”

L2: Approval-Gated Management

L2 involves write operations such as building, installing, configuring, playback, motion, and safety states. The materials indicate L2 writes are approval-gated / fail-closed. Includes:

  • colcon build
  • rosdep install
  • message skeleton generation
  • param set
  • bounded bag record
  • one-click ROS2 install
  • launch management
  • rosbag replay
  • MoveIt motion
  • zero-pose calibration
  • robot registration & topology learning
  • safety_monitor start / human-gated lock / unlock

The key point for this layer is: write operations are prompted first, and refusal results in failure.

L3: Visualization

L3 is oriented towards local visualization sessions to “see” robot state:

  • RViz2 / rqt lifecycle management
  • screenshots
  • multimodal vision description
  • xdotool-level window interaction

This layer is suitable for interface-level checks, screenshots, and window interactions.

L4: Real-Time Vision

L4 is oriented towards real-time visual analysis in displayless environments:

  • parallel VLM ROS2 node
  • image-topic acquisition
  • headless vision_bringup
  • RViz2 offscreen rendering, published to /rviz/scene

If using L4, additional dependencies include Python 3 rclpy and an OpenAI-compatible VLM gateway.

Safety Framework

The materials mention a real-time safety framework, including:

  • safety_monitor node
  • robot_safety_* tools
  • layered defense
  • latched NORMAL / LOCKED state machine

This framework integrates safety states into the robot workflow rather than making temporary judgments in single commands.

Built-in Skills

dsh-ros2 includes four built-in skills:

  • ros2-diagnostics
  • robot-state-vision-analysis
  • robot-registration
  • robot-retrieval

These skills target different tasks: diagnostics, state visual analysis, robot registration and retrieval/loading.

Installation and Activation

Runtime Environment

First, confirm the environment, then install the plugin.

  • A host with ROS2 is required. Materials indicate Jazzy has been verified; Humble is noted as “should work” in the materials but not as a confirmed compatibility fact.
  • DSH host requires Node version:
^22.19 || >=24
  • If using L4 vision, additional requirements include:
  • Python 3 rclpy
  • OpenAI-compatible VLM gateway
  • VLM gateway API keys should be injected via env / secret manager, not hardcoded.

Installation Commands

Execute in the target DSH profile:

dsh plugin --profile <profile> add dsh-ros2

Before installation, it is recommended to review the source code and license, and confirm that the plugin will run with the current dsh process permissions. After these steps, the plugin will provide ROS2 debugging and robot-state visual analysis tools in the current DSH profile.

Typical Usage

Below are sample commands from the materials, suitable for an initial experience:

ros2_graph
ros2_topic_list
ros2_topic_echo /joint_states
ros2_tf_list
ros2_doctor

These commands correspond to:

  • ros2_graph: whole system topology in one shot
  • ros2_topic_list: all topics and types
  • ros2_topic_echo /joint_states: sample one frame of joint states
  • ros2_tf_list: TF tree edges
  • ros2_doctor: system health report

For read-only troubleshooting, typically start with enumeration like ros2_topic_list and ros2_node_list, then sample single frames with ros2_topic_echo, and finally use ros2_doctor to view the system health report.

Use Cases and Notes

Suitable for the following scenarios:

  • Directly executing ROS2 debugging commands in DSH agents
  • Needing to check packages, nodes, topics, TF, parameters, and system health on the host
  • Needing to add approval boundaries to write operations such as building, dependency installation, parameter setting, and bag recording/playback
  • Needing RViz2 lifecycle management, screenshots, visual descriptions, or displayless rendering
  • Needing to integrate safety states and safety_monitor into the robot workflow

Notes:

  • L1 is read-only capability, and L2 write operations are approval-gated / fail-closed.
  • L4 vision introduces dependencies on Python 3 rclpy and an OpenAI-compatible VLM gateway.
  • Humble compatibility in the materials is “should work,” not a confirmed fact.
  • API keys should not be written into configurations or code; use env / secret manager instead.
  • The plugin runs in DSH with current dsh process permissions, so source code, license, and permission scope should be reviewed before installation.
  • The community directory here is an independent site, not an official app store from DeepSeek or幻方.

Conclusion

The value of dsh-ros2 lies in integrating ROS2 debugging, robot-state vision analysis, and safety boundaries into the DSH plugin ecosystem, allowing agents to execute in layers from L1 to L4 instead of mixing all operations at the same level.

  • GitHub: https://github.com/StvLi/dsh-ros2
  • The directory page provided in this clue (not confirmed in the fetched materials): https://www.skillhub.cn/plugins/StvLi/dsh-ros2