前言¶

在 DSH 裏跑自動化時，常見矛盾是：希望機器人在固定時機幫你執行腳本或託管任務，又不想把「任意命令執行」交給 DSH 沙箱或模型側。另一種做法是 SSH、遠程桌面或自建 Bot，各自要維護通道和權限邊界。

下面介紹的是 DSH Host 插件 dsh-qq-shell-commands（維護者 EviMing，分類：工作流）。它通過 NapCat 收 QQ 私信，按配置裏的暗號精確匹配後，在 DSH 所在電腦的當前用戶 下執行 Shell，並把結果私信回主人。QQ 只作觸發器，命令不經過 DSH 執行引擎。倉庫在 GitHub 上星標爲 0；能力等價於遠程命令執行（RCE），部署前需讀完官方 README 中的安全說明。

這是什麼¶

dsh-qq-shell-commands 連接 NapCat 的 OneBot 11 WebSocket，監聽私聊（默認不接受羣消息）。消息格式與配置中 commands 的鍵做 完全相等 比較（不 trim 正文、不模糊匹配；鍵加載時會去掉首尾空白）。命中後按 [Shell 命令, Shell 名稱] 在宿主機啓動對應 Shell；發私信複用前置插件 EviMing/dsh-napcat-tools 提供的 napcat_api 與 lib/runner.mjs 的 runCli。

默認執行前綴爲 執行Shell命令： 加換行再加暗號文本；管理員可通過 增加 Shell 命令： 加 JSON 動態增改命令表（需落在 adminSenders 白名單）。

工作流概覽¶

一條典型鏈路如下：

QQ 私信「執行Shell命令：」+ 換行 +「回聲」
  → 暗號「回聲」與 commands 鍵完全相等
  → 命中 {"回聲": ["echo 1", "cmd"]}
  → 宿主機執行 cmd echo 1
  → 私信主人：開始執行 / 已執行（退出碼、耗時、輸出）

插件入口與模塊劃分見倉庫 README：index.js 負責配置、前置插件、WebSocket 與分發；lib/dispatcher.mjs 處理匹配、權限與執行；lib/shell.mjs 封裝 cmd、PowerShell、pwsh、bash、wsl 等 argv 與超時殺進程。

前置條件¶

部署前需同時滿足：

1. DSH 已安裝，並可啓動 Web GUI 或 headless profile。
2. 前置插件 EviMing/dsh-napcat-tools 已安裝並啓用（Python 3.10+ 可執行 python -m napcat_api）。
3. NapCat 已登錄機器人 QQ，並開啓 OneBot 11 WebSocket（默認 ws://127.0.0.1:3001）與 HTTP（默認 http://127.0.0.1:3000，供 napcat-tools 發消息）。
4. 本插件要求 Node.js >= 22（見 package.json 的 engines）。

安裝與啓用¶

從 DSH 插件市場¶

倉庫帶有 dsh-plugin topic，會被 DSH-Plugins-Marketplace 索引；可在 DSH 插件市場搜索 QQ Shell 或 dsh-qq-shell-commands。

從 GitHub 安裝¶

先裝前置插件，再裝本插件，安裝後重啓 DSH（Host 插件在啓動時加載）：

# 先裝前置插件
dsh plugin --profile web add github:EviMing/dsh-napcat-tools

# 再裝本插件
dsh plugin --profile web add github:EviMing/dsh-qq-shell-commands

若需顯式指向前置插件目錄，可在 profile 配置中設置 prereqDir（須爲包含 package.json 且 name 爲 @local/napcat-tools 的目錄）。兩插件裝在同一 profile 時，prereqDir 留空可自動解析同級 @local/napcat-tools，也可設置環境變量 NAPCAT_TOOLS_DIR。

示例片段（路徑按本機修改）：

- insert:
    - id: qq-shell-commands
      name: dsh-qq-shell-commands
      config:
        configFile: ''
        prereqDir: 'C:\Users\you\.dsh\profiles\web\node_modules\@local\napcat-tools'

配置¶

默認配置文件位於 DSH 主目錄下的 qq-shell-commands.json（Windows 常見路徑爲 C:\Users\<you>\.dsh\qq-shell-commands.json）。文件在插件包外，重裝或升級插件不會丟失。可複製倉庫中的 config.example.json 作爲模板。

核心字段包括：

• selfQQ / ownerQQ：機器人 QQ 與主人 QQ；事件 self_id 必須等於 selfQQ，否則插件停擺。
• formats.execute / formats.add：執行與增改命令的文本前綴，支持模板或關閉增改功能。
• commands：形如 {"文本": ["Shell 命令", "Shell 名稱"]}。
• allowedSenders / adminSenders：可觸發執行與可寫命令表的白名單；主人始終在內。
• allowGroup：是否接受羣消息，默認 false。
• napcat.ws / napcat.token：WebSocket 地址與 access_token。
• shell.cwd / shell.timeoutMs：命令工作目錄與超時（默認 600000 ms，超時會殺掉整棵進程樹）。
• notify.*：是否先發「開始執行」、輸出保留行數與私信最大字符數。

完整示例與字段說明見 GitHub README；此處不重複整張表。

支持的 Shell 名稱包括 cmd、PowerShell / ps、pwsh、bash / sh、wsl 等；命令須非交互（stdin 爲空），否則會一直等到超時。

典型用法¶

用主人 QQ 私聊機器人：

執行Shell命令：
回聲

若配置了 "回聲": ["echo 1", "cmd"]，會收到類似「開始執行」與「命令已執行」的私信，內含主機名、實際 argv、退出碼、耗時與 stdout/stderr 末尾若干行。失敗或超時分別標註 【命令失敗】 / 【命令超時】。

管理員私聊增改命令（默認格式）：

增加 Shell 命令：{"備份": ["Copy-Item 'D:\\data' 'E:\\backup' -Recurse -Force", "PowerShell"]}

寫入成功後立即生效，無需重啓 DSH；解析或權限失敗會私信 【添加失敗】原因。

適用場景與注意¶

適合需要在手機上用固定暗號觸發宿主機腳本、備份、通知類 PowerShell 等重複工作，且 deliberately 不把執行權交給 DSH 本身的場景。

務必注意：

• 命令以 DSH 宿主機當前用戶 權限運行，不經過 DSH 沙箱；配置文件寫權限等價於命令執行權，adminSenders 等價於命令表寫權限。
• 默認僅接受主人私聊；未授權發送者的暗號不會執行，也不會回覆。
• 不要把 DSH Web 端口或 NapCat HTTP/WebSocket 暴露到不可信網絡；暗號鍵是明文，勿把密碼或 token 寫進命令或通知。
• 安裝前應閱讀倉庫源碼與 MIT 許可證，自行評估 RCE 風險。

本地可運行 node test/selftest.mjs 做不依賴 DSH 的斷言；boot-check.mjs、live-ws.mjs 需真實配置與 NapCat。

結尾¶

dsh-qq-shell-commands 把 QQ 私信變成宿主機 Shell 的觸發器，依賴 dsh-napcat-tools 與 NapCat，適合「託管行爲但不把 DSH 當執行面」的工作流。目錄頁：https://www.skillhub.cn/plugins/EviMing/dsh-qq-shell-commands；源碼與完整配置說明：https://github.com/EviMing/dsh-qq-shell-commands。