前言¶

在 DSH 里用 @tencent-connect/dsh-qqbot 把助手接到 QQ 群或私聊时，模型默认仍可能看到读文件、改代码、跑命令等一整套工具。即便你在 qqbot 侧配置了 access 白名单，群友一句「列一下你电脑上的目录」仍可能触发模型去解释权限或尝试调用本地能力。dsh-qqbot-guard 是社区维护的 DSH 插件，在模型请求层把 QQ 会话的工具收窄到白名单，并追加可编辑的 system-prompt 规则，让机器人在被问到本机或自身机制时用角色口吻回避。下面介绍它的定位、安装方式与使用时的边界。

这是什么¶

dsh-qqbot-guard（仓库 Chr1sut1na/dsh-qqbot-guard）由维护者 Chr1sut1na 发布，在 SkillHub 目录中归类为 admin-security。它面向已使用 dsh-qqbot 的场景，提供策略层防护：从发往模型的请求里移除不在白名单内的工具 schema，并可选地注入「角色内回避」提示词。README 明确说明这不是沙箱；识别依赖 dsh / dsh-qqbot 的内部事件（system-prompt/assemble 与 qqbot:scope-prompt section），上游改名时会静默失效（fail-open），因此仍需保留 qqbot 的 access 白名单，不能把本插件当作唯一隔离边界。

核心功能¶

工具防火墙¶

插件识别 QQ 机器人会话后，把模型请求中的工具收窄到白名单。默认只允许 web_search、web_fetch。模型看不到的工具就无法被调用，因此 read、write、edit、grep、glob、pwsh、qqbot_send_file、subagent、workflow、schedule_* 等本地或高权限能力在 QQ 侧会失效。

可在「设置 → QQ 机器人边界守卫」中编辑工具白名单，或在 cordis.patch.yml 的 qqbot-guard 行里用 config.tools 覆盖（mode: allow / deny，以及 allow / deny 列表）。

角色内回避¶

对 QQ 机器人追加一段 system-prompt 规则，遇到列目录、读文件、跑命令、查系统信息，或「你是不是 AI」「什么模型」等提问时，用角色口吻装听不懂，而不是解释「我没有这个工具/权限」。规则文本可在设置页编辑；留空则使用内置规则。设置页修改优先于 YAML 与内置默认。

设置页与状态¶

安装后会出现「设置 → QQ 机器人边界守卫」面板：可编辑约束提示词、开关规则、编辑工具白名单、查看运行状态。保存后下一轮请求即生效。状态区可查看命中次数、移除工具数、最近命中依据；也可通过 GET /qqbot-guard/config 查看 JSON。

配置优先级为：设置页写入的 ~/.dsh-qqbot-guard/config.json > cordis.patch.yml 中 qqbot-guard 行的 config > 内置默认。

可选补丁：注意力闸¶

若希望机器人在群里不要每条消息都接话，只在被 @、被叫名字，或话题命中兴趣词时才开口，可额外应用仓库内 patches/attention-gate/ 的补丁。这是对已安装 qqbot 的补丁，不是独立插件；每次升级 qqbot 后需要重跑：

powershell -ExecutionPolicy Bypass -File .\patches\attention-gate\apply.ps1

细节见仓库中 patches/attention-gate/README.md。

安装与启用¶

推荐通过 DSH 插件管理器安装，装完后会作为组合包出现在「插件」页，可启停与卸载。

桌面客户端：插件 → 添加插件（箭头）→ 安装第三方插件，填写 tarball 路径、包目录或 Git 包 spec（注意：https://github.com/... 网页地址不是合法包 spec）。

命令行 profile 示例：

dsh plugin --profile <profile名> add ./dsh-qqbot-guard-0.1.2.tgz
# 或目录形式
dsh plugin --profile <profile名> add ./dsh-qqbot-guard
# 或从 GitHub 安装（推荐 github: 形式）
dsh plugin --profile <profile名> add github:Chr1sut1na/dsh-qqbot-guard

Electron 桌面版独占的 profile（如默认 desktop）会拒绝 CLI 操作，需在客户端「安装第三方插件」中填写 github:Chr1sut1na/dsh-qqbot-guard 或本地包路径。

安装后建议确认：「插件」页出现 dsh-qqbot-guard 卡片；「设置」里出现「QQ 机器人边界守卫」；<profile>\package.json 的 dependencies 与 dsh.profile.bundles 均包含该包。当前 package 版本为 0.1.2，要求 Node >=20.3.0；README 注明在 dsh-desktop 0.2.1-rc.2 与 @tencent-connect/dsh-qqbot 0.5.2 上验证。

手动复制到 node_modules 并在 cordis.patch.yml 插入 qqbot-guard 行仅适合调试，不会出现在「插件」页；勿与插件管理器安装同时使用，以免重复加载。

典型配置示例¶

高级项可在 cordis.patch.yml 整行替换 qqbot-guard 配置，例如：

- id: qqbot-guard
  name: 'dsh-qqbot-guard'
  config:
    tools:
      mode: allow
      allow: [web_search, web_fetch]
      deny: []
    detect:
      sections: [qqbot:scope-prompt]
      cwdPrefixes: []
      toolNames: []
    persona:
      enabled: true
      name: qqbot:no-machine
      order: 95
      text: ''

若升级 dsh 或 dsh-qqbot 后状态计数不再增长，可能是 section 名称变化导致 fail-open；可临时用 detect.cwdPrefixes（如机器人工作目录前缀）或 detect.toolNames 作兜底，并在设置页核对命中依据。

卸载：CLI 安装使用 dsh plugin --profile <名> remove dsh-qqbot-guard；手动安装则删除 cordis.patch.yml 中对应 insert 行及 node_modules\dsh-qqbot-guard 目录。

适用场景与注意¶

适合：已通过 dsh-qqbot 对外提供 QQ 对话，希望在模型可见工具这一层默认只保留联网检索类能力，并降低群友用话术套取本机信息或模型身份时的「老实回答」风险。

务必知晓的限制：

1. 策略层：插件只是在模型请求里删掉工具 schema，不是操作系统级沙箱；插件与 qqbot 以当前 dsh 进程权限运行，安装前应阅读源码与 MIT 许可证，并自行评估是否满足合规要求。
2. fail-open：上游事件或 section 改名后，识别可能失效且不报错，工具会原样放行；升级后先看设置页状态或 GET /qqbot-guard/config。
3. 提示词非硬边界：角色内回避可被极端越狱绕过，不能替代 qqbot access 与运维层面的访问控制。

结尾¶

dsh-qqbot-guard 把 QQ 侧对话收窄到「默认两个联网工具 + 可编辑角色规则」，并附带可选的群聊注意力闸补丁，适合作为 qqbot 白名单之外的补充策略。目录页：SkillHub - dsh-qqbot-guard；源码与完整说明：GitHub - Chr1sut1na/dsh-qqbot-guard。