@zhin.js/core 1.1.34 → 1.1.35

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

@@ -1,24 +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 发现
  */
-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', '移除', '踢出'],
-        requiredAnyRole: ['group_admin'],
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
         },
@@ -29,7 +30,7 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'mute_member',
         description: '禁言或解除禁言群成员。适用于违规发言、刷屏、骚扰他人等需要临时限制发言的场景。duration 单位为秒，传 0 表示解除禁言。默认禁言 10 分钟(600秒)。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['禁言', 'mute', '静音', '解除禁言', '解禁', '闭嘴'],
-        requiredAnyRole: ['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 },
@@ -41,7 +42,7 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'set_nickname',
         description: '设置群成员的群昵称/名片。仅修改群内显示名称，不影响用户的全局昵称。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['昵称', '名片', 'nickname', 'card', '改名片'],
-        requiredAnyRole: ['group_admin'],
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             nickname: { type: 'string', description: '新的群昵称/名片' },
@@ -49,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', '设置管理', '取消管理', '提升管理', '撤销管理'],
-        requiredAnyRole: ['group_owner'],
+        permit: 'scene_owner',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             enable: { type: 'boolean', description: 'true=设置为管理员，false=取消管理员身份', default: true },
@@ -73,7 +74,7 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'ban_member',
         description: '永久封禁成员（拉入黑名单）。与踢人(kick)不同，封禁后该成员无法再加入群聊。适用于恶意用户、严重违规等需要永久禁止的场景。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['封禁', 'ban', '拉黑', '黑名单'],
-        requiredAnyRole: ['group_admin'],
+        permit: 'scene_admin',
         extraParams: {
             user_id: { type: 'string', description: '目标用户 ID（如果只有昵称，先用 list_members 查询获取）' },
             reason: { type: 'string', description: '封禁原因（将记录在封禁日志中）' },
@@ -85,37 +86,37 @@ export const GROUP_METHOD_SPECS = [
         toolSuffix: 'unban_member',
         description: '解除封禁，将成员从黑名单中移除。解除后该成员可以重新加入群聊。如果只有昵称而没有 user_id，请先调用 list_members 查询',
         keywords: ['解封', 'unban', '解除封禁', '移出黑名单'],
-        requiredAnyRole: ['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', '修改群名'],
-        requiredAnyRole: ['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', '全体禁言', '全体解禁'],
-        requiredAnyRole: ['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,
@@ -124,42 +125,58 @@ 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 createGroupManagementTools(adapter, prefix) {
-    return createGroupManagementToolsRaw(adapter, prefix, (spec, prefix, execute) => ({
-        name: `${prefix}_${spec.toolSuffix}`,
-        description: `${spec.description} (${prefix})`,
-        parameters: {
-            type: 'object',
-            properties: {
-                bot_id: { type: 'string', description: 'Bot ID', contextKey: 'botId' },
-                scene_id: { type: 'string', description: '群/服务器 ID', contextKey: 'sceneId' },
-                ...Object.fromEntries(Object.entries(spec.extraParams)),
+export function defaultScenePermitResolver(adapterPrefix) {
+    return (logicalPerm) => `platform(${adapterPrefix},${logicalPerm})`;
+}
+function resolveSpecPermit(specPerm, prefix, permitResolver) {
+    if (!specPerm)
+        return undefined;
+    const resolved = permitResolver(specPerm);
+    return resolved ? [resolved] : undefined;
+}
+export function createSceneManagementTools(adapter, prefix, options = {}) {
+    const permitResolver = options.permitResolver ?? defaultScenePermitResolver(prefix);
+    if (options.registerChecker !== false) {
+        registerDefaultScenePlatformPermitChecker(prefix);
+    }
+    return createSceneManagementToolsRaw(adapter, prefix, (spec, prefix, execute) => {
+        const specPermissions = resolveSpecPermit(spec.permit, prefix, permitResolver);
+        return {
+            name: `${prefix}_${spec.toolSuffix}`,
+            description: `${spec.description} (${prefix})`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    endpoint_id: { type: 'string', description: 'Endpoint ID', contextKey: 'endpointKey' },
+                    scene_id: { type: 'string', description: 'IM 场景 ID', contextKey: 'sceneId' },
+                    ...Object.fromEntries(Object.entries(spec.extraParams)),
+                },
+                required: ['endpoint_id', 'scene_id', ...(spec.extraRequired ?? [])],
             },
-            required: ['bot_id', 'scene_id', ...(spec.extraRequired ?? [])],
-        },
-        execute,
-        tags: ['group', 'management', prefix],
-        keywords: spec.keywords,
-        ...(spec.requiredAnyRole?.length ? { requiredAnyRole: spec.requiredAnyRole } : {}),
-        scopes: ['group', 'channel'],
-        preExecutable: spec.preExecutable,
-    }));
+            execute,
+            tags: ['scene', 'management', prefix],
+            keywords: spec.keywords,
+            ...(specPermissions ? { permissions: specPermissions } : {}),
+            scopes: ['group', 'channel'],
+            preExecutable: spec.preExecutable,
+        };
+    });
 }
-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 { bot_id, scene_id, ...rest } = args;
-            const methodArgs = buildMethodArgs(spec.method, bot_id, scene_id, rest);
+            const { endpoint_id, scene_id, ...rest } = args;
+            const methodArgs = buildSceneMethodArgs(spec.method, endpoint_id, scene_id, rest);
             return boundFn.apply(adapter, methodArgs);
         };
         tools.push(factory(spec, prefix, execute));
@@ -169,19 +186,18 @@ export function createGroupManagementToolsRaw(adapter, prefix, factory) {
 // ============================================================================
 // 参数映射（method → 有序参数列表）
 // ============================================================================
-export function buildMethodArgs(method, botId, sceneId, rest) {
+export function buildSceneMethodArgs(method, endpointKey, sceneId, rest) {
     switch (method) {
-        case 'kickMember': return [botId, sceneId, rest.user_id];
-        case 'muteMember': return [botId, sceneId, rest.user_id, rest.duration ?? 600];
-        case 'setMemberNickname': return [botId, sceneId, rest.user_id, rest.nickname];
-        case 'setAdmin': return [botId, sceneId, rest.user_id, rest.enable ?? true];
-        case 'listMembers': return [botId, sceneId];
-        case 'banMember': return [botId, sceneId, rest.user_id, rest.reason];
-        case 'unbanMember': return [botId, sceneId, rest.user_id];
-        case 'setGroupName': return [botId, sceneId, rest.name];
-        case 'muteAll': return [botId, sceneId, rest.enable ?? true];
-        case 'getGroupInfo': return [botId, sceneId];
-        default: return [botId, sceneId, ...Object.values(rest)];
+        case 'removeMember': return [endpointKey, sceneId, rest.user_id];
+        case 'muteMember': return [endpointKey, sceneId, rest.user_id, rest.duration ?? 600];
+        case 'setMemberNickname': return [endpointKey, sceneId, rest.user_id, rest.nickname];
+        case 'setModerator': return [endpointKey, sceneId, rest.user_id, rest.enable ?? true];
+        case 'listMembers': return [endpointKey, sceneId];
+        case 'banMember': return [endpointKey, sceneId, rest.user_id, rest.reason];
+        case 'unbanMember': return [endpointKey, sceneId, rest.user_id];
+        case 'renameScene': return [endpointKey, sceneId, rest.name];
+        case 'setSceneMuted': return [endpointKey, sceneId, rest.enable ?? true];
+        case 'getSceneInfo': return [endpointKey, sceneId];
+        default: return [endpointKey, 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

package/lib/built/component.js

@@ -2,9 +2,8 @@
  * ComponentFeature
  * 管理所有插件注册的组件，继承自 Feature 抽象类
  */
-import { Feature } from "@zhin.js/kernel";
+import { Feature } from '@zhin.js/kernel';
 import { renderComponents } from "../component.js";
-import { getPlugin } from "../plugin.js";
 /**
  * 组件服务 Feature
  */
@@ -87,7 +86,7 @@ export class ComponentFeature extends Feature {
         const feature = this;
         return {
             addComponent(component) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const dispose = feature.add(component, plugin.name);
                 plugin.recordFeatureContribution(feature.name, component.name);
                 plugin.onDispose(dispose);
@@ -96,4 +95,3 @@ export class ComponentFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=component.js.map

package/lib/built/config.d.ts

@@ -10,6 +10,8 @@ export declare class ConfigLoader<T extends object> {
     get data(): T;
     get raw(): T;
     get extension(): string;
+    /** `load()` / `patchKey()` 使用的绝对路径 */
+    get resolvedPath(): string;
     constructor(filename: string, initial: T, schema?: Schema<T> | undefined);
     resolvePath(baseDir?: string): string;
     load(baseDir?: string): void;
@@ -20,6 +22,8 @@ export declare class ConfigLoader<T extends object> {
      */
     patchKey(key: string, value: any): void;
 }
+/** 解析 endpoint 配置中的 `${ENV}` 引用（运行时 add 后热连接用） */
+export declare function resolveEndpointConfigEnv(config: Record<string, unknown>): Record<string, unknown>;
 export declare function mergeConfigDefaults<T>(defaults: T, overrides: unknown): T;
 export declare namespace ConfigLoader {
     const supportedExtensions: string[];
@@ -92,8 +96,3 @@ export declare class ConfigFeature extends Feature<ConfigRecord> {
         addConfig(key: string, defaultValue: any): () => void;
     };
 }
-/**
- * @deprecated Use ConfigFeature instead
- */
-export declare const ConfigService: typeof ConfigFeature;
-//# sourceMappingURL=config.d.ts.map

package/lib/built/config.js

@@ -8,7 +8,6 @@ import fs from "node:fs";
 import { stringify as stringifyYaml, parse as parseYaml, parseDocument } from "yaml";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
 /** Deno / Node 统一的工作目录（`Deno.chdir` 后应与 `process.cwd()` 一致） */
 export function runtimeCwd() {
     const g = globalThis;
@@ -37,6 +36,10 @@ export class ConfigLoader {
     get extension() {
         return path.extname(this.filename).toLowerCase();
     }
+    /** `load()` / `patchKey()` 使用的绝对路径 */
+    get resolvedPath() {
+        return this.#resolvedPath || this.resolvePath();
+    }
     constructor(filename, initial, schema) {
         this.filename = filename;
         this.initial = initial;
@@ -96,8 +99,10 @@ export class ConfigLoader {
             ? this.filename
             : path.resolve(baseDir, this.filename);
     }
-    load(baseDir = runtimeCwd()) {
-        const fullPath = this.resolvePath(baseDir);
+    load(baseDir) {
+        const fullPath = baseDir !== undefined
+            ? this.resolvePath(baseDir)
+            : (this.#resolvedPath || this.resolvePath());
         this.#resolvedPath = fullPath;
         if (!fs.existsSync(fullPath)) {
             try {
@@ -197,6 +202,23 @@ function isPlainObject(value) {
         && !Array.isArray(value)
         && Object.getPrototypeOf(value) === Object.prototype;
 }
+/** 解析 endpoint 配置中的 `${ENV}` 引用（运行时 add 后热连接用） */
+export function resolveEndpointConfigEnv(config) {
+    const out = { ...config };
+    for (const [key, value] of Object.entries(out)) {
+        if (typeof value !== 'string')
+            continue;
+        const match = value.match(/^\$\{([^}]+)\}$/);
+        if (!match)
+            continue;
+        const envKey = match[1];
+        const resolved = envLookup(envKey);
+        if (resolved != null && resolved !== '') {
+            out[key] = resolved;
+        }
+    }
+    return out;
+}
 export function mergeConfigDefaults(defaults, overrides) {
     if (Array.isArray(defaults)) {
         return (Array.isArray(overrides) ? overrides : defaults);
@@ -327,7 +349,7 @@ export class ConfigFeature extends Feature {
         const feature = this;
         return {
             addConfig(key, defaultValue) {
-                const plugin = getPlugin();
+                const plugin = this;
                 // 尝试写入主配置文件（如果 key 不存在）
                 if (feature.#primaryConfigFile) {
                     const config = feature.configs.get(feature.#primaryConfigFile);
@@ -348,8 +370,3 @@ export class ConfigFeature extends Feature {
         };
     }
 }
-/**
- * @deprecated Use ConfigFeature instead
- */
-export const ConfigService = ConfigFeature;
-//# sourceMappingURL=config.js.map

package/lib/built/connect-endpoint-instance.d.ts

@@ -0,0 +1,17 @@
+import type { Adapter } from '../adapter.js';
+import type { Endpoint } from '../endpoint.js';
+import type { Plugin } from '../plugin.js';
+import { type EndpointCapabilitiesConfig } from '../endpoint-capabilities.js';
+export interface ConnectEndpointInstanceOptions {
+    plugin: Plugin;
+    adapter: Adapter;
+    config: EndpointCapabilitiesConfig & Record<string, unknown>;
+}
+/**
+ * 按 Endpoint capabilities 连接或注册单个实例（connectEndpoints 与 Adapter.start 共用）。
+ */
+export declare function connectEndpointInstance(options: ConnectEndpointInstanceOptions): Promise<Endpoint>;
+/**
+ * 按 Endpoint capabilities 断开单个实例。
+ */
+export declare function disconnectEndpointInstance(plugin: Plugin, adapter: Adapter, endpoint: Endpoint): Promise<void>;

package/lib/built/connect-endpoint-instance.js

@@ -0,0 +1,42 @@
+import { assertInbound, getAdapterCapabilities, hasInbound, registerEndpointCapabilities, resolveEndpointCapabilities, } from '../endpoint-capabilities.js';
+import { emitEndpointLifecycle } from './endpoint-lifecycle.js';
+import { resolveEndpointConfigEnv } from './config.js';
+/**
+ * 按 Endpoint capabilities 连接或注册单个实例（connectEndpoints 与 Adapter.start 共用）。
+ */
+export async function connectEndpointInstance(options) {
+    const { plugin, adapter, config } = options;
+    const adapterCaps = getAdapterCapabilities(adapter);
+    const caps = resolveEndpointCapabilities(adapterCaps, config.capabilities);
+    const resolvedConfig = resolveEndpointConfigEnv(config);
+    const endpoint = adapter.createEndpoint(resolvedConfig);
+    registerEndpointCapabilities(endpoint, caps);
+    if (caps.includes('inbound')) {
+        assertInbound(endpoint);
+        try {
+            await endpoint.$connect();
+            await emitEndpointLifecycle(plugin, adapter, endpoint, 'connect');
+        }
+        catch (error) {
+            await emitEndpointLifecycle(plugin, adapter, endpoint, 'error', {
+                error: error instanceof Error ? error.message : String(error),
+                phase: 'connect',
+            });
+            throw error;
+        }
+    }
+    else {
+        endpoint.$connected = true;
+    }
+    return endpoint;
+}
+/**
+ * 按 Endpoint capabilities 断开单个实例。
+ */
+export async function disconnectEndpointInstance(plugin, adapter, endpoint) {
+    if (!hasInbound(endpoint))
+        return;
+    assertInbound(endpoint);
+    await endpoint.$disconnect();
+    await emitEndpointLifecycle(plugin, adapter, endpoint, 'disconnect');
+}

package/lib/built/database.d.ts

@@ -4,8 +4,7 @@
  */
 import { Definition, Database } from "@zhin.js/database";
 import { DatabaseConfig, Models } from "../types.js";
-import { Feature, FeatureJSON } from "@zhin.js/kernel";
-import type { PluginLike } from '@zhin.js/kernel';
+import { Feature, FeatureJSON, type PluginLike } from '@zhin.js/kernel';
 /**
  * 模型定义记录
  */
@@ -23,6 +22,9 @@ declare module "../plugin.js" {
         }
     }
 }
+type DatabaseAfterStartHook = (db: Database<any, Models, any>) => void | Promise<void>;
+/** 在 `db.start()` 完成之后、`context.mounted` 发出之前执行（用于 schema 迁移） */
+export declare function onDatabaseAfterStart(hook: DatabaseAfterStartHook): void;
 export declare class DatabaseFeature extends Feature<ModelRecord> {
     readonly name: "database";
     readonly icon = "Database";
@@ -63,4 +65,4 @@ export declare class DatabaseFeature extends Feature<ModelRecord> {
         defineModel<K extends keyof Models>(name: K, definition: Definition<Models[K]>): void;
     };
 }
-//# sourceMappingURL=database.d.ts.map
+export {};

package/lib/built/database.js

@@ -4,10 +4,14 @@
  */
 import { Registry } from "@zhin.js/database";
 import { formatCompact } from '@zhin.js/logger';
-import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
+import { Feature } from '@zhin.js/kernel';
 import { SystemLogDefinition } from "../models/system-log.js";
 import { UserDefinition } from "../models/user.js";
+const databaseAfterStartHooks = [];
+/** 在 `db.start()` 完成之后、`context.mounted` 发出之前执行（用于 schema 迁移） */
+export function onDatabaseAfterStart(hook) {
+    databaseAfterStartHooks.push(hook);
+}
 export class DatabaseFeature extends Feature {
     name = 'database';
     icon = 'Database';
@@ -59,6 +63,9 @@ export class DatabaseFeature extends Feature {
     async mounted(plugin) {
         plugin.logger.debug(formatCompact({ ready: true }));
         await this.db.start();
+        for (const hook of databaseAfterStartHooks) {
+            await hook(this.db);
+        }
     }
     /**
      * 生命周期: 停止数据库
@@ -88,7 +95,7 @@ export class DatabaseFeature extends Feature {
         const feature = this;
         return {
             defineModel(name, definition) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const record = { name: name, definition };
                 const dispose = feature.add(record, plugin.name);
                 plugin.recordFeatureContribution(feature.name, name);
@@ -97,4 +104,3 @@ export class DatabaseFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=database.js.map

package/lib/built/dispatcher.d.ts

@@ -27,12 +27,10 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { Message } from '../message.js';
-import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware } from '../types.js';
-import type { Context } from '../plugin.js';
-export declare function getOutboundReplyStore(): {
-    message: Message<any>;
-    source: OutboundReplySource;
-} | undefined;
+import { type Context } from '../plugin.js';
+import { type PermissionHost } from '@zhin.js/permission';
+import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware, OutboundReplyStore } from '../types.js';
+export declare function getOutboundReplyStore(): OutboundReplyStore | undefined;
 /**
  * 路由判定结果（互斥模式 legacy）
  */
@@ -82,7 +80,7 @@ export type AITriggerMatcher = (message: Message<any>) => {
  */
 export type GroupPassiveContextHandler = (message: Message<any>) => MaybePromise<void>;
 export type GuardrailMiddleware = MessageMiddleware<RegisteredAdapter>;
-/** @alias OutboundReplySource：出站回复来源（指令 / AI） */
+/** Backward-compatible name for the command or AI outbound reply source. */
 export type ReplySource = OutboundReplySource;
 /** replyWithPolish 可选参数 */
 export interface ReplyWithPolishOptions {
@@ -91,6 +89,7 @@ export interface ReplyWithPolishOptions {
 }
 export interface CreateMessageDispatcherOptions {
     dualRoute?: Partial<DualRouteConfig>;
+    permissionHost?: PermissionHost | null;
 }
 export interface MessageDispatcherService {
     dispatch(message: Message<any>): Promise<void>;
@@ -110,6 +109,10 @@ export interface MessageDispatcherService {
      * 在 `before.sendMessage` 管道内调用 `message.$reply`（与 Adapter#sendMessage 同一出站链）
      */
     replyWithPolish(message: Message<any>, source: ReplySource, content: SendContent, options?: ReplyWithPolishOptions): Promise<unknown>;
+    /** Proactive 出站：在 ALS 内执行 send，触发 outbound polish / before.sendMessage */
+    runWithOutboundPolish<T>(store: Pick<OutboundReplyStore, 'message' | 'trigger' | 'proactiveSource'> & {
+        source?: OutboundReplySource;
+    }, fn: () => Promise<T>): Promise<T>;
     /**
      * 是否匹配为指令路径（与 dispatch 内判定一致）
      */
@@ -136,4 +139,3 @@ declare module '../plugin.js' {
     }
 }
 export declare function createMessageDispatcher(options?: CreateMessageDispatcherOptions): Context<'dispatcher', DispatcherContextExtensions>;
-//# sourceMappingURL=dispatcher.d.ts.map