@zhin.js/core 1.3.1 → 1.3.3

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

@@ -66,4 +66,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

@@ -4,7 +4,6 @@
  */
 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[];
@@ -96,4 +100,3 @@ export declare class ConfigFeature extends Feature<ConfigRecord> {
  * @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);
@@ -352,4 +374,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

@@ -15,4 +15,3 @@ export declare function connectEndpointInstance(options: ConnectEndpointInstance
  * 按 Endpoint capabilities 断开单个实例。
  */
 export declare function disconnectEndpointInstance(plugin: Plugin, adapter: Adapter, endpoint: Endpoint): Promise<void>;
-//# sourceMappingURL=connect-endpoint-instance.d.ts.map

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

@@ -1,5 +1,6 @@
 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 共用）。
  */
@@ -7,7 +8,8 @@ export async function connectEndpointInstance(options) {
     const { plugin, adapter, config } = options;
     const adapterCaps = getAdapterCapabilities(adapter);
     const caps = resolveEndpointCapabilities(adapterCaps, config.capabilities);
-    const endpoint = adapter.createEndpoint(config);
+    const resolvedConfig = resolveEndpointConfigEnv(config);
+    const endpoint = adapter.createEndpoint(resolvedConfig);
     registerEndpointCapabilities(endpoint, caps);
     if (caps.includes('inbound')) {
         assertInbound(endpoint);
@@ -38,4 +40,3 @@ export async function disconnectEndpointInstance(plugin, adapter, endpoint) {
     await endpoint.$disconnect();
     await emitEndpointLifecycle(plugin, adapter, endpoint, 'disconnect');
 }
-//# sourceMappingURL=connect-endpoint-instance.js.map

package/lib/built/database.d.ts

@@ -67,4 +67,3 @@ export declare class DatabaseFeature extends Feature<ModelRecord> {
     };
 }
 export {};
-//# sourceMappingURL=database.d.ts.map

package/lib/built/database.js

@@ -5,7 +5,6 @@
 import { Registry } from "@zhin.js/database";
 import { formatCompact } from '@zhin.js/logger';
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
 import { SystemLogDefinition } from "../models/system-log.js";
 import { UserDefinition } from "../models/user.js";
 const databaseAfterStartHooks = [];
@@ -96,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);
@@ -105,4 +104,3 @@ export class DatabaseFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=database.js.map

package/lib/built/dispatcher.d.ts

@@ -27,12 +27,9 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { Message } from '../message.js';
-import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware } from '../types.js';
+import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware, OutboundReplyStore } from '../types.js';
 import type { Context } from '../plugin.js';
-export declare function getOutboundReplyStore(): {
-    message: Message<any>;
-    source: OutboundReplySource;
-} | undefined;
+export declare function getOutboundReplyStore(): OutboundReplyStore | undefined;
 /**
  * 路由判定结果（互斥模式 legacy）
  */
@@ -110,6 +107,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 +137,3 @@ declare module '../plugin.js' {
     }
 }
 export declare function createMessageDispatcher(options?: CreateMessageDispatcherOptions): Context<'dispatcher', DispatcherContextExtensions>;
-//# sourceMappingURL=dispatcher.d.ts.map

package/lib/built/dispatcher.js

@@ -27,7 +27,7 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { getPlugin } from '../plugin.js';
+import { isActionMessage } from './interactive-segments/action.js';
 /** Dispatcher 管理的「会话回复」异步上下文，供 `before.sendMessage` 内读取（与 Adapter.renderSendMessage 同链） */
 const outboundReplyAls = new AsyncLocalStorage();
 export function getOutboundReplyStore() {
@@ -206,10 +206,22 @@ export function createMessageDispatcher(options) {
         if (!rootPlugin) {
             return quote ? message.$reply(content, quote) : message.$reply(content);
         }
-        return outboundReplyAls.run({ message, source }, () => quote ? message.$reply(content, quote) : message.$reply(content));
+        return outboundReplyAls.run({
+            message,
+            source,
+            trigger: 'inbound',
+        }, () => quote ? message.$reply(content, quote) : message.$reply(content));
+    }
+    async function runWithOutboundPolish(store, fn) {
+        return outboundReplyAls.run({
+            message: store.message,
+            source: store.source ?? 'proactive',
+            trigger: store.trigger,
+            proactiveSource: store.proactiveSource,
+        }, fn);
     }
     async function maybeRecordGroupPassiveContext(message) {
-        if (!groupPassiveContextHandler)
+        if (!groupPassiveContextHandler || isActionMessage(message))
             return;
         const scope = message.$channel?.type;
         if (scope !== 'group' && scope !== 'channel')
@@ -336,6 +348,9 @@ export function createMessageDispatcher(options) {
         replyWithPolish(message, source, content, options) {
             return replyWithPolishInternal(message, source, content, options);
         },
+        runWithOutboundPolish(store, fn) {
+            return runWithOutboundPolish(store, fn);
+        },
         matchCommand(message) {
             return matchCommandInternal(message);
         },
@@ -354,18 +369,15 @@ export function createMessageDispatcher(options) {
         },
         extensions: {
             addGuardrail(guardrail) {
-                const plugin = getPlugin();
                 const dispose = service.addGuardrail(guardrail);
-                plugin.onDispose(dispose);
+                rootPlugin?.onDispose(dispose);
                 return dispose;
             },
             addOutboundPolish(handler) {
-                const plugin = getPlugin();
                 const dispose = service.addOutboundPolish(handler);
-                plugin.onDispose(dispose);
+                rootPlugin?.onDispose(dispose);
                 return dispose;
             },
         },
     };
 }
-//# sourceMappingURL=dispatcher.js.map

package/lib/built/endpoint-commands.d.ts

@@ -0,0 +1,3 @@
+import type { CommandFeature } from './command.js';
+import type { Plugin } from '../plugin.js';
+export declare function registerEndpointManagementCommands(plugin: Plugin, commandService: CommandFeature): () => void;

package/lib/built/endpoint-commands.js

@@ -0,0 +1,99 @@
+/**
+ * IM Endpoint 管理与 /endpoints 内省命令（@zhin.js/core）
+ */
+import { Adapter } from '../adapter.js';
+import { MessageCommand } from '../command.js';
+import { MANAGEMENT_OPERATOR_PERMIT } from './management-command-guard.js';
+import { createEndpointLifecycleService } from './endpoint-lifecycle-service.js';
+import { endpointHelpText, formatEndpointsList } from './introspection-format.js';
+function collectRuntimeEndpoints(root) {
+    const rows = [];
+    for (const adapterName of root.adapters) {
+        const adapter = root.inject(adapterName);
+        if (!(adapter instanceof Adapter))
+            continue;
+        for (const [endpointId, endpoint] of adapter.endpoints.entries()) {
+            rows.push({
+                adapter: String(adapterName),
+                name: endpointId,
+                online: !!endpoint.$connected,
+            });
+        }
+    }
+    return rows;
+}
+export function registerEndpointManagementCommands(plugin, commandService) {
+    const root = plugin.root;
+    const disposers = [];
+    const service = () => createEndpointLifecycleService(root);
+    const register = (pattern, desc, handler) => {
+        const cmd = new MessageCommand(pattern)
+            .desc(desc)
+            .permit(MANAGEMENT_OPERATOR_PERMIT)
+            .action(async (message, match) => {
+            try {
+                return await handler(message, match);
+            }
+            catch (err) {
+                return `❌ ${err instanceof Error ? err.message : String(err)}`;
+            }
+        });
+        commandService.add(cmd, plugin.name);
+        disposers.push(() => commandService.remove(cmd));
+    };
+    register('/endpoint help', 'Endpoint 管理帮助', () => endpointHelpText());
+    register('/endpoint add [adapter:word]', '添加 Endpoint', async (message, match) => {
+        const adapterKey = typeof match?.params?.adapter === 'string' ? match.params.adapter.trim() : '';
+        if (!adapterKey) {
+            const list = service().listProvisionableAdapters();
+            if (list.length === 0) {
+                return '当前没有支持运行时添加的适配器（需 EndpointManager 或 endpointConfigSchema）。';
+            }
+            return [
+                '可用适配器：',
+                ...list.map((a) => `  • ${a}  — /endpoint add ${a}`),
+            ].join('\n');
+        }
+        const result = await service().add(adapterKey, message);
+        return result.message;
+    });
+    register('/endpoint remove <adapter:word> <name:word>', '从配置移除 Endpoint', async (_message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().remove(adapterKey, name);
+        return result.message;
+    });
+    register('/endpoint edit <adapter:word> <name:word>', '编辑 Endpoint 配置', async (message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().edit(adapterKey, name, message);
+        return result.message;
+    });
+    register('/endpoint start <adapter:word> <name:word>', '连接 Endpoint', async (message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().start(adapterKey, name, message);
+        return result.message;
+    });
+    register('/endpoint stop <adapter:word> <name:word>', '断开 Endpoint（保留配置）', async (_message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().stop(adapterKey, name);
+        return result.message;
+    });
+    register('/endpoint cancel', '取消进行中的 Endpoint 添加/绑定', () => {
+        if (!service().cancelProvision()) {
+            return '当前没有进行中的 Endpoint 绑定流程。';
+        }
+        return '已取消 Endpoint 绑定流程。';
+    });
+    register('/endpoint sync', '将内存中的 endpoint 配置写回 zhin.config', async () => {
+        const result = await service().syncToDisk();
+        return result.message;
+    });
+    register('/endpoints', '列出各适配器下的 Endpoint 及在线状态', () => formatEndpointsList(collectRuntimeEndpoints(root)));
+    return () => {
+        for (const d of disposers)
+            d();
+    };
+}

package/lib/built/endpoint-lifecycle-service.d.ts

@@ -0,0 +1,28 @@
+import { Adapter } from '../adapter.js';
+import type { Endpoint } from '../endpoint.js';
+import type { Message } from '../message.js';
+import type { Plugin } from '../plugin.js';
+import type { EndpointConfigRecord, EndpointManager } from './endpoint-manager.js';
+export interface EndpointLifecycleResult {
+    message: string;
+    config?: EndpointConfigRecord;
+}
+export declare class EndpointLifecycleService {
+    private readonly root;
+    constructor(root: Plugin);
+    resolveAdapter(adapterKey: string): Adapter;
+    resolveManager(adapterKey: string): EndpointManager;
+    listProvisionableAdapters(): string[];
+    persistEndpoints(endpoints: EndpointConfigRecord[]): Promise<void>;
+    /** 将内存中的 endpoints 写回 zhin.config（修复运行时与磁盘不一致） */
+    syncToDisk(): Promise<EndpointLifecycleResult>;
+    connectConfig(adapter: Adapter, config: EndpointConfigRecord): Promise<Endpoint>;
+    disconnectRuntime(adapter: Adapter, name: string): Promise<boolean>;
+    add(adapterKey: string, message: Message, initialReply?: string): Promise<EndpointLifecycleResult>;
+    edit(adapterKey: string, name: string, message: Message): Promise<EndpointLifecycleResult>;
+    remove(adapterKey: string, name: string): Promise<EndpointLifecycleResult>;
+    start(adapterKey: string, name: string, message: Message): Promise<EndpointLifecycleResult>;
+    stop(adapterKey: string, name: string): Promise<EndpointLifecycleResult>;
+    cancelProvision(): boolean;
+}
+export declare function createEndpointLifecycleService(root: Plugin): EndpointLifecycleService;