@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @zhin.js/adapter-qq
 
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+- Updated dependencies [2c3610a]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/host-http@1.1.12
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/agent-feature@1.1.11
+  - @zhin.js/skill@1.1.11
+  - @zhin.js/tool@1.1.13
+  - @zhin.js/permission@1.1.10
+
+## 1.1.18
+
+### Patch Changes
+
+- 6345a38: feat(adapters): add per-adapter Console pages
+
+  Every platform adapter now ships a `pages/index` Console page backed by a shared
+  `createAdapterConsolePage` component and `createAdapterConsoleRpc` server helper:
+
+  - See running endpoints, test connectivity, and manage
+    `plugins.<adapter>.endpoints` (add/remove writes `.env` references) from the
+    Console instead of chat commands.
+  - Surface LoginAssist pending tasks (QR / slider / SMS / device) so ICQQ login no
+    longer requires the terminal.
+  - QQ moves its QR binding flow (`qq endpoint add`) into Console actions with
+    public/private selection.
+  - Pages are permission-gated by `<adapter>:read`; writes need `<adapter>:write`.
+
+- ff3efe7: feat(adapters): notify masters when ICQQ or QQ goes offline and support ICQQ re-login
+
+  - Add an explicit `notify` target to ICQQ and QQ endpoint config: when the
+    transport goes offline or login fails, send a short notice through another
+    adapter instance's Endpoint via `OutboundHost`.
+  - ICQQ automatically retries login after `system.offline.kickoff` when
+    `autoReconnect` is enabled, and exposes pending QR/slider/device challenges.
+  - Add `icqq login status|qr|confirm|code|retry` recovery commands. They can be
+    invoked from the QQ conversation that received the notice; `qr` returns the
+    login QR code as an image when the notifying platform supports it.
+  - `notify.id` also counts as the master identity for the related endpoint
+    management commands, so recovery can happen from the notified conversation.
+  - Document the new config and commands in the ICQQ/QQ READMEs and generated
+    configuration reference.
+
+- 26888e4: QQ 官方适配器按官方 v2 接口向 ICQQ 能力对齐：新增 `qq-conversation` / `qq-messages` / `qq-group-directory` / `qq-group-admin` / `qq-group-state` 技能（会话信息、引用回复、撤回自己 / 成员消息、群信息与成员、移出、禁言、入群审批、禁言列表、入群申请、黑名单）及频道成员禁言 / 移出；Endpoint 管理端口补齐群成员列表、踢人、禁言与自动群审核；撤回支持入站原生消息 ID，频道消息支持表情回应。好友 / 群列表、合并转发、戳一戳、点赞、公告、精华、头衔、退群等官方无接口的能力明确标注为不支持。
+- Updated dependencies [6345a38]
+- Updated dependencies [ff3efe7]
+- Updated dependencies [c58c589]
+  - @zhin.js/adapter@1.1.25
+  - @zhin.js/client@1.1.21
+  - @zhin.js/core@1.1.53
+  - @zhin.js/im-contract@1.1.9
+  - @zhin.js/tool@1.1.12
+
 ## 1.1.17
 
 ### Patch Changes

package/README.md

@@ -11,7 +11,10 @@ Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 **WebSock
 - Webhook / middleware 模式已实现（经 `httpHostToken` 注册 POST 路由）
 - AI `@` 触发标注：群消息（GROUP_AT_MESSAGE_CREATE 仅 @ 时下发）与频道 `mentions[].bot` 会在入站 metadata 标 `mentioned: true`（新 Plugin Runtime 纯文本 content 经 metadata 传递 @）
 - 群事件：机器人进群/退群、群成员加入/退出、入群申请（支持 `$approve()` / `$reject()`）
-- 完整 SDK 业务 API：通过 `qqClient.get(context, endpoint).api` 使用群管理、禁言、自动审批策略、自定义菜单、指令面板等 `qq-official-bot` 能力
+- 群管理（官方 v2 群接口）：成员列表 / 详情、移出（可拉黑）、禁言（≤30 天）、入群申请审批、黑名单查询；Endpoint 管理端口与自动群审核（`inspectGroupMember` / `moderateGroupMember`）可直接使用
+- 撤回：自己的消息，以及机器人为群管理员时普通成员 2 分钟内的消息（入站原生消息 ID 也可撤回）
+- 频道子频道消息表情回应（`reaction` 操作，Unicode emoji 或 `type:id`）
+- 完整 SDK 业务 API：当前消息操作的 `session.endpoint` 就是 `qq-official-bot` 实例，可直接使用群管理、禁言、自动审批策略、自定义菜单和指令面板等原生 Service
 
 ## 安装
 
@@ -22,12 +25,13 @@ pnpm add @zhin.js/adapter-qq
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/qq/index.ts`（`defineAdapter`）
-- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/core` — `endpoint[endpointSpec].events` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 - **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（WebSocket 路径）
 
-入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef 结构化寻址）  
+入站：`endpoint[endpointSpec].events.emit('message.receive', { conversation, message, content, sender, metadata })`（ConversationRef 结构化寻址）
+
 出站：`send({ conversation, payload })` → `sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`
 
 ## 前置条件
@@ -67,7 +71,7 @@ WebSocket Identify 的 `intents` **必须与开放平台已开通的权限一致
 | `private`（私域） | `GUILD_MESSAGES`（频道全量） | 同上 |
 
 公域机器人订阅 `GUILD_MESSAGES` 会 Identify 失败断连。显式配置 `intents` 时优先于 `botKind`。
-`create-zhin` / `zhin setup` 会询问公/私域并写入；`qq endpoint add` 扫码成功后在同一会话追问 `public`/`private`（或 `公域`/`私域`），确认后一次性写 `.env` 与 yaml。
+`create-zhin` / `zhin setup` 会询问公/私域并写入；`qq endpoint add` 扫码成功后在同一会话追问 `public`/`private`（或 `公域`/`私域`），确认后通过所属 Adapter 的单次 CAS 加密保存为未启动账号，需手动启动。
 
 多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`id` 必填）：
 
@@ -110,10 +114,10 @@ qq:
 
 | 命令 | 说明 |
 |------|------|
-| `qq endpoint add [name]` | 手机 QQ 扫码绑定 → **追问公域/私域** → 一次性写入 `.env` + `qq.endpoints`（重启生效） |
+| `qq endpoint add [name]` | 手机 QQ 扫码绑定 → **追问公域/私域** → 一次 CAS 保存为未启动账号（无需重启） |
 | `qq endpoint cancel` | 取消进行中的扫码绑定或待确认的公域/私域选择 |
 | `qq endpoint list` | 列出运行中与配置中的 endpoints |
-| `qq endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |
+| `qq endpoint remove <name>` | 删除账号配置，取消目标在途并关闭，保留历史 |
 
 add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i].master`）时仅
 master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoint 的 `master`）。二维码当前以链接文本下发
@@ -132,30 +136,48 @@ master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoi
 
 ## AI 工具（Skill）
 
-| 类别 | 路径 |
-|------|------|
-| Permit 词汇 | `PERMITS.md` |
-| 平台工具 | `tools/`（频道、角色等） |
-| 技能说明 | `agents/qq/skills/qq/SKILL.md` |
+| 技能 | 工具 | 场景 |
+|------|------|------|
+| `qq-conversation` | `conversation_info` | 当前会话、机器人实时群角色（`bot_state`）、可用操作与官方限制 |
+| `qq-messages` | `quote_reply`、`recall_own_message` | 私聊 / 群 / 频道 |
+| `qq-group-directory` | `group_info`、`group_members`、`group_member_info` | 当前群 |
+| `qq-group-admin` | `group_kick`、`set_mute`、`recall_member_message`、`handle_join_request` | 当前群（撤回也支持频道） |
+| `qq-group-state` | `list_muted`、`list_join_requests`、`group_blacklist` | 当前群 |
+| `qq-directory` | `list_guilds` | 任意 |
+| `qq` | `list_channels`、`channel_info`、`list_roles`、`create_role`、`add_role`、`remove_role`、`member_detail`、`guild_mute_member`、`guild_kick_member` | 频道 |
+
+群工具只作用于当前会话的群（`group_openid`），成员用 `member_openid` 标识；写操作前实时核验机器人角色。
+`group_kick` / `handle_join_request` / `guild_kick_member` 每次人工审批，禁言类每次审批。Permit 词汇见 `PERMITS.md`。
+
+### 与 ICQQ 的对齐情况
+
+| ICQQ 能力 | QQ 官方 | 说明 |
+|-----------|---------|------|
+| `group_member_info`、`conversation_info`、`quote_reply`、`recall_own_message`、`recall_member_message`、`group_kick`、`set_mute`、`list_muted` | ✅ 对齐 | 官方 v2 群接口；成员 / 移出类为白名单能力（11253） |
+| 入群申请审批、Console 成员列表 / 踢人 / 禁言、自动群审核 | ✅ 对齐 | `EndpointManagement` 端口 |
+| 表情回应 | ⚠️ 部分 | 仅频道子频道消息；官方无群 / 单聊表情回应 |
+| `friend_list`、`group_list`、`user_info` | ❌ 官方不支持 | 无机器人好友 / 群列表、任意用户资料接口 |
+| `forward_messages` | ❌ 官方不支持 | 无合并转发发送接口 |
+| `poke`、`send_user_like`、`group_sign` | ❌ 官方不支持 | |
+| `announce`、`essence`、`set_title`、`set_anonymous`、`group_files`、`group_invite`、`group_leave` | ❌ 官方不支持 | 群公告 / 精华 / 头衔 / 匿名 / 群文件 / 邀请 / 退群均无接口 |
+| 设管理员、删好友（Console） | ❌ 官方不支持 | |
 
 ## 平台 Client 与 QQ API
 
-`qqClient` 返回当前 endpoint 的传输 client。常用发送、撤回、频道查询仍有顶层快捷方法；
-`client.api` 暴露完整的 `qq-official-bot` 1.3 业务 Service 与实体入口；连接启停仍由 Endpoint 生命周期统一管理：
+在已有消息操作中，`session.endpoint` 是完整的 `qq-official-bot` 1.3 原生 Bot 实例，直接暴露业务 Service 与实体入口；账号连接启停仍通过所属 Adapter 管理：
 
 ```ts
-import { qqClient } from '@zhin.js/adapter-qq';
+// session 来自声明 adapter: 'qq' 的当前消息操作。
+const client = session.endpoint;
 
-const client = qqClient.get(context, 'my-qq-bot');
-
-const group = await client.api.groupService.getInfo(groupOpenid);
-const requests = await client.api.groupService.getJoinRequests(groupOpenid);
-await client.api.groupService.setMemberMute(groupOpenid, [
+const group = await client.groupService.getInfo(groupOpenid);
+const requests = await client.groupService.getJoinRequests(groupOpenid);
+await client.groupService.setMemberMute(groupOpenid, [
   { op: 'add', member_openid: memberOpenid, mute_expire_at: expiresAt },
 ]);
 
-const menu = await client.api.menuPanelService.getCustomMenu();
-const panels = await client.api.menuPanelService.getCommandPanels({ scope: 'group' });
+const menu = await client.menuPanelService.getCustomMenu();
+const panels = await client.menuPanelService.getCommandPanels({ scope: 'group' });
 ```
 
 群管理接口中有部分是白名单能力，入群审批和禁言还要求机器人具备群管理员权限；
@@ -196,6 +218,38 @@ QQ 开放平台按有没有带上用户消息的 `msg_id`（或事件的 `event_
 公域机器人在群里只能收到 @ 它的消息，所以群聊旁听（`ai.trigger.ambient`）只对拥有全量
 消息权限的私域机器人有意义。
 
+## Console 页面
+
+启动后打开 Console 的「QQ」页（地址 `/qq`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 在账号库查看、修改、启停、替换或删除 QQ 账号；新增走扫码绑定，保存后需手动启动；
+- 「平台操作」里扫码绑定新机器人：扫码 → 选择公域 / 私域 → 通过同一账号 CAS 保存为未启动状态；原来的 `qq endpoint add` 仍然保留。
+
+读取需要 `qq:read`，写操作需要 `qq:write`；管理员 full token 不受限。页面里的「扫码绑定新机器人」等价于原来的 `qq endpoint add`。
+
+首次修改启动配置里的既有账号前，管理员必须核对清单并确认一次迁移。原 canonical 身份与历史保留，完整账号配置加密进入 Host 数据库；此后账号管理只写数据库，不修改启动文件或 `.env`，不重启进程。没有持久化账号端口的环境可使用静态配置连接，动态写操作明确不可用。
+
+启停意图在进程重启后恢复。停止或删除会取消并关闭目标账号的在途操作，其他账号继续运行；删除保留历史。已启动账号的连接配置更新先关闭旧 incarnation，再仅重连该账号；平台身份变化按替换处理，分配新内部身份、保留旧历史，新账号不继承旧 Session、个人设置或启动意图。提交结果未知时先刷新核实，不自动重复 CAS 或平台操作。
+
+## 掉线通知
+
+QQ 官方机器人掉线 / 启动失败时，可以配置 `notify` 让另一个适配器实例通知 master：
+
+```yaml
+icqq:
+  # ... 已配置好的 ICQQ 实例
+qq:
+  master: "${QQ_MASTER_OPENID}"
+  notify:
+    adapter: icqq
+    endpoint: "123456"
+    kind: private
+    id: "123456"   # master 的 QQ 号
+```
+
+通知里会提示恢复方式：在 QQ 回复 `qq endpoint add` 重新扫码绑定（或打开 Console 的 QQ 页面）。`notify.id` 同时作为 endpoint 管理命令的 master 身份，方便从通知会话直接完成绑定。未配置 `notify` 时只在日志和 Console 的 QQ 页面显示连接状态。
+
 ## 故障排查
 
 | 现象 | 排查 |

package/adapters/qq/index.js

@@ -3,14 +3,12 @@
  * Convention entry: discover `adapters/qq/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { QqHttpEndpoint, QqWebsocketEndpoint } from "../../lib/endpoint.js";
-import { resolveQqConfig, } from "../../lib/protocol.js";
-import { qqRuntimeStateToken } from "../../lib/qq-runtime-state.js";
+import { QqAdapter } from "../../lib/adapter.js";
+import {} from "../../lib/protocol.js";
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    operations: ['recall'],
+    operations: ['recall', 'reaction'],
     // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
     // markdown/keyboard 原生按钮承载交互段。
     segments: {
@@ -19,32 +17,5 @@ export default defineAdapter({
         outboundMedia: ['url', 'upload'],
         interactive: 'native',
     },
-    create(context) {
-        const config = resolveQqConfig(context.config);
-        // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
-        const state = context.use(qqRuntimeStateToken);
-        state.endpoints.set(config.id, {
-            id: config.id,
-            mode: config.mode,
-        });
-        // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
-        // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
-        const endpoint = config.mode === 'websocket'
-            ? new QqWebsocketEndpoint({
-                id: context.id,
-                config,
-            })
-            : new QqHttpEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq endpoint list 仍显示运行中。
-        const stopEndpoint = endpoint.stop.bind(endpoint);
-        endpoint.stop = async () => {
-            state.endpoints.delete(config.id);
-            await stopEndpoint();
-        };
-        return endpoint;
-    },
+    createAdapter: context => new QqAdapter(context),
 });

package/adapters/qq/index.ts

@@ -2,36 +2,25 @@
  * Convention entry: discover `adapters/qq/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { QqHttpEndpoint, QqWebsocketEndpoint } from '../../src/endpoint.js';
+import { QqAdapter } from '../../src/adapter.js';
 import {
-  resolveQqConfig,
   type QqEndpointConfig,
 } 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';
 
-declare module '@zhin.js/core' {
-  interface AdapterEndpoints {
-    qq: import('../../src/endpoint.js').QqWebsocketEndpoint;
-  }
-}
-
 export default defineAdapter<QqEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
-  operations: ['recall'],
+  operations: ['recall', 'reaction'],
   // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
   // markdown/keyboard 原生按钮承载交互段。
   segments: {
@@ -40,32 +29,5 @@ export default defineAdapter<QqEndpointConfig>({
     outboundMedia: ['url', 'upload'],
     interactive: 'native',
   },
-  create(context) {
-    const config = resolveQqConfig(context.config);
-    // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
-    const state = context.use(qqRuntimeStateToken);
-    state.endpoints.set(config.id, {
-      id: config.id,
-      mode: config.mode,
-    });
-    // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
-    // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
-    const endpoint = config.mode === 'websocket'
-      ? new QqWebsocketEndpoint({
-        id: context.id,
-        config,
-      })
-      : new QqHttpEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq endpoint list 仍显示运行中。
-    const stopEndpoint = endpoint.stop.bind(endpoint);
-    endpoint.stop = async () => {
-      state.endpoints.delete(config.id);
-      await stopEndpoint();
-    };
-    return endpoint;
-  },
+  createAdapter: context => new QqAdapter(context),
 });

package/agents/qq/boundaries.md

@@ -1,3 +1,5 @@
 # Boundaries
 
 Operate only on the active qq endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.
+
+QQ official bots only expose the documented Bot API. Group members are `member_openid` values scoped to this bot and group. There is no group list, friend list, user profile, poke, like, merged forward, leave group, announcement, essence, title, anonymous, group file or sign-in API; say so instead of simulating them. Many group management APIs are invite-only (error 11253).

package/agents/qq/conversation.js

@@ -0,0 +1,92 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { outboundMessageToken } from '@zhin.js/core/runtime';
+import { parseCompoundMessageId, qqOutboundKind } from "../../lib/protocol.js";
+// Shared with EndpointManagement so Console, auto-moderation and Agent tools enforce the same official limits.
+export { kickQqGroupMember, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS } from "../../lib/group-admin.js";
+import { messages as t } from './messages.js';
+/** The trusted turn owns the endpoint and address; model input cannot select another one. */
+export function currentConversation(context) {
+    const { origin } = context;
+    if (origin.kind !== 'im' || origin.platform !== 'qq' || !origin.conversation) {
+        throw new Error(t(context.locale, 'conversationRequired'));
+    }
+    context.signal.throwIfAborted();
+    return origin.conversation;
+}
+/** Current QQ group_openid. */
+export function currentGroup(context) {
+    const conversation = currentConversation(context);
+    if (conversation.kind !== 'group')
+        throw new Error(t(context.locale, 'groupRequired'));
+    return conversation.id;
+}
+/** Current guild child channel and its guild. */
+export function currentGuildChannel(context) {
+    const conversation = currentConversation(context);
+    const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : '';
+    if (conversation.kind !== 'channel' || !guildId)
+        throw new Error(t(context.locale, 'channelRequired'));
+    return { guildId, channelId: conversation.id };
+}
+/**
+ * Resolve a message ID inside the current conversation. Outbound receipts are `kind-target:msgId`
+ * and must match the current conversation; anything else is a native inbound ID of this conversation.
+ */
+export function resolveMessageTarget(context, id) {
+    const conversation = currentConversation(context);
+    const kind = qqOutboundKind(conversation);
+    const value = id.trim();
+    if (!value)
+        throw new Error(t(context.locale, 'messageOutsideConversation'));
+    let compound;
+    try {
+        compound = parseCompoundMessageId(value);
+    }
+    catch {
+        compound = undefined;
+    }
+    if (compound) {
+        if (compound.kind !== kind || compound.channelId !== conversation.id || !compound.qqMsgId) {
+            throw new Error(t(context.locale, 'messageOutsideConversation'));
+        }
+        return { kind, targetId: conversation.id, messageId: compound.qqMsgId, ownOutbound: true };
+    }
+    return { kind, targetId: conversation.id, messageId: value, ownOutbound: false };
+}
+export async function recallTarget(context, target) {
+    context.signal.throwIfAborted();
+    const client = context.$client;
+    const recall = {
+        private: client.recallPrivateMessage, group: client.recallGroupMessage,
+        channel: client.recallGuildMessage, direct: client.recallDirectMessage,
+    }[target.kind];
+    if (!recall)
+        return { success: false, message: t(context.locale, 'recallUnconfirmed') };
+    try {
+        const result = await recall.call(client, target.targetId, target.messageId);
+        const success = result !== false;
+        return { success, message: t(context.locale, success ? 'messageRecalled' : 'recallUnconfirmed') };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: t(context.locale, 'recallUnconfirmed'),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function sendToConversation(context, content) {
+    const conversation = currentConversation(context);
+    const receipt = await context.use(outboundMessageToken).send({
+        requester: context.owner.id,
+        conversation,
+        content,
+    });
+    return { success: receipt.status === 'sent', receipt };
+}
+/** Live check: the bot must be owner/admin of the current group. */
+export async function requireGroupManager(context, groupId) {
+    const state = await context.$client.groupService.getBotState(groupId);
+    context.signal.throwIfAborted();
+    return state.member_role === 'owner' || state.member_role === 'admin' ? state : undefined;
+}

package/agents/qq/conversation.ts

@@ -0,0 +1,99 @@
+import { outboundMessageToken, type SendContent } from '@zhin.js/core/runtime';
+import type { ToolExecutionContext } from '@zhin.js/tool';
+import { parseCompoundMessageId, qqOutboundKind, type QqChannelKind } from '../../src/protocol.js';
+// Shared with EndpointManagement so Console, auto-moderation and Agent tools enforce the same official limits.
+export { kickQqGroupMember, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS } from '../../src/group-admin.js';
+import { messages as t } from './messages.js';
+
+export type QqToolContext = ToolExecutionContext<unknown, 'qq'>;
+
+/** The trusted turn owns the endpoint and address; model input cannot select another one. */
+export function currentConversation(context: QqToolContext) {
+  const { origin } = context;
+  if (origin.kind !== 'im' || origin.platform !== 'qq' || !origin.conversation) {
+    throw new Error(t(context.locale, 'conversationRequired'));
+  }
+  context.signal.throwIfAborted();
+  return origin.conversation;
+}
+
+/** Current QQ group_openid. */
+export function currentGroup(context: QqToolContext): string {
+  const conversation = currentConversation(context);
+  if (conversation.kind !== 'group') throw new Error(t(context.locale, 'groupRequired'));
+  return conversation.id;
+}
+
+/** Current guild child channel and its guild. */
+export function currentGuildChannel(context: QqToolContext): { guildId: string; channelId: string } {
+  const conversation = currentConversation(context);
+  const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : '';
+  if (conversation.kind !== 'channel' || !guildId) throw new Error(t(context.locale, 'channelRequired'));
+  return { guildId, channelId: conversation.id };
+}
+
+export interface QqMessageTarget {
+  readonly kind: QqChannelKind;
+  readonly targetId: string;
+  readonly messageId: string;
+  /** `send()` receipt IDs are compound; only those are known to be the bot's own messages. */
+  readonly ownOutbound: boolean;
+}
+
+/**
+ * Resolve a message ID inside the current conversation. Outbound receipts are `kind-target:msgId`
+ * and must match the current conversation; anything else is a native inbound ID of this conversation.
+ */
+export function resolveMessageTarget(context: QqToolContext, id: string): QqMessageTarget {
+  const conversation = currentConversation(context);
+  const kind = qqOutboundKind(conversation);
+  const value = id.trim();
+  if (!value) throw new Error(t(context.locale, 'messageOutsideConversation'));
+  let compound: ReturnType<typeof parseCompoundMessageId> | undefined;
+  try { compound = parseCompoundMessageId(value); } catch { compound = undefined; }
+  if (compound) {
+    if (compound.kind !== kind || compound.channelId !== conversation.id || !compound.qqMsgId) {
+      throw new Error(t(context.locale, 'messageOutsideConversation'));
+    }
+    return { kind, targetId: conversation.id, messageId: compound.qqMsgId, ownOutbound: true };
+  }
+  return { kind, targetId: conversation.id, messageId: value, ownOutbound: false };
+}
+
+export async function recallTarget(context: QqToolContext, target: QqMessageTarget) {
+  context.signal.throwIfAborted();
+  const client = context.$client;
+  const recall = {
+    private: client.recallPrivateMessage, group: client.recallGroupMessage,
+    channel: client.recallGuildMessage, direct: client.recallDirectMessage,
+  }[target.kind];
+  if (!recall) return { success: false, message: t(context.locale, 'recallUnconfirmed') };
+  try {
+    const result = await recall.call(client, target.targetId, target.messageId);
+    const success = result !== false;
+    return { success, message: t(context.locale, success ? 'messageRecalled' : 'recallUnconfirmed') };
+  } catch (error) {
+    return {
+      success: false,
+      message: t(context.locale, 'recallUnconfirmed'),
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function sendToConversation(context: QqToolContext, content: SendContent) {
+  const conversation = currentConversation(context);
+  const receipt = await context.use(outboundMessageToken).send({
+    requester: context.owner.id,
+    conversation,
+    content,
+  });
+  return { success: receipt.status === 'sent', receipt };
+}
+
+/** Live check: the bot must be owner/admin of the current group. */
+export async function requireGroupManager(context: QqToolContext, groupId: string) {
+  const state = await context.$client.groupService.getBotState(groupId);
+  context.signal.throwIfAborted();
+  return state.member_role === 'owner' || state.member_role === 'admin' ? state : undefined;
+}

package/agents/qq/messages.js

@@ -20,5 +20,65 @@ export const messages = createMessages({
     "roleRemoved": {
         "zh-CN": "已移除成员的角色",
         "en": "Role removed from the member"
+    },
+    "conversationRequired": {
+        "zh-CN": "此操作需要当前 QQ 官方机器人会话",
+        "en": "This operation requires the current QQ official bot conversation"
+    },
+    "groupRequired": {
+        "zh-CN": "此操作仅支持当前 QQ 群",
+        "en": "This operation requires the current QQ group"
+    },
+    "channelRequired": {
+        "zh-CN": "此操作仅支持当前 QQ 频道子频道",
+        "en": "This operation requires the current QQ guild channel"
+    },
+    "messageOutsideConversation": {
+        "zh-CN": "该消息 ID 不属于当前会话，请勿猜测消息 ID",
+        "en": "The message ID does not belong to this conversation; do not guess message IDs"
+    },
+    "ownMessageRequired": {
+        "zh-CN": "该工具只能撤回机器人自己发送的消息（发送回执里的消息 ID）",
+        "en": "This tool can only recall messages the bot sent (the ID from its send receipt)"
+    },
+    "botNotManager": {
+        "zh-CN": "机器人当前不是本群群主或管理员，平台不允许此操作",
+        "en": "The bot is not an owner or admin of this group, so the platform does not allow this"
+    },
+    "targetNotMember": {
+        "zh-CN": "目标必须是本群的普通成员（官方不允许处置群主、管理员或机器人）",
+        "en": "The target must be an ordinary member of this group (owners, admins and bots cannot be targeted)"
+    },
+    "messageRecalled": {
+        "zh-CN": "平台已确认撤回消息",
+        "en": "The platform confirmed the message was recalled"
+    },
+    "recallUnconfirmed": {
+        "zh-CN": "平台未确认撤回成功（官方只允许撤回 2 分钟内的消息），请勿自动重试",
+        "en": "Recall was not confirmed (QQ only allows recalling messages younger than 2 minutes); do not retry automatically"
+    },
+    "memberKicked": {
+        "zh-CN": "已将成员 {p0} 移出本群",
+        "en": "Removed member {p0} from this group"
+    },
+    "blacklistFailed": {
+        "zh-CN": "成员已移出，但加入黑名单失败",
+        "en": "The member was removed, but adding them to the blacklist failed"
+    },
+    "muted": {
+        "zh-CN": "已禁言 {user} {seconds} 秒",
+        "en": "Muted {user} for {seconds} seconds"
+    },
+    "unmuted": {
+        "zh-CN": "已解除 {user} 的禁言",
+        "en": "Unmuted {user}"
+    },
+    "joinApproved": {
+        "zh-CN": "已通过 {user} 的入群申请",
+        "en": "Approved the join request from {user}"
+    },
+    "joinDeclined": {
+        "zh-CN": "已拒绝 {user} 的入群申请",
+        "en": "Declined the join request from {user}"
     }
 });