dsh-agv

*面向 AGV / AMR 研发迭代�?DeepSeek Harness 插件�?

�?Agent 直接看懂一台移动机器人现场：把 ROS 2 图读成一份按整车子系统归类的概览 —�?叉车、扫地车、AGV、AMR 都算�? English

这是什�?

dsh-agv 是一�?DSH 插件（一�?npm �?+ 一�?Cordis 挂载配置），装上之后 Agent 就多了一�?agv_ros_graph 工具�?

AGV ROS 2 graph (ROS_DISTRO=humble) via wsl (Ubuntu-22.04)
6 node(s), 22 topic(s), 179 ms  ·  namespaces: /, /agv01, /agv02

Safety / 安全 �?1 topic(s)
  /agv01/safety/estop          std_msgs/msg/Bool
Implement / 属具 �?2 topic(s)
  /agv01/fork/height           std_msgs/msg/Float32
  /agv01/sweeper/brush_speed   std_msgs/msg/Float32  (also: chassis)
Docking & charging / 对接充电 �?1 topic(s)
  /agv01/charging_pile/status  agv_msgs/msg/DockStatus  (also: diagnostics)
Chassis & drive / 底盘驱动 �?4 topic(s)
  /agv01/chassis/cmd_vel       geometry_msgs/msg/Twist
  /agv01/chassis/odom          nav_msgs/msg/Odometry  (also: localization)
  ...
Other / 未归�?�?1 topic(s)
  /warehouse_thing             std_msgs/msg/String

分组不是按消息类型，而是�?**整车子系�?*：安全、属具、对接充电、电源、调度、底盘、导航、定位建图、感知、人机交互、诊断、仿真。一�?topic 可以同时属于多个子系统（/odom 既是底盘输出也是定位输入），报告会同时标出，但只归组一次�? 这个工具是只读的 —�?不发布、不设置参数、不改变任何状态，可以在跑着的车上放心调用�?

为什么做这个：和 dsh-ros2 的边�?

StvLi/dsh-ros2 已经证明 DSH + ROS 2 这条路能走通（79 个工具�? 个技能�? �?npm 包）。本项目不重复它�? | | dsh-ros2 | dsh-agv | |---|---|---| | 主战�?| 调试：为什么跑不起�?| 迭代：怎么更快做出来、越做越�?| | 车型 | 机械�?/ 人形（MoveIt、零位标定、手眼相机） | AGV / AMR（叉车、扫地车、搬运车�?| | 能力 | L1 只读诊断 �?L2 审批写入 �?L3 可视�?�?L4 实时视觉 | 从只读现场认知开始，向仿真驱动的开发闭环走 | | 命名空间 | dsh-ros2-* | dsh-agv�?不碰* dsh-ros2-* |

它的 docs/safety-handover.md 明确把本体相关的数据源和算法留给下游 —�?本项目正是在那个位置上�? **要做的（它完全没有的�?*：仿真驱动的开发闭环、场景与测试用例生成、回归测试、导航参数批量调优、多车调度仿真、AGV 特有部件状态（叉齿、门架、充电桩对接）�?

安装

dsh plugin --profile web add dsh-agv

包内声明�?dsh.bundle.patch，所�?dsh plugin add 会把它自动加进该 profile �?dsh.profile.bundles 层栈。装完重�?profile 即可�? 需�?Node ^22.19.0 || >=24.0.0�?

配置：ros2 到底在哪台机器上�?

这是这个插件最需要配对的一件事。默�?runner: local，也就是"agent 所在的机器"。而实际情况通常是：*agent �?Windows / 开发机上，ROS 2 �?WSL、在车上、或在另一台工控机上�?

三种模式�? | runner | 用�?| 关键配置 | |---|---|---| | local | ROS 2 �?agent 同机（Linux / macOS�?| �?| | wsl | ROS 2 �?Windows �?WSL 发行版里 | wslDistro、wslUser | | ssh | ROS 2 在车�?/ 另一台机�?| sshTarget、sshPort、sshIdentityFile |

�?profile �?cordis.patch.yml 里按 �?id 覆盖配置（id: agv 来自本包�?cordis.patch.yml，这一层在所�?bundle 层之后应用）�?

- id: agv
  config:
    runner: wsl
    wslDistro: Ubuntu-22.04
    rosSetup: /opt/ros/humble/setup.bash
    workspaceSetup: ~/agv_ws/install/setup.bash

指向真车�?

- id: agv
  config:
    runner: ssh
    sshTarget: [email protected]
    rosSetup: /opt/ros/humble/setup.bash
    workspaceSetup: /home/agv/agv_ws/install/setup.bash

全部配置项：

| �?| 默认�?| 说明 | |---|---|---| | runner | local | local | wsl | ssh | | wslDistro | Ubuntu-22.04 | wsl -l -v 里的发行版名 | | wslUser | （空�?| �?= 发行版默认用�?| | sshTarget | （空�?| agv01 �?[email protected] | | sshPort | 0 | 0 = ssh 默认 / 你的 ssh_config | | sshIdentityFile | （空�?| �?= ssh agent / ssh_config | | rosSetup | /opt/ros/humble/setup.bash | 每个命令�?source；文件不存在则跳�?| | workspaceSetup | （空�?| rosSetup 之后�?source 的工作空�?overlay | | workdir | （空�?| 执行前进入的目录 | | timeoutMs | 30000 | 单条命令超时 |

rosSetup / workspaceSetup �?source 是有 -f 保护的：路径写错时会得到 ROS 自己�?command not found，而不是一个和你无关的 No such file�?

工具

agv_ros_graph

只读读取 ROS 2 图，按整车子系统归类�? | 参数 | 类型 | 说明 | |---|---|---| | namespace | string | 只看某个命名空间，如 agv01。多车工位必�?| | group | enum | 只看某个子系统；匹配 topic �?*全部**归属，不只是主分�?| | timeout_ms | number | 单条命令超时；默认取插件配置 |

读失败时不抛异常，而是返回一�?*能照着�?*的报告：

FAILED to read the ROS 2 graph via wsl (Ubuntu-22.04)
command: if [ -f '/opt/ros/humble/setup.bash' ]; then . '/opt/ros/humble/setup.bash'; fi; ros2 topic list -t
detail:  /bin/bash: line 1: ros2: command not found
hint:    `ros2` is not on PATH inside WSL. Set `rosSetup` to the distribution you installed ...

**后续工具会沿"改代�?�?跑仿�?�?看结�?�?再改"这条闭环�?*，而不是横向铺很多只读命令。见 docs/ROADMAP.md�?

已知限制

• 只读。目前不做任何写入，colcon build、参数下发、bag 录制都还没有�?- 不会替你�?ROS 2。rosSetup 指向的发行版要自己装好�?- �?CLI 封装，不�?DDS 直连。它�?ros2 命令行并解析输出，因此单次调用有 CLI 启动开销（实测百毫秒级），不是高频遥测通道�?- **需要能 spawn 子进�?*。DSH 的受限沙箱模式下（Windows �?read-only / workspace-write），带管道的子进程可能被拒绝并报 EPERM；此时请以完全访问模式运行该 profile，或�?runner 指向 ssh�?- SSH 主机密钥不做自动信任。首次连接请在终端里手动 ssh <target> 接受一次，之后本插件才连得上（这样"要不要信任这台车"的决定权在你，而不在插件）�?- 超时杀进程只杀直接子进程：�?kill �?wsl.exe 可能留下 Linux 侧进程。当前所有命令都是短命只读命令，可以接受�?

架构：领域逻辑与插件胶水层分离

src/
├── index.ts         插件入口：name / inject / Config / apply   �?胶水�?├── dsh.ts           DSH 接缝：本插件用到的全部宿主契约（结构化类型，�?import 版本�?├── config.ts        schemastery 配置 schema
├── runtime.ts       配置 �?runner
├── tools/           工具定义与呈�?└── core/            �?�?import 任何 DSH / Cordis 的领域层
    ├── exec.ts        命令运行器：local / wsl / ssh
    ├── ros2.ts        ros2 命令构�?+ 纯解析函�?    ├── subsystems.ts  AGV 子系统分类规则表
    ├── overview.ts    读取 + 归类 + 分组的完整领域操�?    └── types.ts

两条硬规则：

1. src/core/ �?import 任何 DSH / Cordis 包�? 它是普�?TypeScript，可以在工具里调用、可以在 CLI 里调用、可以在测试里调用。要�?harness，只�?src/index.ts �?src/dsh.ts�?2. src/dsh.ts 是唯一描述宿主契约的地方，且用的是结构化类型而不�?import�? 插件依赖的是形状（register(definition) 长什么样），不是某个包版本；DSH 升级时不会因为包版本对不上而崩。代价是新增能力时要动这个文�?—�?而这正是值得 review 的时刻，因为那意味着插件又多绑定了一点宿主�? 细节�?docs/ARCHITECTURE.md�?

开�?

npm install
npm run build      # tsc �?lib/
npm test           # 构建后跑 node:test�?09 个用例）
npm run typecheck

本地加载调试�?

dsh plugin --profile <your-profile> add .    # 注意：`add .` 会按你的调用目录解析

只想看效果、不�?ROS 2：test/fixtures/fakeros/ 里有一个假�?ros2，把它拷�?WSL 就能跑通整条链路：

wsl -d Ubuntu-22.04 -- bash -lc \
  'mkdir -p /tmp/fakeros/bin && cp /mnt/f/<repo>/test/fixtures/fakeros/bin/ros2 /tmp/fakeros/bin/ && \
   cp /mnt/f/<repo>/test/fixtures/fakeros/setup.bash /tmp/fakeros/ && chmod +x /tmp/fakeros/bin/ros2'

然后�?profile �?rosSetup 指向 /tmp/fakeros/setup.bash、runner 设为 wsl�?

参与

• 提交前请�?npm test�?- 分类规则（src/core/subsystems.ts）的改动必须同步�?test/subsystems.test.ts 里那�?topic �?�?子系�?的期望表 —�?那张表就是规格�?- 详见 CONTRIBUTING.md�?

许可

MIT © 2026 xu-sheng