dsh-qq-onebot

把 QQ 接成 DeepSeek Harness 的一个前端：私聊、群聊都能和同一个 Agent 聊；语音听得懂、图片看得见，还能戳一戳、贴表情、点赞。

底层走 OneBot v11 协议，默认搭配 NapCat。不用公网 IP、不用备案、不用企业主体。

⚠️ 先说清楚：NapCat 属于「QQ 协议端」，跑在你自己登录的 QQ 客户端上，不符合腾讯的用户协议。用小号、别和常用号同一台设备、别发垃圾消息，账号有被风控或封禁的可能。插件只负责把 OneBot 消息转给 Agent，协议端本身怎么合规、怎么稳，由你自己负责。场景能用 QQ 官方机器人的，优先用官方的。

📢 这是个公开仓库：MIT，随便取用、改、再发。作者是个人不是公司，没有客服、没有 SLA，能回 issue 但不保证秒回。提 issue 或贴日志之前，请先把 token、真实 QQ 号、本机路径 抹掉——发出去就收不回来了。

你的 QQ 客户端  ←→  NapCat（协议端，注入 QQ）
                        ↕  OneBot v11 WebSocket
                dsh-qq-onebot 插件（跑在 DSH 宿主进程里）
                        ↕  进程内 ctx.agents
                  你的 Agent（你自己的预设、工具、记忆）

它能干什么

特性	说明
一个 QQ 会话 = 一个持久 Agent 会话	有历史、有记忆，不会聊两句就忘
每个会话一个独立工作目录	自带 `AGENTS.md` 和 `记忆区/`，彼此看不见，也碰不到宿主自己的私人记忆
语音转文字	本地 vosk 离线识别，不联网、不上传，结果直接进对话
群里默认 @ 才理	被某人 @ 过一次后 60 秒内不用再 @ 也能接（窗口按「群 + 人」算，别人蹭不到）
分得清谁在跟自己说话	引用算叫我、`[SILENT]` 可以不接、同类机器人单独开关、跳过的群消息也进上下文
不会把自己聊丢	窗口快满时补回聊天规矩；再撑满就换新会话，旧的最近聊天先落盘再接上
十个互动工具	`qq_poke` / `qq_react` / `qq_like` / `qq_send_image` / `qq_send_file` / `qq_face` / `qq_mface` / `qq_reply` / `qq_send` / `qq_recall`
问答能转回 QQ	`ask_user_question` 抛的问题会变成一条 QQ 消息，回个数字就行

三步跑通

1. 装 NapCat，登录小号

下载 Windows 一键版（NapCat.Shell.Windows.OneKey.zip），解压运行 NapCatInstaller.exe——它装一份独立的 QQ，不会碰你现有的 QQ。登录小号，打开 WebUI（默认 http://127.0.0.1:6099），在「网络配置」里新建 WebSocket 服务器：

项	填什么
地址	`127.0.0.1`
端口	`3001`（被占用就换一个，记住它）
Token	自己编一串，比如 `my-token-2026`
消息格式	`array`（重要，别选 string）

⚠️ NapCat 的 QQ 和你桌面的 QQ 是两套程序。 重装 / 重启 NapCat 时别用 Get-Process -Name QQ | Stop-Process 一把全杀——那会把自己正在用的 QQ 也踢下线。按进程路径挑，或者在 NapCat 自己的托盘 / WebUI 里退。

2. 装插件

先把 DSH 完全退出（托盘也要退掉，插件文件被占用会装到一半失败）。

# 从 npm 装（推荐）
dsh plugin --profile desktop add dsh-qq-onebot

# 或从 Releases 下载 dsh-qq-onebot-1.0.0.tgz
dsh plugin --profile desktop add "D:\下载\dsh-qq-onebot-1.0.0.tgz"

不想用打好的包，也可以直接装源码目录（git clone，或下 Source code (zip) 解压）：

dsh plugin --profile desktop add "D:\dsh-qq-onebot-1.0.0"

三个容易踩的坑：

必须用 DSH 自带的 dsh，不能 npx @deepseek-ai/dsh。 desktop 这份 profile 由桌面端独占管理，npx 会直接报 profile "desktop" is managed exclusively by the Electron application。PATH 里找不到 dsh 就用完整路径：
```
& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "D:\dsh-qq-onebot-1.0.0"
```
--profile 不能省，省了直接报 error: --profile <name> is required。
写绝对路径，相对路径是按你敲命令那一刻的当前目录算的。

装完它会自动写进 $DSH_HOME/profiles/desktop/package.json 的 dsh.profile.bundles（默认就启用），启动后在 设置 → 插件 里能看到。想确认装没装上：

dsh plugin --profile desktop why dsh-qq-onebot

3. 重启 DSH，填连接信息

重新打开 DSH → 设置 → QQ，把 wsUrl 和 accessToken 填进去就行（34 项都在那个面板上，改完即时生效）。

设置里没看到 QQ 这一项？ 别慌，不用等修——两条路都能救。

① 直接写设置文件（不用重启宿主）：$DSH_HOME/dsh-qq/settings.json，Windows 一般是 C:\Users\<用户名>\.dsh\dsh-qq\settings.json。插件第一次启动时会在那儿放一份带说明的骨架，改成：
{
  "wsUrl": "ws://127.0.0.1:3001",
  "accessToken": "my-token-2026"
}
保存后约 800ms 自动生效。

② 看日志找原因：插件启动时会自检浏览器半端，日志里有 客户端半端自检通过：id=... 就是好的；如果是 客户端半端自检失败（client-id-mismatch / no-inject ...），那句话本身就说明了设置页为什么没出现。日志在 <workspaceRoot>/logs/dsh-qq-<日期>.log（workspaceRoot 默认是进程 cwd）。也可以看 $DSH_HOME/dsh-qq/ 下有没有东西——一个文件都没有，通常就是浏览器半端根本没被加载。

想直接写 profile 配置也可以，改 $DSH_HOME/profiles/desktop/cordis.patch.yml 里 dsh-qq 那一段（整段替换，不是往下叠）：

- id: dsh-qq
  name: dsh-qq
  config:
    wsUrl: ws://127.0.0.1:3001
    accessToken: my-token-2026
    cwd: D:/my-agent                     # Agent 工作目录，不填用进程 cwd
    workspaceRoot: D:/my-agent/QQ会话    # 每个会话的独立目录（不填用 <cwd>/会话）
    persona: |                           # 它是谁、什么脾气（不填就是个普通助手）
      你叫小满，是个住在电脑里的助手。说话简短、带点懒，被夸的时候会嘴硬。
    provider: deepseek-official          # 想指定模型时才填
    model: deepseek-flash

日志里看到 已连接 ws://127.0.0.1:3001 就成了，给小号发条私聊试试。

最常改的几个配置

配置	默认	什么时候改
`persona`	空	想让它有名字、有性格、有称呼
`ownerIds` / `ownerLabel`	`[]` / `主人`	想在群里认出主人，优先响应
`requireMention`	`true`	群里不 @ 也想让它接话
`groupMode` / `privateMode`	`open`	只想在指定群 / 指定人那里开
`groupReplyGapMs`	`20000`	觉得回得太密（防刷屏、防风控）
`rateLimitPerMin`	`12`	每个会话每分钟最多发几条
`contextGuard`	`true`	不想要自动换会话就关掉
`chatLog`	`true`	不想记原始流水就关掉

全部 50+ 项见 docs/configuration.md。

想深入看哪块

想看	去哪
它是谁、群里怎么认主人、上下文守卫、认时间、引用与沉默判断	docs/persona.md
所有配置项的默认值和含义	docs/configuration.md
长期跑、看门狗、定时写日记、开机自启	docs/deployment.md
改代码、跑测试、目录结构	docs/development.md
测试怎么做、踩坑记录、排障	TESTING.md · tools/README.md

在 DSH 设置里调它

不想手改 YAML 的话，设置 → QQ 那一节就是个面板，34 项都能点着改：

分组	能改什么
状态	连接点、登录账号、家目录、设置文件；「重连」「重新读一遍」两个按钮
连接	`wsUrl`、`accessToken`、`selfId`
它人设	`persona`、`personaFile`、`ownerLabel`
补充提示	`directPrompt`、`groupPrompt`
记忆区与工作区	`workspaceRoot`、`isolateByPeer`
群里怎么说话	`requireMention`、`groupWakeMs`、`groupReplyGapMs`、`groupMinGapMs`、`rateLimitPerMin`、`historyLimit`
谁能跟它说话	`privateMode`、`privateAllow`、`ownerIds`、`groupMode`、`groupAllow`
同类机器人	`botChatEnabled`、`peerBots`
其它	`debug`、`textChunkLimit`、`splitDelayMs`

改完立刻生效（wsUrl / accessToken 要点「重连」；reconnectMs / selfId / workspaceRoot / isolateByPeer / asrPython 要重启宿主）。设置写在 $DSH_HOME/dsh-qq/settings.json，只覆盖你显式设过的键，清空就回默认——不动 profile 的 cordis.patch.yml。

同一个 QQ 号不能两处同时登录（会互相抢消息），所以桌面 / Web GUI 那份配 uiOnly: true：只提供设置页，不连 NapCat；真正干活的是 --profile qqbot 那个宿主。

和别的 OneBot 插件共存

一台 NapCat 的 WebSocket 一般只该被一个 Agent 连着。社区的 dsh-onebot-hub 之类也连同一台 NapCat 时，两边都会收到同一条消息、各自回一遍——表现是「回复错乱」「一条消息两份回复」，不是任何一边的 bug。

只留一个：

dsh plugin --profile desktop remove dsh-onebot-hub
# 再确认 profile 的 package.json 里 dsh.profile.bundles 已经没有它

搬家到 dsh-qq 时顺手清一下旧家的状态目录（不清也不影响，只是留着占地方）：$DSH_HOME 下旧插件自己的目录。dsh-qq 的家是 $DSH_HOME/dsh-qq/，卸载插件时这个目录不会自动删，设置、日志、覆盖表都在里面，留着下次重装能直接用。

常见问题

设置里没有「QQ」这一项 浏览器半端没被加载。最常见两个原因：插件版本太老（1.1.1 之前的 dsh.client.inject 写了宿主要么没有的包），或者装的是改过包名却没跟着改 client.js 里 id 的版本。现在不用等更新：连上 NapCat 只看设置文件的话，改 $DSH_HOME/dsh-qq/settings.json 就够了（见上面第 3 步的兜底），QQ 本身不依赖设置页。插件启动日志里搜 客户端半端自检，它会把原因写在里面。

连不上 / 一直重连 看 NapCat 的 WebUI 里 WS 服务器是不是「启用」，端口对不对，Token 两边是否一模一样。插件日志里 连接错误 后面会带具体原因。

配置看着没问题，但就是发不出去 NapCat 的 WS 和 HTTP 是两个不同的 token，填错不报错，只是安静地发不出去。另外别让 PowerShell 把配置写出 BOM——一个看不见的字节能让所有判断歪掉。

收得到消息但 Agent 不回 群里先确认 @ 了；私聊看 privateMode 是不是 allowlist 却没把自己加进 privateAllow；都没问题就看 DSH 那边是不是还在跑（一轮本身要时间）。

消息重复发两遍 一般是两个 qqbot 宿主同时连着 NapCat（日志里每行出现两次）。用 tools/start-bot.cmd 起，它会先掐掉旧的宿主。

语音没转出文字 先确认 asrPython -c "import vosk" 能过，再手动跑一次 <asrPython> <asrScript> <音频文件> [模型目录]。模型目录必须是纯 ASCII 路径（vosk 的 C++ 层不认中文路径）。

记忆存在哪 / 会不会和宿主串 默认 isolateByPeer: true：私聊在 <workspaceRoot>/会话/私聊_<QQ号>/，群在 群_<群号>/，第一次用自动铺好 AGENTS.md + 记忆区/。想共用宿主目录就设 false。

能不能群发 / 主动推消息 不做群发。冷场时会主动开口：会话安静满 proactiveSilentMs（默认 20 分钟）之后，它有机会自己说一句，说不说由它判断（不想说就 [SILENT]）。有静默时段、每天次数上限、以及「连着几次没人接就闭嘴」三道闸，见配置项。想定时定点让它说话，就在 DSH 里给它挂个定时任务。

装之前

需要	版本
DeepSeek Harness	≥ 0.2.0
Node.js	≥ 18（插件零编译依赖）
NapCat	v4.x（推荐 `NapCat.Shell.Windows.OneKey` 独立版）
一个 QQ 小号	别用主号，真的
（可选）vosk + numpy	只有想让语音自动转文字才要；不装也行，语音会标成「没听清」

放出去之前，逐条确认

接入只是第一天，第二天才见真章。装之前先想清楚三件事：你准备长期维护它吗？不想养了会好好收尾吗？它在公共场合出现时，你负责吗？——群里其他人看到的是一个会说人话的账号，不是一个玩具。

别把 token 提交进仓库。 NapCat 的 access token、模型 API key 都放配置里，别写进代码或 commit。
别手改 profile 的 package.json / pnpm-lock.yaml / node_modules。 装插件用 dsh plugin --profile <名字> add，而且要在 DSH 完全退出时做。手改 lockfile 会让 pnpm 重排包、撞到被占用的文件，最坏是整个桌面端报「web 缺失或文件损坏」（这个坑真踩过，最后靠卸载重装才救回来）。
杀进程按路径挑，别 Get-Process -Name QQ | Stop-Process 一把全杀。 NapCat 的 QQ 和你桌面的 QQ 是两套程序，一把杀会把自己踢下线。
它会花你的 token。 群里每句话都是一次模型调用，先用 rateLimitPerMin、groupReplyGapMs、groupWakeMs 把节奏压住。
它会读写你指定的工作区。 workspaceRoot 指到哪，它就能在哪读写文件。
上下文会被压缩或换会话。 重要的事要落盘，别指望它一直记得。
人多的地方它可能说错话。 先用 groupMode: 'allowlist' 缩到测试群，稳了再放开。
账号风控不是插件的问题。 频繁换设备登录、短时间大量发消息都可能被判风险，遇到了去手机 QQ 做安全恢复。

出问题了去哪问

先在 Issues 提一个：带上插件版本、DSH 版本、dsh-qq-debug.log 里相关的几行、复现步骤。别贴 token 和真实 QQ 号。

也可以直接把报错原文、api-state.txt、日志尾部丢给你的 AI 助手，通常能判断出是配置、连接还是插件本身的问题。

许可证

MIT，见 LICENSE。用出问题、账号被风控，作者不承担责任——协议端本来就是灰色地带，用之前想清楚。

dsh-qq

Instalar

README