@zhin.js/core 1.1.33 → 1.1.35

package/README.md

@@ -1,71 +1,72 @@
 # @zhin.js/core
 
-Zhin.js IM 核心框架包，提供插件系统、Feature 架构、适配器、消息路由与出站发送链。**AI 编排（ZhinAgent、工具安全、MCP）在 [`@zhin.js/agent`](../agent/README.md)**；本包仅 selective re-export `@zhin.js/ai` 的 Provider / Agent 原语供插件直接使用。
+## Plugin Runtime 子路径
 
-领域词汇见 [CONTEXT.md](./CONTEXT.md)；入站/出站流程见 [消息如何流转](../../docs/essentials/message-flow.md)。
+新的 owner-aware IM 能力已经并入 Core，作为 Plugin Runtime 的正式领域接口：
 
-## 核心概念
+- `@zhin.js/core/runtime`
 
-### Plugin（插件）
+`@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 的基本组织单位。每个插件拥有独立的生命周期和上下文，通过 `usePlugin()` Hook 访问框架能力。
+Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、MessageDispatcher 与统一出站链。**AI 编排（ZhinAgent、工具安全、MCP）在 [`@zhin.js/agent`](../agent/README.md)**；本包仅 selective re-export `@zhin.js/ai` 的 Provider / Agent 原语供插件直接使用。
 
-```typescript
-import { usePlugin, MessageCommand } from '@zhin.js/core'
-
-const { addCommand, addTool, addCron, onMounted, onDispose } = usePlugin()
+领域词汇见 [CONTEXT.md](./CONTEXT.md)；入站/出站流程见 [消息如何流转](../../docs/essentials/message-flow.md)。
 
-onMounted(() => console.log('插件已挂载'))
-onDispose(() => console.log('插件已卸载'))
+## 核心概念
 
-addCommand(
-  new MessageCommand('hello <name:string>')
-    .desc('打招呼')
-    .action((_, result) => `Hello, ${result.params.name}!`)
-)
-```
+### Plugin（插件）— Plugin Runtime
 
-插件名称默认从文件路径推导，也可以显式声明：
+唯一启动路径：`zhin runtime start`。`plugin.ts` 必须 default-export `definePlugin()`；能力按约定目录发现。
 
 ```typescript
-// 方式 1: 导出 pluginName 常量
-export const pluginName = 'my-awesome-plugin'
-
-// 方式 2: 使用 definePlugin 声明式 API
-import { definePlugin } from '@zhin.js/core'
+// plugin.ts
+import { definePlugin } from '@zhin.js/plugin-runtime'
 
 export default definePlugin({
-  name: 'my-awesome-plugin',
-  setup(plugin) {
-    // 在这里使用 plugin 注册命令、工具等
+  name: 'hello-bot',
+  metadata: { displayName: 'Hello Bot' },
+  setup(context) {
+    context.lifecycle.add(() => { /* cleanup */ })
   },
 })
+```
+
+```typescript
+// commands/hello/[name].ts
+import { defineCommand } from '@zhin.js/command'
 
-// 方式 3: 手动设置
-const plugin = usePlugin()
-plugin.setName('my-awesome-plugin')
+export default defineCommand({
+  description: '打招呼',
+  params: {
+    name: { type: 'string' },
+  },
+  execute({ params }) {
+    return `Hello, ${params.name}!`
+  },
+})
 ```
 
+> **已移除**：`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`。
+
 ### Feature（特性抽象）
 
-Feature 是 Zhin.js 的核心扩展机制。所有内置功能均继承自 `Feature` 抽象基类，提供统一的注册/注销、插件归属追踪、JSON 序列化和变更事件通知能力。
+约定式 Feature（Command / Middleware / Component / Adapter…）由独立包提供 definition + 约定发现；Core Runtime 消费 snapshot。
+
+经典 `CommandFeature` / `addCommand` 等仍挂在 `Plugin.prototype`，**已 deprecated**，仅兼容 Agent init / game-kit：
 
 ```
-Feature (抽象基类)
-├── CommandFeature    — 消息命令       addCommand()
-├── ToolFeature       — AI 可调用工具   addTool()
-├── SkillFeature      — 技能记录       Agent 从 SKILL.md 注入
-├── CronFeature       — 定时任务       addCron()
-├── DatabaseFeature   — 数据模型       defineModel()
-├── ComponentFeature  — 消息组件       addComponent()
-├── ConfigFeature     — 插件配置       addConfig()
-└── PermissionFeature — 权限管理
+Feature (抽象基类) — legacy 注册表仍在
+├── CommandFeature    — MessageCommand（→ defineCommand）
+├── ToolFeature       — AI 工具（→ defineAgentTool）
+├── …
 ```
 
-每个 Feature 都会在 `Plugin.prototype` 上注入对应的扩展方法（如 `addCommand`、`addTool`），插件通过 `usePlugin()` 获取这些方法。
-
-Feature 支持变更事件监听，依赖方可实时响应 item 的增删：
-
 ```typescript
 const toolFeature = plugin.inject('tool')
 const off = toolFeature.on('add', (tool, pluginName) => {
@@ -76,6 +77,71 @@ toolFeature.on('remove', (tool) => {
 })
 ```
 
+### 出站消息段：`segment.html`
+
+业务插件可返回 **`html` 消息段**，由出站链统一处理转图或文本回退：
+
+```typescript
+import { segment } from '@zhin.js/core'
+
+return segment.html({
+  html: '<div>…</div>',  // 必填：Satori 可渲染的 HTML
+  text: undefined,        // 可选：显式回退文本（覆盖自动剥离）
+  width: 540,
+  backgroundColor: '#d8dce3',
+  fileName: 'card.png',
+})
+
+// Markdown 段（QQ 等平台 policy 为 origin 时透传）
+return segment.markdown('# Title\n\nBody')
+```
+
+出站富媒体段（`qrcode` / `html` / `markdown`）在 **`Adapter.renderSendMessage` 首步** 按各 Adapter 的 **`outboundRichSegmentPolicy`** 统一渲染为 `image` / `text` / `origin`：
+
+| 渲染模式 | 含义 |
+|---------|------|
+| `image` | 转为 `image` 段（qrcode 生成 PNG；html/markdown 经 `@zhin.js/html-renderer` 动态转图，未安装则降级 text） |
+| `text` | 剥离为纯文本段 |
+| `origin` | 原样透传，由 Endpoint 解释（如 QQ markdown、process 终端二维码） |
+
+默认策略：`qrcode: image`，`html: text`，`markdown: text`。QQ / KOOK 等适配器 override static policy。
+
+- 安装 **`@zhin.js/html-renderer`** 且 policy 为 `html: 'image'` 时，core 在首步动态 import 并转 PNG。
+- policy 为 `html: 'text'` 时等价于 **`coerceHtmlSegmentsToText`** / **`htmlToFallbackText`**。
+- 日志预览：`[html-card]`、`[qrcode]`、`[markdown]` + 摘要（前 80 字）。
+
+#### 扩展新 Rich Segment（长期方案）
+
+内置 kind 通过 **`richSegmentRegistry`** 注册；optional 能力通过 **`registerRichSegmentCapabilityLoader`** 注入（与 `@zhin.js/html-renderer` 同模式）。
+
+```typescript
+import {
+  RichSegment,
+  registerRichSegmentKind,
+  registerRichSegmentCapabilityLoader,
+  RICH_SEGMENT_MODE,
+  segment,
+} from '@zhin.js/core';
+
+// 1. 内置 capability：speech（@zhin.js/speech）已注册，tts kind 已内置
+// 可选：注册 ffmpeg 等
+registerRichSegmentCapabilityLoader('media-pipeline', async (opts) => {
+  const { createMediaPipeline } = await import('@zhin.js/media-pipeline');
+  return createMediaPipeline(opts.getConfig?.());
+});
+
+// 2. 使用内置 segment.tts（Adapter policy 决定 audio/text/origin）
+// segment.tts({ text: '你好' })
+class MyAdapter extends Adapter {
+  static override outboundRichSegmentPolicy = {
+    tts: 'audio',
+    qrcode: 'image', // 其余 kind 用 registry 默认值
+  };
+}
+```
+
+**分工**：Rich Segment 负责「语义段 → 标准 IM 段」；Endpoint `materializeOutboundMedia` 负责「已有 audio/video/file → 平台上传」。
+
 ### Adapter（适配器）
 
 适配器将不同聊天平台接入 Zhin.js，统一消息收发接口。
@@ -85,20 +151,20 @@ toolFeature.on('remove', (tool) => {
 Adapter.register('my-platform', MyAdapter)
 ```
 
-每个适配器可以通过 `addTool()` 注册平台特有工具，标准群管操作通过覆写 `IGroupManagement` 方法自动注册。
+每个适配器可以通过 `addTool()` 注册平台特有工具，标准群管操作通过覆写 `ISceneManagement` 方法自动注册。
 
-**群管理能力自动检测：** 适配器基类声明了 `IGroupManagement` 接口中的可选方法（`kickMember`、`muteMember`、`banMember` 等），子类只需覆写自己平台支持的方法，`start()` 会自动检测哪些方法已实现，生成对应的 Tool 并注册为"群聊管理"Skill。目前所有 9 个 IM 适配器（ICQQ、OneBot11、QQ 官方、Telegram、Discord、KOOK、Slack、钉钉、飞书）均已采用此模式：
+**群管理能力自动检测：** 适配器基类声明了 `ISceneManagement` 接口中的可选方法（`kickMember`、`muteMember`、`banMember` 等），子类只需覆写自己平台支持的方法，`start()` 会自动检测哪些方法已实现，生成对应的 Tool 并注册为"群聊管理"Skill。目前所有 9 个 IM 适配器（ICQQ、OneBot11、QQ 官方、Telegram、Discord、KOOK、Slack、钉钉、飞书）均已采用此模式：
 
 ```typescript
-class IcqqAdapter extends Adapter<IcqqBot> {
+class IcqqAdapter extends Adapter<IcqqEndpoint> {
   // 覆写标准群管方法
-  async kickMember(botId: string, sceneId: string, userId: string) {
-    const bot = this.bots.get(botId)
-    if (!bot) throw new Error(`Bot ${botId} 不存在`)
-    return bot.kickMember(Number(sceneId), Number(userId), false)
+  async kickMember(endpointId: string, sceneId: string, userId: string) {
+    const endpoint = this.endpoints.get(endpointId)
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`)
+    return endpoint.kickMember(Number(sceneId), Number(userId), false)
   }
-  async muteMember(botId: string, sceneId: string, userId: string, duration = 600) { /* ... */ }
-  async setAdmin(botId: string, sceneId: string, userId: string, enable = true) { /* ... */ }
+  async muteMember(endpointId: string, sceneId: string, userId: string, duration = 600) { /* ... */ }
+  async setAdmin(endpointId: string, sceneId: string, userId: string, enable = true) { /* ... */ }
   // ...共覆写 7 个标准方法
 
   async start() {
@@ -130,9 +196,9 @@ Core **不包含** ZhinAgent 实现。IM 侧的 AI 对话、工具收集、执
 
 | 类别 | 示例导出 |
 |------|----------|
-| Provider | `OpenAIProvider`、`OllamaProvider`、`AnthropicProvider` 等 |
-| Agent 原语 | `Agent`、`createAgent`、`ModelRegistry` |
-| 会话 / 上下文 | `SessionManager`（遗留）、`ContextRepository`、`ImTranscriptStore`、`ContextManager`、`ConversationMemory` |
+| Provider | `AIProvider` 接口、`createSdkProviderAdapter`（AI SDK 传输） |
+| Agent 原语 | `ModelRegistry`、`agentLoop` |
+| 会话 / 上下文 | `ConversationEventStore`（IM 事实）与 Agent 的 `ContextRepository`（模型会话） |
 | 压缩 / 限流 / 输出 | `compactSession`、`RateLimiter`、`parseOutput`、`CostTracker` |
 
 完整 Agent 能力与配置见 [`@zhin.js/agent`](../agent/README.md) 与 [AI 模块](https://zhin.js.org/advanced/ai)。
@@ -143,22 +209,35 @@ 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'
-export { CommandFeature, ToolFeature, SkillFeature, CronFeature, DatabaseFeature, ... } from './built/*.js'
+export { CommandFeature, ToolFeature, SkillFeature, ScheduleFeature, DatabaseFeature, ... } from './built/*.js'
 
 // 消息路由
 export { createMessageDispatcher } from './built/dispatcher.js'
 
-// 适配器与消息
-export { Adapter, Message, MessageCommand, Bot, ... } from './'
+// 适配器与消息（MessageCommand 已 deprecated）
+export { Adapter, Message, MessageCommand, Endpoint, segment, ... } from './'
+
+// 富媒体出站段
+export {
+  resolveRichSegments,
+  DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY,
+  QrcodeSegment,
+  HtmlSegment,
+  MarkdownSegment,
+} from './built/rich-segments/index.js'
+export type { RichSegmentKind, RichRenderMode, OutboundRichSegmentPolicy } from './built/rich-segments/types.js'
+
+// HTML 出站回退（legacy；policy html:'text' 时等价）
+export { htmlToFallbackText, coerceHtmlSegmentsToText, registerHtmlSegmentFallback } from './built/*.js'
 
 // AI 原语（来自 @zhin.js/ai，非 ZhinAgent）
 export {
-  OpenAIProvider, OllamaProvider, Agent, createAgent, ModelRegistry,
-  SessionManager, ContextManager, ConversationMemory, compactSession, ...
+  AIProvider, createSdkProviderAdapter, ModelRegistry,
+  ContextRepository, ContextManager, compactSession, ...
 } from '@zhin.js/ai'
 ```
 

package/lib/adapter.d.ts

@@ -1,44 +1,73 @@
-import { Bot } from "./bot.js";
+import { Endpoint } from "./endpoint.js";
+import { DEFAULT_ENDPOINT_CAPABILITIES, type EndpointCapability } from "./endpoint-capabilities.js";
+import type { EndpointManager } from "./built/endpoint-manager.js";
 import { Plugin } from "./plugin.js";
 import { EventEmitter } from "node:events";
 import { Message } from "./message.js";
 import { Notice } from "./notice.js";
 import { Request } from "./request.js";
-import { SendOptions } from "./types.js";
+import { EditMessageOptions, SendOptions } from "./types.js";
+import { type OutboundRichSegmentPolicy } from "./built/rich-segments/index.js";
+import { type InteractivePolicy } from "./built/interactive-segments/index.js";
+import { type AiOutboundCapabilities, type AiOutboundExtensionDefinition } from "./built/ai-outbound/index.js";
+import type { Schema } from '@zhin.js/schema';
 /**
  * Adapter类：适配器抽象，管理多平台Bot实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
  *
  * 适配器可以提供 AI 工具，供 AI 服务调用。
  */
-export declare abstract class Adapter<R extends Bot = Bot> extends EventEmitter<Adapter.Lifecycle> {
+export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps extends readonly EndpointCapability[] = typeof DEFAULT_ENDPOINT_CAPABILITIES> extends EventEmitter<Adapter.Lifecycle> {
     #private;
     plugin: Plugin;
     name: keyof Plugin.Contexts;
-    config: Adapter.BotConfig<R>[];
-    /** 当前适配器下所有Bot实例，key为bot名称 */
-    bots: Map<string, R>;
+    config: Adapter.EndpointConfig<R>[];
+    endpoints: Map<string, R>;
+    private recallMessageHandler;
+    /** Adapter 支持的能力上限（子类覆盖） */
+    static readonly capabilities: readonly EndpointCapability[];
+    /** 出站富媒体段渲染策略（子类 override static） */
+    static outboundRichSegmentPolicy: OutboundRichSegmentPolicy;
+    /** 交互段出站策略：native 保留按钮段，text 降级为编号文本 */
+    static interactivePolicy: InteractivePolicy;
+    /** AI 结构化出站能力声明（mentions / richSegments / interactive） */
+    static aiOutboundCapabilities: AiOutboundCapabilities;
+    /** 平台特有 extensions schema + 解析（对齐各 SDK 文档子集） */
+    static aiOutboundExtensions?: readonly AiOutboundExtensionDefinition[];
+    protected getInteractivePolicy(): InteractivePolicy;
     /** 并发上限，0 表示不限制（默认） */
     static DEFAULT_MAX_CONCURRENT_MESSAGES: number;
     get maxConcurrentMessages(): number;
     /** 当前正在处理的消息数 */
     get pendingMessages(): number;
     /**
-     * 构造函数
+     * 创建一个适配器运行实例。
+     * @param plugin 拥有该适配器的插件实例
      * @param name 适配器名称（如 'process'、'qq' 等）
-     * @param botFactory Bot工厂函数或构造器
+     * @param config Endpoint 配置列表
      */
-    constructor(plugin: Plugin, name: keyof Plugin.Contexts, config: Adapter.BotConfig<R>[]);
+    constructor(plugin: Plugin, name: keyof Plugin.Contexts, config: Adapter.EndpointConfig<R>[]);
+    /** 入站消息管线（替代 emit override 的隐式管线） */
+    private inboundPipeline;
     /**
-     * 重写 emit：拦截 message.receive 事件，按架构规定的入站流程处理
-     * 入站消息链：adapter.emit → dispatcher.dispatch → plugin.dispatch('message.receive') → adapter observers
-     *
-     * 以属性 + `EventEmitter.prototype.emit` 调用满足 Node @types 25 对泛型 `emit` 的可赋值检查。
+     * 重写 emit：拦截 message.receive/notice.receive/request.receive 事件，
+     * 将入站处理委托给 InboundMessagePipeline。
      */
     emit: EventEmitter<Adapter.Lifecycle>['emit'];
-    abstract createBot(config: Adapter.BotConfig<R>): R;
+    abstract createEndpoint(config: Adapter.EndpointConfig<R>): R;
     get logger(): import("@zhin.js/logger").Logger;
     binding(plugin: Plugin): void;
+    /**
+     * 同步等待入站管线结束（middleware → dispatcher → 生命周期 → 观察者）。
+     * 用于 QQ 等需在被动回复完成后再 ack 交互的平台事件。
+     */
+    receiveMessageAwait(message: Message): Promise<boolean>;
+    /** 运行时 Endpoint 管理（add/remove/edit/start/stop）；未实现则 core 尝试 endpointConfigSchema 通用向导 */
+    getEndpointManager?(): EndpointManager | null;
+    /** 通用 schema 驱动 add/edit 时的字段定义 */
+    getEndpointConfigSchema?(): Schema | undefined;
+    /** 热连接失败时是否建议重启进程 */
+    getEndpointNeedsRestart?(): boolean;
     /**
      * 出站富媒体能力（Publisher 按此过滤/降级；各 adapter 可覆盖）。
      */
@@ -49,20 +78,41 @@ export declare abstract class Adapter<R extends Bot = Bot> extends EventEmitter<
         file?: boolean;
         maxAttachmentBytes?: number;
     };
-    private renderSendMessage;
+    protected getOutboundRichSegmentPolicy(): OutboundRichSegmentPolicy;
+    /**
+     * 出站两阶段：
+     * 1. resolveRichSegments — 语义段 → 标准 IM 段（image/audio/text）
+     * 2. Endpoint materializeOutboundMedia — base64/本地路径 → 平台 URL（各 adapter 可选）
+     * @see docs/essentials/rich-segment-adapters.md
+     */
+    protected renderSendMessage(options: SendOptions): Promise<SendOptions>;
     sendMessage(options: SendOptions): Promise<string>;
+    /**
+     * `call.recallMessage` 事件链（prompt.ts 超时撤回等）的统一出口：
+     * 经 canonical `EndpointControl` 端口撤回。
+     */
+    private recallEndpointMessage;
+    /**
+     * 编辑已发送的消息。
+     * - 如果 Endpoint 的 control 端口实现了 edit，调用平台编辑 API
+     * - 否则 fallback 到发送新消息
+     * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
+     */
+    editMessage(options: EditMessageOptions): Promise<string>;
     start(): Promise<void>;
     /**
-     * 停止适配器，断开并移除所有Bot实例
-     * @param plugin 所属插件实例
+     * 停止适配器，断开并移除所有 Endpoint 实例
      */
     stop(): Promise<void>;
 }
 export interface Adapters {
 }
+/** Per-adapter live Endpoint class map for HandlerContext.$endpoint() typing. */
+export interface AdapterEndpoints {
+}
 export declare namespace Adapter {
     type Factory<R extends Adapter = Adapter> = {
-        new (plugin: Plugin, name: string, config: Adapter.BotConfig<Adapter.InferBot<R>>[]): R;
+        new (plugin: Plugin, name: string, config: Adapter.EndpointConfig<Adapter.InferEndpoint<R>>[]): R;
     };
     interface Lifecycle {
         'message.receive': [Message];
@@ -77,10 +127,10 @@ export declare namespace Adapter {
      * 适配器工厂注册表
      * 灵感来源于 zhinjs/next 的 Adapter.Registry
      */
-    const Registry: Map<string, Factory<Adapter<Bot<{}, {}>>>>;
-    type InferBot<R extends Adapter = Adapter> = R extends Adapter<infer T> ? T : never;
-    type BotConfig<T extends Bot> = T extends Bot<infer R> ? R : never;
-    type BotMessage<T extends Bot> = T extends Bot<infer _L, infer R> ? R : never;
+    const Registry: Map<string, Factory<Adapter<Endpoint, readonly EndpointCapability[]>>>;
+    type InferEndpoint<R extends Adapter = Adapter> = R extends Adapter<infer T> ? T : never;
+    type EndpointConfig<T extends Endpoint> = T extends Endpoint<infer R> ? R : never;
+    type EndpointMessage<T extends Endpoint> = T extends Endpoint<infer _L, infer R> ? R : never;
     /**
      * 注册适配器工厂
      *
@@ -93,4 +143,3 @@ export declare namespace Adapter {
      */
     function register(name: string, factory: Factory): void;
 }
-//# sourceMappingURL=adapter.d.ts.map