@zaofan/dsh-qqbot 1.4.0 → 1.4.5

package/README.md

@@ -253,6 +253,75 @@ npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 
 **配置项**(Web 面板 ⑥ 可改, 见下表 `groupAdmin.*`)
 
+## 🧠 本地小模型（可选，省 token）(v1.4.5+)
+
+让插件先用一个**跑在本机的小模型**给群消息打分（「价值评分」）：分数低于门槛、又**没被 @** 的闲聊
+**直接不唤醒 AI** → 那一轮 token 就省下来了；被 @ 的永远放行，**带图的消息一律放行**（群友发图多半是给她看的）。
+
+- **模型**：`bge-small-zh-v1.5`（中文专训，ONNX 量化版 **≈ 23MB**，CPU 毫秒级，**零 token、完全离线**，不上传任何内容）
+- **位置**：`{DSH_HOME | ~/.dsh}/models/bge-small-zh/`（用户级，跨工作区共用一份；也可在配置里指别的目录）
+- **缺了也不影响使用**：检测不到模型就**自动静默关闭**评分，插件照常跑（只是不再省 token）
+
+### ① 一条命令下载（推荐）
+
+```bash
+node scripts/download-model.mjs                                   # 源码分发(在插件仓库根目录跑)
+node node_modules/@zaofan/dsh-qqbot/scripts/download-model.mjs    # npm 装的插件(npm 目录内)
+```
+
+默认**优先走国内镜像** `hf-mirror.com`（失败自动换官方源），下载完会校验体积并打印后续步骤。可选参数：
+
+```bash
+node scripts/download-model.mjs --dir "D:\models\bge-small-zh"   # 换目录(填进插件配置 localModel.modelDir)
+node scripts/download-model.mjs --source hf                       # 强制官方源
+```
+
+### ② 手动下载（就三个文件）
+
+把 `<源>` 换成 `https://hf-mirror.com` 或 `https://huggingface.co`，文件放到 `~/.dsh/models/bge-small-zh/`：
+
+| 下载地址 | 存放位置 | 体积参考 |
+|---|---|---|
+| `<源>/BAAI/bge-small-zh-v1.5/resolve/main/onnx/model_quantized.onnx` | `bge-small-zh/onnx/model_quantized.onnx` | ≈ 23MB |
+| `<源>/BAAI/bge-small-zh-v1.5/resolve/main/tokenizer.json` | `bge-small-zh/tokenizer.json` | ≈ 430KB |
+| `<源>/BAAI/bge-small-zh-v1.5/resolve/main/config.json` | `bge-small-zh/config.json` | < 1KB |
+
+Windows PowerShell 例子：
+
+```powershell
+$dir  = "$env:USERPROFILE\.dsh\models\bge-small-zh"
+$base = "https://hf-mirror.com/BAAI/bge-small-zh-v1.5/resolve/main"
+New-Item -ItemType Directory -Force "$dir\onnx" | Out-Null
+Invoke-WebRequest "$base/onnx/model_quantized.onnx" -OutFile "$dir\onnx\model_quantized.onnx"
+Invoke-WebRequest "$base/tokenizer.json"            -OutFile "$dir\tokenizer.json"
+Invoke-WebRequest "$base/config.json"               -OutFile "$dir\config.json"
+```
+
+### ③ 交给 AI 做（把下面这段直接粘给你的 AI / dsh 里的她）
+
+```text
+请帮我在本机装好 dsh 的 qqbot 插件要用的本地小模型（离线、不上传内容）：
+1. 下载 BAAI/bge-small-zh-v1.5 的三个文件到 `~/.dsh/models/bge-small-zh/`：
+   onnx/model_quantized.onnx（≈23MB）、tokenizer.json、config.json；
+   国内优先用 https://hf-mirror.com，失败再试 https://huggingface.co。
+2. 目录结构必须是：<模型目录>/onnx/model_quantized.onnx、<模型目录>/tokenizer.json、<模型目录>/config.json
+3. 下完自己校验：model_quantized.onnx ≥ 20MB、tokenizer.json ≥ 300KB；
+   也可以直接跑插件仓库里的一键脚本：`node scripts/download-model.mjs`
+4. 最后告诉我：插件设置页「本地小模型」这一项该填什么、以及三个评分模式 off / log / block 分别什么行为。
+```
+
+### 评分模式怎么选
+
+| 模式 | 行为 | 建议 |
+|---|---|---|
+| `off` | 完全不评分，所有消息照常唤醒 | 不想掺和 |
+| `log` | **只记分，不拦** | **观察期**：先跑几天，在面板「最近评分」看分准不准 |
+| `block` | 低于门槛（默认 `0.5`）**不唤醒** | 正式使用、省 token |
+
+- **会话级覆盖**：dock「⚙ 单会话设置」里可以**按群单独设**模式 / 门槛 / 开关（存 `settings.yaml` 的 `localModel.overrides`），**保存即时生效，无需重启**（v1.4.5 起）。
+- **拦截边界**：被 @ 的永远放行；带图一律放行；**只有被拦在唤醒之前**（没花 token）的那次才会**回滚**本群的回复冷却 —— 冷却本来就是用来省 token 的，token 花了就不算白花。
+- **评分记录**：`{dataRoot}/.qqbot/value-scores.jsonl`，一行一条，字段 `score / worth / gate / min / conf / mention / img / lib / agg / top`。面板能直读，也可以让 AI 读它来维护样例库（`{dataRoot}/.qqbot/value-samples.jsonl`：`{"m":"消息文本","y":1|0}`，y=1 表示"她会想接话"）。
+
 ## 配置项
 
 | 配置 | 类型 | 默认值 | 说明 |
@@ -275,6 +344,7 @@ npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
 | `groupAdmin.manageGroup` | string | `''` | 对话内默认管理群 openid(web/非群会话时用) |
 | `groupAdmin.watchJoinRequests` | boolean | `false` | 订阅入群申请事件(改后需重启) |
 | `groupAdmin.notifyInGroup` | boolean | `true` | 收到申请时在群内发提醒 |
+| `messageReference` | boolean | `true` | 引用消息总开关(v1.4.1): 开=入站消息带**短消息号** + 引用附原文 + 注入引用指令, AI 可用 `[rf:短号]` 引用对方; 关=完全不注入 |
 
 > 🔧 新版 Web 面板把群管理单开成「⑥ QQ 群管理」卡片(入群审批/禁言/成员信息/黑名单), 与上方 `groupAdmin.*` 配置同一份数据。
 
@@ -378,6 +448,7 @@ export default {
 | `[MEDIA:file\|来源]` | 发文件 | `[MEDIA:file\|D:\docs\计划.pdf]` |
 | `[RECALL]` | 撤回自己刚发的那条消息 | 单独一行写 `[RECALL]` |
 | `[RECALL:N]` | 撤回自己发的倒数第 N 条 | 如 `[RECALL:2]` 撤倒数第二条 |
+| `[rf:短号]` | **引用**某条消息（以引用气泡形式发出） | `[rf:0913a]` 引用短号 `0913a` 那条 |
 
 要点：
 - 图片/文件可用**本机绝对路径**或**网络 URL**；语音本地路径若为 QQ SILK 格式也能转码发送。
@@ -385,6 +456,20 @@ export default {
 - 一次回复可混用多条 `[MEDIA:]`，配合长文本拆条连发使用。
 - 这些是"AI 会自己写"的暗号——正常聊天时她收到"发个开心点的图"这类指令，会自己调工具完成，不需要你手动写标记。
 
+### 引用消息（v1.4.1，默认开）
+
+每条入站消息都带一个**短消息号**（形如 `#0913a` = 月日 + 流水号）：
+
+```
+[做早饭 (E9020753…) #0913a] 帮我看看这个
+```
+
+- AI 想引用某条消息时，在回复正文里写 `[rf:0913a]`，这条回复就会以**引用气泡**发出（对方能看到"她引用了这条"）。
+- 别人引用某条消息时，**被引用原文**会一并进上下文（`[Quoted message begins] … [Quoted message ends]`），AI 能读懂"他在回哪句话"。
+- 短号 ↔ 完整 msg_id 的对应关系存在本地台账 `{dataRoot}/.qqbot/msg-index/{群|私聊}/refs.json`（**按会话分文件夹**，每份上限 500 条，超出丢最旧；带时间与发送者昵称，可直接打开查）。
+- 好处：长 msg_id（60+ 字符）不再进上下文，**短号只花 1-2 token**。
+- 关闭：设置面板 ③ 区块去掉「引用消息」勾选 → 不登记台账、不注入短号、不注入引用指令。
+
 ## 核心模块
 
 ```

package/README_EN.md

@@ -221,6 +221,21 @@ auto-cancelled when the agent is cancelled or dsh exits.
 | `textChunkLimit` | number | `4500` | Max chars per message |
 | `sessionIdleTimeout` | number | `1800000` | Session idle timeout (ms), default 30 min |
 | `debug` | boolean | `false` | Debug mode |
+| `messageReference` | boolean | `true` | Message-reference master switch (v1.4.1): inbound messages carry a **short message number** + quoted originals are included + the reference instruction is injected, so the AI can reply with a quote via `[rf:short-id]`; off = nothing injected |
+
+## Message Reference (v1.4.1, on by default)
+
+Every inbound message carries a **short message number** (e.g. `#0913a` — month/day + rolling id):
+
+```
+[做早饭 (E9020753…) #0913a] take a look at this
+```
+
+- To quote a message, the AI writes `[rf:0913a]` in its reply body → the reply is sent as a **quote bubble** (the other side sees "she quoted this message"). The tag itself is never displayed.
+- When someone quotes a message, the **quoted original** is included in the context (`[Quoted message begins] … [Quoted message ends]`), so the AI understands what is being replied to.
+- The short-id ↔ full msg_id mapping lives in a local ledger at `{dataRoot}/.qqbot/msg-index/{group|dm}/refs.json` — **one folder per conversation**, capped at **500 entries** each (oldest dropped first), with timestamps and sender nicknames so it stays human-readable.
+- Why: full msg_ids (60+ chars) no longer enter the context — a short id costs **1-2 tokens** instead of ~20+ per message.
+- Turn it off in the settings panel (section ③, "引用消息"): no ledger, no short ids, no instruction injected.
 
 ## Built-in Commands