@zhin.js/adapter-icqq 1.0.28 → 1.0.30

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zhin.js/adapter-icqq
 
+## 1.0.30
+
+### Patch Changes
+
+- 26d2942: fix: ai
+- 6b02c41: fix: ai
+- Updated dependencies [26d2942]
+- Updated dependencies [6b02c41]
+  - @zhin.js/client@1.0.8
+  - @zhin.js/core@1.0.25
+  - zhin.js@1.0.25
+  - @zhin.js/console@1.0.21
+  - @zhin.js/http@1.0.16
+
+## 1.0.29
+
+### Patch Changes
+
+- Updated dependencies [6108e5d]
+  - @zhin.js/core@1.0.24
+  - zhin.js@1.0.24
+  - @zhin.js/console@1.0.20
+  - @zhin.js/http@1.0.15
+
 ## 1.0.28
 
 ### Patch Changes

package/README.md

@@ -11,6 +11,8 @@ Zhin.js ICQQ 适配器，基于 ICQQ 库实现的 QQ 机器人适配器，支持
 - 📁 自动数据目录管理
 - 🖼️ 支持图片、语音、视频等多媒体消息
 - 🎯 支持 @ 提及和引用回复
+- 🔧 **群管理工具**：踢人、禁言、设置管理员、群名片、头衔等（AI 可调用）
+- 🔒 **权限控制**：基于群角色的工具权限过滤
 
 ## 安装
 
@@ -241,6 +243,128 @@ const friendList = bot.getFriendList()
 const memberInfo = bot.getGroupMemberInfo(groupId, userId)
 ```
 
+## 🔧 群管理工具（AI 可调用）
+
+适配器自动注册了一系列群管理工具，这些工具可以被 AI 调用，实现智能化的群管理。
+
+### 工具列表
+
+| 工具 | 所需权限 | 说明 |
+|------|----------|------|
+| `icqq_kick_member` | 管理员 | 踢出群成员（可选拉黑） |
+| `icqq_mute_member` | 管理员 | 禁言群成员 |
+| `icqq_mute_all` | 管理员 | 全员禁言 |
+| `icqq_set_admin` | 群主 | 设置/取消管理员 |
+| `icqq_set_card` | 管理员 | 设置群名片 |
+| `icqq_set_title` | 群主 | 设置专属头衔 |
+| `icqq_set_group_name` | 管理员 | 修改群名称 |
+| `icqq_announce` | 管理员 | 发送群公告 |
+| `icqq_poke` | 普通用户 | 戳一戳 |
+| `icqq_list_members` | 普通用户 | 获取群成员列表 |
+| `icqq_list_muted` | 普通用户 | 获取被禁言成员列表 |
+| `icqq_set_anonymous` | 管理员 | 开启/关闭匿名聊天 |
+
+### 使用示例
+
+#### 通过 AI 对话管理群
+
+```
+用户（群主）：把 @小明 踢出群并拉黑
+AI：已将 小明 踢出群并拉黑。
+
+用户（管理员）：禁言 @捣蛋鬼 1小时
+AI：已禁言 捣蛋鬼 3600 秒。
+
+用户（管理员）：发个群公告：明天下午3点开会
+AI：群公告已发送。
+
+用户：戳一戳 @朋友
+AI：已戳了戳 朋友。
+```
+
+#### 编程调用
+
+```typescript
+// 获取 ICQQ Bot 实例
+const icqqAdapter = app.adapters.get('icqq')
+const bot = icqqAdapter?.bots.get('你的QQ号')
+
+// 踢出成员
+await bot.kickMember(groupId, userId, true) // 第三个参数为是否拉黑
+
+// 禁言成员（单位：秒）
+await bot.muteMember(groupId, userId, 600) // 禁言 10 分钟
+await bot.muteMember(groupId, userId, 0)   // 解除禁言
+
+// 全员禁言
+await bot.muteAll(groupId, true)  // 开启
+await bot.muteAll(groupId, false) // 关闭
+
+// 设置管理员
+await bot.setAdmin(groupId, userId, true)  // 设为管理员
+await bot.setAdmin(groupId, userId, false) // 取消管理员
+
+// 设置群名片
+await bot.setCard(groupId, userId, '新名片')
+
+// 设置专属头衔
+await bot.setTitle(groupId, userId, '大佬', -1) // -1 表示永久
+
+// 修改群名
+await bot.setGroupName(groupId, '新群名')
+
+// 发送群公告
+await bot.sendAnnounce(groupId, '公告内容')
+
+// 戳一戳
+await bot.pokeMember(groupId, userId)
+
+// 获取群成员列表
+const members = await bot.getMemberList(groupId)
+
+// 获取被禁言成员列表
+const mutedList = await bot.getMutedMembers(groupId)
+
+// 开启/关闭匿名
+await bot.setAnonymous(groupId, true)
+```
+
+### 发送者权限信息
+
+消息中的 `$sender` 包含 ICQQ 特有的权限信息：
+
+```typescript
+interface IcqqSenderInfo {
+  id: string;           // QQ 号
+  name: string;         // 昵称
+  role?: GroupRole;     // 'owner' | 'admin' | 'member'
+  isOwner?: boolean;    // 是否为群主
+  isAdmin?: boolean;    // 是否为管理员
+  card?: string;        // 群名片
+  title?: string;       // 专属头衔
+}
+```
+
+#### 在插件中检查权限
+
+```typescript
+onGroupMessage(async (message) => {
+  const sender = message.$sender as IcqqSenderInfo;
+  
+  if (sender.isOwner) {
+    console.log('这是群主的消息');
+  }
+  
+  if (sender.isAdmin) {
+    console.log('这是管理员的消息');
+  }
+  
+  if (sender.role === 'member') {
+    console.log('这是普通成员的消息');
+  }
+})
+```
+
 ## 签名服务器
 
 为了提高登录稳定性和避免风控，建议配置签名服务器：

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { Config, Client, PrivateMessageEvent, GroupMessageEvent, Sendable } from "@icqqjs/icqq";
+import { Config, Client, PrivateMessageEvent, GroupMessageEvent, Sendable, MemberInfo, GroupRole } from "@icqqjs/icqq";
 import { Bot, Adapter, Plugin, Message, SendOptions, MessageSegment, SendContent } from "zhin.js";
 import { Router } from "@zhin.js/http";
 declare module "zhin.js" {
@@ -12,6 +12,20 @@ declare module "zhin.js" {
         icqq: IcqqAdapter;
     }
 }
+export interface IcqqSenderInfo {
+    id: string;
+    name: string;
+    /** 群角色 */
+    role?: GroupRole;
+    /** 是否为群主 */
+    isOwner?: boolean;
+    /** 是否为管理员 */
+    isAdmin?: boolean;
+    /** 群名片 */
+    card?: string;
+    /** 头衔 */
+    title?: string;
+}
 export interface IcqqBotConfig extends Config {
     context: "icqq";
     name: `${number}`;
@@ -30,6 +44,86 @@ export declare class IcqqBot extends Client implements Bot<IcqqBotConfig, Privat
     $connect(): Promise<void>;
     $disconnect(): Promise<void>;
     $formatMessage(msg: PrivateMessageEvent | GroupMessageEvent): Message<PrivateMessageEvent | GroupMessageEvent>;
+    /**
+     * 获取发送者的详细权限信息
+     */
+    private getSenderInfo;
+    /**
+     * 踢出群成员
+     * @param groupId 群号
+     * @param userId 用户QQ号
+     * @param block 是否拉黑（加入黑名单）
+     */
+    kickMember(groupId: number, userId: number, block?: boolean): Promise<boolean>;
+    /**
+     * 禁言群成员
+     * @param groupId 群号
+     * @param userId 用户QQ号
+     * @param duration 禁言时长（秒），0 表示解除禁言
+     */
+    muteMember(groupId: number, userId: number, duration?: number): Promise<boolean>;
+    /**
+     * 全员禁言
+     * @param groupId 群号
+     * @param enable 是否开启全员禁言
+     */
+    muteAll(groupId: number, enable?: boolean): Promise<boolean>;
+    /**
+     * 设置管理员
+     * @param groupId 群号
+     * @param userId 用户QQ号
+     * @param enable 是否设为管理员
+     */
+    setAdmin(groupId: number, userId: number, enable?: boolean): Promise<boolean>;
+    /**
+     * 设置群名片
+     * @param groupId 群号
+     * @param userId 用户QQ号
+     * @param card 群名片
+     */
+    setCard(groupId: number, userId: number, card: string): Promise<boolean>;
+    /**
+     * 设置群头衔
+     * @param groupId 群号
+     * @param userId 用户QQ号
+     * @param title 头衔
+     * @param duration 持续时间（秒），-1 表示永久
+     */
+    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
+    /**
+     * 设置群名
+     * @param groupId 群号
+     * @param name 群名
+     */
+    setGroupName(groupId: number, name: string): Promise<boolean>;
+    /**
+     * 发送群公告
+     * @param groupId 群号
+     * @param content 公告内容
+     */
+    sendAnnounce(groupId: number, content: string): Promise<boolean>;
+    /**
+     * 戳一戳
+     * @param groupId 群号
+     * @param userId 用户QQ号
+     */
+    pokeMember(groupId: number, userId: number): Promise<boolean>;
+    /**
+     * 获取群成员列表
+     * @param groupId 群号
+     */
+    getMemberList(groupId: number): Promise<Map<number, MemberInfo>>;
+    /**
+     * 获取被禁言成员列表
+     * @param groupId 群号
+     */
+    getMutedMembers(groupId: number): Promise<any[]>;
+    /**
+     * 允许/禁止匿名
+     * @param groupId 群号
+     * @param enable 是否允许匿名
+     */
+    setAnonymous(groupId: number, enable?: boolean): Promise<boolean>;
     $recallMessage(id: string): Promise<void>;
     $sendMessage(options: SendOptions): Promise<string>;
 }
@@ -40,6 +134,15 @@ export declare namespace IcqqBot {
 declare class IcqqAdapter extends Adapter<IcqqBot> {
     constructor(plugin: Plugin);
     createBot(config: IcqqBotConfig): IcqqBot;
+    start(): Promise<void>;
+    /**
+     * 注册 ICQQ 平台特有的群管理工具
+     */
+    private registerIcqqTools;
+    /**
+     * 检查执行上下文中的权限
+     */
+    private checkPermission;
 }
 export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,QAAQ,EAAe,MAAM,cAAc,CAAC;AAE7G,OAAO,EACL,GAAG,EAEH,OAAO,EACP,MAAM,EACN,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,MAAM,CAAC;QACf,UAAU,QAAQ;YAChB,GAAG,EAAE,GAAG,CAAC;YACT,MAAM,EAAE,MAAM,CAAC;SAChB;KACF;IAED,UAAU,QAAQ;QAChB,IAAI,EAAE,WAAW,CAAC;KACnB;CACF;AAKD,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,qBAAa,OAAQ,SAAQ,MAAO,YAAW,GAAG,CAAC,aAAa,EAAE,mBAAmB,GAAG,iBAAiB,CAAC;IAOrF,OAAO,EAAE,WAAW;IANvC,UAAU,EAAE,OAAO,CAAS;IAE5B,IAAI,GAAG,gBAEN;gBAEkB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa;IAQ9D,OAAO,CAAC,iBAAiB;IAMnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC,cAAc,CAAC,GAAG,EAAE,mBAAmB,GAAG,iBAAiB;IAiCrD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAgB1D;AAED,yBAAiB,OAAO,CAAC;IAGvB,SAAgB,UAAU,CAAC,OAAO,EAAE,QAAQ,GAAG,cAAc,EAAE,CAW9D;IAED,SAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,CASzD;CACF;AAED,cAAM,WAAY,SAAQ,OAAO,CAAC,OAAO,CAAC;gBAC5B,MAAM,EAAE,MAAM;IAI1B,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;CAG1C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}