@zhin.js/core 1.3.2 → 1.3.3

package/lib/built/html-segment-fallback.d.ts

@@ -7,4 +7,3 @@ import type { SendContent } from '../types.js';
 export declare function coerceHtmlSegmentsToText(content: SendContent): SendContent;
 /** 注册链尾 before.sendMessage：将未转换的 html 段降级为 text */
 export declare function registerHtmlSegmentFallback(plugin: Plugin): () => void;
-//# sourceMappingURL=html-segment-fallback.d.ts.map

package/lib/built/html-segment-fallback.js

@@ -47,4 +47,3 @@ export function registerHtmlSegmentFallback(plugin) {
     plugin.root.on('before.sendMessage', handler);
     return () => plugin.root.off('before.sendMessage', handler);
 }
-//# sourceMappingURL=html-segment-fallback.js.map

package/lib/built/html-to-text.d.ts

@@ -14,4 +14,3 @@ export declare function htmlToPlainTextWithBlockBreaks(html: string, options?: H
  * HTML 卡片出站回退：块级换行 + 语义标题轻量 markdown 前缀。
  */
 export declare function htmlToFallbackText(html: string, options?: HtmlToPlainTextOptions): string;
-//# sourceMappingURL=html-to-text.d.ts.map

package/lib/built/html-to-text.js

@@ -163,4 +163,3 @@ export function htmlToFallbackText(html, options) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
-//# sourceMappingURL=html-to-text.js.map

package/lib/built/inbound-pipeline.d.ts

@@ -35,4 +35,3 @@ export declare class InboundMessagePipeline {
     bridgeNoticeOrRequest(event: string, args: unknown[], directEmit: () => boolean): boolean;
     private logIncoming;
 }
-//# sourceMappingURL=inbound-pipeline.d.ts.map

package/lib/built/inbound-pipeline.js

@@ -62,4 +62,3 @@ export class InboundMessagePipeline {
         }));
     }
 }
-//# sourceMappingURL=inbound-pipeline.js.map

package/lib/built/inbound-runner.d.ts

@@ -20,4 +20,3 @@ export interface InboundRunResult {
  * Agent / 业务逻辑一致。
  */
 export declare function runInboundMessage(options: RunInboundMessageOptions): Promise<InboundRunResult>;
-//# sourceMappingURL=inbound-runner.d.ts.map

package/lib/built/inbound-runner.js

@@ -34,4 +34,3 @@ export async function runInboundMessage(options) {
     emitAdapterObservers();
     return { dispatched: !!dispatcher };
 }
-//# sourceMappingURL=inbound-runner.js.map

package/lib/built/interactive-segment-contract.d.ts

@@ -0,0 +1,6 @@
+import type { InteractivePolicy } from './interactive-segments/types.js';
+/** 契约测试：adapter 须声明 interactivePolicy */
+export declare function assertAdapterDeclaresInteractivePolicy(adapterClass: {
+    interactivePolicy?: InteractivePolicy;
+}): void;
+export type { InteractivePolicy };

package/lib/built/interactive-segment-contract.js

@@ -0,0 +1,9 @@
+/** 契约测试：adapter 须声明 interactivePolicy */
+export function assertAdapterDeclaresInteractivePolicy(adapterClass) {
+    if (!adapterClass.interactivePolicy) {
+        throw new Error('Adapter must declare static interactivePolicy');
+    }
+    if (adapterClass.interactivePolicy !== 'native' && adapterClass.interactivePolicy !== 'text') {
+        throw new Error('interactivePolicy must be "native" or "text"');
+    }
+}

package/lib/built/interactive-segments/action.d.ts

@@ -0,0 +1,17 @@
+import type { Message } from '../../message.js';
+import type { MessageElement } from '../../types.js';
+import { type ActionSegmentData } from './types.js';
+export declare function actionSegment(data: ActionSegmentData): MessageElement;
+export declare function getActionFromMessage(message: Message<any>): ActionSegmentData | undefined;
+/** 入站互动 action（按钮点击等），不应计入用户发言/消息统计 */
+export declare function isActionMessage(message: Message<any>): boolean;
+/** 去掉 @bot、XML at 段、首尾空白（QQ 指令预填文本归一化） */
+export declare function stripInteractiveCommandText(raw: string): string;
+/** 从文本降级输入解析 payload（需在 active session 的 fallback.map 中查找） */
+export declare function resolveTextFallbackPayload(raw: string, map: Record<string, string>): string | undefined;
+/**
+ * 从用户文本入站解析 interactive payload：
+ * 归一化 → 直接匹配 prefix:session:id → fallback 数字映射
+ */
+export declare function resolvePayloadFromText(raw: string, map?: Record<string, string>): string | undefined;
+export declare function formatActionAsRaw(data: ActionSegmentData): string;

package/lib/built/interactive-segments/action.js

@@ -0,0 +1,54 @@
+import { ACTION_SEGMENT_TYPE, isActionSegment, } from './types.js';
+export function actionSegment(data) {
+    return { type: ACTION_SEGMENT_TYPE, data };
+}
+export function getActionFromMessage(message) {
+    for (const item of message.$content ?? []) {
+        if (typeof item === 'string')
+            continue;
+        if (isActionSegment(item))
+            return item.data;
+    }
+    return undefined;
+}
+/** 入站互动 action（按钮点击等），不应计入用户发言/消息统计 */
+export function isActionMessage(message) {
+    return getActionFromMessage(message) != null;
+}
+const PAYLOAD_PATTERN = /^[a-z0-9_]+:[^:\s]+:[a-z0-9_-]+$/i;
+/** 去掉 @bot、XML at 段、首尾空白（QQ 指令预填文本归一化） */
+export function stripInteractiveCommandText(raw) {
+    let text = raw.trim();
+    text = text.replace(/<at\s[^>]*\/>/gi, ' ');
+    text = text.replace(/^@\S+\s+/u, '');
+    text = text.replace(/\s+/g, ' ').trim();
+    return text;
+}
+/** 从文本降级输入解析 payload（需在 active session 的 fallback.map 中查找） */
+export function resolveTextFallbackPayload(raw, map) {
+    const trimmed = raw.trim();
+    if (map[trimmed])
+        return map[trimmed];
+    const match = trimmed.match(/^(?:ttt\s+)?(\d)$/i);
+    if (match && map[match[1]])
+        return map[match[1]];
+    return undefined;
+}
+/**
+ * 从用户文本入站解析 interactive payload：
+ * 归一化 → 直接匹配 prefix:session:id → fallback 数字映射
+ */
+export function resolvePayloadFromText(raw, map) {
+    const normalized = stripInteractiveCommandText(raw);
+    if (!normalized)
+        return undefined;
+    if (PAYLOAD_PATTERN.test(normalized))
+        return normalized;
+    if (map && Object.keys(map).length > 0) {
+        return resolveTextFallbackPayload(normalized, map);
+    }
+    return undefined;
+}
+export function formatActionAsRaw(data) {
+    return data.payload;
+}

package/lib/built/interactive-segments/button-spec.d.ts

@@ -0,0 +1,10 @@
+import type { ButtonData } from './types.js';
+/** 键盘布局单元：`segment.button()` 产物，仅用于组装 `segment.keyboard()` */
+export declare class ButtonSpec {
+    readonly data: ButtonData;
+    constructor(data: ButtonData);
+}
+export type KeyboardRowInput = Array<ButtonSpec | ButtonData>;
+export declare function isButtonLike(value: unknown): value is ButtonSpec | ButtonData;
+export declare function normalizeButton(btn: ButtonSpec | ButtonData): ButtonData;
+export declare function normalizeKeyboardRows(rows: KeyboardRowInput[]): ButtonData[][];

package/lib/built/interactive-segments/button-spec.js

@@ -0,0 +1,21 @@
+/** 键盘布局单元：`segment.button()` 产物，仅用于组装 `segment.keyboard()` */
+export class ButtonSpec {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+}
+export function isButtonLike(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    if (value instanceof ButtonSpec)
+        return true;
+    const v = value;
+    return typeof v.id === 'string' && typeof v.label === 'string' && typeof v.payload === 'string';
+}
+export function normalizeButton(btn) {
+    return btn instanceof ButtonSpec ? btn.data : btn;
+}
+export function normalizeKeyboardRows(rows) {
+    return rows.map((row) => row.map(normalizeButton));
+}

package/lib/built/interactive-segments/handlers.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from '../../message.js';
+import type { MessageMiddleware } from '../../types.js';
+import type { InteractiveHandler, RegisteredInteractiveHandler } from './types.js';
+export declare function registerInteractiveHandler(prefix: string, handler: InteractiveHandler): () => void;
+export declare function getInteractiveHandlers(): readonly RegisteredInteractiveHandler[];
+export declare function resetInteractiveHandlersForTests(): void;
+/** 在根插件上安装一次性 action 路由中间件（幂等） */
+export declare function ensureInteractiveMiddleware(addMiddleware: (mw: MessageMiddleware) => () => void): void;
+export declare function dispatchInteractiveAction(message: Message<any>): Promise<boolean>;

package/lib/built/interactive-segments/handlers.js

@@ -0,0 +1,58 @@
+import { getActionFromMessage } from './action.js';
+const handlers = [];
+let middlewareInstalled = false;
+function findHandler(payload) {
+    let match;
+    for (const entry of handlers) {
+        if (payload.startsWith(entry.prefix)) {
+            if (!match || entry.prefix.length > match.prefix.length) {
+                match = entry;
+            }
+        }
+    }
+    return match?.handler;
+}
+export function registerInteractiveHandler(prefix, handler) {
+    const entry = { prefix, handler };
+    handlers.push(entry);
+    const dispose = () => {
+        const idx = handlers.indexOf(entry);
+        if (idx >= 0)
+            handlers.splice(idx, 1);
+    };
+    return dispose;
+}
+export function getInteractiveHandlers() {
+    return handlers;
+}
+export function resetInteractiveHandlersForTests() {
+    handlers.length = 0;
+    middlewareInstalled = false;
+}
+/** 在根插件上安装一次性 action 路由中间件（幂等） */
+export function ensureInteractiveMiddleware(addMiddleware) {
+    if (middlewareInstalled)
+        return;
+    middlewareInstalled = true;
+    addMiddleware(async (message, next) => {
+        const action = getActionFromMessage(message);
+        if (!action)
+            return next();
+        const handler = findHandler(action.payload);
+        if (!handler)
+            return next();
+        const handled = await handler(message);
+        if (handled)
+            return;
+        return next();
+    });
+}
+export async function dispatchInteractiveAction(message) {
+    const action = getActionFromMessage(message);
+    if (!action)
+        return false;
+    const handler = findHandler(action.payload);
+    if (!handler)
+        return false;
+    return !!(await handler(message));
+}

package/lib/built/interactive-segments/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './button-spec.js';
+export * from './action.js';
+export * from './resolve.js';
+export * from './handlers.js';
+export { KeyboardSegment, InteractiveSegment } from './keyboard-segment.js';
+export * from './onebot-keyboard.js';

package/lib/built/interactive-segments/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './button-spec.js';
+export * from './action.js';
+export * from './resolve.js';
+export * from './handlers.js';
+export { KeyboardSegment, InteractiveSegment } from './keyboard-segment.js';
+export * from './onebot-keyboard.js';

package/lib/built/interactive-segments/keyboard-segment.d.ts

@@ -0,0 +1,12 @@
+import { type KeyboardSegmentData } from './types.js';
+export declare class KeyboardSegment {
+    readonly data: KeyboardSegmentData;
+    readonly segmentType: "keyboard";
+    constructor(data: KeyboardSegmentData);
+    toElement(): {
+        type: "keyboard";
+        data: KeyboardSegmentData;
+    };
+}
+/** @deprecated 使用 {@link KeyboardSegment} */
+export declare const InteractiveSegment: typeof KeyboardSegment;

package/lib/built/interactive-segments/keyboard-segment.js

@@ -0,0 +1,13 @@
+import { KEYBOARD_SEGMENT_TYPE } from './types.js';
+export class KeyboardSegment {
+    data;
+    segmentType = KEYBOARD_SEGMENT_TYPE;
+    constructor(data) {
+        this.data = data;
+    }
+    toElement() {
+        return { type: this.segmentType, data: this.data };
+    }
+}
+/** @deprecated 使用 {@link KeyboardSegment} */
+export const InteractiveSegment = KeyboardSegment;

package/lib/built/interactive-segments/onebot-keyboard.d.ts

@@ -0,0 +1,10 @@
+import type { MessageSegment, SendContent } from '../../types.js';
+import { type KeyboardSegmentData } from './types.js';
+/** OneBot / QQ 系 keyboard 段（各 adapter 在 $sendMessage 中识别） */
+export declare function keyboardToOneBotSegment(data: KeyboardSegmentData): MessageSegment;
+/** @deprecated 使用 {@link keyboardToOneBotSegment} */
+export declare const interactiveToKeyboardSegment: typeof keyboardToOneBotSegment;
+/** 出站前将 core keyboard 段展开为 OneBot keyboard（保留前置 text 等段） */
+export declare function expandKeyboardSegmentsInContent(content: SendContent): SendContent;
+/** @deprecated 使用 {@link expandKeyboardSegmentsInContent} */
+export declare const expandInteractiveSegmentsInContent: typeof expandKeyboardSegmentsInContent;

package/lib/built/interactive-segments/onebot-keyboard.js

@@ -0,0 +1,53 @@
+import { isKeyboardSegment } from './types.js';
+import { KeyboardSegment } from './keyboard-segment.js';
+/** OneBot / QQ 系 keyboard 段（各 adapter 在 $sendMessage 中识别） */
+export function keyboardToOneBotSegment(data) {
+    return {
+        type: 'keyboard',
+        data: {
+            rows: data.rows.map((row) => row.map((btn) => ({
+                label: btn.label,
+                data: btn.payload,
+                enter: false,
+                action_type: 'callback',
+                disable: !!btn.disabled,
+            }))),
+        },
+    };
+}
+/** @deprecated 使用 {@link keyboardToOneBotSegment} */
+export const interactiveToKeyboardSegment = keyboardToOneBotSegment;
+function asKeyboardData(item) {
+    if (item instanceof KeyboardSegment)
+        return item.data;
+    if (isKeyboardSegment(item))
+        return item.data;
+    return null;
+}
+/** 出站前将 core keyboard 段展开为 OneBot keyboard（保留前置 text 等段） */
+export function expandKeyboardSegmentsInContent(content) {
+    const items = Array.isArray(content) ? content : [content];
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        if (typeof item.type !== 'string') {
+            continue;
+        }
+        const data = asKeyboardData(item);
+        if (data) {
+            out.push(keyboardToOneBotSegment(data));
+            continue;
+        }
+        out.push(item);
+    }
+    if (out.length === 0)
+        return { type: 'text', data: { text: '' } };
+    if (out.length === 1)
+        return out[0];
+    return out;
+}
+/** @deprecated 使用 {@link expandKeyboardSegmentsInContent} */
+export const expandInteractiveSegmentsInContent = expandKeyboardSegmentsInContent;

package/lib/built/interactive-segments/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { SendContent } from '../../types.js';
+import { type InteractivePolicy } from './types.js';
+export declare function hasKeyboardSegment(content: SendContent | undefined): boolean;
+/** @deprecated 使用 {@link hasKeyboardSegment} */
+export declare const hasInteractiveSegment: typeof hasKeyboardSegment;
+/** 按 Adapter interactivePolicy 将 keyboard 段转为 native 保留或文本降级 */
+export declare function resolveKeyboardSegments(content: SendContent, policy: InteractivePolicy): SendContent;
+/** @deprecated 使用 {@link resolveKeyboardSegments} */
+export declare const resolveInteractiveSegments: typeof resolveKeyboardSegments;

package/lib/built/interactive-segments/resolve.js

@@ -0,0 +1,84 @@
+import { segment } from '../../utils.js';
+import { KeyboardSegment } from './keyboard-segment.js';
+import { KEYBOARD_SEGMENT_TYPE, isKeyboardSegment, } from './types.js';
+function asKeyboardData(item) {
+    if (item instanceof KeyboardSegment)
+        return item.data;
+    if (isKeyboardSegment(item))
+        return item.data;
+    return null;
+}
+function toKeyboardElement(data) {
+    return { type: KEYBOARD_SEGMENT_TYPE, data };
+}
+function asArray(content) {
+    return Array.isArray(content) ? content : [content];
+}
+function packSegments(out) {
+    if (out.length === 0)
+        return { type: 'text', data: { text: '' } };
+    if (out.length === 1)
+        return out[0];
+    return out;
+}
+function renderKeyboardAsText(data) {
+    const lines = [];
+    const flat = data.rows.flat();
+    if (data.fallback?.hint) {
+        lines.push(data.fallback.hint);
+    }
+    else {
+        lines.push('请选择（回复数字）：');
+    }
+    const map = data.fallback?.map ?? {};
+    const entries = Object.keys(map).length > 0
+        ? Object.entries(map).sort(([a], [b]) => Number(a) - Number(b))
+        : flat.map((btn, idx) => [String(idx + 1), btn.payload]);
+    for (const [key, payload] of entries) {
+        const btn = flat.find((b) => b.payload === payload);
+        const label = btn?.label ?? '·';
+        lines.push(`${key}. ${label}${btn?.disabled ? ' (不可用)' : ''}`);
+    }
+    return lines.join('\n');
+}
+export function hasKeyboardSegment(content) {
+    if (content == null)
+        return false;
+    return asArray(content).some((item) => {
+        if (typeof item === 'string')
+            return false;
+        return item instanceof KeyboardSegment || isKeyboardSegment(item);
+    });
+}
+/** @deprecated 使用 {@link hasKeyboardSegment} */
+export const hasInteractiveSegment = hasKeyboardSegment;
+/** 按 Adapter interactivePolicy 将 keyboard 段转为 native 保留或文本降级 */
+export function resolveKeyboardSegments(content, policy) {
+    if (!hasKeyboardSegment(content))
+        return content;
+    const items = asArray(content);
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        const data = item instanceof KeyboardSegment
+            ? item.data
+            : isKeyboardSegment(item)
+                ? item.data
+                : null;
+        if (!data) {
+            out.push(item);
+            continue;
+        }
+        if (policy === 'native') {
+            out.push(toKeyboardElement(data));
+            continue;
+        }
+        out.push(segment.text(renderKeyboardAsText(data)));
+    }
+    return packSegments(out);
+}
+/** @deprecated 使用 {@link resolveKeyboardSegments} */
+export const resolveInteractiveSegments = resolveKeyboardSegments;

package/lib/built/interactive-segments/types.d.ts

@@ -0,0 +1,62 @@
+import type { MessageElement } from '../../types.js';
+export declare const KEYBOARD_SEGMENT_TYPE: "keyboard";
+/** @deprecated 使用 {@link KEYBOARD_SEGMENT_TYPE} */
+export declare const INTERACTIVE_SEGMENT_TYPE: "keyboard";
+export declare const ACTION_SEGMENT_TYPE: "action";
+export type ButtonStyle = 'primary' | 'danger' | 'secondary';
+/** @deprecated 使用 {@link ButtonStyle} */
+export type InteractiveButtonStyle = ButtonStyle;
+/** callback：平台回调 action 入站；command：QQ 指令预填后文本入站 */
+export type ButtonInteractionMode = 'callback' | 'command';
+export interface ButtonCommandOptions {
+    /** QQ action.enter — 仅单聊；预填后自动发送 */
+    enter?: boolean;
+    /** QQ action.reply — 预填时引用原消息 */
+    reply?: boolean;
+}
+export interface ButtonData {
+    id: string;
+    label: string;
+    payload: string;
+    disabled?: boolean;
+    style?: ButtonStyle;
+    /** 默认 callback */
+    mode?: ButtonInteractionMode;
+    command?: ButtonCommandOptions;
+}
+/** @deprecated 使用 {@link ButtonData} */
+export type InteractiveButton = ButtonData;
+export interface KeyboardFallback {
+    hint: string;
+    map: Record<string, string>;
+}
+/** @deprecated 使用 {@link KeyboardFallback} */
+export type InteractiveFallback = KeyboardFallback;
+export interface KeyboardSegmentData {
+    rows: ButtonData[][];
+    fallback?: KeyboardFallback;
+}
+/** @deprecated 使用 {@link KeyboardSegmentData} */
+export type InteractiveSegmentData = KeyboardSegmentData;
+export interface ActionSegmentData {
+    id: string;
+    payload: string;
+    sourceMessageId?: string;
+}
+export type InteractivePolicy = 'native' | 'text';
+export declare const DEFAULT_INTERACTIVE_POLICY: InteractivePolicy;
+export type InteractiveHandler = (message: import('../../message.js').Message<any>) => Promise<boolean> | boolean;
+export interface RegisteredInteractiveHandler {
+    prefix: string;
+    handler: InteractiveHandler;
+}
+export declare function isKeyboardSegment(item: MessageElement): item is MessageElement & {
+    type: typeof KEYBOARD_SEGMENT_TYPE;
+    data: KeyboardSegmentData;
+};
+/** @deprecated 使用 {@link isKeyboardSegment} */
+export declare const isInteractiveSegment: typeof isKeyboardSegment;
+export declare function isActionSegment(item: MessageElement): item is MessageElement & {
+    type: typeof ACTION_SEGMENT_TYPE;
+    data: ActionSegmentData;
+};

package/lib/built/interactive-segments/types.js

@@ -0,0 +1,13 @@
+export const KEYBOARD_SEGMENT_TYPE = 'keyboard';
+/** @deprecated 使用 {@link KEYBOARD_SEGMENT_TYPE} */
+export const INTERACTIVE_SEGMENT_TYPE = KEYBOARD_SEGMENT_TYPE;
+export const ACTION_SEGMENT_TYPE = 'action';
+export const DEFAULT_INTERACTIVE_POLICY = 'text';
+export function isKeyboardSegment(item) {
+    return item != null && typeof item === 'object' && 'type' in item && item.type === KEYBOARD_SEGMENT_TYPE;
+}
+/** @deprecated 使用 {@link isKeyboardSegment} */
+export const isInteractiveSegment = isKeyboardSegment;
+export function isActionSegment(item) {
+    return item != null && typeof item === 'object' && 'type' in item && item.type === ACTION_SEGMENT_TYPE;
+}

package/lib/built/introspection-format.d.ts

@@ -8,4 +8,3 @@ export interface EndpointRow {
 }
 export declare function formatEndpointsList(endpoints: EndpointRow[]): string;
 export declare function endpointHelpText(): string;
-//# sourceMappingURL=introspection-format.d.ts.map

package/lib/built/introspection-format.js

@@ -21,8 +21,8 @@ export function endpointHelpText() {
         '  /endpoint start <adapter> <name>',
         '  /endpoint stop <adapter> <name>',
         '  /endpoint cancel          — 取消进行中的添加/绑定',
+        '  /endpoint sync            — 将内存 endpoint 写回 zhin.config',
         '  /endpoint help',
         '  /endpoints                — 查看运行时在线状态',
     ].join('\n');
 }
-//# sourceMappingURL=introspection-format.js.map

package/lib/built/login-assist.d.ts

@@ -58,4 +58,3 @@ declare module '../plugin.js' {
         }
     }
 }
-//# sourceMappingURL=login-assist.d.ts.map

package/lib/built/login-assist.js

@@ -72,4 +72,3 @@ export class LoginAssist {
         this.pending.clear();
     }
 }
-//# sourceMappingURL=login-assist.js.map

package/lib/built/management-command-guard.d.ts

@@ -5,7 +5,11 @@ import { resolveSenderRoles, type AITriggerConfig } from './ai-trigger.js';
 import type { Message } from '../message.js';
 import type { Plugin } from '../plugin.js';
 export declare const MANAGEMENT_COMMAND_DENIED = "\u26A0\uFE0F \u8BE5\u547D\u4EE4\u4EC5 Endpoint Owner\uFF08master\uFF09\u6216 trusted \u64CD\u4F5C\u5458\u53EF\u7528\u3002";
+/** 运维 / 内省 / Endpoint 管理命令：仅 master 或 trusted 可执行与展示 */
+export declare const MANAGEMENT_OPERATOR_PERMIT: "role(master,trusted)";
+/** Endpoint Owner 私聊专用命令（如 /approve） */
+export declare const OWNER_OPERATOR_PERMIT: "role(master)";
+export declare const OWNER_PRIVATE_PERMITS: readonly ["role(master)", "private(*)"];
 export declare function resolveManagementCommandRoles(message: Message, root: Plugin, triggerConfig?: AITriggerConfig): ReturnType<typeof resolveSenderRoles>['roles'];
 /** 通过返回 null；拒绝返回用户可见提示文案 */
 export declare function rejectUnlessManagementOperator(message: Message, root: Plugin, triggerConfig?: AITriggerConfig): string | null;
-//# sourceMappingURL=management-command-guard.d.ts.map

package/lib/built/management-command-guard.js

@@ -4,6 +4,11 @@
 import { mergeAITriggerConfig, resolveSenderRoles, } from './ai-trigger.js';
 import { hasSenderRole } from './roles.js';
 export const MANAGEMENT_COMMAND_DENIED = '⚠️ 该命令仅 Endpoint Owner（master）或 trusted 操作员可用。';
+/** 运维 / 内省 / Endpoint 管理命令：仅 master 或 trusted 可执行与展示 */
+export const MANAGEMENT_OPERATOR_PERMIT = 'role(master,trusted)';
+/** Endpoint Owner 私聊专用命令（如 /approve） */
+export const OWNER_OPERATOR_PERMIT = 'role(master)';
+export const OWNER_PRIVATE_PERMITS = [OWNER_OPERATOR_PERMIT, 'private(*)'];
 export function resolveManagementCommandRoles(message, root, triggerConfig) {
     const cfg = mergeAITriggerConfig(triggerConfig ?? {});
     const adapterInstance = root.inject(message.$adapter);
@@ -18,4 +23,3 @@ export function rejectUnlessManagementOperator(message, root, triggerConfig) {
     }
     return MANAGEMENT_COMMAND_DENIED;
 }
-//# sourceMappingURL=management-command-guard.js.map

package/lib/built/message-enrich.d.ts

@@ -37,4 +37,3 @@ export declare function createSyntheticMessage(input: SyntheticMessageInput): Ag
 export declare function commMessageFromHookContext(context: Record<string, unknown>): Message<any> | undefined;
 /** 兼容 tool parameters 上的 contextKey（endpointId / sceneId / scope 等） */
 export declare function resolveContextKey(message: Message<any>, key: string): unknown;
-//# sourceMappingURL=message-enrich.d.ts.map

package/lib/built/message-enrich.js

@@ -79,4 +79,3 @@ export function resolveContextKey(message, key) {
         }
     }
 }
-//# sourceMappingURL=message-enrich.js.map

package/lib/built/message-filter.d.ts

@@ -174,4 +174,3 @@ export declare class MessageFilterFeature extends Feature<FilterRule> {
         setDefaultFilterPolicy(policy: FilterAction): void;
     };
 }
-//# sourceMappingURL=message-filter.d.ts.map

package/lib/built/message-filter.js

@@ -13,7 +13,6 @@
  *   - 插件通过 `addFilterRule()` 动态注册规则，卸载时自动清理
  */
 import { Feature } from '@zhin.js/kernel';
-import { getPlugin } from '../plugin.js';
 // ============================================================================
 // 规则工厂
 // ============================================================================
@@ -155,7 +154,7 @@ export class MessageFilterFeature extends Feature {
         const feature = this;
         return {
             addFilterRule(rule) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const dispose = feature.add(rule, plugin.name);
                 plugin.recordFeatureContribution(feature.name, rule.name);
                 plugin.onDispose(dispose);
@@ -238,4 +237,3 @@ export class MessageFilterFeature extends Feature {
         });
     }
 }
-//# sourceMappingURL=message-filter.js.map

package/lib/built/optional-peer-import.d.ts

@@ -0,0 +1,3 @@
+/** 从应用根（ZHIN_PROJECT_ROOT / cwd）解析 optional peer，避免 core 包目录下 dynamic import 失败 */
+export declare function resolveOptionalPeerPackage(packageName: string): string | undefined;
+export declare function importOptionalPeerPackage<T = Record<string, unknown>>(packageName: string): Promise<T>;