@zhin.js/core 1.5.1 → 1.5.4

package/README.md

@@ -36,18 +36,21 @@ export default definePlugin({
 ```
 
 ```typescript
-// commands/hello/[name:string].ts
+// commands/hello/[name].ts
 import { defineCommand } from '@zhin.js/command'
 
 export default defineCommand({
   description: '打招呼',
+  params: {
+    name: { type: 'string' },
+  },
   execute({ params }) {
     return `Hello, ${params.name}!`
   },
 })
 ```
 
-> **已弃用**：`usePlugin()` / `MessageCommand` / `Plugin.addCommand` 仅经典路径（`zhin.js/node`）残留，新代码勿用。见 [public-api-surface](../../docs/contributing/public-api-surface.md)。
+> **已移除**：`usePlugin()` / `getPlugin()` / `bootstrapNode`（`zhin.js/node`）调用即 throw；唯一入口为 `definePlugin` + `zhin runtime start`。`MessageCommand` / `Plugin.addCommand` 仍 deprecated。见 [public-api-surface](../../docs/contributing/public-api-surface.md)。
 
 本包仍提供 IM 运行时契约（Message / Adapter / Endpoint）；创作面在 Feature 包与 `@zhin.js/plugin-runtime`。
 
@@ -206,7 +209,7 @@ Core **不包含** ZhinAgent 实现。IM 侧的 AI 对话、工具收集、执
 
 ```typescript
 // 插件系统
-export { Plugin, usePlugin, getPlugin, definePlugin } from './plugin.js'
+export { Plugin, usePlugin, getPlugin, definePlugin } from './plugin.js'  // usePlugin/getPlugin 为 throwing stub
 
 // Feature 体系（Cron / Scheduler 来自 @zhin.js/kernel）
 export { Feature, Cron, Scheduler } from '@zhin.js/kernel'

package/lib/adapter.d.ts

@@ -86,9 +86,15 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
      */
     protected renderSendMessage(options: SendOptions): Promise<SendOptions>;
     sendMessage(options: SendOptions): Promise<string>;
+    /**
+     * `call.recallMessage` 事件链（prompt.ts 超时撤回等）的统一出口：
+     * 经 canonical `EndpointControl` 端口撤回，classic 端点的 `$` 方法由
+     * `resolveEndpointControl` 迁移桥适配。
+     */
+    private recallEndpointMessage;
     /**
      * 编辑已发送的消息。
-     * - 如果 Endpoint 实现了 $editMessage，调用平台编辑 API
+     * - 如果 Endpoint 的 control 端口实现了 edit，调用平台编辑 API
      * - 否则 fallback 到发送新消息
      * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
      */

package/lib/adapter.js

@@ -1,9 +1,10 @@
 import { assertOutbound, DEFAULT_ENDPOINT_CAPABILITIES, hasInbound, } from "./endpoint-capabilities.js";
+import { resolveEndpointControl } from "@zhin.js/adapter";
 import { connectEndpointInstance, disconnectEndpointInstance } from "./built/connect-endpoint-instance.js";
 import { EventEmitter } from "node:events";
 import { getOutboundReplyStore } from "./built/dispatcher.js";
 import { DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY, resolveRichSegments, } from "./built/rich-segments/index.js";
-import { DEFAULT_INTERACTIVE_POLICY, collectKeyboardFallbackMaps, keyboardFallbackStore, resolveInteractiveSegments, } from "./built/interactive-segments/index.js";
+import { DEFAULT_INTERACTIVE_POLICY, collectKeyboardFallbackMaps, keyboardFallbackStore, resolveKeyboardSegments, } from "./built/interactive-segments/index.js";
 import { DEFAULT_AI_OUTBOUND_CAPABILITIES, } from "./built/ai-outbound/index.js";
 import { createRichSegmentRenderContext } from "./built/rich-segments/capabilities.js";
 import { collectOutboundMediaKinds } from "./built/outbound-media-utils.js";
@@ -63,14 +64,7 @@ export class Adapter extends EventEmitter {
         this.plugin = plugin;
         this.name = name;
         this.config = config;
-        this.recallMessageHandler = async (endpoint_id, id) => {
-            const endpoint = this.endpoints.get(endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${endpoint_id} not found`);
-            assertOutbound(endpoint);
-            this.logger.debug(formatCompact({ recall: id, endpoint: endpoint_id }));
-            await endpoint.$recallMessage(id);
-        };
+        this.recallMessageHandler = (endpoint_id, id) => this.recallEndpointMessage(endpoint_id, id);
         this.on('call.recallMessage', this.recallMessageHandler);
         this.inboundPipeline = new InboundMessagePipeline({
             getPlugin: () => this.plugin,
@@ -100,7 +94,7 @@ export class Adapter extends EventEmitter {
         const message = args[0];
         // 背压控制：同步返回 false 表示丢弃
         if (this.inboundPipeline.shouldDropDueToBackpressure()) {
-            this.logger.warn(formatCompact({ drop: 'concurrency', limit: this.maxConcurrentMessages }));
+            this.logger.warn(formatCompact({ op: 'backpressure_drop', limit: this.maxConcurrentMessages }));
             return false;
         }
         // 同步计数，保证背压判断的准确性
@@ -180,7 +174,7 @@ export class Adapter extends EventEmitter {
             }
             options = {
                 ...options,
-                content: resolveInteractiveSegments(options.content, this.getInteractivePolicy()),
+                content: resolveKeyboardSegments(options.content, this.getInteractivePolicy()),
             };
             const mediaKinds = collectOutboundMediaKinds(options.content);
             if (mediaKinds.length > 0) {
@@ -222,9 +216,26 @@ export class Adapter extends EventEmitter {
         });
         return messageId;
     }
+    /**
+     * `call.recallMessage` 事件链（prompt.ts 超时撤回等）的统一出口：
+     * 经 canonical `EndpointControl` 端口撤回，classic 端点的 `$` 方法由
+     * `resolveEndpointControl` 迁移桥适配。
+     */
+    async recallEndpointMessage(endpointKey, messageId) {
+        const endpoint = this.endpoints.get(endpointKey);
+        if (!endpoint)
+            throw new Error(`Endpoint ${endpointKey} not found`);
+        assertOutbound(endpoint);
+        const control = resolveEndpointControl(endpoint);
+        if (!control?.recall) {
+            throw new Error(`Endpoint ${endpointKey} does not support recall`);
+        }
+        this.logger.debug(formatCompact({ op: 'recall_message', msgId: messageId, endpoint: endpointKey }));
+        await control.recall(messageId);
+    }
     /**
      * 编辑已发送的消息。
-     * - 如果 Endpoint 实现了 $editMessage，调用平台编辑 API
+     * - 如果 Endpoint 的 control 端口实现了 edit，调用平台编辑 API
      * - 否则 fallback 到发送新消息
      * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
      */
@@ -233,8 +244,8 @@ export class Adapter extends EventEmitter {
         if (!endpoint)
             throw new Error(`Endpoint ${options.endpoint} not found`);
         assertOutbound(endpoint);
-        const editable = endpoint;
-        if (editable.$editMessage) {
+        const control = resolveEndpointControl(endpoint);
+        if (control?.edit) {
             const rendered = await this.renderSendMessage({
                 context: options.context,
                 endpoint: options.endpoint,
@@ -242,7 +253,7 @@ export class Adapter extends EventEmitter {
                 type: options.type,
                 content: options.content,
             });
-            await editable.$editMessage({ ...options, content: rendered.content });
+            await control.edit(options.messageId, rendered.content);
             this.logger.debug(formatCompact({
                 edit: `${options.type}(${options.id})`,
                 endpoint: options.endpoint,
@@ -253,7 +264,7 @@ export class Adapter extends EventEmitter {
         this.logger.debug(formatCompact({
             editFallback: 'sendMessage',
             endpoint: options.endpoint,
-            reason: '$editMessage not implemented',
+            reason: 'control.edit not implemented',
         }));
         return this.sendMessage({
             context: options.context,
@@ -314,14 +325,7 @@ export class Adapter extends EventEmitter {
         }
         // 移除所有事件监听器
         this.removeAllListeners();
-        this.recallMessageHandler = async (endpoint_id, id) => {
-            const endpoint = this.endpoints.get(endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${endpoint_id} not found`);
-            assertOutbound(endpoint);
-            this.logger.debug(formatCompact({ recall: id, endpoint: endpoint_id }));
-            await endpoint.$recallMessage(id);
-        };
+        this.recallMessageHandler = (endpoint_id, id) => this.recallEndpointMessage(endpoint_id, id);
         this.on('call.recallMessage', this.recallMessageHandler);
         this.logger.debug(formatCompact({ stop: this.name }));
         if (errors.length) {

package/lib/agent-prompt.d.ts

@@ -3,7 +3,6 @@
  *
  * Implementations live in adapter plugins; resolution runs in @zhin.js/agent.
  */
-import type { Message } from './message.js';
 export type AgentPromptSlot = 'orchestrator' | 'deferred_worker';
 /** Minimal tool shape for deferred catalog selection (no @zhin.js/ai import). */
 export interface DeferredToolCatalogItem {
@@ -12,8 +11,8 @@ export interface DeferredToolCatalogItem {
 }
 export interface AgentPromptBuildContext {
     slot: AgentPromptSlot;
-    /** 当前 turn 的 Message 通讯上下文 */
-    commMessage: Message<any>;
+    /** Authenticated IM platform projected by the ingress adapter. */
+    platform: string;
     /** Truncated user message for intent hints (~500 chars). */
     userMessagePreview?: string;
     deferred?: {

package/lib/agent-prompt.js

@@ -1 +1,6 @@
+/**
+ * Agent system-prompt extension contract (per IM platform / adapter).
+ *
+ * Implementations live in adapter plugins; resolution runs in @zhin.js/agent.
+ */
 export {};

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

@@ -1,6 +1,6 @@
 import type { Segment } from '../segment-contract/types.js';
 import type { ZhinAiOutboundPayload } from './types.js';
-/** 解析单条 outbound segment（canonical 或 legacy kind/mode）。 */
+/** 解析单条 outbound segment（canonical type/data 形态）。 */
 export declare function parseOutboundSegment(raw: unknown): Segment | null;
 /** 去掉嵌入 JSON 候选末尾的 markdown 围栏（模型常见 ```json … ``` 误输出）。 */
 export declare function trimTrailingMarkdownFence(raw: string): string;

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

@@ -2,15 +2,11 @@ import { isCanonicalSegment } from '../segment-contract/assert.js';
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** 解析单条 outbound segment（canonical 或 legacy kind/mode）。 */
+/** 解析单条 outbound segment（canonical type/data 形态）。 */
 export function parseOutboundSegment(raw) {
     if (!isPlainObject(raw))
         return null;
-    const type = typeof raw.type === 'string' && raw.type.trim()
-        ? raw.type.trim()
-        : typeof raw.kind === 'string' && raw.kind.trim()
-            ? raw.kind.trim()
-            : undefined;
+    const type = typeof raw.type === 'string' && raw.type.trim() ? raw.type.trim() : undefined;
     if (!type)
         return null;
     const data = isPlainObject(raw.data) ? raw.data : {};

package/lib/built/ai-outbound/plain-mention-rewrite.js

@@ -13,8 +13,8 @@ export function rewritePlainTextMentions(plainText, mentionResolver) {
         const token = match[1];
         if (!token)
             continue;
-        const endpointId = mentionResolver(token);
-        if (!endpointId)
+        const endpointKey = mentionResolver(token);
+        if (!endpointKey)
             continue;
         const ref = token;
         if (!mentions.includes(ref))
@@ -23,8 +23,8 @@ export function rewritePlainTextMentions(plainText, mentionResolver) {
     if (mentions.length === 0)
         return null;
     rewritten = trimmed.replace(PLAIN_MENTION_PATTERN, (full, token) => {
-        const endpointId = mentionResolver(token);
-        return endpointId ? '' : full;
+        const endpointKey = mentionResolver(token);
+        return endpointKey ? '' : full;
     });
     rewritten = rewritten
         .replace(/[ \t]+\n/g, '\n')

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

@@ -1,8 +1,8 @@
 import { segmentsForImDelivery } from '../segment-contract/delivery.js';
-function buildMentionSegments(endpointIds, text, ctx) {
+function buildMentionSegments(endpointKeys, text, ctx) {
     const segments = [];
-    for (const endpointId of endpointIds) {
-        const target = ctx.atIdResolver?.(endpointId) ?? endpointId;
+    for (const endpointKey of endpointKeys) {
+        const target = ctx.atIdResolver?.(endpointKey) ?? endpointKey;
         segments.push({ type: 'mention', data: { target } });
     }
     const body = text.trim();
@@ -19,16 +19,16 @@ function resolveMentionEndpointIds(mentions, ctx) {
     if (!ctx.mentionResolver) {
         return { ok: false, error: 'mentionResolver 未配置' };
     }
-    const endpointIds = [];
+    const endpointKeys = [];
     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);
+        if (!endpointKeys.includes(resolved))
+            endpointKeys.push(resolved);
     }
-    return { ok: true, endpointIds };
+    return { ok: true, endpointKeys };
 }
 /** 将 ZhinAiOutboundPayload 转为 MessageElement[]（canonical segments + extensions）。 */
 export async function resolveAiOutboundToMessageElements(payload, ctx) {
@@ -40,7 +40,7 @@ export async function resolveAiOutboundToMessageElements(payload, ctx) {
         const text = payload.text?.trim() ?? '';
         if (!text)
             return null;
-        segments.push(...buildMentionSegments(resolved.endpointIds, text, ctx));
+        segments.push(...buildMentionSegments(resolved.endpointKeys, text, ctx));
     }
     else if (payload.text?.trim()) {
         segments.push({ type: 'text', data: { text: payload.text.trim() } });

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

@@ -35,14 +35,14 @@ export interface AiOutboundMentionResolver {
     (ref: string): string | undefined;
 }
 export interface AiOutboundAtIdResolver {
-    (endpointId: string): string;
+    (endpointKey: string): string;
 }
 /** 解析 AI 出站 JSON 时的上下文。 */
 export interface AiOutboundParseContext {
     message: Message;
-    /** 将 peer ref（role/endpoint/primary）解析为 endpointId */
+    /** 将 peer ref（role/endpoint/primary）解析为 endpointKey */
     mentionResolver?: AiOutboundMentionResolver;
-    /** 将 endpointId 解析为 platform @ id */
+    /** 将 endpointKey 解析为 platform @ id */
     atIdResolver?: AiOutboundAtIdResolver;
     /** Adapter 声明的 extensions（运行时从 Adapter 静态属性注入） */
     extensions?: readonly AiOutboundExtensionDefinition[];

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

@@ -76,6 +76,11 @@ export declare function isAtEndpoint<T extends object>(message: Message<T>, endp
  * 使用 segment.toString 将 MessageElement 转为 XML 格式
  */
 export declare function extractTextContent<T extends object>(message: Message<T>): string;
+/**
+ * 为群/频道消息构建发送者前缀（与 sender-extra.ts buildSenderPrefix 格式对齐）
+ * 私聊消息返回 null
+ */
+export declare function buildSenderPrefixForMessage<T extends object>(message: Message<T>, roles: SenderRole[]): string | null;
 /**
  * 解析 AI 回复中的富媒体内容
  * 将字符串中的 XML-like 标签解析为 MessageElement

package/lib/built/ai-trigger.js

@@ -39,23 +39,23 @@ function normalizeAtIds(endpointAtIds) {
 function segmentAtUserId(seg) {
     return readMentionSegmentTarget(seg);
 }
-function isAtSegmentForEndpoint(seg, endpointIds) {
+function isAtSegmentForEndpoint(seg, endpointKeys) {
     if (seg.type !== 'at' && seg.type !== 'mention')
         return false;
     const uid = segmentAtUserId(seg);
-    return uid !== '' && endpointIds.includes(uid);
+    return uid !== '' && endpointKeys.includes(uid);
 }
-function textMentionsEndpoint(text, endpointIds) {
-    for (const id of endpointIds) {
+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 stripTextAtEndpoint(text, endpointIds) {
+function stripTextAtEndpoint(text, endpointKeys) {
     let result = text;
-    for (const id of endpointIds) {
+    for (const id of endpointKeys) {
         const re = new RegExp(`@${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|[\\u200b\\uFEFF])?`, 'g');
         result = result.replace(re, '');
     }
@@ -76,12 +76,12 @@ export function collectEndpointAtIds(message, extraIds) {
  * 检查消息是否 @ 了 Endpoint
  */
 export function isAtEndpoint(message, endpointAtIds) {
-    const endpointIds = normalizeAtIds(endpointAtIds?.length ? endpointAtIds : collectEndpointAtIds(message));
-    if (message.$content.some((seg) => isAtSegmentForEndpoint(seg, endpointIds))) {
+    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 && textMentionsEndpoint(seg.data.text, endpointIds)) {
+        if (seg.type === 'text' && seg.data?.text && textMentionsEndpoint(seg.data.text, endpointKeys)) {
             return true;
         }
     }
@@ -94,6 +94,22 @@ export function isAtEndpoint(message, endpointAtIds) {
 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
@@ -117,13 +133,13 @@ export function parseRichMediaContent(content) {
  * 移除 @ Endpoint 的部分
  */
 export function removeAtEndpoint(message, endpointAtIds) {
-    const endpointIds = normalizeAtIds(endpointAtIds?.length ? endpointAtIds : collectEndpointAtIds(message));
+    const endpointKeys = normalizeAtIds(endpointAtIds?.length ? endpointAtIds : collectEndpointAtIds(message));
     return message.$content
-        .filter((seg) => !isAtSegmentForEndpoint(seg, endpointIds))
+        .filter((seg) => !isAtSegmentForEndpoint(seg, endpointKeys))
         .map((seg) => {
         if (seg.type !== 'text' || !seg.data?.text)
             return seg;
-        const stripped = stripTextAtEndpoint(seg.data.text, endpointIds).trim();
+        const stripped = stripTextAtEndpoint(seg.data.text, endpointKeys).trim();
         if (!stripped)
             return null;
         return { ...seg, data: { ...seg.data, text: stripped } };
@@ -185,6 +201,16 @@ export function shouldTriggerAI(message, config, options) {
     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)) {
@@ -202,9 +228,10 @@ export function shouldTriggerAI(message, config, options) {
     // 2. 检查 @ 触发（群/频道主路径；仅 @ 无正文时也触发，由 Agent 处理空输入）
     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. 检查私聊触发

package/lib/built/authorization.js

@@ -1,11 +1,11 @@
 import { mergeAITriggerConfig, resolveSenderRoles, } from './ai-trigger.js';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('Authorization');
-function findEndpointEntryFromConfig(config, adapter, endpointId) {
+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.name) === endpointId);
+        const found = topLevel.find((b) => b.context === adapter && String(b.id) === endpointKey);
         if (found)
             return found;
     }
@@ -15,13 +15,13 @@ function findEndpointEntryFromConfig(config, adapter, endpointId) {
         return undefined;
     const nested = adapterConfig.endpoints;
     const entry = Array.isArray(nested)
-        ? nested.find((b) => String(b.name) === endpointId)
+        ? 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 ?? { name: endpointId }),
+        ...(entry ?? { id: endpointKey }),
     };
     if (adapterConfig.master != null && merged.master == null) {
         merged.master = adapterConfig.master;

package/lib/built/command.d.ts

@@ -9,8 +9,8 @@ export declare function commandLeadingToken(pattern: string): string;
 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 扩展方法类型
  */
@@ -54,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>;
     /**
      * 生命周期: 销毁时清理所有命令
      */

package/lib/built/command.js

@@ -54,10 +54,10 @@ export class CommandFeature extends Feature {
     /**
      * 处理消息，依次尝试匹配命令（较长前缀优先，避免 `teach` 抢 `teach-list`）
      */
-    async handle(message, plugin) {
+    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;
         }

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

@@ -18,16 +18,16 @@ import type { Tool } from '../types.js';
  * Adapter 基类通过此接口声明方法签名，子类选择性覆写。
  */
 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>;
-    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>;
-    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>;
+    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 SceneManagementMethodSpec {
     method: keyof ISceneManagement;
@@ -58,4 +58,4 @@ export interface CreateSceneManagementToolsOptions {
 }
 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[];
+export declare function buildSceneMethodArgs(method: keyof ISceneManagement, endpointKey: string, sceneId: string, rest: Record<string, any>): any[];

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

@@ -152,7 +152,7 @@ export function createSceneManagementTools(adapter, prefix, options = {}) {
             parameters: {
                 type: 'object',
                 properties: {
-                    endpoint_id: { type: 'string', description: 'Endpoint ID', contextKey: 'endpointId' },
+                    endpoint_id: { type: 'string', description: 'Endpoint ID', contextKey: 'endpointKey' },
                     scene_id: { type: 'string', description: 'IM 场景 ID', contextKey: 'sceneId' },
                     ...Object.fromEntries(Object.entries(spec.extraParams)),
                 },
@@ -186,18 +186,18 @@ export function createSceneManagementToolsRaw(adapter, prefix, factory) {
 // ============================================================================
 // 参数映射（method → 有序参数列表）
 // ============================================================================
-export function buildSceneMethodArgs(method, endpointId, sceneId, rest) {
+export function buildSceneMethodArgs(method, endpointKey, sceneId, rest) {
     switch (method) {
-        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 '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 '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)];
+        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)];
     }
 }

package/lib/built/config.d.ts

@@ -96,7 +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;

package/lib/built/config.js

@@ -370,7 +370,3 @@ export class ConfigFeature extends Feature {
         };
     }
 }
-/**
- * @deprecated Use ConfigFeature instead
- */
-export const ConfigService = ConfigFeature;

package/lib/built/dispatcher.d.ts

@@ -28,6 +28,7 @@
  */
 import { Message } from '../message.js';
 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;
 /**
@@ -88,6 +89,7 @@ export interface ReplyWithPolishOptions {
 }
 export interface CreateMessageDispatcherOptions {
     dualRoute?: Partial<DualRouteConfig>;
+    permissionHost?: PermissionHost | null;
 }
 export interface MessageDispatcherService {
     dispatch(message: Message<any>): Promise<void>;

package/lib/built/dispatcher.js

@@ -239,7 +239,7 @@ export function createMessageDispatcher(options) {
         const commandService = rootPlugin.inject('command');
         if (!commandService)
             return;
-        const response = await commandService.handle(message, rootPlugin);
+        const response = await commandService.handle(message, options?.permissionHost ?? null);
         if (response !== undefined && response !== null) {
             await replyWithPolishInternal(message, 'command', response);
         }

package/lib/built/endpoint-commands.js

@@ -12,10 +12,10 @@ function collectRuntimeEndpoints(root) {
         const adapter = root.inject(adapterName);
         if (!(adapter instanceof Adapter))
             continue;
-        for (const [endpointId, endpoint] of adapter.endpoints.entries()) {
+        for (const [endpointKey, endpoint] of adapter.endpoints.entries()) {
             rows.push({
                 adapter: String(adapterName),
-                name: endpointId,
+                name: endpointKey,
                 online: !!endpoint.$connected,
             });
         }