QQ 智能体接入 Jiangsubei/dsh-napcat-bridge

dsh-napcat-bridge

DeepSeek Harness × NapCat QQ 接入插件 —— 既是随叫随到的专业助手，也是懂梗斗图、能学黑话、主动冒泡的灵魂群友。让 DSH 智能体在 QQ 群聊 / 私聊中开箱即用。

✨ 功能特性

- QQ 群聊 / 私聊全场景接入：基于 NapCat（OneBot 11 协议）反向 WebSocket 连接。
- QQ 会话专属预设（qq-session）：构建期与运行时单一真相源（SSOT）自动同步，专属注入 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）与库容维护/LRU 淘汰（manage_faces）闭环工具链；另有群聊 react_message 贴表情轻量表态。
- 串行发送与多媒体交互：单对端串行出站队列，避免并发乱序；支持私聊文件入站自动落盘、群共享文件索引查询（list_group_files）、动态资源拉取（fetch_chat_resource）与合并转发展开（expand_forward_message）。
- 卡片消息通用提取器：自动提取 QQ 卡片（小程序、分享、音乐等）的标题与链接。
- 群聊主动回复策略：普通消息窗口期聚合轮询 + 潜水超时破冰 + 智能体繁忙丢弃 + 夜间免打扰，支持「仅回复文本内容」过滤并赋予智能体 [结束] 静默决策权。
- 纯两字中文斜杠命令：/新建、/会话、/用量、/停止、/模型、/权限、/思考、/状态、/帮助，内置严格的管理员白名单权限隔离与 per-session 状态管理。
- 发言黑名单与权限安全防线：支持私聊与群聊发言黑名单（入库留存审计但永不唤醒与回复，管理员亦不豁免）；支持新建会话默认权限（私聊默认 workspace-write、群聊默认 read-only）及针对指定 QQ 号/群号的权限例外表；支持 Coding 工程工具组（bash/pwsh/read/write/edit）按私聊/群聊及例外表裁剪硬隔离（只读工具 read_image 与 working_directory 始终保留）。
- WebUI 设置面板：通过 DSH Web UI 配置所有插件参数，7 大 Tab 分组（连接设置、人格与准则、回复配置、权限与安全、记忆、表情包、黑话学习），全部 39 项参数支持 volatile 动态热更新。

📦 安装与启动

前置条件

- DeepSeek Harness (npm install -g @deepseek-ai/dsh) >= 0.2.0
- NapCat（QQ 机器人协议端）
- Node.js >= 22.12.0（受 better-sqlite3 原生依赖约束，低于此版本无法加载）
- pnpm >= 9.0.0（仅源码安装需要）

方式一：从 npm 安装（推荐）

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

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

[!NOTE]
Desktop 版没有 dsh 命令行，请在 DSH「插件 → 添加插件」里直接输入包名 dsh-napcat-bridge 安装。

npm 包已内置编译产物与 cordis.patch.yml，安装后重启 DSH 即生效，无需本地构建。better-sqlite3 自带 8 平台预编译二进制，常规安装不触发 node-gyp 编译。

方式二：从源码安装（开发 / 调试）

[!IMPORTANT]
DSH 通过 package.json 的 main -> dist/index.js 与 dsh.bundle.patch 加载插件。在执行 link 之前必须先运行 pnpm build 生成编译产物与预设同步补丁。

git clone https://github.com/Jiangsubei/dsh-napcat-bridge.git
cd dsh-napcat-bridge

安装依赖并编译（内置 sync-patch 预设同步、tsc 编译与客户端面板构建）
pnpm install
pnpm build

link 安装到 DSH 的 web profile
dsh plugin --profile web add link:.

配置与运行

1. NapCat 添加反向 WebSocket 客户端：在 NapCat WebUI（默认 http://127.0.0.1:6099/webui）的网络配置中新增反向 WebSocket 客户端：
- URL：ws://127.0.0.1:8080/（插件显式绑定本地环回地址 127.0.0.1，端口需与插件 ws_port 对齐）
- Token：必填项，必须与插件 ws_token 保持一致（严禁留空；若未配置或两端不一致，网关握手将直接拒绝连接并返回 401 Unauthorized）
- 心跳周期：30000 ms，重连间隔：3000 ms
2. 启动 DSH：
dsh --profile web

3. DSH WebUI 配置核心参数：访问 DSH Web UI（默认 http://127.0.0.1:3080/），进入 dsh-napcat-bridge 设置卡片（标有 的为必填字段）：
- ws_token（核心必填项）：NapCat 连接鉴权 Token。用于网关握手安全鉴权，留空时网关将直接拒绝连接并产生警告；WebUI 保存时服务端亦会强校验拦截空 Token（返回 400 Bad Request）。
- bot_qq（核心必填项）：填写机器人的 QQ 号，用于过滤自身消息防死循环，并作为群聊识别 @机器人的基准。
- admins：填写管理员 QQ 号，授权执行斜杠命令。
- 其他可选参数（人设、主动回复、记忆预算、表情包开关等）按需调整，保存即时热更新生效。

⚙️ 运行时配置 (39 项)

配置卡片在 WebUI 中分为 7 个 Tab：

1. 连接设置 (Connection)

| 参数 | 类型 | 默认值 | 说明 |
| ws_port | number | 8080 | WebSocket 监听端口（NapCat 连接目标，变更时服务热重启） |
| ws_token | string | "" | 连接鉴权 Token（必填项，空着直接拒绝连接） |
| bot_qq | string | "" | 机器人自身 QQ 号（核心必填项，自循环防护与识别锚点） |
| admins | string[] | [] | 管理员 QQ 号白名单（斜杠命令授权） |
| aliases | string[] | [] | 助手点名别名（群聊点名唤醒） |
| image_ttl_days | number | 7 | 外来图片与多媒体缓存本地保留天数（过期定时清理） |

2. 人格与准则 (Persona & Behavior)

| 参数 | 类型 | 默认值 | 说明 |
| persona | string | (内置)* | 助手的人格设定（注入 System Prompt 动态段） |
| behavior | string | (内置) | 行为约束准则（注入 System Prompt 动态段） |

3. 回复配置 (Proactive)

| 参数 | 类型 | 默认值 | 说明 |
| proactive_reply_enabled | boolean | false | 启用群聊主动回复功能总开关 |
| proactive_interval_mins | number | 3 | 主动回复轮询窗口期（分钟，期间有新消息才唤醒） |
| proactive_buffer_size | number | 10 | 主动回复滑动窗口消息保留条数 |
| proactive_random_enabled | boolean | false | 启用群聊普通消息随机概率唤醒 |
| proactive_random_probability | number | 0.05 | 普通消息随机唤醒概率（0~1，0.05 即 5%） |
| proactive_cooldown_mins | number | 10 | 主动回复冷却时间（分钟，防止频繁插话） |
| proactive_only_text | boolean | false | 仅回复纯文本内容（多模态媒体消息不主动触发） |
| proactive_idle_enabled | boolean | false | 启用潜水超时主动唤醒（冷场破冰冒泡） |
| proactive_idle_timeout_mins | number | 120 | 潜水超时阈值（分钟） |
| proactive_night_dnd | boolean | true | 夜间免打扰 (每日 23:00~08:00 暂停主动回复) |

4. 权限与安全 (Security)

| 参数 | 类型 | 默认值 | 说明 |
| private_blacklist | BlacklistItem[] | [] | 私聊发言黑名单列表（命中则不唤醒、不回复，管理员亦不例外） |
| group_blacklist | BlacklistItem[] | [] | 群聊发言黑名单列表（命中则不唤醒、不回复，管理员亦不例外） |
| session_permission_private_default | string | "workspace-write" | 私聊新建会话初始权限模式（workspace-write / read-only / danger-full-access） |
| session_permission_group_default | string | "read-only" | 群聊新建会话初始权限模式（read-only / workspace-write / danger-full-access） |
| session_permission_overrides | SessionPermissionOverride[] | [] | 针对特定 QQ 号或群号的新建会话初始权限例外覆盖表 |
| coding_tools_private_default | boolean | true | 私聊新建会话是否默认装载 Coding 编码工具组 |
| coding_tools_group_default | boolean | false | 群聊新建会话是否默认装载 Coding 编码工具组（默认关闭，安全推荐） |
| coding_tools_overrides | CodingToolsOverride[] | [] | 针对特定 QQ 号或群号的 Coding 工具组装载例外覆盖表 |

5. 记忆 (Memory)

| 参数 | 类型 | 默认值 | 说明 |
| memory_storage_dir | string | ".dsh/napcat/napcat_memory" | 记忆 Markdown 文件根存储目录 |
| user_profile_budget_chars | number | 2200 | 单个用户画像文件的写入上限（跨群聊/私聊通用） |
| session_memory_budget_chars | number | 2200 | 单个 Session 规则文件的写入上限（群聊/私聊统一） |
| group_memory_total_budget_chars | number | 8000 | 群聊注入时所有活跃群友画像合计的字符预算；Session 规则不计入 |

6. 表情包 (Face)

| 参数 | 类型 | 默认值 | 说明 |
| face_enabled | boolean | false | 控制新建会话是否在预设中装载表情包工具集（保存对后续新会话生效） |
| face_store_max | number | 100 | 本地表情库存储容量上限（张） |
| face_store_dir | string | ".dsh/napcat/faces" | 本地表情库文件存储目录 |
| face_sub_type | number | 1 | OneBot 11 发送表情使用的 sub_type 字段值 |
| face_evict_policy | string | "evict_lru" | 库容满额淘汰策略 (reject 拒绝 / evict_lru 淘汰最久未用) |

7. 黑话学习 (Slang)

| 参数 | 类型 | 默认值 | 说明 |
| slang_enabled | boolean | true | 控制新建会话是否装载黑话工具集与注入黑话上下文（保存对后续新会话生效） |
| slang_max_entries | number | 300 | 黑话知识库条数容量上限 (默认 300 条) |
| slang_evict_policy | 'reject' \| 'evict_lru' | 'reject' | 黑话满额策略（reject: 拒绝新增, evict_lru: 淘汰模型查阅最少词条） |
| slang_storage_path | string | ".dsh/napcat/slang/slang.md" | 存量旧版黑话 Markdown 迁移源路径 (仅启动时迁移，不删原文件) |

配置下线说明：群聊强制引用/艾特死配置（group_reply_quote、group_reply_at）及空回复行为面板已下线。出站回复遵循「用户侧静默原则」，是否引用与艾特统一由大模型通过 send_qq_message 工具参数（reply_to、at_user）自主决策。独立后台 Agent 参数也已清退下线。

🛠️ 开发与构建

git clone https://github.com/Jiangsubei/dsh-napcat-bridge.git
cd dsh-napcat-bridge
pnpm install
pnpm typecheck
pnpm test:quick # 快速单测
pnpm build # 同步预设、类型编译与构建 WebUI 产物

🧪 测试

本项目遵循严格的契约测试先行与真实装配验证规范，覆盖专属预设单一真相源同步、出站静默工具流、单 Agent 顺手提炼、表情包闭环、两层记忆体系与斜杠命令等场景（60 套件 500+ 测试用例）。

pnpm test # 完整测试（先执行 pnpm build 再执行测试）
pnpm test:quick # 快速执行测试（跳过 build）

📚 文档索引

面向使用者的标准开源文档统一存放于 docs/ 目录：

- 快速上手 (docs/getting-started.md)：环境依赖、安装步骤、NapCat WS 配置与验证指南。
- 系统架构 (docs/architecture.md)：模块总览、生命周期装配、用户侧静默出站体系、记忆与表情体系。
- 配置说明 (docs/configuration.md)：WebUI 7 大 Tab 完整配置项、默认值与迁移说明。
- 工具与命令 (docs/tools-and-commands.md)：send_qq_message 等 13 个 Agent 工具契约与 9 个纯两字中文斜杠命令。
- 故障排查 (docs/troubleshooting.md)：出站静默未调用工具、预设隔离、连接异常等问题排查指引。

📄 License

MIT