@zaofan/dsh-qqbot 1.10.48 → 1.11.1

package/README.md

@@ -200,7 +200,7 @@ export default {
 > 调官方 API / 持久化 / 身份…）就是插件内部模块在用的同一套封装，所以你写的东西不是"外挂"，
 > 只是**长在同一条链上的另一个模块**。
 
-**🧩 六套扩展点，挑一个放进去就行**
+**🧩 七套扩展点，挑一个放进去就行**
 
 | 你想做的事 | 放哪个目录 | 什么时候跑 |
 |---|---|---|
@@ -210,8 +210,9 @@ export default {
 | 启动时恢复任务 / 起定时器 / 预取 | `hooks/` | 插件启动时跑一次 |
 | **管每一条消息的命运** | `inbound/` | **每条消息都过一遍** |
 | **管每一条出站消息 / 补发媒体** | `outbound/` | **每条要发出去的消息都过一遍** |
+| **给面板/悬浮球加自己的界面** | `ui/` | 页面加载时（静态资源，不进 import 流程） |
 
-**🧰 一套能力包，六套通用**（不用为每套各记一套 API）
+**🧰 一套能力包，七套通用**（不用为每套各记一套 API）
 
 ```js
 await env.text('hi') / env.markdown('# 标题') / env.markdownCard(md, keyboard)
@@ -246,6 +247,36 @@ env.user / env.owners / env.peer · env.log() · env.kernel（全权限遥控器
 - 📘 **写扩展前先读**：[`docs/extension-contract.md`](./docs/extension-contract.md) —— 五套扩展点、能力包全表、
   入站操控、安全红线、常见坑，一份写全
 
+### 🖼 自定义界面：给面板和悬浮球加自己的卡片
+
+不想只加功能、还想**加个界面**？`ui/` 就是干这个的 —— 丢三个文件进去，
+设置页顶栏或悬浮球里就多一个页签，里面是你自己写的 HTML。
+
+```
+{PROFILE_ROOT}/.qqbot-extensions/ui/<目录>/   ← slot: settings（全局，所有机器人共用）
+{dataRoot}/.qqbot-extensions/ui/<目录>/       ← slot: dock（每个机器人一份，能读当前会话数据）
+```
+
+元信息写在 `card.html` 顶部注释里：
+
+```html
+<!-- qqbot-ui: { "id": "demo", "slot": "dock", "title": "🔌 扩展示例", "order": 5 } -->
+```
+
+卡片跑在 **Shadow DOM** 里 —— 你的样式不会污染面板，崩了也只白自己那张卡。
+能拿到 `qqbotExt` 这个 API 对象：读写两级配置、往当前会话静默注入消息、
+读写本机文本文件、调宿主服务（`kernel.get`）、访问你自己的后端路由。
+
+![dock 扩展卡片](docs/images/ext-ui-dock.png)
+
+下面这张是**设置页**的卡片 —— 注意它能「改全局」也能「改当前选中账号」，
+一个界面同时管两种作用域：
+
+![设置页扩展卡片](docs/images/ext-ui-settings.png)
+
+> 完整 API、两条硬边界（样式隔离、拿不到面板 DOM）、示例代码：见
+> [`docs/extension-contract.md`](docs/extension-contract.md) §1 末尾「第六套：`ui/`」。
+
 ### 🎁 白送的扩展示例：装上就有能跑、能抄的样板
 
 插件启动时会把这些示例**只补不覆盖**地铺进你的扩展目录 —— 不用自己从零写。
@@ -267,6 +298,12 @@ env.user / env.owners / env.peer · env.log() · env.kernel（全权限遥控器
 - **启动就跑一次**：打日志、计数落盘（跨重启累加）；
 - **注册监听并自己收尾**：演示怎么挂监听、怎么在卸载时清理干净
 
+**给她加一个自己的界面**
+
+- **`ui/demo/`**：设置页一张（改全局 / 改当前账号）+ 悬浮球一张（五个子标签：改本实例文本、
+  读会话数据、自有存储、静默注入、读写文件）—— 抄它就能做出自己的面板
+- **`ext-commands/扩展示例.mjs`**：配套的 `/扩展示例` 命令，演示「两级配置 + 命令读」的完整链路
+
 **让她管"每条消息的命运"**
 
 - **引用子会话不叫醒她**：群里引用一条"子会话转发"的消息，不会被当成在叫她；
@@ -847,4 +884,4 @@ autoRecall:
 
 [MIT](./LICENSE)
 
----
+---