前言¶

给智能体写命令执行能力时，常见做法是给模型配一个临时 shell，让它自己断开、重连、维护 SSH 配置。这样做的代价是：连接、跳板机、分组这些资产没有被复用，命令过程是否能被人看到取决于终端实现，事后也难以回看你究竟让 AI 跑了什么。

nyaterm-bridge 走的是另一条路：把命令执行交给你已经在用的 NyaTerm 终端，让 AI 复用 NyaTerm 里已经配好的连接和分组，同时用工作区级的白名单限制它能碰哪些分组和主机。它和 dsh-remote 是互补关系：文件读写、workspace 镜像、SFTP 同步继续用 dsh-remote，命令执行走 NyaTerm。

插件由 visualcjy 维护，属于客户端类插件，目录页在 https://www.skillhub.cn/plugins/visualcjy/nyaterm-bridge ，源码在 https://github.com/visualcjy/nyaterm-bridge 。

这是什么¶

一句话定位：让 AI 在 NyaTerm 的真实终端会话里执行命令，命令过程实时可见，并按工作区限制可用的 NyaTerm 分组和主机。

它解决的是「命令执行的落点」和「谁能被执行」两个问题。前者通过复用 NyaTerm 的现有连接、审批和审计能力实现；后者通过插件自己维护的工作区 allowlist 实现。

核心能力¶

命令不是丢进一个临时 shell，而是落在你已经在用的 NyaTerm 里，因此能直接复用它的资产和留痕能力。下面按「连接、执行、观察、审计」这条链路说明。

1、复用现成连接。分组、跳板机、SSH / 串口 / SFTP、本地终端都是 NyaTerm 里已经配好的。AI 不需要另维护一套连接配置，也不会绕开你现有的跳板链路。

2、真实终端、可观察可批准。命令在真实会话里执行，过程和输出实时可见。NyaTerm 的 External MCP 权限模式决定是否需要人工批准。

3、审计与回看。MCP 调用会进入 NyaTerm 的审计日志；在 NyaTerm 里开启会话录制/保留后，AI 执行的每条命令和输出都留在会话记录里，事后可以查。

4、白名单叠加。工作区 allowlist 决定 AI 只能碰哪些分组、主机和连接，这和 NyaTerm 自己的权限模型是两层独立的闸。

安装与启用¶

需要 NyaTerm（正式版），并在 NyaTerm 里打开 设置 → External MCP；DSH 侧建议 0.2.1 及以上。插件市场（dshmarket）里搜索 nyaterm-bridge 可以一键安装。

从 GitHub 源码安装的命令如下：

dsh plugin --profile web add github:visualcjy/nyaterm-bridge

普通 dsh web 把 web 换成自己的 profile；桌面端的 profile 由应用管理，请在界面里安装。也可在 DSH 插件页 → 添加插件 → 安装第三方插件，填 github:visualcjy/nyaterm-bridge。

装好后打开 DSH 设置 → NyaTerm 白名单，确认「MCP 程序位置」指向本机的 nyaterm-mcp（通常自动检测即可）。

前置条件有三条：NyaTerm 侧打开 External MCP 并让插件读到发现文档；NyaTerm 里至少有一个 SSH 连接；NyaTerm 窗口不能被锁屏或最小化，因为批准提示落在 NyaTerm 窗口里，窗口不可用时命令会卡住或失败。

external MCP 的发现文档路径是 ~/.nyaterm/mcp/discovery.json（正式版）或 ~/.nyaterm-preview/mcp/discovery.json（Preview），也接受环境变量 NYATERM_MCP_DISCOVERY 或插件配置项 discoveryFile。

工具集¶

插件自己持有 MCP 连接，只注册下面这套 nt_* 工具；NyaTerm 的原始工具不进工具表，因此没有绕过工作区校验的面。

典型流程是 nt_connections → nt_open → nt_exec → nt_output：先列出可用连接，再开标签页，再执行命令，最后读输出。

权限模型¶

权限分三层。

第一层是 NyaTerm 侧：External MCP 的 permission_mode（confirm 弹窗逐条批准 / auto 直接执行）与 session_scope，这是最后一道闸。

第二层是 allowlist：工作区到分组、主机、连接的映射，未列出的工作区默认拒绝。

第三层是守卫 ctx.tools.guard()：对所有 nt_* 调用做单调同步复核，返回的拒绝无法被后续监听器翻盘；observe: true 的工作区还会顺带拦掉无关工具。

allowlist 的读写操作一律走工具体内已 await 的校验做主判，守卫只作兜底，因为守卫是同步的，拿不到连接列表。

配置 allowlist¶

首选在图形界面里改：DSH 设置 → NyaTerm 白名单（客户端插件，页面左右栏与「远程工作区」同一位置）。它从 NyaTerm 实时拉取分组、连接，工作区从 DSH 的工作区列表里选，保存后立即生效。

底层是一个 JSON 文件，位置由 storeDir 决定；为空时默认 <home>/.dsh/nyaterm-bridge/，全局、与任何工作区和进程 cwd 无关。注意配置里的 ~ 不会被展开，也不要在共享配置里写死某个用户的路径。

{
  "workspaces": {
    "/Users/you/project": {
      "connections": ["2bf46e9f-…"],
      "observeConnections": ["c4bb63a6-…"],
      "groups": [], "hosts": [],
      "observeGroups": [], "observeHosts": [],
      "observe": false
    },
    "C:/work/lab-*": { "observe": true }
  }
}

每个工具调用都会重新读这个文件，所以改完直接重试即可，无需重启；写入走 tmp + rename 原子替换。

几个要点：

1、connections / groups / hosts 授予可读写；平行的 observeConnections / observeGroups / observeHosts 授予只读。

2、可写意味着能 nt_open 开会话、能 nt_exec 执行命令；只读意味着能开会话、能 nt_output 读输出，但不能执行命令。想完全禁止，就连这条规则都别给。

3、observe: true 让整个工作区只读，覆盖上面所有授予。

4、优先级是连接 id > 主机名 > 分组，同一层级里「只读」赢。所以「一组只读、只给某个管理服务器开读写」用一条规则就能写清楚。

5、匹配规则：* 是单层路径，** 是任意深度，多个模式命中时长者优先。反斜杠与 / 等价，Windows 盘符大小写不敏感。

6、未列出即拒绝，除非插件配置 defaultObserveOnly: true，那时降级为只读：可开会话、读输出，不能执行。

设置 MCP 程序位置¶

nyaterm-mcp 和 NyaTerm 一起安装，路径随安装方式和用户变化，所以插件不写死路径，按下面顺序解析：已保存在 allowlist.json 里的 bridgeExecutable（最高优先级）→ 插件配置里的 bridgeExecutable（部署级默认值）→ 平台候选路径，最后走 PATH。

图形界面在 DSH 设置 → NyaTerm 白名单 → MCP 程序位置。可以直接填完整路径（支持带引号的路径、~、%LOCALAPPDATA% 这类变量），也可以点「自动检测」扫描本机已安装的 nyaterm-mcp，或点「恢复自动」清空覆盖。

保存后立即生效，下一次 nt_* 调用会按新路径重新拉起 bridge，不需要重启 DSH。保存时插件会校验文件确实存在、是普通文件、可执行（Windows 只查存在），并且文件名必须是 nyaterm-mcp / nyaterm-mcp.exe。底层就是 allowlist 存储文件里的一个键：

{
  "bridgeExecutable": "C:\\Users\\me\\AppData\\Local\\Programs\\NyaTerm\\nyaterm-mcp.exe",
  "workspaces": { "...": {} }
}

nt_status 会显示最终选中的路径、来源（saved setting / plugin config / auto-detect）以及路径校验结果。

插件配置¶

cordis.patch.yml 中的默认配置项如下，一般只用到 enabled 和 enforceAllowlist：

- insert:
    - id: nyaterm-bridge
      name: 'nyaterm-bridge'
      config:
        enabled: true
        enforceAllowlist: true
        defaultObserveOnly: false
        # storeDir: /home/you/.dsh/nyaterm-bridge
        # bridgeExecutable: 部署级默认路径；留空 = 自动检测
        # discoveryFile: /home/you/.nyaterm/mcp/discovery.json
        # allowOtherTools: true
        # observeTools: []
        # workspaces: {}   # 内联 allowlist，优先级高于 allowlist.json

跨平台行为¶

插件本身不含原生模块，宿主逻辑全部用 node 内置模块，客户端半是纯 DOM。平台差异集中在「找 bridge」和「路径匹配」两处。bridge 定位按 设置页的 bridgeExecutable → 插件配置的 bridgeExecutable → 平台候选表 → PATH 查找的顺序；候选表覆盖 macOS 的 /Applications 与 ~/Applications、Windows 的 %LOCALAPPDATA%\Programs 与 %PROGRAMFILES%、Linux 的 /usr/bin、/usr/local/bin。

发现目录用 os.homedir() 解析（Windows GUI 进程通常没有 HOME）；bridge 路径里含 “Preview” 时优先 ~/.nyaterm-preview，否则优先 ~/.nyaterm。工作区 glob 会把 pattern 与 cwd 归一化为 /、去掉尾部分隔符、Windows 盘符统一大写，* 不跨分隔符、** 跨任意层；匹配保持大小写敏感。

Windows / Linux 上不必提前知道安装路径，默认按平台候选位置和 PATH 自动找。某个用户装在自定义目录时，让他打开 设置 → NyaTerm 白名单 → MCP 程序位置 填一次即可，该值只存在他自己的 allowlist.json 里。

已知限制¶

在决定是否采用前，下面这些限制需要先了解。

1、NyaTerm 的 MCP 不返回主机明细（host/port/username 被刻意隐藏），所以 allowlist 只能按分组路径、连接 id、连接名称来写。

2、NyaTerm 的 MCP 没有关闭会话的工具，nt_open 开出来的标签页需要手动关闭。

3、nt_exec 必须带 sessionId（allowlist 生效时）。不带 sessionId 就无法判断目标连接，插件会拒绝，这是刻意的。

4、NyaTerm 的 MCP 命令是带外执行的：命令不会出现在终端标签页里，其审计日志记为 insertedToTerminal: false；每次 nt_exec 都是新 shell，cwd 和变量不延续。想看命令在终端里跑，只能用 NyaTerm 自带的 AI 命令卡片。

5、组规则只能由工具主体校验，守卫只认显式 connectionId，nt_open 的越权拦截以主体为准。

6、NyaTerm 重启后端口和 token 会变，插件会重新读发现文档并重连。

7、sftp_* 工具没有暴露，文件操作继续交给 dsh-remote 的 rw_*，避免两套文件通道打架。

适用场景与注意¶

适合已经在用 NyaTerm 管理 SSH / 串口 / SFTP 连接、希望 AI 直接复用这批连接、并且需要命令留痕和细粒度授权的团队或个人。想用 NyaTerm 的连接资产、又不想自建一套命令执行通道的场景，会比较对口。

需要留意的是，插件以当前 dsh 进程的权限运行，能执行的动作受该进程权限约束。安装前应检查源码与许可证（README 的 package.json 标注 MIT，作者为 visualcjy，插件版本 0.1.0）。权限模型是插件层加 NyaTerm 层的组合，只有两层都按预期配置时，白名单的限制才完整。

结尾¶

nyaterm-bridge 的价值在于把「AI 执行命令」这件事挂回到你已经在用的终端和连接上，同时保留可观察、可批准、可审计和按工作区授权这四件事。目录页在 https://www.skillhub.cn/plugins/visualcjy/nyaterm-bridge ，源码在 https://github.com/visualcjy/nyaterm-bridge 。