@zaofan/dsh-qqbot 1.3.0 → 1.4.1

package/README.md

@@ -61,8 +61,10 @@
 
 ### 给AI的话
 - QQ 会话内可直接调用的标准工具：发图/撤图/查库/打标/查未整理/定时（`send_media`/`recall_message`/`list_stickers`/`sticker_tag`/`sticker_untagged`/`schedule_timer`/`schedule_cancel`…），会话按账号精确路由
-- **群管理工具**（`group_join_requests`/`group_approve_join`/`group_join_auto`/`group_mute_state`/`group_mute_member`…）：入群审批与禁言，需机器人为该群管理员；对话内管当前群，web/非群会话用配置的 `manageGroup`。**入群审批默认听主人的，不自动批**——先 `group_join_requests` 查看，把申请人+验证信息汇报给主人，等主人明确说"通过/拒绝"再 `group_approve_join`；**主人明确要求**"按关键词自动批"时才用 `group_join_auto`（命中关键词放行 / 未命中拒绝，`dry_run` 可预览）
+- **群管理工具**（`group_join_requests`/`group_approve_join`/`group_join_auto`/`group_mute_state`/`group_mute_member`/`id_lookup`…）：入群审批与禁言，需机器人为该群管理员；**禁言可批量**（`member_openids` 数组，单次最多 20 人；`gid` 可指向别的群）；**按昵称查 openid 用 `id_lookup`**（想主动 @ 没 @ 过你的人时用它；⚠️ 从没发过言、没申请过入群的人查不到，官方群成员列表接口未开放）；对话内管当前群，web/非群会话用配置的 `manageGroup`。**入群审批默认听主人的，不自动批**——先 `group_join_requests` 查看，把申请人+验证信息汇报给主人，等主人明确说"通过/拒绝"再 `group_approve_join`；**主人明确要求**"按关键词自动批"时才用 `group_join_auto`（命中关键词放行 / 未命中拒绝，`dry_run` 可预览）
+- **图片消息的内置「看图」提示可关**（`imageHint`，默认开）：关掉后不再注入「把 URL 传给识图工具」那条提示 —— 模型自己能读图时，在设置面板 ③ 区块取消勾选即可。
 - **纯文本也能发图撤消息**：让 AI 在回复里写 `[MEDIA:image|图片路径或网址]` 就自动变成真图发出去（`voice`/`video`/`file` 同理）；写 `[RECALL]` 撤回自己刚发的那条
+- **扩展命令能悄悄唤醒 AI**：命令返回 `{ wake: { content } }` 即可 —— 插件会把这条消息塞进**和真人消息同一个聚合窗口**（多人同时触发自动合并成一回合，不浪费 token），适合「用户没找到想要的东西 → 自动喊 AI 去找」这类场景。
 - **跨会话通信**：`session_list` 列出全部会话（含潜在群）；`session_wake(session_id 或 scope+peer_id, text, send_qq?, media?)` 向指定会话/群发消息并唤醒对方 LLM，可同时走 QQBot 通道发给人看，`media` 支持跨群发图
 - **省 token 设计（v1.3.0）**：群历史行默认 `[昵称] 内容`（只有被 @ 的那条带 openid），`session_list` 默认"群名+尾号"（`full=true` 才给完整），`group_join_requests`/`list_stickers` 等列表默认 3~5 条并可翻页 —— 长聊天的上下文开销明显更小
 - **入群申请的两种形态**：
@@ -273,6 +275,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.*` 配置同一份数据。
 
@@ -376,6 +379,7 @@ export default {
 | `[MEDIA:file\|来源]` | 发文件 | `[MEDIA:file\|D:\docs\计划.pdf]` |
 | `[RECALL]` | 撤回自己刚发的那条消息 | 单独一行写 `[RECALL]` |
 | `[RECALL:N]` | 撤回自己发的倒数第 N 条 | 如 `[RECALL:2]` 撤倒数第二条 |
+| `[rf:短号]` | **引用**某条消息（以引用气泡形式发出） | `[rf:0913a]` 引用短号 `0913a` 那条 |
 
 要点：
 - 图片/文件可用**本机绝对路径**或**网络 URL**；语音本地路径若为 QQ SILK 格式也能转码发送。
@@ -383,6 +387,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

@@ -43,8 +43,10 @@ Right: sticker-battle in action — the bot answers with stickers from its own l
 
 ### For developers
 - Standard tools available inside QQ sessions: `send_media` / `recall_message` / `list_stickers` / `sticker_tag` / `sticker_untagged` / `schedule_timer` / `schedule_cancel` …, routed per bot account.
-- **Group admin tools** (`group_join_requests` / `group_approve_join` / `group_join_auto` / `group_mute_state` / `group_mute_member` …): join-request approval and mute management — requires the bot to be a group admin; inside a group session the current group is used, elsewhere the configured `manageGroup` applies. **Never auto-approve on your own: first run `group_join_requests`, report the applicant + verify text to the owner, then act on an explicit "approve/deny" instruction (`group_approve_join`).** Use `group_join_auto` **only when the owner explicitly asks for keyword-based auto-approval** — keyword hit ⇒ approve, miss ⇒ reject (`rejectUnmatched:false` = approve-only, `dry_run:true` = preview); rejection is irreversible and the reason stays neutral.
+- **Group admin tools** (`group_join_requests` / `group_approve_join` / `group_join_auto` / `group_mute_state` / `group_mute_member` / `id_lookup` …): join-request approval and mute management — requires the bot to be a group admin; inside a group session the current group is used, elsewhere the configured `manageGroup` applies. **Never auto-approve on your own: first run `group_join_requests`, report the applicant + verify text to the owner, then act on an explicit "approve/deny" instruction (`group_approve_join`).** Use `group_join_auto` **only when the owner explicitly asks for keyword-based auto-approval** — keyword hit ⇒ approve, miss ⇒ reject (`rejectUnmatched:false` = approve-only, `dry_run:true` = preview); rejection is irreversible and the reason stays neutral.
+- **The built-in "look at this image" hint can be turned off** (`imageHint`, on by default): when off, the plugin no longer injects the "pass this URL to a vision tool" line — uncheck it in settings panel section ③ if your model can read images by itself.
 - **Plain text can send media or recall messages**: writing `[MEDIA:image|path-or-url]` in a reply turns it into a real image message (`voice`/`video`/`file` work the same); a lone `[RECALL]` line recalls the bot's own last message.
+- **Extension commands can quietly wake the AI**: return `{ wake: { content } }` and the plugin injects that message into the **same debounce window as real user messages** (multiple triggers merge into one turn, saving tokens) — handy for "user could not find it → automatically ask the AI to search".
 - **Cross-session messaging**: `session_list` lists all sessions (incl. latent groups); `session_wake(session_id or scope+peer_id, text, send_qq?, media?)` sends a message to a target session/group and wakes its LLM, optionally also delivering to the bound QQ group/private chat (for humans); `media` supports cross-group images.
 - **Token-lean by design (v1.3.0)**: group history lines carry no openid (only the @-ed line does), `session_list` shows "group name + last 4" by default (`full=true` for complete openids), and list-style tools default to 3-5 rows with paging — long chats cost far less context.
 - **Two forms of a join request**:
@@ -219,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