dsh-qq-onebot-bridge
QQ ↔ DeepSeek Harness 双向桥插件（独立 bundle）。QQ 消息直接驱动 DSH agent 会话，agent 回复自动发回 QQ。
当前版本 v0.8.3 · 发布记录（Releases） · 更新日志
架构
QQ 客户端 ←→ OneBot 实现（NapCat / LLOneBot / OpenShamrock / Lagrange…）
│ 反向 WebSocket（OneBot 连我们；端口 6700）
▼
dsh-qq-onebot-bridge（本插件）
│ ctx.agents.create / followup
▼
DSH agent 会话（每群/每私聊用户一个）
旁路（都不参与回复决策，出问题也不影响发消息）：
每条入站事件 ──► qq-inbox.jsonl （录制：可离线回放）
每个决策点 ──► qq-trace.jsonl （结构化事件：stage/ok/reason/耗时/traceId）
快照每 2s ──► qq-runtime.json （会话/闸门/生效配置/录制与注入状态）
qq-inject.jsonl ◄── 控制台写、桥轮询读 （注入：默认 dry-run，出站全拦截）
独立控制台 control/（进程 8799，不依赖 DSH 桌面端）
├─ 读：端口/进程、事件流、决策链、体检、录制列表、运行快照
├─ 写：启停宿主/NapCat/TTS、释放端口、离线回放（沙箱 + dry-run）、事件注入
└─ 鉴权：仅 127.0.0.1 + token + 同源 Origin 校验
安装 / 卸载
# 安装（本地目录）：先在被安装的目录里装运行时依赖，再注册插件
# 本地目录走 pnpm 的 link:，不会自动安装被链接包自己的依赖（ws）
cd <本目录> && npm install --omit=dev
dsh plugin --profile web add <本目录>
# 卸载（随时可移除，独立 bundle 不影响其它插件）
dsh plugin --profile web remove dsh-qq-onebot-bridge
装/卸后重启 dsh web 生效。
官方依赖（@deepseek-ai/dsh-*、@deepseek-ai/schemastery）声明为 peerDependencies，由 DSH 随 profile 一起装好，插件目录里不需要重复安装。
官方桌面端（DSH Desktop）
官方桌面端（Electron 版 DeepSeek Harness.exe）跑的是 ~/.dsh/profiles/desktop 这个 profile，由应用独占管理（CLI 会拒绝 dsh --profile desktop），它和 CLI 版共用同一个 DSH 运行时版本——所以本插件从 v0.5.9 起声明的 peer 范围同时覆盖 ^0.1.x 与 ^0.2.0-rc.2，两边都能直接装、不需要 dsh plugin allow-version 豁免。
装法与 web 版一致，只是走桌面端的插件管理界面：
- 桌面端 → 设置 → 插件 → 安装，选本地目录（就是本插件所在的目录，也就是
dsh plugin --profile web add 时填的那个路径），或直接填 GitHub 仓库地址；
- 配置同样写在
~/.dsh/profiles/desktop/cordis.patch.yml（id: dsh-qq-onebot-bridge 的 config），不要写进仓库；
- 重启桌面端生效。
手动/本地目录安装（不经市场）时注意：光有依赖还不够，必须同时把 dsh-qq-onebot-bridge 加进该 profile package.json 的 dsh.profile.bundles，加载器才会挂载它——只装依赖的话它只会出现在"已装依赖"里而不工作（本机实测）。市场安装会自动处理这一步。
⚠️ 一台机器只允许一个实例托管 QQ 桥：web 宿主与桌面端可以都装本插件，但两者抢同一个 OneBot 端口（默认 6700），只有一个能绑上——另一个会在日志里说明原因并每 15 秒重试，等端口释放后自动接管（v0.5.9 起不再崩溃、也不会拖住宿主启动）。不要用"给另一个 profile 改个端口"来让两个都跑：它们共用同一份 cwd（qq-sessions.json / qq-memory/ / qq-reminders.json / 积分与统计…都在那儿），两个实例同时读写会互相覆盖，injectDryRun:false 时注入队列里的动作还会真的发两遍。要固定由某一个托管，正确做法是只在一个 profile 里启用本插件（另一个从 dsh.profile.bundles 里去掉），或者把 cwd 也分成两个不同目录。
在 DSH 设置里开关功能（v0.6「QQ助手」页）
装好插件、重启一次宿主（让面板路由挂上）之后：DSH → 设置 → QQ助手。
- 11 组、7 组直接铺开：AI账号与白名单 / 对话基础 / 限流：入站 / 出站 / 避开高峰期 / 群运营工具箱 / 娱乐与互动 / 语音与媒体；
安全与风控 · 记录与通知 · 实验性 · 高级与调试四组标「进阶」、默认折叠。共 87 个键（69 开关 + 12 数值 + 1 时段列表 + 3 名单 + 2 句式列表），
从 238 个配置键里精选 —— 面板只放"日常会动的"，其余仍在
cordis.patch.yml（见下面的「v0.7.x 新增开关」）。
顶部搜索框按中文标签 / 配置键名过滤（纯前端）。
- 两个限流闸放在同一组、按管道顺序排，就是为了别混：每分钟进模型上限（入站，消息还没进模型就拦，省模型额度）vs 出站回复限流（模型已生成、发出去之前拦，防 QQ 端发太快被风控）。两个默认都关，可以只开一个。
- 开关和它的数值在同一行里：左边开关、右边
− n +，不用再上下对照「XX」和「XX·数值」谁管谁。
- 避开高峰期（v0.6.8）：功能本来就有，但以前只能改 YAML；现在整组搬进面板——开关、周末不静默、以及静默时段列表（每段两个原生时间控件，支持跨夜
22:00-6:00，最多 8 段）。
- 回复带引用（v0.6.9）：打开后回复会引用被回答的那条消息（QQ 原生「回复」），多人同时提问时更清楚；默认关（单人聊天会显得啰嗦），引用失败（消息被撤回 / ID 过期 / 客户端不支持）会自动去掉引用重发一次。它放在**「对话基础」**组——那是"回复的样子"，不是"谁能让它开口"。
- AI账号与白名单（v0.6.8）：这一组回答"机器人是谁、它认谁"——AI 账号（
botQq，判断 @ 与戳一戳）、回应所有人、「群里只理被 @ 的」「允许私聊」两个准入门、以及 allowUsers / allowGroups 两个白名单（空列表 = 全部拒绝）。不想维护名单时把「回应所有人」打开：所有私聊和所有群都会响应，但群里的 @ 门槛不变（仍要 @ 到它）。它们以前都得改 YAML；现在面板里直接填号码（输入框 + 「添加」，号码以数字写进配置，写成字符串会让白名单永远匹配不上），还能从「最近来信」一键加入；「回应所有人」开着时两个名单行会标成"现在不起作用"。
- 数值项（v0.6.7）：风控里那些"阈值"不再要你去手改 YAML——每分钟进模型条数（1–10，默认 5）、出站回复的上限与窗口、去重窗口、刷屏治理四项、戳一戳每小时上限、周报天数，都在面板里用
− 数字 + 直接改。范围与步长从 schema 现读（不抄第二份），越界/小数会被服务端 400 拒掉并说清范围。
- 每行都写清楚：中文标签 + 一句话"关掉会怎样" + 配置键名（方便你去配置文件里找同名键），右侧是拨动开关；行尾徽标
非默认（与 schema 默认值不同）、更新中（配置文件里的值与当前生效值不一致）。
- 点一下即写入：只改 profile 的
cordis.patch.yml 里本插件那一个 config 块（其它条目与注释原样保留）；白名单之外的键、非布尔值一律拒绝。写入是先写临时文件再 rename 的原子替换，并留一份 .bak-qqai 备份。
- 生效方式：写入后 DSH 会热重载本插件条目（QQ 桥会短暂重连一两秒）；若宿主没开热重载，重启宿主后生效。
- 没装 web 服务的宿主（如 TUI profile）不会有这一页——此时用
ctx.inject(['webServer']) 的那段代码根本不会执行，插件照常工作。
- 页面最上面是一组「相关链接」（v0.6.3 起，原来在页面最底下）：依次是 （→ 宿主的 ，点开即已登录的 NapCat 页面）、（GitHub 的 ）、（README 调试章节）、。地址由 / 推导。
想改的键不在面板里？直接编辑 profile 的 cordis.patch.yml（面板顶行会显示它是哪个文件）。面板刻意只放"日常会动的开关"，不做成任意配置编辑器。
配置
profile 的 cordis.patch.yml 覆盖 id: dsh-qq-onebot-bridge 的 config（完整示例见 examples/cordis.patch.example.yml）：
⚠️ 别改错文件：仓库根目录也有一个同名 cordis.patch.yml，那是安装用的 bundle patch（4 行，只有 insert: - id: …），不要往里填配置。真正要改的是 profile 目录里的那份，例如 ~/.dsh/profiles/web/cordis.patch.yml（Windows：C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml）——它在仓库外，密钥写在那里才不会进 git。
| 键 | 默认 | 说明 |
|---|
host | 127.0.0.1 | 反向 WS 监听地址 |
port | 6700 | 反向 WS 监听端口 |
accessToken | '' | OneBot 端须携带的 Bearer token（空=不校验） |
allowUsers | [] | 私聊用户白名单（空=拒绝所有私聊，务必填入自己的 QQ 号） |
allowGroups | [] | 群白名单（空=拒绝所有群消息，列出机器人服务的群号） |
botQq | 0 | 机器人 QQ 号（用于群内 @ 检测；0=任何群消息视为@） |
replyOnlyWhenMentioned | true | 群聊仅 @机器人 才回复 |
acceptPrivate | true | 是否回复私聊（私聊仍需 allowUsers 放行） |
autoCollectStickers | false | 自动收藏消息里的图片表情到本地图库 |
faceEnabled | true | 表情功能总开关（[face:] 标记 + qq_face_* 工具） |
sessionMode | chat | 群会话分组：chat=每群一会话；user=每群每人一会话 |
cwd | '' | 会话工作目录（同时决定 qq-faces/、qq-replies/、qq-bridge-debug.log 的位置） |
provider | '' | LLM provider 覆盖（空=agent 默认） |
model | '' | LLM 模型覆盖（空=agent 默认） |
maxMessageLength | 1700 | 单条出站消息最大字符数（超出自动分段） |
botName | 小鲸鱼 | 机器人显示名（合并转发卡片的署名） |
sessionResumeEnabled | true | 宿主重启后 resume 上次会话（完整记录续接）；关掉则每次重启都新建会话 |
agentMediaToolsEnabled | true |
v0.7.x 新增开关（面板里能改，也列在这里方便查默认值）
面板只覆盖 87 / 238 个键（刻意只放日常会动的；连接地址、端口、token、模型参数、提示词只在配置文件里）。
下面这几个是 v0.7 加的，默认值都在面板里能看到，这里只是给"看文档的人"一个索引。
| 键 | 默认 | 面板位置 | 说明 |
|---|
quoteReplyEnabled | false | 对话基础 | 回复时引用被回答的那条消息（只作用于群聊）；引用失败会自动去掉引用重发一次 |
longReplySplitOnPunctuation | true | 对话基础 | 长回复分批时优先在句末 → 句内标点断开；关掉后仍然按单条上限切成多条，只是变成等长硬切 |
extensionToolsEnabled | false | 实验性 | 允许同宿主其它插件通过 ctx.qqBridge.registerToolProvider() 注入工具与提示段（只能新增、抛错跳过并记 trace） |
taintDryRunEnabled | false | 实验性 | 污点窗口：入站命中注入句式后，该会话一段时间内所有出站写动作降级为 dry-run（问答照常），每次拦截都写 trace |
taintWindowMinutes | 30 | 实验性（与上一项同一行） | 污点窗口时长（1–1440 分钟） |
taintExtraPatterns | [] | 实验性 | 自定义注入句式：正则数组（≤20 条、每条 ≤200 字、大小写不敏感、内置 8 条优先）；坏正则保存时 400 拒掉 |
outboundRedactEnabled | false | 安全与风控 | 出站脱敏（防线三，v0.7.9）：发送前把文本里的密钥打码（sk-… / gh*_… / AKIA… / xox… / JWT / Bearer … / 私钥块）。QQ 号 / 手机号 / URL 不碰；只处理文本段 |
outboundRedactBlock | false | 安全与风控 | 命中时的动作：false = 打码后照发，true = 整条不发并记 trace |
outboundRedactPatterns | [] | 安全与风控 | 自定义脱敏规则（正则数组，≤20 条 / ≤200 字）；坏正则跳过并记 trace |
想知道"换了 OneBot 实现之后哪些功能会失效"：见 docs/COMPAT.md，
或者直接发 /health —— 第一行是识别到的实现，后面会点名失败过的动作与最可能的原因。
用户侧（OneBot 实现）配置
以 NapCat 为例：OneBot11 配置里把 WebSocket 客户端地址填成：
ws://127.0.0.1:6700/
其它实现同理（LLOneBot 填反向 WebSocket、OpenShamrock 填被动 WebSocket、go-cqhttp 填 ws-reverse）。若本插件配了 accessToken，OneBot 端填同一 token。
NapCat 一键启动与排障（v0.6.5）
机器人在线只要求 NapCat 反过来连 6700，不要求你能从这里启动它——但登录/扫码那一步通常得把 NapCat 拉起来。
- 不用手抄路径：DSH 面板「快捷操作 → 启动 NapCat」与控制台「启动 NapCat」会自己探测常见安装位置
（
%LOCALAPPDATA%\Programs\NapCat\bootmain\、%ProgramFiles%\NapCat\bootmain\、~\.dsh-qq\）。
都没找到时才需要填：控制台「配置 → NapCat 启动脚本」= …\NapCat\bootmain\launcher.bat
（别填同目录的 napcat.bat：那一版它只是拉起加载器 + pause，实测秒退什么都不做）。
控制台与 DSH 面板读的是同一份 qq-control.json，填一次两边都生效。
- 两个文件都在你的工作目录里（
qq-control.json 的 cwd）：
qq-napcat-launch.cmd（垫片脚本，点「启动 NapCat」那一刻才生成，所以安装包里没有它，别去插件目录翻）
与 qq-napcat-launch.log（提权窗口是隐藏的，启动脚本的输出全在这里）。
- 成功判据是日志里的心跳行（
=== shim start … ===）：提权那一跳被系统拦下时，powershell 退出码仍是 0、
6099 也可能一直在监听（NapCat 本来就在跑），只有心跳能证明"命令真的落地了"。没有心跳时界面会说
"这次点击什么都没发生"，请用管理员身份重开控制台/宿主，或手动右键 launcher.bat →「以管理员身份运行」。
- 本机策略
ConsentPromptBehaviorAdmin=0 时提权不弹窗，看不到 UAC 是正常的（不是"没反应"）。
- 「桥：无快照」怎么读（v0.6.5 起鼠标停上去有完整解释）：① 快照停在 N 分钟前 ⇒ 桥停了/插件被禁用；
② 宿主没跑 ⇒ 快照由宿主里的插件写出，先启动宿主；③ 宿主在跑却没快照 ⇒ 插件没启用，
或插件的工作目录与控制台配的不是同一个（插件把快照写成
<它自己的工作目录>\qq-runtime.json；
用控制台「启动宿主」两边就一致）。
语音转文字（STT）
触发规则（最终版）：
| 场景 | 行为 |
|---|
| 群聊：@机器人 + 引用（回复）一条语音 | ✅ 转写被引用语音并以文字回复 |
| 群聊：单独发语音（不@/不引用） | ❌ 不触发 |
| 私聊：直接发语音 | ✅ 转写并回复（不受 acceptPrivate 限制） |
| 私聊：文字 + 引用语音 | ✅ 转写被引用语音 |
实现链路：消息里的引用 → get_msg 找到被引用消息 → 其中含 record 段 → OneBot get_record（out_format mp3/wav，响应含 base64）→ POST {sttBaseUrl}/audio/transcriptions（multipart 字段 file 二进制）→ 转写文本注入会话。
注意事项：
- 智谱 GLM-ASR-2512 限 wav/mp3、≤ 30 秒、≤ 25MB；更长的语音请换 SiliconFlow 等端点
- 智谱接口的 multipart 字段必须是
file（二进制）——文档里写的 file_base64 实测会报 1214 错误
会话分组
- 群聊：
sessionMode: chat（默认）下每个群一个独立会话，全群共享上下文；user 下每群每人一个会话
- 私聊：每个私聊用户一个独立会话，与群聊完全隔离
- 会话创建时 agent 系统提示注入 chatScope（"你正在 QQ 群 xxx 里聊天"/"你在和用户 xxx 私聊"），并要求不串上下文
/new 仅重置当前会话；会话存内存，宿主重启后重建（不持久化）
表情系统
- 回复文本里写
[face:鼓掌] 等标记会替换为对应 CQ 表情段（黄脸表见 lib/faces.js，约 70 个）
faceEnabled=true 时每个会话注册 qq_face_list / qq_face_send 工具- 手动把图片放进
cwd/qq-faces/ 自动登记为可发送表情（文件名=表情名），删除文件自动剔除
autoCollectStickers=true 时自动收藏群消息里的图片表情
扩展接缝（v0.7.0）
同宿主里的其它插件可以不改本插件源码地"发一条消息、看一眼收发、加一组工具"，但没有绕过护栏的第二条路：
// ① 实例出口（宿主把它挂成 ctx.qqBridge；挂不上时用下面那个 import 兜底）
const r = await ctx.qqBridge.sendText('g:123456', '你好') // { ok, reason, chatKey }
await ctx.qqBridge.sendImage('u:1001', '/abs/pic.png', '配文')
ctx.qqBridge.sessions() // [{ chatKey, sessionId, turnActive }]（只读副本）
ctx.qqBridge.config() // 配置快照：token / apiKey / secret / password / cookie 已抹掉
// ② 只读事件（ctx.on 或 api.on；返回取消订阅函数）
ctx.on('qqbridge:inbound', (e) => console.log(e.chatKey, e.text))
ctx.on('qqbridge:outbound', (e) => console.log(e.chatKey, e.kind, e.text))
// ③ 实验性：工具 provider（需要打开面板「实验性」组里的开关）
ctx.qqBridge.registerToolProvider(({ agentCtx, route, key, config, workspaceRoot }) => ({
tools: [ /* defineTool(...) 的返回值 */ ],
sections: [ /* { name?, order?, text } */ ],
}), { name: 'my-plugin' })
// ④ 拿不到 ctx 时（插件加载顺序 / 独立进程）：包导出了入口，别再写 file:// 绝对路径
import { getExtensionApi } from 'dsh-qq-onebot-bridge/extension'
const api = getExtensionApi()
// ⑤ 桥实例标识：宿主重建桥（重启 / 热重载 / 面板点开关）后这个值会变，
// 第三方据此判断"我注册的 provider 还在不在原实例上"，不用靠轮询猜
if (api.instanceId !== lastInstanceId) { lastInstanceId = api.instanceId; reRegister() }
- 发送一律复用原有护栏（出站限流 / 注入抑制 / 分段 / 合并转发 / 路径解析 / ActionGate 配额 / TTS 可用性），
并额外检查目标是否在白名单——否则第三方能绕过白名单主动打扰名单外的人/群，而风控封的是机器人自己的号。
- 入站事件在白名单 / 静默 / 去重之后、命令与模型之前发出：监听不可能绕过门禁；文本是归一化后的那份。
- 只读：事件不能改写内容、不能拦截消息；监听器抛错或异步 reject 只记一条 debug。
- 工具 provider 是实验功能、默认关：只能新增（不能覆盖 10 个内置
qq_* 工具）、provider 抛错只跳过它自己、
每 provider 16 工具 / 4 段、总计 40 / 12 的上限；注入与跳过全部进 trace。外部扩展的行为不在本项目维护范围内。
（工具上限 v0.7.1 从 8 抬到 16：有真实使用者按"一个包一类工具"拆分，正好卡在 8 上。提示段仍是 4 —— 那是每条消息的固定成本。）
- 写 provider 的三条注意事项（① 是第三方实战报告，②③ 已按宿主源码核对）：
① 不要改写
agentCtx.tools（比如给 .register 赋值）。agentCtx.tools 背后是宿主共享的 ToolRuntime
（@deepseek-ai/dsh-tools 里 class ToolRuntime extends Service；register() 内部是
this.layers.effect(this.ctx, layer => layer.tools.insert(name, definition))）。第三方实测：直接赋值会落到
进程级实例上，所有 agent 一起被改，且没有任何警告。想按会话过滤工具，正确做法是 Object.create(tools) 造视图 +
只 defineProperty 一个 register，再用 Proxy 只拦 tools 这一个键，其余（systemPrompt / context / ctx）反射透传。
② tools.restrict({ allow, deny }) 只作用于全局工具，不是"把这一层收窄成几个"。按 @deepseek-ai/dsh-tools@0.2.0-rc.2
的类型原话："Per-scope filter over global tools. Restrictions intersect and do not affect scoped registrations"，
allow 是 "Global tool names that stay visible; everything else is removed"。
所以：没被点名的全局工具会静默消失（预设层的 web_search 也会），而自己 scope 里注册的工具不受影响。
③ 上面那个 restrict 还有一半是不静默的：名字必须是已知全局工具，写错名字（以及空 filter、run_code、scope 内名字）
会直接抛错（unknown global tool / requires a scoped context / is a no-op）。
要收窄优先用 deny（只禁点名的），或者把过滤做在自己的视图层，别去动共享 runtime。
- 写 provider 的四条注意事项（v0.7.3，来自第一个真实第三方插件的实测，出处见 issue #4 作者的
ext/README.md）：
① 参数必须是标准 JSON Schema：直接返回裸工具对象时，宿主用 assertSupportedJsonSchema 校验，
属性里写 required: true 会被直接拒，必须写成对象顶层的 required: ['name'] 数组。
用本项目的 defineTool({...}) 则自动转成这份标准形状（推荐）。
② ：cordis 的 live reload 只重新 、，
状态写在 内会每次多堆一个同名 provider（新工具因重名被跳过，trace 里一串 skipped）。状态请放模块级。
③ ：桥重启 / 热重载 / 面板点开关都会重建实例，你的 provider 就不在了 ——
所以第三方应自己重挂（例如每 5s 检查一次 ，
不在就重新 ；别做成"注册成功就停"的一次性轮询）。
④ ：改 的 config 会触发热重载（重跑 ），但改
本身不会重新 import —— 常见做法是把工具实现放在 ，每次 带时间戳重新 import 它。
第三方扩展（社区）
- 551123 / dsh-qq-onebot-bridge ·
patches/0.7.9/ext ——
第一个真正用 registerToolProvider 的插件集：小屋 / 页面与笔记 / 工作区 / 表情四个包、20 个工具，
按我们的 tag 维护，ext/README.md 里写了安装方式与五条硬约束（file:// 解析、标准 JSON Schema、同步返回、状态放模块级…）。
由作者本人维护，不在本项目的支持范围内；这里只做指路，出问题请去他仓库提。
链接约定（作者与他约定的，写在这里免得每次都要问）：分支永远叫 patches/<我们的 tag>、ext/ 永远在分支根目录，
所以这条链接只需跟着最新 tag 改；分支里是 1 个提交还是十几个，都不影响这个地址。
兼容承诺（我们怎么改这些接口）
公开的东西一旦有人用，就不能随手改了——所以规则先写在这里：
- 只增不改：新增方法 / 新增事件字段 / 新增返回字段 → 不升版本，老调用方不受影响。
- 删改现有名字或形状（改名、改参数顺序、改变返回值含义、把异步改成同步…）→ 升
version（现在是 1），
并且旧版至少保留一个小版本，README 上标 deprecated，到期才删。
- 事件只读不变：不会给
inbound / outbound 加"能改内容 / 能拦消息"的返回值——要那种能力请另开插件，不走这个接缝。
- "有没有人在用"看得到，但不是"统计"：只有出口真的被调用过，面板「实验性」组才多出一行
出口被调用（本机计数：只在内存里累加，不含消息内容、不外传、重启清零）：sendText N · …。
全 0 时整行不显示。它不落盘、不进 qq-runtime.json、不发任何请求，面板也只由本机宿主提供 ——
换句话说：它数的是"别人有没有调用这个 API"，不是"你在用什么"；没数字就说明没人在用，
那时任何破坏性改动都不疼，一旦有数字，上面三条就生效。
- 内部实现（私有方法、文件格式、trace 字段）不在此承诺范围内，随便重构。
关于 fork：上游只有一条线
- 本仓库只维护
main + tag（例如 v0.7.4）。GitHub 上的 fork 是别人的副本：它不等于上游分支，
也不会自动进这里——fork 里有多少提交，这条 main 一条都不受影响。
- 我们不合并、也不 rebase 别人的 fork 历史：那些提交按 fork 作者自己的节奏演进，硬并进来历史会读不懂。
想贡献就开 issue 或 PR（小改动直接 PR 最快）；想长期维护一条自己的线也完全没问题——按我们的 tag rebase 即可。
我们不会去抄你的提交历史，但想法可以取（v0.7.4 的「污点窗口」就来自 issue #4 作者的补丁分支）。
- 装的时候认准本仓库或 npm 包，别从任意 fork 装——里面的代码可能被改过，而 README 与 CHANGELOG 只描述这条线。
- 给"按字面锚点做补丁"的人：我们重构不会为兼容放慢，但会在 CHANGELOG 里点出来——
尤其是
lib/bridge.js 顶部的 import 块、以及某个函数被整块重写这种会让人重锚的改动。
（这条是 issue #4 作者要求的：他的补丁库靠"在 pristine 的哪个唯一字符串处替换"定位，import 一动锚点就没了。）
命令与调试
命令清单不写死在 README 里，因为它是按你打开的开关动态生成的 —— 在 QQ 里发 /help（或「帮助」「菜单」）
就能看到当前这份配置真正可用的命令（关掉的玩法不会出现，省得你以为是坏的）。
下面是按用途的摘要，细节见 docs/FEATURES.md：
| 用途 | 常用命令 |
|---|
| 会话 | /new 新对话 · /status 会话状态 · /summary 群聊总结 · /export 导出记录 |
| 查询 | /为什么 某条消息为什么没回 · /health 运行诊断 · /成员 名单/详情 · /群信息 /公告 /荣誉 /精华 · /找一个历史 · /文件 /取 /相册 /ocr |
| 玩法 | 「签到」打卡 · /签到榜 · /积分 /排行榜 /转账 · 「今日人品」「抽签」 · .r 3d6 · 「接龙」「猜数字」 · /画 生图 · /读 朗读 |
| 群运营 | /mute /unmute /kick /clear · /公告 /全员禁言 /名片 /头衔 · /批量踢 · /禁言名单 /全体余量 · /退群（慎用） |
| 管理/调试 | /reminders 提醒 · /todo 待办 · /日报 · /kw 词库 · /播报 · /赞榜 /谁赞了 · /点赞 /戳 · /能力体检（只读探针，见下） |
两条最常用的（单独说清楚）：
-
/为什么（v0.6.9）：引用那条消息发 /为什么（或 /为什么 <消息id>、不带参数查本会话最近一条），
它把 trace 的决策链翻译成人话：收到消息✅ → 白名单✅ → 静默时段⛔ + 「卡在「静默时段」：…」。
群聊仅管理员可用；只给环节与原因，不回显消息原文。
-
/health：一次性体检（连接、闸门、录制/注入状态、配置生效值），和面板顶部那份诊断同源。
-
/能力体检（v0.7.9）：对当前 OneBot 实现跑一轮只读探针（21 个 get_* 动作，逐个分类成
「支持 / 不支持 / 参数不符 / 权限不足 / 无响应」），回答"这个功能是真不支持，还是我还没用到"。
写操作永远不探（会改 QQ 状态）；群里仅管理员可触发。详见 docs/COMPAT.md。
-
调试日志：{cwd}/qq-bridge-debug.log（消息路由、语音转写、agent 事件，按时间戳追加）
-
宿主错误日志：启动 dsh web 时把 stderr 重定向到文件（如 %LOCALAPPDATA%\qq-host-err.log）可查启动崩溃
-
关键日志标记：voice fetched via get_record、quoted voice transcribed、followup sent (voice)、group msg without @bot ignored
测试
65 个单测脚本，共 4224 项断言（test/*-unit.mjs）+ 3 个真机脚本：
# 1) 单元测试：不联网、不起宿主，纯逻辑 + 临时目录（推荐每次改完都跑）
node test/control-unit.mjs # 也可以逐个跑：node test/<name>-unit.mjs
# 62 个文件：桥的分支/命令/守卫、控制台 HTTP 与体检、录制回放与注入、注入安全边界、硬约束验收台、
# `/为什么` 的决策链翻译（why-unit）…
# 一次性全跑（PowerShell）：
# Get-ChildItem test -Filter '*-unit.mjs' | ForEach-Object { node $_.FullName }
# 2) 回放的端到端验收：真实桥代码 + 真实 OneBot 服务端，沙箱 + dry-run，不需要宿主
node test/replay-live.mjs
# 3) 真机脚本（需要宿主/控制台已在运行，自己扮演 OneBot 客户端连 6700）
node test/live-e2e.mjs # 消息 → 回复 全链路
node test/live-stream.mjs # 实时事件流 / 决策链 / 体检接口（控制台 8799）
node test/replay-live-host.mjs --token <控制台 token> # 录制 → 离线回放 → 注入
老版本的 sim-*.mjs 协议模拟脚本保留在 test/ 下，仍可用于手工排查（node test/sim-group.mjs 等，需宿主运行）。
语音转文字链路建议直接用 QQ 实测（模拟脚本需真实 STT 调用）。
记忆与人设说明（重要）
本插件不内置任何人设、偏好或群规则。小鲸鱼人设、问答偏好、群内行为规则等记忆内容由 dsh-mnemon 插件的运行时记忆（~/.mnemon/runtime/USER.md + MEMORY.md）注入每个 QQ 会话——插件只负责"功能"，记忆只负责"灵魂"，两者完全解耦。换人设只改 Mnemon 记忆，换功能只动本插件。
⚠️ 风险与合规说明（使用前必读）
账号风控风险
- 本插件通过第三方协议实现（NapCat 等）接入 QQ，不是腾讯官方接口，与《QQ 软件许可及服务协议》相悖，QQ 官方明确禁止非官方客户端/协议
- 使用第三方协议存在账号被限制登录、冻结、甚至永久封禁的风险，且可能波及其他正常使用的 QQ 账号（同设备/同 IP）
- 建议使用机器人小号运行，绝不要用大号/常用号
- 常见风控诱因：高频发言、短时间大量消息、发送营销/广告/违规内容、被多人举报、异常登录设备
- 缓解建议：降低回复频率、仅在小群/自用场景运行、不 24 小时刷屏、严格内容合规
内容风控
- agent 生成的一切内容都会以机器人账号身份发出，使用者对该账号发布的内容负全部责任
- 建议在人设/系统提示中约束输出合规内容；违规内容既触发账号处罚，也可能带来法律责任
安全风险
allowUsers / allowGroups 未配置（为空）时，插件默认拒绝所有私聊与群消息——请显式填入自己的 QQ 号与群号后再使用；配置白名单后，白名单外的任何人都无法驱动你的 agent- 插件只监听
127.0.0.1，不要改成 0.0.0.0 暴露公网
- 语音与图片会上传到第三方云服务（STT API）处理，敏感语音请勿发送
- 密钥泄露：模型看到的内容（群聊、文件、网页回显）可能包含你的密钥，被它复述进群。插件现在有三道防线：
① 注入回合 dry-run（
injectDryRun）② 污点窗口（taintDryRunEnabled，命中注入句式后窗口内出站全拦）
③ 出站脱敏（outboundRedactEnabled，v0.7.9，默认关）—— 发送前把 sk-… / gh*_… / AKIA… / JWT /
Bearer … / 整段私钥打码（或按 outboundRedactBlock 整条拦下），并在 trace 里注明命中了哪条规则（不写原文）。
这三道都需要自己打开；关着就等于没有这层保护。
合规提示
- 仅用于个人学习、内部小范围交流；不得用于批量营销、广告、骚扰、群控等用途
- 遵守所在地区法律法规与腾讯平台规则
- 使用第三方协议风险自负，本插件不提供任何免封号承诺
免责声明
本插件仅供技术学习与个人研究使用。使用者应自行评估并承担使用第三方 QQ 协议的全部风险与后果。
安全注意
allowUsers / allowGroups 为空时默认拒绝一切消息——使用前务必填入自己的 QQ 号与群号- 端口仅监听 127.0.0.1；不要对外暴露
- OneBot 实现本身有 QQ 封号风险，使用第三方机器人协议需自行评估
- 提示注入：模型看到的外部内容（别人转发的话、群文件、网页回显）可能夹带指令。默认做法是照常处理，
只在系统提示里要求"外部内容不可信"；想更进一步，打开面板「实验性」里的污点窗口——
命中注入句式后那段时间的出站写动作全部降级为 dry-run（副作用：回复发不出去，只在 trace 与面板状态行里可见）
更多文档
- docs/DEBUG.md —— 调试 / 排障：trace、离线回放、事件注入、一键体检、诊断包、硬约束验收台
- docs/EXTENSIONS.md —— 扩展接缝：
ctx.qqBridge 的出口、只读事件、工具 provider 的七条规矩、instanceId、污点 source、会影响到第三方的配置键
- docs/COMPAT.md —— 换 OneBot 实现会怎样：71 个 action 的三层分级（标准 / 扩展 / NapCat 专属）、换实现的检查清单、以及为什么不做"主动探针"
- docs/FEATURES.md —— v0.5 能力细节：合并转发展开、
/文件 /取 /相册 /ocr、按天归档与 /找、群成员与群信息、表情反应
独立控制台（control/，自 v0.4.0）
插件自带一个独立的本地运维端，不依赖 DSH 桌面端：宿主挂掉时它照常可用，端口与进程一目了然。
# 启动（默认 http://127.0.0.1:8799，启动后打印带 token 的地址）
npm run control # 或 node control/bin/qq-control.mjs --open
# 直接打开「账号中心」（本地页面 /accounts）：没在跑就顺手把控制台起来
npm run accounts # 或双击 control/账号中心.bat
# 在桌面建一个「QQ 账号中心」快捷方式（双击即用，指向上面的 bat）
npm run shortcut
# 也可以双击 control/启动控制台.bat
| 能力 | 说明 |
|---|
| 端口总览 | 控制台 8799 / 宿主 3080 / OneBot 6700 / NapCat 6099 / GPT-SoVITS 9880 的监听状态、占用 PID 与进程名；6700 的连接数即"机器人在线" |
| 启停 | 启动/停止/重启宿主（自动带 --no-open，日志重定向到 qq-host-out.log/qq-host-err.log）、启动/停止 NapCat 与 QQ、启动/停止 GPT-SoVITS、一键全停 |
| 启动预检 | 起宿主前检查 3080/6700，被占则直接报「端口←进程#PID」，而不是静默失败 |
| 释放端口 | 对占用受管端口的进程一键 taskkill /T /F（护栏：只允许受管端口占用者与已知机器人进程，绝不误杀无关 PID） |
| 日志 | 宿主 stdout / stderr / 桥调试日志，自动跟随、可切行数 |
| 扫码状态 | 显示 NapCat 二维码图片是否存在、是否新鲜，并一键打开 6099 扫码页 |
| 配置 | qq-control.json 是端口与路径的唯一真源（自动探测 node、dsh bin.js、NapCat、TTS 脚本；可在 UI 里改路径）；6700 被 NapCat 配置写死，勿改 |
| 调试 | 「录制 · 回放 · 注入」：列出 qq-inbox.jsonl 里录到的每条消息，可一键离线回放（沙箱 + dry-run）或注入合成事件；注入队列状态（行数 / 本次已消费 / dry-run）直接显示 |
| 验收 | 顶部「硬约束验收台」：6 条硬约束的实时证据（无静默分支 / traceId 贯穿 / 可回放 / 可体检 / 可导出 / 可注入），不达标项直接说明该点哪里；GET /api/acceptance |
| 账号中心 | /accounts（v0.7.11 起）：本地页面直接看 NapCat WebUI 的地址与打码 token、登录状态、扫码二维码、快速登录列表与本机账号配置；可一键「快速登录」或「设为自动登录」。只连本机，webui.json 的 token 只在服务端使用；NapCat 没起时如实说「连不上」而不是报错 |
| 安全 | 只绑 127.0.0.1；所有 API 需要 token；带 Origin 的跨站请求一律拒绝 |
以后若想做真正的托盘/桌面程序，直接包一层 Electron/Tauri 复用同一套 HTTP API 即可，逻辑无需重写。
排障：NapCat「点重启没反应 / 自己起不来」
真机上踩过的现象与原因，写在这里省得再查一遍：
| 现象 | 原因 | 处理 |
|---|
手动跑 napcat.bat，只打印一行 argv[0]:.\NapCatWinBootMain.exe 就退出，QQ 没起 | 该 bat 里是 NapCatWinBootMain.exe 不带参数；引导器需要 QQ 号才干活 | 用带参数的启动方式：NapCatWinBootMain.exe <QQ号>（同目录的 quick.bat 就是这么写的），或 launcher.bat |
用 spawn 拉起却没反应，直接跑又正常 | bat 里用的是 .\NapCatWinBootMain.exe 相对路径，cwd 不对就找不到 exe | 启动时把 cwd 设到 bootmain/ 目录 |
| 控制台点「重启 NapCat」只报「连不上」 | 旧实现只调 WebUI 的 RestartNapCat，进程不在时必然失败 | v0.7.11 起：连不上就用 QQ 号拉起（autoLoginAccount → onebot11_<uin>.json 兜底），没有 uin 再退回 launcher.bat |
| 拉起时弹出 UAC / 需要管理员 | launcher.bat 会 net session 自检，非管理员就调 launcher-elevate.ps1 用 wt.exe 提权 | 进程无法静默提权，UAC 必须本人点；不想提权就用 NapCatWinBootMain.exe <QQ号> 的直启方式 |
| 页面显示「NapCat 连不上（可能正在重启）」 | 6099 在 NapCat 重启窗口内不监听 | 页面已自动重试 3 次（间隔 2 秒）；仍失败会给「重试」按钮，等十几秒再点 |
排查顺序建议：先看 6099 有没有在听 → 再看 QQ.exe 有没有起来 → 都正常但页面还报连不上，再回去看 webui.json 的端口与 token。
隐私与脱敏
出问题排查往往要把日志发给别人，所以本插件对"数据会去哪"有明确约定：
| 项 | 约定 |
|---|
| 诊断包 | 「导出诊断包」默认勾选脱敏：QQ 号按位掩码（保留前两位）、消息原文替换为「[已脱敏 N 字]」，包内附 REDACTED.json 说明口径；取消勾选才导出明文（会有提醒） |
| 运行产物 | qq-inbox.jsonl（消息原文）、qq-trace.jsonl（会话键 + 文本片段）、qq-runtime.json、qq-actions.log 等只写本机工作目录，且全部被 .gitignore 覆盖（qq-*/、qq-*.json、qq-*.jsonl、qq-*.log 通配 + 逐项列出），cwd 恰好在仓库里也不会误提交 |
| 录制脱敏 | inboxRedact: true 可在录制阶段就把 QQ 号脱敏 |
| 仓库本身 | 不含任何密钥/口令/真实 QQ 号：密钥只存在于你的 DSH profile 配置（仓库外）；test/privacy-unit.mjs 每次跑测试都会重新扫描全部被跟踪文件（真实号从你本机私有配置或 DSH_QQ_PRIVATE_IDS 现取，测试文件里不含真实号） |
| 控制台 | 只绑 127.0.0.1，所有接口需 token（存在被忽略的 qq-control.json），拒绝跨站 Origin |
部署事实：本插件是 DSH bundle，运行在 DSH profile 内，@deepseek-ai/dsh-*、@deepseek-ai/schemastery 等官方 peer 依赖随 profile 一起装好。官方包必须写全作用域名：不带作用域的 schemastery 是另一个包（3.18.0），只有在"别的插件恰好把它 hoist 到共享 node_modules"时才能解析——v0.4.0 之前 lib/ 正是这么写的，换到干净环境立刻 ERR_MODULE_NOT_FOUND（issue #1）；现已统一用作用域名，并由 test/static-unit.mjs 静态守住（裸名/未声明的 import 直接测试失败）。ws 是普通运行时依赖，本地目录安装要按上面「安装」一节先 npm install。把 lib/ 单独拷出来裸跑仍然跑不起来（设计如此，不是缺依赖）。
更新日志
每个发过的版本都有 Release 页（27 个 tag 全覆盖：该版改了什么 + 与上一版的完整 diff 链接）：
https://github.com/cheesehaqi/dsh-qq-onebot-bridge/releases —— 想快速判断"要不要升级"看这里；
想读完整历史（缺陷清单、测试计数）看 CHANGELOG.md。
最近五个版本（始终滚动展示）：
- v0.8.3 — 「控制台自己会体检」：版本更新检查、端口占用显示、
napcat.json 只读预览（脱敏）、插件目录带 config/pages 标记、文件统计、配置回收站（还原 / 送 Windows 回收站，不硬删）、复制诊断摘要、网络未保存提示、实时测试「只看失败 + 事件过滤」；并修好场景注入群号/QQ 号被丢弃、场景下拉为空
- v0.8.2 — 「少点几下」：文件与账号搜索、日志时间范围与「下载跟随筛选」、操作记录导出/清空、最近一次错误卡片、Ctrl+K 命令面板（含账号跳转）、日志筛选偏好持久化、插件目录条目可复制路径；测试新增 DOM 时序断言与运行时冒烟（含反向验证）
- v0.8.1 — 「让控制台能自证」：配置备份管理（还原前另存
.pre-restore-*、删除移到 config/_trash）、操作记录持久化、日志关键词高亮 + 只看 Info 以上、一键导出脱敏诊断包、网络配置的 WS 服务器与 HTTP 服务器段可编辑，以及「新建」入口统一
- v0.8.0 — 「本地账号中心」：
/accounts 11 个分区（基础信息 / 账号配置 / 网络配置 / 文件 / 插件 / 运行日志 / 实时测试 / 运行与设备 / 系统配置 / 操作记录 / 关于）；网络配置可增删改与启停、系统配置可改端口与回环地址、插件可启停卸载，写前均有 .bak 备份；实时测试支持「单发 / 即时调试 15 秒」并能点开事件看完整链路；修掉 assistantText 在 content 非数组时崩溃（会吞掉整条回复）
- v0.7.10 — 「能力体检 + 两处测试口径修正」：①
/能力体检（lib/conformance.js）—— 21 个只读探针（状态/版本/登录号/群与好友/成员/荣誉/精华/公告/群文件/历史消息/@全体余量/禁言名单/群打卡/群相册/系统消息…），逐个分类成「支持 / 不支持 / 参数不符 / 权限不足 / 无响应 / 没有数据」，回答"这功能是真不支持还是我没用到"；写操作永远不探，且 assertProbeSafety() 会拒绝任何 send_/set_/delete_/upload_/mark_ 条目 —— 手滑加一条写操作，体检直接拒跑。结果落到 trace、面板「高级与调试」与 knownUnsupported。② 两处测试口径：inject-guard-unit 的 7 处数组全等改成后缀匹配（宿主给正文加前缀不再整段崩，且不会把「注入的消息」认成「注入的消息二」）；privacy-unit 区分「git 检出缺 .gitignore（照红）」与「npm 包形态缺（显式跳过）」。面板不变（87 键）。
更早的版本（v0.4 线及之前）见 CHANGELOG.md —— 完整历史、每个版本的缺陷清单与测试计数都在那里。
也可以直接在 Releases 页按版本过滤（每版都带 compare/v上一版...v本版 的 diff 链接）。
