@zhin.js/adapter-icqq 1.1.0 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.3
+
+### Patch Changes
+
+- 5b5d270: Complete the canonical share segment contract and preserve native ICQQ share delivery through Core and AI outbound pipelines.
+- Updated dependencies [5b5d270]
+- Updated dependencies [36c2eb9]
+  - @zhin.js/im-contract@1.1.2
+  - @zhin.js/core@1.1.38
+  - @zhin.js/adapter@1.1.15
+  - @zhin.js/agent-feature@1.1.2
+  - @zhin.js/feature-kit@1.1.2
+  - @zhin.js/permission@1.1.2
+  - @zhin.js/skill@1.1.2
+  - @zhin.js/tool@1.1.2
+
+## 1.1.2
+
+### Patch Changes
+
+- 62dee52: Rename the Agent Tool policy field from `approval` to `requiresApproval`, so values such as `never` and `always` state when human approval is required. Remove the old field without a compatibility alias and migrate built-in, adapter, feature, and utility Tools to the canonical contract.
+- a9e4a40: Derive Command user routes only from explicit `commands/**/*/index.ts(x)` entry paths instead of prepending the plugin owner. Child plugins can now publish top-level static or dynamic commands, while duplicate routes across owners fail during generation construction. Adapter endpoint commands move to explicit paths such as `commands/qq/endpoint/list/index.ts` and are invoked as `qq endpoint list`.
+- 8740059: Standardize TypeScript capabilities on named module directories such as `commands/foo/index.ts`, `middlewares/audit/index.ts`, `handlers/message-receive/index.ts`, `pages/workroom/index.tsx`, and `mcps/filesystem/index.ts`. Only the fixed `index` entry is discovered; sibling files remain private helpers.
+
+  Command route segments come from directories, while `[name]`, `[[name]]`, `[...name]`, and `[[...name]]` directories declare dynamic parameters. Plugin owners do not enter the route unless their config explicitly sets `commandNamespace`; Endpoint `commandPrefix` remains platform-owned and defaults to an empty string.
+
+  Migrate the built-in adapters, plugins, examples, generators, migration tooling, hot reload classification, Agent authoring surfaces, documentation, and release artifacts to the explicit entry convention.
+
+  Make Tool ownership and progressive disclosure explicit across all four supported locations: plugin-public `tools/`, Agent-private `agents/<name>/tools/`, Skill-private `skills/<name>/tools/`, and Agent-Skill-private `agents/<name>/skills/<name>/tools/`. Move adapter and group-suite operations that require domain instructions into their owning Skills so `load_skill` is the only path that unlocks their schemas.
+
+  Remove the package-root `agent/` convention. Public capabilities now use named package-root directories, schedules use `schedules/<name>/index.ts` or `plugin.ts` injection, MCP connections use `mcps/<name>/index.ts`, Prompt Sections use `prompt-sections/<name>/index.ts`, Agent definitions use `agents/<name>/`, and permission vocabulary is published as `PERMITS.md`.
+
+- eb3227a: Move Endpoint project-configuration persistence behind the root-owned `EndpointConfigurationStore` resource. The Adapter package now owns only command semantics and no longer imports Node filesystem, path, or YAML APIs; CLI owns canonical YAML and `.env` persistence, while QQ and ICQQ special binding flows use the same injected boundary. Remove the old direct persistence helpers and reject legacy `plugins` arrays instead of promoting them at runtime.
+- ddbb92e: Isolate adapter Skills under platform-specific Agents and automatically select the matching platform Agent for IM ingress, preventing unrelated adapter Skills from entering another platform's prompt surface.
+- 40d2c8f: Reduce the default Agent Tool surface by moving process diagnostics into a Skill and splitting broad platform Skills into focused task domains. Restore ICQQ friend and group directory tools with `on-risk` approval and explicit owner, administrator, master, or trusted access.
+- 73a24b7: Reorganize the Adapter package into one-way authoring, Endpoint boundary, managed lifecycle, and Runtime projection modules without changing public imports. Extract ICQQ content resolution behind a focused module and document its source map.
+- 4380cf9: Colocate adapter command definitions and Agent Skill handlers with their owning capabilities, and provide a shared validated platform permission constructor.
+- 6dad65e: Require one canonical expanded ICQQ endpoint configuration. Remove nested endpoint and environment identity compatibility, replace the conflicting name-based public endpoint type with the actual direct-Client configuration contract, and delete the obsolete endpoint typing-indicator guide.
+- 5c3858e: Make `@zhin.js/im-contract` the explicit zero-dependency owner of transport identities, canonical segments, media guards, conversation facts, stores, and delivery contracts. Platform adapters now read media contracts from that foundation instead of reaching through Core.
+- 33ea736: Use `tools/<name>/index.ts` and `defineAgentTool` from `@zhin.js/tool` as the sole Agent Tool authoring model. Remove the duplicate `@zhin.js/tools` definition, context, bridge, export, and discovery path; migrate plugin manifests, examples, scaffolding, HMR, and prepack compilation to the generation-owned Tool Feature.
+- df9f76b: Make Endpoint configuration persistence asynchronous and route it through the canonical transactional Root configuration port. Endpoint management now supports both YAML and JSON, materializes a missing Root config safely, serializes concurrent mutations, restores `.env` when the config commit fails, and restarts the development process after environment-file changes.
+- Updated dependencies [c861789]
+- Updated dependencies [1414ccb]
+- Updated dependencies [743d470]
+- Updated dependencies [62dee52]
+- Updated dependencies [cd54131]
+- Updated dependencies [a9e4a40]
+- Updated dependencies [5855db7]
+- Updated dependencies [ec921d2]
+- Updated dependencies [8740059]
+- Updated dependencies [63d1f7a]
+- Updated dependencies [25a845a]
+- Updated dependencies [9110ab8]
+- Updated dependencies [eb3227a]
+- Updated dependencies [b853dba]
+- Updated dependencies [e561309]
+- Updated dependencies [d4c6175]
+- Updated dependencies [7a0e1ca]
+- Updated dependencies [103b5d3]
+- Updated dependencies [5a7a7f7]
+- Updated dependencies [b076eae]
+- Updated dependencies [535fed1]
+- Updated dependencies [73a24b7]
+- Updated dependencies [4380cf9]
+- Updated dependencies [1cb1163]
+- Updated dependencies [be3061e]
+- Updated dependencies [75f8332]
+- Updated dependencies [81935e2]
+- Updated dependencies [f9ed01b]
+- Updated dependencies [ac0ab50]
+- Updated dependencies [5140ce1]
+- Updated dependencies [522d75f]
+- Updated dependencies [a7611b3]
+- Updated dependencies [8823044]
+- Updated dependencies [379439b]
+- Updated dependencies [11c9352]
+- Updated dependencies [135ac91]
+- Updated dependencies [140cf0f]
+- Updated dependencies [251e4d2]
+- Updated dependencies [203ad34]
+- Updated dependencies [e6c5113]
+- Updated dependencies [e0f6478]
+- Updated dependencies [698f16f]
+- Updated dependencies [2fd8017]
+- Updated dependencies [5c3858e]
+- Updated dependencies [33ea736]
+- Updated dependencies [df9f76b]
+  - @zhin.js/core@1.1.37
+  - @zhin.js/tool@1.1.1
+  - @zhin.js/adapter@1.1.14
+  - @zhin.js/feature-kit@1.1.1
+  - @zhin.js/agent-feature@1.1.1
+  - @zhin.js/skill@1.1.1
+  - @zhin.js/logger@1.1.1
+  - @zhin.js/im-contract@1.1.1
+  - @zhin.js/permission@1.1.1
+
+## 1.1.1
+
+### Patch Changes
+
+- f0f4573: Fix ICQQ share segments to use the native share protocol instead of sending them as JSON cards.
+- 51df035: fix: 修复 icqq 点赞错误
+- Updated dependencies [769e67f]
+  - @zhin.js/adapter@1.1.13
+  - @zhin.js/core@1.1.36
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -8,7 +8,7 @@ ICQQ Plugin Runtime 适配器 — 进程内直接使用 [@icqqjs/icqq](https://g
 - 入站：ICQQ Client 原始事件经 `Endpoint.emit(...)` 唯一入口上送；文本与图片 / 语音 / 视频 / 文件统一归一为 canonical `Segment` + `MediaRef`
 - 出站：canonical Segment 直接投影为 ICQQ 原生 `Sendable`，再由 `sendGroupMsg` / `sendPrivateMsg` / …发送
 - 群聊 reaction：`control.addReaction` / `removeReaction`（协议 ACK 失败不阻塞后续发送）
-- Agent 工具：包根 `tools/`（`@zhin.js/tool` Feature；模型侧名为 `icqq__send_user_like` 等）
+- Agent 工具：按职责拆分在 `agents/icqq/skills/icqq-*/tools/`，只在对应 Skill 激活后披露
 - Console Endpoint 管理：`src/endpoint.ts` 显式实现 `EndpointManagement`（好友/群/群成员列表、请求审批、删好友、踢人、禁言、设管理）
 
 ## 安装
@@ -62,6 +62,10 @@ plugins:
       - id: "${ICQQ_ACCOUNT_3}"
 ```
 
+`AdapterIndex` 会先合并插件实例默认值与 endpoint 覆盖值，再把一份完整配置交给
+ICQQ adapter。协议层只接受这份展开后的 endpoint 配置，不读取环境变量，也不再次解析
+嵌套的 `endpoints`。环境变量替换由 composition root 在配置加载阶段完成。
+
 ## Send conversation
 
 | 类型 | conversation |
@@ -136,11 +140,16 @@ IM turn 的场景，才使用 `icqqClient.get(context, endpointId)` 显式选择
 
 ## 架构
 
-- `plugin.ts` + `adapters/icqq.ts`（`defineAdapter`）
-- Client token：`src/client.ts`（直接引用 ICQQ `Client` / `EventMap`）
-- Endpoint：`src/endpoint.ts`（组合 ICQQ `Client`，负责账号 transport 与 Zhin lifecycle）
-- 协议常量 / 配置：`src/protocol.ts`
-- Agent 工具：`tools/*.ts`；权限说明见 `agent/PERMITS.md`
+- `plugin.ts` + `adapters/icqq/index.ts`：Plugin Runtime 入口与 `defineAdapter` 声明
+- `src/endpoint.ts`：组合 ICQQ `Client`，只协调账号 transport、Zhin lifecycle 与各能力端口
+- `src/content-resolver.ts`：保存已观察消息，并按深度和条数限制递归展开合并转发
+- `src/icqq-inbound.ts`：把 ICQQ 原生消息归一为 Zhin 入站消息
+- `src/protocol.ts`：配置解析、会话映射与出站目标转换
+- `src/client.ts`：向插件作者暴露 ICQQ `Client` / `EventMap` 类型注册
+- Agent 工具：`agents/icqq/skills/icqq-*/tools/<name>/index.ts`；权限说明见 `PERMITS.md`
+
+阅读适配器实现时从 `endpoint.ts` 看能力装配，再进入对应能力文件。包外代码只从
+`@zhin.js/adapter-icqq` 与 `zhin.js/adapter` 的公开入口导入，不依赖上述源码路径。
 
 ## Plugin Runtime 迁移说明
 

package/adapters/{icqq.js → icqq/index.js}

@@ -1,13 +1,13 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
+ * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { loginAssistToken } from '@zhin.js/core/runtime';
-import { IcqqEndpoint } from "../lib/endpoint.js";
-import { icqqRuntimeStateToken } from "../lib/icqq-runtime-state.js";
-import { resolveIcqqConfig, } from "../lib/protocol.js";
-export { IcqqEndpoint } from "../lib/endpoint.js";
+import { IcqqEndpoint } from "../../lib/endpoint.js";
+import { icqqRuntimeStateToken } from "../../lib/icqq-runtime-state.js";
+import { resolveIcqqConfig, } from "../../lib/protocol.js";
+export { IcqqEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['recall', 'reaction'],
@@ -17,7 +17,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveIcqqConfig(context.config);
-        // 注册到插件运行时状态（icqq.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
         context.use(icqqRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: 'direct',

package/adapters/{icqq.ts → icqq/index.ts}

@@ -1,25 +1,25 @@
 /**
- * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
+ * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { loginAssistToken } from '@zhin.js/core/runtime';
-import { IcqqEndpoint } from '../src/endpoint.js';
-import { icqqRuntimeStateToken } from '../src/icqq-runtime-state.js';
+import { IcqqEndpoint } from '../../src/endpoint.js';
+import { icqqRuntimeStateToken } from '../../src/icqq-runtime-state.js';
 import {
   resolveIcqqConfig,
-  type IcqqAdapterConfig,
-} from '../src/protocol.js';
+  type IcqqEndpointConfig,
+} from '../../src/protocol.js';
 
-export { IcqqEndpoint } from '../src/endpoint.js';
-export type { IcqqEndpointOptions } from '../src/endpoint.js';
+export { IcqqEndpoint } from '../../src/endpoint.js';
+export type { IcqqEndpointOptions } from '../../src/endpoint.js';
 
 declare module '@zhin.js/core' {
   interface AdapterEndpoints {
-    icqq: import('../src/endpoint.js').IcqqEndpoint;
+    icqq: import('../../src/endpoint.js').IcqqEndpoint;
   }
 }
 
-export default defineAdapter<IcqqAdapterConfig>({
+export default defineAdapter<IcqqEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall', 'reaction'],
   segments: {
@@ -28,7 +28,7 @@ export default defineAdapter<IcqqAdapterConfig>({
   },
   create(context) {
     const config = resolveIcqqConfig(context.config);
-    // 注册到插件运行时状态（icqq.endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
     context.use(icqqRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       mode: 'direct',

package/agents/icqq/agent.json

@@ -0,0 +1,20 @@
+{
+  "name": "ICQQ Platform Agent",
+  "version": "1.0.0",
+  "description": "Handles icqq platform-specific operations and progressively loads only the required platform Skill.",
+  "trigger_rules": {
+    "file_patterns": [],
+    "keywords": [
+      "icqq",
+      "adapter:icqq"
+    ]
+  },
+  "entry_points": [
+    "system.md",
+    "boundaries.md",
+    "conventions.md"
+  ],
+  "platforms": [
+    "icqq"
+  ]
+}

package/agents/icqq/boundaries.md

@@ -0,0 +1,3 @@
+# Boundaries
+
+Operate only on the active icqq endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.

package/agents/icqq/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.

package/agents/icqq/skills/icqq-directory/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: icqq-directory
+platforms:
+  - icqq
+description: ICQQ 好友、群和成员目录查询能力。
+keywords:
+  - "icqq"
+  - "好友列表"
+  - "群列表"
+  - "成员信息"
+tools:
+  - "friend_list"
+  - "group_list"
+  - "user_info"
+  - "group_member_info"
+---
+
+# icqq-directory
+
+查询用户或群成员前先获取稳定 QQ 号或群号。目录信息只向群主、管理员、master 或 trusted 披露；不要根据昵称猜测身份。

package/{tools/friend_list.js → agents/icqq/skills/icqq-directory/tools/friend_list/index.js}

@@ -5,7 +5,8 @@ export default defineAgentTool({
     description: '获取 QQ 好友列表',
     inputSchema: z.object({}),
     adapter: 'icqq',
-    approval: 'never',
+    requiresApproval: 'on-risk',
+    permissions: ['role(master,admin,trusted,owner)'],
     async execute(_input, context) {
         const client = context.$client;
         const friends = Array.from(client.fl.values()).map((friend) => ({

package/{tools/friend_list.ts → agents/icqq/skills/icqq-directory/tools/friend_list/index.ts}

@@ -5,7 +5,8 @@ export default defineAgentTool<Record<string, never>>({
   description: '获取 QQ 好友列表',
   inputSchema: z.object({}),
   adapter: 'icqq',
-  approval: 'never',
+  requiresApproval: 'on-risk',
+  permissions: ['role(master,admin,trusted,owner)'],
   async execute(_input, context) {
     const client = context.$client;
     const friends = Array.from(client.fl.values()).map((friend) => ({

package/{tools/group_list.js → agents/icqq/skills/icqq-directory/tools/group_list/index.js}

@@ -5,7 +5,8 @@ export default defineAgentTool({
     adapter: 'icqq',
     description: '获取当前 QQ 账号的群列表',
     inputSchema: z.object({}),
-    approval: 'never',
+    requiresApproval: 'on-risk',
+    permissions: ['role(master,admin,trusted,owner)'],
     async execute(_input, context) {
         const client = context.$client;
         const groups = Array.from(client.gl.values()).map((group) => ({

package/{tools/group_list.ts → agents/icqq/skills/icqq-directory/tools/group_list/index.ts}

@@ -5,7 +5,8 @@ export default defineAgentTool<Record<string, never>>({
   adapter: 'icqq',
   description: '获取当前 QQ 账号的群列表',
   inputSchema: z.object({}),
-  approval: 'never',
+  requiresApproval: 'on-risk',
+  permissions: ['role(master,admin,trusted,owner)'],
   async execute(_input, context) {
     const client = context.$client;
     const groups = Array.from(client.gl.values()).map((group) => ({

package/{tools/group_member_info.js → agents/icqq/skills/icqq-directory/tools/group_member_info/index.js}

@@ -8,7 +8,9 @@ export default defineAgentTool({
         user_id: z.number().describe('目标成员 QQ号'),
     }),
     adapter: 'icqq',
-    approval: 'never',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
     async execute({ group_id, user_id }, context) {
         const group = context.$client.pickGroup(group_id);
         if (!group)

package/{tools/group_member_info.ts → agents/icqq/skills/icqq-directory/tools/group_member_info/index.ts}

@@ -12,7 +12,9 @@ export default defineAgentTool<GroupMemberInfoInput>({
     user_id: z.number().describe('目标成员 QQ号'),
   }),
   adapter: 'icqq',
-  approval: 'never',
+  scopes:['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
   async execute({ group_id, user_id }, context) {
     const group = context.$client.pickGroup(group_id);
     if (!group) return { success: false, message: '目标群不存在' };

package/{tools/user_info.js → agents/icqq/skills/icqq-directory/tools/user_info/index.js}

@@ -7,6 +7,7 @@ export default defineAgentTool({
         user_id: z.number().describe('目标成员 QQ号'),
     }),
     adapter: 'icqq',
+    requiresApproval: 'never',
     async execute({ user_id }, context) {
         const profile = await context.$client.getProfile(user_id);
         return { success: true, message: `已获取 ${user_id} 的用户信息:${JSON.stringify(profile, null, 2)}` };

package/{tools/user_info.ts → agents/icqq/skills/icqq-directory/tools/user_info/index.ts}

@@ -6,6 +6,7 @@ export default defineAgentTool<{ user_id: number }>({
     user_id: z.number().describe('目标成员 QQ号'),
   }),
   adapter: 'icqq',
+  requiresApproval: 'never',
   async execute({ user_id }, context) {
     const profile = await context.$client.getProfile(user_id);
     return { success: true, message: `已获取 ${user_id} 的用户信息:${JSON.stringify(profile,null,2)}` };

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

@@ -0,0 +1,25 @@
+---
+name: icqq-group-admin
+platforms:
+  - icqq
+description: ICQQ 邀请、踢人、禁言、头衔、匿名、公告和精华管理能力。
+keywords:
+  - "icqq"
+  - "群管理"
+  - "禁言"
+  - "踢人"
+  - "公告"
+  - "精华"
+tools:
+  - "group_invite"
+  - "group_kick"
+  - "set_mute"
+  - "set_title"
+  - "set_anonymous"
+  - "announce"
+  - "essence"
+---
+
+# icqq-group-admin
+
+仅在目标群和目标成员明确时加载。所有写操作遵守 Tool 审批与角色权限；不可逆或影响成员关系的操作先复核参数。

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

@@ -8,6 +8,8 @@ export default defineAgentTool({
         content: z.string().describe('公告内容'),
     }),
     adapter: 'icqq',
+    requiresApproval: 'once',
+    scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],
     async execute({ group_id, content }, context) {
         await context.$client.sendGroupNotice(group_id, content);

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

@@ -7,6 +7,8 @@ export default defineAgentTool<{ group_id: number; content: string }>({
     content: z.string().describe('公告内容'),
   }),
   adapter: 'icqq',
+  requiresApproval: 'once',
+  scopes:['group'],
   permissions: ['role(master,admin,trusted,owner)'],
   async execute({ group_id, content }, context) {
     await context.$client.sendGroupNotice(group_id, content);

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

@@ -8,7 +8,9 @@ export default defineAgentTool({
         action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
     }),
     adapter: 'icqq',
-    approval: 'always',
+    requiresApproval: 'once',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
     async execute({ message_id, action }, context) {
         const client = context.$client;
         if (action === 'add') {

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

@@ -7,7 +7,9 @@ export default defineAgentTool<{ message_id: string; action: 'add' | 'remove' }>
     action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
   }),
   adapter: 'icqq',
-  approval: 'always',
+  requiresApproval: 'once',
+  scopes:['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
   async execute({ message_id, action }, context) {
     const client = context.$client;
     if (action === 'add') {

package/{tools/group_invite.js → agents/icqq/skills/icqq-group-admin/tools/group_invite/index.js}

@@ -8,7 +8,7 @@ export default defineAgentTool({
         user_id: z.number().describe('要邀请的 QQ号'),
     }),
     adapter: 'icqq',
-    approval: 'never',
+    requiresApproval: 'always',
     async execute({ group_id, user_id }, context) {
         const client = context.$client;
         const groupInfo = client.pickGroup(group_id);

package/{tools/group_invite.ts → agents/icqq/skills/icqq-group-admin/tools/group_invite/index.ts}

@@ -7,7 +7,7 @@ export default defineAgentTool<{ group_id: number; user_id: number }>({
     user_id: z.number().describe('要邀请的 QQ号'),
   }),
   adapter: 'icqq',
-  approval: 'never',
+  requiresApproval: 'always',
   async execute({ group_id, user_id }, context) {
     const client = context.$client;
     const groupInfo= client.pickGroup(group_id);

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

@@ -8,15 +8,16 @@ export default defineAgentTool({
         user_id: z.number().describe('要踢出的成员 QQ号'),
     }),
     adapter: 'icqq',
+    scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],
-    approval: 'never',
+    requiresApproval: 'once',
     async execute({ group_id, user_id }, context) {
         const client = context.$client;
         const selfInfo = client.pickMember(group_id, client.uin);
         if (!selfInfo.is_admin && !selfInfo.is_owner)
-            return { success: false, message: '我不是群主或管理员，无法踢出成员' };
+            return { success: false, message: '机器人不是群主或管理员，无法踢出成员' };
         if (selfInfo.user_id === user_id)
-            return { success: false, message: '我不能踢出自己' };
+            return { success: false, message: '机器人不能踢出自己' };
         const memberInfo = client.pickMember(group_id, user_id);
         if (!memberInfo)
             return { success: false, message: '目标成员不存在' };

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

@@ -7,13 +7,14 @@ export default defineAgentTool<{ group_id: number; user_id: number }>({
     user_id: z.number().describe('要踢出的成员 QQ号'),
   }),
   adapter: 'icqq',
+  scopes:['group'],
   permissions: ['role(master,admin,trusted,owner)'],
-  approval: 'never',
+  requiresApproval: 'once',
   async execute({ group_id, user_id }, context) {
     const client = context.$client;
     const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '我不是群主或管理员，无法踢出成员' };
-    if(selfInfo.user_id === user_id) return { success: false, message: '我不能踢出自己' };
+    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '机器人不是群主或管理员，无法踢出成员' };
+    if(selfInfo.user_id === user_id) return { success: false, message: '机器人不能踢出自己' };
     const memberInfo= client.pickMember(group_id,user_id);
     if(!memberInfo) return { success: false, message: '目标成员不存在' };
     await client.setGroupKick(group_id, user_id);

package/{tools/set_anonymous.js → agents/icqq/skills/icqq-group-admin/tools/set_anonymous/index.js}

@@ -8,13 +8,15 @@ export default defineAgentTool({
         enable: z.boolean().optional().describe('true=开启，false=关闭，默认 true'),
     }),
     adapter: 'icqq',
+    requiresApproval: 'once',
+    scopes: ['group'],
     permissions: ['role(master,trusted,owner,admin)'],
     async execute({ group_id, enable }, context) {
         const client = context.$client;
         const on = enable ?? true;
         const selfInfo = client.pickMember(group_id, client.uin);
         if (!selfInfo.is_admin && !selfInfo.is_owner)
-            return { success: false, message: '我不是群主或管理员，无法开启或关闭匿名聊天' };
+            return { success: false, message: '机器人不是群主或管理员，无法开启或关闭匿名聊天' };
         await client.setGroupAnonymous(group_id, on);
         return { success: true, message: on ? '已开启匿名聊天' : '已关闭匿名聊天' };
     },

package/{tools/set_anonymous.ts → agents/icqq/skills/icqq-group-admin/tools/set_anonymous/index.ts}

@@ -7,12 +7,14 @@ export default defineAgentTool<{ group_id: number; enable?: boolean }>({
     enable: z.boolean().optional().describe('true=开启，false=关闭，默认 true'),
   }),
   adapter: 'icqq',
+  requiresApproval: 'once',
+  scopes:['group'],
   permissions: ['role(master,trusted,owner,admin)'],
   async execute({ group_id, enable }, context) {
     const client = context.$client;
     const on = enable ?? true;
     const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '我不是群主或管理员，无法开启或关闭匿名聊天' };
+    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '机器人不是群主或管理员，无法开启或关闭匿名聊天' };
     await client.setGroupAnonymous(group_id, on);
     return { success: true, message: on ? '已开启匿名聊天' : '已关闭匿名聊天' };
   },

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

@@ -9,12 +9,13 @@ export default defineAgentTool({
         duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
     }),
     adapter: 'icqq',
-    approval: 'always',
+    scopes: ['group'],
+    requiresApproval: 'always',
     async execute({ group_id, user_id, duration }, context) {
         const client = context.$client;
         const selfInfo = client.pickMember(group_id, client.uin);
         if (!selfInfo.is_admin && !selfInfo.is_owner)
-            return { success: false, message: '我不是群主或管理员，无法禁言/解除禁言成员' };
+            return { success: false, message: '机器人不是群主或管理员，无法禁言/解除禁言成员' };
         const memberInfo = client.pickMember(group_id, user_id);
         if (!memberInfo)
             return { success: false, message: '目标成员不存在' };

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

@@ -8,11 +8,12 @@ export default defineAgentTool<{ group_id: number; user_id: number; duration?: n
     duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
   }),
   adapter: 'icqq',
-  approval: 'always',
+  scopes:['group'],
+  requiresApproval: 'always',
   async execute({ group_id, user_id, duration }, context) {
     const client = context.$client;
     const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '我不是群主或管理员，无法禁言/解除禁言成员' };
+    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '机器人不是群主或管理员，无法禁言/解除禁言成员' };
     const memberInfo= client.pickMember(group_id,user_id);
     if(!memberInfo) return { success: false, message: '目标成员不存在' };
     await client.setGroupBan(group_id, user_id, duration === 0 ? 0 : duration);

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

@@ -10,12 +10,13 @@ export default defineAgentTool({
         duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
     }),
     adapter: 'icqq',
-    approval: 'always',
+    scopes: ['group'],
+    requiresApproval: 'always',
     async execute({ group_id, user_id, title, duration }, context) {
         const client = context.$client;
         const selfInfo = client.pickMember(group_id, client.uin);
         if (!selfInfo.is_admin && !selfInfo.is_owner)
-            return { success: false, message: '我不是群主或管理员，无法设置头衔' };
+            return { success: false, message: '机器人不是群主或管理员，无法设置头衔' };
         const memberInfo = client.pickMember(group_id, user_id);
         if (!memberInfo)
             return { success: false, message: '目标成员不存在' };

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

@@ -9,11 +9,12 @@ export default defineAgentTool<{ group_id: number; user_id: number; title: strin
     duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
   }),
   adapter: 'icqq',
-  approval: 'always',
+  scopes:['group'],
+  requiresApproval: 'always',
   async execute({ group_id, user_id, title, duration }, context) {
     const client = context.$client;
     const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '我不是群主或管理员，无法设置头衔' };
+    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '机器人不是群主或管理员，无法设置头衔' };
     const memberInfo= client.pickMember(group_id,user_id);
     if(!memberInfo) return { success: false, message: '目标成员不存在' };
     await client.setGroupSpecialTitle(group_id, user_id, title, duration ?? -1);

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

@@ -0,0 +1,17 @@
+---
+name: icqq-group-state
+platforms:
+  - icqq
+description: ICQQ 群文件与禁言状态查询能力。
+keywords:
+  - "icqq"
+  - "群文件"
+  - "禁言列表"
+tools:
+  - "group_files"
+  - "list_muted"
+---
+
+# icqq-group-state
+
+用于读取群文件和禁言状态。确认群号后调用，不把列表之外的信息当作已验证事实。