@zhin.js/core 1.3.3 → 1.3.5

package/README.md

@@ -1,5 +1,17 @@
 # @zhin.js/core
 
+## Plugin Runtime 子路径
+
+新的 owner-aware IM 能力已经并入 Core，作为 Plugin Runtime 的正式领域接口：
+
+- `@zhin.js/core/runtime`
+
+`@zhin.js/adapter`、`@zhin.js/command`、`@zhin.js/component` 与
+`@zhin.js/middleware` 提供纯 definition、约定发现 provider 和 generation projection；
+Core Runtime 只消费它们发布的 snapshot。
+旧根入口的 `addCommand`、`addComponent`、`addMiddleware` 暂时作为作者兼容接口保留，后续
+只向 RuntimeSnapshot 投影，不再维护第二套运行时权威。
+
 Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、MessageDispatcher 与统一出站链。**AI 编排（ZhinAgent、工具安全、MCP）在 [`@zhin.js/agent`](../agent/README.md)**；本包仅 selective re-export `@zhin.js/ai` 的 Provider / Agent 原语供插件直接使用。
 
 领域词汇见 [CONTEXT.md](./CONTEXT.md)；入站/出站流程见 [消息如何流转](../../docs/essentials/message-flow.md)。

package/lib/adapter.js

@@ -194,7 +194,7 @@ export class Adapter extends EventEmitter {
         if (!endpoint)
             throw new Error(`Endpoint ${options.endpoint} not found`);
         assertOutbound(endpoint);
-        this.logger.info(formatCompact({
+        this.logger.debug(formatCompact({
             send: `${options.type}(${options.id})`,
             endpoint: options.endpoint,
             preview: truncatePreview(segment.raw(options.content)),
@@ -231,7 +231,7 @@ export class Adapter extends EventEmitter {
                 content: options.content,
             });
             await editable.$editMessage({ ...options, content: rendered.content });
-            this.logger.info(formatCompact({
+            this.logger.debug(formatCompact({
                 edit: `${options.type}(${options.id})`,
                 endpoint: options.endpoint,
                 messageId: options.messageId,

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

@@ -21,19 +21,17 @@ export function parseOutboundSegment(raw) {
 /** 去掉嵌入 JSON 候选末尾的 markdown 围栏（模型常见 ```json … ``` 误输出）。 */
 export function trimTrailingMarkdownFence(raw) {
     let s = raw.trim();
-    const trailingFence = s.match(/^([\s\S]*?)\s*```\s*$/);
-    if (trailingFence)
-        s = trailingFence[1].trim();
+    if (s.endsWith('```'))
+        s = s.slice(0, -3).trimEnd();
     return s;
 }
 export function unwrapAiOutboundJsonCandidate(raw) {
     const trimmed = raw.trim();
-    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)```\s*$/i);
-    if (fenced)
-        return fenced[1].trim();
-    const embeddedFence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
-    if (embeddedFence && trimmed.indexOf('{') >= 0) {
-        return trimTrailingMarkdownFence(embeddedFence[1].trim());
+    const fenced = readMarkdownFence(trimmed);
+    if (fenced && fenced.full)
+        return fenced.body.trim();
+    if (fenced && trimmed.indexOf('{') >= 0) {
+        return trimTrailingMarkdownFence(fenced.body.trim());
     }
     return trimTrailingMarkdownFence(trimmed);
 }
@@ -42,12 +40,12 @@ export function extractEmbeddedAiOutboundJson(plain) {
     const trimmed = plain.trim();
     if (!trimmed.includes('{'))
         return null;
-    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const fenced = readMarkdownFence(trimmed);
     if (fenced) {
-        const jsonRaw = trimTrailingMarkdownFence(fenced[1].trim());
+        const jsonRaw = trimTrailingMarkdownFence(fenced.body.trim());
         const payload = parseAiOutboundJson(jsonRaw);
         if (payload?.mentions?.length && payload.text?.trim()) {
-            const prose = trimmed.slice(0, fenced.index).trim();
+            const prose = trimmed.slice(0, fenced.start).trim();
             return { prose, jsonRaw };
         }
     }
@@ -62,6 +60,22 @@ export function extractEmbeddedAiOutboundJson(plain) {
     }
     return null;
 }
+function readMarkdownFence(text) {
+    const start = text.indexOf('```');
+    if (start < 0)
+        return null;
+    let bodyStart = start + 3;
+    const langEnd = text.indexOf('\n', bodyStart);
+    if (langEnd >= 0) {
+        const lang = text.slice(bodyStart, langEnd).trim().toLowerCase();
+        if (lang === '' || lang === 'json')
+            bodyStart = langEnd + 1;
+    }
+    const end = text.indexOf('```', bodyStart);
+    if (end < 0)
+        return null;
+    return { start, body: text.slice(bodyStart, end), full: start === 0 && text.slice(end + 3).trim() === '' };
+}
 export function parseAiOutboundJson(raw) {
     const candidate = unwrapAiOutboundJsonCandidate(raw);
     if (!candidate.startsWith('{'))

package/lib/built/authorization.js

@@ -1,6 +1,6 @@
 import { mergeAITriggerConfig, resolveSenderRoles, } from './ai-trigger.js';
-import { formatCompact, Logger } from '@zhin.js/logger';
-const logger = new Logger(null, 'Authorization');
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('Authorization');
 function findEndpointEntryFromConfig(config, adapter, endpointId) {
     const endpoints = config.endpoints;
     if (!Array.isArray(endpoints))

package/lib/built/component.d.ts

@@ -2,9 +2,8 @@
  * ComponentFeature
  * 管理所有插件注册的组件，继承自 Feature 抽象类
  */
-import { Feature, FeatureJSON } from "@zhin.js/kernel";
+import { Feature, FeatureJSON, type PluginLike } from '@zhin.js/kernel';
 import { Component } from "../component.js";
-import type { PluginLike } from '@zhin.js/kernel';
 /**
  * ComponentContext 扩展方法类型
  */

package/lib/built/component.js

@@ -2,7 +2,7 @@
  * ComponentFeature
  * 管理所有插件注册的组件，继承自 Feature 抽象类
  */
-import { Feature } from "@zhin.js/kernel";
+import { Feature } from '@zhin.js/kernel';
 import { renderComponents } from "../component.js";
 /**
  * 组件服务 Feature

package/lib/built/database.d.ts

@@ -4,8 +4,7 @@
  */
 import { Definition, Database } from "@zhin.js/database";
 import { DatabaseConfig, Models } from "../types.js";
-import { Feature, FeatureJSON } from "@zhin.js/kernel";
-import type { PluginLike } from '@zhin.js/kernel';
+import { Feature, FeatureJSON, type PluginLike } from '@zhin.js/kernel';
 /**
  * 模型定义记录
  */

package/lib/built/database.js

@@ -4,7 +4,7 @@
  */
 import { Registry } from "@zhin.js/database";
 import { formatCompact } from '@zhin.js/logger';
-import { Feature } from "@zhin.js/kernel";
+import { Feature } from '@zhin.js/kernel';
 import { SystemLogDefinition } from "../models/system-log.js";
 import { UserDefinition } from "../models/user.js";
 const databaseAfterStartHooks = [];

package/lib/built/dispatcher.d.ts

@@ -27,8 +27,8 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { Message } from '../message.js';
+import { type Context } from '../plugin.js';
 import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware, OutboundReplyStore } from '../types.js';
-import type { Context } from '../plugin.js';
 export declare function getOutboundReplyStore(): OutboundReplyStore | undefined;
 /**
  * 路由判定结果（互斥模式 legacy）

package/lib/built/endpoint-lifecycle-service.js

@@ -1,3 +1,4 @@
+import { formatDisplayPath } from '@zhin.js/logger';
 import { Adapter } from '../adapter.js';
 import { segment } from '../utils.js';
 import { connectEndpointInstance, disconnectEndpointInstance } from './connect-endpoint-instance.js';
@@ -81,7 +82,7 @@ export class EndpointLifecycleService {
         const loader = configService.configs.get(configService.primaryFile);
         const endpoints = readAllEndpoints(this.root);
         await this.persistEndpoints(endpoints);
-        const configPath = loader.resolvedPath;
+        const configPath = formatDisplayPath(loader.resolvedPath);
         const names = endpoints.map((e) => `${e.context}/${e.name}`).join(', ') || '（无）';
         return {
             message: `✅ 已将 ${endpoints.length} 个 endpoint 写入 \`${configPath}\`：${names}`,

package/lib/built/endpoint-lifecycle.js

@@ -26,9 +26,10 @@ export async function emitEndpointLifecycle(plugin, adapter, endpoint, kind, det
         $id: `endpoint-lifecycle:${endpoint.$id}:${kind}:${Date.now()}`,
         $adapter: adapter.name,
         $endpoint: endpoint.$id,
-        $type: 'endpoint.lifecycle',
-        $subType: kind,
-        $channel: { id: endpoint.$id, type: 'private' },
+        $type: 'notice',
+        $scene_id: endpoint.$id,
+        $scene_type: 'endpoint',
+        $sub_type: kind,
         $timestamp: Date.now(),
     });
     adapter.emit('notice.receive', notice);

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

@@ -79,20 +79,21 @@ function stripRemainingTags(html) {
     return out;
 }
 function decodeCommonEntities(text) {
-    return text
-        .replace(/ /gi, ' ')
-        .replace(/&/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'")
-        .replace(/&apos;/g, "'")
-        .replace(/&#(\d+);/g, (_, code) => {
-        const n = Number(code);
-        return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
-    })
-        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => {
-        const n = parseInt(hex, 16);
+    return text.replace(/&(#x[0-9a-fA-F]+|#\d+|nbsp|amp|lt|gt|quot|apos);/gi, (entity) => {
+        const key = entity.slice(1, -1).toLowerCase();
+        if (key === 'nbsp')
+            return ' ';
+        if (key === 'amp')
+            return '&';
+        if (key === 'lt')
+            return '<';
+        if (key === 'gt')
+            return '>';
+        if (key === 'quot')
+            return '"';
+        if (key === 'apos')
+            return "'";
+        const n = key.startsWith('#x') ? parseInt(key.slice(2), 16) : Number(key.slice(1));
         return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
     });
 }

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

@@ -4,7 +4,7 @@
  * Extracted from Adapter.emit() override to improve testability and decoupling.
  * Handles: event routing, logging, backpressure, pipeline execution, observer emission.
  */
-import type { Logger } from '@zhin.js/logger';
+import { type Logger } from '@zhin.js/logger';
 import { type Message as MessageType } from '../message.js';
 import type { Plugin } from '../plugin.js';
 export interface InboundPipelineOptions {

package/lib/built/inbound-pipeline.js

@@ -54,7 +54,7 @@ export class InboundMessagePipeline {
         return result;
     }
     logIncoming(message) {
-        this.options.logger.info(formatCompact({
+        this.options.logger.debug(formatCompact({
             recv: `${message.$channel.type}(${message.$channel.id})`,
             endpoint: message.$endpoint,
             preview: truncatePreview(segment.raw(message.$content)),

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

@@ -19,11 +19,26 @@ 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 = stripXmlAtSegments(text);
     text = text.replace(/^@\S+\s+/u, '');
     text = text.replace(/\s+/g, ' ').trim();
     return text;
 }
+function stripXmlAtSegments(text) {
+    let out = '';
+    let cursor = 0;
+    while (cursor < text.length) {
+        const start = text.toLowerCase().indexOf('<at ', cursor);
+        if (start < 0)
+            break;
+        const end = text.indexOf('/>', start + 4);
+        if (end < 0)
+            break;
+        out += text.slice(cursor, start) + ' ';
+        cursor = end + 2;
+    }
+    return out + text.slice(cursor);
+}
 /** 从文本降级输入解析 payload（需在 active session 的 fallback.map 中查找） */
 export function resolveTextFallbackPayload(raw, map) {
     const trimmed = raw.trim();

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

@@ -5,7 +5,7 @@ import type { Plugin } from '../plugin.js';
 import { Message, type MessageChannel } from '../message.js';
 import type { Adapters } from '../adapter.js';
 import type { SendContent } from '../types.js';
-import type { SenderRole } from './roles.js';
+import { type SenderRole } from './roles.js';
 /** Agent turn 可挂载在 Message 扩展字段上的元数据 */
 export type AgentTurnMessage = Message<{
     extra?: Record<string, unknown>;

package/lib/built/permit-check.d.ts

@@ -2,6 +2,6 @@
  * 内置 permit 同步校验（adapter/group/private/channel/user/role）
  */
 import type { Message } from '../message.js';
-import type { SenderRole } from './roles.js';
+import { type SenderRole } from './roles.js';
 export declare function checkBuiltinPermit(name: string, message: Message<any>, roles: readonly SenderRole[]): boolean;
 export declare function checkBuiltinPermitList(permits: readonly string[], message: Message<any>, roles: readonly SenderRole[]): boolean;

package/lib/built/platform-permit.js

@@ -1,18 +1,25 @@
 import { parsePlatformPermitName, isPlatformPermit } from './permit-parse.js';
 const checkers = new Map();
-const registeredDefaultSceneCheckers = new Set();
+const defaultSceneRegistrations = new Map();
 export function registerPlatformPermitChecker(adapter, checker) {
     const key = String(adapter);
-    checkers.set(key, checker);
+    const registrations = checkers.get(key) ?? [];
+    registrations.push(checker);
+    checkers.set(key, registrations);
     return () => {
-        if (checkers.get(key) === checker) {
+        const current = checkers.get(key);
+        if (!current)
+            return;
+        const index = current.lastIndexOf(checker);
+        if (index >= 0)
+            current.splice(index, 1);
+        if (current.length === 0)
             checkers.delete(key);
-        }
     };
 }
 export function clearPlatformPermitCheckers() {
     checkers.clear();
-    registeredDefaultSceneCheckers.clear();
+    defaultSceneRegistrations.clear();
 }
 export function checkPlatformPermit(name, message) {
     const parsed = parsePlatformPermitName(name);
@@ -20,7 +27,8 @@ export function checkPlatformPermit(name, message) {
         return false;
     if (String(message.$adapter) !== parsed.adapter)
         return false;
-    const checker = checkers.get(parsed.adapter);
+    const registrations = checkers.get(parsed.adapter);
+    const checker = registrations?.[registrations.length - 1];
     if (!checker)
         return false;
     return checker(parsed.perm, message);
@@ -58,9 +66,26 @@ export function createSceneRolePlatformChecker() {
 /** 为适配器注册默认场景治理 platform checker（幂等） */
 export function registerDefaultScenePlatformPermitChecker(adapter) {
     const key = String(adapter);
-    if (registeredDefaultSceneCheckers.has(key)) {
-        return () => { };
+    const existing = defaultSceneRegistrations.get(key);
+    if (existing) {
+        existing.references += 1;
+        return () => releaseDefaultSceneChecker(key, existing);
     }
-    registeredDefaultSceneCheckers.add(key);
-    return registerPlatformPermitChecker(key, createSceneRolePlatformChecker());
+    const checker = createSceneRolePlatformChecker();
+    const registration = {
+        checker,
+        dispose: registerPlatformPermitChecker(key, checker),
+        references: 1,
+    };
+    defaultSceneRegistrations.set(key, registration);
+    return () => releaseDefaultSceneChecker(key, registration);
+}
+function releaseDefaultSceneChecker(key, registration) {
+    if (defaultSceneRegistrations.get(key) !== registration)
+        return;
+    registration.references -= 1;
+    if (registration.references > 0)
+        return;
+    defaultSceneRegistrations.delete(key);
+    registration.dispose();
 }

package/lib/built/schedule.d.ts

@@ -1,8 +1,7 @@
 /**
  * ScheduleFeature — 管理插件注册的内存定时任务
  */
-import { Feature, FeatureJSON, type ScheduleKind } from '@zhin.js/kernel';
-import type { HolidayInput, ScatterInput } from '@zhin.js/kernel';
+import { Feature, FeatureJSON, type ScheduleKind, type HolidayInput, type ScatterInput } from '@zhin.js/kernel';
 export interface ScheduleDescriptor {
     kind: ScheduleKind | 'every' | 'at';
     /** 6 段 cron（solar/lunar/workday/freeDay/holiday） */

package/lib/built/schedule.js

@@ -1,7 +1,7 @@
 /**
  * ScheduleFeature — 管理插件注册的内存定时任务
  */
-import { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine, } from '@zhin.js/kernel';
+import { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine } from '@zhin.js/kernel';
 function ensureEngine() {
     let engine = getScheduleEngine();
     if (!engine) {

package/lib/component.js

@@ -176,24 +176,41 @@ function parseAttributeValue(str, startIndex, context) {
 function evaluateQuotedExpression(quotedValue, context) {
     if (!context)
         return quotedValue;
-    // 处理引号内的表达式，将 {expr} 格式转换为 ${expr} 格式
-    let result = quotedValue;
-    const expressionRegex = /\{([^}]+)\}/g;
-    let match;
-    while ((match = expressionRegex.exec(quotedValue)) !== null) {
-        const expr = match[1];
+    let result = '';
+    let cursor = 0;
+    for (const match of readBraceExpressions(quotedValue)) {
+        result += quotedValue.slice(cursor, match.start);
         try {
-            const value = context.getValue(expr);
-            if (value !== undefined && value !== expr) {
+            const value = context.getValue(match.expr);
+            if (value !== undefined && value !== match.expr) {
                 const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
-                result = result.replace(match[0], stringValue);
+                result += stringValue;
+            }
+            else {
+                result += quotedValue.slice(match.start, match.end);
             }
         }
         catch (error) {
-            // 如果求值失败，保持原始表达式
+            result += quotedValue.slice(match.start, match.end);
         }
+        cursor = match.end;
     }
-    return result;
+    return result + quotedValue.slice(cursor);
+}
+function readBraceExpressions(value) {
+    const matches = [];
+    let cursor = 0;
+    while (cursor < value.length) {
+        const start = value.indexOf('{', cursor);
+        if (start < 0)
+            break;
+        const end = value.indexOf('}', start + 1);
+        if (end < 0)
+            break;
+        matches.push({ start, end: end + 1, expr: value.slice(start + 1, end) });
+        cursor = end + 1;
+    }
+    return matches;
 }
 /**
  * 解析表达式值

package/lib/index.d.ts

@@ -8,6 +8,7 @@ export * from './message.js';
 export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
+export * from './side-event/index.js';
 export * from './prompt.js';
 export * from './types.js';
 export * from './agent-prompt.js';

package/lib/index.js

@@ -9,6 +9,7 @@ export * from './message.js';
 export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
+export * from './side-event/index.js';
 export * from './prompt.js';
 export * from './types.js';
 export * from './agent-prompt.js';

package/lib/notice.d.ts

@@ -1,81 +1,38 @@
-import { Adapters } from './adapter.js';
-import type { MessageSender } from './types.js';
+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 { SideEventBase } from './side-event/base.js';
+export { composeSideEventName, formatSideEventName, matchesSideEventName, parseSideEventName, sideEventSendChannel, } from './side-event/base.js';
 /**
- * 通知类型枚举
- *
- * 常见 IM 通知事件分类：
- * - group_member_increase: 群成员增加（入群）
- * - group_member_decrease: 群成员减少（退群/被踢）
- * - group_admin_change:    群管理员变动
- * - group_ban:             群禁言
- * - group_recall:          群消息撤回
- * - friend_recall:         好友消息撤回
- * - friend_add:            新增好友
- * - group_poke:            群戳一戳
- * - friend_poke:           好友戳一戳
- * - group_transfer:        群转让
- * - endpoint.lifecycle:         Endpoint 连接/断开/错误（$subType: connect | disconnect | error）
- *
- * 适配器可自行扩展更多子类型
- */
-export type NoticeType = 'group_member_increase' | 'group_member_decrease' | 'group_admin_change' | 'group_ban' | 'group_recall' | 'friend_recall' | 'friend_add' | 'group_poke' | 'friend_poke' | 'group_transfer' | (string & {});
-/**
- * 通知频道信息
- */
-export interface NoticeChannel {
-    id: string;
-    type: 'group' | 'private' | 'channel';
-}
-/**
- * 通知基础结构
- *
- * 与 MessageBase 同构设计，所有通知共享以下字段。
- * 适配器通过 `Notice.from(raw, base)` 合并平台原始数据和标准字段。
+ * 通知基础结构 — 继承 SideEventBase。
  *
  * @example
  * ```typescript
- * // 适配器中格式化通知
  * const notice = Notice.from(rawEvent, {
  *   $id: rawEvent.id,
  *   $adapter: 'icqq',
  *   $endpoint: endpointId,
- *   $type: 'group_member_decrease',
- *   $subType: 'kick',
- *   $channel: { id: groupId, type: 'group' },
- *   $operator: { id: operatorId, name: '管理员' },
+ *   $type: 'notice',
+ *   $scene_id: groupId,
+ *   $scene_type: 'group',
+ *   $sub_type: 'member_decrease',
+ *   $actor: { id: operatorId, name: '管理员' },
  *   $target: { id: userId, name: '被踢者' },
  *   $timestamp: Date.now(),
  * });
+ * // formatSideEventName(notice) === 'notice.group.member_decrease'
  * this.adapter.emit('notice.receive', notice);
  * ```
  */
-export interface NoticeBase {
-    /** 通知唯一 ID（平台提供或自生成） */
-    $id: string;
-    /** 适配器名称 */
+export interface NoticeBase extends SideEventBase {
     $adapter: keyof Adapters;
-    /** Endpoint 名称 */
-    $endpoint: string;
-    /** 通知类型 */
-    $type: NoticeType;
-    /** 通知子类型（如 leave/kick、set/unset） */
-    $subType?: string;
-    /** 通知发生的频道/群/会话 */
-    $channel: NoticeChannel;
-    /** 操作者信息（如管理员） */
-    $operator?: MessageSender;
-    /** 被操作目标信息（如被踢的成员） */
-    $target?: MessageSender;
-    /** 通知时间戳 */
-    $timestamp: number;
+    $type: NoticeKind;
 }
 /**
  * 完整通知类型，支持平台原始数据扩展
  */
 export type Notice<T extends object = {}> = NoticeBase & T;
 export declare namespace Notice {
-    /**
-     * 工具方法：合并自定义字段与基础通知结构
-     */
     function from<T extends object>(input: T, format: NoticeBase): Notice<T>;
 }

package/lib/notice.js

@@ -1,8 +1,6 @@
+export { composeSideEventName, formatSideEventName, matchesSideEventName, parseSideEventName, sideEventSendChannel, } from './side-event/base.js';
 export var Notice;
 (function (Notice) {
-    /**
-     * 工具方法：合并自定义字段与基础通知结构
-     */
     function from(input, format) {
         return Object.assign(input, format);
     }

package/lib/plugin-runtime/im/contracts.d.ts

@@ -0,0 +1,71 @@
+import type { CapabilityId, PluginId } from '@zhin.js/plugin-runtime';
+declare const componentCallBrand: "zhin.component-call/1";
+declare const rawContentBrand: "zhin.raw-content/1";
+export interface ComponentCall<TProps = unknown> {
+    readonly $content: typeof componentCallBrand;
+    readonly name: string;
+    readonly props: TProps;
+}
+export interface RawContent<TPayload = unknown> {
+    readonly $content: typeof rawContentBrand;
+    readonly payload: TPayload;
+}
+export type SendContent = string | ComponentCall | RawContent | readonly SendContent[];
+export declare function component<TProps>(name: string, props: TProps): ComponentCall<TProps>;
+export declare function raw<TPayload>(payload: TPayload): RawContent<TPayload>;
+export declare function isComponentCall(value: SendContent): value is ComponentCall;
+export declare function isRawContent(value: SendContent): value is RawContent;
+export interface IncomingMessage {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly content: string;
+    readonly id?: string;
+    readonly sender?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface SendRequest {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly requester: PluginId;
+    readonly content: SendContent;
+    readonly parent?: ChannelParent;
+}
+/** Console 通道的来源场景（群临时会话 parent.group / QQ 子频道 parent.guild）。 */
+export interface ChannelParent {
+    readonly type?: string;
+    readonly id?: string;
+    readonly name?: string;
+}
+export interface OutboundEnvelope {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly requester: PluginId;
+    readonly generation: number;
+    readonly payload: unknown;
+    readonly parent?: ChannelParent;
+    replace(payload: unknown): void;
+}
+export interface MessageGateway {
+    receive(input: IncomingMessage): Promise<MessageDispatchResult>;
+    send(request: SendRequest): Promise<unknown>;
+}
+export interface MessageDispatchResult {
+    readonly matched: boolean;
+    readonly command?: string;
+    readonly owner?: PluginId;
+    readonly value?: unknown;
+}
+export declare class Message {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly content: string;
+    readonly generation: number;
+    readonly id?: string | undefined;
+    readonly sender?: string | undefined;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    constructor(adapter: CapabilityId, target: string, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<unknown>, id?: string | undefined, sender?: string | undefined, metadata?: Readonly<Record<string, unknown>>);
+    readonly $reply: (content: SendContent) => Promise<unknown>;
+    readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<unknown>;
+}
+export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;
+export {};