@zhin.js/core 1.3.5 → 1.4.1

package/README.md

@@ -18,66 +18,52 @@ Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、Message
 
 ## 核心概念
 
-### Plugin（插件）
+### Plugin（插件）— Plugin Runtime
 
-插件是 Zhin.js 的基本组织单位。每个插件拥有独立的生命周期和上下文，通过 `usePlugin()` Hook 访问框架能力。
+唯一启动路径：`zhin runtime start`。`plugin.ts` 必须 default-export `definePlugin()`；能力按约定目录发现。
 
 ```typescript
-import { usePlugin, MessageCommand } from '@zhin.js/core'
+// plugin.ts
+import { definePlugin } from '@zhin.js/plugin-runtime'
 
-const { addCommand, addTool, addSchedule, onMounted, onDispose } = usePlugin()
-
-onMounted(() => console.log('插件已挂载'))
-onDispose(() => console.log('插件已卸载'))
-
-addCommand(
-  new MessageCommand('hello <name:word>')
-    .desc('打招呼')
-    .action((_, result) => `Hello, ${result.params.name}!`)
-)
+export default definePlugin({
+  name: 'hello-bot',
+  metadata: { displayName: 'Hello Bot' },
+  setup(context) {
+    context.lifecycle.add(() => { /* cleanup */ })
+  },
+})
 ```
 
-插件名称默认从文件路径推导，也可以显式声明：
-
 ```typescript
-// 方式 1: 导出 pluginName 常量
-export const pluginName = 'my-awesome-plugin'
-
-// 方式 2: 使用 definePlugin 声明式 API
-import { definePlugin } from '@zhin.js/core'
+// commands/hello/[name:string].ts
+import { defineCommand } from '@zhin.js/command'
 
-export default definePlugin({
-  name: 'my-awesome-plugin',
-  setup(plugin) {
-    // 在这里使用 plugin 注册命令、工具等
+export default defineCommand({
+  description: '打招呼',
+  execute({ params }) {
+    return `Hello, ${params.name}!`
   },
 })
-
-// 方式 3: 手动设置
-const plugin = usePlugin()
-plugin.setName('my-awesome-plugin')
 ```
 
+> **已弃用**：`usePlugin()` / `MessageCommand` / `Plugin.addCommand` 仅经典路径（`zhin.js/node`）残留，新代码勿用。见 [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 注入
-├── ScheduleFeature   — 调度任务       addSchedule()
-├── 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) => {
@@ -229,7 +215,7 @@ export { CommandFeature, ToolFeature, SkillFeature, ScheduleFeature, DatabaseFea
 // 消息路由
 export { createMessageDispatcher } from './built/dispatcher.js'
 
-// 适配器与消息
+// 适配器与消息（MessageCommand 已 deprecated）
 export { Adapter, Message, MessageCommand, Endpoint, segment, ... } from './'
 
 // 富媒体出站段

package/lib/adapter.js

@@ -3,7 +3,7 @@ import { connectEndpointInstance, disconnectEndpointInstance } from "./built/con
 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, resolveInteractiveSegments, } from "./built/interactive-segments/index.js";
+import { DEFAULT_INTERACTIVE_POLICY, collectKeyboardFallbackMaps, keyboardFallbackStore, resolveInteractiveSegments, } 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";
@@ -77,7 +77,11 @@ export class Adapter extends EventEmitter {
             logger: this.logger,
             getMaxConcurrentMessages: () => this.maxConcurrentMessages,
             getPendingMessages: () => this.#pendingMessages,
-            decrementPending: () => { this.#pendingMessages--; },
+            decrementPending: () => {
+                // stop() may zero the counter while in-flight receives still finish;
+                // never let the budget go negative.
+                this.#pendingMessages = Math.max(0, this.#pendingMessages - 1);
+            },
         });
     }
     /** 入站消息管线（替代 emit override 的隐式管线） */
@@ -166,6 +170,14 @@ export class Adapter extends EventEmitter {
                     },
                 })),
             };
+            // 'text' 策略端点：keyboard 即将降级为编号文本，先把有效 fallback
+            // 映射写入中央存储（频道键与入站回跳解析一致），供数字回跳路由。
+            if (this.getInteractivePolicy() === 'text') {
+                const channelKey = `${this.name}-${options.endpoint}-${options.type}:${options.id}`;
+                for (const map of collectKeyboardFallbackMaps(options.content)) {
+                    keyboardFallbackStore.remember(channelKey, map);
+                }
+            }
             options = {
                 ...options,
                 content: resolveInteractiveSegments(options.content, this.getInteractivePolicy()),
@@ -291,6 +303,9 @@ export class Adapter extends EventEmitter {
         }
         // 无论是否有错误，始终完成清理
         this.endpoints.clear();
+        // Drop in-flight concurrency counter so a subsequent start() does not
+        // inherit a stale backpressure budget from the previous generation.
+        this.#pendingMessages = 0;
         // 从 adapters 数组中移除（可能因重复 start 出现多条同名，需全部删掉）
         const rootAdapters = this.plugin.root.adapters;
         for (let i = rootAdapters.length - 1; i >= 0; i--) {

package/lib/built/command.d.ts

@@ -15,7 +15,7 @@ import type { RegisteredAdapter, AdapterMessage } from "../types.js";
  * CommandContext 扩展方法类型
  */
 export interface CommandContextExtensions {
-    /** 添加命令 */
+    /** @deprecated 使用 `defineCommand` + `commands/`；勿在新代码调用。 */
     addCommand<T extends RegisteredAdapter>(command: MessageCommand<T>): () => void;
 }
 declare module "../plugin.js" {
@@ -28,7 +28,10 @@ declare module "../plugin.js" {
     }
 }
 /**
- * 命令服务 Feature
+ * 命令服务 Feature（经典 MessageCommand 注册表）。
+ *
+ * @deprecated 新命令走 `@zhin.js/command` 的 `defineCommand` + 约定目录发现。
+ * 本 Feature 仍服务 Agent / game-kit / legacy Plugin.addCommand。
  */
 export declare class CommandFeature extends Feature<MessageCommand<RegisteredAdapter>> {
     readonly name: "command";

package/lib/built/command.js

@@ -20,7 +20,10 @@ export function compareCommandPatterns(a, b) {
     return tokB - tokA;
 }
 /**
- * 命令服务 Feature
+ * 命令服务 Feature（经典 MessageCommand 注册表）。
+ *
+ * @deprecated 新命令走 `@zhin.js/command` 的 `defineCommand` + 约定目录发现。
+ * 本 Feature 仍服务 Agent / game-kit / legacy Plugin.addCommand。
  */
 export class CommandFeature extends Feature {
     name = 'command';

package/lib/built/interactive-segments/fallback-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * keyboard 文本降级 fallback map 的中央存储。
+ *
+ * 出站：端点 interactive 策略为 'text' 时，框架把 keyboard 段降级为编号文本，
+ * 同时把「数字 → payload」映射按频道写入本存储（后写覆盖先写，等价
+ * game-kit lastMenus 的“最近一张键盘”语义）。
+ * 入站：框架中间件 / dispatcher 钩子用本存储把用户回复的裸数字解析回
+ * payload，再按 prefix 最长匹配路由给注册的 interactive handler。
+ *
+ * 模块级共享实例与 handlers.ts 的 handler 注册表同例：状态按频道键控、
+ * TTL 有界（对齐 game-hub 菜单上下文的 1h），无裸悬挂业务对象。
+ */
+export declare const KEYBOARD_FALLBACK_TTL_MS: number;
+export declare class KeyboardFallbackStore {
+    #private;
+    private readonly defaultTtlMs;
+    constructor(defaultTtlMs?: number);
+    /** 记录频道最近一次 keyboard 降级的数字→payload 映射（空 map 忽略）。 */
+    remember(channelKey: string, map: Record<string, string>, ttlMs?: number): void;
+    /** 频道当前有效的 fallback map（过期即删并返回 undefined）。 */
+    mapFor(channelKey: string): Record<string, string> | undefined;
+    /** 裸数字 / fallback 键 → payload（无映射或过期返回 undefined）。 */
+    resolve(channelKey: string, raw: string): string | undefined;
+    clear(): void;
+}
+/** 中央共享实例：出站降级写入、入站回跳读取。 */
+export declare const keyboardFallbackStore: KeyboardFallbackStore;
+/** 测试专用：清空中央 fallback 存储。 */
+export declare function resetKeyboardFallbackStoreForTests(): void;

package/lib/built/interactive-segments/fallback-store.js

@@ -0,0 +1,63 @@
+import { resolveTextFallbackPayload } from './action.js';
+/**
+ * keyboard 文本降级 fallback map 的中央存储。
+ *
+ * 出站：端点 interactive 策略为 'text' 时，框架把 keyboard 段降级为编号文本，
+ * 同时把「数字 → payload」映射按频道写入本存储（后写覆盖先写，等价
+ * game-kit lastMenus 的“最近一张键盘”语义）。
+ * 入站：框架中间件 / dispatcher 钩子用本存储把用户回复的裸数字解析回
+ * payload，再按 prefix 最长匹配路由给注册的 interactive handler。
+ *
+ * 模块级共享实例与 handlers.ts 的 handler 注册表同例：状态按频道键控、
+ * TTL 有界（对齐 game-hub 菜单上下文的 1h），无裸悬挂业务对象。
+ */
+export const KEYBOARD_FALLBACK_TTL_MS = 60 * 60 * 1000;
+export class KeyboardFallbackStore {
+    defaultTtlMs;
+    #entries = new Map();
+    constructor(defaultTtlMs = KEYBOARD_FALLBACK_TTL_MS) {
+        this.defaultTtlMs = defaultTtlMs;
+    }
+    /** 记录频道最近一次 keyboard 降级的数字→payload 映射（空 map 忽略）。 */
+    remember(channelKey, map, ttlMs = this.defaultTtlMs) {
+        if (Object.keys(map).length === 0)
+            return;
+        this.#prune();
+        this.#entries.set(channelKey, {
+            map: Object.freeze({ ...map }),
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    /** 频道当前有效的 fallback map（过期即删并返回 undefined）。 */
+    mapFor(channelKey) {
+        const entry = this.#entries.get(channelKey);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt < Date.now()) {
+            this.#entries.delete(channelKey);
+            return undefined;
+        }
+        return entry.map;
+    }
+    /** 裸数字 / fallback 键 → payload（无映射或过期返回 undefined）。 */
+    resolve(channelKey, raw) {
+        const map = this.mapFor(channelKey);
+        return map ? resolveTextFallbackPayload(raw, map) : undefined;
+    }
+    clear() {
+        this.#entries.clear();
+    }
+    #prune() {
+        const now = Date.now();
+        for (const [key, entry] of this.#entries) {
+            if (entry.expiresAt < now)
+                this.#entries.delete(key);
+        }
+    }
+}
+/** 中央共享实例：出站降级写入、入站回跳读取。 */
+export const keyboardFallbackStore = new KeyboardFallbackStore();
+/** 测试专用：清空中央 fallback 存储。 */
+export function resetKeyboardFallbackStoreForTests() {
+    keyboardFallbackStore.clear();
+}

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

@@ -1,6 +1,13 @@
 import type { Message } from '../../message.js';
 import type { MessageMiddleware } from '../../types.js';
 import type { InteractiveHandler, RegisteredInteractiveHandler } from './types.js';
+/** 旧轨频道键：与出站降级（Adapter.renderSendMessage）及 game-kit channelKey 一致。 */
+export declare function interactiveChannelKey(message: Message<any>): string;
+/**
+ * 文本回跳解析：中央 fallback map（裸数字）→ payload；
+ * 或 QQ 指令预填等直出 `prefix:session:id` payload。
+ */
+export declare function resolveInboundTextPayload(message: Message<any>): string | undefined;
 export declare function registerInteractiveHandler(prefix: string, handler: InteractiveHandler): () => void;
 export declare function getInteractiveHandlers(): readonly RegisteredInteractiveHandler[];
 export declare function resetInteractiveHandlersForTests(): void;

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

@@ -1,4 +1,5 @@
-import { getActionFromMessage } from './action.js';
+import { getActionFromMessage, resolvePayloadFromText } from './action.js';
+import { keyboardFallbackStore } from './fallback-store.js';
 const handlers = [];
 let middlewareInstalled = false;
 function findHandler(payload) {
@@ -12,6 +13,20 @@ function findHandler(payload) {
     }
     return match?.handler;
 }
+/** 旧轨频道键：与出站降级（Adapter.renderSendMessage）及 game-kit channelKey 一致。 */
+export function interactiveChannelKey(message) {
+    return `${String(message.$adapter)}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+}
+/**
+ * 文本回跳解析：中央 fallback map（裸数字）→ payload；
+ * 或 QQ 指令预填等直出 `prefix:session:id` payload。
+ */
+export function resolveInboundTextPayload(message) {
+    const raw = message.$raw?.trim() ?? '';
+    if (!raw)
+        return undefined;
+    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(interactiveChannelKey(message)));
+}
 export function registerInteractiveHandler(prefix, handler) {
     const entry = { prefix, handler };
     handlers.push(entry);
@@ -35,10 +50,11 @@ export function ensureInteractiveMiddleware(addMiddleware) {
         return;
     middlewareInstalled = true;
     addMiddleware(async (message, next) => {
-        const action = getActionFromMessage(message);
-        if (!action)
+        const payload = getActionFromMessage(message)?.payload
+            ?? resolveInboundTextPayload(message);
+        if (!payload)
             return next();
-        const handler = findHandler(action.payload);
+        const handler = findHandler(payload);
         if (!handler)
             return next();
         const handled = await handler(message);

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

@@ -3,5 +3,6 @@ export * from './button-spec.js';
 export * from './action.js';
 export * from './resolve.js';
 export * from './handlers.js';
+export * from './fallback-store.js';
 export { KeyboardSegment, InteractiveSegment } from './keyboard-segment.js';
 export * from './onebot-keyboard.js';

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

@@ -3,5 +3,6 @@ export * from './button-spec.js';
 export * from './action.js';
 export * from './resolve.js';
 export * from './handlers.js';
+export * from './fallback-store.js';
 export { KeyboardSegment, InteractiveSegment } from './keyboard-segment.js';
 export * from './onebot-keyboard.js';

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

@@ -1,5 +1,14 @@
 import type { SendContent } from '../../types.js';
-import { type InteractivePolicy } from './types.js';
+import { type InteractivePolicy, type KeyboardSegmentData } from './types.js';
+/**
+ * keyboard 的有效 fallback 映射：显式 `fallback.map` 优先；否则按按钮顺序
+ * 自动编号（与 {@link renderKeyboardAsText} 的自动编号一致，含 disabled 按钮）。
+ */
+export declare function effectiveKeyboardFallbackMap(data: KeyboardSegmentData): Record<string, string>;
+/** 收集 content 中所有 keyboard 段的有效 fallback 映射（文本降级前调用）。 */
+export declare function collectKeyboardFallbackMaps(content: SendContent | undefined): Record<string, string>[];
+/** keyboard 段 → 编号文本（'text' 策略端点的中央降级渲染）。 */
+export declare function renderKeyboardAsText(data: KeyboardSegmentData): string;
 export declare function hasKeyboardSegment(content: SendContent | undefined): boolean;
 /** @deprecated 使用 {@link hasKeyboardSegment} */
 export declare const hasInteractiveSegment: typeof hasKeyboardSegment;

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

@@ -21,7 +21,36 @@ function packSegments(out) {
         return out[0];
     return out;
 }
-function renderKeyboardAsText(data) {
+/**
+ * keyboard 的有效 fallback 映射：显式 `fallback.map` 优先；否则按按钮顺序
+ * 自动编号（与 {@link renderKeyboardAsText} 的自动编号一致，含 disabled 按钮）。
+ */
+export function effectiveKeyboardFallbackMap(data) {
+    const map = data.fallback?.map ?? {};
+    if (Object.keys(map).length > 0)
+        return { ...map };
+    const out = {};
+    data.rows.flat().forEach((btn, idx) => {
+        out[String(idx + 1)] = btn.payload;
+    });
+    return out;
+}
+/** 收集 content 中所有 keyboard 段的有效 fallback 映射（文本降级前调用）。 */
+export function collectKeyboardFallbackMaps(content) {
+    if (content == null)
+        return [];
+    const maps = [];
+    for (const item of asArray(content)) {
+        if (typeof item === 'string')
+            continue;
+        const data = asKeyboardData(item);
+        if (data)
+            maps.push(effectiveKeyboardFallbackMap(data));
+    }
+    return maps;
+}
+/** keyboard 段 → 编号文本（'text' 策略端点的中央降级渲染）。 */
+export function renderKeyboardAsText(data) {
     const lines = [];
     const flat = data.rows.flat();
     if (data.fallback?.hint) {

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

@@ -7,9 +7,12 @@
  *
  * 事件：
  *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
 import type { Plugin } from '../plugin.js';
 export type LoginAssistType = 'qrcode' | 'sms' | 'slider' | 'device' | 'auth' | 'other';
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export declare const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS: number;
 export interface PendingLoginTaskPayload {
     /** 说明文案（如「请扫码登录」） */
     message?: string;
@@ -27,16 +30,30 @@ export interface PendingLoginTask {
     type: LoginAssistType;
     payload: PendingLoginTaskPayload;
     createdAt: number;
+    /** 到期时间戳（ms）；无超时则为 undefined */
+    expiresAt?: number;
+}
+export interface WaitForInputOptions {
+    /**
+     * 超时毫秒。默认 {@link DEFAULT_LOGIN_ASSIST_TIMEOUT_MS}。
+     * 传 `0` / `Infinity` / 负数表示不超时（仅测试或显式长驻场景）。
+     */
+    timeoutMs?: number;
 }
 export declare class LoginAssist {
     private readonly plugin;
     private readonly pending;
     private idSeq;
-    constructor(plugin: Plugin);
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    private readonly defaultTimeoutMs;
+    constructor(plugin: Plugin, options?: {
+        defaultTimeoutMs?: number;
+    });
     /**
      * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
      */
-    waitForInput(adapter: string, endpointId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload): Promise<string | Record<string, unknown>>;
+    waitForInput(adapter: string, endpointId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload, options?: WaitForInputOptions): Promise<string | Record<string, unknown>>;
     /**
      * 消费者：提交结果，对应 waitForInput 的 Promise 会 resolve。
      */

package/lib/built/login-assist.js

@@ -7,7 +7,10 @@
  *
  * 事件：
  *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS = 5 * 60 * 1000;
 // ============================================================================
 // LoginAssist 服务
 // ============================================================================
@@ -15,24 +18,48 @@ export class LoginAssist {
     plugin;
     pending = new Map();
     idSeq = 0;
-    constructor(plugin) {
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    defaultTimeoutMs;
+    constructor(plugin, options) {
         this.plugin = plugin;
+        this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_LOGIN_ASSIST_TIMEOUT_MS;
     }
     /**
      * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
      */
-    waitForInput(adapter, endpointId, type, payload = {}) {
+    waitForInput(adapter, endpointId, type, payload = {}, options) {
         const id = `login-${Date.now()}-${++this.idSeq}`;
+        const timeoutMs = resolveTimeoutMs(options?.timeoutMs, this.defaultTimeoutMs);
+        const createdAt = Date.now();
         const task = {
             id,
             adapter,
             endpointId,
             type,
             payload: { message: payload.message ?? '', ...payload },
-            createdAt: Date.now(),
+            createdAt,
+            ...(timeoutMs != null ? { expiresAt: createdAt + timeoutMs } : {}),
         };
         const promise = new Promise((resolve, reject) => {
-            this.pending.set(id, { task, resolve, reject });
+            const entry = { task, resolve, reject };
+            if (timeoutMs != null) {
+                entry.timer = setTimeout(() => {
+                    if (!this.pending.has(id))
+                        return;
+                    this.pending.delete(id);
+                    try {
+                        this.plugin.emit('endpoint.login.expired', task);
+                    }
+                    catch {
+                        /* observer failure must not leave the producer hanging forever */
+                    }
+                    reject(new Error(`LoginAssist task timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                // Node: 不阻止进程退出
+                entry.timer.unref?.();
+            }
+            this.pending.set(id, entry);
             this.plugin.emit('endpoint.login.pending', task);
         });
         return promise;
@@ -45,6 +72,8 @@ export class LoginAssist {
         if (!entry)
             return false;
         this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
         entry.resolve(value);
         return true;
     }
@@ -56,6 +85,8 @@ export class LoginAssist {
         if (!entry)
             return false;
         this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
         entry.reject(new Error(reason));
         return true;
     }
@@ -67,8 +98,16 @@ export class LoginAssist {
     }
     dispose() {
         for (const [, entry] of this.pending) {
+            if (entry.timer)
+                clearTimeout(entry.timer);
             entry.reject(new Error('LoginAssist disposed'));
         }
         this.pending.clear();
     }
 }
+function resolveTimeoutMs(explicit, fallback) {
+    const raw = explicit === undefined ? fallback : explicit;
+    if (!Number.isFinite(raw) || raw <= 0)
+        return undefined;
+    return raw;
+}

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

@@ -1,8 +1,10 @@
 export type { Segment, SegmentBase, MediaRef, TextSegment, MentionSegment, ImageSegment, ReplySegment, ForwardSegment, FaceSegment, DiceSegment, RpsSegment, } from './types.js';
 export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
 export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
 export { segmentsForImDelivery } from './delivery.js';
-export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
+export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields, collectSegmentMedia, type SegmentMediaRef, } from './media.js';
 export { createImageSegment } from './image.js';
 export { formatSegmentPreview } from './preview.js';
+export { segmentsToPlainText } from './text.js';
 export { readMentionTarget, readMentionName, readMentionSegmentTarget } from './mention.js';

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

@@ -1,7 +1,9 @@
 export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
 export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
 export { segmentsForImDelivery } from './delivery.js';
-export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
+export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields, collectSegmentMedia, } from './media.js';
 export { createImageSegment } from './image.js';
 export { formatSegmentPreview } from './preview.js';
+export { segmentsToPlainText } from './text.js';
 export { readMentionTarget, readMentionName, readMentionSegmentTarget } from './mention.js';

package/lib/built/segment-contract/json-schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+type JsonSchemaObject = Record<string, unknown>;
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export declare const mediaRefJsonSchema: JsonSchemaObject;
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export declare const STRICT_OUTBOUND_SEGMENT_TYPES: readonly ["text", "mention", "image", "reply", "forward", "face", "dice", "rps"];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export declare const outboundSegmentJsonSchema: JsonSchemaObject;
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export declare const aiOutboundJsonSchema: JsonSchemaObject;
+export {};