QQ对接坞 NimuStudio/NimuQDock-dsh

美感即匠心 · Beauty is the craft

🔌 NimuQDock-dsh

把 DeepSeek Harness 的 AI 停靠进 QQ 的对接坞 · 带人格引擎的仿真群友：心情、精力、记忆，像真人一样潜水与参与

中文 · English

由 Nimu Studio 维护 · 官网 nimustudio.cn

下载

| 方式 | 链接 | 说明 |
| exe（图形安装器，约 30 MB） | GitHub Releases | 自动检测本机组件，勾选要装的 DSH / NapCat / 判断模型 |
| 国内加速（推荐） | gh-proxy 直链 | 固定文件名，始终指向最新版 |
| zip 完整离线包 | Releases 页面的 Assets | 内置 0.6B 模型与推理引擎，解压即用，适合网络不好 |

安装器下载 NapCat、推理引擎、判断模型时会自动走国内镜像；只有 exe 本身需要走上面的加速链接。
安装内容都在安装目录内，卸载删目录即可。

这是什么

NimuQDock-dsh 把 DeepSeek Harness 的智能体请进 QQ 群和私聊：群里有人说话，它就能听见；它想开口时，回复会出现在群里。在此基础上，人格引擎让它不是有问必答的客服，而是一个有心情、有精力、有记忆、会潜水也会冒泡的仿真群友。

一条消息的旅程：

① 群友在 QQ 发言（NapCat 以 OneBot v11 协议上报） │ ▼ ② 桥接进程把消息投入对应的 DSH 会话 │ ▼ ③ agent 思考完毕：产出回复 / 提问 / 工具审批 │ ▼ ④ 结果发回 QQ（chat 模式自动回；agent 模式由 AI 用工具自主收发）

chat 模式：①②③④ 全自动；agent 模式：AI 自己看消息、自己决定回不回、自己挑话题接。

架构

flowchart TB
subgraph QQ["QQ 侧"]
G["QQ 群"]
P["QQ 私聊"]
end
NC["NapCat OneBot v11"]
subgraph BRIDGE["NimuQDock-dsh 桥接"]
R["消息路由 / 会话管理"]
PE["人格引擎：心情 精力 记忆 参与评分"]
CON["Web 控制台 :3100"]
end
DSH["DeepSeek Harness :3080"]

G --> NC
P --> NC
NC -->|WS 3001 / HTTP 3005| R
PE -.状态与评分.-> R CON -.管理 / 远程指令.-> R
R --> DSH
DSH --> R

- QQ 侧：NapCat 负责接入 QQ 协议，把群/私聊消息以 OneBot v11 协议上报
- 桥接进程：收到消息后路由到对应 DSH 会话；agent 的回复（含提问、工具审批）原路发回 QQ
- 人格引擎（agent 模式）：用心情/精力/记忆计算参与意愿，决定"这条要不要接"
- Web 控制台：本地管理界面，可切换模式、调人格、管白名单、发远程指令

截图

| 概览 | 人格卡 |
| 概览 | 人格卡 |

| 远程指令 |
| 远程指令 |

截图中的机器人 QQ 号与群聊内容已打码。

特性

- 🧠 人格引擎：心情 / 精力 / 与群友的关系随互动演化。被怼心情下降，聊得多关系变熟，精力低了倾向潜水
- 🎯 参与意愿模型：不是「每条都回」，而是按「被点名程度 + 话题兴趣 + 精力 + 心情 + 随机扰动」评分，超过阈值才参与——被 @/提问必回，普通闲聊按状态决定
- 💾 分层记忆：群话题滚动统计 + 长期记忆（对群友的印象、没聊完的话题），按相关性自动注入
- 🛡️ 安全边界：QQ 会话物理上没有本地工具，发送强制白名单，回复敏感信息整条拦截，联网搜索带 SSRF 防护
- 🎛️ Web 控制台（玻璃拟态 UI）：人格状态可视化调节、白名单管理、角色卡管理、远程指令面板（完整工具会话）、记忆/日志/会话管理
- 🚀 远程指令面板：登录控制台即可让 DSH 的完整工具（pwsh/文件等）执行任务，结果回显——不经 QQ 传输层

一键安装（Windows）

去 Releases 下载安装包（含全部依赖，无需 npm install）：

| 方式 | 大小 | 操作 |
| exe 安装向导（推荐） | 约 26 MB | 双击 → 勾选组件（程序本体 / DSH / NapCat / 判断模型）→ 选目录 → 安装 → 完成页直接启动 |
| zip 离线包 | 约 410 MB | 解压 → 双击 start.bat（内置 0.6B 模型与推理引擎） |

安装向导会自动检测本机已装的组件（已装好的置灰跳过），下载时会走国内镜像、支持断点续传与 SHA256 校验。
你只需要两件手动事：① 安装 QQ 客户端 ② 扫码登录并配置 OneBot11，最后启动并打开 Web 控制台。

需要 Node.js ≥ 22.13 和已安装的 QQ 客户端（exe 包自带 Node）。

卸载

- exe 安装的用户：Windows「设置 → 应用」里卸载，或运行安装目录下的 uninstall.exe。
- zip / 源码用户：双击项目里的 uninstall.bat。
- 卸载会先停止运行中的桥接与 NapCat 注入进程，再删除安装目录。
- 卸载前会自动把 state/（记忆、日志）和 config.json 备份到「文档\NimuQDock-dsh-backup」，需要时可以手动恢复。

开始使用

需要准备

| 依赖 | 说明 |
| Node.js | ≥ 22.13 |
| DeepSeek Harness | 见下方「先装好 DeepSeek Harness」 |
| NapCat | QQ 协议实现，下载 |
| QQ 账号 | 一个用于机器人的 QQ 号（建议小号） |

先装好 DeepSeek Harness（DSH）

本项目把 AI 放在 DeepSeek Harness 里运行，需要先把它启动起来：

方式一：临时运行（想先试试就用这个）
npx @deepseek-ai/dsh web

方式二：全局安装后运行
npm i -g @deepseek-ai/dsh
dsh web

浏览器打开 http://127.0.0.1:3080 能看到 DSH 界面即成功。DSH 的地址/端口在 config.json 的 dsh.baseUrl 配置（默认 http://127.0.0.1:3080），改了地址就同步改这里。

① 安装依赖

npm install

② 让 NapCat 上线

版本选择：Windows 用 Shell 版（需先安装 QQ 客户端 QQNT，扫码登录）；Linux 服务器用 Docker 版（镜像自带 Linux QQ）。以下步骤以 Windows Shell 版为例。

1. 下载 NapCat 并按官方教程把它接入你的 QQ 账号（扫码登录，会要求已安装 QQ 客户端）。
2. 打开 NapCat WebUI：http://127.0.0.1:6099/webui（默认口令 napcat）。
3. 进入 网络配置，新建两个连接，消息格式都选 array：
- HTTP 服务端：127.0.0.1:3005（端口可自定义；用 start.bat 自动安装时，若 3000 被别的程序占用会自动改用 3005 并写进 config.json）
- WebSocket 服务端：127.0.0.1:3001
4. 如果在 WebUI 里设置了 accessToken，记下来，下一步填进 config.json；两边都留空也可以，但必须一致。

用 start.bat 自动安装时不用手动做这一步：桥接会生成 onebot11_<QQ号>.json 并自动避开被占用的端口，实际端口以 config.json 的 napcat.wsUrl/httpUrl 为准。

生成的 OneBot11 配置在 NapCat 目录的 config/onebot11_<QQ号>.json。

用自己的 QQ 时注意：NapCat 需要把 QQ 重新拉起才能注入，所以启动机器人会把你当前登录的 QQ 退出。
想两边同时用，给机器人单独准备一份 QQ（把现有 QQ 安装目录整个复制一份即可），然后在 config.json 里设置
"napcat": { "qqPath": "D:\\QQ-bot\\QQ.exe" } —— start.bat 会优先用这个路径，你自己的 QQ 不受影响。

接话判断：规则 / 本地模型（可选）

agent 模式下「这条消息该不该接」有两种判断方式，桥接会自动选择：

| 方式 | 条件 | 说明 |
| 规则（默认） | 未安装模型 | 基于 @/引用/第二人称/问句/冷却/连续接话等信号打分 |
| 本地模型 | 检测到 llama-server + GGUF | 小模型判断语义（是否在叫它），上下文信号仍由规则兜底 |
- 模型：Qwen3-1.7B Q4_K_M（约 1.1 GB，Apache-2.0；实测 20/20，判断约 200ms/条）
- 轻量替代：npm run fetch-judge -- --small 换成 0.6B（约 379 MB，CPU 也能跑）
- 推理：llama.cpp 的 llama-server（发行包自带 CPU 版，约 23 MB）
- 安装：npm run fetch-judge（默认 1.7B；加 -- --small 换 0.6B；模型放 models/，推理放 llama/）
- 发行包内置的是 0.6B；想要更准，双击 install-model.bat 升级到 1.7B（约 1.1 GB）
- 自动回退：模型没装、启动超时、或输出异常时，自动退回规则，聊天不受影响
- chat 模式：不经过判断，所有消息原样交给 DSH

config.json 相关配置：

"judge": {
"enabled": "auto", // auto | on | off
"url": "http://127.0.0.1:8080",
"modelPath": "", // 留空自动用 models/ 下的第一个 .gguf "llamaServer": "", // 留空自动用 llama/llama-server.exe；有 N 卡可指向自己的 CUDA 版 "timeoutMs": 2500 }

训练自己的判断器（可选，进阶）

桥接会把每次判断写进 state/judge-decisions.jsonl（只记消息文本，已脱敏）。积累一段时间后：

npm run export-judge # 导出 dataset/judge-train.jsonl（正负均衡、去重）
npm run train-judge # LoRA 微调 Qwen3-0.6B（需要 Python + torch/peft/datasets）

训练产物需要合并 adapter 并转成 GGUF 才能给 llama.cpp 用（脚本头部有完整步骤）。
没有 GPU 也能用：llama.cpp 的 CPU 版随包提供，只是判断稍慢（约 100~200ms/条）。

③ 填写 config.json

copy config.example.json config.json

主要字段：

| 字段 | 说明 |
| dsh.baseUrl | DSH Web 服务地址，默认 http://127.0.0.1:3080 |
| dsh.provider / dsh.model / dsh.reasoningEffort | 模型服务商 / 模型名 / 推理强度（off/low/high/max）；若你的 DSH 没有示例中的模型，改成 DSH 设置页里可用的即可。回复慢就调低推理强度（low 比 max 快 30%~45%，闲聊足够） |
| napcat.wsUrl | NapCat WebSocket 服务端地址，默认 ws://127.0.0.1:3001 |
| napcat.httpUrl | NapCat HTTP 服务端地址，默认 http://127.0.0.1:3000；自动安装时若 3000 被占用会改用空闲端口并写回这里（别填成 WS 端口） |
| napcat.qqPath | 机器人专用的 QQ 路径（留空自动检测）。NapCat 注入会重启 QQ，填一份独立的 QQ 可避免退出你自己的 QQ |
| napcat.accessToken | 与 WebUI 里设置的 accessToken 一致，未配置留空 |
| ownerQQ | 管理员 QQ 号（agent 模式的私聊唤醒、管理操作等） |
| agentPreset | chat 模式使用的 DSH agent preset，默认 qq-chat |
| agentPresetAgent | agent 模式使用的 DSH agent preset，默认 qq-agent |
| workspaceTitle | QQ 会话在 DSH 界面里的归组名称，默认「QQ 聊天」 |
| allow.private / allow.groups | 私聊 / 群聊白名单（QQ 号 / 群号数组），建议先填上 |
| deny.private / deny.groups | 黑名单，优先级高于白名单 |
| allowAllWhenEmpty | 白名单为空时是否放行全部，默认 false（保持默认） |
| ackMessage | 收到消息后的即时回复文本，空字符串关闭 |
| sendDelayMs | QQ 连续发送间隔，防止触发频率限制 |
| maxReplyChars | agent 单条回复最大字符数，超出自动分段 |
| console.port / console.token | Web 控制台端口（默认 3100）与访问令牌；token 留空则启动时自动生成并打印 |
| security.interceptNotify | 回复被敏感拦截时是否提示 |
| vision.enabled / vision.maxImageBytes | 图片理解开关与大小上限（需 vision 模型） |
| queue.maxPerSession | DSH 掉线期间每会话缓存的消息条数上限 |
| social. | 人格引擎参数（默认人格、参与评分权重、心跳、记忆、话题窗口），一般保持默认 |

④ 给 DSH 装 preset 和 MCP

node scripts/setup-dsh.mjs

脚本会把 qq-chat / qq-agent 两套 agent preset、两个 MCP server（QQ 安全工具 + 联网搜索）和一个设置页插件装进 DSH 环境，并写入本地 state/mode.json 兜底。可重复运行；移动过项目目录后必须重跑（MCP/插件路径是绝对路径）。装完重启 DSH 生效。

⑤ 启动

npm start
或双击 start.bat（守护模式：崩溃后 5 秒自动拉起）日志依次出现 配置已加载 → DSH 已连接 → NapCat 已连接 → 桥接已启动 即成功。

提示：桥接只能跑一个实例（单实例锁）。出现「已有实例在运行」时双击 restart.bat 一键重启，或手动删除 state/bridge.lock。

验证与日常使用

- 给机器人私聊或群里 @ 它，看它是否回复。
- 打开 Web 控制台 http://127.0.0.1:3100（令牌在启动日志里）：查看状态、切换 chat / agent 模式、调节人格、管理白名单、发远程指令。
- agent 模式 = 仿真群友：AI 主动看消息、按人格决定参不参与；agent 模式私聊只响应 ownerQQ。
- 重启 DSH 不需要动桥接：桥接会自动探活，DSH 掉线期间的消息会入队缓存，恢复后自动补投。

配置人格卡（角色扮演）

- 控制台「🧠 人格 → 人格卡」页可新建 / 编辑 roles/.yaml：一个文件 = 一个完整人格，保存即生效（自动清缓存）。
prompt 字段就是人设文本（注入给 AI 的身份、说话风格、雷点）；其余字段（心情/精力/兴趣/参与度）驱动人格引擎。
- chat 模式切换角色：控制台「📊 概览 → 人格 / 角色」点人格卡即可（群友无法更改）。
- agent 模式默认人格：改 config.json 的 social.defaultPersona（如 小鲸鱼），保存后重启桥接生效。

离线自测（不需要 QQ）

npm run self-test # 桥接与 DSH 的连接链路
npm run test-loop # chat 闭环（真实 DSH + 假 QQ）
npm run test-loop -- --mode agent # agent 闭环（唤醒/潜水）
npm run test-persona # 人格引擎单测
npm run test-agent-api # agent 内部 API
npm run test-mcp-web # SSRF 防护搜索
npm run test-onebot # NapCat 连接

常见问题

| 现象 | 处理 |
| HTTP 426（Upgrade Required） | napcat.httpUrl 填成了 WebSocket 端口；检查 config.json 与 onebot11_<QQ号>.json 的端口是否一致 |
| 群里 @ 没反应 | 群号是否在白名单 allow.groups；agent 模式下检查它是不是在潜水（参与评分没过阈值） |
| 私聊没反应 | 私聊白名单 allow.private；agent 模式只响应 ownerQQ |
| 改了 MCP 或 preset 不生效 | MCP 由 DSH 拉起，改 src/mcp/*.js 或 dsh/agent-presets/ 后要重启 DSH |
| 提示「已有实例在运行」 | 单实例锁残留，双击 restart.bat 或删 state/bridge.lock |
| 模型选择失败 | dsh.model 改成 DSH 设置页里实际可用的模型 |

能力一览

| 功能 | 说明 |
| chat 模式 | 文本自动转发，安全聊天 |
| agent 模式 | 仿真群友：人格引擎 + 参与意愿 + 工具自主收发 |
| 人格引擎 | 心情/精力/关系/在场状态演化（持久化） |
| 分层记忆 | 群话题 + 长期记忆按相关性注入 |
| 主动心跳 | 人格驱动"偶尔看看群" |
| Web 控制台 | 状态/模式/人格调节/角色卡/记忆/远程指令/白名单/日志 |
| 远程指令 | 完整工具会话执行，结果回显 |
| 接话判断 | 规则 + 可选本地小模型，模型缺失自动回退 |
| 图形安装器 | 原生 Windows 安装向导，按需下载组件 |
| 安全 MCP | 白名单发送 + SSRF 防护搜索 |

项目结构

| 目录 | 作用 |
| src/transport/ | NapCat OneBot11 客户端、DSH WebSocket 下行客户端 |
| src/core/ | 会话管理 / 消息路由 / 发送链 / 事件泵 / turn 收集 |
| src/persona/ | 人格引擎：状态 / 记忆 / 参与度 / 词库 / 令牌 |
| src/mcp/ | 安全 QQ 工具 MCP + SSRF 防护搜索 MCP |
| src/console/ | Web 控制台 + /agent/v1 内部 API |
| dsh/ | DSH 端 agent preset（qq-chat / qq-agent） |
| roles/ | 人格卡（YAML，prompt 内嵌人设） |
| scripts/ | 安装 / 测试脚本 |
| docs/ | 架构与实现规格（DESIGN.md / PERSONA_ENGINE.md） |

讨论

💬 有问题或想交流？欢迎来 GitHub Discussions 聊聊。

加入 Nimu Studio 用户交流群：QQ 群 1097466590（或加作者 QQ 2998827169），一起交流、反馈、催更。

配套组件

- 🎨 控制台的玻璃拟态 UI 来自 Nimu Glass UI（三主题玻璃拟态 UI 体系）
- ⚡ 需要轻量 WebSocket 通讯？NimuChat

支持者

感谢以下支持者让这个项目持续下去 ❤️

| 支持者 | 赞助档位 | 日期 |
| 等你来 ⭐ | 支持者 ¥18 | — |

想支持这个项目？☕ 去爱发电请我喝杯咖啡。¥18 支持者档支持者的名字（GitHub 用户名或昵称）会永久列入上表。

支持

喜欢这个项目？☕ 去爱发电请我喝杯咖啡

数据与隐私

- 所有数据都留在本机：config.json、state/（记忆/日志）、NapCatShell/（QQ 登录）、~/.dsh（DSH 会话）
- 不上传任何数据；模型和组件直接从上游官方源下载
- 控制台、DSH、NapCat、判断模型都只监听 127.0.0.1
- 控制台 token 写入 state/console-token；Windows 下文件权限靠本机进程隔离（POSIX 的 0600 不生效）
- state/judge-decisions.jsonl 会保存脱敏后的群聊文本，用来以后训练判断模型；不需要就删掉该文件

使用提醒

QQ 协议层由第三方开源项目 NapCat 提供，与腾讯公司及其产品无任何隶属关系；本项目仅用于学习与技术研究，使用前请自行了解并遵守相关条款与《QQ 用户协议》。

另外注意：把智能体接进 QQ，等于把账号的发言权交给了模型。对外使用前务必先配好白名单（allow.private / allow.groups），谨慎评估风险。

许可证

MIT

联系

- 官网：nimustudio.cn
- GitHub：@NimuStudio
- QQ 交流群：1097466590
- 爱发电：☕ 请我喝杯咖啡