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只 importnode:*,无需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),不做"静默失败"。
安全护栏
- 写路径:
/boot、/etc/fstab、/etc/network、/etc/sudoers(含.d)、/dev、/proc、/sys一律拒绝;本地 + 远端双重校验(readlink -f真实路径、拒绝符号链接目标、拒绝目录目标)。 - 命令:
sudo/su、apt/apt-get/dpkg、shutdown/reboot/poweroff/halt/init、mkfs*、flash.sh、dd of=/dev/*、fork bomb、rm -rf /→ 结构化拒绝(blocked:true,execexit_code=126),不执行。 - 尺寸/时延:read 默认 256 KB(≤4 MB)、write ≤8 MB、exec 默认 120 s(≤600 s,超时 kill 并返回
exit_code=-1)。 - 凭据:只使用配置里指定的 SSH 私钥;不读取、不写入任何 API key。
- 不动系统:不 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)。
卸载 / 回滚
- 删除 desktop patch 里的
id: jetson-bridgeinsert 行(或scripts\install-desktop.ps1 -Restore latest还原备份); - 删除本仓库/插件目录;
- 重启 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
No comments yet. Be the first to write one.