@zhin.js/core 1.5.1 → 1.5.4

package/lib/command.js

@@ -1,4 +1,5 @@
 import { SegmentMatcher } from 'segment-matcher';
+import { toPermissionSubject } from '@zhin.js/permission';
 /**
  * MessageCommand类：经典命令系统（segment-matcher）。
  *
@@ -75,26 +76,22 @@ export class MessageCommand extends SegmentMatcher {
         return this.#permissions;
     }
     /** 与 handle 一致的 permit 校验，供帮助菜单等场景过滤不可见命令 */
-    async checkPermits(message, plugin) {
+    async checkPermits(message, host) {
         if (!this.#permissions.length)
             return true;
-        const auth = plugin.contextIsReady('permission') ? plugin.inject('permission') : null;
-        if (!auth)
+        if (!host)
             return false;
-        for (const permit of this.#permissions) {
-            if (!(await auth.check(permit, message)))
-                return false;
-        }
-        return true;
+        const subject = toPermissionSubject(message);
+        return host.checkAll(this.#permissions, subject);
     }
     /**
      * 处理消息，自动匹配命令并执行回调
      * @param message 消息对象
-     * @param plugin 插件实例
+     * @param host PermissionHost（null 时有 permit 的命令 fail-closed）
      * @returns 命令返回内容或undefined
      */
-    async handle(message, plugin) {
-        if (!(await this.checkPermits(message, plugin))) {
+    async handle(message, host) {
+        if (!(await this.checkPermits(message, host))) {
             return;
         }
         const matched = this.match(message.$content);

package/lib/endpoint-capabilities.d.ts

@@ -22,15 +22,14 @@ export interface OutboundEndpoint<Config extends object = object> {
     $config: Config;
     $connected: boolean;
     $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
 }
 export type FullEndpoint<Config extends object = object, Event extends object = object> = InboundEndpoint<Config, Event> & OutboundEndpoint<Config>;
 export type CapableEndpoint<Config extends object, Event extends object, Caps extends readonly EndpointCapability[]> = ('inbound' extends Caps[number] ? InboundEndpoint<Config, Event> : object) & ('outbound' extends Caps[number] ? OutboundEndpoint<Config> : object);
 export declare class OutboundNotSupportedError extends Error {
-    constructor(endpointId?: string);
+    constructor(endpointKey?: string);
 }
 export declare class InboundNotSupportedError extends Error {
-    constructor(endpointId?: string);
+    constructor(endpointKey?: string);
 }
 export declare function registerEndpointCapabilities(endpoint: object, caps: readonly EndpointCapability[]): void;
 export declare function getEndpointCapabilities(endpoint: object): readonly EndpointCapability[] | undefined;

package/lib/endpoint-capabilities.js

@@ -1,13 +1,13 @@
 export const DEFAULT_ENDPOINT_CAPABILITIES = ['inbound', 'outbound'];
 export class OutboundNotSupportedError extends Error {
-    constructor(endpointId) {
-        super(endpointId ? `Endpoint ${endpointId} does not support outbound` : 'Outbound not supported');
+    constructor(endpointKey) {
+        super(endpointKey ? `Endpoint ${endpointKey} does not support outbound` : 'Outbound not supported');
         this.name = 'OutboundNotSupportedError';
     }
 }
 export class InboundNotSupportedError extends Error {
-    constructor(endpointId) {
-        super(endpointId ? `Endpoint ${endpointId} does not support inbound` : 'Inbound not supported');
+    constructor(endpointKey) {
+        super(endpointKey ? `Endpoint ${endpointKey} does not support inbound` : 'Inbound not supported');
         this.name = 'InboundNotSupportedError';
     }
 }

package/lib/endpoint.d.ts

@@ -3,6 +3,8 @@ import type { EndpointCapabilitiesConfig, FullEndpoint } from './endpoint-capabi
 import type { EndpointWithManagement } from '@zhin.js/adapter';
 export type { EndpointChannel, EndpointChannelParent, EndpointFriend, EndpointGroup, EndpointManagement, EndpointWithManagement, EndpointManagementCapability, } from '@zhin.js/adapter';
 export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
+export type { EndpointControl, EndpointWithControl } from '@zhin.js/adapter';
+export { resolveEndpointControl } from '@zhin.js/adapter';
 export type { EndpointCapability, EndpointCapabilitiesConfig, InboundEndpoint, OutboundEndpoint, FullEndpoint, CapableEndpoint, } from './endpoint-capabilities.js';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';
 /**

package/lib/endpoint.js

@@ -1,2 +1,3 @@
 export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
+export { resolveEndpointControl } from '@zhin.js/adapter';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';

package/lib/errors.d.ts

@@ -8,8 +8,8 @@ import { ZhinError } from '@zhin.js/kernel';
  */
 export declare class AdapterError extends ZhinError {
     readonly adapterName: string;
-    readonly endpointId?: string;
-    constructor(message: string, adapterName: string, endpointId?: string, context?: Record<string, any>);
+    readonly endpointKey?: string;
+    constructor(message: string, adapterName: string, endpointKey?: string, context?: Record<string, any>);
 }
 /**
  * 消息处理错误

package/lib/errors.js

@@ -8,11 +8,11 @@ import { ZhinError } from '@zhin.js/kernel';
  */
 export class AdapterError extends ZhinError {
     adapterName;
-    endpointId;
-    constructor(message, adapterName, endpointId, context) {
-        super(message, 'ADAPTER_ERROR', { ...context, adapterName, endpointId });
+    endpointKey;
+    constructor(message, adapterName, endpointKey, context) {
+        super(message, 'ADAPTER_ERROR', { ...context, adapterName, endpointKey });
         this.adapterName = adapterName;
-        this.endpointId = endpointId;
+        this.endpointKey = endpointKey;
     }
 }
 /**

package/lib/host-plugin-registry.d.ts

@@ -1,7 +1,8 @@
 /**
- * 宿主根插件引用 — 在 Bot 启动/装配阶段注册，供运行时路径读取。
- * 避免在中间件、工具 execute、命令 action 等回调内调用 getPlugin()（ALS 易丢失）。
+ * @deprecated **已删除**。全局根插件注册表已移除；服务通过 Scope+Token 提供。
+ * 保留 no-op 签名供编译期过渡。
  */
-import type { Plugin } from './plugin.js';
-export declare function setHostRootPlugin(plugin: Plugin | null): void;
-export declare function getHostRootPlugin(): Plugin | null;
+/** @deprecated 已删除——不做任何事。 */
+export declare function setHostRootPlugin(_plugin: unknown): void;
+/** @deprecated 已删除——总是返回 null。 */
+export declare function getHostRootPlugin(): null;

package/lib/host-plugin-registry.js

@@ -1,7 +1,12 @@
-let hostRoot = null;
-export function setHostRootPlugin(plugin) {
-    hostRoot = plugin ? (plugin.root ?? plugin) : null;
+/**
+ * @deprecated **已删除**。全局根插件注册表已移除；服务通过 Scope+Token 提供。
+ * 保留 no-op 签名供编译期过渡。
+ */
+/** @deprecated 已删除——不做任何事。 */
+export function setHostRootPlugin(_plugin) {
+    // no-op: legacy host root plugin registry has been removed
 }
+/** @deprecated 已删除——总是返回 null。 */
 export function getHostRootPlugin() {
-    return hostRoot;
+    return null;
 }

package/lib/im-scene.d.ts

@@ -9,7 +9,7 @@ export interface IMSceneParentRef {
 }
 export interface IMSceneRef {
     platform: string;
-    endpointId: string;
+    endpointKey: string;
     sceneId: string;
     kind: IMSceneKind;
     senderId?: string;

package/lib/im-scene.js

@@ -12,9 +12,9 @@ export function normalizeIMSceneParentKind(value) {
 }
 export function sceneRefFromMessage(message) {
     const platform = nonEmptyString(message.$adapter);
-    const endpointId = nonEmptyString(message.$endpoint);
+    const endpointKey = nonEmptyString(message.$endpoint);
     const kind = message.$channel?.type;
-    if (!platform || !endpointId || !kind)
+    if (!platform || !endpointKey || !kind)
         return undefined;
     const senderId = nonEmptyString(message.$sender?.id);
     const channelId = nonEmptyString(message.$channel?.id);
@@ -34,7 +34,7 @@ export function sceneRefFromMessage(message) {
         : undefined;
     return {
         platform,
-        endpointId,
+        endpointKey,
         sceneId,
         kind,
         ...(senderId ? { senderId } : {}),
@@ -45,7 +45,7 @@ export function sceneRefToSendOptions(target, content) {
     const { scene } = target;
     return {
         context: scene.platform,
-        endpoint: scene.endpointId,
+        endpoint: scene.endpointKey,
         id: scene.sceneId,
         type: scene.kind,
         parent: scene.parent
@@ -59,7 +59,7 @@ export function sceneRefToSendOptions(target, content) {
 export function resolveIMSceneSessionId(scene) {
     return resolveIMSceneSessionIdKernel({
         platform: scene.platform,
-        endpointId: scene.endpointId,
+        endpointKey: scene.endpointKey,
         sceneId: scene.sceneId,
         kind: scene.kind,
     });

package/lib/im-session-id.d.ts

@@ -1,7 +1,7 @@
 /**
  * IM 会话 ID 解析（SSOT 在 @zhin.js/kernel + im-scene）
  *
- * 格式：`platform:endpointId:kind:sceneId`
+ * 格式：`platform:endpointKey:kind:sceneId`
  */
 import { type ResolveIMSessionIdInput } from '@zhin.js/kernel';
 import { type IMSceneKind, type IMSceneRef } from './im-scene.js';
@@ -33,7 +33,7 @@ export declare function resolveSceneFieldsFromMessage(message: {
     };
 }): {
     platform: string;
-    endpointId: string;
+    endpointKey: string;
     sceneId: string;
     sceneType: IMSceneKind;
 };

package/lib/im-session-id.js

@@ -1,7 +1,7 @@
 /**
  * IM 会话 ID 解析（SSOT 在 @zhin.js/kernel + im-scene）
  *
- * 格式：`platform:endpointId:kind:sceneId`
+ * 格式：`platform:endpointKey:kind:sceneId`
  */
 import { resolveIMSceneIdForSession as resolveIMSceneIdForSessionKernel, resolveIMSessionId as resolveIMSessionIdKernel, } from '@zhin.js/kernel';
 import { resolveIMSceneSessionId, sceneRefFromMessage, } from './im-scene.js';
@@ -21,7 +21,7 @@ export function resolveIMSessionIdFromMessage(message) {
     const kind = (message.$channel?.type || 'private');
     return resolveIMSessionId({
         platform: String(message.$adapter || ''),
-        endpointId: String(message.$endpoint || ''),
+        endpointKey: String(message.$endpoint || ''),
         kind,
         sceneId: resolveIMSceneIdForSession(kind, message.$channel?.id, message.$sender?.id),
     });
@@ -32,7 +32,7 @@ export function resolveSceneFieldsFromMessage(message) {
     if (scene) {
         return {
             platform: scene.platform,
-            endpointId: scene.endpointId,
+            endpointKey: scene.endpointKey,
             sceneId: scene.sceneId,
             sceneType: scene.kind,
         };
@@ -40,7 +40,7 @@ export function resolveSceneFieldsFromMessage(message) {
     const sceneType = (message.$channel?.type || 'private');
     return {
         platform: String(message.$adapter || ''),
-        endpointId: String(message.$endpoint || ''),
+        endpointKey: String(message.$endpoint || ''),
         sceneType,
         sceneId: resolveIMSceneIdForSession(sceneType, message.$channel?.id, message.$sender?.id),
     };

package/lib/index.d.ts

@@ -20,7 +20,6 @@ export * from './built/schedule.js';
 export type { ScheduleDescriptor, ScheduleHandle, ScheduleContextExtensions } from './built/schedule.js';
 export * from './models/system-log.js';
 export * from './models/user.js';
-export * from './built/permission.js';
 export * from './built/permit-parse.js';
 export * from './built/permit-check.js';
 export * from './built/platform-permit.js';
@@ -42,7 +41,6 @@ export * from './built/dispatcher.js';
 export * from './built/schema-feature.js';
 export * from './built/login-assist.js';
 export * from './built/generated-qrcode.js';
-export * from './built/qrcode-segment.js';
 export * from './built/rich-segments/index.js';
 export * from './built/interactive-segments/index.js';
 export * from './built/ai-outbound/index.js';
@@ -52,6 +50,7 @@ export * from './built/outbound-media-utils.js';
 export * from './built/outbound-media-contract.js';
 export * from './built/interactive-segment-contract.js';
 export * from './built/segment-contract/index.js';
+export type { SegmentMediaRef } from './built/segment-contract/media.js';
 export * from './built/generic-segment-mapper.js';
 export * from './built/adapter-process.js';
 export * from './built/component.js';

package/lib/index.js

@@ -22,7 +22,6 @@ export * from './built/schedule.js';
 // Models
 export * from './models/system-log.js';
 export * from './models/user.js';
-export * from './built/permission.js';
 export * from './built/permit-parse.js';
 export * from './built/permit-check.js';
 export * from './built/platform-permit.js';
@@ -43,7 +42,6 @@ export * from './built/dispatcher.js';
 export * from './built/schema-feature.js';
 export * from './built/login-assist.js';
 export * from './built/generated-qrcode.js';
-export * from './built/qrcode-segment.js';
 export * from './built/rich-segments/index.js';
 export * from './built/interactive-segments/index.js';
 export * from './built/ai-outbound/index.js';

package/lib/jsx-runtime.d.ts

@@ -1,5 +1,6 @@
 import { jsx, jsxs, Fragment, renderJSX } from './jsx.js';
 export { jsx, jsxs, Fragment, renderJSX };
+export type { JSX } from './jsx.js';
 declare const _default: {
     jsx: typeof jsx;
     jsxs: typeof jsxs;

package/lib/jsx.d.ts

@@ -1,30 +1,28 @@
-import { SendContent, MessageElement } from './types.js';
-import { MessageComponent } from './message.js';
-import { Component, ComponentContext } from './component.js';
+import type { SendContent, MessageElement } from './types.js';
+import type { MessageComponent } from './message.js';
+import type { Component, ComponentContext } from './component.js';
 export type JSXChildren = MessageElement | string | number | boolean | null | undefined | JSXChildren[];
 export type JSXElementType = string | Component<any>;
 export type JSXProps = Record<string, any> & {
     children?: JSXChildren;
 };
 export { Fragment } from './component.js';
-declare global {
-    namespace JSX {
-        type Element = SendContent | Promise<SendContent>;
-        interface ElementClass {
-            render(props: any, context?: ComponentContext): Element;
-        }
-        interface ElementAttributesProperty {
-            data: {};
-        }
-        interface ElementChildrenAttribute {
-            children: {};
-        }
-        interface IntrinsicElements {
-            [elemName: string]: any;
-        }
-        interface IntrinsicAttributes {
-            key?: string | number;
-        }
+export declare namespace JSX {
+    type Element = SendContent | Promise<SendContent>;
+    interface ElementClass {
+        render(props: any, context?: ComponentContext): Element;
+    }
+    interface ElementAttributesProperty {
+        data: {};
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+    interface IntrinsicElements {
+        [elemName: string]: any;
+    }
+    interface IntrinsicAttributes {
+        key?: string | number;
     }
 }
 export declare function jsx(type: JSXElementType, data: JSXProps): MessageComponent<any>;

package/lib/message.d.ts

@@ -1,4 +1,4 @@
-import { MessageElement, MessageSender, SendContent } from "./types.js";
+import type { MessageElement, MessageSender, SendContent } from "./types.js";
 import { Component } from "./component.js";
 import { Adapters } from "./adapter.js";
 /**

package/lib/message.js

@@ -6,7 +6,7 @@ export var Message;
      * 工具方法：合并自定义字段与基础消息结构
      */
     function from(input, format) {
-        return Object.assign(input, format);
+        return Object.assign({}, input, format);
     }
     Message.from = from;
     function quoteIdFromContent(content) {

package/lib/notice.d.ts

@@ -1,7 +1,7 @@
 import type { Adapters } from './adapter.js';
 import type { NoticeKind } from './side-event/types.js';
 import type { SideEventBase } from './side-event/base.js';
-export type { NoticeKind, ComposedNoticeName, NoticeType } from './side-event/types.js';
+export type { NoticeKind, ComposedNoticeName } from './side-event/types.js';
 export type { SideEventBase } from './side-event/base.js';
 export { composeSideEventName, formatSideEventName, matchesSideEventName, parseSideEventName, sideEventSendChannel, } from './side-event/base.js';
 /**
@@ -12,7 +12,7 @@ export { composeSideEventName, formatSideEventName, matchesSideEventName, parseS
  * const notice = Notice.from(rawEvent, {
  *   $id: rawEvent.id,
  *   $adapter: 'icqq',
- *   $endpoint: endpointId,
+ *   $endpoint: endpointKey,
  *   $type: 'notice',
  *   $scene_id: groupId,
  *   $scene_type: 'group',

package/lib/plugin-context.d.ts

@@ -7,23 +7,21 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Plugin } from "./plugin.js";
 export declare const storage: AsyncLocalStorage<Plugin>;
+/**
+ * Plugin Runtime (`zhin runtime start`) 启动时调用。
+ * 标记后 getPlugin()/usePlugin() 在 ALS 为空时抛出更明确的迁移提示，
+ * 而非通用的 "must be called within a plugin context"。
+ */
+export declare function markPluginRuntimeActive(): void;
+export declare function isPluginRuntimeActive(): boolean;
+/** 测试重置 */
+export declare function resetPluginRuntimeFlag(): void;
 /**
  * 获取当前文件路径（调用者）
  */
 export declare function getCurrentFile(metaUrl?: string): string;
 /**
- * getPlugin - 获取当前 AsyncLocalStorage 中的插件实例
- *
- * **调用时机（重要）**
- * - ✅ 插件**初始化/装配**阶段：模块顶层、register/init 函数内、注册命令/中间件/工具**之前**
- * - ❌ **运行时回调**内严禁调用：中间件、命令 `.action()`、工具 `.execute()`、Cron、生命周期 `.on()` 等
- *
- * 运行时回调应使用初始化时捕获的 `plugin` / `root` 闭包引用，而非再次 `getPlugin()`。
- * AsyncLocalStorage 在跨 await、线程池、部分平台适配器回调中可能丢失，导致线上 `getPlugin() must be called within a plugin context`。
- *
- * 插件作者优先在模块顶层使用 `usePlugin()` 解构 API，一般不需要 `getPlugin()`。
- * Bot 启动时框架调用 `setHostRootPlugin(root)`；运行时模块用 `getHostRootPlugin()` 代替 `getPlugin()`。
- *
- * @see docs/guide/plugin-development.md#getplugin-与-useplugin
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录；运行时通过 Scope+Token 访问服务。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
  */
 export declare function getPlugin(): Plugin;

package/lib/plugin-context.js

@@ -11,6 +11,22 @@ import { fileURLToPath } from "node:url";
 // AsyncLocalStorage 上下文
 // ============================================================================
 export const storage = new AsyncLocalStorage();
+let _pluginRuntimeActive = false;
+/**
+ * Plugin Runtime (`zhin runtime start`) 启动时调用。
+ * 标记后 getPlugin()/usePlugin() 在 ALS 为空时抛出更明确的迁移提示，
+ * 而非通用的 "must be called within a plugin context"。
+ */
+export function markPluginRuntimeActive() {
+    _pluginRuntimeActive = true;
+}
+export function isPluginRuntimeActive() {
+    return _pluginRuntimeActive;
+}
+/** 测试重置 */
+export function resetPluginRuntimeFlag() {
+    _pluginRuntimeActive = false;
+}
 /**
  * 获取当前文件路径（调用者）
  */
@@ -38,24 +54,11 @@ export function getCurrentFile(metaUrl = import.meta.url) {
     }
 }
 /**
- * getPlugin - 获取当前 AsyncLocalStorage 中的插件实例
- *
- * **调用时机（重要）**
- * - ✅ 插件**初始化/装配**阶段：模块顶层、register/init 函数内、注册命令/中间件/工具**之前**
- * - ❌ **运行时回调**内严禁调用：中间件、命令 `.action()`、工具 `.execute()`、Cron、生命周期 `.on()` 等
- *
- * 运行时回调应使用初始化时捕获的 `plugin` / `root` 闭包引用，而非再次 `getPlugin()`。
- * AsyncLocalStorage 在跨 await、线程池、部分平台适配器回调中可能丢失，导致线上 `getPlugin() must be called within a plugin context`。
- *
- * 插件作者优先在模块顶层使用 `usePlugin()` 解构 API，一般不需要 `getPlugin()`。
- * Bot 启动时框架调用 `setHostRootPlugin(root)`；运行时模块用 `getHostRootPlugin()` 代替 `getPlugin()`。
- *
- * @see docs/guide/plugin-development.md#getplugin-与-useplugin
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录；运行时通过 Scope+Token 访问服务。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
  */
 export function getPlugin() {
-    const plugin = storage.getStore();
-    if (!plugin) {
-        throw new Error('getPlugin() must be called within a plugin context');
-    }
-    return plugin;
+    throw new Error('getPlugin() has been removed. Use `definePlugin` + convention directories, '
+        + 'and access services via Scope+Token. '
+        + 'See docs/contributing/public-api-surface.md');
 }