前言¶

在 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。