前言¶

給智能體寫命令執行能力時，常見做法是給模型配一個臨時 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 。