@zaofan/dsh-qqbot 1.6.6 → 1.6.8

package/README.md

@@ -41,6 +41,11 @@ QQ 官方**没有开放踢人接口**，所以这一块走"你自己的 QQ 号 +
 **🗂️ 归档了也会自己回家**
 不小心把她的会话点了「归档」藏进侧边栏深处？不用满世界找——那个会话**下次在 QQ 里被消息触发时**，会自己从归档里摘出来回到侧边栏（你主动归档的其它会话不受影响）。
 
+**🔝 QQ 一有动静，她的会话自己爬到最上面**（v1.6.8）
+侧边栏里正在跟你聊的那个会话，不该被别的压着 —— QQ 里一有消息、她**真的回了话**，对应会话就会自动插到「**还热着**」的那批之后（10 分钟内聊过的算热，**置顶的永不动**），冷掉的会话自然被它越过。全程事件驱动、不轮询；宿主没起来、或聊天页没开着时天然不排序。
+
+![侧边栏会话自动重排：刚聊过的「鲸鱼娘舒尔特诗格权限修复」跃到工作区最前，越过了 12 小时 / 1 天前的那批](docs/screenshots/session-reorder.png)
+
 **🖥️ 不碰配置文件，设置面板点点点**
 怎么回、能发什么图、什么时候开口、什么人格——面板上改完保存即生效（只有增删账号才要重启）。还有 ✏️ 预设人格编辑器，直接在网页里改她的"性格文件"。
 
@@ -297,6 +302,56 @@ dsh: disabling profile plugin row "mcp-chrome": Plugin ... is incompatible with
 
 想强行运行，可用官方提供的**确切版本例外**（`dsh plugin allow-version`，或插件管理页里授予），但官方警告"可能崩溃或数据丢失"，自行权衡。
 
+## 🤖 自定义事件 + 「让 AI 写」（v1.6.7）
+
+普通的互动卡片只能「点按钮 → 回一句固定文本」，能力被编辑器框死。
+这一版让卡片**变成一个真的 JS 模块**（可以叫 AI 帮你写），于是它能做到编辑器做不到的事：
+
+- **自己维护状态**：谁点过、点了几次、本轮名单 —— 落盘、升级不丢
+- **自己判权限**：QQ 的按钮权限是"整张卡片一个"，但模块里能用 `ctx.user.isOwner` 做到"这个按钮只有主人能点"
+- **自己发消息**：文本 / markdown / 图片，还能 @ 某人
+- **调 AI**：`ctx.appendSilent()` 静默记进上下文；或 `ctx.appendWake()` **把 AI 叫起来**
+- **调官方 API**：模块拿到 `ctx.appId` / `ctx.appSecret`，自己换 token 就能 fetch 任意官方接口
+
+### 📸 长什么样
+
+**① 面板：事件列表 + 「让 AI 写」+ 自定义事件信息区**
+
+![自定义事件面板](docs/screenshots/botplay-custom-event-panel.png)
+
+**② 效果：签到统计 + 结束后唤醒 AI（AI 自己开口总结）**
+
+![唤醒 AI 演示](docs/screenshots/botplay-wake-ai-demo.png)
+
+**③ 那 AI 到底收到了什么？（这就是 `ctx.appendWake` 的内容）**
+
+![AI 收到的唤醒内容](docs/screenshots/botplay-wake-payload.png)
+
+> 事件模块自己决定"什么时候叫醒 AI、告诉它什么"，并顺手把"你只要补一句人话、别复述名单"
+> 这种约束一起发过去 —— 所以 AI 的回复才既贴群气氛、又不啰嗦。
+> **这一段不是插件写死的，是卡片模块（AI 写的那个 .mjs）自己组织的。**
+
+> 上面第二张就是"第三方框架做不到的事"：**卡片点完后 AI 也知道了结果**，
+> 而且它会顺着群里的气氛自己说人话 —— 那段「带头营业（尾巴摇摇）」不是模板文案，是 AI 现场说的。
+
+### 怎么用
+
+1. 面板 → 📤 群发 → **互动事件** → 底部「🤖 让 AI 写自定义事件」输入框
+2. 用大白话写你要什么，例如：
+   > 我想写一个签到人数统计，有两个按钮，按钮1是签到，所有人都能点且每个人只能点一次；
+   > 按钮2是结束，只能我点。我点结束后，bot 发送消息到 QQ 上，统计签到人数和所有签到者的名称
+3. 点 **🤖 让 AI 写** —— 面板会把「你的需求 + 官方文档链接 + 契约 + 环境信息」发进当前会话；
+   AI 按契约写一个 `.mjs` 放进 `{dataRoot}/.qqbot-extensions/botplay/`，并登记到 `botplay-events.json`
+4. 改完模块后，面板点 **🔄 重载模块** 即生效（**不用重启**）
+5. 想让它回到普通编辑器：把事件 JSON 里的 `file` 字段删掉即可
+
+### 契约在哪
+
+`docs/botplay-contract.md` —— **纯文本、可直接改**（改完重启宿主生效）。
+它定义了模块导出哪些钩子、`ctx` 有哪些能力（含上面那几条），也是「让 AI 写」时发给 AI 的那份说明。
+
+---
+
 ## 🔨 锤子面板：禁言 / 踢人（v1.6.3）
 
 dock 面板里的 **🔨 锤子**（原来叫「🔇 禁言」），下面分两页：

package/README_EN.md

@@ -27,6 +27,11 @@ The little ball at the corner of the settings panel opens a whole control deck:
 
 **🛡️ Group-admin helper** — join approval + mute management over official APIs, with human-readable errors (not an admin / cannot mute the owner…).
 
+**🔝 A QQ message brings her session back to the top** (v1.6.8)
+The web-sidebar session you are actually talking to should not be buried. As soon as a QQ message lands in one of her web sessions **and she really replies**, that session is moved to just after the still-"hot" ones (anything active within 10 minutes counts as hot; **pinned sessions never move**), so it leapfrogs whatever has gone cold. Fully event-driven, no polling — and nothing happens when the chat page is closed or the host is not up yet.
+
+![Sidebar auto-reorder: the just-active session jumps to the top of its workspace, leapfrogging the 12-hour / 1-day-old ones](docs/screenshots/session-reorder.png)
+
 **🖥️ No config-file surgery** — reply pacing, sticker gates, scheduled wake-ups, outbound mode and per-bot personas are all in the panel; saving applies live (only adding/removing bots needs a restart). There is even a ✏️ persona editor to tweak her "personality file" right in the browser.
 
 **📦 Clean & lean** — drive image sending / recall from plain text (`[MEDIA:image|path]` / `[RECALL]`); the repo contains no bot credentials or private data.