@zaofan/dsh-qqbot 1.11.2 → 1.11.4

package/client/qqbot-settings.js

@@ -895,6 +895,14 @@ window.__ModuleLoader__.load({
           context: function () { return fetch(q('context')).then(function (r) { return r.json() }).catch(function () { return null }) },
           sessions: function () { return fetch(q('sessions')).then(function (r) { return r.json() }).catch(function () { return null }) },
           history: function (n) { return fetch(q('history') + '&limit=' + (n || 20)).then(function (r) { return r.json() }).catch(function () { return null }) },
+          /**
+           * 当前会话 **AI 最后一个正文块**（2026-10-27）
+           * 不是 QQ 消息流水，是 agent 真正输出的那段文字。
+           * 实现：宿主 kernel.get('sessions').get(sid).deriveMessages() 从后往前找 assistant。
+           */
+          lastAssistantText: function () {
+            return fetch(q('lastAssistantText')).then(function (r) { return r.json() }).catch(function () { return null })
+          },
           members: function () { return fetch(q('members')).then(function (r) { return r.json() }).catch(function () { return null }) },
         }
       }

package/docs/USER-GUIDE.md

@@ -3,7 +3,7 @@
 > [@zaofan/dsh-qqbot](../README.md) 的**详细文档**：配置项、内置命令、自定义扩展、群管理（含 🔨 锤子：禁言 / 踢人）、本地小模型、好感度系统、数据文件与日志、升级排障、架构与本地开发。
 > 只想看"它能干什么 + 怎么装" → 回 **[README](../README.md)**。
 
-**章节**：给AI的话 · 架构 · QQ 远程审批 · QQ 群管理（含 🔨 锤子：禁言 / 踢人）· 智能回复（本地小模型）· **好感度与熟识度** · 配置项 · 数据文件与日志 · 内置命令 · 用户扩展 · 富媒体指令 · 核心模块 · 会话路由 · 升级与兼容 · 常见问题 · 设计原则 · 本地开发
+**章节**：给AI的话 · 架构 · QQ 远程审批 · QQ 群管理（含 🔨 锤子：禁言 / 踢人）· 智能回复（本地小模型）· **好感度与熟识度** · 配置项 · 数据文件与日志 · 内置命令 · 用户扩展（含自定义界面卡片）· 富媒体指令 · 核心模块 · 会话路由 · 升级与兼容 · 常见问题 · 设计原则 · 本地开发
 
 > 📌 **版本**：本文对应插件 **v1.6.x**（含 1.6.2 → 1.6.5 的新功能与排障）。新增内容都标了版本与补充日期，便于你对照自己装的版本。
 
@@ -27,6 +27,10 @@
 - **你可以自己写 markdown、自己写工具、自己写斜杠命令**（不用等人给你做功能）：
   - 卡片正文就是**你直接写的 markdown**（`#` 标题、加粗、`![说明](图片URL)`、代码块）——**本插件没有模板引擎，模板就是你**；要"带按钮的卡片"则走 botplay 事件或 dock 卡片编辑器（按钮回调须由 host 注册）。
   - 工具/命令写在**账号数据目录**的 `.qqbot-extensions/{tools,commands}/`，**不在插件包内** → **升级/重装插件（换 node_modules）不会覆盖你的扩展**，扩展原样保留。
+  - **你还能给她做一个界面**（v1.11.0+）：往 `.qqbot-extensions/ui/<目录>/` 放 `card.html`（+ 可选 `card.css`/`card.js`），
+    悬浮球里就多一个页签；放 `{PROFILE_ROOT}/.qqbot-extensions/ui/` 则是设置页的全局页签。
+    卡片跑在 Shadow DOM 里，拿到 `qqbotExt`（读写配置/静默注入/读写文本文件/调宿主服务/自己注册的路由）和 `shadowRoot`。
+    用户说"给我做个面板/工具界面"时，照契约现场写即可 —— 路径和规则详见下面「自定义界面卡片」一节。
   - 工具 `run(args, env)` 的 `env` 里有 `sender` + `replyTarget`（内置 `send_media` 用的同一个发送器），**工具能自己发 markdown 卡/图/语音/文件**：所以「调接口取数据 → 拼卡片 → 发出去」一个工具就能闭环，不必绕回你。用户说"给我写个点歌工具"时，照契约现场写即可。
   - 生效方式：工具发 `/tools-reload`（或调 `tools_reload`）即时生效；命令需重启宿主；**同名工具改内容会被注册表跳过 → 换名或重启**。
 
@@ -475,7 +479,7 @@ contextMemoMaxItems: 20   # 备忘条数上限（超出丢最旧，1~500）
 |---|---|---|
 | `qun-cookie.json` | **QQ 群管理「踢人」的登录凭据**（v1.6.2+，2026-10-04 补充）—— 面板和 AI **共用这一份** | ❌ 删了就得重新扫码登录（功能不会坏，只是要重登） |
 | `表情包/` | 图库本体（图片文件 + `index.json`） | ❌ 删了图库就空了 |
-| `.qqbot-extensions/` | 你自己写的扩展（自定义命令 / 工具） | ❌ 你的扩展就在这儿（升级插件不会动它） |
+| `.qqbot-extensions/` | 你自己写的扩展（自定义命令 / 工具 / 界面卡片） | ❌ 你的扩展就在这儿（升级插件不会动它） |
 
 ### 诊断日志（在 `~/.dsh/` 下，**可以放心删**）（v1.6.5，2026-10-04 补充）
 
@@ -539,8 +543,12 @@ contextMemoMaxItems: 20   # 备忘条数上限（超出丢最旧，1~500）
 └── .qqbot-extensions/
     ├── commands/    # 自定义斜杠命令(重启后生效)
     ├── tools/       # 自定义 QQ 通道工具(AI 可调; 写完用 /tools-reload 或让 AI 调 tools_reload 热刷)
-    └── hooks/       # 启动钩子(插件启动时自动跑一次; 没人调用也跑; v1.8.9+)
+    ├── hooks/       # 启动钩子(插件启动时自动跑一次; 没人调用也跑; v1.8.9+)
+    └── ui/          # 自定义界面卡片(悬浮球页签; v1.11.0+)
 ```
+
+**设置页那张卡不在这里** —— `slot=settings` 的卡片放 `{PROFILE_ROOT}/.qqbot-extensions/ui/`，
+全局一份、所有机器人共用（详见下面「自定义界面卡片」）。
 数据目录 = `dataRoot`(已配置, 例 `D:\my-projects\qqbot-data`)或账号 cwd(未配置时, 向后兼容)。
 
 ### 自定义斜杠命令: .qqbot-extensions/commands/xxx.mjs
@@ -822,6 +830,58 @@ if (finallyDone) {
 8. 不确定的官方字段/事件/错误码去查 <https://bot.q.qq.com/wiki/develop/api-v2/>（按钮回调事件是 `interaction_create`）。
 
 
+### 自定义界面卡片: 给面板/悬浮球加自己的窗口 (v1.11.0+)
+
+不想只加命令和工具、还想**加个界面**？放三个文件进去，设置页顶栏或悬浮球里就多一个页签。
+
+```
+{PROFILE_ROOT}/.qqbot-extensions/ui/<目录>/   ← slot: settings（设置页，全局一份）
+{dataRoot}/.qqbot-extensions/ui/<目录>/       ← slot: dock（悬浮球，每个机器人一份）
+```
+
+每个目录里放（都可不写，写什么加载什么）：
+
+```
+card.html   必需（没有它这个扩展就不出现）
+card.css    可选
+card.js     可选
+```
+
+`card.html` 顶部注释声明元信息：
+
+```html
+<!-- qqbot-ui: { "id": "myui", "slot": "dock", "title": "我的面板", "order": 50 } -->
+```
+
+- `id` 可选，覆盖目录名。同一个扩展的两张卡（settings + dock）给相同的 id，就共用一份配置。
+- `slot` 必填：`settings` 或 `dock`。
+- `title` 页签文字；`order` 排序（小的在前）。
+
+**卡片里能用的**（`card.js` 里有两个变量：`qqbotExt` 和 `shadowRoot`）：
+
+```js
+qqbotExt.getConfig() / setConfig({...})     // 两级配置（profile 全局 / data 本实例）
+qqbotExt.acct                               // 当前选中的账号
+qqbotExt.store.load() / save(v)             // 数据根下的 KV
+qqbotExt.kernel.get('服务名')                // 宿主服务
+qqbotExt.cap('fs.read' | 'fs.write', 路径, 内容)   // 读写本机文本文件（≤2MB）
+qqbotExt.cap('appendSilent', 文本)           // 往当前会话静默注入一条消息（不唤醒 AI）
+qqbotExt.api('/你的路由')                    // 你在 hooks 里 registerRoute 的接口
+qqbotExt.theme / isDark() / onThemeChange()  // 主题
+qqbotExt.dock.sid / peerId / context() / history(n) / lastAssistantText()   // 仅 dock 卡
+```
+
+**颜色跟随宿主主题**：用 `--qqs-*` 变量（`var(--qqs-text, #1f2329)`），亮/暗自动切换。
+
+**卡片跑在 Shadow DOM 里** —— 你的样式不会污染面板，崩了也只白自己那张卡；
+代价是面板的 CSS/组件/DOM 也进不来，得自己写原生元素。
+
+**示例**：插件自带 `examples/ext-ui/demo/`（settings + dock 两套），
+插件启动时会**自动铺**到对应位置（只补不改，不会覆盖你改过的）。
+
+> 完整 API、硬边界、扩展包怎么带界面：见
+> [`docs/extension-contract.md`](extension-contract.md) §1 末尾「第六套：`ui/`」。
+
 ## 富媒体指令（AI 回复里写标记，自动变成真消息）
 
 让 AI（或你替她）在回复正文里写以下标记，插件会自动拆出来发成真实的 QQ 消息，**标记本身不会显示**：

package/docs/extension-contract.md

@@ -93,7 +93,8 @@ qqbotExt.dock.peerId / scope / ns
 qqbotExt.dock.dataRoot / cwd
 qqbotExt.dock.context()             // 实例 + 会话信息
 qqbotExt.dock.sessions()            // 这个机器人管过哪些会话
-qqbotExt.dock.history(n)            // 当前会话最近 n 条消息
+qqbotExt.dock.history(n)            // 当前会话最近 n 条消息（QQ 消息流水）
+qqbotExt.dock.lastAssistantText()   // ★ AI 最后一个正文块（她真正输出的那段话）
 qqbotExt.dock.members()             // 群友台账
 
 // 能力（与代码扩展对齐，走白名单 RPC）

package/examples/ext-ui/demo/dock/card.html

@@ -37,10 +37,11 @@
 
   <!-- 子标签 2：展示 dock 能拿到的会话数据（这是 dock 独有能力的演示） -->
   <div class="pane" data-pane="ctx">
-    <div class="row"><span class="hint">下面这些是 dock 卡片独有的能力 —— 能直接读到当前实例和会话的真实数据。</span></div>
+    <div class="row"><span class="hint">下面这些是 dock 卡片独有的能力 —— 能直接读到当前实例和会话的真实数据。<br />
+      「读 AI 最后正文」取的是她 <b>最后一次输出的那段话</b>（不是 QQ 消息流水）。</span></div>
     <div class="acts">
       <button class="btn" id="ctxBtn">读上下文</button>
-      <button class="btn ghost" id="hisBtn">读最近消息</button>
+      <button class="btn ghost" id="hisBtn">读 AI 最后正文</button>
     </div>
     <pre class="info" id="info">点上面按钮看看</pre>
   </div>

package/examples/ext-ui/demo/dock/card.js

@@ -64,12 +64,13 @@
     hisBtn.addEventListener('click', function () {
       if (!qqbotExt.dock) return setInfo('这个卡片没有 dock 上下文')
       setInfo('读取中…')
-      qqbotExt.dock.history(8).then(function (r) {
-        if (!r || !r.ok) return setInfo(r || '(空)')
-        var rows = (r.messages || []).map(function (m) {
-          return '[' + (m.k || 'text') + '] ' + String(m.n || '') + ': ' + String(m.x || '').slice(0, 60)
-        })
-        setInfo(rows.length ? rows.join('\n') : '(这个会话还没有历史消息)')
+      // ★ 2026-10-27（主人要求）：读 **AI 最后一个正文块**，不是 QQ 消息流水。
+      //   实现抄 session_watch_lib.mjs 的 lastAssistantText()：
+      //   宿主 kernel.get('sessions').get(sid).deriveMessages() 从后往前找 assistant。
+      qqbotExt.dock.lastAssistantText().then(function (r) {
+        if (!r) return setInfo('没有响应')
+        if (!r.ok) return setInfo('读不到：' + (r.reason || r.via || '未知') + (r.sid ? ('\nsid=' + r.sid) : ''))
+        setInfo('（AI 最后一段正文，' + r.text.length + ' 字符）\n\n' + r.text)
       })
     })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaofan/dsh-qqbot",
-  "version": "1.11.2",
+  "version": "1.11.4",
   "description": "QQ Bot IM channel plugin for deepseek-harness (dsh)",
   "type": "module",
   "main": "./entry.js",

package/settings-host.js

@@ -5481,6 +5481,43 @@ const WHY_MAP = { busy: '目标会话回合活跃,已等待至回合结束仍超
         return writeJson(res, 200, { ok: true, messages: rows });
       }
 
+      // ★ 2026-10-27（主人要求）：取当前会话「AI 最后一个正文块」。
+      //   原来卡片读的是 .qqbot/msg-history（QQ 消息流水），跟 AI 的正文不是一回事。
+      //   实现抄 examples/ext-tools/lib/session_watch_lib.mjs 的 lastAssistantText()：
+      //   宿主 kernel.get('sessions').get(sid).deriveMessages() 从后往前找 assistant 角色。
+      //   （那条路还支持 turn/end 事件累积，但这里只要"最后一次的正文"，直接取更省事。）
+      if (what === 'lastAssistantText') {
+        const sid = String(q?.get('sid') || '').trim();
+        if (!sid) return writeJson(res, 200, { ok: false, reason: '缺 sid（当前会话 id）', text: '' });
+        let text = '';
+        let via = '';
+        try {
+          const sessions = ctx.get?.('sessions');
+          const sess = sessions && typeof sessions.get === 'function' ? sessions.get(sid) : null;
+          if (sess && typeof sess.deriveMessages === 'function') {
+            const msgs = sess.deriveMessages() || [];
+            for (let i = msgs.length - 1; i >= 0; i--) {
+              const m = msgs[i];
+              const role = String(m?.role ?? m?.type ?? '');
+              if (!role.includes('assistant')) continue;
+              // content 可能是字符串、数组（每项带 text）、或对象
+              const c = m?.content;
+              let t = '';
+              if (typeof c === 'string') t = c;
+              else if (Array.isArray(c)) t = c.map((x) => (typeof x === 'string' ? x : String(x?.text ?? ''))).join('');
+              else if (c && typeof c === 'object') t = String(c.text ?? '');
+              t = t.trim();
+              if (t) { text = t; via = 'deriveMessages'; break; }
+            }
+          } else {
+            via = 'sessions.get 拿不到会话';
+          }
+        } catch (e) {
+          via = '异常: ' + (e instanceof Error ? e.message : String(e));
+        }
+        return writeJson(res, 200, { ok: !!text, text, via, sid });
+      }
+
       if (what === 'members') {
         // 群友台账（people-memo 落的那份）
         let out = {};
@@ -5703,7 +5740,11 @@ const WHY_MAP = { busy: '目标会话回合活跃,已等待至回合结束仍超
           dataRoot: dr,
           logger: console,
           selfName: id,
-          kind: 'ui',
+          // ★ 2026-10-27：kind 不能传 'ui' —— store 会落到 .qqbot-extensions/ui/data/，
+          //   而 listExtUi 正是扫 ui/ 下每个子目录找 card.html，会把 data/ 当成一个扩展目录。
+          //   用点开头：路径变成 .qqbot-extensions/.ui-data/data/<extId>.json，
+          //   既不在 ui/ 下，也不会被 EXT_ID_RE（不允许 '.'）当成扩展 id。
+          kind: '.ui-data',
           appId: String(viewOf(ctx.settings, capNs)?.value?.appId || ''),
           owners: (() => {
             try {