@zaofan/dsh-qqbot 1.10.26 → 1.10.27

package/README.md

@@ -73,8 +73,94 @@ QQ 官方**没有开放踢人接口**，所以这一块走"你自己的 QQ 号 +
 
 ![群管理·审批放行成功效果](docs/screenshots/group-admin-approval-chat.png)
 
+图⑥：**插件市场**——两列卡片、封面图、版本号、安装/更新/卸载一键搞定（数据来自扩展索引仓库，支持填代理解决墙内访问）；
+图⑦：**扩展包面板**——每个包下面直接列出它带的工具和 `/斜杠命令`，点「设置」还能配自定义参数。
+
+![插件市场（卡片网格 / 封面 / 一键安装更新）](docs/images/market.png)
+
+![扩展包面板（工具与斜杠命令按包分组展示）](docs/images/packs.png)
+
+图⑧：**设置中心**——50 个内置扩展一览，每个都能单独开关、点齿轮改配置；
+图⑨：**扩展自注册设置面板**——扩展用 `qqbotSettingsPage` 声明 schema，面板自动渲染出表单，值存成 JSON 供扩展读取。
+
+![设置中心（内置扩展一览与单条开关）](docs/images/settings-center.png)
+
+![扩展自注册设置面板（声明式 schema 自动渲染）](docs/images/ext-settings.png)
+
+---
+
+
 ---
 
+## 📦 扩展包与插件市场：把你的扩展分享给别人
+
+单个 `.mjs` 是「扩展文件」，**一个目录就是一个「扩展包」** —— 可以带工具、斜杠命令、封面、版本号，装进别人的面板里就是一张卡片。
+
+市场索引在独立仓库：[**zaofan-make/dsh-qqbot-plugins**](https://github.com/zaofan-make/dsh-qqbot-plugins)。
+
+### 目录结构
+
+```
+packs/你的插件id/              ← id 只能用字母数字-_（它就是安装后的目录名）
+  qqbot-pack.json              ← 元信息，必填
+  cover.png                    ← 可选，卡片封面（自动探测 cover.png/jpg/webp/gif）
+  tools/xxx.mjs                ← 可选，给 AI 调用的工具
+  commands/yyy.mjs             ← 可选，/斜杠命令
+```
+
+`qqbot-pack.json`：
+
+```json
+{
+  "name": "实用小工具",
+  "author": "你的名字",
+  "version": "1.0.0",
+  "description": "一句话说明，会显示在卡片上",
+  "homepage": "https://github.com/你/你的仓库",
+  "tags": ["工具", "日常"]
+}
+```
+
+`name` / `author` / `version` 必填，其余可选。
+
+### 上传流程（不需要 token，也不会冲突）
+
+```bash
+# 1. fork + clone
+git clone https://github.com/<你>/dsh-qqbot-plugins.git
+
+# 2. 只加你自己的目录
+mkdir -p packs/my-pack/tools packs/my-pack/commands
+#   写 qqbot-pack.json、tools/*.mjs、commands/*.mjs
+
+# 3. 提 PR
+```
+
+**不要改 `index.json`** —— 它由 GitHub Action 自动生成：
+
+- 提 PR → 自动跑检查（manifest 字段、`node --check` 语法、禁二进制、`inputSchema` 格式）
+- 合并到 main → Action 扫描 `packs/*/qqbot-pack.json`，重建索引（**顺便把文件清单和封面也扫出来**，你不用手写）
+- 两个人同时提 PR **也不会冲突**，因为各自只加自己的目录
+
+### ⚠️ 最容易踩的坑：`inputSchema` 不是标准 JSON Schema
+
+```js
+// ✅ 对：dsh 的扁平写法，属性名 → 类型描述
+export default {
+  name: 'pick_one',
+  description: '从列表里随机挑一个',
+  inputSchema: {
+    options: { type: 'array', items: { type: 'string' }, description: '候选选项' },
+  },
+  run: async (args) => ({ ok: true, msg: '选中：' + args.options[0] }),
+}
+
+// ❌ 错：包成标准 JSON Schema，注册时会被拒
+// inputSchema: { type: 'object', properties: { options: {...} } }
+//   → unsupported JSON schema: parameters.type must be a value schema object
+```
+
+命令的契约也不一样：工具用 **`run`**，命令用 **`handler`**（返回字符串）。
 
 ---
 
@@ -646,55 +732,55 @@ AI 侧的工具叫 **`qq_group_admin`**：
 - **不常驻**：拿到凭据立刻关；等扫码最多留 5 分钟；宿主退出时会一起带走（不留孤儿进程）
 - 凭据只存在你自己的机器上，仓库里不含任何凭据
 
-## ♻️ 撤回消息与自动撤回（v1.10.11+）
-
-机器人**是群管理员**时，可以撤回**普通成员**的消息（官方窗口 2 分钟，超时就撤不了，这是平台限制）。
-
-### 三个工具
-
-| 工具 | 作用 |
-| --- | --- |
-| `group_recall` | 撤某人最近一条 / 群里最近一条 / 指定 message_id |
-| `group_msg_search` | 按关键词或类型搜台账（**含机器人自己发的**），返回 message_id |
-| `group_recall_batch` | 批量撤（给 msg_ids，或给关键词/类型让它自己挑）+ 可选批量禁言发送者 |
-
-`gid` 是**可选**的：不传 = 当前会话所在的群；要撤别的群（机器人也是那个群的管理员）才传。
-
-### 自动撤回（设置面板 → 🔨 锤子 → ♻️ 自动撤回）
-
-命中关键词或附件类型 → 消息**一进来就撤**，不等 AI。配置项 `groupAdmin.autoRecall`：
-
-```yaml
-autoRecall:
-  enabled: true
-  mode: keep          # keep=仍进 AI（只撤消息）；drop=连 AI 都收不到
-  keywords: ["加我微信"]
-  kinds: []           # text / image / voice / video / file，按附件类型命中
-  muteSeconds: 0      # >0 时顺带禁言发送者
-  dryRun: false       # true = 只记日志、不真撤
-```
-
-> **实现位置很关键**：挂在 **debounce 之前**的中间件里。
-> 写在 `bot.on('message')` 里会被 debounce 吃掉（它 consume 后自己调 `handleInbound`）；
-> 写在 `handleInbound` 里又要等派发，等到了往往已过 2 分钟窗口 —— 两种都实测踩过。
-
-## 📒 消息历史台账（v1.10.11+）
-
-```
-{dataRoot}/.qqbot/msg-history/
-├── _索引.txt                 # 目录 ↔ 群名 对照，方便人工辨认
-├── group_<群openid>/
-│   ├── 群名.txt              # 文件名就是群名
-│   └── 2026-10-20.jsonl      # 一天一个文件
-└── c2c_<对方openid>/
-    └── 2026-10-20.jsonl
-```
-
-- 一行一条：`message_id` / 发送者 / 昵称 / 类型 / 正文摘要 / 时间 / 是否机器人
-- 默认保留 **7 天**（启动时 + 每 200 次写清理过期文件；目录空了自动删）
-- 入站与出站都记；`group_msg_search` / `group_recall*` 就是读它
-- 与引用补全用的 `.qqbot/msg-content.jsonl` **互不干扰**（后者只存被引用消息的正文与图片路径）
-
+## ♻️ 撤回消息与自动撤回（v1.10.11+）
+
+机器人**是群管理员**时，可以撤回**普通成员**的消息（官方窗口 2 分钟，超时就撤不了，这是平台限制）。
+
+### 三个工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `group_recall` | 撤某人最近一条 / 群里最近一条 / 指定 message_id |
+| `group_msg_search` | 按关键词或类型搜台账（**含机器人自己发的**），返回 message_id |
+| `group_recall_batch` | 批量撤（给 msg_ids，或给关键词/类型让它自己挑）+ 可选批量禁言发送者 |
+
+`gid` 是**可选**的：不传 = 当前会话所在的群；要撤别的群（机器人也是那个群的管理员）才传。
+
+### 自动撤回（设置面板 → 🔨 锤子 → ♻️ 自动撤回）
+
+命中关键词或附件类型 → 消息**一进来就撤**，不等 AI。配置项 `groupAdmin.autoRecall`：
+
+```yaml
+autoRecall:
+  enabled: true
+  mode: keep          # keep=仍进 AI（只撤消息）；drop=连 AI 都收不到
+  keywords: ["加我微信"]
+  kinds: []           # text / image / voice / video / file，按附件类型命中
+  muteSeconds: 0      # >0 时顺带禁言发送者
+  dryRun: false       # true = 只记日志、不真撤
+```
+
+> **实现位置很关键**：挂在 **debounce 之前**的中间件里。
+> 写在 `bot.on('message')` 里会被 debounce 吃掉（它 consume 后自己调 `handleInbound`）；
+> 写在 `handleInbound` 里又要等派发，等到了往往已过 2 分钟窗口 —— 两种都实测踩过。
+
+## 📒 消息历史台账（v1.10.11+）
+
+```
+{dataRoot}/.qqbot/msg-history/
+├── _索引.txt                 # 目录 ↔ 群名 对照，方便人工辨认
+├── group_<群openid>/
+│   ├── 群名.txt              # 文件名就是群名
+│   └── 2026-10-20.jsonl      # 一天一个文件
+└── c2c_<对方openid>/
+    └── 2026-10-20.jsonl
+```
+
+- 一行一条：`message_id` / 发送者 / 昵称 / 类型 / 正文摘要 / 时间 / 是否机器人
+- 默认保留 **7 天**（启动时 + 每 200 次写清理过期文件；目录空了自动删）
+- 入站与出站都记；`group_msg_search` / `group_recall*` 就是读它
+- 与引用补全用的 `.qqbot/msg-content.jsonl` **互不干扰**（后者只存被引用消息的正文与图片路径）
+
 ## 🚫 无上下文模式（按会话省 token）
 
 让某个 QQ 会话**每轮只记得最近几条对话**，更早的历史自动折叠 —— 群聊省 token 利器。
@@ -728,28 +814,28 @@ autoRecall:
 ## License
 
 [MIT](./LICENSE)
-
----
-
-## 正文图组：markdown 图片直接发
-
-DSH 前端会把**回复正文里的 markdown 图片**渲染成图；本插件把同一段文本**原样转发到 QQ** ——
-本地路径会自动上传成 `qqbot-media` 引用（读文件头补真实宽高，配额满 100 张自动删最早），不需要调用任何工具。
-
-```markdown
-![干饭女王 #400px](D:/pics/a.jpg)
-
-第一幕：本鲸宣布今晚不睡了
-
-![何意味 #400px](D:/pics/b.jpg)
-```
-
-**一行一张、连续几行就是图组**（小剧场 / 分镜 / 图文并排），QQ 侧按顺序渲染成一屏。
-
-| DSH 前端 | QQ 群 |
-| :---: | :---: |
-| ![DSH 前端显示](docs/images/dsh-md-images.png) | ![QQ 群显示](docs/images/qq-md-images.jpg) |
-
-配合表情包库最顺手：`list_stickers` 搜到图 → 把本地路径写进正文 → 图组直接出来，比连发 `send_media` 更像翻漫画。
-
-失败策略：图传不上去时会**原样留在文字里**（不阻断本条，不会吞掉正文）。
+
+---
+
+## 正文图组：markdown 图片直接发
+
+DSH 前端会把**回复正文里的 markdown 图片**渲染成图；本插件把同一段文本**原样转发到 QQ** ——
+本地路径会自动上传成 `qqbot-media` 引用（读文件头补真实宽高，配额满 100 张自动删最早），不需要调用任何工具。
+
+```markdown
+![干饭女王 #400px](D:/pics/a.jpg)
+
+第一幕：本鲸宣布今晚不睡了
+
+![何意味 #400px](D:/pics/b.jpg)
+```
+
+**一行一张、连续几行就是图组**（小剧场 / 分镜 / 图文并排），QQ 侧按顺序渲染成一屏。
+
+| DSH 前端 | QQ 群 |
+| :---: | :---: |
+| ![DSH 前端显示](docs/images/dsh-md-images.png) | ![QQ 群显示](docs/images/qq-md-images.jpg) |
+
+配合表情包库最顺手：`list_stickers` 搜到图 → 把本地路径写进正文 → 图组直接出来，比连发 `send_media` 更像翻漫画。
+
+失败策略：图传不上去时会**原样留在文字里**（不阻断本条，不会吞掉正文）。