@zhin.js/adapter-icqq 1.1.20 → 1.1.22

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @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
+
+- af8f803: Use the current Endpoint's platform profile for Agent account identity, with per-field configured fallbacks and scoped, identity-approved profile tools. Keep SOUL first-person and independent of account names. Profile ports preserve the source Client, cancellation, truthful update outcomes and private image authority.
+
+  Adapter Feature API 2.1 and Tool Feature API 1.1 describe the additive profile requirements; new Core, official adapters and generated plugins declare the corresponding floors. Existing compatible API-2.0/API-1.0 plugins remain accepted by the newer providers. npm releases remain patch.
+
+  Private IM assets now bind to the full canonical conversation and principal. Existing IM asset records that contain only the earlier lossy hash remain on disk until their original expiry, but cannot be safely rebound; recapture them. No automatic file deletion, platform profile mutation or workspace SOUL rewrite occurs during upgrade.
+
+- Updated dependencies [b88e988]
+- Updated dependencies [f78eb84]
+- Updated dependencies [c15cef9]
+- Updated dependencies [b0c02a2]
+- Updated dependencies [af8f803]
+- Updated dependencies [26fda97]
+- Updated dependencies [976886c]
+- Updated dependencies [032dc96]
+  - @zhin.js/adapter@1.1.27
+  - @zhin.js/client@1.1.23
+  - @zhin.js/im-contract@1.1.10
+  - @zhin.js/core@1.1.55
+  - @zhin.js/tool@1.1.14
+  - @zhin.js/page@1.1.13
+  - @zhin.js/agent-feature@1.1.12
+  - @zhin.js/feature-kit@1.1.11
+  - @zhin.js/permission@1.1.11
+  - @zhin.js/skill@1.1.12
+
 ## 1.1.20
 
 ### 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 页面
 
@@ -249,3 +249,13 @@ ICQQ 要求分享、文件、语音、视频、JSON 卡片和合并转发单独
 Endpoint 管理和工具反馈跟随当前操作语言；登录没有当前聊天发送者，LoginAssist 提示采用项目语言。提示文案变化不改变扫码、短信、滑块验证过程，群管理权限、审批与平台结果检查保持原规则。
 
 Endpoint 添加用法中的调用头由当前环境的实际命令前缀与插件命名空间提供；未知时只提示所需参数，不生成猜测命令。
+
+## 当前账号资料
+
+`endpointSpec.profile` 接到原生 ICQQ Client 的资料卡与设置方法；Agent 通过统一的 `get_self_profile` / `set_self_profile` 工具访问当前账号，修改沿用身份类审批。平台资料优先于配置兜底，群名片仍是独立的场景资料。
+
+- 可读：昵称、性别、年龄、个性签名、头像 URL。只投影这些公开资料，不把 SDK 返回的邮箱、QID 等一起交给模型。
+- 可写：昵称、性别、签名、个人说明、头像。SDK 返回 `false` 时明确拒绝，不报告成功。头像输入经工具链解析为已授权图片，结果不回传图片 base64。
+- 年龄不反推生日；当前安装的 ICQQ 1.12.3 `setBirthday` 月日编码有缺陷，因此不开放生日写入。兴趣无对应已验证接口，只能使用配置兜底。
+
+配置的 `nickname`、`profile` 可放在适配器默认值或某个 `endpoints[]` 项中；Endpoint 逐字段覆盖默认值，只有平台未提供的字段才使用它们。配置兜底不会写回 QQ。

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-conversation/SKILL.md

@@ -15,9 +15,9 @@ tools:
 ---
 # icqq-conversation
 
-Use `conversation_info` before claiming the bot's role or available platform permissions. It uses the current endpoint account, not the sender's role. Group roles are refreshed from the platform on demand; failure is not evidence that the bot is an ordinary member.
+Use `conversation_info` before claiming your role or available platform permissions. It uses the current endpoint account, not the sender's role. Group roles are refreshed from the platform on demand; failure is not evidence that you are an ordinary member.
 
-Caller roles authorize a request; bot platform roles determine whether QQ can execute it. They are independent. A successful inspection does not replace the live permission check before a management action.
+Caller roles authorize a request; your platform roles determine whether QQ can execute it. They are independent. A successful inspection does not replace the live permission check before a management action.
 
 Guild member lookup can be incomplete. Missing self membership means `unknown`. A `channel_admin` record does not identify which child channels it governs, so it cannot authorize an operation in the current channel.
 

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

@@ -3,7 +3,7 @@ import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { currentConversation } from '../../../../conversation.js';
 export default defineAgentTool({
-    description: '读取当前 ICQQ 会话及机器人自己的群／频道身份；区分调用者权限、机器人平台权限和不支持的操作',
+    description: '读取当前 ICQQ 会话及你自己的群／频道身份；区分调用者权限、你的平台权限和不支持的操作',
     adapter: 'icqq',
     requiresApproval: 'never',
     inputSchema: z.object({}),

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

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { currentConversation } from '../../../../conversation.js';
 
 export default defineAgentTool({
-  description: '读取当前 ICQQ 会话及机器人自己的群／频道身份；区分调用者权限、机器人平台权限和不支持的操作',
+  description: '读取当前 ICQQ 会话及你自己的群／频道身份；区分调用者权限、你的平台权限和不支持的操作',
   adapter: 'icqq',
   requiresApproval: 'never',
   inputSchema: z.object({}),

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,8 +38,10 @@ scopes:
 
 已配置的自动审核流程可对入群 10 分钟内的明确广告直接踢出；该例外由审核流程核验，不授权本技能或普通对话绕过人工审批。
 
-`group_leave` 仅主人（master）可发起，每次人工审批，只能退出当前群。Bot 为群主时拒绝执行，因为 SDK 的退群会解散群。
+`set_group_admin` 仅在你是当前群群主时注入（你只是管理员时不可见），沿用 master/admin/trusted/owner 发起权限，每次人工审批并展示目标群、成员、设/撤方向和理由。执行前实时复核：你必须仍是群主；设为管理员只针对普通成员，取消只针对现任管理员；平台未确认时不宣称成功、不自动重试。
 
-`recall_member_message` 沿用 master/admin/trusted/owner 发起权限，无需逐次审批；目标固定在当前群中的真实消息。执行前实时查询 Bot 与目标成员角色：管理员只能撤回普通成员，群主可撤回管理员或普通成员。平台时限与执行结果仍然有效，不自动重试未确认的结果。
+`group_leave` 仅主人（master）可发起，每次人工审批，只能退出当前群。你为群主时拒绝执行，因为 SDK 的退群会解散群。
 
-撤回 Bot 自己的消息不要求群管角色：使用 `icqq-messages` 的 `recall_own_message`。已配置自动群审核的撤回继续走原有审核路径，不因本工具新增审批，也不扩大审核类别或目标群。
+`recall_member_message` 沿用 master/admin/trusted/owner 发起权限，无需逐次审批；目标固定在当前群中的真实消息。执行前实时查询你与目标成员的角色：管理员只能撤回普通成员，群主可撤回管理员或普通成员。平台时限与执行结果仍然有效，不自动重试未确认的结果。
+
+撤回你自己的消息不要求群管角色：使用 `icqq-messages` 的 `recall_own_message`。已配置自动群审核的撤回继续走原有审核路径，不因本工具新增审批，也不扩大审核类别或目标群。

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/group_leave/index.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { currentGroup } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '让机器人退出当前 QQ 群；仅主人可发起且每次人工审批，机器人是群主时拒绝执行以免解散群',
+    description: '退出你当前所在的 QQ 群；仅主人可发起且每次人工审批，你是群主时拒绝执行以免解散群',
     adapter: 'icqq',
     scopes: ['group'],
     currentConversationBotRoles: ['admin', 'member'],

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

@@ -4,7 +4,7 @@ import { currentGroup } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '让机器人退出当前 QQ 群；仅主人可发起且每次人工审批，机器人是群主时拒绝执行以免解散群',
+  description: '退出你当前所在的 QQ 群；仅主人可发起且每次人工审批，你是群主时拒绝执行以免解散群',
   adapter: 'icqq',
   scopes: ['group'],
   currentConversationBotRoles: ['admin', 'member'],

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

@@ -4,8 +4,10 @@ import { z } from 'zod';
 import { currentGroup, recallMessage, resolveMessage } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '撤回当前 QQ 群内他人的真实消息；需调用方具备群管发起权限及机器人具备实时平台权限，无需逐次审批',
+    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

@@ -4,8 +4,10 @@ import { currentGroup, recallMessage, resolveMessage } from '../../../../convers
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '撤回当前 QQ 群内他人的真实消息；需调用方具备群管发起权限及机器人具备实时平台权限，无需逐次审批',
+  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)'],