@zhin.js/core 1.1.33 → 1.1.35

package/lib/built/ai-trigger.js

@@ -9,7 +9,7 @@
  * 4. 关键词触发 - 非群/频道场景下匹配关键词时触发
  */
 import { segment } from "../utils.js";
-import { resolveIMSessionId, } from '@zhin.js/ai';
+import { readMentionSegmentTarget } from './segment-contract/mention.js';
 import { normalizeSenderRoles, } from './roles.js';
 // ============================================================================
 // 默认配置
@@ -26,50 +26,44 @@ export const DEFAULT_AI_TRIGGER_CONFIG = {
     errorTemplate: '❌ AI 处理失败: {error}',
     masters: [],
     trusted: [],
-    resolveQuotedMessages: true,
 };
 // ============================================================================
 // 工具函数
 // ============================================================================
-function normalizeAtIds(botAtIds) {
-    const ids = botAtIds?.length ? botAtIds : [];
+function normalizeAtIds(endpointAtIds) {
+    const ids = endpointAtIds?.length ? 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 isAtSegmentForBot(seg, botIds) {
+function isAtSegmentForEndpoint(seg, endpointKeys) {
     if (seg.type !== 'at' && seg.type !== 'mention')
         return false;
     const uid = segmentAtUserId(seg);
-    return uid !== '' && botIds.includes(uid);
+    return uid !== '' && endpointKeys.includes(uid);
 }
-function textMentionsBot(text, botIds) {
-    for (const id of botIds) {
+function textMentionsEndpoint(text, endpointKeys) {
+    for (const id of endpointKeys) {
         const re = new RegExp(`@${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|$|[\\u200b\\uFEFF])`);
         if (re.test(text))
             return true;
     }
     return false;
 }
-function stripTextAtBot(text, botIds) {
+function stripTextAtEndpoint(text, endpointKeys) {
     let result = text;
-    for (const id of botIds) {
+    for (const id of endpointKeys) {
         const re = new RegExp(`@${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|[\\u200b\\uFEFF])?`, 'g');
         result = result.replace(re, '');
     }
     return result;
 }
 /**
- * 收集用于 @ 匹配的 bot 标识符
+ * 收集用于 @ 匹配的 Endpoint 标识符
  */
-export function collectBotAtIds(message, extraIds) {
-    const ids = new Set([String(message.$bot)]);
+export function collectEndpointAtIds(message, extraIds) {
+    const ids = new Set([String(message.$endpoint)]);
     for (const id of extraIds ?? []) {
         if (id)
             ids.add(String(id));
@@ -77,15 +71,15 @@ export function collectBotAtIds(message, extraIds) {
     return [...ids];
 }
 /**
- * 检查消息是否 @ 了机器人
+ * 检查消息是否 @ 了 Endpoint
  */
-export function isAtBot(message, botAtIds) {
-    const botIds = normalizeAtIds(botAtIds?.length ? botAtIds : collectBotAtIds(message));
-    if (message.$content.some((seg) => isAtSegmentForBot(seg, botIds))) {
+export function isAtEndpoint(message, endpointAtIds) {
+    const endpointKeys = normalizeAtIds(endpointAtIds?.length ? endpointAtIds : collectEndpointAtIds(message));
+    if (message.$content.some((seg) => isAtSegmentForEndpoint(seg, endpointKeys))) {
         return true;
     }
     for (const seg of message.$content) {
-        if (seg.type === 'text' && seg.data?.text && textMentionsBot(seg.data.text, botIds)) {
+        if (seg.type === 'text' && seg.data?.text && textMentionsEndpoint(seg.data.text, endpointKeys)) {
             return true;
         }
     }
@@ -98,6 +92,22 @@ export function isAtBot(message, botAtIds) {
 export function extractTextContent(message) {
     return segment.toString(message.$content);
 }
+/**
+ * 为群/频道消息构建发送者前缀（与 sender-extra.ts buildSenderPrefix 格式对齐）
+ * 私聊消息返回 null
+ */
+export function buildSenderPrefixForMessage(message, roles) {
+    const scope = message.$channel?.type || 'private';
+    if (scope !== 'group' && scope !== 'channel')
+        return null;
+    const rawId = String(message.$sender?.id ?? 'unknown');
+    const id = rawId.trim().replace(/[\]\s]+/g, '_').slice(0, 64) || 'unknown';
+    const rawName = message.$sender?.name;
+    const name = (rawName?.trim() || 'unknown').replace(/[\]\s]+/g, '_').slice(0, 64);
+    const nonUserRoles = roles.filter((r) => r !== 'user');
+    const roleStr = nonUserRoles.join(',') || 'user';
+    return `[sender:id=${id} name=${name} roles=${roleStr}]`;
+}
 /**
  * 解析 AI 回复中的富媒体内容
  * 将字符串中的 XML-like 标签解析为 MessageElement
@@ -118,23 +128,23 @@ export function parseRichMediaContent(content) {
     }
 }
 /**
- * 移除 @ 机器人的部分
+ * 移除 @ Endpoint 的部分
  */
-export function removeAtBot(message, botAtIds) {
-    const botIds = normalizeAtIds(botAtIds?.length ? botAtIds : collectBotAtIds(message));
+export function removeAtEndpoint(message, endpointAtIds) {
+    const endpointKeys = normalizeAtIds(endpointAtIds?.length ? endpointAtIds : collectEndpointAtIds(message));
     return message.$content
-        .filter((seg) => !isAtSegmentForBot(seg, botIds))
+        .filter((seg) => !isAtSegmentForEndpoint(seg, endpointKeys))
         .map((seg) => {
         if (seg.type !== 'text' || !seg.data?.text)
             return seg;
-        const stripped = stripTextAtBot(seg.data.text, botIds).trim();
+        const stripped = stripTextAtEndpoint(seg.data.text, endpointKeys).trim();
         if (!stripped)
             return null;
         return { ...seg, data: { ...seg.data, text: stripped } };
     })
         .filter((seg) => seg != null);
 }
-function normalizeBotIdList(input) {
+function normalizeEndpointIdList(input) {
     if (Array.isArray(input))
         return input.map((v) => String(v)).filter(Boolean);
     if (typeof input === 'string') {
@@ -142,15 +152,15 @@ function normalizeBotIdList(input) {
     }
     return [];
 }
-function collectBotTrustedIds(botConfig) {
-    if (!botConfig)
+function collectEndpointTrustedIds(endpointConfig) {
+    if (!endpointConfig)
         return [];
-    return normalizeBotIdList(botConfig.trusted);
+    return normalizeEndpointIdList(endpointConfig.trusted);
 }
 /**
- * 解析发送者角色集合（IM 群角色 + trigger + bots[].$config）
+ * 解析发送者角色集合（IM 群角色 + trigger + endpoints[].$config）
  */
-export function resolveSenderRoles(message, config, botConfig) {
+export function resolveSenderRoles(message, config, endpointConfig) {
     const scope = message.$channel?.type || 'private';
     // process 适配器（stdin/本机 CLI）：操作者即宿主用户，恒为 master
     if (message.$adapter === 'process') {
@@ -160,60 +170,45 @@ export function resolveSenderRoles(message, config, botConfig) {
         };
     }
     const senderId = String(message.$sender.id);
-    const senderPermissions = message.$sender.permissions || [];
     const roles = [];
     const masters = config.masters || [];
     const globalTrusted = config.trusted || [];
-    const cfg = botConfig;
-    const botMaster = cfg?.master != null ? String(cfg.master) : undefined;
-    const botTrustedIds = collectBotTrustedIds(cfg);
-    if (masters.includes(senderId) || (botMaster != null && senderId === botMaster)) {
+    const cfg = endpointConfig;
+    const endpointMaster = cfg?.master != null ? String(cfg.master) : undefined;
+    const endpointTrustedIds = collectEndpointTrustedIds(cfg);
+    if (masters.includes(senderId) || (endpointMaster != null && senderId === endpointMaster)) {
         roles.push('master');
     }
-    else if (globalTrusted.includes(senderId) || botTrustedIds.includes(senderId)) {
+    else if (globalTrusted.includes(senderId) || endpointTrustedIds.includes(senderId)) {
         roles.push('trusted');
     }
-    const isGroupOwner = senderPermissions.includes('owner')
-        || senderPermissions.includes('group_owner')
-        || message.$sender?.role === 'owner';
-    const isGroupAdmin = isGroupOwner
-        || senderPermissions.includes('admin')
-        || senderPermissions.includes('group_admin')
-        || message.$sender?.role === 'admin';
-    if (isGroupOwner)
-        roles.push('group_owner');
-    else if (isGroupAdmin)
-        roles.push('group_admin');
     return {
         scope,
         roles: normalizeSenderRoles(roles),
     };
 }
-/** 从 IM 消息生成 sessionId（platform:botId:type:sceneId） */
-export function resolveIMSessionIdFromMessage(message) {
-    const scope = (message.$channel?.type || 'private');
-    const sceneId = scope === 'private'
-        ? String(message.$sender.id)
-        : String(message.$channel?.id || message.$sender.id);
-    return resolveIMSessionId({
-        platform: message.$adapter,
-        botId: message.$bot,
-        scope,
-        sceneId,
-    });
-}
 /**
  * 检查消息是否应该触发 AI
  */
 export function shouldTriggerAI(message, config, options) {
     const fullConfig = { ...DEFAULT_AI_TRIGGER_CONFIG, ...config };
-    const botAtIds = collectBotAtIds(message, options?.botAtIds);
+    const endpointAtIds = collectEndpointAtIds(message, options?.endpointAtIds);
     if (!fullConfig.enabled) {
         return { triggered: false, content: '' };
     }
     const text = extractTextContent(message);
     const scope = message.$channel?.type || 'private';
     const isSharedSession = scope === 'group' || scope === 'channel';
+    /** 对群/频道触发结果附加发送者前缀（与 DB 历史的 buildSenderPrefix 格式对齐） */
+    const withSenderPrefix = (content) => {
+        if (!isSharedSession)
+            return content;
+        const { roles } = resolveSenderRoles(message, config);
+        const prefix = buildSenderPrefixForMessage(message, roles);
+        if (!prefix)
+            return content;
+        return content ? `${prefix} ${content}` : prefix;
+    };
     // 检查忽略前缀
     for (const prefix of fullConfig.ignorePrefixes) {
         if (text.startsWith(prefix)) {
@@ -229,11 +224,12 @@ export function shouldTriggerAI(message, config, options) {
         }
     }
     // 2. 检查 @ 触发（群/频道主路径；仅 @ 无正文时也触发，由 Agent 处理空输入）
-    if (fullConfig.respondToAt && isAtBot(message, botAtIds)) {
-        const content = removeAtBot(message, botAtIds);
+    if (fullConfig.respondToAt && isAtEndpoint(message, endpointAtIds)) {
+        const content = removeAtEndpoint(message, endpointAtIds);
+        const body = content.length ? segment.toString(content).trim() : '';
         return {
             triggered: true,
-            content: content.length ? segment.toString(content).trim() : '',
+            content: withSenderPrefix(body),
         };
     }
     // 3. 检查私聊触发
@@ -259,4 +255,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

@@ -0,0 +1,10 @@
+/**
+ * 授权重算 — ConfigFeature + Message 为单一真相源（$sender.isMaster/isTrusted 为 enrich 快照）
+ */
+import type { Plugin } from '../plugin.js';
+import type { Message } from '../message.js';
+import { type SenderRolesResult } from './ai-trigger.js';
+/**
+ * 从 ConfigFeature + Message 重算发送者角色（含群角色与 master/trusted）
+ */
+export declare function resolveSubjectRoles(plugin: Plugin, message: Message<any>): SenderRolesResult;

package/lib/built/authorization.js

@@ -0,0 +1,76 @@
+import { mergeAITriggerConfig, resolveSenderRoles, } from './ai-trigger.js';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('Authorization');
+function findEndpointEntryFromConfig(config, adapter, endpointKey) {
+    // 1) top-level endpoints[] (legacy / flat format)
+    const topLevel = config.endpoints;
+    if (Array.isArray(topLevel)) {
+        const found = topLevel.find((b) => b.context === adapter && String(b.id) === endpointKey);
+        if (found)
+            return found;
+    }
+    // 2) plugins.<adapter> — adapter-level master/trusted + nested endpoints[]
+    const adapterConfig = config.plugins?.[adapter];
+    if (!adapterConfig)
+        return undefined;
+    const nested = adapterConfig.endpoints;
+    const entry = Array.isArray(nested)
+        ? nested.find((b) => String(b.id) === endpointKey)
+        : undefined;
+    // Merge adapter-level master/trusted onto the matched endpoint entry
+    // so that resolveSenderRoles sees them in one place
+    const merged = {
+        context: adapter,
+        ...(entry ?? { id: endpointKey }),
+    };
+    if (adapterConfig.master != null && merged.master == null) {
+        merged.master = adapterConfig.master;
+    }
+    if (adapterConfig.trusted != null && merged.trusted == null) {
+        merged.trusted = adapterConfig.trusted;
+    }
+    return merged;
+}
+function readTriggerConfig(plugin) {
+    const root = plugin.root ?? plugin;
+    try {
+        const ai = root.inject('ai');
+        if (ai?.getTriggerConfig)
+            return ai.getTriggerConfig();
+    }
+    catch (e) {
+        logger.debug(formatCompact({ auth: 'trigger_config_fallback', reason: 'ai_not_ready' }));
+    }
+    try {
+        const configSvc = root.inject('config');
+        const primary = configSvc?.getPrimary?.();
+        return primary?.ai?.trigger ?? {};
+    }
+    catch (e) {
+        logger.debug(formatCompact({ auth: 'trigger_config_read_error' }));
+        return {};
+    }
+}
+function readEndpointConfig(plugin, message) {
+    const root = plugin.root ?? plugin;
+    try {
+        const configSvc = root.inject('config');
+        const primary = configSvc?.getPrimary?.();
+        if (!primary)
+            return undefined;
+        const entry = findEndpointEntryFromConfig(primary, String(message.$adapter), String(message.$endpoint));
+        return entry;
+    }
+    catch (e) {
+        logger.debug(formatCompact({ auth: 'endpoint_config_read_error' }));
+        return undefined;
+    }
+}
+/**
+ * 从 ConfigFeature + Message 重算发送者角色（含群角色与 master/trusted）
+ */
+export function resolveSubjectRoles(plugin, message) {
+    const triggerConfig = mergeAITriggerConfig(readTriggerConfig(plugin));
+    const endpointConfig = readEndpointConfig(plugin, message);
+    return resolveSenderRoles(message, triggerConfig, endpointConfig);
+}

package/lib/built/command.d.ts

@@ -5,15 +5,17 @@
 import { Feature, FeatureJSON } from "@zhin.js/kernel";
 /** 命令 pattern 的首个词（用于前缀排序） */
 export declare function commandLeadingToken(pattern: string): string;
+/** 命令匹配优先级：首词越长越优先；同首词则完整 pattern 越长越优先 */
+export declare function compareCommandPatterns(a: string, b: string): number;
 import { MessageCommand } from "../command.js";
 import { Message } from "../message.js";
-import { Plugin } from "../plugin.js";
 import type { RegisteredAdapter, AdapterMessage } from "../types.js";
+import type { PermissionHost } from '@zhin.js/permission';
 /**
  * CommandContext 扩展方法类型
  */
 export interface CommandContextExtensions {
-    /** 添加命令 */
+    /** @deprecated 使用 `defineCommand` + `commands/`；勿在新代码调用。 */
     addCommand<T extends RegisteredAdapter>(command: MessageCommand<T>): () => void;
 }
 declare module "../plugin.js" {
@@ -26,7 +28,10 @@ declare module "../plugin.js" {
     }
 }
 /**
- * 命令服务 Feature
+ * 命令服务 Feature（经典 MessageCommand 注册表）。
+ *
+ * @deprecated 新命令走 `@zhin.js/command` 的 `defineCommand` + 约定目录发现。
+ * 本 Feature 仍服务 Agent / game-kit / legacy Plugin.addCommand。
  */
 export declare class CommandFeature extends Feature<MessageCommand<RegisteredAdapter>> {
     readonly name: "command";
@@ -49,7 +54,7 @@ export declare class CommandFeature extends Feature<MessageCommand<RegisteredAda
     /**
      * 处理消息，依次尝试匹配命令（较长前缀优先，避免 `teach` 抢 `teach-list`）
      */
-    handle(message: Message<AdapterMessage<RegisteredAdapter>>, plugin: Plugin): Promise<any>;
+    handle(message: Message<AdapterMessage<RegisteredAdapter>>, host: PermissionHost | null): Promise<any>;
     /**
      * 生命周期: 销毁时清理所有命令
      */
@@ -65,4 +70,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

@@ -7,9 +7,23 @@ import { Feature } from "@zhin.js/kernel";
 export function commandLeadingToken(pattern) {
     return pattern.split(/\s/)[0] ?? "";
 }
-import { getPlugin } from "../plugin.js";
+/** 命令匹配优先级：首词越长越优先；同首词则完整 pattern 越长越优先 */
+export function compareCommandPatterns(a, b) {
+    const leadDiff = commandLeadingToken(b).length - commandLeadingToken(a).length;
+    if (leadDiff !== 0)
+        return leadDiff;
+    const lenDiff = b.length - a.length;
+    if (lenDiff !== 0)
+        return lenDiff;
+    const tokA = a.trim().split(/\s+/).length;
+    const tokB = b.trim().split(/\s+/).length;
+    return tokB - tokA;
+}
 /**
- * 命令服务 Feature
+ * 命令服务 Feature（经典 MessageCommand 注册表）。
+ *
+ * @deprecated 新命令走 `@zhin.js/command` 的 `defineCommand` + 约定目录发现。
+ * 本 Feature 仍服务 Agent / game-kit / legacy Plugin.addCommand。
  */
 export class CommandFeature extends Feature {
     name = 'command';
@@ -40,10 +54,10 @@ export class CommandFeature extends Feature {
     /**
      * 处理消息，依次尝试匹配命令（较长前缀优先，避免 `teach` 抢 `teach-list`）
      */
-    async handle(message, plugin) {
-        const commands = [...this.items].sort((a, b) => commandLeadingToken(b.pattern).length - commandLeadingToken(a.pattern).length);
+    async handle(message, host) {
+        const commands = [...this.items].sort((a, b) => compareCommandPatterns(a.pattern, b.pattern));
         for (const command of commands) {
-            const result = await command.handle(message, plugin);
+            const result = await command.handle(message, host);
             if (result)
                 return result;
         }
@@ -80,7 +94,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);
@@ -89,4 +103,3 @@ export class CommandFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=command.js.map

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

@@ -1,40 +1,40 @@
 /**
- * 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, SenderRole } from '../types.js';
+import type { Tool } from '../types.js';
 /**
- * 群管理能力接口。
+ * 场景治理能力接口。
  * Adapter 基类通过此接口声明方法签名，子类选择性覆写。
  */
-export interface IGroupManagement {
-    kickMember?(botId: string, sceneId: string, userId: string): Promise<any>;
-    muteMember?(botId: string, sceneId: string, userId: string, duration?: number): Promise<any>;
-    setMemberNickname?(botId: string, sceneId: string, userId: string, nickname: string): Promise<any>;
-    setAdmin?(botId: string, sceneId: string, userId: string, enable?: boolean): Promise<any>;
-    listMembers?(botId: string, sceneId: string): Promise<any>;
-    banMember?(botId: string, sceneId: string, userId: string, reason?: string): Promise<any>;
-    unbanMember?(botId: string, sceneId: string, userId: string): Promise<any>;
-    setGroupName?(botId: string, sceneId: string, name: string): Promise<any>;
-    muteAll?(botId: string, sceneId: string, enable?: boolean): Promise<any>;
-    getGroupInfo?(botId: string, sceneId: string): Promise<any>;
+export interface ISceneManagement {
+    removeMember?(endpointKey: string, sceneId: string, userId: string): Promise<any>;
+    muteMember?(endpointKey: string, sceneId: string, userId: string, duration?: number): Promise<any>;
+    setMemberNickname?(endpointKey: string, sceneId: string, userId: string, nickname: string): Promise<any>;
+    setModerator?(endpointKey: string, sceneId: string, userId: string, enable?: boolean): Promise<any>;
+    listMembers?(endpointKey: string, sceneId: string): Promise<any>;
+    banMember?(endpointKey: string, sceneId: string, userId: string, reason?: string): Promise<any>;
+    unbanMember?(endpointKey: string, sceneId: string, userId: string): Promise<any>;
+    renameScene?(endpointKey: string, sceneId: string, name: string): Promise<any>;
+    setSceneMuted?(endpointKey: string, sceneId: string, enable?: boolean): Promise<any>;
+    getSceneInfo?(endpointKey: string, sceneId: string): Promise<any>;
 }
-export interface GroupMethodSpec {
-    method: keyof IGroupManagement;
+export interface SceneManagementMethodSpec {
+    method: keyof ISceneManagement;
     toolSuffix: string;
     description: string;
     keywords: string[];
-    requiredAnyRole?: SenderRole[];
+    permit?: string;
     extraParams: Record<string, {
         type: string;
         description: string;
@@ -43,13 +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 createGroupManagementTools(adapter: IGroupManagement, prefix: string): Tool[];
-export declare function createGroupManagementToolsRaw<T>(adapter: IGroupManagement, prefix: string, factory: GroupManagementToolFactory<T>): T[];
-export declare function buildMethodArgs(method: keyof IGroupManagement, botId: string, sceneId: string, rest: Record<string, any>): any[];
-//# sourceMappingURL=common-adapter-tools.d.ts.map
+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 系 scene checker（默认 true） */
+    registerChecker?: boolean;
+}
+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, endpointKey: string, sceneId: string, rest: Record<string, any>): any[];