QQ 互通桥 Yuuyuko-uu/dsh-qq-link

Unexpected end of JSON input 这类字样，多半是配置文件被写坏了（常见于装插件时 DSH 正好在写配置、或者手动改配置改出了语法错）。

按顺序试：

1. 先备份：把 ~/.dsh/ 整个目录复制一份。
2. 找到坏掉的那个文件：错误信息里一般会带路径，通常是 ~/.dsh/config.json 或 ~/.dsh/profiles/<名字>.json。
3. 用编辑器打开，检查有没有：
- 文件开头多了 BOM（看不见的字符，编辑器里显示成 ）；
- 少逗号、多逗号、括号没配对；
- 内容被截断（文件末尾突然断掉）。
4. 修不好就用备份覆盖回去，或者把那个文件删掉让 DSH 重新生成（会丢这个文件里的设置）。
5. 重启 DSH。

实在找不出问题，把报错原文和那个文件的内容（记得先删掉里面的密钥、token）贴到 issue 里。

它依赖什么

- DSH：最新版。
- QQ 后端：一个跑在 127.0.0.1:3000 的 HTTP 服务，提供收发消息的接口。
插件只认 HTTP，不关心你用的是哪个实现 —— 只要接口对得上就行。
- git（只在用 github: 写法安装时需要）。

设置项

进 设置 → 通到 QQ，逐项填：

| 设置项 | 说明 | 默认 |
| 总开关 | 关掉时一句都不发 | 关 |
| 试运行 | 开着时只打日志，不真发 | 开 |
| QQ 后端地址 | HTTP 接口地址 | http://127.0.0.1:3000 |
| 私聊会话 | DSH → QQ 发到哪个 QQ 私聊 | 空 |
| 群会话 | DSH → QQ 发到哪个 QQ 群 | 空 |
| 收图 | 收进来的图存到本地并转给它看 | 开 |
| 图片根目录 | 解析 markdown 图片相对路径的根 | 空（用会话工作区） |
| 语音转写命令 | 读 {file} 打一行字的命令 | 空 |
| 回复门槛 | 先判断「是不是在跟我说话」 | 关 |
| 点名之后接着听几条 | 见上文 | 5 |
| 接着听多少秒 | 见上文 | 120 |

常见问题

Q：装完设置页里找不到「通到 QQ」？ A：先确认插件装成功了（设置 → 插件里能看到），再重启一次 DSH。还不行就看 DSH 启动日志里有没有插件加载报错。

Q：消息发不出去？ A：按顺序查：总开关开了没 → 试运行关了没 → QQ 后端地址对不对 → 后端本身活着没（浏览器打开那个地址试试）。

Q：QQ 里发的消息 DSH 收不到？ A：插件每 4 秒轮询一次，稍等一下。还是没有就确认：私聊 / 群会话选对了没、后端接口返回正常不正常。

Q：语音条转不出字？ A：检查「语音转写命令」填了没、命令里有没有 {file}、那个命令单独在终端里跑得通不通。

Q：它发的图在 QQ 里显示不出来？ A：看「图片根目录」—— 留空时用会话工作区，如果图不在工作区里就得填对路径。另外 GIF 会变成静态图，这是 DSH 那边重新编码导致的。

许可

看 LICENSE。
readProfileManifest —— 那是配置档的 package.json 被存成了 UTF-8 带 BOM。
跟插件无关：文件内容都是对的，只是开头多了三个看不见的字节，DSH 读它就崩。

先找出来（不同装法位置不一样，别猜 —— 真正的配置档目录里同时有 cordis.yml、cordis.patch.yml、package.json；机器上别处那些同名的都不算）：

Get-ChildItem C:\,D:\,E:\ -Directory -Filter profiles -Recurse -Depth 4 -ErrorAction SilentlyContinue |
ForEach-Object {
Get-ChildItem $_.FullName -Directory -ErrorAction SilentlyContinue | ForEach-Object {
$p = Join-Path $_.FullName 'package.json'
if ((Test-Path (Join-Path $_.FullName 'cordis.patch.yml')) -and (Test-Path $p)) {
$b = [System.IO.File]::ReadAllBytes($p)
$bom = ($b.Length -ge 3 -and $b[0] -eq 0xEF -and $b[1] -eq 0xBB -and $b[2] -eq 0xBF)
"{0} BOM={1}" -f $p, $bom
}
}
}

输出里 BOM=True 的那一行，就是要修的文件（标准安装在 C:\Users\<你>\.dsh\profiles\<档名>\package.json）。
去掉 BOM（路径换成上面那一行）：

$p = "把上面 BOM=True 那一行的路径粘到这里"
[System.IO.File]::WriteAllText($p, [System.IO.File]::ReadAllText($p), (New-Object System.Text.UTF8Encoding($false)))

然后重启 DSH 就好，数据一点没丢。

实在进不去时，那个错误框里的 「Disable third-party plugins, back up profile patch, and restart」 能先起来（它先备份再停插件），再一个个开回去定位。

⚠️ 手动改配置档里的文件，一律存 UTF-8 无 BOM。让 AI 帮你改时，别让它用 Set-Content -Encoding UTF8 或 Out-File -Encoding utf8（Windows 自带的这两个默认带 BOM），用上面那行 .NET 的写法就不会。

更新到最新版

最省事：把这个仓库的地址丢给你自己的 DSH，说「帮我更新这个插件」。装完重启一次 DSH。

也可以点 设置 → 通到 QQ 最上面的「检查更新」 —— 有新版会提示，还能一键复制更新命令。

命令行（--profile 照你平时那个写，桌面端一般 desktop、网页端 web）：

dsh plugin --profile desktop remove dsh-qq-link
dsh plugin --profile desktop add github:Yuuyuko-uu/dsh-qq-link

⚠️ 必须先卸再装：直接装可能拿到缓存里的旧副本，装完还是老的。
⚠️ 装完重启一次 DSH才会用新代码。

我的设置会不会丢？

不会。 设置存在 DSH 家目录（%USERPROFILE%\.dsh\）里，不在插件代码里；卸载只删代码：

.dsh\qq-bridge-config.json （还有 qq-bridge-inbox\ 里收到的图）

所以卸载 → 重装，设置、收到的图片、转发记录 都还在。

三件小事提醒：

- 别用「重装 DSH」来更新插件 —— 那是两件事，重装可能动到配置档。
- 新版本新加的设置项会用默认值（以前没这一项），想要自己的值就再填一次。
- 设置项改名或换单位时，旧值会按规则自动换算，不用你管。

配置（设置页里点就行，不用改文件）

设置 → 通到 QQ，从上到下：

| 项 | 默认 | 说明 |
| 总开关 | 关 | 关着 = 一句都不发 |
| 试运行 | 开 | 开着只记账，不真发 |
| 目标会话 | （没选） | 下拉里选你自己要的那一间，不用手填 id |
| 转私聊 / 私聊 QQ 号 | 开 / 空 | 发到哪个私聊 |
| 转群 / 群号 | 关 / 空 | 发到哪个群 |
| 收图（QQ → 它） | 开 | 你在 QQ 里发的图也转给它。文字里带本地备份路径 |
| 发图（它 → QQ） | 开 | 它这一轮里发的图也发到 QQ |
| 一条最多收几张 | 4 | 1–10，多出来的不转 |
| 单张最大（MB） | 5 | 超过就跳过，两个方向共用 |
| 点名之后接着听几条 | 5 | 0–50。被 @ / 被引用之后，同一个群紧接着的几句话也转进来；0 = 关掉这个功能 |
| 接着听多少秒 | 120 | 0–600。到点就停，就算条数还没接完（填 0 只剩点名那一条能进来） |
| 允许发 QQ 空间动态 | 关 | 只影响发说说；看说说、看好友动态不受它管。见下面「QQ 空间」那一节 |
| 测试一句 | — | 真发一条测试句到已填的私聊/群（绕过试运行） |

配置文件落在 %USERPROFILE%\.dsh\qq-bridge-config.json（一般不用碰它）。

QQ 空间（可选）

绑了 QQ 的那几间会话会多出四个工具。它们走的就是上面那个后端地址和令牌，不用另填一套（SnowLuma 2.0.0 原生就有这些动作，NapCat 也有同族接口 —— 前提是你的后端真的支持）。

| 工具 | 能干什么 |
| qq_space_list | 看某个号的说说（不填 QQ 号 = 机器人自己）：总共多少条；每条带时间、正文（长的会截断）、评论数、是不是私密、带几张图。每条前面有 tid，后面那个工具要用 |
| qq_space_detail | 看一条说说的正文，加一页评论（谁说的、什么时候） |
| qq_space_feeds | 好友动态流：谁发的、什么时候、说了什么。里面的 HTML 会先去标签、再把空白压掉才给它，不会丢一坨标签过去 |
| qq_space_post | 发说说。可以带图（最多 9 张，本地路径 / http 网址都行），可见范围可选：所有人 / 好友 / 部分可见 / 仅自己 / 部分不可见（后两种「部分」得另外给名单，不给就不发） |

发说说默认是关的。 开的地方：设置 →「通到 QQ」→「发消息」页 →「QQ 空间」→ 勾上「允许发 QQ 空间动态」。

关着的时候这四个工具照常挂着，但一调只回一句「没开」，一个请求都不会发出去 —— 那不是故障，别重试。
看说说、看好友动态不用开这个闸，只有发才要。

开之前先想清楚：说说发出去所有人都看得见，还是用你那个 QQ 号的名义发的，发错了得自己上手机删。模型判断不了「这条到底该不该发」—— 它看见工具就想用，所以这道理得你自己在会话里跟它说清楚，别指望它自觉。

还有几件小事：

- 好友动态第二页起可能重复或者缺（后端那边就这脾气），翻一页够用就别翻。
- 机器人的号一条说说都没有时，后端会回 msglist:null；这里翻成「这个号的空间里还没有说说」——那是空的，不是坏了。
- 连不上 / 10 秒没回 / 后端拒绝，三种说法不一样，看它回的那句话就知道是哪一种。
- 工具只挂在绑了 QQ 的会话上；没绑 QQ 的会话里看不见它们。

现在就能用的接口

- GET /dsh-qq-bridge/state —— 配置、日志、会话清单、以及「连着的 QQ 是哪个号/昵称」。
- POST /dsh-qq-bridge/save —— 存配置（body 里给要改的键）。
- POST /dsh-qq-bridge/test-send —— 真发测试句（绕过试运行）。

自测（不装插件也能跑）

node tests/宿主半边.mjs
node tests/网页半边.mjs

想让它发语音？（可选附加件）

主插件只管文字。想让 AI「念」出来的声音变成 QQ 语音条，tools\语音\ 里放了整套：

| 文件 | 干什么 |
| 录语音.mjs | 看门狗：盯着朗读桥，念的时候录音、录到就发 QQ |
| 录音回环.ps1 | 录音器（录系统声音回环，不要麦克风） |
| 朗读信号哨兵/ | Chrome 扩展：看到朗读桥面板的「🔊 点朗读」就通知看门狗开录 |

两种发法，自己选（双击 启动-录语音.bat 会让你输 1 或 2）：

| 模式 | 什么样 |
| 1 = 切断发 | 边录边发，念一段发一段（响应快，会连着几条） |
| 2 = 完整发 | 整段念完，把所有分段拼成一条再发 |

前提：Windows + 装了朗读桥（dsh-tts-bridge）+ QQ 后端支持发语音。
详细步骤见 tools/语音/README.md。

不装这一套也完全能用主插件。

它依赖什么：一个 QQ 后端（SnowLuma 或 NapCat，二选一）

插件本身不碰 QQ 协议，它只会说 OneBot 11 的 HTTP。所以你要在本机跑一个「QQ 接口」程序，让插件通过 http://127.0.0.1:3000 跟它说话。

选哪个

| 后端 | 说明 |
| SnowLuma | 测过，能用（本插件一直在用的就是这个）。 |
| NapCat | 也测过，能用。自带网页后台（默认 http://127.0.0.1:6099）扫码登录，比自己配一端省事 |

插件实际用到的接口（换后端时照这个核对）

send_private_msg 发私聊 send_group_msg 发群消息 get_login_info 看登录的 QQ 是哪个（设置页显示"✓ 连着的 QQ"） get_friend_msg_history 收私聊（QQ → DSH） get_group_msg_history 收群消息（QQ → DSH）

收发消息要的就是上面这几个接口（都在 HTTP 上）。QQ 空间是可选的，另外四个动作：

get_qzone_msg_list 看某人的说说列表 get_qzone_msg_detail 看一条说说和评论 get_qzone_feeds 好友动态流 send_qzone_msg 发说说

后端没这几个动作时，那四个工具调了会回一句后端给的原因，不影响正常的收发。

装 NapCat 的步骤

1. 从 NapCat 的 Releases 下 Windows 版，解压到任意目录
2. 双击启动，它会弹一个网页后台（默认 http://127.0.0.1:6099）
3. 在网页里扫码登录你要用的 QQ 号
4. 确认 HTTP 服务开着、端口是 3000（不是的话，在插件设置里把「NapCat 地址」改成你的）
5. 回到 DSH → 设置 → 通到 QQ → 点「测一下」，应该显示 ✓ 连着的 QQ：<昵称>（<号>）

装 SnowLuma 的步骤

同样思路：跑起来 → 登录 QQ → 开启 OneBot 11 的 HTTP 服务 → 端口对上（或改插件里的地址）。
具体菜单名以它的文档为准：SnowLuma 仓库。

两个后端作者都实测过，接口对得上就能用。挑一个顺手的即可。

⚠️ 只有 HTTP 模式够用（插件不连 WebSocket）。开了 WS 但没开 HTTP 的话，插件连不上。

其它

- 桌面只留这个后端 + 本插件 + DSH。
- /receive 路由还留着，是想用别的方式（比如另一个程序）把 QQ 消息灌进来的备用入口，不依赖它也能跑。

它要什么权限，边界在哪

装之前先看清楚 —— 这个插件真会动你的账号和本机文件：

| 能力 | 用在哪 | 边界 |
| 网络 | 连你本机的 QQ 后端（默认 127.0.0.1:3000，NapCat / SnowLuma 的 OneBot 11 HTTP） | 只连你填的那个地址；不往别处发。收图时会去图床地址下载（QQ 消息里带的 url） |
| 文件 | 收进来的图存在 ~/.dsh/qq-bridge-inbox/；配置和状态在 ~/.dsh/（qq-bridge-config.json / qq-bridge-state.json） | 只碰这两个地方；不扫别的目录 |
| 命令 | 只有你自己填了「语音转写命令」才会跑一条本地命令（比如 python tools/asr_cli.py {file}） | 不填就完全不跑；不装额外依赖 |
| 凭据 | 「令牌」那一栏（QQ 后端的 access token），存在配置文件里 | 只用来连你自己填的那个后端；不要把它贴进公开 issue |
| 公开发东西 | qq_space_post 能往你这个 QQ 号的空间里发说说 | 默认关（「允许发 QQ 空间动态」）；关着时一个请求都不发。开着就是公开可见，发出去得自己去删 |

外部依赖：一个 OneBot 11 的 QQ 后端（NapCat / SnowLuma 等）—— 插件本身不带 QQ 协议实现。
失败边界：后端连不上时它只记账、不转发，不会把消息丢掉重发；DSH 里没有对应智能体时会明确提示「那间会话现在没活着」。

改动记录

见 CHANGELOG.md。版本号规矩：每改一次 +0.0.1，末位满 10 进位。