dsh-napcat-bot

DeepSeek Harness (DSH) 插件：内置 NapCat（随 tgz 一起分发），启用即自动启动、监听 6099，并且通过 NapCat 官方 WebUI API 自动开启 OneBot 正向 HTTP + 正向 WS，WS 断线自动重连、进程异常自动拉起，让 AI 通过 QQ 私聊 / 群聊与真人对话。

开箱即用：安装并启用插件 → 重启 DSH → 打开侧边【设置 → 集成 → NapCat QQ 机器人】→ 在「NapCat WebUI」标签页扫码登录 QQ → 完事。接口地址、端口、OneBot access_token、WebUI 管理 Token 全部由插件自动生成与写入，不用手填、不用手抄、不用调试连接。 OneBot WS 固定 ws://127.0.0.1:3001；如果历史配置被写成了 6099，插件会自动纠正并落盘。

零外部 npm 依赖、可离线运行；不带 pnpm-lock.yaml，不会触发 pnpm 供应链校验。

安装

推荐：从 Releases 下载 dsh-napcat-bot-x.y.z.tgz，在 DSH 插件市场「导入本地包」里选择它。
源码：本仓库不含 vendor/（内置 NapCat 本体约 111MB 的第三方二进制，用 Release 分发更合适）。 clone 后可直接读改 lib/；要打包成可安装 tgz，请把 NapCat 解压到 vendor/napcat/ 再 tar -czf。

装好必须完全退出 DSH 再启动：服务端 lib/index.js 只在启动时加载一次。

2.8.0：联网搜索（手动 + 不懂自动查）

搜索后端直接用 DSH 自带的 ctx.web.search()（dsh-base 已挂 @deepseek-ai/dsh-web + dsh-web-search-deepseek，走 DeepSeek 原生搜索），所以不需要另填搜索接口和 Key；面板也支持填 SearXNG 等自定义接口。

两类触发

类型	条件	例子
手动（原有）	命中关键词：`帮我搜 / 搜一下 / 查一下 / 上网查 / 搜索`	搜一下今天金价
自动（新增）	本地规则先判：时效信息（新闻/价格/时刻/表/发售/比分）、现实实体（地点/参数/规格/教程/怎么设置）、带疑问但拿不准；拿不准时再让模型回一个词确认	今天金价多少？（没说搜，也去查）

不搜的情况：纯闲聊、情绪陪伴（想你了/抱抱/晚安）、玩梗（哈哈哈/笑死/这梗）、主观感受、人设对话（你叫什么）、以及去掉标点后不足 4 个字的语气词。

优先级

强制语音 > 手动搜索 > 自动搜索 > 识图解读 > 普通闲聊 所以「发个语音说你好」永远直接朗读、不会去搜；发图 + 「搜一下这是啥」会先让主模型用一句短话点出图里是什么，再拿这句话去搜。

兜底与容错

搜索失败 / 无结果 → 回 呜，鱼鱼的小鳍划不动搜索引擎，暂时查不到这个哦（手动、自动同一套）。
没有可用搜索后端时（宿主没挂 web 且没填自定义接口）→ 直接跳过搜索、照常回答，不会突然回「查不到」。
所有搜索都 try/catch，超时 20 秒、同类查询 10 分钟内走缓存，插件不崩不刷屏。

配置 / 规则 / 日志

面板「联网搜索」：总开关、不懂自动搜索（默认开）、自动搜索前模型二次确认、自定义接口地址、Key、每次取几条。
管理 → 规则：可对单个私聊/群单独「不联网」或「只手动搜」。
日志：[SEARCH] manual:<关键词> / auto:<原因> / ok provider=… n=… ms / fail … / skip <原因> / image-hint <提词>。

2.7.0：识图默认「读梗接话」，下指令才描述画面

以前默认提示词是「简短描述这张图片内容」——本质是在让模型看图汇报，发张表情包回来一段画面说明，很出戏。 2.7.0 把两种模式分开，优先级由你这句话决定：

你说的话	模式	模型被要求做什么
只发图 / 「哈哈哈哈」/「你看这个」	接梗模式（默认）	禁止描述物体、角色、文字、构图；只判断你发图的意图，读懂梗和情绪，直接接梗互动（例：`呜！你好坏，居然喊一车肥鱼来欺负我🥺`）
「描述一下这张图」「说说图片里面有什么」「图里长啥样」「详细讲讲画面」	描述模式	客观描述画面：元素、角色、文字（有就念出来）、构图

命中词表在 lib/vision.js 的 DESCRIBE_KEYWORDS，只收「明确针对图片内容」的说法，所以「你长啥样呀」不会误触发。
描述模式的提示词是硬编码的 DESCRIBE_PROMPT，不受面板提示词影响；面板里的「识图提示词（默认模式）」只管接梗模式。
兜底与容错：默认模式若模型仍在「图片里有…」式汇报，会自动带更硬指令重试一次；重试仍汇报就照发（不冷场、不死循环）。
历史默认提示词（「简短描述这张图片内容」等）在 __schemaVersion=10 迁移时自动换成新默认，用户自己改过的提示词保留。

其余链路一律没动：图片仍走 ctx.attachments 附件引用 + V4.1-Flash 原生视觉（同一条 user 消息里 text + image），识图开关、规则面板按会话覆盖、TTS 四种模式与强制语音、随缘主动发言、记忆、NapCat、风控全部原样。

新增日志：[VISION] mode: meme（默认接梗，不报画面） / describe:<命中词> / report-retry。

2.6.0：主动发言改成「随缘」（去掉倒计时与次数上限，只留冷却）

2.5.0 是「安静满 N 秒 → 说一条 → 你必须回话才会有下一条」，本质还是个定时器，而且被「一轮一条」卡住。 2.6.0 换成随机心情判定：

维度	现在的行为
触发方式	安静下来后，每隔 20~45 秒（带抖动）做一次心情判定，没有固定倒计时
次数	完全取消上限（没有每日/每轮封顶），冷却过完、心情到了就来找你
概率	每次判定先抽「心情档位」（12% 忽然很想你 p=0.45 / 43% 一般 p=0.18 / 45% 懒得开口 p=0.07），再掷一次是否命中 —— 所以节奏天然不均匀，可能一晚上两三次，也可能一整天不吭声
冷却	发出一条后强制冷却（默认 180 秒，面板滑块 60~1800），冷却期内绝不再发
对话中	正在生成回复、或刚说过话（冷却内）→ 一律不插话
告别	收到「晚安 / 先睡了 / 先不聊了 / 晚点再说 / 拜拜…」→ 暂停随机触发，直到你重新发消息才恢复
群聊	默认关闭，只在私聊；规则面板可给某个群单独打开
内容	主模型 + 面板人设 + 最近 12 条记忆生成，短句优先；方向含「想念 / 关心 / 接旧话题 / 小鱼碎碎念」，不是固定句子
语音	主动那句照样走「想发就发」随机判定
失败	模型空回复 / 报错 → 一个字都不发

面板

AI 配置 → 主动发言：主动找我（随缘）开关（默认开）、冷却间隔滑块（60~1800 秒，默认 180）、群聊也允许。状态行：主动发言：开启（随缘）· 冷却 180 秒 · 待机 1 个会话 · 已主动 3 · 没心情 12 · 收尾暂停 1。

日志

日志	内容
`主动发言待机`	冷却多少秒后开始随缘判定
`主动发言触发`	触发时间、空闲多久、`p=命中概率 roll=骰子`、进入多少秒冷却
`主动发言跳过 / 顺延 / 停表`	没心情、正在回复、收尾语句
`[PROACTIVE]`	主动发出的那句话原文

2.5.0：空闲主动发言（会接话，不会刷屏）

旧版是「每 N 分钟给最近活跃私聊群发一句问候」——那套已经删掉，生硬、会打断人、还容易刷屏。新版走空闲触发 + 上下文生成：

维度	行为
触发	最后一条消息之后静默满 N 秒才考虑开口（默认 120 秒，面板滑块 30~600）
说什么	把「刚刚聊了什么 + 对方最后一句」交给主模型，按面板人设写成一句短话；不是固定句子
频率	同一段空闲最多一条；你回话后重新计时，进入新一轮
边界	正在生成回复时到点 → 顺延，绝不插话；你说「晚安 / 先不聊了 / 拜拜」→ 直接停表
群聊	默认关闭，只在私聊生效；规则面板可对某个群单独打开
语音	主动那句照样进「想发就发」随机判定，有心情就出声
失败	模型没给出内容 / 报错 → 一个字都不发（宁可不吭声，也不发套话）

面板

AI 配置 → 主动发言：开关（默认开）、空闲等待时长（滑块 30~600 秒，默认 120）、群聊也允许。状态行会显示：主动发言：开启 · 空闲 120 秒触发 · 计时中 1 个会话（最近 98 秒后）· 已主动 3。

管理 → 规则 新增「主动发言（本会话覆盖）」：跟随全局 / 允许 / 本会话不主动 —— 可以给某个群开、给某个私聊关。

日志

前缀	内容
`[napcat] 主动发言计时中`	什么时候排的计时、多久后检查、最后一句是什么
`[napcat] 主动发言已发送`	空闲了多久才开口、之后重置计时
`[napcat] 主动发言跳过 / 顺延 / 停表`	为什么没说话（未开启、已说过一条、正在回复、收尾语句）
`[PROACTIVE]`	主动发出的那句话原文（在「消息收发记录」里能看到）

2.4.0：识图改用主模型原生视觉（不再配两套模型）

为什么能这么干：DSH 的模型目录里 deepseek-flash（= DeepSeek-V4.1-Flash）本身就声明了 inputModalities: ["text","image"]，视觉是主模型自带能力，没必要再挂一个独立的识图接口。

做法

旧（≤2.3.1）	新（2.4.0）
面板填「识图接口地址 + 识图 API Key + 识图模型名」	三个输入框全部删除，复用 DSH 里已填好的主模型与密钥
先调识图接口拿一句描述，再把描述拼进 prompt	图片和文本同一次请求进主模型：`[{type:'text'}, {type:'image', attachment}]`
两套模型、两套密钥、两份计费	一套配置，文字和看图同一个模型

技术要点：QQ 图片先下载成字节 → ctx.attachments.saveImage() 存进 DSH 附件库拿 ImageAttachmentRef → 以 {type:'image', attachment} 进 user 消息；宿主的 deepseek 适配器会自己 readImageRequest() 转成 base64 图片块发出去。直接塞 url 是不行的（适配器会判为不支持的块，整条请求失败），所以必须走附件引用。

保留的东西

识图总开关（默认开）、识图提示词（默认「简短描述这张图片内容」，可改、持久化）。
规则面板仍可按群/私聊单独关识图、单独调语音概率。
识图回复照常进 TTS 判定（全部 / 关键词 / 性格随机 / 强制语音）。
强制语音仍是绕过 LLM 的预处理拦截：发个语音说你好 直接抠出「你好」合成发送。
识图关闭 / 图片取不到 / 类型不支持 / 附件服务不可用 / 主模型报错 → 一律走人设兜底台词。

日志

前缀	内容
`[FORCE]`	命中哪个强制语音词、抠出的朗读文本（或「交给模型起稿」）
`[VISION]`	`原生多模态 · 图 N 张` 或 `fallback（原因）`；原因含 `download` / `unsupported-type` / `no-url` / `no-attachment-service`
`[MODEL]`	`multimodal · 带图 N 张请求主模型 · 返回 M 字`
`[TTS]`	`synth-ok`（引擎 + 音色 + 耗时）/ `fail` / `skip`

同类报错 30 秒只写一条，插件不崩、不刷屏。

验收

发「发个语音说你好」→ 直接发 QQ 语音，不经过模型，不会出现「鱼鱼不会按按钮」。
发「一车肥鱼」表情包 → 图片随对话进 V4.1-Flash，小鱼语气回复（日志有 [VISION] 原生多模态 · 图 1 张 + [MODEL] multimodal）。
不用填任何识图地址 / 识图 Key —— 用的就是 DSH 当前选择的主模型。

2.3.1：专项修复（强制语音只回文字 / 发图不识图）

真因（看日志就能确认）

强制语音只回文字：两个原因叠加 ——
- ttsUrl 是空的，plan() 判定「无引擎」→ 只发文字；
- 指令走的是「先让模型说话，再决定发不发语音」，模型先回了「鱼鱼这小短鳍按不来按钮啦」，推脱话术检查里没覆盖「按不来」，于是这条推脱被当正文发出去了。
发图不识图：visionEndpoint 是空的 → 直接 no-endpoint 兜底。

修法

① 强制语音改成「消息底层预处理拦截」，绕过 LLM 消息进来先解析指令，命中 发语音 / 发句语音 / 语音说xxx / 说出来 … 就把要念的正文抠出来，直接合成语音发送，完全不调模型（从根上不可能再推脱）。

「发个语音说你好」→ 朗读文本 = 你好 → 直接发语音；
「语音说你今天怎么样」→ 朗读文本 = 你今天怎么样；
只说「发语音」没给内容 → 才让模型起稿，但仍强制语音，并注入「禁止说不会发语音/按不了按钮」+ 回复里出现推脱就重试/清洗；
带图 + 强制语音 → 不走抠文本，走识图 + 人设起稿 + 强制语音（否则会把「这是啥」念出来）。
优先级最高：ttsMode=off、随机 0% 也照发。

② 内置离线语音引擎（真开箱即用） 没填 TTS 接口地址时，自动用 Windows 自带语音（SAPI）合成 WAV → 交 NapCat 发语音。零依赖、无需联网、无需 Key；本机实测 3.16 秒语音合成耗时 ~2.4 秒。填了接口则以接口为准。可在面板关闭（「接口没填时用系统内置语音」）或指定音色（Huihui / Xiaoxiao …）。

③ 识图接口自动预置 默认 visionEndpoint = zhipu（智谱，glm-4v-flash 有免费额度），模型名自动补，提示词默认「简短描述图片内容，不要冗长」，开关默认开 —— 只需要补一个 API Key 就能识图（面板会显示「缺 API Key → 补上即可识图」）。地址/提示词都能在界面改，保存即持久化。

④ 日志（面板「消息收发记录」直接看）

前缀	内容
`[FORCE]`	是否命中强制语音、命中词、抠出的朗读文本
`[VISION]`	是否触发识图、`ok/fallback`、原因（`no-endpoint` / `auth` / `http-500` / `no-url` …）、识别到的内容
`[TTS]`	`synth-ok`（引擎 http/local + 音色 + 耗时）/ `fail` / `skip`（含 `no-engine` 原因）

同类报错 30 秒内只写一条，不刷屏；所有异常都降级为文字，插件不崩。

升级到 2.3.1 后必须完全退出 DSH 再启动。

2.3.0：强制语音指令 + 识图默认开箱即用

一、TTS 强制语音（内置关键词库，不用配）

只要这句话里命中下列任一说法，优先级最高：跳过模式（哪怕模式是「关闭」）、跳过随机概率，直接合成语音发出去。

发语音 发句语音 发条语音 发个语音 发一段语音 来句语音 来条语音 来段语音 语音说 用语音 语音回复 语音回答 语音念 语音读 说出来 念出来 读出来 念一下 读一下 说给我听 念给我听 唱一个

例：发「发个语音说你好」→ 直接发语音。

防推脱三层保险：

生成前给模型注入定向提示：你能直接发语音，禁止回答「不会发语音 / 按不了按钮 / 没法发」；
回复里仍出现推脱话术 → 带更硬指令自动重试一次；
还在推脱 → 清洗掉推脱句，语音照发（messages.log 记一行 TTS retry）。

二、识图默认配置

识图开关默认开启；识图提示词默认「简短描述图片内容，不要冗长」（老配置里的旧默认值会自动迁移）。
接口地址支持预设短名，只填一个词就行，模型名会自动补：

填这个	实际地址	自动模型
`zhipu`	open.bigmodel.cn/api/paas/v4/chat/completions	`glm-4v-flash`（有免费额度）
`dashscope`	dashscope.aliyuncs.com/compatible-mode/v1/chat/completions	`qwen-vl-max`
`openai`	api.openai.com/v1/chat/completions	`gpt-4o-mini`
`siliconflow`	api.siliconflow.cn/v1/chat/completions	`Qwen/Qwen2.5-VL-72B-Instruct`
`moonshot`	api.moonshot.cn/v1/chat/completions	`moonshot-v1-8k-vision-preview`
`openrouter`	openrouter.ai/api/v1/chat/completions	`google/gemini-2.0-flash-exp:free`
`ollama`	127.0.0.1:11434/v1/chat/completions	`llava`

也可以填任意完整地址（.../chat/completions）或只填 base 地址（https://api.openai.com/v1，会自动补 /chat/completions），自定义完整地址不会被乱拼。

API Key 只能你自己填（这个没法内置）。

三、联动

识图产出的回复若没有命中强制语音，正常走「心情随机语音」掷骰子。
强制语音与随机模式互不干扰：随机 0% 时普通消息不发语音，但「发语音」指令照样发。
规则面板可对单个群/私聊单独关闭识图、单独设语音概率（规则 > 全局）。
面板「人设已生效」下方能看到：语音已发/跳过/强制/失败、识图成功/失败 + 上一张图内容。

四、容错

TTS / 识图超时、401、5xx、返回空 → 一律降级为文字（或人设兜底台词），只写日志，插件不崩；同类报错 30 秒内只记一条，不刷屏。所有配置保存后立即生效，重启自动加载。

升级到 2.3.0 后必须完全退出 DSH 再启动。

2.2.0：识图（看图 → 用人设说话）

面板 AI 配置 → 识图（多模态）：

配置项	说明
识图功能总开关	默认开启。关闭后收到图片只回一句人设兜底台词
多模态模型接口地址	OpenAI 兼容的 `/chat/completions`，如 `https://api.openai.com/v1/chat/completions`
识图 API Key	以 `Bearer` 发送；留空则不带鉴权头
多模态模型名	如 `gpt-4o-mini` / `qwen-vl-max` / `glm-4v-flash`（必须支持图片输入）
识图提示词	默认「描述这张图片，简短一点」

链路：QQ 图片 → 从 NapCat 消息里拿直链（只有文件名时用 OneBot get_image 换）→ 多模态接口得到一句描述 → 描述作为上下文交给主模型 → 按面板人设的语气重新组织语言（不是冷冰冰的客观描述）。

例：识图得到「一整车肥鱼表情包」→ 大肥鱼会说「哇！一整车都是肥鱼小伙伴，浩浩荡荡的，也太热闹啦🥳」。

兜底：识图关闭 / 没填接口 / 超时 / 密钥错 / 请求报错 / 返回空 → 直接回人设台词：「呜…有点糊糊的，鱼鱼眼睛小，得凑很近才看得清一点点。要不你讲讲图里是啥？我慢慢听～」（这条台词整句一次发出，不拆段、不刷屏；同类报错 30 秒内只写一条日志。）
和随机语音联动：识图回复与兜底台词都走同一条投递管道，所以照样按 TTS 模式掷骰子，可能变成语音。
按会话覆盖：管理 → 规则可对某个私聊/群聊单独「关闭识图」。
纯图片消息也能收到：以前没有文字的消息会被当作空消息丢掉，现在只要带图片就放行。
同一张图 10 分钟内复用识别结果（有缓存，不重复烧 token）。
面板「人设已生效」下方会显示识图状态、成功/失败次数和上一张图识别到的内容。

升级到 2.2.0 后必须完全退出 DSH 再启动。

2.1.0：TTS 语音「性格随机模式（想发就发）」

面板 AI 配置 → 语音（TTS） 区域，模式四选一：

模式	行为
`关闭`	只发文字
`全部消息转语音`	每条回复都发语音（回复超过「单条语音最长字数」时自动补发文字，信息不丢）
`关键词触发`	用户或回复里出现触发词（默认「语音 / 发语音 / 说给我听 / 念一下」）才发语音
`性格随机模式（想发就发）`	每轮先掷骰子，命中发语音，没命中只发文字

随机模式细节

⚠️ 语音要真的出声，必须填「TTS 接口地址」。接口只需要 POST {text, voice} 返回音频二进制或 {"audio_base64":"..."}；OpenAI 兼容的 /v1/audio/speech 也能直接用（此时再填「TTS 模型名」）。没填接口时面板会显示「未填接口地址」，行为等同只发文字。

概率滑动条 0~100%，默认 40%；0 = 永不发，100 = 次次发。是每轮独立掷骰，不是固定间隔，所以出现「有时出声、有时懒得开口」的随性节奏。
人设智能权重（默认开）：短句（≤12 字）权重 ×1.3、活泼语气再往上抬；长段解释（>120 字）×0.72、emotion 低落词（难过/累/emo/哭…）再压；人设里带「懒 / 瘫 / 佛系 / 慢悠悠」整体 ×0.9。边界仍然严格：0 还是 0，100 还是 100。
随机音色（默认开）：每次从音色池（默认 软萌少女,甜妹,奶音,软糯小助手，可改）里随机挑，每轮都可能不一样；关掉则固定用「固定音色」。
兜底：TTS 接口超时/报错/返回空/发送失败 → 自动降级只发文字，写 messages.log，插件不崩；如果是「只发语音」模式且发送失败，会补发文字保证用户收到内容。
缓存：同文本+同音色命中内存缓存（TTL 10 分钟、上限 60 条，自动淘汰）。音频全程 base64 直发 NapCat，不落盘，所以没有残留文件需要清理。
按会话覆盖：管理 → 规则里可以对某个群/某个私聊单独设 语音模式 / 概率 / 随机音色（留空 = 跟随全局）。
面板「人设已生效」下方会显示：语音模式、概率、已发 / 跳过 / 失败次数、上一句用的音色 —— 用来确认「确实是想发就发」。

升级到 2.1.0 后必须完全退出 DSH 再启动。旧配置里 ttsEnabled=true 会自动迁移成 ttsMode='all'，行为不变。

2.0.1（紧急修复）：人格不生效 / 固定输出套话

现象：面板里填了「大肥鱼」，问“你叫什么名字”却固定回一句 我觉得这个得看具体情况～你先说说细节，我再给你个靠谱的答复。

两个真实原因（都已修）：

代码里有一段硬编码兜底话术（离线降级时输出）。模型调用一失败就会吐出这句，看起来就像“人格完全没生效”。现在这句连同整套硬编码兜底已彻底删除：模型不可用时就用人设推导一句身份回答（如「我是大肥鱼呀～…」），推导不出来就不发消息，绝不敷衍一句模板话。
system 提示词用错了传参方式。以前把人格塞在 llm.stream({ system }) 这个字段里，而 DSH 的模型协议要求 system 作为 role:'system' 的消息进入 messages；字段被忽略，等于人格根本没送到模型。现在 system 以标准消息发送，面板文本一字不改地成为唯一 system。
顺带修掉「模型返回空内容」→ 之前 maxTokens=800 时，模型的思维链会把预算吃光，可见文本为空，于是又触发第 1 条的兜底话术。现在 maxTokens=2000，并且空内容会自动以 reasoningEffort:'off' 重试一次。

现在的规则：

面板填了人格 → 它就是唯一的 system（不加前缀、不追加任何“最高优先级”之类的说明文字，也不放风格模板）；
面板留空 → 完全不发 system，不自动补任何文字；
问身份（你叫什么 / 你是谁 / 你会做什么）→ 额外给一条定向指令：直接按人设第一人称回答，禁止“看具体情况、你先说说细节”式回避；万一模型还是回避，会自动带硬指令重试一次；
上下文（历史 / 摘要 / 知识库）和排版要求全部挪到 user 消息里，不再污染 system。

排障：面板「人设已生效」下方会显示回复引擎、上次生成成功/失败以及具体报错；明细写入 ~/.dsh/napcat-bot/engine.log，也可通过 GET /napcat-bot/api/napcat/log?source=engine 查看。

升级到 2.0.1 后必须完全退出 DSH 再启动（服务端代码只在启动时加载）。

三步验收

导入 dsh-napcat-bot-2.8.0.tgz → 完全退出并重启 DSH（服务端代码只在启动时加载）→ 启用插件 → 日志出现「内置 NapCat 已就绪，WebUI 监听 127.0.0.1:6099」。
设置页左侧【集成】里点「NapCat QQ 机器人」→ 第二个标签页「NapCat WebUI」已自动带上管理 Token，直接扫码登录。
三个状态灯全绿（NapCat 进程 ✓ / WS 已连接 ✓ / 可以收发消息 ✓）后，私聊发消息、群里 @ 机器人即可收到 AI 回复。

端口分工（1.5.0 起强制纠正，不再可能连错）

用途	地址	说明
NapCat WebUI（管理面）	`http://127.0.0.1:6099/webui`	只用来扫码登录 QQ、看 NapCat 自己的面板。它不是 OneBot 端口
OneBot 正向 WS（收消息）	`ws://127.0.0.1:3001`	插件主通道。连上后 NapCat 的「WS 客户端数」显示 1
OneBot HTTP（发消息）	`http://127.0.0.1:3000`	能开就用；没开也不影响，插件会自动改走 WS 通道发送

历史配置里如果 napcatWsUrl 被写成了 6099（把管理面当成了 OneBot 端口），插件启动时会 自动改回 3001 并落盘，日志里会有一行 已修正 OneBot 端点：WS ws://127.0.0.1:6099 → ws://127.0.0.1:3001。面板顶部也会把这三个地址并排列出来，排障时一眼能确认连的是哪个口。

⚠️ 关键：QQ 登录 ≠ WS 自动连上

这是本插件踩过的最深的坑，1.4.0 修了配置生效问题，1.5.0 又补了两个：

坑 0：WS 连到 6099 上（1.5.0 修复）

6099 是 NapCat 的管理面（HTTP 页面 + WebUI API），不在上面跑 OneBot 协议。连它只会被拒或无响应，表现就是「插件 WS 状态未知/断开、NapCat 里 WS 客户端数一直是 0」。现在 normalizeWsUrl() 会把「空值 / 等于 6099 / 等于 HTTP 端口」的地址一律纠正成 ws://127.0.0.1:3001，配置层、WS 客户端层、面板展示层三处都过一遍，不可能再漏。

坑 1：改配置文件不生效（1.4.0 修复）

直接改 config/onebot11_<QQ>.json 并不能保证生效。 实测 NapCat 4.18.41 经常不热加载该文件，甚至在自身保存配置时把 websocketServers 条目丢掉——结果就是「QQ 明明登录了，3001 却没在监听」。

所以插件改用 NapCat 自己的 WebUI HTTP API 来配置 OneBot 网络：

POST /api/auth/login              { hash = sha256(webuiToken + ".napcat") }  → data.Credential
POST /api/OB11Config/SetConfig    { config: "<json 文本>" }   // NapCat 内部 save + reloadNetwork

SetConfig 会让 NapCat 真正重启网络适配器，3001 立刻开始监听，不需要重启 NapCat、不需要重新扫码。插件在「WebUI 就绪」「QQ 登录成功」「发现 3001 未监听」三个时机自动调用它，失败则每 6 秒重试。

坑 2：OneBot HTTP 必须打到具名路径（1.4.0 修复）

NapCat 的 HTTP 适配器不按 body 里的 action 字段分发。往根路径 POST http://127.0.0.1:3000 只会得到一个桩响应：

{"status":"ok","retcode":0,"data":{},"message":"NapCat4 Is Running"}

于是 get_login_info 永远拿不到 QQ 号（面板显示「未登录」），send_private_msg / send_group_msg 变成空操作（消息永远发不出去却也不报错）。

正确写法是 POST 到 /<action>。1.5.0 更进一步：HTTP 不通时 action 会自动走正向 WS（同一连接支持 echo 应答），所以「NapCat 只开了 WS、没开 HTTP」也能正常收发。

两处 Token（插件已全自动，这里只是说明区别）

Token	用途	谁生成
WebUI 管理 Token	登录 `http://127.0.0.1:6099/webui` 这个管理页面	插件启动前写入 `config/webui.json`，随后从 NapCat 启动日志（`[WebUi] WebUi Token: xxx`）自动读取校验；内嵌页面自动附加，无需手输
OneBot access_token	插件 ↔ NapCat 通信用（HTTP Bearer / WS query），真正收发 QQ 消息	插件首次启用时随机生成，自动写进插件配置与 NapCat 的 `onebot11_<QQ>.json`

两者完全独立：WebUI Token 只影响能否打开管理页面；OneBot token 只影响插件能否调 NapCat 的 API。

自动写入的 NapCat 配置

插件启动内置 NapCat 前会主动写配置文件（作为兜底），并在运行期用官方 API 校正：

config/webui.json：host=127.0.0.1、port=6099、带 token、不禁用 WebUI。
config/onebot11_<QQ>.json（对历史登录过的 QQ 号全部预置）：
- 正向 HTTP（默认 3000）—— 插件用它发消息、查登录态；
- 正向 WS（默认 3001）—— 插件用它收消息；
- 两者使用同一个自动生成的 token（与插件配置一致，不一致会直接 403 → 全链路静默）；
- reportSelfMessage=false，避免机器人收到自己发的消息形成自问自答。

状态灯与自动重连（1.5.0）

面板顶部固定三个灯，语义与 NapCat 侧对得上：

灯	含义
🟢 NapCat 进程已启动	内置 NapCat 在跑（按 6099 端口实际监听判定，不是看状态文件）
🟡 WS 正在尝试连接	插件正在重连 `ws://127.0.0.1:3001`；旁边显示第几次重试、下次重试倒计时
🔴 WS 连接失败	重连次数用尽（`wsMaxRetries>0` 时）或环境不支持 WebSocket
🟢✓ 可以收发消息	WS 已连接且 3001 在监听且 QQ 已登录

灯下面一行会直接显示 WS 目标：ws://127.0.0.1:3001（端口 3001），并标注 客户端数 1，可以和 NapCat WebUI 里的「WS 客户端数」对照。

重连策略（面板可调）：

首次重连间隔 wsRetryInterval（默认 2000ms），之后指数退避 2→4→8→15s（上限 wsRetryMaxInterval）。
wsMaxRetries 默认 0 = 一直重试；填 N 则连续失败 N 次后停止（按钮可手动重连）。
连接超时 8s 未建立即判失败换下一次（不依赖 onclose——实测 Node 的 WebSocket 在连接被拒时可能只触发 error）。
心跳看门狗：连上后 wsHeartbeatTimeout（默认 100s）内收不到任何数据（含心跳）→ 判定半死连接，主动重连。
NapCat 重启 / QQ 掉线重连后，插件检测到 3001 恢复监听会立即重连，不用手动操作。
进程守护：NapCat 进程异常退出（6099 不再监听）→ 状态如实回落成「未运行」，并在 12s 后自动重新拉起； 10 分钟内最多自动拉起 3 次，超过则停在「反复退出」提示，避免把 QQ 拉成重启风暴。

消息应答逻辑（默认即正确）

私聊自动回复；群聊默认仅在被 @ 时回复（面板可关）。
只处理真人聊天消息：post_type=message 且 message_type=private|group；自动丢弃点赞 / 群成员变动等 notice、心跳 meta_event、加好友请求、机器人自己发的消息（含 sub_type=self）、以及纯图片语音等无文字消息。
回复时把人设 Prompt + 最近 10 条对话记忆一起喂给模型，输出限制为口语化短句（不用 Markdown、不自称 AI）。
回复引擎默认 dsh：走 ctx.get('llm') + ctx.get('agentDefaultModel').currentSelection()，用你在 DSH 里选中的模型与凭据，不需要另填 API Key。
发送失败会被捕获并显示在面板（发送失败：...），同时计入「失败」计数。
面板顶部有连接指示灯：未连接 / 连接中 / 已就绪，并显示 QQ 号、收发计数、最近收到时间、错误信息。

面板结构（固定两个标签页）

AI 配置：AI 配置 内含内置 NapCat 状态卡与启停、连接（全部自动维护，一般不用改）、人格与回复、行为与风控（记忆开关、群内仅 @ 回复、主动发言、冷却与每分钟上限）。
NapCat WebUI：内嵌 WebUI（自动免 Token 登录，这里扫码登录 QQ）、两类 Token 卡片、NapCat 控制台日志预览（实时刷新 / 暂停 / 只看 Token 行 / 复制日志）。

插件详情页里的配置表单同样保留，两个入口共存。

进程管理

启动前先检测：自己的 pid 文件 + 日志里的 Main Process ID + 6099 端口探测 + 短期互斥锁，绝不重复多开 NapCat / QQ。
关闭插件或退出 DSH 时自动停掉由本插件拉起的 NapCat 进程树（面板可关 stopNapCatOnDisable）。
面板提供「启动内置 NapCat / 重新启动 / 停止」。

关于 QQ（唯一的外部前提）

NapCat 的工作原理是注入已安装的官方 QQ NT 客户端（NapCatWinBootMain.exe + NapCatWinBootHook.dll）。系统上有官方 QQ 即可，不需要再单独安装或启动 NapCat。插件按下列顺序探测 QQ：

面板里填写的 qqPath；
%ProgramFiles% / %ProgramFiles(x86)% / %LOCALAPPDATA%\Programs 下的 Tencent\QQNT\QQ.exe；
C: – F: 盘下的 Program Files\Tencent\QQNT\QQ.exe、Tencent\QQNT\QQ.exe。

探测不到时面板会明确提示「未检测到 QQ NT」并给出填写入口。

HTTP 面板接口

注意：宿主 webServer 的 prefix 匹配是 pathname === prefix || pathname.startsWith(prefix + '/')，因此 prefix 路由的 path 结尾不能带斜杠（早期版本 /napcat-bot/api/napcat/ 就是因为这个永远 404）。

方法	路径	说明
GET	`/napcat-bot/api/status`	连接三态、OneBot 登录态、内置进程态、WebUI Token、运行计数、当前回复引擎
GET/POST	`/napcat-bot/api/config`	读取 / 保存配置（保存即热重载）
GET	`/napcat-bot/api/webui`	WebUI 地址 + 自动读取的管理 Token + OneBot token
POST	`/napcat-bot/api/webui/token`	重新生成 / 指定 WebUI 管理 Token（并重启生效）
POST	`/napcat-bot/api/napcat/{start\|stop\|restart}`	内置 NapCat 启停
POST	`/napcat-bot/api/napcat/reconnect`	只重连插件侧 WS（不动 NapCat、不踢 QQ）
POST	`/napcat-bot/api/napcat/apply-onebot`	立即通过 WebUI API 重新应用 OneBot 配置
GET	`/napcat-bot/api/napcat/log?tail=N`	控制台日志尾部（含 Token 行）
POST	`/napcat-bot/api/client-report`	客户端 UI 注册自检回执（排障用）

排障

现象	处理
面板还是旧样子（没有三个灯 / 没有端点行）	服务端代码只在 DSH 启动时加载。装完新版必须完全退出 DSH 再启动，否则跑的还是内存里的旧版本
侧边【集成】没有入口	看 `~/.dsh/napcat-bot/client-report.json`，其中 `registered` 应含 `settings.section`（1.5.0 已验证会出现）
WS 状态未知 / 断开，NapCat 里客户端数 0	1.5.0 已自动纠正到 3001；确认面板「WS 目标」这一行显示的是 `ws://127.0.0.1:3001`
状态灯一直「WS 正在尝试连接」	点「重新应用 OneBot 配置」；若仍不行看日志里有没有 `WebSocket服务: ... 已启动`
显示「未登录」但 QQ 确实在线	1.4.0 已修：OneBot HTTP 必须 POST 到 `/<action>`，打到根路径只会拿到桩响应
日志面板 404	1.3.0 起已修（路由 path 去掉尾斜杠），确认版本 ≥ 1.5.0
收到消息但发不出去	1.5.0 会自动改走 WS 通道发送，不再依赖 3000；若仍失败看面板 `发送失败：...` 的具体报错
NapCat 进程显示「未运行」	1.5.0 按端口真实存活判定，会 12s 后自动拉起（10 分钟内最多 3 次）；也可点「启动内置 NapCat」
回复走离线兜底	面板连接卡显示「回复引擎：离线兜底应答」→ DSH 未配置模型，或 `llm` 服务不可用
内嵌 WebUI 空白	个别版本禁止 iframe 嵌套，点「在浏览器打开」，链接已带 Token

v2.0.0：AstrBot 风格消息管道

三个标签页

标签	内容
AI 配置	三个状态灯、端点明细、人设生效提示、消息收发记录、全部开关与字段
NapCat WebUI	内嵌管理页（自动带 token），扫码登录 QQ
管理	人格 / 会话 / 规则 / 知识库 / 任务五个子页

消息处理顺序

组件解析（文本/图片/@/语音/文件/卡片）→ 过滤（自身、系统、进退群、红包闪照、空消息、纯表情）
黑白名单（用户 + 群）→ message_id 去重（跨实例共享，2 分钟窗口；另加 1.5s 内容指纹兜底）
私聊直达；群聊「@ 唤醒 → 免@ 超时（默认 120s，滑动续期）→ 超时静默」
会话等待器（多轮流程接管，例如 /idiom 成语接龙，接管期间不过模型）
指令层（见下）→ 上下文（历史 + 摘要压缩 + 知识库检索）→ 模型流式 → 分段发送

会话隔离

私聊：private:${uid}，强制独立，不可关闭。
群聊：开关 groupUniqueSession（面板「会话策略」里）
- 开：group:${gid}:${uid}，每人独立上下文
- 关：group:${gid}，全群共用一套

指令

基础：/help /reset /new /stop /stats /sid /history /ls /rename /del /switch /idiom 管理员：/op /deop /ban /unban /model /provider /groupnew

人格优先级

规则里指定的人格（按会话） > 全局人格（人格库） > 面板单人格字段。全部走 system prompt 最前面，插件内不再内置任何固定人设（旧版的“小深”会在升级时自动清除）。人格文本支持变量：{{bot_name}} {{group_id}} {{user_id}} {{user_name}} {{time}}。

知识库

本地 BM25 + 字符 bigram 哈希向量余弦的混合检索（0.65 / 0.35 加权），中文优化；按规则把知识库绑定到会话，命中后自动加进 system 并在回复末尾标注来源。支持粘贴文本片段（PDF/DOCX 请先转成文本）。

定时任务

target 形如 group:123456 / private:10001，prompt 以 gen: 开头表示先用模型生成文案再发。任务持久化在 state.json，支持立即执行/删除，重启后继续按间隔触发。

目录结构

lib/index.js           服务端主入口（配置 schema、路由、生命周期、单例守卫）
lib/client.js          面板 UI（AI 配置 / NapCat WebUI / 管理 三个标签）
lib/pipeline.js        消息流水线：解析 → 过滤 → 去重 → 指令 → 识图 → 搜索 → 推理 → 分段/语音
lib/responder.js       DSH 模型调用（system 只来自面板人格，三级重试，绝不输出套话）
lib/napcat.js          OneBot 连接：HTTP 动作 + 正向 WS + 重连/心跳
lib/napcat-embedded.js 内置 NapCat 进程管理（启动/停止/探活/自动拉起）
lib/vision.js          原生多模态：图片 → 附件引用；两种识图模式
lib/search.js          联网搜索：手动指令 + 自动查证 + 断路器
lib/tts.js             TTS 四种模式 + 强制语音 + 音色池 + 缓存
lib/tts-local.js       内置离线语音（Windows SAPI）
lib/proactive.js       主动发言调度（随缘随机、仅冷却）
lib/state.js           人格/规则/定时任务持久化
lib/sessions.js        会话与上下文
lib/kb.js              知识库混合检索
lib/risk.js            限流 / 黑白名单
tools/                 开发期自测脚本（Node 原生跑，无第三方依赖）

License

MIT

dsh-napcat-bot

开箱即用：安装并启用插件 → 重启 DSH → 打开侧边【设置 → 集成 → NapCat QQ 机器人】→ 在「NapCat WebUI」标签页扫码登录 QQ → 完事。接口地址、端口、OneBot access_token、WebUI 管理 Token 全部由插件自动生成与写入，不用手填、不用手抄、不用调试连接。 OneBot WS 固定 ws://127.0.0.1:3001；如果历史配置被写成了 6099，插件会自动纠正并落盘。

零外部 npm 依赖、可离线运行；不带 pnpm-lock.yaml，不会触发 pnpm 供应链校验。

安装

推荐：从 Releases 下载 dsh-napcat-bot-x.y.z.tgz，在 DSH 插件市场「导入本地包」里选择它。
源码：本仓库不含 vendor/（内置 NapCat 本体约 111MB 的第三方二进制，用 Release 分发更合适）。 clone 后可直接读改 lib/；要打包成可安装 tgz，请把 NapCat 解压到 vendor/napcat/ 再 tar -czf。

装好必须完全退出 DSH 再启动：服务端 lib/index.js 只在启动时加载一次。

2.8.0：联网搜索（手动 + 不懂自动查）

两类触发

类型	条件	例子
手动（原有）	命中关键词：`帮我搜 / 搜一下 / 查一下 / 上网查 / 搜索`	搜一下今天金价
自动（新增）	本地规则先判：时效信息（新闻/价格/时刻/表/发售/比分）、现实实体（地点/参数/规格/教程/怎么设置）、带疑问但拿不准；拿不准时再让模型回一个词确认	今天金价多少？（没说搜，也去查）

优先级

兜底与容错

搜索失败 / 无结果 → 回 呜，鱼鱼的小鳍划不动搜索引擎，暂时查不到这个哦（手动、自动同一套）。
没有可用搜索后端时（宿主没挂 web 且没填自定义接口）→ 直接跳过搜索、照常回答，不会突然回「查不到」。
所有搜索都 try/catch，超时 20 秒、同类查询 10 分钟内走缓存，插件不崩不刷屏。

配置 / 规则 / 日志

面板「联网搜索」：总开关、不懂自动搜索（默认开）、自动搜索前模型二次确认、自定义接口地址、Key、每次取几条。
管理 → 规则：可对单个私聊/群单独「不联网」或「只手动搜」。
日志：[SEARCH] manual:<关键词> / auto:<原因> / ok provider=… n=… ms / fail … / skip <原因> / image-hint <提词>。

2.7.0：识图默认「读梗接话」，下指令才描述画面

你说的话	模式	模型被要求做什么
只发图 / 「哈哈哈哈」/「你看这个」	接梗模式（默认）	禁止描述物体、角色、文字、构图；只判断你发图的意图，读懂梗和情绪，直接接梗互动（例：`呜！你好坏，居然喊一车肥鱼来欺负我🥺`）
「描述一下这张图」「说说图片里面有什么」「图里长啥样」「详细讲讲画面」	描述模式	客观描述画面：元素、角色、文字（有就念出来）、构图

命中词表在 lib/vision.js 的 DESCRIBE_KEYWORDS，只收「明确针对图片内容」的说法，所以「你长啥样呀」不会误触发。
描述模式的提示词是硬编码的 DESCRIBE_PROMPT，不受面板提示词影响；面板里的「识图提示词（默认模式）」只管接梗模式。
兜底与容错：默认模式若模型仍在「图片里有…」式汇报，会自动带更硬指令重试一次；重试仍汇报就照发（不冷场、不死循环）。
历史默认提示词（「简短描述这张图片内容」等）在 __schemaVersion=10 迁移时自动换成新默认，用户自己改过的提示词保留。

新增日志：[VISION] mode: meme（默认接梗，不报画面） / describe:<命中词> / report-retry。

2.6.0：主动发言改成「随缘」（去掉倒计时与次数上限，只留冷却）

2.5.0 是「安静满 N 秒 → 说一条 → 你必须回话才会有下一条」，本质还是个定时器，而且被「一轮一条」卡住。 2.6.0 换成随机心情判定：

维度	现在的行为
触发方式	安静下来后，每隔 20~45 秒（带抖动）做一次心情判定，没有固定倒计时
次数	完全取消上限（没有每日/每轮封顶），冷却过完、心情到了就来找你
概率	每次判定先抽「心情档位」（12% 忽然很想你 p=0.45 / 43% 一般 p=0.18 / 45% 懒得开口 p=0.07），再掷一次是否命中 —— 所以节奏天然不均匀，可能一晚上两三次，也可能一整天不吭声
冷却	发出一条后强制冷却（默认 180 秒，面板滑块 60~1800），冷却期内绝不再发
对话中	正在生成回复、或刚说过话（冷却内）→ 一律不插话
告别	收到「晚安 / 先睡了 / 先不聊了 / 晚点再说 / 拜拜…」→ 暂停随机触发，直到你重新发消息才恢复
群聊	默认关闭，只在私聊；规则面板可给某个群单独打开
内容	主模型 + 面板人设 + 最近 12 条记忆生成，短句优先；方向含「想念 / 关心 / 接旧话题 / 小鱼碎碎念」，不是固定句子
语音	主动那句照样走「想发就发」随机判定
失败	模型空回复 / 报错 → 一个字都不发

面板

日志

日志	内容
`主动发言待机`	冷却多少秒后开始随缘判定
`主动发言触发`	触发时间、空闲多久、`p=命中概率 roll=骰子`、进入多少秒冷却
`主动发言跳过 / 顺延 / 停表`	没心情、正在回复、收尾语句
`[PROACTIVE]`	主动发出的那句话原文

2.5.0：空闲主动发言（会接话，不会刷屏）

旧版是「每 N 分钟给最近活跃私聊群发一句问候」——那套已经删掉，生硬、会打断人、还容易刷屏。新版走空闲触发 + 上下文生成：

维度	行为
触发	最后一条消息之后静默满 N 秒才考虑开口（默认 120 秒，面板滑块 30~600）
说什么	把「刚刚聊了什么 + 对方最后一句」交给主模型，按面板人设写成一句短话；不是固定句子
频率	同一段空闲最多一条；你回话后重新计时，进入新一轮
边界	正在生成回复时到点 → 顺延，绝不插话；你说「晚安 / 先不聊了 / 拜拜」→ 直接停表
群聊	默认关闭，只在私聊生效；规则面板可对某个群单独打开
语音	主动那句照样进「想发就发」随机判定，有心情就出声
失败	模型没给出内容 / 报错 → 一个字都不发（宁可不吭声，也不发套话）

面板

管理 → 规则 新增「主动发言（本会话覆盖）」：跟随全局 / 允许 / 本会话不主动 —— 可以给某个群开、给某个私聊关。

日志

前缀	内容
`[napcat] 主动发言计时中`	什么时候排的计时、多久后检查、最后一句是什么
`[napcat] 主动发言已发送`	空闲了多久才开口、之后重置计时
`[napcat] 主动发言跳过 / 顺延 / 停表`	为什么没说话（未开启、已说过一条、正在回复、收尾语句）
`[PROACTIVE]`	主动发出的那句话原文（在「消息收发记录」里能看到）

2.4.0：识图改用主模型原生视觉（不再配两套模型）

做法

旧（≤2.3.1）	新（2.4.0）
面板填「识图接口地址 + 识图 API Key + 识图模型名」	三个输入框全部删除，复用 DSH 里已填好的主模型与密钥
先调识图接口拿一句描述，再把描述拼进 prompt	图片和文本同一次请求进主模型：`[{type:'text'}, {type:'image', attachment}]`
两套模型、两套密钥、两份计费	一套配置，文字和看图同一个模型

保留的东西

识图总开关（默认开）、识图提示词（默认「简短描述这张图片内容」，可改、持久化）。
规则面板仍可按群/私聊单独关识图、单独调语音概率。
识图回复照常进 TTS 判定（全部 / 关键词 / 性格随机 / 强制语音）。
强制语音仍是绕过 LLM 的预处理拦截：发个语音说你好 直接抠出「你好」合成发送。
识图关闭 / 图片取不到 / 类型不支持 / 附件服务不可用 / 主模型报错 → 一律走人设兜底台词。

日志

前缀	内容
`[FORCE]`	命中哪个强制语音词、抠出的朗读文本（或「交给模型起稿」）
`[VISION]`	`原生多模态 · 图 N 张` 或 `fallback（原因）`；原因含 `download` / `unsupported-type` / `no-url` / `no-attachment-service`
`[MODEL]`	`multimodal · 带图 N 张请求主模型 · 返回 M 字`
`[TTS]`	`synth-ok`（引擎 + 音色 + 耗时）/ `fail` / `skip`

同类报错 30 秒只写一条，插件不崩、不刷屏。

验收

发「发个语音说你好」→ 直接发 QQ 语音，不经过模型，不会出现「鱼鱼不会按按钮」。
发「一车肥鱼」表情包 → 图片随对话进 V4.1-Flash，小鱼语气回复（日志有 [VISION] 原生多模态 · 图 1 张 + [MODEL] multimodal）。
不用填任何识图地址 / 识图 Key —— 用的就是 DSH 当前选择的主模型。

2.3.1：专项修复（强制语音只回文字 / 发图不识图）

真因（看日志就能确认）

强制语音只回文字：两个原因叠加 ——
- ttsUrl 是空的，plan() 判定「无引擎」→ 只发文字；
- 指令走的是「先让模型说话，再决定发不发语音」，模型先回了「鱼鱼这小短鳍按不来按钮啦」，推脱话术检查里没覆盖「按不来」，于是这条推脱被当正文发出去了。
发图不识图：visionEndpoint 是空的 → 直接 no-endpoint 兜底。

修法

「发个语音说你好」→ 朗读文本 = 你好 → 直接发语音；
「语音说你今天怎么样」→ 朗读文本 = 你今天怎么样；
只说「发语音」没给内容 → 才让模型起稿，但仍强制语音，并注入「禁止说不会发语音/按不了按钮」+ 回复里出现推脱就重试/清洗；
带图 + 强制语音 → 不走抠文本，走识图 + 人设起稿 + 强制语音（否则会把「这是啥」念出来）。
优先级最高：ttsMode=off、随机 0% 也照发。

④ 日志（面板「消息收发记录」直接看）

前缀	内容
`[FORCE]`	是否命中强制语音、命中词、抠出的朗读文本
`[VISION]`	是否触发识图、`ok/fallback`、原因（`no-endpoint` / `auth` / `http-500` / `no-url` …）、识别到的内容
`[TTS]`	`synth-ok`（引擎 http/local + 音色 + 耗时）/ `fail` / `skip`（含 `no-engine` 原因）

同类报错 30 秒内只写一条，不刷屏；所有异常都降级为文字，插件不崩。

升级到 2.3.1 后必须完全退出 DSH 再启动。

2.3.0：强制语音指令 + 识图默认开箱即用

一、TTS 强制语音（内置关键词库，不用配）

只要这句话里命中下列任一说法，优先级最高：跳过模式（哪怕模式是「关闭」）、跳过随机概率，直接合成语音发出去。

例：发「发个语音说你好」→ 直接发语音。

防推脱三层保险：

生成前给模型注入定向提示：你能直接发语音，禁止回答「不会发语音 / 按不了按钮 / 没法发」；
回复里仍出现推脱话术 → 带更硬指令自动重试一次；
还在推脱 → 清洗掉推脱句，语音照发（messages.log 记一行 TTS retry）。

二、识图默认配置

识图开关默认开启；识图提示词默认「简短描述图片内容，不要冗长」（老配置里的旧默认值会自动迁移）。
接口地址支持预设短名，只填一个词就行，模型名会自动补：

填这个	实际地址	自动模型
`zhipu`	open.bigmodel.cn/api/paas/v4/chat/completions	`glm-4v-flash`（有免费额度）
`dashscope`	dashscope.aliyuncs.com/compatible-mode/v1/chat/completions	`qwen-vl-max`
`openai`	api.openai.com/v1/chat/completions	`gpt-4o-mini`
`siliconflow`	api.siliconflow.cn/v1/chat/completions	`Qwen/Qwen2.5-VL-72B-Instruct`
`moonshot`	api.moonshot.cn/v1/chat/completions	`moonshot-v1-8k-vision-preview`
`openrouter`	openrouter.ai/api/v1/chat/completions	`google/gemini-2.0-flash-exp:free`
`ollama`	127.0.0.1:11434/v1/chat/completions	`llava`

也可以填任意完整地址（.../chat/completions）或只填 base 地址（https://api.openai.com/v1，会自动补 /chat/completions），自定义完整地址不会被乱拼。

API Key 只能你自己填（这个没法内置）。

三、联动

识图产出的回复若没有命中强制语音，正常走「心情随机语音」掷骰子。
强制语音与随机模式互不干扰：随机 0% 时普通消息不发语音，但「发语音」指令照样发。
规则面板可对单个群/私聊单独关闭识图、单独设语音概率（规则 > 全局）。
面板「人设已生效」下方能看到：语音已发/跳过/强制/失败、识图成功/失败 + 上一张图内容。

四、容错

升级到 2.3.0 后必须完全退出 DSH 再启动。

2.2.0：识图（看图 → 用人设说话）

面板 AI 配置 → 识图（多模态）：

配置项	说明
识图功能总开关	默认开启。关闭后收到图片只回一句人设兜底台词
多模态模型接口地址	OpenAI 兼容的 `/chat/completions`，如 `https://api.openai.com/v1/chat/completions`
识图 API Key	以 `Bearer` 发送；留空则不带鉴权头
多模态模型名	如 `gpt-4o-mini` / `qwen-vl-max` / `glm-4v-flash`（必须支持图片输入）
识图提示词	默认「描述这张图片，简短一点」

例：识图得到「一整车肥鱼表情包」→ 大肥鱼会说「哇！一整车都是肥鱼小伙伴，浩浩荡荡的，也太热闹啦🥳」。

兜底：识图关闭 / 没填接口 / 超时 / 密钥错 / 请求报错 / 返回空 → 直接回人设台词：「呜…有点糊糊的，鱼鱼眼睛小，得凑很近才看得清一点点。要不你讲讲图里是啥？我慢慢听～」（这条台词整句一次发出，不拆段、不刷屏；同类报错 30 秒内只写一条日志。）
和随机语音联动：识图回复与兜底台词都走同一条投递管道，所以照样按 TTS 模式掷骰子，可能变成语音。
按会话覆盖：管理 → 规则可对某个私聊/群聊单独「关闭识图」。
纯图片消息也能收到：以前没有文字的消息会被当作空消息丢掉，现在只要带图片就放行。
同一张图 10 分钟内复用识别结果（有缓存，不重复烧 token）。
面板「人设已生效」下方会显示识图状态、成功/失败次数和上一张图识别到的内容。

升级到 2.2.0 后必须完全退出 DSH 再启动。

2.1.0：TTS 语音「性格随机模式（想发就发）」

面板 AI 配置 → 语音（TTS） 区域，模式四选一：

模式	行为
`关闭`	只发文字
`全部消息转语音`	每条回复都发语音（回复超过「单条语音最长字数」时自动补发文字，信息不丢）
`关键词触发`	用户或回复里出现触发词（默认「语音 / 发语音 / 说给我听 / 念一下」）才发语音
`性格随机模式（想发就发）`	每轮先掷骰子，命中发语音，没命中只发文字

随机模式细节

⚠️ 语音要真的出声，必须填「TTS 接口地址」。接口只需要 POST {text, voice} 返回音频二进制或 {"audio_base64":"..."}；OpenAI 兼容的 /v1/audio/speech 也能直接用（此时再填「TTS 模型名」）。没填接口时面板会显示「未填接口地址」，行为等同只发文字。

概率滑动条 0~100%，默认 40%；0 = 永不发，100 = 次次发。是每轮独立掷骰，不是固定间隔，所以出现「有时出声、有时懒得开口」的随性节奏。
人设智能权重（默认开）：短句（≤12 字）权重 ×1.3、活泼语气再往上抬；长段解释（>120 字）×0.72、emotion 低落词（难过/累/emo/哭…）再压；人设里带「懒 / 瘫 / 佛系 / 慢悠悠」整体 ×0.9。边界仍然严格：0 还是 0，100 还是 100。
随机音色（默认开）：每次从音色池（默认 软萌少女,甜妹,奶音,软糯小助手，可改）里随机挑，每轮都可能不一样；关掉则固定用「固定音色」。
兜底：TTS 接口超时/报错/返回空/发送失败 → 自动降级只发文字，写 messages.log，插件不崩；如果是「只发语音」模式且发送失败，会补发文字保证用户收到内容。
缓存：同文本+同音色命中内存缓存（TTL 10 分钟、上限 60 条，自动淘汰）。音频全程 base64 直发 NapCat，不落盘，所以没有残留文件需要清理。
按会话覆盖：管理 → 规则里可以对某个群/某个私聊单独设 语音模式 / 概率 / 随机音色（留空 = 跟随全局）。
面板「人设已生效」下方会显示：语音模式、概率、已发 / 跳过 / 失败次数、上一句用的音色 —— 用来确认「确实是想发就发」。

升级到 2.1.0 后必须完全退出 DSH 再启动。旧配置里 ttsEnabled=true 会自动迁移成 ttsMode='all'，行为不变。

2.0.1（紧急修复）：人格不生效 / 固定输出套话

现象：面板里填了「大肥鱼」，问“你叫什么名字”却固定回一句 我觉得这个得看具体情况～你先说说细节，我再给你个靠谱的答复。

两个真实原因（都已修）：

代码里有一段硬编码兜底话术（离线降级时输出）。模型调用一失败就会吐出这句，看起来就像“人格完全没生效”。现在这句连同整套硬编码兜底已彻底删除：模型不可用时就用人设推导一句身份回答（如「我是大肥鱼呀～…」），推导不出来就不发消息，绝不敷衍一句模板话。
system 提示词用错了传参方式。以前把人格塞在 llm.stream({ system }) 这个字段里，而 DSH 的模型协议要求 system 作为 role:'system' 的消息进入 messages；字段被忽略，等于人格根本没送到模型。现在 system 以标准消息发送，面板文本一字不改地成为唯一 system。
顺带修掉「模型返回空内容」→ 之前 maxTokens=800 时，模型的思维链会把预算吃光，可见文本为空，于是又触发第 1 条的兜底话术。现在 maxTokens=2000，并且空内容会自动以 reasoningEffort:'off' 重试一次。

现在的规则：

面板填了人格 → 它就是唯一的 system（不加前缀、不追加任何“最高优先级”之类的说明文字，也不放风格模板）；
面板留空 → 完全不发 system，不自动补任何文字；
问身份（你叫什么 / 你是谁 / 你会做什么）→ 额外给一条定向指令：直接按人设第一人称回答，禁止“看具体情况、你先说说细节”式回避；万一模型还是回避，会自动带硬指令重试一次；
上下文（历史 / 摘要 / 知识库）和排版要求全部挪到 user 消息里，不再污染 system。

升级到 2.0.1 后必须完全退出 DSH 再启动（服务端代码只在启动时加载）。

三步验收

导入 dsh-napcat-bot-2.8.0.tgz → 完全退出并重启 DSH（服务端代码只在启动时加载）→ 启用插件 → 日志出现「内置 NapCat 已就绪，WebUI 监听 127.0.0.1:6099」。
设置页左侧【集成】里点「NapCat QQ 机器人」→ 第二个标签页「NapCat WebUI」已自动带上管理 Token，直接扫码登录。
三个状态灯全绿（NapCat 进程 ✓ / WS 已连接 ✓ / 可以收发消息 ✓）后，私聊发消息、群里 @ 机器人即可收到 AI 回复。

端口分工（1.5.0 起强制纠正，不再可能连错）

用途	地址	说明
NapCat WebUI（管理面）	`http://127.0.0.1:6099/webui`	只用来扫码登录 QQ、看 NapCat 自己的面板。它不是 OneBot 端口
OneBot 正向 WS（收消息）	`ws://127.0.0.1:3001`	插件主通道。连上后 NapCat 的「WS 客户端数」显示 1
OneBot HTTP（发消息）	`http://127.0.0.1:3000`	能开就用；没开也不影响，插件会自动改走 WS 通道发送

⚠️ 关键：QQ 登录 ≠ WS 自动连上

这是本插件踩过的最深的坑，1.4.0 修了配置生效问题，1.5.0 又补了两个：

坑 0：WS 连到 6099 上（1.5.0 修复）

坑 1：改配置文件不生效（1.4.0 修复）

所以插件改用 NapCat 自己的 WebUI HTTP API 来配置 OneBot 网络：

POST /api/auth/login              { hash = sha256(webuiToken + ".napcat") }  → data.Credential
POST /api/OB11Config/SetConfig    { config: "<json 文本>" }   // NapCat 内部 save + reloadNetwork

坑 2：OneBot HTTP 必须打到具名路径（1.4.0 修复）

NapCat 的 HTTP 适配器不按 body 里的 action 字段分发。往根路径 POST http://127.0.0.1:3000 只会得到一个桩响应：

{"status":"ok","retcode":0,"data":{},"message":"NapCat4 Is Running"}

于是 get_login_info 永远拿不到 QQ 号（面板显示「未登录」），send_private_msg / send_group_msg 变成空操作（消息永远发不出去却也不报错）。

两处 Token（插件已全自动，这里只是说明区别）

Token	用途	谁生成
WebUI 管理 Token	登录 `http://127.0.0.1:6099/webui` 这个管理页面	插件启动前写入 `config/webui.json`，随后从 NapCat 启动日志（`[WebUi] WebUi Token: xxx`）自动读取校验；内嵌页面自动附加，无需手输
OneBot access_token	插件 ↔ NapCat 通信用（HTTP Bearer / WS query），真正收发 QQ 消息	插件首次启用时随机生成，自动写进插件配置与 NapCat 的 `onebot11_<QQ>.json`

两者完全独立：WebUI Token 只影响能否打开管理页面；OneBot token 只影响插件能否调 NapCat 的 API。

自动写入的 NapCat 配置

插件启动内置 NapCat 前会主动写配置文件（作为兜底），并在运行期用官方 API 校正：

config/webui.json：host=127.0.0.1、port=6099、带 token、不禁用 WebUI。
config/onebot11_<QQ>.json（对历史登录过的 QQ 号全部预置）：
- 正向 HTTP（默认 3000）—— 插件用它发消息、查登录态；
- 正向 WS（默认 3001）—— 插件用它收消息；
- 两者使用同一个自动生成的 token（与插件配置一致，不一致会直接 403 → 全链路静默）；
- reportSelfMessage=false，避免机器人收到自己发的消息形成自问自答。

状态灯与自动重连（1.5.0）

面板顶部固定三个灯，语义与 NapCat 侧对得上：

灯	含义
🟢 NapCat 进程已启动	内置 NapCat 在跑（按 6099 端口实际监听判定，不是看状态文件）
🟡 WS 正在尝试连接	插件正在重连 `ws://127.0.0.1:3001`；旁边显示第几次重试、下次重试倒计时
🔴 WS 连接失败	重连次数用尽（`wsMaxRetries>0` 时）或环境不支持 WebSocket
🟢✓ 可以收发消息	WS 已连接且 3001 在监听且 QQ 已登录

灯下面一行会直接显示 WS 目标：ws://127.0.0.1:3001（端口 3001），并标注 客户端数 1，可以和 NapCat WebUI 里的「WS 客户端数」对照。

重连策略（面板可调）：

首次重连间隔 wsRetryInterval（默认 2000ms），之后指数退避 2→4→8→15s（上限 wsRetryMaxInterval）。
wsMaxRetries 默认 0 = 一直重试；填 N 则连续失败 N 次后停止（按钮可手动重连）。
连接超时 8s 未建立即判失败换下一次（不依赖 onclose——实测 Node 的 WebSocket 在连接被拒时可能只触发 error）。
心跳看门狗：连上后 wsHeartbeatTimeout（默认 100s）内收不到任何数据（含心跳）→ 判定半死连接，主动重连。
NapCat 重启 / QQ 掉线重连后，插件检测到 3001 恢复监听会立即重连，不用手动操作。
进程守护：NapCat 进程异常退出（6099 不再监听）→ 状态如实回落成「未运行」，并在 12s 后自动重新拉起； 10 分钟内最多自动拉起 3 次，超过则停在「反复退出」提示，避免把 QQ 拉成重启风暴。

消息应答逻辑（默认即正确）

私聊自动回复；群聊默认仅在被 @ 时回复（面板可关）。
只处理真人聊天消息：post_type=message 且 message_type=private|group；自动丢弃点赞 / 群成员变动等 notice、心跳 meta_event、加好友请求、机器人自己发的消息（含 sub_type=self）、以及纯图片语音等无文字消息。
回复时把人设 Prompt + 最近 10 条对话记忆一起喂给模型，输出限制为口语化短句（不用 Markdown、不自称 AI）。
回复引擎默认 dsh：走 ctx.get('llm') + ctx.get('agentDefaultModel').currentSelection()，用你在 DSH 里选中的模型与凭据，不需要另填 API Key。
发送失败会被捕获并显示在面板（发送失败：...），同时计入「失败」计数。
面板顶部有连接指示灯：未连接 / 连接中 / 已就绪，并显示 QQ 号、收发计数、最近收到时间、错误信息。

面板结构（固定两个标签页）

AI 配置：AI 配置 内含内置 NapCat 状态卡与启停、连接（全部自动维护，一般不用改）、人格与回复、行为与风控（记忆开关、群内仅 @ 回复、主动发言、冷却与每分钟上限）。
NapCat WebUI：内嵌 WebUI（自动免 Token 登录，这里扫码登录 QQ）、两类 Token 卡片、NapCat 控制台日志预览（实时刷新 / 暂停 / 只看 Token 行 / 复制日志）。

插件详情页里的配置表单同样保留，两个入口共存。

进程管理

启动前先检测：自己的 pid 文件 + 日志里的 Main Process ID + 6099 端口探测 + 短期互斥锁，绝不重复多开 NapCat / QQ。
关闭插件或退出 DSH 时自动停掉由本插件拉起的 NapCat 进程树（面板可关 stopNapCatOnDisable）。
面板提供「启动内置 NapCat / 重新启动 / 停止」。

关于 QQ（唯一的外部前提）

面板里填写的 qqPath；
%ProgramFiles% / %ProgramFiles(x86)% / %LOCALAPPDATA%\Programs 下的 Tencent\QQNT\QQ.exe；
C: – F: 盘下的 Program Files\Tencent\QQNT\QQ.exe、Tencent\QQNT\QQ.exe。

探测不到时面板会明确提示「未检测到 QQ NT」并给出填写入口。

HTTP 面板接口

注意：宿主 webServer 的 prefix 匹配是 pathname === prefix || pathname.startsWith(prefix + '/')，因此 prefix 路由的 path 结尾不能带斜杠（早期版本 /napcat-bot/api/napcat/ 就是因为这个永远 404）。

方法	路径	说明
GET	`/napcat-bot/api/status`	连接三态、OneBot 登录态、内置进程态、WebUI Token、运行计数、当前回复引擎
GET/POST	`/napcat-bot/api/config`	读取 / 保存配置（保存即热重载）
GET	`/napcat-bot/api/webui`	WebUI 地址 + 自动读取的管理 Token + OneBot token
POST	`/napcat-bot/api/webui/token`	重新生成 / 指定 WebUI 管理 Token（并重启生效）
POST	`/napcat-bot/api/napcat/{start\|stop\|restart}`	内置 NapCat 启停
POST	`/napcat-bot/api/napcat/reconnect`	只重连插件侧 WS（不动 NapCat、不踢 QQ）
POST	`/napcat-bot/api/napcat/apply-onebot`	立即通过 WebUI API 重新应用 OneBot 配置
GET	`/napcat-bot/api/napcat/log?tail=N`	控制台日志尾部（含 Token 行）
POST	`/napcat-bot/api/client-report`	客户端 UI 注册自检回执（排障用）

排障

现象	处理
面板还是旧样子（没有三个灯 / 没有端点行）	服务端代码只在 DSH 启动时加载。装完新版必须完全退出 DSH 再启动，否则跑的还是内存里的旧版本
侧边【集成】没有入口	看 `~/.dsh/napcat-bot/client-report.json`，其中 `registered` 应含 `settings.section`（1.5.0 已验证会出现）
WS 状态未知 / 断开，NapCat 里客户端数 0	1.5.0 已自动纠正到 3001；确认面板「WS 目标」这一行显示的是 `ws://127.0.0.1:3001`
状态灯一直「WS 正在尝试连接」	点「重新应用 OneBot 配置」；若仍不行看日志里有没有 `WebSocket服务: ... 已启动`
显示「未登录」但 QQ 确实在线	1.4.0 已修：OneBot HTTP 必须 POST 到 `/<action>`，打到根路径只会拿到桩响应
日志面板 404	1.3.0 起已修（路由 path 去掉尾斜杠），确认版本 ≥ 1.5.0
收到消息但发不出去	1.5.0 会自动改走 WS 通道发送，不再依赖 3000；若仍失败看面板 `发送失败：...` 的具体报错
NapCat 进程显示「未运行」	1.5.0 按端口真实存活判定，会 12s 后自动拉起（10 分钟内最多 3 次）；也可点「启动内置 NapCat」
回复走离线兜底	面板连接卡显示「回复引擎：离线兜底应答」→ DSH 未配置模型，或 `llm` 服务不可用
内嵌 WebUI 空白	个别版本禁止 iframe 嵌套，点「在浏览器打开」，链接已带 Token

v2.0.0：AstrBot 风格消息管道

三个标签页

标签	内容
AI 配置	三个状态灯、端点明细、人设生效提示、消息收发记录、全部开关与字段
NapCat WebUI	内嵌管理页（自动带 token），扫码登录 QQ
管理	人格 / 会话 / 规则 / 知识库 / 任务五个子页

消息处理顺序

组件解析（文本/图片/@/语音/文件/卡片）→ 过滤（自身、系统、进退群、红包闪照、空消息、纯表情）
黑白名单（用户 + 群）→ message_id 去重（跨实例共享，2 分钟窗口；另加 1.5s 内容指纹兜底）
私聊直达；群聊「@ 唤醒 → 免@ 超时（默认 120s，滑动续期）→ 超时静默」
会话等待器（多轮流程接管，例如 /idiom 成语接龙，接管期间不过模型）
指令层（见下）→ 上下文（历史 + 摘要压缩 + 知识库检索）→ 模型流式 → 分段发送

会话隔离

私聊：private:${uid}，强制独立，不可关闭。
群聊：开关 groupUniqueSession（面板「会话策略」里）
- 开：group:${gid}:${uid}，每人独立上下文
- 关：group:${gid}，全群共用一套

指令

基础：/help /reset /new /stop /stats /sid /history /ls /rename /del /switch /idiom 管理员：/op /deop /ban /unban /model /provider /groupnew

人格优先级

知识库

定时任务

目录结构

lib/index.js           服务端主入口（配置 schema、路由、生命周期、单例守卫）
lib/client.js          面板 UI（AI 配置 / NapCat WebUI / 管理 三个标签）
lib/pipeline.js        消息流水线：解析 → 过滤 → 去重 → 指令 → 识图 → 搜索 → 推理 → 分段/语音
lib/responder.js       DSH 模型调用（system 只来自面板人格，三级重试，绝不输出套话）
lib/napcat.js          OneBot 连接：HTTP 动作 + 正向 WS + 重连/心跳
lib/napcat-embedded.js 内置 NapCat 进程管理（启动/停止/探活/自动拉起）
lib/vision.js          原生多模态：图片 → 附件引用；两种识图模式
lib/search.js          联网搜索：手动指令 + 自动查证 + 断路器
lib/tts.js             TTS 四种模式 + 强制语音 + 音色池 + 缓存
lib/tts-local.js       内置离线语音（Windows SAPI）
lib/proactive.js       主动发言调度（随缘随机、仅冷却）
lib/state.js           人格/规则/定时任务持久化
lib/sessions.js        会话与上下文
lib/kb.js              知识库混合检索
lib/risk.js            限流 / 黑白名单
tools/                 开发期自测脚本（Node 原生跑，无第三方依赖）

License

MIT

9178159/dsh-napcat-bot

dsh-napcat-bot

安装

2.8.0：联网搜索（手动 + 不懂自动查）

两类触发

优先级

兜底与容错

配置 / 规则 / 日志

2.7.0：识图默认「读梗接话」，下指令才描述画面

2.6.0：主动发言改成「随缘」（去掉倒计时与次数上限，只留冷却）

面板

日志

2.5.0：空闲主动发言（会接话，不会刷屏）

面板

日志

2.4.0：识图改用主模型原生视觉（不再配两套模型）

做法

保留的东西

日志

验收

2.3.1：专项修复（强制语音只回文字 / 发图不识图）

真因（看日志就能确认）

修法

2.3.0：强制语音指令 + 识图默认开箱即用

一、TTS 强制语音（内置关键词库，不用配）

二、识图默认配置

三、联动

四、容错

2.2.0：识图（看图 → 用人设说话）

2.1.0：TTS 语音「性格随机模式（想发就发）」

2.0.1（紧急修复）：人格不生效 / 固定输出套话

三步验收

端口分工（1.5.0 起强制纠正，不再可能连错）

⚠️ 关键：QQ 登录 ≠ WS 自动连上

坑 0：WS 连到 6099 上（1.5.0 修复）

坑 1：改配置文件不生效（1.4.0 修复）

坑 2：OneBot HTTP 必须打到具名路径（1.4.0 修复）

两处 Token（插件已全自动，这里只是说明区别）

自动写入的 NapCat 配置

状态灯与自动重连（1.5.0）

消息应答逻辑（默认即正确）

面板结构（固定两个标签页）

进程管理

关于 QQ（唯一的外部前提）

HTTP 面板接口

排障

v2.0.0：AstrBot 风格消息管道

三个标签页

消息处理顺序

会话隔离

指令

人格优先级

知识库

定时任务

目录结构

License

Community comments

9178159/dsh-napcat-bot

dsh-napcat-bot

安装

2.8.0：联网搜索（手动 + 不懂自动查）

两类触发

优先级

兜底与容错

配置 / 规则 / 日志

2.7.0：识图默认「读梗接话」，下指令才描述画面

2.6.0：主动发言改成「随缘」（去掉倒计时与次数上限，只留冷却）

面板

日志

2.5.0：空闲主动发言（会接话，不会刷屏）

面板

日志

2.4.0：识图改用主模型原生视觉（不再配两套模型）

做法

保留的东西

日志

验收

2.3.1：专项修复（强制语音只回文字 / 发图不识图）

真因（看日志就能确认）

修法