@zhin.js/adapter-qq 5.0.2 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @zhin.js/adapter-qq
 
+## 6.0.0
+
+### Minor Changes
+
+- 3ea88d8: 恢复 legacy 的聊天命令添加 endpoint 能力（随适配器发布）：`qq endpoint add [name]`（手机 QQ 扫码绑定 → 凭据写 `.env` 的 `QQ_<NAME>_APPID/SECRET` → 追加 `plugins.qq.endpoints` 配置，重启生效）、`qq endpoint cancel`（中止绑定）、`qq endpoint list`（运行中 + 配置内 endpoints）、`qq endpoint remove <name>`（移除配置项）。add/cancel/remove 受 `master` 限制（顶层或 `endpoints[i]` 声明时仅 master 可执行，未配置则放行）；schema 新增顶层共享字段 `master`。绑定协议（create_bind_task / poll_bind_result / AES-256-GCM 解密）自 legacy 移植，二维码当前以链接文本下发（QQ 出站富媒体待迁移）。
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- e5c84ed: Adapter 多账号：插件实例 config 支持 `endpoints: [{name, ...覆盖}]` 数组，`expandEndpointConfigs` 将一个实例展开为多个 endpoint record（id 为 `<slotId>~<name>`，顶层字段共享、逐项覆盖），替代多 `instanceKey` 方案；Console `/api/plugins` 收敛为一个插件卡片 + 多 endpoint。icqq / qq schema 与 README 补 `endpoints` 配置。
+
+  Plugin Runtime Console Host：补 `/esm/*` React/router ESM 代理路由（legacy `consoleApiRouter` 对齐），TypeScriptClientBuilder 裸导入改写为 `/esm/<enc>.mjs`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+  - @zhin.js/command@1.0.2
+
+## 5.0.3
+
+### Patch Changes
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- 447f3e2: 迁移缺口修复（legacy 功能对齐）：
+
+  - html 段出站规范化：经 `@zhin.js/html-renderer` 渲染为 image 段（sandbox 豁免、无渲染器时降级文本），修复真实平台 `[object Object]`。
+  - 群聊 @ 触发 AI：适配器入站标注 `metadata.mentioned`（icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori），`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords（默认值与 legacy 对齐）。
+  - im_transcripts 全量流水恢复写入（chat_history 工具可用）；群聊旁听上下文回迁。
+  - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效；masters/trusted 角色解析对齐 legacy。
+  - `Message.sender` 统一为用户 ID（onebot11/12、napcat、milky 原误传显示名）；quote_id 经 metadata 接入 AI 引用上下文。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - @zhin.js/host-http@1.0.1
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
 ## 5.0.2
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,15 @@
 # @zhin.js/adapter-qq
 
-Zhin.js QQ 官方机器人适配器，基于 QQ 官方机器人 API 开发，支持频道、群聊和私聊消息。
+Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 **WebSocket Gateway**（`qq-official-bot`）收发消息（无需 host-router / host-http）。
+
+## 功能
+
+- WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
+- 解析私聊 / 群 / 频道消息
+- 出站 `send({ target, payload })` → QQ API（`private:` / `group:` / `channel:` / `direct:`）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- Webhook / middleware 模式已实现（经 `httpHostToken` 注册 POST 路由）
+- AI `@` 触发标注：群消息（GROUP_AT_MESSAGE_CREATE 仅 @ 时下发）与频道 `mentions[].bot` 会在入站 metadata 标 `mentioned: true`（新 Plugin Runtime 纯文本 content 经 metadata 传递 @）
 
 ## 安装
 
@@ -8,444 +17,101 @@ Zhin.js QQ 官方机器人适配器，基于 QQ 官方机器人 API 开发，支
 pnpm add @zhin.js/adapter-qq
 ```
 
-## 扫码添加机器人（/endpoint）
-
-无需手动复制 AppID/AppSecret：在 IM 中由 **master / trusted** 操作员发送命令，适配器会内联调用 QQ 开放平台绑定协议（等价 `@tencent-connect/qqbot-connector`，**不依赖**该 npm 包），扫码成功后：
-
-- 凭据写入项目根 **`.env`**（键名 `QQ_<name>_APPID` / `QQ_<name>_SECRET`）
-- `zhin.config.yml` 仅保留 **`${...}` 引用**（与脚手架其它 adapter 一致）
-- **`master`** 与 **`aiAccess.users`** 自动设为 `poll_bind_result` 返回的扫码者 OpenID（接口无该字段时回退为发起命令的用户 ID）
-
-| 命令 | 说明 |
-|------|------|
-| `/endpoint add qq [name]` | 发起扫码绑定；`name` 默认使用 AppID |
-| `/endpoint sync` | 将内存 endpoint 写回 `zhin.config.yml` |
-| `/endpoint cancel` | 取消进行中的绑定 |
-| `/endpoints` | 查看运行时 qq endpoints 在线状态 |
-| `/endpoint help` | Endpoint 管理帮助 |
-
-二维码通过 IM `$reply` 发送 `segment.qrcode(url)`；各 Adapter 在 **`$sendMessage`** 内解析该段（IM → `image`，process → 终端 ASCII，GitHub 等 → 文本链接）。
-
-二维码渲染使用 core 的 `segment.qrcode` / `GeneratedQrCode`（`import { segment } from 'zhin.js'` 或 `import { GeneratedQrCode } from 'zhin.js/qrcode'`）。
-
-## AIGC 合规（AI 白名单）
-
-QQ 开放平台限制 AIGC 进入社群场景、禁止面向全量用户开放生成式能力。请配置 **`endpoints[].aiAccess`**（推荐）或全局 **`ai.access`**，仅 gate LLM 回复；斜杠命令、游戏插件等不受影响。
-
-```yaml
-endpoints:
-  - context: qq
-    name: my-bot
-    appid: ...
-    secret: ...
-    aiAccess:
-      mode: whitelist
-      users: ['QQ用户openid']
-      groups: ['QQ群openid']
-      denyMessage: 当前未开放 AI，请联系管理员。
-```
-
-多 Endpoint 时可分别设置（例如正式服 `whitelist`、沙箱 `open`）。未写 `endpoints[].aiAccess` 时回退到全局 `ai.access`。
-
-- 群/频道未放行：**静默**（不回复 AI）
-- 私聊未放行：回复 `denyMessage`
-- 白名单：`users` 与 `groups` **OR** 匹配
-
-详见 [内容审查 / AI Access Gate](../../../docs/advanced/content-moderation.md)。
-
-## 配置
-
-### 基础配置
-
-```typescript
-import { defineConfig } from 'zhin.js';
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'qq',
-      name: 'my-qq-bot',
-      appid: process.env.QQ_APPID,
-      secret: process.env.QQ_SECRET,
-      mode: 'middleware',
-      application: 'koa',
-      webhookPath: '/qq/webhook',
-      sandbox: true,
-      data_dir: './data',
-    },
-  ],
-  plugins: [
-    '@zhin.js/adapter-qq',
-  ],
-})
-```
+## Plugin Runtime
 
-### 完整配置选项
-
-```typescript
-const config: QQEndpointConfig = {
-  context: 'qq',
-  name: 'my-qq-bot',
-  appid: 'YOUR_APPID',         // 机器人 AppID（必需，小写 appid）
-  secret: 'YOUR_SECRET',       // 机器人 Secret（必需）
-  mode: 'middleware',        // websocket | webhook | middleware（推荐挂 host-router）
-  application: 'koa',          // middleware 模式必填
-  webhookPath: '/qq/webhook', // middleware 回调路径（完整 URL: {host}:8086/qq/webhook，无 /api 前缀）
-  // mode: 'webhook',         // 独立 HTTP 端口模式
-  // port: 8087,
-  // path: '/qq/webhook',
-  platform: 'qq',              // 'qq' | 'qzone' 平台类型
-  intents: [                   // 事件订阅意图（qq-official-bot ^1.2 使用 GROUP_AND_C2C_EVENT）
-    'GROUP_AND_C2C_EVENT',     // QQ 群 @ 消息 + C2C 私聊（必需）
-    'GUILDS',
-    'GUILD_MEMBERS',
-    'GUILD_MESSAGES',          // 频道私域 @ 消息（公域用 PUBLIC_GUILD_MESSAGES）
-    'DIRECT_MESSAGE',
-    'PUBLIC_GUILD_MESSAGES',
-  ],
-  data_dir: './data',          // 数据目录（可选）
-  sandbox: false               // 是否为沙箱环境（可选）
-}
-```
+- `@zhin.js/adapter` — 约定式 `adapters/qq.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（WebSocket 路径）
 
-## 入站模式（二选一）
+入站：`gateway.receive({ adapter, target: 'group:…'|…, content, sender, metadata })`  
+出站：`send({ target, payload })` → `sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`
 
-| 模式 | 配置 | 说明 |
-|------|------|------|
-| **middleware**（推荐） | `mode: middleware` + `application: koa` + `webhookPath` | 挂在 `@zhin.js/host-router`，与 Host **同端口**（如 `8086`） |
-| **webhook**（独立端口） | `mode: webhook` + `port` + `path` | `qq-official-bot` 自建 HTTP 服务，需单独暴露端口 |
-| websocket | `mode: websocket` | 长连接，无需公网回调 |
+## 前置条件
 
-### 自定义网关（qq-official-bot ^1.2.2）
+| 要求 | 说明 |
+|------|------|
+| **AppID / Secret** | [QQ 开放平台](https://q.qq.com/) 创建机器人应用并获取 |
+| **WebSocket（默认）** | `qq-official-bot` 正向连接；无需公网回调 |
+| **host-http** | WebSocket **不需要**；Webhook / middleware 模式需要（经 `httpHostToken`） |
 
-经代理或私有部署时，可覆盖官方 token / gateway 接口：
+必填字段（`endpoints[i]`）：`name`、`appid`、`secret`。
 
-```yaml
-# WebSocket 入站：gatewayUrl 与 accessTokenUrl 均生效
-- context: qq
-  name: my-qq-bot
-  mode: websocket
-  appid: ${QQ_APPID}
-  secret: ${QQ_SECRET}
-  accessTokenUrl: https://your-proxy.example.com/app/getAppAccessToken
-  gatewayUrl: https://your-proxy.example.com/gateway/bot
-  intents:
-    - GROUP_AND_C2C_EVENT
-```
+## 最小配置
 
 ```yaml
-# middleware / webhook：仅 accessTokenUrl 影响出站鉴权（入站走 HTTP 回调，不用 gateway）
-- context: qq
-  name: my-qq-bot
-  mode: middleware
-  application: koa
-  webhookPath: /qq/webhook
-  accessTokenUrl: https://your-proxy.example.com/app/getAppAccessToken
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  qq:
+    # mode: websocket   # 默认
+    endpoints:
+      - name: my-qq-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
 ```
 
-- `gatewayUrl` 可为完整 URL 或相对路径（默认 `/gateway/bot`，相对 `api.sgroup.qq.com` baseURL）
-- 连接时日志会输出 `op: qq_gateway` 及实际使用的地址
-
-### middleware 回调地址（test-bot 默认）
-
-1. 确保 `plugins` 含 `@zhin.js/host-router`（test-bot 已启用）
-2. `zhin.config.yml` 示例见上文 `webhookPath: /qq/webhook`
-3. 在 [QQ 开放平台](https://q.qq.com/bot) → **开发 → 回调配置** 填写：
-
-   ```
-   https://<你的公网域名>/qq/webhook
-   ```
-
-   本地：`http://127.0.0.1:8086/qq/webhook`（经 ngrok / cloudflared 暴露公网即可）。
-
-   > **注意**：Host 的 Console/API 走 `/api/*`（如 `/api/stats`），但适配器 webhook 直接挂在 Router 根路径，**不要**加 `/api` 前缀；填 `/api/qq/webhook` 会命中 Bearer 鉴权，QQ 平台回调会 401。
-
-4. 勾选事件：**群事件**、**C2C 私聊**、**频道事件**（按需）
-5. 保存时平台会发 `SIGN_VERIFY` 签名校验，适配器会自动响应
-
-> Host 对含 `/webhook` 的路径**免 Bearer 鉴权**，由 QQ 的 `X-Signature-Ed25519` 验签。
-
-### webhook 独立端口
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
 
 ```yaml
-mode: webhook
-port: 8087
-path: /qq/webhook
-```
-
-回调填 `https://<域名>:8087/qq/webhook`（或反代到该端口）。
-
-## 获取配置信息
-
-### 1. 注册 QQ 机器人
-
-1. 访问 [QQ 开放平台](https://q.qq.com/bot)
-2. 登录并创建机器人应用
-3. 在「开发设置」中获取：
-   - **AppID**（配置字段 `appid`）: 机器人应用 ID
-   - **Secret**: 机器人密钥（`secret`）
-   - **Secret**: 机器人密钥
-
-### 2. 配置权限
-
-在机器人设置中：
-- 配置需要的事件订阅
-- 设置消息接收模式（公域/私域）
-- 添加频道/群聊白名单（如需要）
-
-### 3. 事件订阅（Intents）
-
-可订阅的事件类型：
-- `GUILDS` - 频道事件
-- `GUILD_MEMBERS` - 成员变动
-- `GUILD_MESSAGES` - 频道消息
-- `DIRECT_MESSAGE` - 私信消息
-- `GROUP_AND_C2C_EVENT` - QQ 群 @ 消息 + C2C 私聊（`GROUP_AT_MESSAGE_CREATE` / `C2C_MESSAGE_CREATE`）
-- `INTERACTION` - 互动事件
-
-## 使用示例
-
-### 基础消息处理
-
-```typescript
-import { addCommand, MessageCommand } from 'zhin.js'
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
+plugins:
+  qq:
+    mode: websocket
+    intents: [GUILDS, GROUP_AND_C2C_EVENT]
+    endpoints:
+      - name: main-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+      - name: second-bot
+        appid: ${QQ_APPID_2}
+        secret: ${QQ_SECRET_2}
 ```
 
-### 频道消息
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
 
-```typescript
-import { onMessage } from 'zhin.js'
-
-onMessage(async (message) => {
-  // 仅处理频道消息
-  if (message.$channel.type === 'channel') {
-    console.log(`频道消息：${message.$raw}`)
-  }
-})
-```
+## Endpoint 管理命令
 
-### 群聊消息
-
-```typescript
-import { onGroupMessage } from 'zhin.js'
-
-onGroupMessage(async (message) => {
-  console.log(`群聊消息来自：${message.$sender.name}`)
-  console.log(`消息内容：${message.$raw}`)
-})
-```
-
-### 私聊消息
-
-```typescript
-import { onPrivateMessage } from 'zhin.js'
-
-onPrivateMessage(async (message) => {
-  await message.$reply('收到你的私信了！')
-})
-```
-
-### 发送不同类型消息
-
-```typescript
-addCommand(new MessageCommand('card')
-  .action(async (message) => {
-    // 发送 Ark 模板卡片
-    return {
-      type: 'ark',
-      template_id: 23,
-      kv: [
-        { key: '#TITLE#', value: '标题' },
-        { key: '#DESC#', value: '描述' },
-        { key: '#PROMPT#', value: '提示' }
-      ]
-    }
-  })
-)
-
-addCommand(new MessageCommand('embed')
-  .action(async (message) => {
-    // 发送 Embed 消息
-    return {
-      type: 'embed',
-      title: 'Embed 标题',
-      prompt: '消息提示',
-      thumbnail: { url: 'https://example.com/image.png' },
-      fields: [
-        { name: '字段1', value: '值1' }
-      ]
-    }
-  })
-)
-```
+适配器自带 `qq endpoint` 命令组（聊天内直接使用，默认无前缀；受 `commandPrefix` 影响）：
 
-## 消息类型支持
-
-### 接收消息类型
-
-- ✅ 文本消息
-- ✅ @ 提及
-- ✅ 图片消息
-- ✅ 表情消息
-- ✅ Ark 模板消息
-- ✅ Embed 消息
-- ✅ Markdown 消息
-
-### 发送消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ Ark 模板消息
-- ✅ Embed 富文本消息
-- ✅ Markdown 消息
-- ✅ 消息引用（回复）
-
-### AI 出站 Markdown（默认开启）
-
-官方已支持全量 Markdown 后，适配器会在 `$sendMessage` 出站前自动把 AI 的纯文本段转为 `msg_type=2` 的 Markdown 消息（保留 leading `reply`）。配置项 `outboundMarkdown`：
-
-| 值 | 行为 |
-|---|---|
-| `auto`（默认） | 正文含 `**`、列表、代码块等 Markdown 语法时才转换 |
-| `true` | 纯文本也走 Markdown |
-| `false` | 始终发纯文本（与旧行为一致） |
-
-```yaml
-endpoints:
-  - context: qq
-    name: my-bot
-    outboundMarkdown: auto   # 或 true / false
-```
-
-含图片/文件等富媒体的多段消息不会合并，避免破坏分条发送。
-
-**图文混排**（文本 + 图片，典型如二维码说明 + `segment.qrcode`）会自动处理：
-
-| 图片类型 | 行为 |
-|---|---|
-| 公网 `https` URL | 合并为单条 Markdown（`msg_type=2`），图片用 `![说明 #宽 #高](url)` |
-| 内联 base64 / data URI（如二维码渲染） | 群聊/私聊先上传 `file_info`，再以 `msg_type=7` 图文混排同条发送 |
-
-`outboundMarkdown: false` 时关闭上述合并，恢复分条发送。
-
-## API 方法
-
-### 基础方法
-
-```typescript
-const endpoint = app.adapters.get('qq')?.endpoints.get('你的机器人ID')
-
-// 发送私信
-await endpoint.sendPrivateMessage(userId, '消息内容')
-
-// 发送群消息
-await endpoint.sendGroupMessage(groupId, '消息内容')
-
-// 发送频道消息
-await endpoint.sendGuildMessage(channelId, '消息内容')
-
-// 撤回消息
-await endpoint.$recallMessage(messageId)
-```
-
-## 消息 ID 格式
-
-本适配器使用特殊的消息 ID 格式来区分不同类型的消息：
-
-- 私信：`private-{userId}:{messageId}`
-- 群聊：`group-{groupId}:{messageId}`
-- 频道：`channel-{channelId}:{messageId}`
-- 私域频道：`direct-{guildId}:{messageId}`
-
-## 注意事项
-
-### 接收模式
-
-- **公域模式 (public)**: 仅接收 @ 机器人的消息
-- **私域模式 (private)**: 可接收频道内所有消息（需要申请权限）
-
-### 频率限制
-
-QQ 机器人有严格的频率限制：
-- 主动消息：每个用户每天 5 条
-- 被动消息（回复）：无限制
-- 建议在被动模式下使用（用户 @ 后回复）
-
-### 沙箱环境
-
-开发时可以使用沙箱环境测试：
-
-```typescript
-{
-  context: 'qq',
-  sandbox: true,  // 启用沙箱
-  // ...其他配置
-}
-```
-
-## 常见问题
-
-### Q: 机器人无法收到消息？
-
-A: 检查以下几点：
-1. AppID、Secret 是否正确；`intents` 必须含 **`GROUP_AND_C2C_EVENT`**（不是旧名 `GROUP_AT_MESSAGE_CREATE`）
-2. **沙箱环境**：在 [QQ 开放平台](https://q.qq.com/bot) → 开发设置 → 沙箱配置，把测试 **QQ 群** 加入沙箱白名单（私聊能通不代表群已配置）
-3. 机器人是否已被拉入该 QQ 群（日志应出现 `qq notice group.add_robot`）
-4. 群管理员是否在机器人资料页 **开启消息接收**（`qq notice group.msg_receive_open`）；若出现 `group.msg_receive_close` 则群聊不会推送
-5. 公域/群聊场景必须 **@ 机器人** 才会推送（`GROUP_AT_MESSAGE_CREATE`）
-6. **QQ 频道** 与 **QQ 群** 是两套事件：频道 @ 需要 `GUILD_MESSAGES` 或 `PUBLIC_GUILD_MESSAGES`，不是 `GROUP_AND_C2C_EVENT`
-
-### Q: Typing Indicator 群聊报 `40034105 主动消息失败, 无权限`？
-
-A: QQ **群聊**不允许无引用的主动消息。框架已对 QQ 群场景的「正在处理中…」自动附带 `reply` 引用触发消息；若仍失败，可在 Endpoint 配置中关闭群聊 typing：
-
-```yaml
-typingIndicator:
-  enabled: true
-  groupConfig:
-    type: none
-```
-
-### Q: 发送消息失败？
+| 命令 | 说明 |
+|------|------|
+| `qq endpoint add [name]` | 手机 QQ 扫码绑定：下发二维码链接 → 确认后凭据写入 `.env`（`QQ_<NAME>_APPID/SECRET`），并追加 `plugins.qq.endpoints`（重启生效） |
+| `qq endpoint cancel` | 取消进行中的扫码绑定（同时只允许一个流程） |
+| `qq endpoint list` | 列出运行中与配置中的 endpoints |
+| `qq endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |
 
-A: 可能的原因：
-1. 超过主动消息频率限制
-2. 没有对应频道/群的发送权限
-3. 消息格式不符合规范
-4. Token 已过期或失效
+add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i]`）时仅
+master 可执行；未配置则放行（首个扫码绑定者即 owner）。二维码当前以链接文本下发
+（出站富媒体待迁移），用手机 QQ 打开链接即可扫码。
 
-### Q: 如何处理不同平台？
+## 环境变量
 
-A: 使用 `platform` 配置：
-- `qq`: QQ 频道和群聊
-- `qzone`: QQ 空间（如支持）
+| 变量 | 说明 |
+|------|------|
+| `QQ_APPID` / `QQ_BOT_APPID` | 应用 AppID |
+| `QQ_SECRET` / `QQ_BOT_SECRET` | 应用 Secret |
+| `QQ_BOT_NAME` | 可选，默认 endpoint 名 |
 
-## 相关链接
+## Webhook / middleware
 
-- [QQ 开放平台](https://q.qq.com/bot)
-- [QQ 机器人开发文档](https://bot.q.qq.com/wiki/)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
+`mode: webhook` 或 `mode: middleware` 经 `httpHostToken` 注册 POST 路由（默认 `/qq/webhook`），使用 qq-official-bot Middleware 接收器验签并入站；出站仍走 QQ HTTP API。Host 需注入 `httpHostToken`。
 
-## AI 工具
+## AI 工具（Skill）
 
 | 类别 | 路径 |
 |------|------|
 | Permit 词汇 | `agent/PERMITS.md` |
-| 平台工具（8 个） | `agent/tools/`（`qq_*`：公会、频道、角色等） |
+| 平台工具 | `agent/tools/`（频道、角色等） |
 | 技能说明 | `agent/skills/qq.md` |
-| 群管标准工具 | `createSceneManagementTools()` |
 
+## 平台权限（platform permit）
 
-## 许可证
+platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；`@zhin.js/tool` descriptor 保留 `platforms` / `scopes` / `permissions`，CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 执行门禁。
 
-MIT License
+## 迁移后出站能力变化
 
-## 贡献
+迁移到 Plugin Runtime 后，出站统一经 `messageGatewayToken` 渲染为文本后发送（`sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`）。旧 Adapter 的富媒体出站能力（图片 / 语音 / 视频、keyboard 按钮、markdown 模板等）暂未迁移，当前出站等价于纯文本。如需富媒体，可通过 endpoint 的 QQ API 封装或直接调用 QQ HTTP API 作为逃生舱。
 
-欢迎提交 Issue 和 Pull Request！
+## 许可证
+
+MIT License

package/adapters/qq.ts

@@ -0,0 +1,51 @@
+/**
+ * Convention entry: discover `adapters/qq.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from '../src/endpoint.js';
+import {
+  resolveQqConfig,
+  type QqAdapterConfig,
+} from '../src/protocol.js';
+import { qqRuntimeStateToken } from '../src/qq-runtime-state.js';
+
+export {
+  QqHttpEndpoint,
+  QqWebsocketEndpoint,
+} from '../src/endpoint.js';
+export type {
+  CreateQqBot,
+  CreateQqHttpBot,
+  QqBotTransport,
+  QqEndpointOptions,
+  QqHttpBotTransport,
+  QqHttpEndpointOptions,
+} from '../src/endpoint.js';
+
+export default defineAdapter<QqAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    const config = resolveQqConfig(context.config);
+    const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
+    context.use(qqRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.mode,
+    });
+    if (config.mode === 'webhook' || config.mode === 'middleware') {
+      return new QqHttpEndpoint({
+        id: context.id,
+        gateway,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new QqWebsocketEndpoint({
+      id: context.id,
+      gateway,
+      config,
+    });
+  },
+});

package/agent/tools/add_role.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }>({
   description: '给成员添加 QQ 频道角色',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),