dsh-devices

dsh plugin --profile web add dsh-devices

dsh-devices

[English](./README.md) · 简体中文

<p align="center">

<a href="https://www.npmjs.com/package/dsh-devices"><img alt="npm" src="https://img.shields.io/npm/v/dsh-devices?style=flat-square&color=4b6fff"></a>

<a href="https://github.com/polaris-smart/dsh-devices"><img alt="GitHub stars" src="https://img.shields.io/github/stars/polaris-smart/dsh-devices?style=flat-square&color=4b6fff"></a>

<a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>

<img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-7da1de?style=flat-square">

</p>

<p align="center">

<strong>把你的设备变成一个舰队。</strong><br>

<strong>Turn your devices into a fleet.</strong>

</p>

零核心改动，纯插件挂载。 一个 dsh 插件，让你的多台设备（笔记本 / 台式机 / 服务器）组网协作。装完在 dsh 会话内自动注册工具，任何跑在 dsh 里的智能体（agent）都能直接调用。卸载后不留任何核心补丁。

Zero core changes, pure plugin mounting. A dsh plugin that lets your devices collaborate. Tools auto-register in dsh sessions — any dsh-hosted agent can call them directly. Uninstall leaves no core patches.

适用前提 / Requirements：

① 至少 2 台设备都装 dsh-devices（配对是双向的——只有一台装了没法配对，单设备装了没有配对对象）。

② 连接方式二选一：同一局域网且放行 mDNS 广播（UDP 5353，组播不跨路由器/子网）；或公网可达设备（有公网 IP 或端口映射）且开通 SSH（22 端口）。NAT 内网设备之间（如两台都在家庭/办公路由器后面）当前版本无法直连——需要 V2（P2P/tailscale 路线）。

Requirements: ① At least 2 devices, each with dsh-devices installed (pairing is two-sided; a single device has nothing to pair with). ② Connectivity: same LAN with mDNS multicast allowed (UDP 5353; doesn't cross routers/subnets), or publicly reachable devices with SSH (port 22) open. NAT-isolated devices cannot connect to each other in this version (V2 = P2P/tailscale planned).

· 中文 · English

同网发现 · 同一局域网 + 放行 mDNS 广播 → 设备互见 · Same LAN + mDNS allowed → devices see each other

密钥配对 · 输一个 key 完成配对（WiFi 式），无头设备友好 · Pair with one key (WiFi-style), headless friendly

跨网直连 · 公网可达设备（开通 SSH）→ 直接指挥 · Public devices with SSH → direct command

智能体原生 · dsh 会话内自动注册工具，agent 直接调 · Tools auto-register for dsh agents

模块开关 · modules: mdns \ · ssh \ · both，按需启用 · Enable what you need

轻依赖 · 运行时零 npm 依赖，纯 Node 22 标准库 · Zero runtime deps, pure Node 22 stdlib

随 dsh 起停 · 装进 profile 即随 dsh 运行，无需独立服务 · Lives with dsh, no separate service

---

快速开始 · Quick Start

从零到用，5 步 / From zero to use in 5 steps:

┌──────────────┐          ┌──────────────┐
│  设备 A（你）  │          │  设备 B（对方） │
│  dsh + devices  │◄────────►│  dsh + devices  │
│  主控/指挥     │  配对连接  │  被控/执行    │
└──────────────┘          └──────────────┘
     ↑ 你说："在 B 上跑 hostname"
     └─ agent 调 fleet_ssh_exec → B 返回结果

第 1 步：装 dsh（还没有的话）/ Install dsh if you don't have it:

npm install -g @deepseek-ai/dsh

第 2 步：两台设备都装 Fleet（配对是双向的，单台没用）/ Install Fleet on both devices:

dsh plugin add dsh-devices

第 3 步：重启 dsh 会话（让插件加载）/ Restart the dsh session:

dsh web              # 或 dsh --profile headless "…"

第 4 步：连接两台设备（二选一）/ Connect the two devices (pick one):

• 同一局域网：两台都开机，B 的 agent 开广播（"启动 fleet 广播"），你在 A 的会话说"发现设备并配对"
• 跨网络（B 有公网 SSH）：对 A 的 agent 说"用 fleet8 配对服务器 <IP>，用户 <用户名>，名字 <别名>"，agent 把公钥给你 → 你贴到 B 的 authorized_keys

第 5 步：像聊天一样用 / Use it like a chat:

你：帮我连上我的服务器，看看它现在什么状态
agent：已连接 my-server（43.135.x.x），内存可用 1.2G、负载 0.01、磁盘 51%。

你：在服务器上跑一下 hostname
agent：返回：VM-0-11-ubuntu

你：把备份脚本在服务器上执行一遍
agent：备份完成，输出：…

不需要记命令——发现设备、配对、执行，都是 agent 在会话里调 fleet_discover / fleet_pair / fleet_ssh_exec 完成的。

No commands to memorize — discovery, pairing, and execution are all done by the agent calling fleet_discover / fleet_pair / fleet_ssh_exec in your session.

也可以下载 Release 的 tgz 本地安装：dsh plugin add ./dsh-devices-<version>.tgz。

Or grab the tgz from Releases: dsh plugin add ./dsh-devices-<version>.tgz.

---

安装 · Installation

第 1 步 / Step 1：确认环境 / Prerequisites

node --version   # 需要 Node 22+（dsh 运行要求）

第 2 步 / Step 2：安装插件 / Install the plugin

# 一条命令（npm 源）/ One command from npm:
dsh plugin add dsh-devices

# 或从 GitHub Releases 下载 tgz / Or install a release tgz:
dsh plugin add ./dsh-devices-<version>.tgz

看到安装成功且无 warning 即可。装完 dsh 会话内自动注册 7 个 fleet_* 工具。

You should see a clean install with no warnings. Four fleet_* tools are then auto-registered in dsh sessions.

从源码打包 / Build from source:

```sh

git clone https://github.com/polaris-smart/dsh-devices.git

cd dsh-devices && npm pack # 产出 dsh-devices-<version>.tgz

```

---

使用场景 · Usage Scenarios

场景 A：同一局域网（推荐入门）

Scenario A: Same LAN (recommended start)

双方都要装 dsh-devices（配对是双向的——只有一边装了没法配对）。两台设备（下称 A、B）在同一 WiFi/局域网。

Both devices need dsh-devices (pairing is two-sided). Devices A and B on the same LAN.

第 1 步 / Step 1：在 B 上启动广播（让 A 能发现它）/ Start broadcasting on B

B 的用户在 B 的 dsh 会话里对 agent 说"启动 fleet 广播"（agent 会跑 fleet7 serve），或手动：

B's user asks B's dsh agent to "start fleet broadcast" (agent runs fleet7 serve), or manually:

fleet7 serve

第 2 步 / Step 2：在 A 的 dsh 会话里发现 B / Discover B from A's dsh session

你：调用 fleet_discover
AI：发现设备 B（192.168.x.x:端口，未配对）

第 3 步 / Step 3：配对 / Pair

B 首次运行 fleet7 serve 会生成设备密钥（fleet-d- 开头，打印在终端）。在 A 的 dsh 会话里：

B generates a device key (fleet-d-..., printed in the terminal) on first fleet7 serve. Then on A:

你：调用 fleet_pair，target 填 B 的地址，key 填 B 的设备密钥
AI：配对成功，已联动 SSH 注册表

第 4 步 / Step 4：指挥 B 干活 / Command B

你：用 fleet_ssh_exec 在设备 B 上执行 hostname
AI：（B 真实返回它的主机名）

配对一次，永久可用——B 已把 A 的公钥写入 authorized_keys，A 已记住 B 的连接方式。

Pair once, use forever — B has authorized A's public key; A remembers how to reach B.

场景 B：跨网络（SSH 直连）

Scenario B: Cross-network (SSH direct)

设备不在同一局域网时（如家里指挥云服务器），手动配对：

When devices are not on the same LAN (e.g., commanding a cloud server from home):

**让 agent 帮你配对 / Let your agent do the pairin

…(truncated)