前言¶

DeepSeek Harness（DSH）把智能体能力放在可扩展的插件体系里；要在 QQ 里和用户对话，通常还要单独搭 OneBot 协议端、自己写消息转发和会话隔离。社区维护者 Jiangsubei 的 dsh-napcat-bridge（npm 包名 dsh-napcat-bridge）把 DSH 与 NapCat 接在一起：基于 OneBot 11 反向 WebSocket，在群聊和私聊里开箱即用，并带 QQ 专属预设、记忆、权限与 WebUI 配置。下面介绍它是什么、能做什么，以及如何安装与对接 NapCat。

这是什么¶

dsh-napcat-bridge 是 DeepSeek Harness × NapCat QQ 接入插件，分类属于 DSH 生态里的客户端方向插件。仓库：https://github.com/Jiangsubei/dsh-napcat-bridge；社区目录页：https://www.skillhub.cn/plugins/Jiangsubei/dsh-napcat-bridge。许可证为 MIT；当前资料中的 npm 版本为 0.2.8，要求 DSH >= 0.2.0、Node.js >= 22.12.0（受 better-sqlite3 约束）。

SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系；安装前建议自行查看源码与许可证。插件在当前 DSH 进程权限下运行，群聊默认只读等工作区权限策略需结合自己的部署环境理解。

核心功能¶

接入与会话隔离¶

• QQ 群聊 / 私聊经 NapCat 反向 WebSocket 接入 DSH。
• 专属预设 qq-session：构建期与运行时 SSOT 同步，QQ 工具集只注入 QQ 会话，避免向 Web UI 常规会话泄露；并补齐工作区、跨平台 Shell（Windows pwsh / Linux bash）、Web 搜索、交互提问与技能等能力。
• 用户侧静默出站：纯文本不再直接推流；文本统一由 send_qq_message 驱动，模型根据入站标头 [消息ID: <id>] 决定是否 reply_to 或 at_user。
• 出站工具与回合解耦：调用出站工具不强行结束回合，同一轮可继续用记忆、表情等工具。

记忆、表情与黑话¶

• 两层记忆：群聊会话记忆 + 用户跨群画像，Markdown 存储；工具 read_memory、create_memory、edit_memory；写入侧有用户画像、Session 规则、群聊画像总预算三套字符上限，超限硬拒绝落盘。
• 表情包（受 face_enabled 门控）：list_faces、send_face、collect_face、manage_faces，以及群聊 react_message；库容与 LRU 等策略可配。
• 黑话学习（SQLite + 工具 query_slang、record_slang、manage_slang）：动态注入 L1 索引，支持 LRU 淘汰；默认 slang_enabled 为 true。

消息、权限与群聊策略¶

• 单对端串行出站队列；支持私聊文件入站落盘、群文件索引 list_group_files、fetch_chat_resource、expand_forward_message 等。
• 群成员与定时任务：get_group_member_info；schedule_task、manage_scheduled_tasks。
• 卡片消息通用提取（小程序、分享、音乐等标题与链接）。
• 群聊主动回复：窗口期聚合、潜水超时破冰、Agent 繁忙丢弃、夜间免打扰（默认 23:00–08:00）；new_message_behavior 可选 steer（插话）或 queue（入队）。
• 斜杠命令（两字中文）：/新建、/会话、/用量、/停止、/模型、/权限、/思考、/状态、/帮助；管理员白名单 admins。
• 黑名单与权限：私聊/群聊发言黑名单（命中不唤醒、不回复，管理员不豁免）；新建会话默认权限（私聊默认 workspace-write、群聊默认 read-only）及 QQ 号/群号例外；Coding 工具组可按场景裁剪，只读工具 read_image 与 working_directory 始终保留。

WebUI 配置¶

DSH Web UI 中提供 dsh-napcat-bridge 设置卡片，7 个 Tab、共 40 项参数，支持 volatile 热更新（连接、人格与准则、回复、权限与安全、记忆、表情包、黑话学习）。

安装与启用¶

前置条件¶

• 已安装 DeepSeek Harness（例如 npm install -g @deepseek-ai/dsh），版本 >= 0.2.0。
• 已部署 NapCat 作为 QQ 协议端。
• Node.js >= 22.12.0；从源码开发时需 pnpm >= 9.0.0。

安装插件（推荐 npm）¶

CLI 环境：

# 安装到 DSH 的 web profile
dsh plugin --profile web add dsh-napcat-bridge

# 或安装到全局默认环境
dsh plugin add dsh-napcat-bridge

DSH Desktop 无 dsh CLI 时，在「插件 → 添加插件」中输入包名 dsh-napcat-bridge 安装。npm 包内置编译产物与 cordis.patch.yml，安装后重启 DSH 生效，常规安装不触发 better-sqlite3 本地编译。

对接 NapCat 并启动¶

1. 在 NapCat WebUI（默认 http://127.0.0.1:6099/webui）新增反向 WebSocket 客户端：
   - URL：ws://127.0.0.1:8080/（插件绑定环回 127.0.0.1，端口与 ws_port 一致，默认 8080）
   - Token：必填，与插件 ws_token 完全一致（不一致或未配置时握手拒绝，401）
   - 心跳周期 30000 ms，重连间隔 3000 ms
2. 启动 DSH：

dsh --profile web

3. 打开 DSH Web UI（默认 http://127.0.0.1:3080/），进入 dsh-napcat-bridge 设置，至少填写：
   - ws_token：与 NapCat 一致（空值会被拒绝连接，WebUI 保存亦会校验）
   - bot_qq：机器人 QQ 号（过滤自身消息、识别 @）
   - admins：可执行斜杠命令的管理员 QQ 号

其余如 aliases 点名、proactive_* 主动回复、记忆预算、face_enabled、slang_* 等按需保存，即时热更新。

典型用法¶

在 QQ 里对话¶

NapCat 与 DSH 连通且必填项保存后，用户在群聊 @ 机器人或使用配置的 aliases 点名，或在私聊发消息，即可触发 QQ 专属会话。模型通过 send_qq_message 回复；是否引用、是否 @ 由工具参数决定，不再使用已下线的固定「群聊强制引用/艾特」配置项。

管理员斜杠命令¶

管理员 QQ 号写入 admins 后，可在 QQ 内使用 /帮助 等命令管理会话、用量、模型、权限、思考模式与状态；具体行为以实现为准，权限严格依赖白名单。

记忆与群文化维护¶

Agent 可在对话中调用记忆工具维护用户画像与群 Session 规则；开启 slang_enabled 后可通过黑话工具沉淀群词条；开启 face_enabled 后可在新会话中装载表情工具链（对已存在会话需按 README 说明理解「对新会话生效」的门控语义）。

适用场景与注意¶

适合：已有 NapCat + DSH 部署、希望在 QQ 群/私聊统一跑 Agent，并需要会话与工具隔离、权限分级、可选主动回复与群文化（记忆/表情/黑话）能力的团队或个人。

注意：

• 插件依赖本地 WebSocket 网关与 Token 鉴权，生产环境应使用强 ws_token，并理解默认只监听 127.0.0.1。
• 群聊默认 read-only 与群聊默认关闭 Coding 工具组是安全向默认值；需要写工作区或 bash 时应显式调整默认或例外表，并评估 DSH 进程权限。
• 发言黑名单命中后永不回复，包括管理员；误配前请确认列表。
• 社区目录页星标等数据会变动；以 GitHub 与 npm 页面为准。

结尾¶

dsh-napcat-bridge 把 DSH Agent 接到 NapCat/OneBot 11 上，用 qq-session 预设和静默出站模型把 QQ 场景与 Web 会话隔开，再用 WebUI 四十项参数覆盖连接、人格、主动回复、权限、记忆、表情与黑话。若要进一步了解参数表与开发构建，见仓库 README：https://github.com/Jiangsubei/dsh-napcat-bridge；插件索引：https://www.skillhub.cn/plugins/Jiangsubei/dsh-napcat-bridge。