@zhin.js/core 1.3.2 → 1.3.4

package/lib/built/ai-outbound/prompt.d.ts

@@ -0,0 +1,11 @@
+import type { AiOutboundCapabilities, AiOutboundExtensionDefinition } from './types.js';
+export declare const AI_OUTBOUND_JSON_EXAMPLE = "{\"mentions\":[\"researcher\",\"210723495\"],\"text\":\"\u6B63\u6587\"}";
+export declare function buildCoreAiOutboundPromptHint(capabilities?: AiOutboundCapabilities): string;
+export declare function buildAiOutboundPromptHint(input: {
+    capabilities?: AiOutboundCapabilities;
+    extensions?: readonly AiOutboundExtensionDefinition[];
+    rosterLines?: string[];
+    forceJsonOnly?: boolean;
+}): string;
+/** 检测入站是否含 handoff / @ 意图（协作群 structured_only 信号）。 */
+export declare function detectInboundHandoffIntent(content: string): boolean;

package/lib/built/ai-outbound/prompt.js

@@ -0,0 +1,44 @@
+export const AI_OUTBOUND_JSON_EXAMPLE = '{"mentions":["researcher","210723495"],"text":"正文"}';
+export function buildCoreAiOutboundPromptHint(capabilities) {
+    const lines = [
+        'When your reply must @ peers, send rich media, buttons, or delegate — output JSON only (no Markdown wrapper):',
+        AI_OUTBOUND_JSON_EXAMPLE,
+        'mentions: peer endpoint ID or pipelineRole; text: message body.',
+        'Do NOT write "@researcher" in plain text — the framework converts JSON mentions to real platform @ segments.',
+    ];
+    if (capabilities?.richSegments?.length) {
+        lines.push(`Rich segments (optional "segments" array): ${capabilities.richSegments.join(', ')}.`);
+    }
+    if (capabilities?.interactive === 'native') {
+        lines.push('Interactive buttons: use extensions field per adapter schema.');
+    }
+    return lines.join('\n');
+}
+export function buildAiOutboundPromptHint(input) {
+    const lines = [];
+    if (input.rosterLines?.length) {
+        lines.push(...input.rosterLines);
+    }
+    lines.push(buildCoreAiOutboundPromptHint(input.capabilities));
+    if (input.extensions?.length) {
+        lines.push('Adapter extensions (optional "extensions" object):');
+        for (const ext of input.extensions) {
+            lines.push(`- ${ext.key}: see platform schema`);
+            if (ext.examples[0])
+                lines.push(`  example: ${ext.examples[0]}`);
+        }
+    }
+    if (input.forceJsonOnly) {
+        lines.push('MUST reply with JSON only when @ peers or handoff — no Markdown body with plain "@role" text.');
+    }
+    return lines.join('\n');
+}
+/** 检测入站是否含 handoff / @ 意图（协作群 structured_only 信号）。 */
+export function detectInboundHandoffIntent(content) {
+    const t = content.trim();
+    if (!t)
+        return false;
+    if (t.includes('@'))
+        return true;
+    return /依次|自我介绍|叫大家|请各位|handoff|delegate/i.test(t);
+}

package/lib/built/ai-outbound/resolve.d.ts

@@ -0,0 +1,4 @@
+import type { MessageElement } from '../../types.js';
+import type { AiOutboundParseContext, ZhinAiOutboundPayload } from './types.js';
+/** 将 ZhinAiOutboundPayload 转为 MessageElement[]（canonical segments + extensions）。 */
+export declare function resolveAiOutboundToMessageElements(payload: ZhinAiOutboundPayload, ctx: AiOutboundParseContext): Promise<MessageElement[] | null>;

package/lib/built/ai-outbound/resolve.js

@@ -0,0 +1,64 @@
+import { segmentsForImDelivery } from '../segment-contract/delivery.js';
+function buildMentionSegments(endpointIds, text, ctx) {
+    const segments = [];
+    for (const endpointId of endpointIds) {
+        const target = ctx.atIdResolver?.(endpointId) ?? endpointId;
+        segments.push({ type: 'mention', data: { target } });
+    }
+    const body = text.trim();
+    segments.push({
+        type: 'text',
+        data: { text: body.startsWith(' ') ? body : ` ${body}` },
+    });
+    return segments;
+}
+function resolveMentionEndpointIds(mentions, ctx) {
+    if (!mentions?.length) {
+        return { ok: false, error: 'mentions 不能为空' };
+    }
+    if (!ctx.mentionResolver) {
+        return { ok: false, error: 'mentionResolver 未配置' };
+    }
+    const endpointIds = [];
+    for (const ref of mentions) {
+        const resolved = ctx.mentionResolver(ref);
+        if (!resolved) {
+            return { ok: false, error: `未知 peer "${ref}"` };
+        }
+        if (!endpointIds.includes(resolved))
+            endpointIds.push(resolved);
+    }
+    return { ok: true, endpointIds };
+}
+/** 将 ZhinAiOutboundPayload 转为 MessageElement[]（canonical segments + extensions）。 */
+export async function resolveAiOutboundToMessageElements(payload, ctx) {
+    const segments = [];
+    if (payload.mentions?.length) {
+        const resolved = resolveMentionEndpointIds(payload.mentions, ctx);
+        if (!resolved.ok)
+            return null;
+        const text = payload.text?.trim() ?? '';
+        if (!text)
+            return null;
+        segments.push(...buildMentionSegments(resolved.endpointIds, text, ctx));
+    }
+    else if (payload.text?.trim()) {
+        segments.push({ type: 'text', data: { text: payload.text.trim() } });
+    }
+    if (payload.segments?.length) {
+        segments.push(...payload.segments);
+    }
+    const parts = segments.length
+        ? segmentsForImDelivery(segments)
+        : [];
+    if (payload.extensions && ctx.extensions?.length) {
+        for (const def of ctx.extensions) {
+            const ext = payload.extensions[def.key];
+            if (ext == null || !def.toMessageElements)
+                continue;
+            const extSegments = await def.toMessageElements(ext, ctx);
+            parts.push(...(Array.isArray(extSegments) ? extSegments : [extSegments]));
+        }
+    }
+    return parts.length ? parts : null;
+}

package/lib/built/ai-outbound/structured-detect.d.ts

@@ -0,0 +1,3 @@
+import type { StructuredOutboundDetectInput } from './types.js';
+/** structured_only：满足任一即进入结构化出站模式。 */
+export declare function isStructuredOutboundRequired(input: StructuredOutboundDetectInput): boolean;

package/lib/built/ai-outbound/structured-detect.js

@@ -0,0 +1,7 @@
+/** structured_only：满足任一即进入结构化出站模式。 */
+export function isStructuredOutboundRequired(input) {
+    return Boolean(input.collaborationCell
+        || input.toolRequiresStructured
+        || input.inboundHandoffIntent
+        || input.adapterHasExtensions);
+}

package/lib/built/ai-outbound/types.d.ts

@@ -0,0 +1,60 @@
+import type { Message } from '../../message.js';
+import type { MessageElement } from '../../types.js';
+import type { InteractivePolicy } from '../interactive-segments/types.js';
+import type { Segment } from '../segment-contract/types.js';
+/** AI 结构化出站 payload — 平台无关 DSL（Adapter extensions 承载平台特有段）。 */
+export interface ZhinAiOutboundPayload {
+    text?: string;
+    mentions?: string[];
+    segments?: Segment[];
+    extensions?: Record<string, unknown>;
+}
+/**
+ * @deprecated 使用 canonical `Segment`（`type` + `data` + 可选 `platform`）。
+ * 历史 `kind` → `type`；`mode` 已删除。
+ */
+export interface AiOutboundSegment {
+    kind: string;
+    mode?: string;
+    data?: Record<string, unknown>;
+}
+export interface AiOutboundCapabilities {
+    mentions?: boolean;
+    richSegments?: readonly string[];
+    interactive?: InteractivePolicy;
+}
+export interface AiOutboundExtensionDefinition {
+    /** 平台扩展字段名，如 qq.ark / onebot.keyboard */
+    key: string;
+    /** JSON Schema 子集，对齐平台 SDK 文档 */
+    schema: Record<string, unknown>;
+    examples: readonly string[];
+    toMessageElements?: (ext: unknown, ctx: AiOutboundParseContext) => MessageElement[] | Promise<MessageElement[]>;
+}
+export interface AiOutboundMentionResolver {
+    (ref: string): string | undefined;
+}
+export interface AiOutboundAtIdResolver {
+    (endpointId: string): string;
+}
+/** 解析 AI 出站 JSON 时的上下文。 */
+export interface AiOutboundParseContext {
+    message: Message;
+    /** 将 peer ref（role/endpoint/primary）解析为 endpointId */
+    mentionResolver?: AiOutboundMentionResolver;
+    /** 将 endpointId 解析为 platform @ id */
+    atIdResolver?: AiOutboundAtIdResolver;
+    /** Adapter 声明的 extensions（运行时从 Adapter 静态属性注入） */
+    extensions?: readonly AiOutboundExtensionDefinition[];
+}
+export interface StructuredOutboundDetectInput {
+    /** 协作 Cell 活跃且可能 @ peer */
+    collaborationCell?: boolean;
+    /** 工具链要求结构化出站（如 group_delegate message JSON） */
+    toolRequiresStructured?: boolean;
+    /** 用户入站含 handoff / @ 意图 */
+    inboundHandoffIntent?: boolean;
+    /** Adapter 声明 extensions 且非空 */
+    adapterHasExtensions?: boolean;
+}
+export declare const DEFAULT_AI_OUTBOUND_CAPABILITIES: AiOutboundCapabilities;

package/lib/built/ai-outbound/types.js

@@ -0,0 +1,5 @@
+export const DEFAULT_AI_OUTBOUND_CAPABILITIES = {
+    mentions: true,
+    richSegments: ['qrcode', 'html', 'markdown', 'tts'],
+    interactive: 'text',
+};

package/lib/built/ai-trigger.d.ts

@@ -39,6 +39,11 @@ export interface AITriggerConfig {
     trusted?: string[];
     /** 是否在 AI 入参前拉取 $quote_id 对应消息正文（默认 true） */
     resolveQuotedMessages?: boolean;
+    /**
+     * 协作单元内 peer Bot 入站策略（ADR 0023）。
+     * mention-only：仅被 @ 时触发；off：与普通人消息相同规则。
+     */
+    peerMode?: 'mention-only' | 'off';
 }
 /**
  * AI 触发检查结果
@@ -97,4 +102,3 @@ export declare function shouldTriggerAI<T extends object>(message: Message<T>, c
  * 合并配置
  */
 export declare function mergeAITriggerConfig(config: AITriggerConfig): Required<AITriggerConfig>;
-//# sourceMappingURL=ai-trigger.d.ts.map

package/lib/built/ai-trigger.js

@@ -9,6 +9,7 @@
  * 4. 关键词触发 - 非群/频道场景下匹配关键词时触发
  */
 import { segment } from "../utils.js";
+import { readMentionSegmentTarget } from './segment-contract/mention.js';
 import { normalizeSenderRoles, } from './roles.js';
 // ============================================================================
 // 默认配置
@@ -26,6 +27,7 @@ export const DEFAULT_AI_TRIGGER_CONFIG = {
     masters: [],
     trusted: [],
     resolveQuotedMessages: true,
+    peerMode: 'mention-only',
 };
 // ============================================================================
 // 工具函数
@@ -35,12 +37,7 @@ function normalizeAtIds(endpointAtIds) {
     return [...new Set(ids.map((id) => String(id)).filter(Boolean))];
 }
 function segmentAtUserId(seg) {
-    const { data } = seg;
-    if (!data || typeof data !== 'object')
-        return '';
-    const record = data;
-    const raw = record.user_id ?? record.qq ?? record.id;
-    return raw == null ? '' : String(raw);
+    return readMentionSegmentTarget(seg);
 }
 function isAtSegmentForEndpoint(seg, endpointIds) {
     if (seg.type !== 'at' && seg.type !== 'mention')
@@ -233,4 +230,3 @@ export function shouldTriggerAI(message, config, options) {
 export function mergeAITriggerConfig(config) {
     return { ...DEFAULT_AI_TRIGGER_CONFIG, ...config };
 }
-//# sourceMappingURL=ai-trigger.js.map

package/lib/built/authorization.d.ts

@@ -8,4 +8,3 @@ import { type SenderRolesResult } from './ai-trigger.js';
  * 从 ConfigFeature + Message 重算发送者角色（含群角色与 master/trusted）
  */
 export declare function resolveSubjectRoles(plugin: Plugin, message: Message<any>): SenderRolesResult;
-//# sourceMappingURL=authorization.d.ts.map

package/lib/built/authorization.js

@@ -50,4 +50,3 @@ export function resolveSubjectRoles(plugin, message) {
     const endpointConfig = readEndpointConfig(plugin, message);
     return resolveSenderRoles(message, triggerConfig, endpointConfig);
 }
-//# sourceMappingURL=authorization.js.map

package/lib/built/command.d.ts

@@ -67,4 +67,3 @@ export declare class CommandFeature extends Feature<MessageCommand<RegisteredAda
         addCommand<T extends RegisteredAdapter>(command: MessageCommand<T>): () => void;
     };
 }
-//# sourceMappingURL=command.d.ts.map

package/lib/built/command.js

@@ -19,7 +19,6 @@ export function compareCommandPatterns(a, b) {
     const tokB = b.trim().split(/\s+/).length;
     return tokB - tokA;
 }
-import { getPlugin } from "../plugin.js";
 /**
  * 命令服务 Feature
  */
@@ -92,7 +91,7 @@ export class CommandFeature extends Feature {
         const feature = this;
         return {
             addCommand(command) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const dispose = feature.add(command, plugin.name);
                 plugin.recordFeatureContribution(feature.name, command.pattern);
                 plugin.onDispose(dispose);
@@ -101,4 +100,3 @@ export class CommandFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=command.js.map

package/lib/built/common-adapter-tools.d.ts

@@ -1,36 +1,36 @@
 /**
- * Group Management — 方法规范与 Tool 工厂
+ * Scene Management — 方法规范与 Tool 工厂
  *
  * 设计理念：
- *   各 IM 平台在适配器内自行实现群管方法（kickMember、muteMember 等），
+ *   各 IM 平台在适配器内自行实现场景治理方法（removeMember、muteMember 等），
  *   并自行注册 Tool；平台说明使用包内 `skills/<adapter>/SKILL.md`。
  *
  * 使用方式（在各适配器 start 或注册方法中）：
  *
- *   import { createGroupManagementTools, GROUP_MANAGEMENT_SKILL_KEYWORDS, GROUP_MANAGEMENT_SKILL_TAGS } from 'zhin.js';
- *   const tools = createGroupManagementTools(this, this.name);
+ *   import { createSceneManagementTools, SCENE_MANAGEMENT_SKILL_KEYWORDS, SCENE_MANAGEMENT_SKILL_TAGS } from 'zhin.js';
+ *   const tools = createSceneManagementTools(this, this.name);
  *   tools.forEach(t => this.addTool(t));
  *   // 另：包内 skills/<name>/SKILL.md 供 Agent 发现
  */
 import type { Tool } from '../types.js';
 /**
- * 群管理能力接口。
+ * 场景治理能力接口。
  * Adapter 基类通过此接口声明方法签名，子类选择性覆写。
  */
-export interface IGroupManagement {
-    kickMember?(endpointId: string, sceneId: string, userId: string): Promise<any>;
+export interface ISceneManagement {
+    removeMember?(endpointId: string, sceneId: string, userId: string): Promise<any>;
     muteMember?(endpointId: string, sceneId: string, userId: string, duration?: number): Promise<any>;
     setMemberNickname?(endpointId: string, sceneId: string, userId: string, nickname: string): Promise<any>;
-    setAdmin?(endpointId: string, sceneId: string, userId: string, enable?: boolean): Promise<any>;
+    setModerator?(endpointId: string, sceneId: string, userId: string, enable?: boolean): Promise<any>;
     listMembers?(endpointId: string, sceneId: string): Promise<any>;
     banMember?(endpointId: string, sceneId: string, userId: string, reason?: string): Promise<any>;
     unbanMember?(endpointId: string, sceneId: string, userId: string): Promise<any>;
-    setGroupName?(endpointId: string, sceneId: string, name: string): Promise<any>;
-    muteAll?(endpointId: string, sceneId: string, enable?: boolean): Promise<any>;
-    getGroupInfo?(endpointId: string, sceneId: string): Promise<any>;
+    renameScene?(endpointId: string, sceneId: string, name: string): Promise<any>;
+    setSceneMuted?(endpointId: string, sceneId: string, enable?: boolean): Promise<any>;
+    getSceneInfo?(endpointId: string, sceneId: string): Promise<any>;
 }
-export interface GroupMethodSpec {
-    method: keyof IGroupManagement;
+export interface SceneManagementMethodSpec {
+    method: keyof ISceneManagement;
     toolSuffix: string;
     description: string;
     keywords: string[];
@@ -43,20 +43,19 @@ export interface GroupMethodSpec {
     extraRequired?: string[];
     preExecutable?: boolean;
 }
-export declare const GROUP_METHOD_SPECS: GroupMethodSpec[];
-export declare const GROUP_MANAGEMENT_SKILL_TAGS: string[];
-export declare const GROUP_MANAGEMENT_SKILL_KEYWORDS: string[];
-export interface GroupManagementToolFactory<T> {
-    (spec: GroupMethodSpec, prefix: string, execute: (args: Record<string, any>) => Promise<any>): T;
+export declare const SCENE_MANAGEMENT_METHOD_SPECS: SceneManagementMethodSpec[];
+export declare const SCENE_MANAGEMENT_SKILL_TAGS: string[];
+export declare const SCENE_MANAGEMENT_SKILL_KEYWORDS: string[];
+export interface SceneManagementToolFactory<T> {
+    (spec: SceneManagementMethodSpec, prefix: string, execute: (args: Record<string, any>) => Promise<any>): T;
 }
-export declare function defaultQqGroupPermitResolver(adapterPrefix: string): (logicalPerm: string) => string;
-export interface CreateGroupManagementToolsOptions {
-    /** 将 GROUP_METHOD_SPECS 逻辑 perm（group_admin/group_owner）映射为 platform(...) 字符串 */
+export declare function defaultScenePermitResolver(adapterPrefix: string): (logicalPerm: string) => string;
+export interface CreateSceneManagementToolsOptions {
+    /** 将 SCENE_MANAGEMENT_METHOD_SPECS 逻辑 perm（scene_admin/scene_owner）映射为 platform(...) 字符串 */
     permitResolver?: (logicalPerm: string) => string | undefined;
-    /** 是否注册默认 QQ 系 group checker（默认 true） */
+    /** 是否注册默认 QQ 系 scene checker（默认 true） */
     registerChecker?: boolean;
 }
-export declare function createGroupManagementTools(adapter: IGroupManagement, prefix: string, options?: CreateGroupManagementToolsOptions): Tool[];
-export declare function createGroupManagementToolsRaw<T>(adapter: IGroupManagement, prefix: string, factory: GroupManagementToolFactory<T>): T[];
-export declare function buildMethodArgs(method: keyof IGroupManagement, endpointId: string, sceneId: string, rest: Record<string, any>): any[];
-//# sourceMappingURL=common-adapter-tools.d.ts.map
+export declare function createSceneManagementTools(adapter: ISceneManagement, prefix: string, options?: CreateSceneManagementToolsOptions): Tool[];
+export declare function createSceneManagementToolsRaw<T>(adapter: ISceneManagement, prefix: string, factory: SceneManagementToolFactory<T>): T[];
+export declare function buildSceneMethodArgs(method: keyof ISceneManagement, endpointId: string, sceneId: string, rest: Record<string, any>): any[];

package/lib/built/common-adapter-tools.js

@@ -1,25 +1,25 @@
 /**
- * Group Management — 方法规范与 Tool 工厂
+ * Scene Management — 方法规范与 Tool 工厂
  *
  * 设计理念：
- *   各 IM 平台在适配器内自行实现群管方法（kickMember、muteMember 等），
+ *   各 IM 平台在适配器内自行实现场景治理方法（removeMember、muteMember 等），
  *   并自行注册 Tool；平台说明使用包内 `skills/<adapter>/SKILL.md`。
  *
  * 使用方式（在各适配器 start 或注册方法中）：
  *
- *   import { createGroupManagementTools, GROUP_MANAGEMENT_SKILL_KEYWORDS, GROUP_MANAGEMENT_SKILL_TAGS } from 'zhin.js';
- *   const tools = createGroupManagementTools(this, this.name);
+ *   import { createSceneManagementTools, SCENE_MANAGEMENT_SKILL_KEYWORDS, SCENE_MANAGEMENT_SKILL_TAGS } from 'zhin.js';
+ *   const tools = createSceneManagementTools(this, this.name);
  *   tools.forEach(t => this.addTool(t));
  *   // 另：包内 skills/<name>/SKILL.md 供 Agent 发现
  */
-import { registerDefaultGroupPlatformPermitChecker } from './platform-permit.js';
-export const GROUP_METHOD_SPECS = [
+import { registerDefaultScenePlatformPermitChecker } from './platform-permit.js';
+export const SCENE_MANAGEMENT_METHOD_SPECS = [
     {
-        method: 'kickMember',
-        toolSuffix: 'kick_member',
-        description: '将成员踢出群/服务器。适用于严重违规、广告号等需要移除的场景。踢出后该成员将无法再进入群聊（部分平台可重新邀请）。如果只需要用户名而没有 user_id，请先调用 list_members 查询',
+        method: 'removeMember',
+        toolSuffix: 'remove_member',
+        description: '将成员移出当前 IM 场景。适用于严重违规、广告号等需要移除的场景。如果只需要用户名而没有 user_id，请先调用 list_members 查询',
         keywords: ['踢', 'kick', '移除', '踢出'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
         },
@@ -30,7 +30,7 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'mute_member',
         description: '禁言或解除禁言群成员。适用于违规发言、刷屏、骚扰他人等需要临时限制发言的场景。duration 单位为秒，传 0 表示解除禁言。默认禁言 10 分钟(600秒)。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['禁言', 'mute', '静音', '解除禁言', '解禁', '闭嘴'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             duration: { type: 'number', description: '禁言时长(秒)，0=解除禁言，默认600(10分钟)。常用值：60=1分钟, 600=10分钟, 3600=1小时, 86400=1天', default: 600 },
@@ -42,7 +42,7 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'set_nickname',
         description: '设置群成员的群昵称/名片。仅修改群内显示名称，不影响用户的全局昵称。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['昵称', '名片', 'nickname', 'card', '改名片'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             nickname: { type: 'string', description: '新的群昵称/名片' },
@@ -50,11 +50,11 @@ export const GROUP_METHOD_SPECS = [
         extraRequired: ['user_id', 'nickname'],
     },
     {
-        method: 'setAdmin',
-        toolSuffix: 'set_admin',
-        description: '设置或取消群管理员。注意：此操作需要群主权限，普通管理员无法执行。enable=true 为设置管理员，enable=false 为取消管理员。如果只有昵称而没有 user_id，请先调用 list_members 查询',
+        method: 'setModerator',
+        toolSuffix: 'set_moderator',
+        description: '设置或取消场景管理员。注意：此操作通常需要场景所有者权限。enable=true 为设置管理员，enable=false 为取消管理员。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['管理员', 'admin', '设置管理', '取消管理', '提升管理', '撤销管理'],
-        permit: 'group_owner',
+        permit: 'scene_owner',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             enable: { type: 'boolean', description: 'true=设置为管理员，false=取消管理员身份', default: true },
@@ -74,7 +74,7 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'ban_member',
         description: '永久封禁成员（拉入黑名单）。与踢人(kick)不同，封禁后该成员无法再加入群聊。适用于恶意用户、严重违规等需要永久禁止的场景。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['封禁', 'ban', '拉黑', '黑名单'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             reason: { type: 'string', description: '封禁原因（将记录在封禁日志中）' },
@@ -86,37 +86,37 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'unban_member',
         description: '解除封禁，将成员从黑名单中移除。解除后该成员可以重新加入群聊。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['解封', 'unban', '解除封禁', '移出黑名单'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
         },
         extraRequired: ['user_id'],
     },
     {
-        method: 'setGroupName',
-        toolSuffix: 'set_group_name',
-        description: '修改群/服务器名称。修改后所有成员立即可见新群名',
+        method: 'renameScene',
+        toolSuffix: 'rename_scene',
+        description: '修改 IM 场景名称。修改后所有成员立即可见新名称',
         keywords: ['群名', '改名', 'group name', '修改群名'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             name: { type: 'string', description: '新群名称' },
         },
         extraRequired: ['name'],
     },
     {
-        method: 'muteAll',
-        toolSuffix: 'mute_all',
-        description: '开启或关闭全员禁言。开启后除管理员外所有成员都无法发言。适用于紧急维护、重要通知、聊天秩序混乱等场景。enable=true 开启，enable=false 解除',
+        method: 'setSceneMuted',
+        toolSuffix: 'set_scene_muted',
+        description: '开启或关闭场景全员禁言。开启后除管理员外所有成员都无法发言。适用于紧急维护、重要通知、聊天秩序混乱等场景。enable=true 开启，enable=false 解除',
         keywords: ['全员禁言', 'mute all', '全体禁言', '全体解禁'],
-        permit: 'group_admin',
+        permit: 'scene_admin',
         extraParams: {
             enable: { type: 'boolean', description: 'true=开启全员禁言，false=解除全员禁言', default: true },
         },
     },
     {
-        method: 'getGroupInfo',
-        toolSuffix: 'get_group_info',
-        description: '获取群/服务器基本信息，包括群名、群主、成员数量、创建时间等。用于了解群聊概况',
+        method: 'getSceneInfo',
+        toolSuffix: 'get_scene_info',
+        description: '获取 IM 场景基本信息，包括名称、所有者、成员数量、创建时间等。用于了解场景概况',
         keywords: ['群信息', 'group info', '群资料', '群详情'],
         extraParams: {},
         preExecutable: true,
@@ -125,12 +125,12 @@ export const GROUP_METHOD_SPECS = [
 // ============================================================================
 // Skill 常量（群管相关 SKILL.md 与文档可复用 keywords/tags）
 // ============================================================================
-export const GROUP_MANAGEMENT_SKILL_TAGS = ['group', 'management', 'im', 'admin'];
-export const GROUP_MANAGEMENT_SKILL_KEYWORDS = [
-    '群管理', '踢人', '禁言', '封禁', '管理员', '群名',
+export const SCENE_MANAGEMENT_SKILL_TAGS = ['scene', 'management', 'im', 'admin'];
+export const SCENE_MANAGEMENT_SKILL_KEYWORDS = [
+    '场景治理', '群管理', '踢人', '禁言', '封禁', '管理员', '群名',
     '成员', 'kick', 'mute', 'ban', 'admin', 'members',
 ];
-export function defaultQqGroupPermitResolver(adapterPrefix) {
+export function defaultScenePermitResolver(adapterPrefix) {
     return (logicalPerm) => `platform(${adapterPrefix},${logicalPerm})`;
 }
 function resolveSpecPermit(specPerm, prefix, permitResolver) {
@@ -139,12 +139,12 @@ function resolveSpecPermit(specPerm, prefix, permitResolver) {
     const resolved = permitResolver(specPerm);
     return resolved ? [resolved] : undefined;
 }
-export function createGroupManagementTools(adapter, prefix, options = {}) {
-    const permitResolver = options.permitResolver ?? defaultQqGroupPermitResolver(prefix);
+export function createSceneManagementTools(adapter, prefix, options = {}) {
+    const permitResolver = options.permitResolver ?? defaultScenePermitResolver(prefix);
     if (options.registerChecker !== false) {
-        registerDefaultGroupPlatformPermitChecker(prefix);
+        registerDefaultScenePlatformPermitChecker(prefix);
     }
-    return createGroupManagementToolsRaw(adapter, prefix, (spec, prefix, execute) => {
+    return createSceneManagementToolsRaw(adapter, prefix, (spec, prefix, execute) => {
         const specPermissions = resolveSpecPermit(spec.permit, prefix, permitResolver);
         return {
             name: `${prefix}_${spec.toolSuffix}`,
@@ -153,13 +153,13 @@ export function createGroupManagementTools(adapter, prefix, options = {}) {
                 type: 'object',
                 properties: {
                     endpoint_id: { type: 'string', description: 'Endpoint ID', contextKey: 'endpointId' },
-                    scene_id: { type: 'string', description: '群/服务器 ID', contextKey: 'sceneId' },
+                    scene_id: { type: 'string', description: 'IM 场景 ID', contextKey: 'sceneId' },
                     ...Object.fromEntries(Object.entries(spec.extraParams)),
                 },
                 required: ['endpoint_id', 'scene_id', ...(spec.extraRequired ?? [])],
             },
             execute,
-            tags: ['group', 'management', prefix],
+            tags: ['scene', 'management', prefix],
             keywords: spec.keywords,
             ...(specPermissions ? { permissions: specPermissions } : {}),
             scopes: ['group', 'channel'],
@@ -167,16 +167,16 @@ export function createGroupManagementTools(adapter, prefix, options = {}) {
         };
     });
 }
-export function createGroupManagementToolsRaw(adapter, prefix, factory) {
+export function createSceneManagementToolsRaw(adapter, prefix, factory) {
     const tools = [];
-    for (const spec of GROUP_METHOD_SPECS) {
+    for (const spec of SCENE_MANAGEMENT_METHOD_SPECS) {
         const fn = adapter[spec.method];
         if (typeof fn !== 'function')
             continue;
         const boundFn = fn.bind(adapter);
         const execute = async (args) => {
             const { endpoint_id, scene_id, ...rest } = args;
-            const methodArgs = buildMethodArgs(spec.method, endpoint_id, scene_id, rest);
+            const methodArgs = buildSceneMethodArgs(spec.method, endpoint_id, scene_id, rest);
             return boundFn.apply(adapter, methodArgs);
         };
         tools.push(factory(spec, prefix, execute));
@@ -186,19 +186,18 @@ export function createGroupManagementToolsRaw(adapter, prefix, factory) {
 // ============================================================================
 // 参数映射（method → 有序参数列表）
 // ============================================================================
-export function buildMethodArgs(method, endpointId, sceneId, rest) {
+export function buildSceneMethodArgs(method, endpointId, sceneId, rest) {
     switch (method) {
-        case 'kickMember': return [endpointId, sceneId, rest.user_id];
+        case 'removeMember': return [endpointId, sceneId, rest.user_id];
         case 'muteMember': return [endpointId, sceneId, rest.user_id, rest.duration ?? 600];
         case 'setMemberNickname': return [endpointId, sceneId, rest.user_id, rest.nickname];
-        case 'setAdmin': return [endpointId, sceneId, rest.user_id, rest.enable ?? true];
+        case 'setModerator': return [endpointId, sceneId, rest.user_id, rest.enable ?? true];
         case 'listMembers': return [endpointId, sceneId];
         case 'banMember': return [endpointId, sceneId, rest.user_id, rest.reason];
         case 'unbanMember': return [endpointId, sceneId, rest.user_id];
-        case 'setGroupName': return [endpointId, sceneId, rest.name];
-        case 'muteAll': return [endpointId, sceneId, rest.enable ?? true];
-        case 'getGroupInfo': return [endpointId, sceneId];
+        case 'renameScene': return [endpointId, sceneId, rest.name];
+        case 'setSceneMuted': return [endpointId, sceneId, rest.enable ?? true];
+        case 'getSceneInfo': return [endpointId, sceneId];
         default: return [endpointId, sceneId, ...Object.values(rest)];
     }
 }
-//# sourceMappingURL=common-adapter-tools.js.map

package/lib/built/component.d.ts

@@ -2,9 +2,8 @@
  * ComponentFeature
  * 管理所有插件注册的组件，继承自 Feature 抽象类
  */
-import { Feature, FeatureJSON } from "@zhin.js/kernel";
+import { Feature, FeatureJSON, type PluginLike } from '@zhin.js/kernel';
 import { Component } from "../component.js";
-import type { PluginLike } from '@zhin.js/kernel';
 /**
  * ComponentContext 扩展方法类型
  */
@@ -66,4 +65,3 @@ export declare class ComponentFeature extends Feature<Component<any>> {
         addComponent<T extends Component<any>>(component: T): () => void;
     };
 }
-//# sourceMappingURL=component.d.ts.map