dsh-tmux

把 AIMUX 接进 DeepSeek Harness(dsh),让 dsh agent 拥有 AIMUX 的全部能力。

AIMUX 是什么:AIMUX 是 AI 系统的触手 —— 它把任意计算机(Windows / Mac / Linux)接入一张 协作网络,从而完成复杂的跨设备任务。AIMUX 专门针对缺 SSH / SSH 不可达的桌面笔记本、工作站、 嵌入式设备、网络受限设备设计:设备主动**反向连接(reverse connect)**到一台 bridge broker, broker 再把指令透传给设备。这样,即便设备在 NAT、防火墙或受限网络后面,也能被远程操控。

这个插件把上述能力暴露成一组 dsh 工具。于是 dsh agent 不再只能待在自己的 shell 里 —— 它能够到任何 一台挂在 AIMUX 触手网里的机器,在上面开长生命周期 session、跑命令、传文件、甚至把那台机器上的 web 服务端口转发回来。

为什么 dsh 需要 AIMUX

dsh 自带的 bash / 终端工具只能操作 dsh 所在那台机器,且依赖 SSH 才能到别的 host。而真实世界的设备 往往是:

• Windows 工作站 / 笔记本(没有 SSH 服务,或在 NAT 后面);
• 嵌入式 / 工控设备(网络受限、只出不进);
• 实验室里那台“能联网但连不进来”的 GPU 工作站。

AIMUX 用 bridge + 反向连接打通这些场景。dsh-tmux 让 dsh agent 直接用这套触手网:部署 broker、让 目标设备反连进来、然后在设备上干活。

给 agent 提供的工具

所有工具都用 argv(不走 shell)spawn aimux CLI,模型传入的值无法注入元字符;每个工具返回 { exitCode, stdout, stderr, durationMs },aimux 的非零退出码体现在返回值里(不抛异常)。

Session —— 长生命周期 shell(本地 / SSH / bridge 远程)

工具	aimux 命令	用途
aimux_session_new	new	创建 session;remote+profile 指 bridge 远程,remote 单独指 SSH 主机,可带 cwd/cmd/reuse
aimux_session_send_keys	send-keys	发送按键 / 跑命令(tmux 风格;Enter 提交,C-c 中断)
aimux_session_capture	capture	读取 pane 的最后 N 行
aimux_session_wait	wait-last-command-complete	阻塞到回到 shell 提示符(仅本地)
aimux_session_kill	kill	销毁 session
aimux_session_list	ls	列出所有 session

触手网络 / Bridge —— AIMUX 的立身之本(接 SSH 不可达设备)

工具	aimux 命令	用途
aimux_bridge_deploy	bridge deploy	启动 bridge broker,监听反连(port 必填,可选 host/token)
aimux_reverse_connect	reverse connect	让本机反向连接到一个 broker(url+identifier 必填);连上后这台机器就作为触手登记进 aimux remote,即可被远程操控

远程主机管理

工具	aimux 命令	用途
aimux_remote_list	remote ls	列出 SSH 主机与 bridge 远程(反连后自动加入)
aimux_remote_add	remote add	注册一台 SSH 主机
aimux_remote_test	remote test	探测连通性 / 鉴权

文件

工具	aimux 命令	用途
aimux_files_send	send_files	上传文件/目录(SSH 或 bridge,sftp)
aimux_files_get	get_files	下载文件/目录(SSH 或 bridge,sftp)
aimux_files_sync	sync_dir	差分同步目录(bridge;to-remote/from-remote 二选一,可 exclude)
aimux_file	file <op>	精细文件操作:list / stat / read / write / mkdir / delete / rename(SSH 或 bridge,按 remote 名自动派发)

网络

工具	aimux 命令	用途
aimux_port_forward	port forward	把本地 HTTP/SSE/WebSocket 流量经 broker 转发(用于访问 SSH 不可达设备上的 web 服务)

前置条件

1. dsh —— 已安装(npm i -g @deepseek-ai/dsh,或从源码运行),Node ^22.19 || >=24。
2. aimux —— 已安装并在 PATH 上(pip install aimux)。
3. bridge 拓扑(可选,接 SSH 不可达设备时才需要):一台能被设备和控制端都访问到的 broker 主机;目标设备 上能跑 aimux reverse connect。

安装到 dsh profile

# 从本地 checkout
dsh plugin --profile my add ./dsh-tmux

# 直接从 git(仓库自带预编译 lib/,无需构建步骤,也不会弹“允许构建脚本”)
dsh plugin --profile my add github:<you>/dsh-tmux

# 从 tarball
npm pack && dsh plugin --profile my add ./dsh-tmux-0.1.0.tgz

查看合成后的配置(应能看到一层 # == dsh-tmux),再启动:

dsh --profile my --dump-config
dsh --profile my

临时加载、不打包(在 dsh 源码 checkout 里):

pnpm dsh web --patch ./dsh-tmux/cordis.patch.yml

配置

默认即用即走;可在 bundle 的 cordis.patch.yml、profile 的 cordis.patch.yml、或 $DSH_HOME/cordis.patch.yml 里覆盖:

- insert:
    - id: aimux
      name: dsh-tmux
      config:
        aimuxBin: aimux          # aimux 不在 dsh 进程 PATH 上时填绝对路径
        defaultTimeoutMs: 60000  # 0 = 不设内部超时

字段	默认值	说明
aimuxBin	aimux	可执行文件名或绝对路径。找不到时抛可操作错误。
defaultTimeoutMs	60000	单次调用超时;aimux_session_wait 与长任务不受此限。

典型场景:够到一台 SSH 不可达的 Windows 工作站

目标:让 dsh agent 在一台 NAT 后面、没开 SSH 的 Windows 工作站上跑命令,并把那台机器上的某个 web 服务端口转发回本地浏览。

1. 控制端起 broker(dsh agent 在可达的主机上): aimux_bridge_deploy({ port: 8765 }) → broker 监听 :8765。
2. 工作站反连(在工作站上一次性执行,或由 bootstrap 自动拉起): aimux reverse connect http://<broker>:8765 --identifier win-ws-01。
3. 确认触手已登记(dsh agent): aimux_remote_list() → 应能看到 win-ws-01(bridge 远程)。
4. 开 session 并干活: aimux_session_new({ name: "work", remote: "win-ws-01", profile: "powershell" }) → 句柄 win-ws-01/work;接着 aimux_session_send_keys({ session: "win-ws-01/work", keys: ["dir", "Enter"] }), 再 aimux_session_capture({ session: "win-ws-01/work", lines: 80 }) 读输出。
5. 传文件:aimux_files_send({ remote: "win-ws-01", remoteDir: "C:\\build", localPaths: ["./pkg"] })。
6. 把工作站上的 web 服务转发回来:aimux_port_forward({ url: "http://<broker>:8765", localPort: 8080, remotePort: 3080 }) → 本机 http://127.0.0.1:8080 即工作站上的服务。
7. 清理:aimux_session_kill({ session: "win-ws-01/work" })。

session 会跨多轮对话保活 —— agent 可以一直把这台工作站当成长期可操控的触手。

工作原理(如何 patch 进 harness)

本包是一个 dsh bundle:package.json 声明 dsh.bundle.patch → cordis.patch.yml,该 patch 往 profile 合成配置里 insert 一行 { id: aimux, name: dsh-tmux }。loader 挂载这行时,从 profile 的 node_modules 解析已安装的 dsh-tmux 包并运行 apply(ctx)。插件声明 inject = ['tools'],Cordis 等 tool registry 就绪后,由 ctx.tools.register(...) 把每个 aimux 工具注册成模型可调用的能力(Web UI 可见, Code Mode 下 await tools.aimux_session_new(...))。卸载插件 fiber 时自动反注册。这与 dsh-emoji 的 bundle → patch → inject → register 形态一致 (dsh-emoji 注入 llm + systemPrompt;本插件注入 tools)。

工具执行侧:每个工具 spawn aimux CLI(不走 shell),exec.signal 和超时会 kill 子进程。send_keys 会在 session 内执行任意命令,请像对待 bash 一样用 dsh 的权限策略(tools/pre-execute、ctx.tools.guard()、 当前权限预设)加以管控。

为什么 git 安装“开箱即用”

本仓库提交了预编译的 lib/(同 dsh-emoji)。因此 dsh plugin add github:<you>/dsh-tmux 拿到的是可直接运行的代码 —— 不跑任何 prepare 脚本,也不弹 pnpm 的“是否允许构建脚本?”。为可复现可 pin commit(github:<you>/dsh-tmux#<sha>)。

开发

需要 Node ^22.19 || >=24 和 pnpm。dsh 框架包(cordis、dsh-tools、schemastery)声明为 peer dependencies,运行时由 host 的 dsh profile 提供;dev dependencies 提供类型用于本地检查。

pnpm install               # devDependencies 提供 @deepseek-ai/* 类型
pnpm typecheck             # tsc --noEmit,对照已发布的 @deepseek-ai/dsh-tools 类型
pnpm build                 # tsc → lib/(JS + .d.ts);构建后请提交 lib/

注意 / 限制

• wait-last-command-complete 仅限本地;aimux_session_wait 沿用此限制。远程 / bridge session 请 轮询 aimux_session_capture。
• bridge 远程 session 需要 profile(对应设备上的 shell 形态,如 cmd/powershell/bash);由设备 反连时的 --default-profile 或 aimux_session_new 的 profile 参数决定。
• dsh 与 @deepseek-ai/dsh-tools 处于 developer preview,会有破坏性变更。请 pin 构建时版本,升级时 重新验证。
• 本包独立于 DeepSeek AI;“DeepSeek Harness”与 dsh 归各自所有者。MIT 协议。