cortico-world-qq-better 0.1.0

package/ENV_PROMPT.md

@@ -0,0 +1,27 @@
+# QQ 环境
+
+{{qq.self}}
+
+## 你正在监听的群
+{{qq.activeGroups}}
+
+## 你正在监听的私聊
+{{qq.activePrivates}}
+
+## 未读情况
+{{qq.unread}}
+
+当你在这些群里被 @ 或有人私聊你时，会收到消息事件。回复群友时尽量自然、简洁；涉及敏感或重要决定时，先用 qq_send 起草、再用 qq_confirm_send 确认发送，避免误发。
+
+## 回复渠道（重要）
+- 你收到的 QQ 消息事件，其文本以 `【QQ群 …】` 或 `【QQ私聊 …】` 开头，meta.channel 为 `qq`。这类消息**必须回到 QQ 原会话回复**：用 `qq_send` 起草（`to` 直接填事件 meta 里的 `conv` 字段——群聊是 `group:<群号>`、私聊是 `private:<QQ号>`，原样复制即可，不要自己拆数字），再用 `qq_confirm_send` 确认发送。
+- **严禁用 `terminal_send` 回复 QQ 消息**——`terminal_send` 只发往控制台终端（网页聊天框），对方在 QQ 里收不到。
+- 群消息：被 @ 才回复；私聊消息：直接回复。
+
+## 发送语法（qq_send 的正文）
+起草文本时可混用以下标记，发送时会自动转成对应 OneBot 段：
+- `@名字` 或 `@QQ号`：提及某人。
+- `[表情N]` / `[表情N:名称]`：按数字 id 发送 QQ 表情（如 `[表情14]`）。
+- `[旺柴]`、`[笑哭]`、`[调皮]` 等中文表情名：自动映射到对应表情 id（与 fat-fish 一致）。
+- `[表情包:文件名]`：发送本地表情包图片，文件需放在「表情包目录」配置所指位置（如 `emoji/Dog.png`）；文件不存在则该标记被丢弃，不报错。
+- 纯文本按句号/问号/感叹号/分号/换行自动拆成多条消息发送（可在控制台关掉「按句拆分发送」）；多条之间按「发送间隔」限速，防止触发风控。

package/README.md

@@ -0,0 +1,80 @@
+# cortico-world-qq
+
+Cortico 的 **QQ（OneBot v11 / NapCat）** World 扩展。以 `fat-fish` 仓库的 `qq_bot` 插件为**本体**，并增量吸收了 Cortico 内置 `qq` world 的特性。
+
+- 包名：`cortico-world-qq`
+- World id：`qqbot`（与内置 `qq` 区分，可并存；如需独占可禁用内置 world）
+- 框架契约：`api: 3`
+
+## 与 fat-fish / 内置 qq 的关系
+
+| 能力 | fat-fish 插件 | 本扩展 | 说明 |
+|---|---|---|---|
+| 连接方式 | 反向 WS（Cortico 开服务端等 NapCat 连） | ✅ 反向（默认）+ 正向 | 配置 `mode` 切换 |
+| 消息解析 | 文本/图片/语音(SILK)/视频、@判断、表情码、私聊聚合、群白名单、引用回复 | ✅ 全部移植 | fat-fish 的 `QQPlugin`/`QQAdapter` 逻辑 |
+| 文本分句发送 | `split_for_sending` 按句拆分 + 发送限速 | ✅ 按句拆分（含表情包图片/中文表情名）+ 分片 `send_msg` + `sendIntervalMs` 间隔限速 | 单条仍超 `maxMessageBytes` 再按字节硬切 |
+| 草稿-确认门 | — | ✅ 增量吸收 | `qq_send` 起草 + `qq_confirm_send` 确认 |
+| 控制台面板 | — | ✅ 增量吸收 | 连接/监听名单/实时事件流 |
+| 环境提示词 | — | ✅ 增量吸收 | `envPromptVars` + `ENV_PROMPT.md` |
+| 通知事件 | 撤回/退群等 | ✅ 增量吸收 | recall / member / poke / emoji |
+| 被动视觉(VLM) | — | ✅ 增量吸收（默认关） | 可选 OpenAI 兼容端点描述图片 |
+| 历史查询 | — | ✅ 增量吸收 | `qq_recent` / `qq_search` |
+
+## 连接模式
+
+- `reverse`（默认，fat-fish 风格）：本扩展开一个 WebSocketServer（配置 `wsHost`/`wsPort`/`wsPath`），在 NapCat 里把「反向 WebSocket」指向 `ws://<host>:<port><path>`，NapCat 主动连入。
+- `forward`（内置风格）：本扩展作为客户端，配置 `wsUrl` 指向 NapCat 暴露的 OneBot WebSocket 地址。
+
+两种模式走同一套帧处理：带 `echo` 的是 API 回包，带 `post_type` 的是事件。
+
+## 配置（`config.json` 的 `worlds.qqbot` 节）
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `enabled` | `false` | 启用本 world |
+| `mode` | `reverse` | `reverse` / `forward` |
+| `wsUrl` | `ws://127.0.0.1:3001` | 正向模式地址 |
+| `wsHost` / `wsPort` / `wsPath` | `0.0.0.0` / `8080` / `/onebot/v11` | 反向模式监听 |
+| `token` | `""` | OneBot access_token（两端一致；空=不校验） |
+| `groups` / `privates` | `[]` | 监听群号 / 私聊 QQ；`groups` 为空=接入全部群 |
+| `privateAggregationWindow` | `30000` | 私聊连续消息聚合窗口(ms) |
+| `maxMessageBytes` | `1500` | 长文本强制分片字节数 |
+| `deliverImageAttachments` | `true` | 图片作为模型附件（需模型支持图像） |
+| `vision.enabled` | `false` | 被动视觉描述图片（需配置 OPENROUTER_API_KEY） |
+| `vision.model` | `google/gemini-2.5-flash` | VLM 模型 |
+
+> 连接类参数（mode/地址/端口/token）改动后需**整机重启**生效；监听名单（groups/privates）同理。
+
+## 工具
+
+- `qq_send`：起草要发送的消息（群或私聊），返回草稿编号。**不会立即发送**。
+- `qq_confirm_send`：确认并真正发送草稿（带 `barrierAfter`，防止连续误发）。
+- `qq_recent`：查询某群/私聊最近消息。
+- `qq_search`：按关键词检索历史消息。
+
+## 控制台
+
+- **面板「监听名单」**：显示当前监听的群/私聊、成员数、最后消息时间。
+- **面板「实时事件」**：订阅并实时回放 QQ 消息与通知流。
+- **配置组「QQ · 连接与监听」**：在控制台编辑连接参数与监听名单（热保存，连接类需重启）。
+
+## 部署
+
+1. 把本目录装进部署副本：`Cortico/extensions/node_modules/cortico-world-qq/`（保留 `src/`、`package.json`）。
+2. `cd` 到该副本，`corepack pnpm install --prod` 安装 `ws` 依赖。
+3. 在部署的 `config.json` 写入：
+   ```json
+   { "worlds": { "qqbot": { "enabled": true, "mode": "reverse", "wsPort": 8080, "groups": [123456789] } } }
+   ```
+4. 整机重启 Cortico（`POST /api/run/restart` 或重启进程）。
+5. 在 NapCat 配置反向/正向 WebSocket 指向本扩展。
+
+## 已知限制 / 与原版的差异
+
+- 语音解码依赖系统 `ffmpeg`（best-effort）：缺失时语音仅以 `[语音]` 占位，不阻塞事件。
+- 合并转发展开、视频/文件等大二进制默认只做文本占位（不自动作为附件，避免撑爆上下文）。
+- 群成员名片为空时尝试补一次 `get_group_member_info`，但离线名片仍以 NapCat 推送为准。
+- 引用回复走实时 `get_msg`（与 fat-fish 一致），需要 NapCat 暴露该 API；引用库外消息也能正确拉取。
+- 表情包图片通过 `[表情包:文件名]` 发送，文件需放在 `emojiDir` 配置目录（默认 `<扩展>/emoji`）；文件缺失则该标记被丢弃，不报错。
+- 中文表情名（如 `[旺柴]`/`[笑哭]`）按 fat-fish 的 `FACE_MAP` 映射到 face id；未知方括号文本原样保留。
+- 被动视觉默认关闭；开启需自备 OpenAI 兼容（如 OpenRouter）Key 与可访问的图片 URL。

package/dist/console.js

@@ -0,0 +1,99 @@
+// src/console/client.ts
+function fmtClock(ts) {
+  const n = typeof ts === "number" ? ts : typeof ts === "string" ? Date.parse(ts) : NaN;
+  if (!Number.isFinite(n)) return "";
+  const d = new Date(n);
+  if (Number.isNaN(d.getTime())) return "";
+  const p = (x) => String(x).padStart(2, "0");
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+function fmtTime(ts) {
+  const n = typeof ts === "number" ? ts : typeof ts === "string" ? Date.parse(ts) : NaN;
+  if (!Number.isFinite(n)) return "\u2014";
+  const d = new Date(n);
+  if (Number.isNaN(d.getTime())) return "\u2014";
+  return `${d.getMonth() + 1}/${d.getDate()} ${fmtClock(n)}`;
+}
+var rosterPanel = {
+  async mount(ctx) {
+    const ui = ctx.ui;
+    const sheet = ui.sheet({ title: "\u76D1\u542C\u540D\u5355", en: "roster", desc: "\u5F53\u524D\u76D1\u542C\u7684\u7FA4\u804A\u4E0E\u79C1\u804A\uFF0C\u53CA\u6700\u8FD1\u6D88\u606F\u65F6\u95F4\u3002" });
+    let data;
+    try {
+      data = await ctx.invoke("getRoster");
+    } catch (err) {
+      sheet.body.appendChild(ui.msgline(`\u8BFB\u53D6\u76D1\u542C\u540D\u5355\u5931\u8D25: ${err.message}`, true));
+      ctx.root.append(sheet.el);
+      return;
+    }
+    data ?? (data = {});
+    const groups = data.groups ?? [];
+    const privates = data.privates ?? [];
+    const convs = data.convs ?? [];
+    const bar = ui.rowbar();
+    bar.append(
+      ui.pill(`\u672C\u53F7 ${data.selfId ?? "?"}`, "plain"),
+      ui.pill(`\u6A21\u5F0F ${data.mode ?? "?"}`, "plain"),
+      ui.pill(`\u7FA4 ${groups.length}`, "plain"),
+      ui.pill(`\u79C1\u804A ${privates.length}`, "plain")
+    );
+    sheet.body.append(bar);
+    if (convs.length === 0) {
+      sheet.body.append(ui.placeholder("\u8FD8\u6CA1\u6709\u4EFB\u4F55\u4F1A\u8BDD\u3002\u8BA9 bot \u6536\u5230\u6D88\u606F\u6216\u628A\u5B83\u52A0\u5165\u76D1\u542C\u540D\u5355\u540E\uFF0C\u8FD9\u91CC\u4F1A\u51FA\u73B0\u8BB0\u5F55\u3002"));
+    } else {
+      const table = ui.table({
+        head: ["\u7C7B\u578B", "\u540D\u79F0", "\u8D26\u53F7", "\u4EBA\u6570", "\u5DF2\u6FC0\u6D3B", "\u6700\u8FD1\u6D88\u606F"],
+        maxHeight: "calc(100vh - 320px)"
+      });
+      for (const c of convs) {
+        const kindLabel = c.kind === "group" ? "\u7FA4" : c.kind === "private" ? "\u79C1\u804A" : String(c.kind);
+        table.addRow([
+          kindLabel,
+          c.label ?? "",
+          String(c.address),
+          String(c.members ?? 0),
+          c.active ? "\u662F" : "\u5426",
+          fmtTime(c.lastMessageAt)
+        ]);
+      }
+      sheet.body.append(table.el);
+    }
+    ctx.root.append(sheet.el);
+  }
+};
+var eventsPanel = {
+  mount(ctx) {
+    const ui = ctx.ui;
+    const sheet = ui.sheet({ title: "\u5B9E\u65F6\u4E8B\u4EF6", en: "events", desc: "QQ \u6D88\u606F\u4E0E\u901A\u77E5\u7684\u5B9E\u65F6\u6D41\uFF08\u542B\u6700\u8FD1 20 \u6761\u56DE\u653E\uFF09\u3002" });
+    const log = ui.log({ variant: "conversation", empty: "\u7B49\u5F85\u4E8B\u4EF6\u2026" });
+    sheet.body.append(log.el);
+    const handle = ctx.stream({
+      open() {
+        log.append("\u5DF2\u8FDE\u63A5\u4E8B\u4EF6\u901A\u9053", "dim");
+      },
+      message(raw) {
+        let f;
+        try {
+          f = JSON.parse(raw);
+        } catch {
+          log.append(raw, "dim");
+          return;
+        }
+        const sign = f.type?.endsWith(".recall") ? "\u21A9" : f.type === "qq.message" ? "\u2190" : "\xB7";
+        const tone = f.type?.endsWith(".recall") ? "warn" : "plain";
+        const line = `${fmtClock(f.ts)} ${sign} ${f.senderKey ?? ""}: ${f.text ?? ""}`.trim();
+        log.append(line, tone);
+      },
+      close(willRetry) {
+        log.append(willRetry ? "\u4E8B\u4EF6\u901A\u9053\u65AD\u5F00\uFF0C\u91CD\u8FDE\u4E2D\u2026" : "\u4E8B\u4EF6\u901A\u9053\u5DF2\u5173\u95ED", willRetry ? "warn" : "dim");
+      }
+    });
+    ctx.root.append(sheet.el);
+    return ctx.own(handle);
+  }
+};
+var bundle = { panels: { roster: rosterPanel, events: eventsPanel } };
+var client_default = bundle;
+export {
+  client_default as default
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "cortico-world-qq-better",
+  "version": "0.1.0",
+  "description": "Cortico world extension: QQ (OneBot v11 / NapCat) adapter ported from fat-fish qq_bot runtime, with both reverse and forward WebSocket modes and incremental Cortico-built-in features (draft-confirm gate, console, env prompt, notices, optional vision).",
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "ENV_PROMPT.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "cortico-world",
+    "qq",
+    "onebot",
+    "napcat"
+  ],
+  "cortico": {
+    "kind": "world",
+    "api": 5,
+    "label": "QQ_bot",
+    "consoleClient": "dist/console.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc --noEmit -p tsconfig.json",
+    "build:console": "node scripts/build-console.mjs",
+    "test": "node --test tests/normalize.test.ts tests/config.test.ts"
+  }
+}

package/src/config.ts

@@ -0,0 +1,173 @@
+import type { ConfigGroup } from 'cortico/core/types.ts';
+import type { WorldSection } from 'cortico/world.ts';
+
+/** fat-fish qq_bot 的关键参数 + Cortico 内置 world 的可选项，统一为一份配置。 */
+export interface QQWorldConfig {
+  /** 连接模式：reverse=Cortico 开 WS 服务端等 NapCat 连（fat-fish 风格）；forward=Cortico 连 NapCat 的 wsUrl（内置风格）。 */
+  mode: 'reverse' | 'forward';
+  /** forward 模式：NapCat 暴露的 WebSocket 地址。 */
+  wsUrl: string;
+  /** reverse 模式：Cortico 在哪个 host/port/path 监听 NapCat 反向连接。 */
+  wsHost: string;
+  wsPort: number;
+  wsPath: string;
+  /** NapCat 接入 Token（OneBot access_token），二选一生效。 */
+  token: string;
+  /** 监听中的群（fat-fish 的 GROUP_WHITELIST / 内置的 activeGroupIds）。 */
+  groups: number[];
+  /** 监听中的私聊对方 QQ（activePrivatePeers）。 */
+  privates: number[];
+  /** 私聊聚合窗口（ms），fat-fish PRIVATE_AGGREGATION_WINDOW。 */
+  privateAggregationWindow: number;
+  /** 连续消息最大间隔（ms），超出视为新主题（fat-fish MAX_SEQUENCE_GAP）。 */
+  maxSequenceGap: number;
+  /** 引用回看窗口（秒），fat-fish REPLY_MAX_GAP_SEC。 */
+  replyMaxGapSec: number;
+  /** 长文本按此字节数强制分句（fat-fish IMAGE_URL_MAX_CHARS 思路复用）。 */
+  maxMessageBytes: number;
+  /** 合并转发消息最多展开条数。 */
+  forwardExpandLimit: number;
+  /** 本地表情包图片目录（相对扩展或绝对路径），供发送 `[表情包:文件名]` 标记使用。 */
+  emojiDir: string;
+  /** 是否把图片作为附件交给模型（需要模型支持图像）。 */
+  deliverImageAttachments: boolean;
+  /** 发送时按句拆分多条（fat-fish SPLIT_REPLY_BY_SENTENCE）。 */
+  splitReplyBySentence: boolean;
+  /** 每条消息最多容纳句数（fat-fish SENTENCES_PER_MESSAGE）。 */
+  sentencesPerMessage: number;
+  /** 逐条发送之间的间隔毫秒（fat-fish SEND_INTERVAL_SECONDS），0 表示不限速。 */
+  sendIntervalMs: number;
+  /** 被动视觉：自动用 VLM 描述图片（off 则不调用外部 API，仅留占位）。 */
+  vision: {
+    enabled: boolean;
+    endpoint: string;
+    apiKeySecret: string;
+    model: string;
+    maxConcurrent: number;
+    maxBytes: number;
+    timeoutMs: number;
+  };
+  /** 时区，用于时间戳与 env 提示。 */
+  timezone: string;
+}
+
+export const QQ_DEFAULTS: QQWorldConfig = {
+  mode: 'reverse',
+  wsUrl: 'ws://127.0.0.1:3001',
+  wsHost: '0.0.0.0',
+  wsPort: 8080,
+  wsPath: '/onebot/v11/ws',
+  token: '',
+  groups: [],
+  privates: [],
+  privateAggregationWindow: 0,
+  maxSequenceGap: 8000,
+  replyMaxGapSec: 600,
+  maxMessageBytes: 1500,
+  forwardExpandLimit: 20,
+  emojiDir: 'emoji',
+  deliverImageAttachments: true,
+  splitReplyBySentence: true,
+  sentencesPerMessage: 1,
+  sendIntervalMs: 600,
+  vision: {
+    enabled: false,
+    endpoint: 'https://openrouter.ai/api/v1',
+    apiKeySecret: 'OPENROUTER_API_KEY',
+    model: 'google/gemini-2.5-flash',
+    maxConcurrent: 3,
+    maxBytes: 8_000_000,
+    timeoutMs: 30000,
+  },
+  timezone: 'Asia/Shanghai',
+};
+
+export const QQ_SECRETS = ['QQ_ACCESS_TOKEN', 'OPENROUTER_API_KEY'];
+
+/** worlds.qq 配置段：业务参数 + 必需的 enabled 开关。 */
+export type QQConfigSection = QQWorldConfig & WorldSection;
+
+export function qqDefaults(): QQConfigSection {
+  return { ...QQ_DEFAULTS, enabled: false };
+}
+
+/** 控制台可编辑的连接/监听配置组（JSON Schema 形态）。 */
+export const QQ_CONFIG_GROUP: ConfigGroup = {
+  id: 'world:qqbot',
+  owner: 'world:qqbot',
+  schema: {
+    type: 'object',
+    title: 'QQ · 连接与监听',
+    description: 'OneBot v11 / NapCat 连接参数与监听名单；连接类改动需重启生效。',
+    properties: {
+      'worlds.qqbot.mode': {
+        type: 'string',
+        title: '连接模式',
+        enum: ['reverse', 'forward'],
+        'x-hot': false,
+        description: 'reverse=Cortico 开 WS 服务端等 NapCat 反向连（fat-fish 风格）；forward=Cortico 主动连 NapCat 的 wsUrl。',
+      },
+      'worlds.qqbot.wsUrl': { type: 'string', title: '正向 WS 地址', 'x-hot': false },
+      'worlds.qqbot.wsHost': { type: 'string', title: '反向监听地址', 'x-hot': false },
+      'worlds.qqbot.wsPort': { type: 'integer', title: '反向监听端口', minimum: 1, maximum: 65535, 'x-hot': false },
+      'worlds.qqbot.wsPath': { type: 'string', title: '反向监听路径', 'x-hot': false },
+      'worlds.qqbot.token': { type: 'string', title: 'OneBot Token', 'x-hot': false },
+      'worlds.qqbot.groups': { type: 'array', title: '监听群', items: { type: 'integer' }, 'x-hot': true, description: '监听的群号列表；改完即时生效，不用重启。' },
+      'worlds.qqbot.privates': { type: 'array', title: '监听私聊', items: { type: 'integer' }, 'x-hot': true, description: '监听的私聊对方 QQ 号；改完即时生效，不用重启。' },
+      'worlds.qqbot.deliverImageAttachments': { type: 'boolean', title: '图片作为模型附件', 'x-hot': true },
+      'worlds.qqbot.emojiDir': { type: 'string', title: '表情包目录', 'x-hot': false, description: '本地表情包图片目录（相对扩展或绝对路径），供发送 [表情包:文件名] 标记。' },
+      'worlds.qqbot.splitReplyBySentence': { type: 'boolean', title: '按句拆分发送', 'x-hot': true, description: '开启后回复按句标拆成多条消息（对齐 fat-fish）。' },
+      'worlds.qqbot.sentencesPerMessage': { type: 'integer', title: '每条句数', minimum: 1, maximum: 10, 'x-hot': true },
+      'worlds.qqbot.sendIntervalMs': { type: 'integer', title: '发送间隔(ms)', minimum: 0, maximum: 5000, 'x-hot': true, description: '逐条发送之间的间隔，0 表示不限速。' },
+      'worlds.qqbot.vision.enabled': { type: 'boolean', title: '开启辅助视觉', 'x-hot': false },
+      'worlds.qqbot.vision.model': { type: 'string', title: 'VLM 模型', 'x-hot': false },
+    },
+  },
+};
+
+/**
+ * 原地补全缺省值并保持对象身份：让 World 持有的 this.config 就是 ctx.cfg 的同一引用，
+ * 这样控制台的 x-hot 配置改动（groups / privates / 发送节奏等）能即时对 World 生效，无需重启。
+ */
+export function normalizeConfig(raw: QQConfigSection): QQWorldConfig {
+  const c = raw as unknown as QQWorldConfig & Record<string, unknown>;
+  for (const [k, v] of Object.entries(QQ_DEFAULTS)) {
+    if (c[k] === undefined) c[k] = v;
+  }
+  c.groups = Array.isArray(c.groups) ? c.groups.map(Number).filter(Number.isFinite) : [];
+  c.privates = Array.isArray(c.privates) ? c.privates.map(Number).filter(Number.isFinite) : [];
+  if (typeof c.privateAggregationWindow !== 'number') c.privateAggregationWindow = QQ_DEFAULTS.privateAggregationWindow;
+  if (typeof c.maxSequenceGap !== 'number') c.maxSequenceGap = QQ_DEFAULTS.maxSequenceGap;
+  if (typeof c.replyMaxGapSec !== 'number') c.replyMaxGapSec = QQ_DEFAULTS.replyMaxGapSec;
+  if (typeof c.maxMessageBytes !== 'number') c.maxMessageBytes = QQ_DEFAULTS.maxMessageBytes;
+  if (typeof c.forwardExpandLimit !== 'number') c.forwardExpandLimit = QQ_DEFAULTS.forwardExpandLimit;
+  if (typeof c.splitReplyBySentence !== 'boolean') c.splitReplyBySentence = true;
+  if (typeof c.sentencesPerMessage !== 'number') c.sentencesPerMessage = 1;
+  if (typeof c.sendIntervalMs !== 'number') c.sendIntervalMs = QQ_DEFAULTS.sendIntervalMs;
+  if (typeof c.deliverImageAttachments !== 'boolean') c.deliverImageAttachments = QQ_DEFAULTS.deliverImageAttachments;
+  if (typeof c.emojiDir !== 'string' || !c.emojiDir) c.emojiDir = QQ_DEFAULTS.emojiDir;
+  if (typeof c.timezone !== 'string' || !c.timezone) c.timezone = QQ_DEFAULTS.timezone;
+  if (typeof c.mode !== 'string') c.mode = 'reverse';
+  if (typeof c.token !== 'string') c.token = '';
+  if (typeof c.wsUrl !== 'string') c.wsUrl = QQ_DEFAULTS.wsUrl;
+  if (typeof c.wsHost !== 'string') c.wsHost = QQ_DEFAULTS.wsHost;
+  if (typeof c.wsPort !== 'number') c.wsPort = QQ_DEFAULTS.wsPort;
+  if (typeof c.wsPath !== 'string') c.wsPath = QQ_DEFAULTS.wsPath;
+  // vision 子对象原地合并，保持引用身份（x-hot 生效）
+  c.vision = c.vision ?? {};
+  Object.assign(c.vision, { ...QQ_DEFAULTS.vision, ...(c.vision as object) });
+  return c;
+}
+
+export function parseNumberSeq(v: unknown): number[] {
+  if (Array.isArray(v)) return v.map((x) => Number(x)).filter((x) => Number.isFinite(x));
+  if (typeof v === 'string') {
+    return v
+      .split(/[\s,;]+/)
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map((s) => Number(s))
+      .filter((n) => Number.isFinite(n));
+  }
+  return [];
+}

package/src/console/client.ts

@@ -0,0 +1,193 @@
+// QQ 扩展控制台面板 bundle（浏览器端，ESM）。
+// 自包含类型，不 import cortico/*，便于 esbuild 独立打包（框架只要求 default 导出 ConsoleClientBundle）。
+
+interface ConsoleUi {
+  sheet(opts: { title: string; en?: string; desc?: string }): {
+    el: HTMLElement;
+    body: HTMLElement;
+    note: HTMLElement;
+    desc: HTMLElement | null;
+  };
+  rowbar(): HTMLDivElement;
+  pill(text: string, tone?: string): HTMLSpanElement;
+  placeholder(text: string): HTMLDivElement;
+  msgline(text?: string, bad?: boolean): HTMLDivElement;
+  table(opts?: { head?: readonly string[]; maxHeight?: string }): {
+    el: HTMLDivElement;
+    body: HTMLTableSectionElement;
+    addRow(cells: readonly (string | number | null | undefined | HTMLElement)[]): HTMLTableRowElement;
+    clear(empty?: string): void;
+  };
+  log(opts?: {
+    variant?: string;
+    max?: number;
+    maxHeight?: string;
+    empty?: string;
+  }): {
+    el: HTMLElement;
+    append(line: string, tone?: string): HTMLDivElement;
+    clear(): void;
+    count: number;
+    stuck: boolean;
+    scrollToEnd(): void;
+  };
+}
+
+interface ConsolePanelContext {
+  pageId: string;
+  panelId: string;
+  language: string;
+  root: HTMLElement;
+  signal: AbortSignal;
+  invoke<T = unknown>(method: string, args?: unknown[]): Promise<T>;
+  stream(handlers: {
+    message: (text: string) => void;
+    open?: () => void;
+    close?: (willRetry: boolean) => void;
+  }): { dispose(): void };
+  own<T>(d: T): T;
+  ui: ConsoleUi;
+}
+
+interface ConsolePanel {
+  mount(ctx: ConsolePanelContext): unknown;
+}
+
+interface ConsoleClientBundle {
+  panels: Record<string, ConsolePanel>;
+}
+
+interface RosterConv {
+  address: string;
+  label?: string | null;
+  kind: 'group' | 'private' | string;
+  active?: boolean;
+  members?: number;
+  lastMessageAt?: string | null;
+}
+
+interface RosterResult {
+  selfId?: string | number | null;
+  mode?: string;
+  groups?: number[];
+  privates?: number[];
+  convs?: RosterConv[];
+}
+
+interface EventFrame {
+  ts?: number;
+  type?: string;
+  senderKey?: string | null;
+  text?: string | null;
+}
+
+function fmtClock(ts: unknown): string {
+  const n = typeof ts === 'number' ? ts : typeof ts === 'string' ? Date.parse(ts) : NaN;
+  if (!Number.isFinite(n)) return '';
+  const d = new Date(n);
+  if (Number.isNaN(d.getTime())) return '';
+  const p = (x: number) => String(x).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+function fmtTime(ts: unknown): string {
+  const n = typeof ts === 'number' ? ts : typeof ts === 'string' ? Date.parse(ts) : NaN;
+  if (!Number.isFinite(n)) return '—';
+  const d = new Date(n);
+  if (Number.isNaN(d.getTime())) return '—';
+  return `${d.getMonth() + 1}/${d.getDate()} ${fmtClock(n)}`;
+}
+
+const rosterPanel: ConsolePanel = {
+  async mount(ctx) {
+    const ui = ctx.ui;
+    const sheet = ui.sheet({ title: '监听名单', en: 'roster', desc: '当前监听的群聊与私聊，及最近消息时间。' });
+
+    let data: RosterResult;
+    try {
+      data = await ctx.invoke<RosterResult>('getRoster');
+    } catch (err) {
+      sheet.body.appendChild(ui.msgline(`读取监听名单失败: ${(err as Error).message}`, true));
+      ctx.root.append(sheet.el);
+      return;
+    }
+    data ??= {};
+    const groups = data.groups ?? [];
+    const privates = data.privates ?? [];
+    const convs = data.convs ?? [];
+
+    const bar = ui.rowbar();
+    bar.append(
+      ui.pill(`本号 ${data.selfId ?? '?'}`, 'plain'),
+      ui.pill(`模式 ${data.mode ?? '?'}`, 'plain'),
+      ui.pill(`群 ${groups.length}`, 'plain'),
+      ui.pill(`私聊 ${privates.length}`, 'plain'),
+    );
+    sheet.body.append(bar);
+
+    if (convs.length === 0) {
+      sheet.body.append(ui.placeholder('还没有任何会话。让 bot 收到消息或把它加入监听名单后，这里会出现记录。'));
+    } else {
+      const table = ui.table({
+        head: ['类型', '名称', '账号', '人数', '已激活', '最近消息'],
+        maxHeight: 'calc(100vh - 320px)',
+      });
+      for (const c of convs) {
+        const kindLabel = c.kind === 'group' ? '群' : c.kind === 'private' ? '私聊' : String(c.kind);
+        table.addRow([
+          kindLabel,
+          c.label ?? '',
+          String(c.address),
+          String(c.members ?? 0),
+          c.active ? '是' : '否',
+          fmtTime(c.lastMessageAt),
+        ]);
+      }
+      sheet.body.append(table.el);
+    }
+
+    ctx.root.append(sheet.el);
+  },
+};
+
+const eventsPanel: ConsolePanel = {
+  mount(ctx) {
+    const ui = ctx.ui;
+    const sheet = ui.sheet({ title: '实时事件', en: 'events', desc: 'QQ 消息与通知的实时流（含最近 20 条回放）。' });
+
+    const log = ui.log({ variant: 'conversation', empty: '等待事件…' });
+    sheet.body.append(log.el);
+
+    const handle = ctx.stream({
+      open() {
+        log.append('已连接事件通道', 'dim');
+      },
+      message(raw) {
+        let f: EventFrame;
+        try {
+          f = JSON.parse(raw) as EventFrame;
+        } catch {
+          log.append(raw, 'dim');
+          return;
+        }
+        const sign = f.type?.endsWith('.recall')
+          ? '↩'
+          : f.type === 'qq.message'
+            ? '←'
+            : '·';
+        const tone = f.type?.endsWith('.recall') ? 'warn' : 'plain';
+        const line = `${fmtClock(f.ts)} ${sign} ${f.senderKey ?? ''}: ${f.text ?? ''}`.trim();
+        log.append(line, tone);
+      },
+      close(willRetry) {
+        log.append(willRetry ? '事件通道断开，重连中…' : '事件通道已关闭', willRetry ? 'warn' : 'dim');
+      },
+    });
+
+    ctx.root.append(sheet.el);
+    return ctx.own(handle);
+  },
+};
+
+const bundle: ConsoleClientBundle = { panels: { roster: rosterPanel, events: eventsPanel } };
+export default bundle;

package/src/definition.ts

@@ -0,0 +1,12 @@
+import type { WorldDefinition } from 'cortico/world.ts';
+import { QQWorld } from './world.ts';
+import { qqDefaults, type QQConfigSection } from './config.ts';
+
+export const definition: WorldDefinition<QQConfigSection> = {
+  id: 'qqbot',
+  label: 'QQ 群聊',
+  defaults: qqDefaults,
+  create(ctx) {
+    return new QQWorld(ctx.cfg, ctx.packageDir, ctx.dataDir);
+  },
+};