@zhin.js/adapter-qq 1.1.18 → 1.1.19

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @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

package/README.md

@@ -14,7 +14,7 @@ Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 **WebSock
 - 群管理（官方 v2 群接口）：成员列表 / 详情、移出（可拉黑）、禁言（≤30 天）、入群申请审批、黑名单查询；Endpoint 管理端口与自动群审核（`inspectGroupMember` / `moderateGroupMember`）可直接使用
 - 撤回：自己的消息，以及机器人为群管理员时普通成员 2 分钟内的消息（入站原生消息 ID 也可撤回）
 - 频道子频道消息表情回应（`reaction` 操作，Unicode emoji 或 `type:id`）
-- 完整 SDK 业务 API：通过 `qqClient.get(context, endpoint).api` 使用群管理、禁言、自动审批策略、自定义菜单、指令面板等 `qq-official-bot` 能力
+- 完整 SDK 业务 API：当前消息操作的 `session.endpoint` 就是 `qq-official-bot` 实例，可直接使用群管理、禁言、自动审批策略、自定义菜单和指令面板等原生 Service
 
 ## 安装
 
@@ -25,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`
 
 ## 前置条件
@@ -70,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` 必填）：
 
@@ -113,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`）。二维码当前以链接文本下发
@@ -163,22 +164,20 @@ master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoi
 
 ## 平台 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';
-
-const client = qqClient.get(context, 'my-qq-bot');
+// session 来自声明 adapter: 'qq' 的当前消息操作。
+const client = session.endpoint;
 
-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' });
 ```
 
 群管理接口中有部分是白名单能力，入群审批和禁言还要求机器人具备群管理员权限；
@@ -224,11 +223,15 @@ QQ 开放平台按有没有带上用户消息的 `msg_id`（或事件的 `event_
 启动后打开 Console 的「QQ」页（地址 `/qq`），可以：
 
 - 查看运行中的连接、点「测试连接」做连通性诊断；
-- 查看 / 删除 `plugins.qq.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；新增走扫码绑定；
-- 「平台操作」里扫码绑定新机器人：扫码 → 选择公域 / 私域 → 写入配置；原来的 `qq endpoint add` 仍然保留。
+- 在账号库查看、修改、启停、替换或删除 QQ 账号；新增走扫码绑定，保存后需手动启动；
+- 「平台操作」里扫码绑定新机器人：扫码 → 选择公域 / 私域 → 通过同一账号 CAS 保存为未启动状态；原来的 `qq endpoint add` 仍然保留。
 
 读取需要 `qq:read`，写操作需要 `qq:write`；管理员 full token 不受限。页面里的「扫码绑定新机器人」等价于原来的 `qq endpoint add`。
 
+首次修改启动配置里的既有账号前，管理员必须核对清单并确认一次迁移。原 canonical 身份与历史保留，完整账号配置加密进入 Host 数据库；此后账号管理只写数据库，不修改启动文件或 `.env`，不重启进程。没有持久化账号端口的环境可使用静态配置连接，动态写操作明确不可用。
+
+启停意图在进程重启后恢复。停止或删除会取消并关闭目标账号的在途操作，其他账号继续运行；删除保留历史。已启动账号的连接配置更新先关闭旧 incarnation，再仅重连该账号；平台身份变化按替换处理，分配新内部身份、保留旧历史，新账号不继承旧 Session、个人设置或启动意图。提交结果未知时先刷新核实，不自动重复 CAS 或平台操作。
+
 ## 掉线通知
 
 QQ 官方机器人掉线 / 启动失败时，可以配置 `notify` 让另一个适配器实例通知 master：

package/adapters/qq/index.js

@@ -2,12 +2,9 @@
 /**
  * Convention entry: discover `adapters/qq/index.ts` → defineAdapter.
  */
-import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
-import { outboundHostToken } from 'zhin.js';
-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 { defineAdapter } from 'zhin.js/adapter';
+import { QqAdapter } from "../../lib/adapter.js";
+import {} from "../../lib/protocol.js";
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
@@ -20,36 +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 outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
-        const notifier = createAdapterOutageNotifier(outbound, config.notify);
-        const endpoint = config.mode === 'websocket'
-            ? new QqWebsocketEndpoint({
-                id: context.id,
-                config,
-                notifier,
-            })
-            : new QqHttpEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-                notifier,
-            });
-        // 运行状态表只增不减：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

@@ -1,35 +1,23 @@
 /**
  * Convention entry: discover `adapters/qq/index.ts` → defineAdapter.
  */
-import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
-import { outboundHostToken } from 'zhin.js';
-import { httpHostToken } from '@zhin.js/host-http';
-import { QqHttpEndpoint, QqWebsocketEndpoint } from '../../src/endpoint.js';
+import { defineAdapter } from 'zhin.js/adapter';
+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', 'reaction'],
@@ -41,36 +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 outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
-    const notifier = createAdapterOutageNotifier(outbound, config.notify);
-    const endpoint = config.mode === 'websocket'
-      ? new QqWebsocketEndpoint({
-        id: context.id,
-        config,
-        notifier,
-      })
-      : new QqHttpEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-        notifier,
-      });
-    // 运行状态表只增不减：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/conversation.js

@@ -86,7 +86,7 @@ export async function sendToConversation(context, content) {
 }
 /** Live check: the bot must be owner/admin of the current group. */
 export async function requireGroupManager(context, groupId) {
-    const state = await context.$client.api.groupService.getBotState(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

@@ -93,7 +93,7 @@ export async function sendToConversation(context: QqToolContext, content: SendCo
 
 /** 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.api.groupService.getBotState(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/skills/qq/tools/add_role/index.js

@@ -17,7 +17,8 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id, channel_id, user_id, role_id }, context) {
         const client = context.$client;
-        const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
+        await client.memberService.addMemberRole(guild_id, channel_id, user_id, role_id);
+        const success = true;
         return { success, message: success ? t(context.locale, 'roleAdded') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/qq/skills/qq/tools/add_role/index.ts

@@ -17,7 +17,8 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
     const client = context.$client;
-    const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
+    await client.memberService.addMemberRole(guild_id, channel_id, user_id, role_id);
+    const success = true;
     return { success, message: success ? t(context.locale, 'roleAdded') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/qq/skills/qq/tools/channel_info/index.js

@@ -13,6 +13,6 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ channel_id }, context) {
         const client = context.$client;
-        return client.getChannelInfo(channel_id);
+        return client.channelService.getInfo(channel_id);
     },
 });

package/agents/qq/skills/qq/tools/channel_info/index.ts

@@ -13,6 +13,6 @@ export default defineAgentTool<{ channel_id: string }>({
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ channel_id  }: { channel_id: string }, context) {
     const client = context.$client;
-    return client.getChannelInfo(channel_id);
+    return client.channelService.getInfo(channel_id);
   },
 });

package/agents/qq/skills/qq/tools/create_role/index.js

@@ -16,7 +16,7 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'guild_owner')],
     async execute({ guild_id, name, color }, context) {
         const client = context.$client;
-        const role = await client.createGuildRole(guild_id, name, color);
+        const role = await client.guildService.createRole(guild_id, { name, color: color || 0, hoist: 0 });
         return { success: !!role, role, message: role ? t(context.locale, 'namedRoleCreated', { p0: name }) : t(context.locale, 'createFailed') };
     },
 });

package/agents/qq/skills/qq/tools/create_role/index.ts

@@ -16,7 +16,7 @@ export default defineAgentTool<{ guild_id: string; name: string; color?: number
   permissions: [platformPermission('qq', 'guild_owner')],
   async execute({ guild_id, name, color  }: { guild_id: string; name: string; color?: number }, context) {
     const client = context.$client;
-    const role = await client.createGuildRole(guild_id, name, color);
+    const role = await client.guildService.createRole(guild_id, { name, color: color || 0, hoist: 0 });
     return { success: !!role, role, message: role ? t(context.locale, 'namedRoleCreated', { p0: name }) : t(context.locale, 'createFailed') };
   },
 });

package/agents/qq/skills/qq/tools/guild_kick_member/index.js

@@ -22,7 +22,7 @@ export default defineAgentTool({
     }),
     async execute({ user_id, blacklist, delete_history_days }, context) {
         const { guildId } = currentGuildChannel(context);
-        const ok = await context.$client.api.memberService.kickMember(guildId, user_id, delete_history_days ?? 0, blacklist === true);
+        const ok = await context.$client.memberService.kickMember(guildId, user_id, delete_history_days ?? 0, blacklist === true);
         if (ok === false)
             return { success: false, message: t(context.locale, 'operationFailed') };
         return { success: true, message: t(context.locale, 'memberKicked', { p0: user_id }) };

package/agents/qq/skills/qq/tools/guild_kick_member/index.ts

@@ -22,7 +22,7 @@ export default defineAgentTool({
   }),
   async execute({ user_id, blacklist, delete_history_days }, context) {
     const { guildId } = currentGuildChannel(context);
-    const ok = await context.$client.api.memberService.kickMember(guildId, user_id, delete_history_days ?? 0, blacklist === true);
+    const ok = await context.$client.memberService.kickMember(guildId, user_id, delete_history_days ?? 0, blacklist === true);
     if (ok === false) return { success: false, message: t(context.locale, 'operationFailed') };
     return { success: true, message: t(context.locale, 'memberKicked', { p0: user_id }) };
   },

package/agents/qq/skills/qq/tools/guild_mute_member/index.js

@@ -19,7 +19,7 @@ export default defineAgentTool({
     }),
     async execute({ user_id, duration }, context) {
         const { guildId } = currentGuildChannel(context);
-        const members = context.$client.api.memberService;
+        const members = context.$client.memberService;
         const seconds = duration ?? 0;
         const ok = seconds === 0
             ? await members.unmuteGuildMember(guildId, user_id)

package/agents/qq/skills/qq/tools/guild_mute_member/index.ts

@@ -19,7 +19,7 @@ export default defineAgentTool({
   }),
   async execute({ user_id, duration }, context) {
     const { guildId } = currentGuildChannel(context);
-    const members = context.$client.api.memberService;
+    const members = context.$client.memberService;
     const seconds = duration ?? 0;
     const ok = seconds === 0
       ? await members.unmuteGuildMember(guildId, user_id)

package/agents/qq/skills/qq/tools/list_channels/index.js

@@ -13,7 +13,7 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_channels')],
     async execute({ guild_id }, context) {
         const client = context.$client;
-        const channels = await client.getChannels(guild_id);
+        const channels = await client.channelService.getList(guild_id);
         return { channels, count: channels.length };
     },
 });

package/agents/qq/skills/qq/tools/list_channels/index.ts

@@ -13,7 +13,7 @@ export default defineAgentTool<{ guild_id: string }>({
   permissions: [platformPermission('qq', 'manage_channels')],
   async execute({ guild_id  }: { guild_id: string }, context) {
     const client = context.$client;
-    const channels = await client.getChannels(guild_id);
+    const channels = await client.channelService.getList(guild_id);
     return { channels, count: channels.length };
   },
 });

package/agents/qq/skills/qq/tools/list_roles/index.js

@@ -13,7 +13,7 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id }, context) {
         const client = context.$client;
-        const roles = await client.getGuildRoles(guild_id);
+        const roles = await client.guildService.getRoles(guild_id);
         return { roles, count: roles.length };
     },
 });

package/agents/qq/skills/qq/tools/list_roles/index.ts

@@ -13,7 +13,7 @@ export default defineAgentTool<{ guild_id: string }>({
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id  }: { guild_id: string }, context) {
     const client = context.$client;
-    const roles = await client.getGuildRoles(guild_id);
+    const roles = await client.guildService.getRoles(guild_id);
     return { roles, count: roles.length };
   },
 });

package/agents/qq/skills/qq/tools/member_detail/index.js

@@ -14,6 +14,6 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ guild_id, user_id }, context) {
         const client = context.$client;
-        return client.getGuildMember(guild_id, user_id);
+        return client.memberService.getGuildMemberInfo(guild_id, user_id);
     },
 });

package/agents/qq/skills/qq/tools/member_detail/index.ts

@@ -14,6 +14,6 @@ export default defineAgentTool<{ guild_id: string; user_id: string }>({
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ guild_id, user_id  }: { guild_id: string; user_id: string }, context) {
     const client = context.$client;
-    return client.getGuildMember(guild_id, user_id);
+    return client.memberService.getGuildMemberInfo(guild_id, user_id);
   },
 });

package/agents/qq/skills/qq/tools/remove_role/index.js

@@ -17,7 +17,8 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id, channel_id, user_id, role_id }, context) {
         const client = context.$client;
-        const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
+        await client.memberService.removeMemberRole(guild_id, channel_id, user_id, role_id);
+        const success = true;
         return { success, message: success ? t(context.locale, 'roleRemoved') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/qq/skills/qq/tools/remove_role/index.ts

@@ -17,7 +17,8 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
     const client = context.$client;
-    const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
+    await client.memberService.removeMemberRole(guild_id, channel_id, user_id, role_id);
+    const success = true;
     return { success, message: success ? t(context.locale, 'roleRemoved') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/qq/skills/qq-conversation/tools/conversation_info/index.js

@@ -38,7 +38,7 @@ export default defineAgentTool({
                 leaveGroup: false,
             },
         };
-        const api = context.$client.api;
+        const api = context.$client;
         if (conversation.kind === 'group') {
             const [state, info] = await Promise.all([
                 api.groupService.getBotState(conversation.id),

package/agents/qq/skills/qq-conversation/tools/conversation_info/index.ts

@@ -36,7 +36,7 @@ export default defineAgentTool({
         leaveGroup: false,
       },
     };
-    const api = context.$client.api;
+    const api = context.$client;
     if (conversation.kind === 'group') {
       const [state, info] = await Promise.all([
         api.groupService.getBotState(conversation.id),

package/agents/qq/skills/qq-directory/tools/list_guilds/index.js

@@ -8,7 +8,7 @@ export default defineAgentTool({
     tags: ['qq'],
     async execute(_input, context) {
         const client = context.$client;
-        const guilds = await client.getGuilds();
+        const guilds = await client.guildService.getList();
         return { guilds, count: guilds.length };
     },
 });

package/agents/qq/skills/qq-directory/tools/list_guilds/index.ts

@@ -8,7 +8,7 @@ export default defineAgentTool<Record<string, never>>({
   tags: ['qq'],
   async execute(_input, context) {
     const client = context.$client;
-    const guilds = await client.getGuilds();
+    const guilds = await client.guildService.getList();
     return { guilds, count: guilds.length };
   },
 });

package/agents/qq/skills/qq-group-admin/tools/group_kick/index.js

@@ -21,7 +21,7 @@ export default defineAgentTool({
         const client = context.$client;
         const [self, member] = await Promise.all([
             requireGroupManager(context, group),
-            client.api.groupService.getMemberInfo(group, user_id),
+            client.groupService.getMemberInfo(group, user_id),
         ]);
         if (!self)
             return { success: false, message: t(context.locale, 'botNotManager') };
@@ -29,7 +29,7 @@ export default defineAgentTool({
             return { success: false, message: t(context.locale, 'targetNotMember') };
         }
         context.signal.throwIfAborted();
-        const { blacklistFailed } = await kickQqGroupMember(client.api, group, user_id, blacklist === true);
+        const { blacklistFailed } = await kickQqGroupMember(client, { groupId: group, userId: user_id, addToBlacklist: blacklist === true });
         return {
             success: true,
             message: t(context.locale, 'memberKicked', { p0: member.username || user_id }),

package/agents/qq/skills/qq-group-admin/tools/group_kick/index.ts

@@ -21,14 +21,14 @@ export default defineAgentTool({
     const client = context.$client;
     const [self, member] = await Promise.all([
       requireGroupManager(context, group),
-      client.api.groupService.getMemberInfo(group, user_id),
+      client.groupService.getMemberInfo(group, user_id),
     ]);
     if (!self) return { success: false, message: t(context.locale, 'botNotManager') };
     if (member.member_openid !== user_id || member.member_role !== 'member' || member.bot || user_id === self.member_openid) {
       return { success: false, message: t(context.locale, 'targetNotMember') };
     }
     context.signal.throwIfAborted();
-    const { blacklistFailed } = await kickQqGroupMember(client.api, group, user_id, blacklist === true);
+    const { blacklistFailed } = await kickQqGroupMember(client, { groupId: group, userId: user_id, addToBlacklist: blacklist === true });
     return {
       success: true,
       message: t(context.locale, 'memberKicked', { p0: member.username || user_id }),

package/agents/qq/skills/qq-group-admin/tools/handle_join_request/index.js

@@ -22,7 +22,7 @@ export default defineAgentTool({
         const group = currentGroup(context);
         if (!await requireGroupManager(context, group))
             return { success: false, message: t(context.locale, 'botNotManager') };
-        await context.$client.api.groupService.approveJoinRequest(group, user_id, {
+        await context.$client.groupService.approveJoinRequest(group, user_id, {
             op: approve ? 'approve' : 'decline',
             ...(join_request_id ? { join_request_id } : {}),
             ...(!approve && reason ? { reject_reason: reason } : {}),

package/agents/qq/skills/qq-group-admin/tools/handle_join_request/index.ts

@@ -21,7 +21,7 @@ export default defineAgentTool({
   async execute({ user_id, join_request_id, approve, reason, blacklist }, context) {
     const group = currentGroup(context);
     if (!await requireGroupManager(context, group)) return { success: false, message: t(context.locale, 'botNotManager') };
-    await context.$client.api.groupService.approveJoinRequest(group, user_id, {
+    await context.$client.groupService.approveJoinRequest(group, user_id, {
       op: approve ? 'approve' : 'decline',
       ...(join_request_id ? { join_request_id } : {}),
       ...(!approve && reason ? { reject_reason: reason } : {}),

package/agents/qq/skills/qq-group-admin/tools/set_mute/index.js

@@ -21,7 +21,7 @@ export default defineAgentTool({
         const seconds = duration ?? 0;
         const [self, member] = await Promise.all([
             requireGroupManager(context, group),
-            client.api.groupService.getMemberInfo(group, user_id),
+            client.groupService.getMemberInfo(group, user_id),
         ]);
         if (!self)
             return { success: false, message: t(context.locale, 'botNotManager') };
@@ -30,7 +30,7 @@ export default defineAgentTool({
             return { success: false, message: t(context.locale, 'targetNotMember') };
         }
         context.signal.throwIfAborted();
-        await muteQqGroupMember(client.api, group, user_id, seconds);
+        await muteQqGroupMember(client, { groupId: group, userId: user_id, durationSeconds: seconds });
         const user = member.username || user_id;
         return { success: true, message: seconds === 0 ? t(context.locale, 'unmuted', { user }) : t(context.locale, 'muted', { user, seconds }) };
     },

package/agents/qq/skills/qq-group-admin/tools/set_mute/index.ts

@@ -21,7 +21,7 @@ export default defineAgentTool({
     const seconds = duration ?? 0;
     const [self, member] = await Promise.all([
       requireGroupManager(context, group),
-      client.api.groupService.getMemberInfo(group, user_id),
+      client.groupService.getMemberInfo(group, user_id),
     ]);
     if (!self) return { success: false, message: t(context.locale, 'botNotManager') };
     // 官方：新增 / 更新禁言只能作用于普通成员；解除不限制。
@@ -29,7 +29,7 @@ export default defineAgentTool({
       return { success: false, message: t(context.locale, 'targetNotMember') };
     }
     context.signal.throwIfAborted();
-    await muteQqGroupMember(client.api, group, user_id, seconds);
+    await muteQqGroupMember(client, { groupId: group, userId: user_id, durationSeconds: seconds });
     const user = member.username || user_id;
     return { success: true, message: seconds === 0 ? t(context.locale, 'unmuted', { user }) : t(context.locale, 'muted', { user, seconds }) };
   },

package/agents/qq/skills/qq-group-directory/tools/group_info/index.js

@@ -10,7 +10,7 @@ export default defineAgentTool({
     readOnly: true,
     inputSchema: z.object({}),
     async execute(_input, context) {
-        const info = await context.$client.api.groupService.getInfo(currentGroup(context));
+        const info = await context.$client.groupService.getInfo(currentGroup(context));
         return { success: true, group: info };
     },
 });