dsh-qq-onebot-bridge
QQ ↔ DeepSeek Harness 双向桥插件（独立 bundle）。QQ 消息直接驱动 DSH agent 会话，agent 回复自动发回 QQ。
v0.4.0 主题：一切皆可调试。每条消息一个 traceId、每个"没回复"都有中文原因、任意历史消息都能离线重跑、假事件能喂进真实管线——而且这 6 条硬约束在自带控制台里随时可验收（见「调试」与「硬约束验收台」）。
功能总览
这里只列最近两个大版本新增的能力（v0.5 线与 v0.4 线）。更早的基础能力——双向消息桥、会话续接、持久化记忆、定时提醒、群管套件、TTS、生图、签到打卡、积分与小游戏、防撤回、敏感词过滤……——全都还在，逐版本记录见 CHANGELOG.md，开关与配置见下方「配置」。
v0.5 线
- 看得见（v0.5.0）：别人合并转发的聊天记录不再被静默丢弃——
get_forward_msg 展开成正文交给模型；同时接通了早已封装却没人调用的能力：/成员（名单/详情）、/群信息、/好友（默认关）、/退群（默认关）、agent 工具 qq_recent_history / qq_member_info / qq_react（表情回应）
- 找得回（v0.5.0）：
/文件、/文件 文件夹名、/取 文件名（下载后只发私聊）、/相册、/ocr（图片转文字）；消息按天归档到 cwd/qq-history/，/找 关键词 与 agent 工具 qq_search_history 在最近 N 天里检索（控制台也有「群资产 · 历史检索」卡片）
- 无人值守（v0.5.2）：入站 webhook（
127.0.0.1:8798，token / HMAC 二选一鉴权，限频 + 64 KiB 上限）把外部系统事件推进会话；定时播报（RSS / 天气 / MC，/播报 管理）；掉线自愈（只拉起、不杀进程，带冷却与每小时上限）
- 点一下就完事（v0.5.3）：
/戳 主动戳一戳、被戳回戳、私聊「正在输入」、自动贴表情、表情回应统计 /赞榜 /谁赞了、/点赞、标记已读（真机探针结论：该 NapCat 构建发不出内联按钮，故按能力探测降级）
- 群运营工具箱（v0.5.4）：
/群打卡、/全体余量、/禁言名单、/群详细、/入群通知、/批量踢（两步确认 + 分批执行）、/待办 /完成待办 /取消待办、/移动文件 /重命名文件 /删文件 /新建文件夹、/传图、/群名 /群备注、/群权限、/历史可见、/周报
- 控制台看得见（v0.5.5）：性能面板（P50/P95）、定时任务面板、群配置页、回放 diff、注入场景库（17 个场景一键注入）
- 补丁版本不新增功能：v0.5.1 审查修复、v0.5.6 真机启动修复 + 完整审计、v0.5.7 纯文档（详单见 CHANGELOG.md）
v0.4 线
- 一切皆可调试（v0.4.0）：6 条硬约束全部落地，并且在控制台里可随时验收——① 每个「没回复」都带中文 reason ② 一条消息一个 traceId 贯穿 ③ 可回放（录制 · 离线重跑真实管线）④ 可体检（一键体检报告）⑤ 可导出诊断包（默认脱敏）⑥ 可注入假事件；每条消息走结构化事件 + SSE 实时事件流
- 自带控制台（v0.4.0）：
control/（端口 8799）——会话列表、实时事件流、trace 检索、体检报告、诊断包导出、录制与离线回放、事件注入、硬约束验收台
- 依赖修复（v0.4.1）：改用
@deepseek-ai/schemastery，修好干净环境的安装依赖（issue #1）
架构
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 一起装好，插件目录里不需要重复安装。
配置
profile 的 cordis.patch.yml 覆盖 id: dsh-qq-onebot-bridge 的 config（完整示例见 examples/cordis.patch.example.yml）：
| 键 | 默认 | 说明 |
|---|
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 |
用户侧（OneBot 实现）配置
以 NapCat 为例：OneBot11 配置里把 WebSocket 客户端地址填成：
ws://127.0.0.1:6700/
其它实现同理（LLOneBot 填反向 WebSocket、OpenShamrock 填被动 WebSocket、go-cqhttp 填 ws-reverse）。若本插件配了 accessToken，OneBot 端填同一 token。
语音转文字（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 时自动收藏群消息里的图片表情
命令与调试
/new：结束当前会话并开新会话/status：查看当前会话状态与 sessionId 前缀- 调试日志：
{cwd}/qq-bridge-debug.log（消息路由、语音转写、agent 事件，按时间戳追加）
- 宿主错误日志：启动 dsh web 时把 stderr 重定向到文件（如
D:\qq-work\qq-host-err.log）可查启动崩溃
- 关键日志标记：
voice fetched via get_record、quoted voice transcribed、followup sent (voice)、group msg without @bot ignored
测试
55 个单测脚本，共 3434 项断言（test/*-unit.mjs）+ 3 个真机脚本：
# 1) 单元测试：不联网、不起宿主，纯逻辑 + 临时目录（推荐每次改完都跑）
node test/control-unit.mjs # 也可以逐个跑：node test/<name>-unit.mjs
# 36 个文件：桥的分支/命令/守卫、控制台 HTTP 与体检、录制回放与注入、注入安全边界、硬约束验收台…
# 一次性全跑（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）处理，敏感语音请勿发送
合规提示
- 仅用于个人学习、内部小范围交流；不得用于批量营销、广告、骚扰、群控等用途
- 遵守所在地区法律法规与腾讯平台规则
- 使用第三方协议风险自负，本插件不提供任何免封号承诺
免责声明
本插件仅供技术学习与个人研究使用。使用者应自行评估并承担使用第三方 QQ 协议的全部风险与后果。
安全注意
allowUsers / allowGroups 为空时默认拒绝一切消息——使用前务必填入自己的 QQ 号与群号- 端口仅监听 127.0.0.1；不要对外暴露
- OneBot 实现本身有 QQ 封号风险，使用第三方机器人协议需自行评估
调试（v0.4「一切皆可调试」）
每条入站消息都有一个 traceId，每个决策点（包括每一次"不回复/丢弃/降级"）都会留下 stage + ok + reason + 耗时。这是本版本的核心设计理念：出问题时不用猜。
| 想看什么 | 在哪看 |
|---|
| 6 条硬约束此刻达标吗 | 控制台最上面「硬约束验收台」：6 行状态灯 + 机器上现有的证据 + 该点哪里的提示，每 30 秒自动重算 |
| 单条消息的完整决策链 | 控制台「实时事件流」点任意一行 → 「决策链」显示时间轴、停在哪一步、为什么 |
| 为什么机器人不回复 | 「实时事件流」筛"仅被拒/失败"，最常见原因直接列出（如 mention: 群聊未 @ 机器人） |
| 每个端口的占用与在线 | 控制台「端口 / 进程」（6700 的连接数即机器人在线） |
| 一键排查 | 控制台「一键体检」：15-19 项 pass/fail + 修复建议（依赖路径、端口、链路、快照、错误、闸门拒绝…） |
| 生效配置（为什么功能没生效） | 控制台「运行快照」里的"关闭中的开关"；完整字段在 qq-runtime.json 的 features（不含任何密钥） |
| 打包给别人看 | 「导出诊断包」→ 一个 zip（事件流/审计/桥日志/宿主日志/运行快照/体检报告/环境信息） |
| 文件级排查 | qq-trace.jsonl（结构化事件，可 jq/grep）、qq-bridge-debug.log、qq-actions.log（写操作审计）、qq-host-out.log/err.log |
相关配置：traceEnabled（默认开）、traceLevel（debug 全量 / warn 只留问题）、traceMemorySize、traceFile。
调试接口（控制台，token + Origin 双重校验）：/api/trace、/api/stream（SSE）、/api/runtime、/api/diagnose、/api/export。
录制 · 离线回放 · 事件注入（v0.4 阶段 3）
前两项解决了"现在发生了什么"，这三项解决"这条消息当时为什么这样、换成别的输入会怎样"。
| 能力 | 怎么用 | 说明 |
|---|
| 录制 | 自动 | 桥收到的每条消息/通知/请求都追加到 qq-inbox.jsonl（可 JSON 逐行解析、按大小轮转），只写本机、不改任何回复行为 |
| 离线回放 | 控制台「录制 · 回放 · 注入」→ 某行「回放这条」／「回放最近 5 条」 | 在沙箱目录里用真实桥代码重跑这条消息：dry-run 拦截所有出站、不建任何 QQ 连接、源目录一个字节都不改。结论逐条给出"会回复/静默/出错 + 原因 + 会发送什么" |
| 事件注入 | 控制台填 群号/QQ 号/文本 → 「注入」 | 写一行到 qq-inject.jsonl，桥按 injectIntervalMs（默认 2s）轮询后走真实管线处理；injectDryRun（默认开）下所有出站调用被拦截并计数，注入内容永远不会真的发到 QQ |
回放的保真度来自运行时快照里的线上决策配置（白名单、安静时段、各功能开关等 28 项，见 qq-runtime.json 的 replay）：否则插件默认值里"白名单为空 = 拒绝一切"会让回放全部判成静默。回放里不含真实模型输出——模型那一轮用一条带 [回放] 前缀的模拟回复代替，用来验证链路与分支，不验证措辞。
排障要点：
- 注入通道未开启时会直接报错并说明开关名（
injectEnabled），不会静默丢进队列；
- 注入触发的 agent 回合是异步的：dry-run 窗口只在同步阶段开着，所以模型真正的回复会在事件流里被单独拦下（
注入回合的模型回复已被拦截（dry-run，未发送）：<原文>）——注入既能走真实管线，又不会漏发一条；真人消息不受影响（收到真实消息立即解除该标记）；
- 回放的帧在事件流里标为
replay: 离线回放（沙箱 + dry-run，不碰 QQ），注入的帧标为 inject: 来自注入器，两者不会互相误判；
- 桥启动时若队列里已有历史行，会跳过它们并在事件流里记一条"本次启动跳过 N 行（只处理启动后新增的行）"，避免重启后重放旧注入；
- 注入的帧不会被二次录制（否则回放/注入会互相激发）；
- 回放沙箱默认保留最近 5 次，更旧的移入回收站（
qq-replay/_trash/<日期>/），不做物理删除。
相关配置：recordInbound（默认开）、inboxFile、inboxRedact、injectEnabled（默认关）、injectFile、injectDryRun（默认开）、injectIntervalMs。
调试接口：/api/inbox、/api/replay、/api/inject、/api/queue/clear。
硬约束验收台（v0.4 阶段 4）
上面两条解决了"现在发生了什么"和"当时为什么这样"。验收台解决第三个问题：设计理念有没有真的落地。
GET /api/acceptance 把 6 条硬约束逐条用机器上现有的产物算成 ✅ 达标 / ⚠️ 有提示 / ❌ 不达标 / ❔ 证据不足，并给出证据与下一步：
| 约束 | 判定用的证据 |
|---|
| ① 无静默分支 | 最近 500 条事件里所有 ok:false（被拒/失败）事件是否都带非空 reason；缺的会点名 stage |
| ② 可关联（traceId） | 消息级事件的 traceId 覆盖率、有多少条消息真正走完 inbound→reply |
| ③ 可回放 | 录制条数 + 最近一次回放的统计与安全保证（dry-run 开、QQ 连接 0、cwd 已沙箱化）；dry-run 被关掉直接判不达标 |
| ④ 可体检 | 体检通过数/失败数/blocker 数与结论，失败项点名 |
| ⑤ 可导出 | 诊断包会收集的产物有几类在位（或最近一次导出的体积与文件名） |
| ⑥ 可注入 | 通道开关、dry-run 开关（关掉→不达标，因为会真发 QQ）、已消费行数、以及拦下过几次异步 agent 回合的回复 |
每一项都能点「去看 →」跳到对应卡片（事件流/决策链/回放结果/体检/日志/注入）；结论为 all-green / partial / unknown / broken 四种。
纯函数实现（control/lib/acceptance.mjs），所以每条分支都有断言覆盖；面板每 30 秒自动刷新，回放结束后立刻重算。
看得见 · 找得回（v0.5）
v0.5 做两件事：把已经封装好、却从没接上线的能力接通，再补上"群里的东西能找回来"。
合并转发展开（先修一个违反硬约束的洞）
以前别人把「聊天记录」合并转发给机器人时，parseMessage 里根本没有 forward 分支，这条消息在传输层就被静默丢掉——连 trace 都没有，直接违反 v0.4 的第一条硬约束。现在：
forwards 会被识别，经 get_forward_msg 展开成 [转发聊天记录] 昵称: 内容 交给模型（默认最多 50 条 / 4000 字，只展开一层，不递归）- 群里仍然要 @ 机器人才处理（空文本不再绕过 @ 门与
acceptPrivate 门——这两个门都补上了）
forwardExpandEnabled: false 可关闭；回放/注入模式（dry-run）不访问 QQ，注入时可用 forwardText 直接喂一份正文
接通的既有能力
| 能力 | 用法 |
|---|
| 群成员 | /成员 看名单（按身份/等级排序，标注头衔与禁言中）· /成员 @某人 / /成员 昵称 / /成员 QQ号 看详情（身份/等级/头衔/入群时间/最后发言/禁言状态）；agent 工具 qq_member_info |
| 群资料 | /群信息（群名/群号/人数与上限/群主/建群时间） |
| 好友列表 | /好友（隐私项，默认关闭 friendListEnabled，且仅私聊里的管理员可用） |
| 群历史 | agent 工具 qq_recent_history（拉本会话最近 N 条，群聊/私聊都支持） |
| 表情回应 | agent 工具 qq_react（给消息贴 👍 之类，而不是发一条消息；写操作，过闸门） |
| 退群 | /退群 确认（默认关闭 leaveGroupEnabled，必须显式二次确认，走闸门） |
群资产（只读为主）
| 命令 | 说明 |
|---|
/文件 | 列群文件与文件夹（文件名/大小/上传者/时间） |
/文件 <文件夹名> | 进文件夹列文件 |
/取 <文件名> | 下载群文件到 cwd/qq-files/ 并只发到发起人私聊（不往群里丢文件）；精确/前缀/模糊匹配，文件名消毒（去路径、去 Windows 非法字符、保留名加前缀） |
/相册 | 列群相册（NapCat get_qun_album_list） |
/ocr | 引用一张图片发 /ocr，用 NapCat 的 ocr_image 读出图里的文字（不消耗模型） |
历史检索与归档
- 每条白名单会话的真实消息按天归档到
cwd/qq-history/YYYY-MM-DD.jsonl；注入/回放的假事件不入档，/ 开头的命令也不入档（否则每次 /找 X 都会命中自己刚敲的查询词）
/找 关键词（空格分隔 = 同时包含，大小写不敏感）检索本会话最近 N 天；agent 工具 qq_search_history 同源同口径- 保留期默认 90 天，过期分片在宿主启动时移入
qq-trash/<日期>/ 而不是删除
- 控制台新增「群资产 · 历史检索」卡片：看归档体积与时间范围、直接检索（与群内
/找 复用同一套解析）
新增配置（括号内为默认值）：forwardExpandEnabled(true) forwardMaxNodes(50) forwardMaxChars(4000) memberQueryEnabled(true) memberListLimit(20) friendListEnabled(false) historyQueryEnabled(true) historyQueryLimit(20) reactToolEnabled(true) leaveGroupEnabled(false) ocrEnabled(true) ocrMaxImages(3) groupFileEnabled(true) groupFileDownloadEnabled(true) groupFileListLimit(20) groupFileMaxBytes(50 MiB) albumEnabled(true) historyArchiveEnabled(true) historyArchiveDir("") historyArchiveKeepDays(90) historySearchEnabled(true) historySearchDays(7) historySearchLimit(20)。
独立控制台（control/，v0.4.0）
插件自带一个独立的本地运维端，不依赖 DSH 桌面端：宿主挂掉时它照常可用，端口与进程一目了然。
# 启动（默认 http://127.0.0.1:8799，启动后打印带 token 的地址）
npm run control # 或 node control/bin/qq-control.mjs --open
# 也可以双击 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 |
| 安全 | 只绑 127.0.0.1；所有 API 需要 token；带 Origin 的跨站请求一律拒绝 |
以后若想做真正的托盘/桌面程序，直接包一层 Electron/Tauri 复用同一套 HTTP API 即可，逻辑无需重写。
隐私与脱敏
出问题排查往往要把日志发给别人，所以本插件对"数据会去哪"有明确约定：
| 项 | 约定 |
|---|
| 诊断包 | 「导出诊断包」默认勾选脱敏：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/ 单独拷出来裸跑仍然跑不起来（设计如此，不是缺依赖）。
更新日志
最近五个版本（始终滚动展示）：
- v0.5.7 — 文档整理：README 的「功能总览」按大版本归纳；更新日志恢复五条滚动显示（纯文档改动，无代码变更）
- v0.5.6 — 真机可用性修复 + 一轮完整审计：修掉三个"看起来能用、其实用不了"的坑（都是在你机器上排障时挖出来的）——① 控制台「启动 NapCat」原来跑的是
napcat.bat（三行、不带参数不提权，实测秒退 exit 0），改成提权调 launcher.bat（-Verb RunAs），并把目标从 napcat.bat 换成真正需要的脚本；② 「打开扫码页」在 6099 未监听时是死链，现在禁用并说明原因；③ 满屏「token 无效」：页面不带 ?token= 打开就等于空 token，现在直接弹中文横幅告诉你 token 存在 qq-control.json、且宿主 3080 的 token 每次重启都会变、两者不能混用。新增登录二维码面板（GET /api/qr 直接给出图片 + 「这张码是几秒前生成的」+ 过期提醒）与**「重启登录流程」按钮。随后做了一轮独立对抗性审查**（只读、禁止改文件/动 git/启停进程），把发现的问题全部修掉：【严重】重启流程原来按镜像名 taskkill /F /IM QQ.exe，会把你自己的 QQ 客户端一起杀掉（真机上就有一个非提权的个人 QQ 在跑），护栏还能被"6099 被别人占用"绕过 → 改为按加载器 PID 清理（taskkill /PID <pid> /T /F），命令里不再出现 QQ.exe//IM，拿不到 PID 直接拒绝；/api/port/free 加上受管端口白名单（原来能借它杀任意占用者）；stopNapcat 不再把「6099 在听」当成「这就是 NapCat」（复现过 nginx 占 6099）；启动命令改用 call "<path>"（路径含括号时 cmd 会剥引号导致静默不执行）并转义单引号；jobsView/groupsView 对元素级畸形快照不再 500；控制台侧不再整对象透传 webhook/自愈字段；自愈命令原文不再进 trace（只留 basename + 参数个数，trace 会进控制台页面与诊断包）；二维码只认 PNG 魔数；qrStatus 区分「读不到」与「不存在」；ops 规划器改用 Object.hasOwn（kind:'constructor' 不再命中原型拿到函数）。全量 55 套 / 3434 断言全绿
- v0.5.5 — 「控制台看得见 / Console visibility」：把控制台从「能启停、能看日志」变成看得懂。新增 性能面板（
GET /api/perf）：端到端延迟按「一条消息的 trace 链」算，给出整体与分会话的 P50/P95、阶段耗时画像（用 trace 里已有的 ms）、最慢几条与失败画像——debug 级「功能没开」不算事故，另列；定时任务面板（GET /api/jobs）：播报任务的下次时间/上次原因/成功失败次数与「一直在失败」标记、webhook 来源计数、自愈状态、注入队列；群配置页（GET /api/groups）：每个群的白名单状态、会话与最近回合、挂在该群的定时任务、16 项生效开关与实时计数（并说明开关真源在插件配置里）；注入场景库（17 个内置场景，GET /api/scenarios + POST /api/inject 的 scenario 字段）：群里 @我 / 普通聊天 / 撤回 / 戳一戳 / 入群 / 表情回应 / 入群与加好友申请 / 私聊文本与图片 / OCR / 转发卡片 / 管理员命令 / 原生打卡 / 批量踢 / 敏感词 / 超长消息，每个都声明需要什么参数、专门验哪条链路，缺参数点名缺什么；回放 diff（POST /api/replay-diff）：同一批消息跑两次回放（基线 vs 你写的配置覆盖），机械比出「决策变了 / 原因变了 / 回复文本变了」（带相似度，避免措辞微调被误判），只有一侧有结果时标 unknown。为此桥在运行快照里多写一个 jobs 块（只有描述性字段，）。新增 2 套测试（perf 61 / scenario 49），全量
更早的版本（v0.4 线及之前）见 CHANGELOG.md —— 完整历史、每个版本的缺陷清单与测试计数都在那里。
