DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

Red-Rayux /

Red-Rayux/dsh-plugin-jetson

Topic repository only

DSH (DeepSeek Harness) Host plugin: six tools to operate a NVIDIA Jetson (Ubuntu/ROS1 Noetic) over SSH, with file-bridge health checks and self-repair.

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@e324f2bc

dsh-plugin-jetson

English: A DeepSeek Harness (DSH) Host plugin that exposes six model-facing tools to operate a NVIDIA Jetson (Ubuntu 20.04 / ROS1 Noetic / aarch64) over SSH — execute commands, read/write files, list directories, health-check the SSH file bridge, and self-repair it. Zero third-party dependencies: the loadable plugin is a single ESM file using only Node built-ins.

把 NVIDIA Jetson(Xavier NX / Ubuntu 20.04 / ROS1 Noetic / aarch64)接入 DeepSeek Harness(DSH) 的 Host 插件:注册 6 个模型可见工具,让 agent 用一次工具调用操作真实板子——执行命令、读写文件、列目录、体检 SSH 文件桥、断链自动修复。

  • 数据面:直接 spawn ssh(不经过 Python,单次约 0.8–1.5 s),路径/命令有硬性护栏。
  • 维护面:复用 platform/jetsonctl.py(纯标准库控制面,start/down/mount/share/verify),不另造一套桥逻辑。
  • 零依赖:dist/index.mjs 只 import node:*,无需 npm install、无需打包器、无 node_modules;可被 DSH 以绝对路径直接加载。
  • 可验证:内置离线单测、真机 smoke、临时 DSH 实例验收 harness(含断链自救用例)。
┌──────────────────────── DSH Host process (Windows) ────────────────────────┐
│  model ──► jetson_exec / read / write / list ──► spawn ssh ───────────┐    │
│        ──► jetson_status / jetson_repair ──► python platform/jetsonctl.py   │
│                                    │                                  │    │
│                        %USERPROFILE%\.dsh\jetson-bridge.log ◄─────────┘    │
└────────────────────────────────────┼───────────────────────────────────────┘
                                     │ SSH (Tailscale / LAN)
                        ┌────────────▼────────────┐
                        │  NVIDIA Jetson (Ubuntu) │
                        │  /opt/ros/noetic        │
                        │  ~/win  ◄── sshfs ── Windows share dir │
                        └─────────────────────────┘

功能

工具 作用
jetson_exec 在 Jetson 上执行 shell 命令(全新 shell;ROS1 需先 source /opt/ros/noetic/setup.bash),返回 exit_code/stdout/stderr/duration_ms/cwd
jetson_read 读远端文本文件,默认 ≤256 KB,超出返回 truncated=true + 完整 size
jetson_write 写远端文件(≤8 MB),返回本地/远端一致的 sha256;写入走「临时文件 + 原子 rename」,覆盖写安全
jetson_list 列目录(depth 1–4),返回 name/type/size/mtime
jetson_status 只读体检:ssh 延迟、Tailscale、rclone/反向隧道/sshfs 挂载、ROS1、磁盘、内存;缓存 60 s
jetson_repair 分层诊断 + 自愈:ssh → Tailscale → rclone 进程 → 反向隧道 → sshfs 挂载;按 share → mount → start → down+start 阶梯修复

所有工具的错误都按层标注(ssh / ssh/auth / tailscale / mount / rclone / config / read / write / arguments),不做"静默失败"。

安全护栏

  1. 写路径:/boot、/etc/fstab、/etc/network、/etc/sudoers(含 .d)、/dev、/proc、/sys 一律拒绝;本地 + 远端双重校验(readlink -f 真实路径、拒绝符号链接目标、拒绝目录目标)。
  2. 命令:sudo/su、apt/apt-get/dpkg、shutdown/reboot/poweroff/halt/init、mkfs*、flash.sh、dd of=/dev/*、fork bomb、rm -rf / → 结构化拒绝(blocked:true,exec exit_code=126),不执行。
  3. 尺寸/时延:read 默认 256 KB(≤4 MB)、write ≤8 MB、exec 默认 120 s(≤600 s,超时 kill 并返回 exit_code=-1)。
  4. 凭据:只使用配置里指定的 SSH 私钥;不读取、不写入任何 API key。
  5. 不动系统:不 sudo、不装系统包、不写注册表、不装服务、不开入站端口。

环境要求

项 要求
DSH Desktop 0.2.2-rc.1 与 0.2.1-rc.3 实测通过(Host 插件,inject: ['tools'];加载机制见 docs/ARCHITECTURE.md)
Node ≥ 22(插件只使用稳定 API;DSH Desktop 自带运行时也可)
控制端 Windows 10/11(PowerShell 5.1+,OpenSSH client),或任何带 ssh/python3 的机器
Jetson Ubuntu 20.04+、SSH 可达(推荐 Tailscale)、ROS1 Noetic 可选(不跑 ROS 也能用 exec/fs 工具)
Python 3.8+(仅 platform/jetsonctl.py 使用,纯标准库)

快速开始

1. 配置

cd dsh-plugin-jetson
Copy-Item platform\config.example.json platform\config.json
# 编辑 platform\config.json:jetson.host / jetson.user / jetson.identity / windows.share_dir / mount.remote_point

platform/config.json 已在 .gitignore 中(含私密拓扑,不要提交)。字段说明见 platform/README.md。

2. 构建(可选,dist/ 已随仓库提供)

node build.mjs          # src/index.mjs -> dist/index.mjs(确定性输出)
node --test test/plugin.test.mjs

3. 接入 DSH desktop profile

把下面这段追加到 %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml 的顶层数组末尾(绝对路径会被 DSH 锚定为 file:// URL):

# jetson-bridge: Jetson tools (exec/read/write/list/status/repair)
- insert:
    - id: jetson-bridge
      name: 'C:/path/to/dsh-plugin-jetson/dist/index.mjs'

或直接运行附带脚本(自动备份 + 写入 + YAML 校验;默认 dry-run):

powershell -ExecutionPolicy Bypass -File scripts\install-desktop.ps1          # 预览
powershell -ExecutionPolicy Bypass -File scripts\install-desktop.ps1 -Apply   # 备份并写入

然后重启 DeepSeek Harness 桌面应用(实测 0.2.1-rc.3 / 0.2.2-rc.1 有时会热组合立即生效,但重启最稳)。新会话工具清单应出现 jetson_exec / jetson_read / jetson_write / jetson_list / jetson_status / jetson_repair。

DSH 对 profile 外模块的裸导入解析有边界(见 docs/ARCHITECTURE.md),所以本插件保持零裸导入:文件放在仓库任意绝对路径即可加载,不需要安装成 npm 包。

4. 验证

让模型调用:

jetson_status
jetson_exec "source /opt/ros/noetic/setup.bash && rosversion -d"

或直接用命令行 smoke(需要真实桥可用;会读写 /tmp 与共享目录并在结束时清理):

node test/real-smoke.mjs

配置项(platform/config.json)

字段 必填 说明
jetson.host ✅ Jetson 的 SSH 地址(推荐 Tailscale IP)
jetson.user ✅ Jetson 用户名(用于 ~ 展开与默认挂载点 /home/<user>/win)
jetson.port 默认 22
jetson.identity SSH 私钥;默认 ~/.ssh/id_ed25519
windows.share_dir Windows 侧共享目录(文件桥 + verify 使用)
windows.share_user rclone SFTP 用户名(默认当前 Windows 用户名)
mount.remote_point Jetson 侧挂载点;留空则 /home/<jetson.user>/win
dsh.* 仅 jetsonctl.py start/up 的 Jetson 侧 dsh web 隧道使用,可按需填写

插件按以下顺序定位"桥根"(包含 platform/ 的目录):DSH_JETSON_BRIDGE_ROOT 环境变量 → 本仓库根(自包含布局)→ 传统 jetson_agent_bridge 布局。

自动维护

机制 行为
加载即自检 apply() 后异步跑一次 jetson_status,只写日志,不阻塞、不抛异常
健康缓存 状态缓存 60 s,并发请求合并为一次探测
懒修复 读写 ~/win 且挂载缺失时:隧道正常先 mount --via-rclone,否则一次 jetsonctl.py start(60 s 冷却),失败给出分层原因
明确修复入口 jetson_repair 五层检查 + share/mount/start/down+start 阶梯修复,每步记录 ok/detail/耗时
漂移检测 记录 config.json/jetsonctl.py 指纹;启动时比对并提示重跑 verify
日志 %USERPROFILE%\.dsh\jetson-bridge.log,>2 MB 轮转 .log.1

不做:不装 systemd/计划任务、不监听端口、不在后台常驻守护进程。

测试与验收

node --test test/plugin.test.mjs        # 离线单测(护栏/路径/注册/解析)
node build.mjs && git diff --exit-code -- dist   # 确认 dist 与 src 同步
node test/real-smoke.mjs                # 真机 smoke(需要可用桥)

验收方法与结果(指令书 §6 的 10 条断言)见 docs/ACCEPTANCE.md。维护者还可以用 harness/run-jetson.ps1 在隔离的临时 DSH_HOME 中加载本插件、通过 ctx.tools.execute() 逐条跑真机验收用例(不碰你正在使用的 DSH profile)。

卸载 / 回滚

见 docs/UNINSTALL.md:

  1. 删除 desktop patch 里的 id: jetson-bridge insert 行(或 scripts\install-desktop.ps1 -Restore latest 还原备份);
  2. 删除本仓库/插件目录;
  3. 重启 DSH 桌面应用。platform/jetsonctl.py、platform/config.json、共享目录与 SSH key 均保留。

目录结构

dsh-plugin-jetson/
├── src/index.mjs              # 唯一源码(零依赖 ESM,带注释)
├── build.mjs                  # 构建:src -> dist(确定性 banner + import 自检)
├── dist/index.mjs             # DSH 实际加载的入口
├── platform/
│   ├── jetsonctl.py           # Win<->Jetson 桥控制面(纯标准库)
│   ├── config.example.json    # 配置模板(复制为 config.json 后填写)
│   └── README.md
├── scripts/
│   ├── install-desktop.ps1    # 备份 + 写入 + YAML 校验 + 一键回滚
│   └── patch-snippet.yml      # 手动接入用 insert 片段
├── test/                      # 单测、验收用例、检查器、真机 smoke
├── harness/                   # 维护者用:临时 DSH 实例验收 harness
├── docs/                      # 架构 / 验收 / 开发 / 卸载
└── docs/ci.yml.example        # CI 样例(复制到 .github/workflows/ 后启用:Node 22/24 × Ubuntu/Windows)

已知限制

  • jetson_read 面向文本(UTF-8,二进制按替换字符解码);大文件/二进制请走共享目录或 jetsonctl.py put/get。
  • 文件桥是 SSHFS/rclone 用户态方案:对已存在文件的 cat > 覆盖写在部分组合下会 EIO —— 本插件的 jetson_write 使用「临时文件 + rename」已规避(0.1.1+)。
  • 本插件是 DSH Host 插件(注册工具),不包含 Web UI 面板。
  • 若把插件拷贝进 DSH profile 的 node_modules 作为 npm 包使用,import.meta.url 会落在 profile 内导致桥根推导变化,此时请设置 DSH_JETSON_BRIDGE_ROOT 指向真实仓库目录。

相关文档

  • docs/ARCHITECTURE.md:加载机制、数据面/维护面设计、护栏与状态采集细节
  • docs/ACCEPTANCE.md:验收断言、方法、结果与证据说明
  • docs/DEVELOPMENT.md:构建、单测、真机 smoke、维护者 harness
  • docs/UNINSTALL.md:卸载与回滚
  • CHANGELOG.md

License

MIT © 2026 Red-Rayux

—/ 5

No ratings yet

Manifest verification required

Commit e324f2bc4f06

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout