@zhin.js/adapter-icqq 1.1.21 → 1.1.22

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.22
+
+### Patch Changes
+
+- b249e5e: ADR 0044 C4：事件映射迁出 core。新增 `@zhin.js/adapter-onebot-events`，承载 OneBot v11 / NapCat / icqq 的原始通知与请求 → 标准事件映射（`receiveOneBotLikeSideEvent`、`mapNoticeParts`、`mapRequestParts`、`resolveSideEventDedupeKey` 及 OneBot 映射表，icqq 差异用覆盖表表达）；KOOK、Slack 的映射迁入各自适配器；`@zhin.js/core` 只保留标准事件名、类型与 `buildNotice` / `buildRequest` / `buildSystem` / `senderFromId`，不再含任何平台名。core 不再导出上述映射函数与 `ONEBOT_/KOOK_/SLACK_NOTICE_PARTS_MAP`、`SideEventPlatform`、`OneBotLike*` 类型，适配器改从共享包导入。
+- 41ff1a5: ADR 0044 C5: every official adapter now declares a capability `profile` (its `segments` moved into `profile.default.messaging.segments`). icqq declares the complete profile (per conversation kind: scene, all 14 actions with real limits, events, feedback, delivery) and implements the seven new management ports (`pokeUser`, `unmuteGroupMember`, `muteAllGroupMembers`, `setGroupCard`, `setGroupTitle`, `setGroupEssence`, `inviteGroupMember`) with fresh bot-role reads. qq official declares its passive reply windows; undeclared capabilities stay unsupported.
+- cbd3f14: ADR 0044 integration and C6 guard. `delivery.spool` now reproduces the pre-0044 media rule (icqq `false`, every other official adapter `true`). icqq narrows `actions.recall.others` unless the Bot is admin or owner, and declares recall for groups. Endpoint kind capabilities merge the Endpoint's `operations` (Discord reactions keep working; Discord declares reaction feedback). Adapters in the `@zhin.js/` scope are trusted: their custom prompt text is not labelled `external_content`. Core no longer keeps a telegram/discord interactive-policy table (adapters declare `segments.interactive`). New `pnpm check:no-platform-branches` blocks platform-name branches in runtime code.
+- 299863a: ADR 0044 C3: runtime consumers read capabilities instead of platform names. Scene facts (group info, member profile) are queried where the profile declares `scene.groupInfo` / `scene.memberProfile`; activity feedback (reaction, typing, status message, refresh interval, quote-only delivery) follows `feedback`, `actions.reaction` and `delivery.proactive` and the per-platform table is gone; large inline media is spooled only where `delivery.spool` is declared; the sandbox ingress and its console shell follow a new additive `runtime.sandbox` capability. `defineAgentTool` and Skill frontmatter accept `requiresCapabilities` (for example `actions.mute`), evaluated against the per-turn `TurnCapabilities`, so moderation tools disappear when the Bot is not an administrator and return when it is; the icqq/qq keyword boost in tool selection is removed and the icqq group-admin tools are tagged. The `icqq` command-line special case in the exec policy is now a generic `registerSensitiveExecCommand` rule registered by the icqq plugin. `EndpointCapabilities` gains a serializable per-kind `kinds` view. Adapters without a profile keep their previous behaviour (their derived profile also reads the management ports they implement).
+- 4fe49b5: 支持配置按需生效：分离保存与有效版本，独立变更先应用，账号资料更新保留连接，模型按回合使用确定版本；Console 返回结构化应用结果。监听改为仅显式 --watch 启用，开发模板显式选择源码和配置监听。
+
+  自变更消费配置应用回执，避免已处理配置被二次重载；持久化本次写入修订和应用结果，未知结果或修订冲突时停止自动续作并保留现场，恢复不会覆盖未经本次变更确认的配置。
+
+- 2766d09: New `set_group_admin` Agent tool in `icqq-group-admin`: set (`enabled: true`) or remove (`enabled: false`) a QQ group administrator. It is injected only when the bot is the current group's owner (not when it is merely an admin), requires `role(master,admin,trusted,owner)` plus per-call human approval, and re-checks live roles before calling `setGroupAdmin` (bot still owner; promote only regular members; demote only current admins). An unconfirmed platform result is reported as such and never retried automatically.
+- Updated dependencies [b249e5e]
+- Updated dependencies [57661f6]
+- Updated dependencies [cbd3f14]
+- Updated dependencies [299863a]
+- Updated dependencies [aaa93d7]
+- Updated dependencies [4fe49b5]
+- Updated dependencies [cce07db]
+- Updated dependencies [b652db3]
+- Updated dependencies [0315ba0]
+- Updated dependencies [00be764]
+  - @zhin.js/adapter-onebot-events@0.0.1
+  - @zhin.js/core@1.1.56
+  - @zhin.js/adapter@1.1.28
+  - @zhin.js/im-contract@1.1.11
+  - @zhin.js/tool@1.1.15
+  - @zhin.js/skill@1.1.13
+  - @zhin.js/feature-kit@1.1.12
+  - @zhin.js/client@1.1.24
+  - @zhin.js/page@1.1.14
+  - @zhin.js/agent-feature@1.1.13
+  - @zhin.js/permission@1.1.12
+
 ## 1.1.21
 
 ### Patch Changes

package/PERMITS.md

@@ -12,6 +12,7 @@
 | `icqq-group-admin` / `recall_member_message` | master/admin/trusted/owner | 无逐次审批；Bot 管理员可撤回普通成员，Bot 群主可撤回管理员或普通成员，执行前实时检查 |
 | `icqq-group-admin` / `group_leave` | 仅 master | 当前群，每次人工审批；Bot 为群主时拒绝，以免 SDK 解散群 |
 | `icqq-group-admin` / `group_kick` | master/admin/trusted/owner | 每次人工审批；执行前检查 Bot 与目标成员角色 |
+| `icqq-group-admin` / `set_group_admin` | master/admin/trusted/owner | 仅 Bot 为当前群群主时注入；每次人工审批；执行前实时检查 Bot 仍为群主、设管理员目标为普通成员、取消目标为现任管理员 |
 
 已配置的自动群审核独立按获准规则执行撤回；上述工具不新增审核触发条件、敏感类别、处罚或目标群。Bot 对自己的消息始终不需要群管权限；平台拒绝或未确认时不能宣称撤回成功，也不自动重试。
 

package/README.md

@@ -171,7 +171,7 @@ IM turn 的场景，应通过 Host 提供的显式账号作用域操作，不能
 
 ICQQ Agent 可按需加载 `icqq-conversation` 查询当前群／频道和 Bot 自身角色。`icqq-messages` 提供当前会话的引用回复、真实消息合并转发和撤回自己发言；自己的消息撤回不要求群管身份或逐次审批，时限由平台决定。
 
-`icqq-group-admin` 新增撤回他人消息与退群：前者保留群管发起权限、实时平台角色检查，无需逐次审批；退群仅主人可发起、每次审批，Bot 为群主时拒绝执行。引用／转发走统一发送链路，不支持跨会话转发。当前 guild-channel 接入仅提供身份查询，不能使用这些群／私聊操作。详见 [权限与能力说明](./PERMITS.md)。
+`icqq-group-admin` 新增撤回他人消息与退群：前者保留群管发起权限、实时平台角色检查，无需逐次审批；退群仅主人可发起、每次审批，Bot 为群主时拒绝执行。引用／转发走统一发送链路，不支持跨会话转发。`set_group_admin` 设置／取消管理员仅在 Bot 为当前群群主时注入，每次人工审批并实时复核角色。当前 guild-channel 接入仅提供身份查询，不能使用这些群／私聊操作。详见 [权限与能力说明](./PERMITS.md)。
 
 ## Console 页面
 

package/adapters/icqq/index.js

@@ -1,38 +1,109 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { IcqqAdapter } from "../../lib/adapter.js";
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
-import {} from "../../lib/protocol.js";
+import { defineAdapter, resolvePlatformRole } from 'zhin.js/adapter';
+import { IcqqAdapter } from "../../lib/adapter.js";
 export { IcqqEndpoint } from "../../lib/endpoint.js";
+/** Group reactions take QQ system face ids. Private chats have none. */
+const ICQQ_REACTIONS = [
+    { value: '76', label: '赞' }, { value: '66', label: '爱心' }, { value: '124', label: 'OK' },
+    { value: '99', label: '鼓掌' }, { value: '144', label: '喝彩' }, { value: '320', label: '庆祝' },
+    { value: '319', label: '比心' }, { value: '299', label: '牛啊' }, { value: '297', label: '拜谢' },
+    { value: '182', label: '笑哭' }, { value: '179', label: 'doge' }, { value: '264', label: '捂脸' },
+    { value: '271', label: '吃瓜' }, { value: '269', label: '暗中观察' }, { value: '268', label: '问号脸' },
+    { value: '270', label: 'emm' }, { value: '106', label: '委屈' }, { value: '285', label: '摸鱼' },
+    { value: '104', label: '哈欠' }, { value: '267', label: '头秃' }, { value: '326', label: '生气' },
+];
+/** QQ group mute: 1 minute to 30 days (0 lifts it, which is the `unmute` action). */
+const ICQQ_MUTE_SECONDS = { min: 60, max: 2592000 };
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    operations: ['recall', 'reaction'],
-    segments: {
-        // Canonical types formatOutboundBody encodes; markdown / keyboard degrade to text first.
-        supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
-        outboundMedia: ['base64', 'url', 'path'],
-        interactive: 'text',
-        // QQ group reactions take system face ids; private chats have no reactions.
-        reaction: {
-            scopes: ['group'],
-            values: [
-                { value: '76', label: '赞' }, { value: '66', label: '爱心' }, { value: '124', label: 'OK' },
-                { value: '99', label: '鼓掌' }, { value: '144', label: '喝彩' }, { value: '320', label: '庆祝' },
-                { value: '319', label: '比心' }, { value: '299', label: '牛啊' }, { value: '297', label: '拜谢' },
-                { value: '182', label: '笑哭' }, { value: '179', label: 'doge' }, { value: '264', label: '捂脸' },
-                { value: '271', label: '吃瓜' }, { value: '269', label: '暗中观察' }, { value: '268', label: '问号脸' },
-                { value: '270', label: 'emm' }, { value: '106', label: '委屈' }, { value: '285', label: '摸鱼' },
-                { value: '104', label: '哈欠' }, { value: '267', label: '头秃' }, { value: '326', label: '生气' },
-            ],
+    profile: {
+        default: {
+            messaging: {
+                segments: {
+                    // Canonical types formatOutboundBody encodes; markdown / keyboard degrade to text first.
+                    supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
+                    outboundMedia: ['base64', 'url', 'path'],
+                    interactive: 'text',
+                    reaction: { scopes: ['group'], values: ICQQ_REACTIONS },
+                    model: {
+                        share: {
+                            fields: ['description', 'image', 'audio', 'platform'],
+                            hint: 'renders as a QQ link card. For a song, set audio to the playable link, image to the cover, description to the artist and platform to its music service (qq, netease, kugou, kuwo or migu), copied from tool results; leave a field "" when you have no real value.',
+                        },
+                    },
+                },
+                mention: { user: true },
+                quote: true,
+                recall: { timeLimitSeconds: 120 },
+                forward: {},
+            },
+            scene: { roles: { owner: 'owner', admin: 'admin', member: 'member' } },
+            actions: {
+                recall: { scopes: ['private', 'group'], params: { timeLimitSeconds: 120 } },
+                quoteReply: { scopes: ['private', 'group'] },
+                forward: { scopes: ['private', 'group'] },
+                poke: { scopes: ['private', 'group'] },
+            },
+            delivery: { send: true, proactive: true, spool: false },
+        },
+        private: {
+            // A private chat has no reactions, so feedback is a short status message.
+            feedback: { mode: 'status-message', text: '⏳' },
+            events: { emit: ['message.recalled', 'poke'] },
         },
-        model: {
-            share: {
-                fields: ['description', 'image', 'audio', 'platform'],
-                hint: 'renders as a QQ link card. For a song, set audio to the playable link, image to the cover, description to the artist and platform to its music service (qq, netease, kugou, kuwo or migu), copied from tool results; leave a field "" when you have no real value.',
+        group: {
+            messaging: { reaction: { emojis: ICQQ_REACTIONS.map((item) => item.value) } },
+            scene: {
+                groupInfo: true,
+                memberProfile: true,
+                card: true,
+                title: true,
+                mute: { durationSeconds: ICQQ_MUTE_SECONDS, all: true },
+            },
+            actions: {
+                // Own messages need no role; recalling others' needs an admin (narrowed in resolveCapabilities).
+                recall: { scopes: ['private', 'group'], params: { timeLimitSeconds: 120, others: true } },
+                reaction: { scopes: ['group'], params: { emojis: ICQQ_REACTIONS.map((item) => item.value), own: true, others: true, cancellable: true } },
+                mute: { scopes: ['group'], requiresRole: 'admin', params: { durationSeconds: ICQQ_MUTE_SECONDS } },
+                unmute: { scopes: ['group'], requiresRole: 'admin' },
+                muteAll: { scopes: ['group'], requiresRole: 'admin' },
+                kick: { scopes: ['group'], requiresRole: 'admin' },
+                setCard: { scopes: ['group'], requiresRole: 'admin' },
+                setTitle: { scopes: ['group'], requiresRole: 'owner' },
+                setAdmin: { scopes: ['group'], requiresRole: 'owner' },
+                essence: { scopes: ['group'], requiresRole: 'admin' },
+                announce: { scopes: ['group'], requiresRole: 'admin' },
+                invite: { scopes: ['group'] },
+            },
+            events: {
+                emit: ['member.joined', 'member.left', 'member.role_changed', 'member.muted', 'message.recalled', 'poke'],
+            },
+            feedback: { mode: 'reaction', emoji: '⏳' },
+            prompt: {
+                text: '被禁言或不是管理员时不要尝试管理类操作；头衔和设/撤管理员只有群主能做；邀请只能邀请你的好友。',
             },
         },
+        channel: {
+            // Guild channels: text and media in and out; no recall, poke, forward, reaction or management actions.
+            actions: {
+                recall: false,
+                poke: false,
+                forward: false,
+            },
+            feedback: { mode: 'none' },
+        },
+    },
+    resolveCapabilities({ capabilities, facts }) {
+        if (!capabilities.actions?.recall)
+            return undefined;
+        const role = resolvePlatformRole(capabilities.scene, facts.bot?.platformRole);
+        // Unknown role fails closed, like every other role-gated action.
+        if (role === 'owner' || role === 'admin')
+            return undefined;
+        return { actions: { recall: { params: { others: false } } } };
     },
     createAdapter: context => new IcqqAdapter(context),
 });

package/adapters/icqq/index.ts

@@ -1,42 +1,112 @@
-import { IcqqAdapter } from '../../src/adapter.js';
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
-import {
-  type IcqqEndpointConfig,
-} from '../../src/protocol.js';
+import { defineAdapter, resolvePlatformRole } from 'zhin.js/adapter';
+import { IcqqAdapter } from '../../src/adapter.js';
+import type { IcqqEndpointConfig } from '../../src/protocol.js';
 
 export { IcqqEndpoint } from '../../src/endpoint.js';
 export type { IcqqEndpointOptions } from '../../src/endpoint.js';
 
+/** Group reactions take QQ system face ids. Private chats have none. */
+const ICQQ_REACTIONS = [
+  { value: '76', label: '赞' }, { value: '66', label: '爱心' }, { value: '124', label: 'OK' },
+  { value: '99', label: '鼓掌' }, { value: '144', label: '喝彩' }, { value: '320', label: '庆祝' },
+  { value: '319', label: '比心' }, { value: '299', label: '牛啊' }, { value: '297', label: '拜谢' },
+  { value: '182', label: '笑哭' }, { value: '179', label: 'doge' }, { value: '264', label: '捂脸' },
+  { value: '271', label: '吃瓜' }, { value: '269', label: '暗中观察' }, { value: '268', label: '问号脸' },
+  { value: '270', label: 'emm' }, { value: '106', label: '委屈' }, { value: '285', label: '摸鱼' },
+  { value: '104', label: '哈欠' }, { value: '267', label: '头秃' }, { value: '326', label: '生气' },
+];
+
+/** QQ group mute: 1 minute to 30 days (0 lifts it, which is the `unmute` action). */
+const ICQQ_MUTE_SECONDS = { min: 60, max: 2592000 } as const;
+
 export default defineAdapter<IcqqEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
-  operations: ['recall', 'reaction'],
-  segments: {
-    // Canonical types formatOutboundBody encodes; markdown / keyboard degrade to text first.
-    supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
-    outboundMedia: ['base64', 'url', 'path'],
-    interactive: 'text',
-    // QQ group reactions take system face ids; private chats have no reactions.
-    reaction: {
-      scopes: ['group'],
-      values: [
-        { value: '76', label: '赞' }, { value: '66', label: '爱心' }, { value: '124', label: 'OK' },
-        { value: '99', label: '鼓掌' }, { value: '144', label: '喝彩' }, { value: '320', label: '庆祝' },
-        { value: '319', label: '比心' }, { value: '299', label: '牛啊' }, { value: '297', label: '拜谢' },
-        { value: '182', label: '笑哭' }, { value: '179', label: 'doge' }, { value: '264', label: '捂脸' },
-        { value: '271', label: '吃瓜' }, { value: '269', label: '暗中观察' }, { value: '268', label: '问号脸' },
-        { value: '270', label: 'emm' }, { value: '106', label: '委屈' }, { value: '285', label: '摸鱼' },
-        { value: '104', label: '哈欠' }, { value: '267', label: '头秃' }, { value: '326', label: '生气' },
-      ],
+  profile: {
+    default: {
+      messaging: {
+        segments: {
+          // Canonical types formatOutboundBody encodes; markdown / keyboard degrade to text first.
+          supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
+          outboundMedia: ['base64', 'url', 'path'],
+          interactive: 'text',
+          reaction: { scopes: ['group'], values: ICQQ_REACTIONS },
+          model: {
+            share: {
+              fields: ['description', 'image', 'audio', 'platform'],
+              hint: 'renders as a QQ link card. For a song, set audio to the playable link, image to the cover, description to the artist and platform to its music service (qq, netease, kugou, kuwo or migu), copied from tool results; leave a field "" when you have no real value.',
+            },
+          },
+        },
+        mention: { user: true },
+        quote: true,
+        recall: { timeLimitSeconds: 120 },
+        forward: {},
+      },
+      scene: { roles: { owner: 'owner', admin: 'admin', member: 'member' } },
+      actions: {
+        recall: { scopes: ['private', 'group'], params: { timeLimitSeconds: 120 } },
+        quoteReply: { scopes: ['private', 'group'] },
+        forward: { scopes: ['private', 'group'] },
+        poke: { scopes: ['private', 'group'] },
+      },
+      delivery: { send: true, proactive: true, spool: false },
+    },
+    private: {
+      // A private chat has no reactions, so feedback is a short status message.
+      feedback: { mode: 'status-message', text: '⏳' },
+      events: { emit: ['message.recalled', 'poke'] },
     },
-    model: {
-      share: {
-        fields: ['description', 'image', 'audio', 'platform'],
-        hint: 'renders as a QQ link card. For a song, set audio to the playable link, image to the cover, description to the artist and platform to its music service (qq, netease, kugou, kuwo or migu), copied from tool results; leave a field "" when you have no real value.',
+    group: {
+      messaging: { reaction: { emojis: ICQQ_REACTIONS.map((item) => item.value) } },
+      scene: {
+        groupInfo: true,
+        memberProfile: true,
+        card: true,
+        title: true,
+        mute: { durationSeconds: ICQQ_MUTE_SECONDS, all: true },
+      },
+      actions: {
+        // Own messages need no role; recalling others' needs an admin (narrowed in resolveCapabilities).
+        recall: { scopes: ['private', 'group'], params: { timeLimitSeconds: 120, others: true } },
+        reaction: { scopes: ['group'], params: { emojis: ICQQ_REACTIONS.map((item) => item.value), own: true, others: true, cancellable: true } },
+        mute: { scopes: ['group'], requiresRole: 'admin', params: { durationSeconds: ICQQ_MUTE_SECONDS } },
+        unmute: { scopes: ['group'], requiresRole: 'admin' },
+        muteAll: { scopes: ['group'], requiresRole: 'admin' },
+        kick: { scopes: ['group'], requiresRole: 'admin' },
+        setCard: { scopes: ['group'], requiresRole: 'admin' },
+        setTitle: { scopes: ['group'], requiresRole: 'owner' },
+        setAdmin: { scopes: ['group'], requiresRole: 'owner' },
+        essence: { scopes: ['group'], requiresRole: 'admin' },
+        announce: { scopes: ['group'], requiresRole: 'admin' },
+        invite: { scopes: ['group'] },
+      },
+      events: {
+        emit: ['member.joined', 'member.left', 'member.role_changed', 'member.muted', 'message.recalled', 'poke'],
+      },
+      feedback: { mode: 'reaction', emoji: '⏳' },
+      prompt: {
+        text: '被禁言或不是管理员时不要尝试管理类操作；头衔和设/撤管理员只有群主能做；邀请只能邀请你的好友。',
       },
     },
+    channel: {
+      // Guild channels: text and media in and out; no recall, poke, forward, reaction or management actions.
+      actions: {
+        recall: false,
+        poke: false,
+        forward: false,
+      },
+      feedback: { mode: 'none' },
+    },
+  },
+  resolveCapabilities({ capabilities, facts }) {
+    if (!capabilities.actions?.recall) return undefined;
+    const role = resolvePlatformRole(capabilities.scene, facts.bot?.platformRole);
+    // Unknown role fails closed, like every other role-gated action.
+    if (role === 'owner' || role === 'admin') return undefined;
+    return { actions: { recall: { params: { others: false } } } };
   },
   createAdapter: context => new IcqqAdapter(context),
 });

package/agents/icqq/messages.js

@@ -85,6 +85,26 @@ export const messages = createMessages({
         "zh-CN": "当前权限或成员状态不允许踢出",
         "en": "Current permissions or member status do not allow removal"
     },
+    "adminSet": {
+        "zh-CN": "已将 {p0} 设为管理员",
+        "en": "Member {p0} is now an administrator"
+    },
+    "adminUnset": {
+        "zh-CN": "已取消 {p0} 的管理员",
+        "en": "Administrator role removed from {p0}"
+    },
+    "adminUnconfirmed": {
+        "zh-CN": "平台未确认管理员变更成功，请勿自动重试",
+        "en": "The platform did not confirm the administrator change; do not retry automatically"
+    },
+    "adminForbidden": {
+        "zh-CN": "机器人不是群主，无法设置或取消管理员",
+        "en": "The bot must be the group owner to set or remove administrators"
+    },
+    "adminTargetInvalid": {
+        "zh-CN": "目标成员身份不允许本次变更：设为管理员需是普通成员，取消管理员需是现任管理员",
+        "en": "The member's role does not allow this change: promotion requires a regular member, removal requires a current administrator"
+    },
     "anonymousDisabled": {
         "zh-CN": "已关闭匿名聊天",
         "en": "Anonymous chat disabled"

package/agents/icqq/messages.ts

@@ -85,6 +85,26 @@ export const messages = createMessages({
     "zh-CN": "当前权限或成员状态不允许踢出",
     "en": "Current permissions or member status do not allow removal"
   },
+  "adminSet": {
+    "zh-CN": "已将 {p0} 设为管理员",
+    "en": "Member {p0} is now an administrator"
+  },
+  "adminUnset": {
+    "zh-CN": "已取消 {p0} 的管理员",
+    "en": "Administrator role removed from {p0}"
+  },
+  "adminUnconfirmed": {
+    "zh-CN": "平台未确认管理员变更成功，请勿自动重试",
+    "en": "The platform did not confirm the administrator change; do not retry automatically"
+  },
+  "adminForbidden": {
+    "zh-CN": "机器人不是群主，无法设置或取消管理员",
+    "en": "The bot must be the group owner to set or remove administrators"
+  },
+  "adminTargetInvalid": {
+    "zh-CN": "目标成员身份不允许本次变更：设为管理员需是普通成员，取消管理员需是现任管理员",
+    "en": "The member's role does not allow this change: promotion requires a regular member, removal requires a current administrator"
+  },
   "anonymousDisabled": {
     "zh-CN": "已关闭匿名聊天",
     "en": "Anonymous chat disabled"

package/agents/icqq/skills/icqq-group-admin/SKILL.md

@@ -11,10 +11,13 @@ keywords:
   - 公告
   - 精华
   - 退群
+  - 设管理员
+  - 取消管理员
   - 撤回他人消息
 tools:
   - group_invite
   - group_kick
+  - set_group_admin
   - set_mute
   - set_title
   - set_anonymous
@@ -35,6 +38,8 @@ scopes:
 
 已配置的自动审核流程可对入群 10 分钟内的明确广告直接踢出；该例外由审核流程核验，不授权本技能或普通对话绕过人工审批。
 
+`set_group_admin` 仅在你是当前群群主时注入（你只是管理员时不可见），沿用 master/admin/trusted/owner 发起权限，每次人工审批并展示目标群、成员、设/撤方向和理由。执行前实时复核：你必须仍是群主；设为管理员只针对普通成员，取消只针对现任管理员；平台未确认时不宣称成功、不自动重试。
+
 `group_leave` 仅主人（master）可发起，每次人工审批，只能退出当前群。你为群主时拒绝执行，因为 SDK 的退群会解散群。
 
 `recall_member_message` 沿用 master/admin/trusted/owner 发起权限，无需逐次审批；目标固定在当前群中的真实消息。执行前实时查询你与目标成员的角色：管理员只能撤回普通成员，群主可撤回管理员或普通成员。平台时限与执行结果仍然有效，不自动重试未确认的结果。

package/agents/icqq/skills/icqq-group-admin/tools/announce/index.js

@@ -9,6 +9,8 @@ export default defineAgentTool({
         content: z.string().describe('公告内容'),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.announce'],
     requiresApproval: 'once',
     scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],

package/agents/icqq/skills/icqq-group-admin/tools/announce/index.ts

@@ -8,6 +8,8 @@ export default defineAgentTool<{ group_id: number; content: string }>({
     content: z.string().describe('公告内容'),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.announce'],
   requiresApproval: 'once',
   scopes:['group'],
   permissions: ['role(master,admin,trusted,owner)'],

package/agents/icqq/skills/icqq-group-admin/tools/essence/index.js

@@ -9,6 +9,8 @@ export default defineAgentTool({
         action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.essence'],
     requiresApproval: 'once',
     scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],

package/agents/icqq/skills/icqq-group-admin/tools/essence/index.ts

@@ -8,6 +8,8 @@ export default defineAgentTool<{ message_id: string; action: 'add' | 'remove' }>
     action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.essence'],
   requiresApproval: 'once',
   scopes:['group'],
   permissions: ['role(master,admin,trusted,owner)'],

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

@@ -10,6 +10,8 @@ export default defineAgentTool({
         reason: z.string().min(1).describe('本次踢人的具体原因，随目标群和成员一起供人工确认'),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.kick'],
     scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],
     requiresApproval: 'human',

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

@@ -9,6 +9,8 @@ export default defineAgentTool<{ group_id: number; user_id: number; reason: stri
     reason: z.string().min(1).describe('本次踢人的具体原因，随目标群和成员一起供人工确认'),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.kick'],
   scopes:['group'],
   permissions: ['role(master,admin,trusted,owner)'],
   requiresApproval: 'human',

package/agents/icqq/skills/icqq-group-admin/tools/recall_member_message/index.js

@@ -6,6 +6,8 @@ import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
     description: '撤回当前 QQ 群内他人的真实消息；需调用方具备群管发起权限及你具备实时平台权限，无需逐次审批',
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.recall.others'],
     scopes: ['group'],
     currentConversationBotRoles: ['owner', 'admin'],
     permissions: ['role(master,admin,trusted,owner)'],

package/agents/icqq/skills/icqq-group-admin/tools/recall_member_message/index.ts

@@ -6,6 +6,8 @@ import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
   description: '撤回当前 QQ 群内他人的真实消息；需调用方具备群管发起权限及你具备实时平台权限，无需逐次审批',
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.recall.others'],
   scopes: ['group'],
   currentConversationBotRoles: ['owner', 'admin'],
   permissions: ['role(master,admin,trusted,owner)'],

package/agents/icqq/skills/icqq-group-admin/tools/set_group_admin/index.js

@@ -0,0 +1,43 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { messages as t } from "../../../../messages.js";
+import { freshMember } from "../../../../members.js";
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '设置或取消 QQ 群管理员（enabled=true 设为管理员，false 取消管理员）；仅你是该群群主时可用，每次人工审批',
+    inputSchema: z.object({
+        group_id: z.number().describe('目标群号'),
+        user_id: z.number().describe('目标成员 QQ号'),
+        enabled: z.boolean().describe('true 设为管理员（目标须为普通成员）；false 取消管理员（目标须为现任管理员）'),
+        reason: z.string().min(1).describe('本次设置或取消管理员的具体原因，随目标群和成员一起供人工确认'),
+    }),
+    adapter: 'icqq',
+    scopes: ['group'],
+    requiresCapabilities: ['actions.setAdmin'],
+    currentConversationBotRoles: ['owner'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'human',
+    async execute({ group_id, user_id, enabled }, context) {
+        const client = context.$client;
+        if (user_id === client.uin)
+            return { success: false, message: t(context.locale, 'adminForbidden') };
+        const [self, member] = await Promise.all([freshMember(client, group_id, client.uin), freshMember(client, group_id, user_id)]);
+        if (self?.role !== 'owner')
+            return { success: false, message: t(context.locale, 'adminForbidden') };
+        if (!member)
+            return { success: false, message: t(context.locale, 'memberMissing') };
+        if (member.role !== (enabled ? 'member' : 'admin'))
+            return { success: false, message: t(context.locale, 'adminTargetInvalid') };
+        context.signal.throwIfAborted();
+        let confirmed = false;
+        try {
+            confirmed = await client.setGroupAdmin(group_id, user_id, enabled);
+        }
+        catch {
+            confirmed = false;
+        }
+        if (!confirmed)
+            return { success: false, message: t(context.locale, 'adminUnconfirmed') };
+        return { success: true, message: t(context.locale, enabled ? 'adminSet' : 'adminUnset', { p0: user_id }) };
+    },
+});

package/agents/icqq/skills/icqq-group-admin/tools/set_group_admin/index.ts

@@ -0,0 +1,36 @@
+import { messages as t } from "../../../../messages.js";
+import { freshMember } from "../../../../members.js";
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool<{ group_id: number; user_id: number; enabled: boolean; reason: string }>({
+  description: '设置或取消 QQ 群管理员（enabled=true 设为管理员，false 取消管理员）；仅你是该群群主时可用，每次人工审批',
+  inputSchema: z.object({
+    group_id: z.number().describe('目标群号'),
+    user_id: z.number().describe('目标成员 QQ号'),
+    enabled: z.boolean().describe('true 设为管理员（目标须为普通成员）；false 取消管理员（目标须为现任管理员）'),
+    reason: z.string().min(1).describe('本次设置或取消管理员的具体原因，随目标群和成员一起供人工确认'),
+  }),
+  adapter: 'icqq',
+  scopes: ['group'],
+  requiresCapabilities: ['actions.setAdmin'],
+  currentConversationBotRoles: ['owner'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'human',
+  async execute({ group_id, user_id, enabled }, context) {
+    const client = context.$client;
+    if (user_id === client.uin) return { success: false, message: t(context.locale, 'adminForbidden') };
+    const [self, member] = await Promise.all([freshMember(client, group_id, client.uin), freshMember(client, group_id, user_id)]);
+    if (self?.role !== 'owner') return { success: false, message: t(context.locale, 'adminForbidden') };
+    if (!member) return { success: false, message: t(context.locale, 'memberMissing') };
+    if (member.role !== (enabled ? 'member' : 'admin')) return { success: false, message: t(context.locale, 'adminTargetInvalid') };
+    context.signal.throwIfAborted();
+    let confirmed = false;
+    try {
+      confirmed = await client.setGroupAdmin(group_id, user_id, enabled);
+    } catch {
+      confirmed = false;
+    }
+    if (!confirmed) return { success: false, message: t(context.locale, 'adminUnconfirmed') };
+    return { success: true, message: t(context.locale, enabled ? 'adminSet' : 'adminUnset', { p0: user_id }) };
+  },
+});

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

@@ -11,6 +11,8 @@ export default defineAgentTool({
         duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.mute'],
     scopes: ['group'],
     requiresApproval: 'always',
     async execute({ group_id, user_id, duration }, context) {

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

@@ -10,6 +10,8 @@ export default defineAgentTool<{ group_id: number; user_id: number; duration?: n
     duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.mute'],
   scopes:['group'],
   requiresApproval: 'always',
   async execute({ group_id, user_id, duration }, context) {

package/agents/icqq/skills/icqq-group-admin/tools/set_title/index.js

@@ -12,6 +12,8 @@ export default defineAgentTool({
         duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.setTitle'],
     scopes: ['group'],
     requiresApproval: 'always',
     async execute({ group_id, user_id, title, duration }, context) {

package/agents/icqq/skills/icqq-group-admin/tools/set_title/index.ts

@@ -11,6 +11,8 @@ export default defineAgentTool<{ group_id: number; user_id: number; title: strin
     duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.setTitle'],
   scopes:['group'],
   requiresApproval: 'always',
   async execute({ group_id, user_id, title, duration }, context) {

package/lib/endpoint.js

@@ -2,7 +2,8 @@ import { parseGroupMessageId, } from '@icqqjs/icqq';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createEndpointSpecification, endpointSpec, createEndpointOperation, } from 'zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent } from '@zhin.js/adapter-onebot-events';
+import { buildSystem, toCanonicalSegments } from '@zhin.js/core';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
@@ -13,6 +14,7 @@ import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guil
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
 import { formatInboundContent, formatOutboundMessageParts, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
+import { createIcqqActionPorts } from './group-actions.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 import { createIcqqSelfProfile } from './self-profile.js';
@@ -108,6 +110,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
                 throw new Error('QQ did not confirm the group notice');
             }
         },
+        ...createIcqqActionPorts(() => this),
     });
     #control = Object.freeze({
         recall: async ({ message, signal }) => {

package/lib/group-actions.d.ts

@@ -0,0 +1,10 @@
+import type { Client } from '@icqqjs/icqq';
+import { type EndpointManagement } from 'zhin.js/adapter';
+type ActionPorts = Pick<EndpointManagement, 'pokeUser' | 'unmuteGroupMember' | 'muteAllGroupMembers' | 'setGroupCard' | 'setGroupTitle' | 'setGroupEssence' | 'inviteGroupMember'>;
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export declare function createIcqqActionPorts(getClient: () => Client): ActionPorts;
+export {};

package/lib/group-actions.js

@@ -0,0 +1,94 @@
+import { createEndpointOperation } from 'zhin.js/adapter';
+function numericId(value) {
+    const id = Number(value);
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id))
+        throw new Error('Invalid QQ identifier');
+    return id;
+}
+/** Uncached member lookup; `pickMember` and the cached roster would report stale roles. */
+async function freshMember(operation, client, group, user) {
+    try {
+        const member = await operation.prepare(() => client.getGroupMemberInfo(group, user, true));
+        return member.user_id === user && member.group_id === group ? member : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function requireBotRole(operation, client, group, roles, message) {
+    const self = await freshMember(operation, client, group, client.uin);
+    if (!self || !roles.includes(self.role))
+        throw new Error(message);
+}
+function confirmed(ok, what) {
+    if (ok === false)
+        throw new Error(`QQ did not confirm ${what}`);
+}
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export function createIcqqActionPorts(getClient) {
+    return {
+        async pokeUser({ userId, groupId, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const user = numericId(userId);
+            confirmed(groupId === undefined
+                ? await operation.run(() => client.pickFriend(user).poke(false))
+                : await operation.run(() => client.sendGroupPoke(numericId(groupId), user)), 'poke');
+        },
+        async unmuteGroupMember({ groupId, userId, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+            confirmed(await operation.run(() => client.setGroupBan(group, numericId(userId), 0)), 'unmute');
+        },
+        async muteAllGroupMembers({ groupId, enabled, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+            confirmed(await operation.run(() => client.setGroupWholeBan(group, enabled)), 'whole-group mute');
+        },
+        async setGroupCard({ groupId, userId, card, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            const user = numericId(userId);
+            if (user !== client.uin)
+                await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+            confirmed(await operation.run(() => client.setGroupCard(group, user, card)), 'card change');
+        },
+        async setGroupTitle({ groupId, userId, title, durationSeconds, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            const user = numericId(userId);
+            await requireBotRole(operation, client, group, ['owner'], 'Only the group owner can set special titles');
+            if (!await freshMember(operation, client, group, user))
+                throw new Error('Target is not a group member');
+            confirmed(await operation.run(() => client.setGroupSpecialTitle(group, user, title, durationSeconds ?? -1)), 'title change');
+        },
+        async setGroupEssence({ groupId, messageId, enabled, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            await requireBotRole(operation, client, numericId(groupId), ['owner', 'admin'], 'Bot is not a group admin');
+            if (enabled)
+                await operation.run(() => client.setEssenceMessage(messageId));
+            else
+                await operation.run(() => client.removeEssenceMessage(messageId));
+        },
+        async inviteGroupMember({ groupId, userId, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            const user = numericId(userId);
+            if (await freshMember(operation, client, group, user))
+                throw new Error('Target is already a group member');
+            confirmed(await operation.run(() => client.inviteFriend(group, user)), 'invitation');
+        },
+    };
+}

package/lib/sensitive-commands.d.ts

@@ -0,0 +1,8 @@
+import type { SensitiveExecCommandRule } from '@zhin.js/agent';
+/**
+ * The `icqq` command-line client can kick members, move money and delete files. Under an `allowlist`
+ * exec policy its non-sensitive subcommands run freely, while these need owner approval (ADR 0044:
+ * this knowledge lives with the adapter, the exec policy only reads the registered rule).
+ */
+export declare const ICQQ_SENSITIVE_SUBCOMMAND_REGEXES: readonly RegExp[];
+export declare const icqqSensitiveExecRule: SensitiveExecCommandRule;

package/lib/sensitive-commands.js

@@ -0,0 +1,16 @@
+/**
+ * The `icqq` command-line client can kick members, move money and delete files. Under an `allowlist`
+ * exec policy its non-sensitive subcommands run freely, while these need owner approval (ADR 0044:
+ * this knowledge lives with the adapter, the exec policy only reads the registered rule).
+ */
+export const ICQQ_SENSITIVE_SUBCOMMAND_REGEXES = Object.freeze([
+    /\bicqq\s+friend\s+(?:delete|block|move)\b/i,
+    /\bicqq\s+group\s+(?:kick|mute|set|admin|announce|transfer|quit|dissolve|invite)\b/i,
+    /\bicqq\s+(?:request|wallet|pay|recall)\b/i,
+    /\bicqq\s+file\s+(?:upload|delete)\b/i,
+    /\bicqq\s+gfs\b.*\b(?:rm|delete|del)\b/i,
+]);
+export const icqqSensitiveExecRule = Object.freeze({
+    command: 'icqq',
+    sensitive: ICQQ_SENSITIVE_SUBCOMMAND_REGEXES,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.21",
+  "version": "1.1.22",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,32 +33,37 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.27",
-    "@zhin.js/agent-feature": "1.1.12",
-    "@zhin.js/client": "1.1.23",
+    "@zhin.js/adapter-onebot-events": "0.0.1",
+    "@zhin.js/adapter": "1.1.28",
+    "@zhin.js/agent-feature": "1.1.13",
+    "@zhin.js/client": "1.1.24",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.55",
-    "@zhin.js/feature-kit": "1.1.11",
-    "@zhin.js/im-contract": "1.1.10",
+    "@zhin.js/core": "1.1.56",
+    "@zhin.js/feature-kit": "1.1.12",
+    "@zhin.js/im-contract": "1.1.11",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.13",
-    "@zhin.js/permission": "1.1.11",
-    "@zhin.js/skill": "1.1.12",
-    "@zhin.js/tool": "1.1.14"
+    "@zhin.js/page": "1.1.14",
+    "@zhin.js/permission": "1.1.12",
+    "@zhin.js/skill": "1.1.13",
+    "@zhin.js/tool": "1.1.15"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.27",
-    "@zhin.js/command": "^1.1.13",
-    "@zhin.js/core": "^1.1.55",
-    "@zhin.js/prompt-section": "^1.1.11",
-    "zhin.js": "^1.1.20"
+    "@zhin.js/adapter": "^1.1.28",
+    "@zhin.js/agent": "^1.1.47",
+    "@zhin.js/command": "^1.1.14",
+    "@zhin.js/core": "^1.1.56",
+    "@zhin.js/prompt-section": "^1.1.12",
+    "zhin.js": "^1.1.21"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
       "optional": true
     },
+    "@zhin.js/agent": {
+      "optional": true
+    },
     "@zhin.js/command": {
       "optional": true
     },
@@ -78,8 +83,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/prompt-section": "1.1.11",
-    "zhin.js": "1.1.20"
+    "@zhin.js/agent": "1.1.47",
+    "@zhin.js/prompt-section": "1.1.12",
+    "zhin.js": "1.1.21"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -1,9 +1,12 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
+import { registerSensitiveExecCommand } from '@zhin.js/agent';
 import { createIcqqConsoleRpc } from "./lib/console.js";
+import { icqqSensitiveExecRule } from "./lib/sensitive-commands.js";
 export default definePlugin({
     name: 'icqq',
+    configUpdate: { featurePaths: [['nickname'], ['profile'], ['endpoints']] },
     metadata: {
         displayName: 'ICQQ Adapter',
     },
@@ -12,6 +15,10 @@ export default definePlugin({
         const disposePlatform = context.resources.has(permissionHostToken)
             ? context.resources.use(permissionHostToken).registerPlatform('icqq', createSceneRolePlatformChecker())
             : undefined;
-        return disposePlatform;
+        const disposeExecRule = registerSensitiveExecCommand(icqqSensitiveExecRule);
+        return () => {
+            disposeExecRule();
+            disposePlatform?.();
+        };
     },
 });

package/src/endpoint.ts

@@ -33,7 +33,8 @@ import {
   type EndpointGroupNoticeRequest,
 } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent } from '@zhin.js/adapter-onebot-events';
+import { buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
 import { EndpointDeliveryError, type EndpointSendPart, type EndpointSendResult, type MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -77,6 +78,7 @@ import {
 } from './protocol.js';
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
 import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
+import { createIcqqActionPorts } from './group-actions.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 import { createIcqqSelfProfile } from './self-profile.js';
@@ -189,6 +191,7 @@ export class IcqqEndpoint extends ManagedIcqqClient implements Endpoint {
         throw new Error('QQ did not confirm the group notice');
       }
     },
+    ...createIcqqActionPorts(() => this),
   });
 
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({

package/src/group-actions.ts

@@ -0,0 +1,105 @@
+import type { Client, MemberInfo } from '@icqqjs/icqq';
+import { createEndpointOperation, type EndpointManagement, type EndpointOperation } from 'zhin.js/adapter';
+
+type ActionPorts = Pick<
+  EndpointManagement,
+  | 'pokeUser'
+  | 'unmuteGroupMember'
+  | 'muteAllGroupMembers'
+  | 'setGroupCard'
+  | 'setGroupTitle'
+  | 'setGroupEssence'
+  | 'inviteGroupMember'
+>;
+
+function numericId(value: string): number {
+  const id = Number(value);
+  if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id)) throw new Error('Invalid QQ identifier');
+  return id;
+}
+
+/** Uncached member lookup; `pickMember` and the cached roster would report stale roles. */
+async function freshMember(operation: EndpointOperation, client: Client, group: number, user: number): Promise<MemberInfo | undefined> {
+  try {
+    const member = await operation.prepare(() => client.getGroupMemberInfo(group, user, true));
+    return member.user_id === user && member.group_id === group ? member : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function requireBotRole(operation: EndpointOperation, client: Client, group: number, roles: readonly string[], message: string): Promise<void> {
+  const self = await freshMember(operation, client, group, client.uin);
+  if (!self || !roles.includes(self.role)) throw new Error(message);
+}
+
+function confirmed(ok: unknown, what: string): void {
+  if (ok === false) throw new Error(`QQ did not confirm ${what}`);
+}
+
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export function createIcqqActionPorts(getClient: () => Client): ActionPorts {
+  return {
+    async pokeUser({ userId, groupId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const user = numericId(userId);
+      confirmed(
+        groupId === undefined
+          ? await operation.run(() => client.pickFriend(user).poke(false))
+          : await operation.run(() => client.sendGroupPoke(numericId(groupId), user)),
+        'poke',
+      );
+    },
+    async unmuteGroupMember({ groupId, userId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupBan(group, numericId(userId), 0)), 'unmute');
+    },
+    async muteAllGroupMembers({ groupId, enabled, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupWholeBan(group, enabled)), 'whole-group mute');
+    },
+    async setGroupCard({ groupId, userId, card, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      if (user !== client.uin) await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupCard(group, user, card)), 'card change');
+    },
+    async setGroupTitle({ groupId, userId, title, durationSeconds, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      await requireBotRole(operation, client, group, ['owner'], 'Only the group owner can set special titles');
+      if (!await freshMember(operation, client, group, user)) throw new Error('Target is not a group member');
+      confirmed(await operation.run(() => client.setGroupSpecialTitle(group, user, title, durationSeconds ?? -1)), 'title change');
+    },
+    async setGroupEssence({ groupId, messageId, enabled, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      await requireBotRole(operation, client, numericId(groupId), ['owner', 'admin'], 'Bot is not a group admin');
+      if (enabled) await operation.run(() => client.setEssenceMessage(messageId));
+      else await operation.run(() => client.removeEssenceMessage(messageId));
+    },
+    async inviteGroupMember({ groupId, userId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      if (await freshMember(operation, client, group, user)) throw new Error('Target is already a group member');
+      confirmed(await operation.run(() => client.inviteFriend(group, user)), 'invitation');
+    },
+  };
+}

package/src/sensitive-commands.ts

@@ -0,0 +1,19 @@
+import type { SensitiveExecCommandRule } from '@zhin.js/agent';
+
+/**
+ * The `icqq` command-line client can kick members, move money and delete files. Under an `allowlist`
+ * exec policy its non-sensitive subcommands run freely, while these need owner approval (ADR 0044:
+ * this knowledge lives with the adapter, the exec policy only reads the registered rule).
+ */
+export const ICQQ_SENSITIVE_SUBCOMMAND_REGEXES: readonly RegExp[] = Object.freeze([
+  /\bicqq\s+friend\s+(?:delete|block|move)\b/i,
+  /\bicqq\s+group\s+(?:kick|mute|set|admin|announce|transfer|quit|dissolve|invite)\b/i,
+  /\bicqq\s+(?:request|wallet|pay|recall)\b/i,
+  /\bicqq\s+file\s+(?:upload|delete)\b/i,
+  /\bicqq\s+gfs\b.*\b(?:rm|delete|del)\b/i,
+]);
+
+export const icqqSensitiveExecRule: SensitiveExecCommandRule = Object.freeze({
+  command: 'icqq',
+  sensitive: ICQQ_SENSITIVE_SUBCOMMAND_REGEXES,
+});