@zhin.js/core 1.0.40 → 1.0.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/lib/built/common-adapter-tools.d.ts.map +1 -1
  3. package/lib/built/common-adapter-tools.js +38 -32
  4. package/lib/built/common-adapter-tools.js.map +1 -1
  5. package/package.json +6 -6
  6. package/src/built/common-adapter-tools.ts +38 -32
package/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # @zhin.js/core
2
2
 
3
+ ## 1.0.41
4
+
5
+ ### Patch Changes
6
+
7
+ - 5a68249: fix: 文档优化
8
+ - @zhin.js/database@1.0.28
9
+ - @zhin.js/logger@0.1.25
10
+ - @zhin.js/schema@1.0.25
11
+ - @zhin.js/ai@1.0.2
12
+ - @zhin.js/kernel@0.0.2
13
+
3
14
  ## 1.0.40
4
15
 
5
16
  ### Patch Changes
package/lib/built/common-adapter-tools.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"common-adapter-tools.d.ts","sourceRoot":"","sources":["../../src/built/common-adapter-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAMvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1E,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7F,iBAAiB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACnG,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1F,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3D,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1F,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3E,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACzE,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7D;AAMD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,gBAAgB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,mBAAmB,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAClF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EA8G/C,CAAC;AAMF,eAAO,MAAM,kCAAkC,QAED,CAAC;AAE/C,eAAO,MAAM,2BAA2B,UAAyC,CAAC;AAClF,eAAO,MAAM,+BAA+B,UAG3C,CAAC;AAMF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,gBAAgB,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACxB,GAAG,EAAE,CAcP"}
1
+ {"version":3,"file":"common-adapter-tools.d.ts","sourceRoot":"","sources":["../../src/built/common-adapter-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAMvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1E,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7F,iBAAiB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACnG,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1F,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3D,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1F,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3E,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACzE,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7D;AAMD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,gBAAgB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,mBAAmB,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAClF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EA8G/C,CAAC;AAMF,eAAO,MAAM,kCAAkC,QAQtB,CAAC;AAE1B,eAAO,MAAM,2BAA2B,UAAyC,CAAC;AAClF,eAAO,MAAM,+BAA+B,UAG3C,CAAC;AAMF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,gBAAgB,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACxB,GAAG,EAAE,CAcP"}
package/lib/built/common-adapter-tools.js CHANGED
@@ -20,55 +20,55 @@ export const GROUP_METHOD_SPECS = [
20
20
  {
21
21
  method: 'kickMember',
22
22
  toolSuffix: 'kick_member',
23
- description: '将成员踢出群/服务器',
23
+ description: '将成员踢出群/服务器。适用于严重违规、广告号等需要移除的场景。踢出后该成员将无法再进入群聊（部分平台可重新邀请）。如果只需要用户名而没有 user_id，请先调用 list_members 查询',
24
24
  keywords: ['踢', 'kick', '移除', '踢出'],
25
25
  permissionLevel: 'group_admin',
26
26
  extraParams: {
27
- user_id: { type: 'string', description: '目标用户 ID' },
27
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
28
28
  },
29
29
  extraRequired: ['user_id'],
30
30
  },
31
31
  {
32
32
  method: 'muteMember',
33
33
  toolSuffix: 'mute_member',
34
- description: '禁言群成员（duration=0 解除）',
35
- keywords: ['禁言', 'mute', '静音', '解除禁言'],
34
+ description: '禁言或解除禁言群成员。适用于违规发言、刷屏、骚扰他人等需要临时限制发言的场景。duration 单位为秒，传 0 表示解除禁言。默认禁言 10 分钟(600秒)。如果只有昵称而没有 user_id，请先调用 list_members 查询',
35
+ keywords: ['禁言', 'mute', '静音', '解除禁言', '解禁', '闭嘴'],
36
36
  permissionLevel: 'group_admin',
37
37
  extraParams: {
38
- user_id: { type: 'string', description: '目标用户 ID' },
39
- duration: { type: 'number', description: '禁言时长(秒)，0=解除', default: 600 },
38
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
39
+ duration: { type: 'number', description: '禁言时长(秒)，0=解除禁言，默认600(10分钟)。常用值：60=1分钟, 600=10分钟, 3600=1小时, 86400=1天', default: 600 },
40
40
  },
41
41
  extraRequired: ['user_id'],
42
42
  },
43
43
  {
44
44
  method: 'setMemberNickname',
45
45
  toolSuffix: 'set_nickname',
46
- description: '设置群成员昵称/名片',
47
- keywords: ['昵称', '名片', 'nickname', 'card'],
46
+ description: '设置群成员的群昵称/名片。仅修改群内显示名称，不影响用户的全局昵称。如果只有昵称而没有 user_id，请先调用 list_members 查询',
47
+ keywords: ['昵称', '名片', 'nickname', 'card', '改名片'],
48
48
  permissionLevel: 'group_admin',
49
49
  extraParams: {
50
- user_id: { type: 'string', description: '目标用户 ID' },
51
- nickname: { type: 'string', description: '新昵称' },
50
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
51
+ nickname: { type: 'string', description: '新的群昵称/名片' },
52
52
  },
53
53
  extraRequired: ['user_id', 'nickname'],
54
54
  },
55
55
  {
56
56
  method: 'setAdmin',
57
57
  toolSuffix: 'set_admin',
58
- description: '设置/取消群管理员',
59
- keywords: ['管理员', 'admin', '设置管理'],
58
+ description: '设置或取消群管理员。注意：此操作需要群主权限，普通管理员无法执行。enable=true 为设置管理员，enable=false 为取消管理员。如果只有昵称而没有 user_id，请先调用 list_members 查询',
59
+ keywords: ['管理员', 'admin', '设置管理', '取消管理', '提升管理', '撤销管理'],
60
60
  permissionLevel: 'group_owner',
61
61
  extraParams: {
62
- user_id: { type: 'string', description: '目标用户 ID' },
63
- enable: { type: 'boolean', description: '设置(true)/取消(false)', default: true },
62
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
63
+ enable: { type: 'boolean', description: 'true=设置为管理员，false=取消管理员身份', default: true },
64
64
  },
65
65
  extraRequired: ['user_id'],
66
66
  },
67
67
  {
68
68
  method: 'listMembers',
69
69
  toolSuffix: 'list_members',
70
- description: '获取群/服务器成员列表',
71
- keywords: ['成员', '列表', 'members', 'list'],
70
+ description: '获取群/服务器成员列表。返回所有成员的 ID、昵称、名片、角色等信息。当用户提供昵称/名片而非 ID 时，应先调用此工具查询成员列表，从中匹配到目标用户的 user_id，再执行禁言、踢人等操作',
71
+ keywords: ['成员', '列表', 'members', 'list', '查找', '搜索用户'],
72
72
  permissionLevel: 'user',
73
73
  extraParams: {},
74
74
  preExecutable: true,
@@ -76,52 +76,52 @@ export const GROUP_METHOD_SPECS = [
76
76
  {
77
77
  method: 'banMember',
78
78
  toolSuffix: 'ban_member',
79
- description: '封禁成员',
80
- keywords: ['封禁', 'ban', '拉黑'],
79
+ description: '永久封禁成员（拉入黑名单）。与踢人(kick)不同，封禁后该成员无法再加入群聊。适用于恶意用户、严重违规等需要永久禁止的场景。如果只有昵称而没有 user_id，请先调用 list_members 查询',
80
+ keywords: ['封禁', 'ban', '拉黑', '黑名单'],
81
81
  permissionLevel: 'group_admin',
82
82
  extraParams: {
83
- user_id: { type: 'string', description: '目标用户 ID' },
84
- reason: { type: 'string', description: '封禁原因' },
83
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
84
+ reason: { type: 'string', description: '封禁原因（将记录在封禁日志中）' },
85
85
  },
86
86
  extraRequired: ['user_id'],
87
87
  },
88
88
  {
89
89
  method: 'unbanMember',
90
90
  toolSuffix: 'unban_member',
91
- description: '解除封禁',
92
- keywords: ['解封', 'unban', '解除封禁'],
91
+ description: '解除封禁，将成员从黑名单中移除。解除后该成员可以重新加入群聊。如果只有昵称而没有 user_id，请先调用 list_members 查询',
92
+ keywords: ['解封', 'unban', '解除封禁', '移出黑名单'],
93
93
  permissionLevel: 'group_admin',
94
94
  extraParams: {
95
- user_id: { type: 'string', description: '目标用户 ID' },
95
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
96
96
  },
97
97
  extraRequired: ['user_id'],
98
98
  },
99
99
  {
100
100
  method: 'setGroupName',
101
101
  toolSuffix: 'set_group_name',
102
- description: '修改群名称',
103
- keywords: ['群名', '改名', 'group name'],
102
+ description: '修改群/服务器名称。修改后所有成员立即可见新群名',
103
+ keywords: ['群名', '改名', 'group name', '修改群名'],
104
104
  permissionLevel: 'group_admin',
105
105
  extraParams: {
106
- name: { type: 'string', description: '新群名' },
106
+ name: { type: 'string', description: '新群名称' },
107
107
  },
108
108
  extraRequired: ['name'],
109
109
  },
110
110
  {
111
111
  method: 'muteAll',
112
112
  toolSuffix: 'mute_all',
113
- description: '全员禁言/解除全员禁言',
114
- keywords: ['全员禁言', 'mute all', '全体禁言'],
113
+ description: '开启或关闭全员禁言。开启后除管理员外所有成员都无法发言。适用于紧急维护、重要通知、聊天秩序混乱等场景。enable=true 开启，enable=false 解除',
114
+ keywords: ['全员禁言', 'mute all', '全体禁言', '全体解禁'],
115
115
  permissionLevel: 'group_admin',
116
116
  extraParams: {
117
- enable: { type: 'boolean', description: '开启(true)/解除(false)', default: true },
117
+ enable: { type: 'boolean', description: 'true=开启全员禁言，false=解除全员禁言', default: true },
118
118
  },
119
119
  },
120
120
  {
121
121
  method: 'getGroupInfo',
122
122
  toolSuffix: 'get_group_info',
123
- description: '获取群/服务器基本信息',
124
- keywords: ['群信息', 'group info', '群资料'],
123
+ description: '获取群/服务器基本信息，包括群名、群主、成员数量、创建时间等。用于了解群聊概况',
124
+ keywords: ['群信息', 'group info', '群资料', '群详情'],
125
125
  permissionLevel: 'user',
126
126
  extraParams: {},
127
127
  preExecutable: true,
@@ -131,7 +131,13 @@ export const GROUP_METHOD_SPECS = [
131
131
  // Skill 常量
132
132
  // ============================================================================
133
133
  export const GROUP_MANAGEMENT_SKILL_DESCRIPTION = '群聊管理能力：在 IM 系统中对群/服务器进行管理，包括踢人、禁言、封禁、' +
134
- '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。';
134
+ '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。\n\n' +
135
+ '使用指南：\n' +
136
+ '1. 用户提供昵称/名片而非 ID 时，必须先调用 list_members 查询成员列表，从返回结果中匹配目标用户的 user_id，再执行后续操作\n' +
137
+ '2. 禁言(mute_member)适用场景：违规发言、刷屏、骚扰他人等；传 duration=0 可解除禁言\n' +
138
+ '3. 设置/取消管理员(set_admin)需要群主权限，普通管理员无法操作；enable=false 为取消管理员\n' +
139
+ '4. 踢人(kick_member)是将成员移出群聊，封禁(ban_member)是永久拉黑，两者不同\n' +
140
+ '5. 操作前应确认目标用户正确，避免误操作';
135
141
  export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
136
142
  export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [
137
143
  '群管理', '踢人', '禁言', '封禁', '管理员', '群名',
package/lib/built/common-adapter-tools.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"common-adapter-tools.js","sourceRoot":"","sources":["../../src/built/common-adapter-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAwCH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD;QACE,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE,aAAa;QACzB,WAAW,EAAE,YAAY;QACzB,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;QACnC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;SACpD;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE,aAAa;QACzB,WAAW,EAAE,sBAAsB;QACnC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;QACtC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;YACnD,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,EAAE;SACxE;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,mBAAmB;QAC3B,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,YAAY;QACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC;QAC1C,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;YACnD,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE;SACjD;QACD,aAAa,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;KACvC;IACD;QACE,MAAM,EAAE,UAAU;QAClB,UAAU,EAAE,WAAW;QACvB,WAAW,EAAE,WAAW;QACxB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC;QAClC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;YACnD,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,EAAE,IAAI,EAAE;SAC9E;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,aAAa;QACrB,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,aAAa;QAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC;QACzC,eAAe,EAAE,MAAM;QACvB,WAAW,EAAE,EAAE;QACf,aAAa,EAAE,IAAI;KACpB;IACD;QACE,MAAM,EAAE,WAAW;QACnB,UAAU,EAAE,YAAY;QACxB,WAAW,EAAE,MAAM;QACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC;QAC7B,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;YACnD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE;SAChD;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,aAAa;QACrB,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,MAAM;QACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC;QACjC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE;SACpD;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,cAAc;QACtB,UAAU,EAAE,gBAAgB;QAC5B,WAAW,EAAE,OAAO;QACpB,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,CAAC;QACpC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE;SAC7C;QACD,aAAa,EAAE,CAAC,MAAM,CAAC;KACxB;IACD;QACE,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE,UAAU;QACtB,WAAW,EAAE,aAAa;QAC1B,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC;QACtC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,EAAE,IAAI,EAAE;SAC9E;KACF;IACD;QACE,MAAM,EAAE,cAAc;QACtB,UAAU,EAAE,gBAAgB;QAC5B,WAAW,EAAE,aAAa;QAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC;QACtC,eAAe,EAAE,MAAM;QACvB,WAAW,EAAE,EAAE;QACf,aAAa,EAAE,IAAI;KACpB;CACF,CAAC;AAEF,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,MAAM,CAAC,MAAM,kCAAkC,GAC7C,uCAAuC;IACvC,4CAA4C,CAAC;AAE/C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAClF,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;IACpC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS;CAChD,CAAC;AAEF,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,MAAM,UAAU,eAAe,CAC7B,MAA8B,EAC9B,KAAa,EACb,OAAe,EACf,IAAyB;IAEzB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,YAAY,CAAC,CAAM,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9D,KAAK,YAAY,CAAC,CAAM,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC;QACpF,KAAK,mBAAmB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/E,KAAK,UAAU,CAAC,CAAQ,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;QACnF,KAAK,aAAa,CAAC,CAAK,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,KAAK,WAAW,CAAC,CAAO,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3E,KAAK,aAAa,CAAC,CAAK,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9D,KAAK,cAAc,CAAC,CAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,KAAK,SAAS,CAAC,CAAS,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;QACrE,KAAK,cAAc,CAAC,CAAI,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,CAAC,CAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"common-adapter-tools.js","sourceRoot":"","sources":["../../src/built/common-adapter-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAwCH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD;QACE,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE,aAAa;QACzB,WAAW,EAAE,mGAAmG;QAChH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;QACnC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;SACjF;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE,aAAa;QACzB,WAAW,EAAE,yHAAyH;QACtI,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;QAClD,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;YAChF,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qEAAqE,EAAE,OAAO,EAAE,GAAG,EAAE;SAC/H;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,mBAAmB;QAC3B,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,0EAA0E;QACvF,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC;QACjD,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;YAChF,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE;SACtD;QACD,aAAa,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;KACvC;IACD;QACE,MAAM,EAAE,UAAU;QAClB,UAAU,EAAE,WAAW;QACvB,WAAW,EAAE,gHAAgH;QAC7H,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC1D,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;YAChF,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,2BAA2B,EAAE,OAAO,EAAE,IAAI,EAAE;SACrF;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,aAAa;QACrB,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,mGAAmG;QAChH,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;QACvD,eAAe,EAAE,MAAM;QACvB,WAAW,EAAE,EAAE;QACf,aAAa,EAAE,IAAI;KACpB;IACD;QACE,MAAM,EAAE,WAAW;QACnB,UAAU,EAAE,YAAY;QACxB,WAAW,EAAE,uGAAuG;QACpH,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;QACpC,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;YAChF,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE;SAC3D;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,aAAa;QACrB,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,uEAAuE;QACpF,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC;QAC1C,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;SACjF;QACD,aAAa,EAAE,CAAC,SAAS,CAAC;KAC3B;IACD;QACE,MAAM,EAAE,cAAc;QACtB,UAAU,EAAE,gBAAgB;QAC5B,WAAW,EAAE,0BAA0B;QACvC,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC;QAC5C,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE;SAC9C;QACD,aAAa,EAAE,CAAC,MAAM,CAAC;KACxB;IACD;QACE,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE,UAAU;QACtB,WAAW,EAAE,mFAAmF;QAChG,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC;QAC9C,eAAe,EAAE,aAAa;QAC9B,WAAW,EAAE;YACX,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,0BAA0B,EAAE,OAAO,EAAE,IAAI,EAAE;SACpF;KACF;IACD;QACE,MAAM,EAAE,cAAc;QACtB,UAAU,EAAE,gBAAgB;QAC5B,WAAW,EAAE,yCAAyC;QACtD,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC;QAC7C,eAAe,EAAE,MAAM;QACvB,WAAW,EAAE,EAAE;QACf,aAAa,EAAE,IAAI;KACpB;CACF,CAAC;AAEF,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,MAAM,CAAC,MAAM,kCAAkC,GAC7C,uCAAuC;IACvC,gDAAgD;IAChD,SAAS;IACT,+EAA+E;IAC/E,2DAA2D;IAC3D,8DAA8D;IAC9D,uDAAuD;IACvD,uBAAuB,CAAC;AAE1B,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAClF,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;IACpC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS;CAChD,CAAC;AAEF,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,MAAM,UAAU,eAAe,CAC7B,MAA8B,EAC9B,KAAa,EACb,OAAe,EACf,IAAyB;IAEzB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,YAAY,CAAC,CAAM,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9D,KAAK,YAAY,CAAC,CAAM,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC;QACpF,KAAK,mBAAmB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/E,KAAK,UAAU,CAAC,CAAQ,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;QACnF,KAAK,aAAa,CAAC,CAAK,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,KAAK,WAAW,CAAC,CAAO,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3E,KAAK,aAAa,CAAC,CAAK,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9D,KAAK,cAAc,CAAC,CAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,KAAK,SAAS,CAAC,CAAS,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;QACrE,KAAK,cAAc,CAAC,CAAI,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,CAAC,CAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/core",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "Zhin机器人核心框架",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -37,11 +37,11 @@
37
37
  "segment-matcher": "^1.0.5",
38
38
  "smol-toml": "^1.6.0",
39
39
  "yaml": "^2.3.4",
40
- "@zhin.js/ai": "1.0.1",
41
- "@zhin.js/database": "1.0.27",
42
- "@zhin.js/kernel": "0.0.1",
43
- "@zhin.js/logger": "0.1.24",
44
- "@zhin.js/schema": "1.0.24"
40
+ "@zhin.js/ai": "1.0.2",
41
+ "@zhin.js/database": "1.0.28",
42
+ "@zhin.js/kernel": "0.0.2",
43
+ "@zhin.js/logger": "0.1.25",
44
+ "@zhin.js/schema": "1.0.25"
45
45
  },
46
46
  "devDependencies": {
47
47
  "@types/node": "^24.3.0",
package/src/built/common-adapter-tools.ts CHANGED
@@ -59,55 +59,55 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
59
59
  {
60
60
  method: 'kickMember',
61
61
  toolSuffix: 'kick_member',
62
- description: '将成员踢出群/服务器',
62
+ description: '将成员踢出群/服务器。适用于严重违规、广告号等需要移除的场景。踢出后该成员将无法再进入群聊（部分平台可重新邀请）。如果只需要用户名而没有 user_id，请先调用 list_members 查询',
63
63
  keywords: ['踢', 'kick', '移除', '踢出'],
64
64
  permissionLevel: 'group_admin',
65
65
  extraParams: {
66
- user_id: { type: 'string', description: '目标用户 ID' },
66
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
67
67
  },
68
68
  extraRequired: ['user_id'],
69
69
  },
70
70
  {
71
71
  method: 'muteMember',
72
72
  toolSuffix: 'mute_member',
73
- description: '禁言群成员（duration=0 解除）',
74
- keywords: ['禁言', 'mute', '静音', '解除禁言'],
73
+ description: '禁言或解除禁言群成员。适用于违规发言、刷屏、骚扰他人等需要临时限制发言的场景。duration 单位为秒，传 0 表示解除禁言。默认禁言 10 分钟(600秒)。如果只有昵称而没有 user_id，请先调用 list_members 查询',
74
+ keywords: ['禁言', 'mute', '静音', '解除禁言', '解禁', '闭嘴'],
75
75
  permissionLevel: 'group_admin',
76
76
  extraParams: {
77
- user_id: { type: 'string', description: '目标用户 ID' },
78
- duration: { type: 'number', description: '禁言时长(秒)，0=解除', default: 600 },
77
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
78
+ duration: { type: 'number', description: '禁言时长(秒)，0=解除禁言，默认600(10分钟)。常用值：60=1分钟, 600=10分钟, 3600=1小时, 86400=1天', default: 600 },
79
79
  },
80
80
  extraRequired: ['user_id'],
81
81
  },
82
82
  {
83
83
  method: 'setMemberNickname',
84
84
  toolSuffix: 'set_nickname',
85
- description: '设置群成员昵称/名片',
86
- keywords: ['昵称', '名片', 'nickname', 'card'],
85
+ description: '设置群成员的群昵称/名片。仅修改群内显示名称，不影响用户的全局昵称。如果只有昵称而没有 user_id，请先调用 list_members 查询',
86
+ keywords: ['昵称', '名片', 'nickname', 'card', '改名片'],
87
87
  permissionLevel: 'group_admin',
88
88
  extraParams: {
89
- user_id: { type: 'string', description: '目标用户 ID' },
90
- nickname: { type: 'string', description: '新昵称' },
89
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
90
+ nickname: { type: 'string', description: '新的群昵称/名片' },
91
91
  },
92
92
  extraRequired: ['user_id', 'nickname'],
93
93
  },
94
94
  {
95
95
  method: 'setAdmin',
96
96
  toolSuffix: 'set_admin',
97
- description: '设置/取消群管理员',
98
- keywords: ['管理员', 'admin', '设置管理'],
97
+ description: '设置或取消群管理员。注意：此操作需要群主权限，普通管理员无法执行。enable=true 为设置管理员，enable=false 为取消管理员。如果只有昵称而没有 user_id，请先调用 list_members 查询',
98
+ keywords: ['管理员', 'admin', '设置管理', '取消管理', '提升管理', '撤销管理'],
99
99
  permissionLevel: 'group_owner',
100
100
  extraParams: {
101
- user_id: { type: 'string', description: '目标用户 ID' },
102
- enable: { type: 'boolean', description: '设置(true)/取消(false)', default: true },
101
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
102
+ enable: { type: 'boolean', description: 'true=设置为管理员，false=取消管理员身份', default: true },
103
103
  },
104
104
  extraRequired: ['user_id'],
105
105
  },
106
106
  {
107
107
  method: 'listMembers',
108
108
  toolSuffix: 'list_members',
109
- description: '获取群/服务器成员列表',
110
- keywords: ['成员', '列表', 'members', 'list'],
109
+ description: '获取群/服务器成员列表。返回所有成员的 ID、昵称、名片、角色等信息。当用户提供昵称/名片而非 ID 时，应先调用此工具查询成员列表，从中匹配到目标用户的 user_id，再执行禁言、踢人等操作',
110
+ keywords: ['成员', '列表', 'members', 'list', '查找', '搜索用户'],
111
111
  permissionLevel: 'user',
112
112
  extraParams: {},
113
113
  preExecutable: true,
@@ -115,52 +115,52 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
115
115
  {
116
116
  method: 'banMember',
117
117
  toolSuffix: 'ban_member',
118
- description: '封禁成员',
119
- keywords: ['封禁', 'ban', '拉黑'],
118
+ description: '永久封禁成员（拉入黑名单）。与踢人(kick)不同，封禁后该成员无法再加入群聊。适用于恶意用户、严重违规等需要永久禁止的场景。如果只有昵称而没有 user_id，请先调用 list_members 查询',
119
+ keywords: ['封禁', 'ban', '拉黑', '黑名单'],
120
120
  permissionLevel: 'group_admin',
121
121
  extraParams: {
122
- user_id: { type: 'string', description: '目标用户 ID' },
123
- reason: { type: 'string', description: '封禁原因' },
122
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
123
+ reason: { type: 'string', description: '封禁原因（将记录在封禁日志中）' },
124
124
  },
125
125
  extraRequired: ['user_id'],
126
126
  },
127
127
  {
128
128
  method: 'unbanMember',
129
129
  toolSuffix: 'unban_member',
130
- description: '解除封禁',
131
- keywords: ['解封', 'unban', '解除封禁'],
130
+ description: '解除封禁，将成员从黑名单中移除。解除后该成员可以重新加入群聊。如果只有昵称而没有 user_id，请先调用 list_members 查询',
131
+ keywords: ['解封', 'unban', '解除封禁', '移出黑名单'],
132
132
  permissionLevel: 'group_admin',
133
133
  extraParams: {
134
- user_id: { type: 'string', description: '目标用户 ID' },
134
+ user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
135
135
  },
136
136
  extraRequired: ['user_id'],
137
137
  },
138
138
  {
139
139
  method: 'setGroupName',
140
140
  toolSuffix: 'set_group_name',
141
- description: '修改群名称',
142
- keywords: ['群名', '改名', 'group name'],
141
+ description: '修改群/服务器名称。修改后所有成员立即可见新群名',
142
+ keywords: ['群名', '改名', 'group name', '修改群名'],
143
143
  permissionLevel: 'group_admin',
144
144
  extraParams: {
145
- name: { type: 'string', description: '新群名' },
145
+ name: { type: 'string', description: '新群名称' },
146
146
  },
147
147
  extraRequired: ['name'],
148
148
  },
149
149
  {
150
150
  method: 'muteAll',
151
151
  toolSuffix: 'mute_all',
152
- description: '全员禁言/解除全员禁言',
153
- keywords: ['全员禁言', 'mute all', '全体禁言'],
152
+ description: '开启或关闭全员禁言。开启后除管理员外所有成员都无法发言。适用于紧急维护、重要通知、聊天秩序混乱等场景。enable=true 开启，enable=false 解除',
153
+ keywords: ['全员禁言', 'mute all', '全体禁言', '全体解禁'],
154
154
  permissionLevel: 'group_admin',
155
155
  extraParams: {
156
- enable: { type: 'boolean', description: '开启(true)/解除(false)', default: true },
156
+ enable: { type: 'boolean', description: 'true=开启全员禁言，false=解除全员禁言', default: true },
157
157
  },
158
158
  },
159
159
  {
160
160
  method: 'getGroupInfo',
161
161
  toolSuffix: 'get_group_info',
162
- description: '获取群/服务器基本信息',
163
- keywords: ['群信息', 'group info', '群资料'],
162
+ description: '获取群/服务器基本信息，包括群名、群主、成员数量、创建时间等。用于了解群聊概况',
163
+ keywords: ['群信息', 'group info', '群资料', '群详情'],
164
164
  permissionLevel: 'user',
165
165
  extraParams: {},
166
166
  preExecutable: true,
@@ -173,7 +173,13 @@ export const GROUP_METHOD_SPECS: GroupMethodSpec[] = [
173
173
 
174
174
  export const GROUP_MANAGEMENT_SKILL_DESCRIPTION =
175
175
  '群聊管理能力：在 IM 系统中对群/服务器进行管理，包括踢人、禁言、封禁、' +
176
- '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。';
176
+ '设置管理员、修改群名、查看成员列表等操作。具体可用的操作取决于平台和 Bot 权限。\n\n' +
177
+ '使用指南：\n' +
178
+ '1. 用户提供昵称/名片而非 ID 时，必须先调用 list_members 查询成员列表，从返回结果中匹配目标用户的 user_id，再执行后续操作\n' +
179
+ '2. 禁言(mute_member)适用场景：违规发言、刷屏、骚扰他人等；传 duration=0 可解除禁言\n' +
180
+ '3. 设置/取消管理员(set_admin)需要群主权限，普通管理员无法操作；enable=false 为取消管理员\n' +
181
+ '4. 踢人(kick_member)是将成员移出群聊，封禁(ban_member)是永久拉黑，两者不同\n' +
182
+ '5. 操作前应确认目标用户正确，避免误操作';
177
183
 
178
184
  export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
179
185
  export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [