@zhin.js/core 1.4.0 → 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";
@@ -170,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()),

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/segment-contract/index.d.ts

@@ -3,7 +3,8 @@ export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSc
 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

@@ -2,7 +2,8 @@ export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSc
 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.js

@@ -20,8 +20,8 @@ export const mediaRefJsonSchema = {
     properties: {
         kind: {
             type: 'string',
-            enum: ['url', 'path', 'base64'],
-            description: 'url=http(s) 链接；path=本地文件路径；base64=内联 base64 数据',
+            enum: ['url', 'path', 'base64', 'file'],
+            description: 'url=http(s) 链接；path=本地文件路径；base64=内联 base64 数据；file=平台不透明文件引用（如 Telegram file_id）',
         },
         value: { type: 'string', description: '媒体内容：URL / 文件路径 / 纯 base64' },
         mime_type: { type: 'string', description: '如 image/png、audio/mpeg' },

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

@@ -1,4 +1,4 @@
-import type { MediaRef } from './types.js';
+import type { MediaRef, Segment } from './types.js';
 import { isMediaRef } from './validate.js';
 export { isMediaRef };
 export declare function mediaRefFromLegacyData(data: Record<string, unknown>): MediaRef | undefined;
@@ -6,3 +6,13 @@ export declare function mediaRefToLegacyFields(media: MediaRef): {
     url?: string;
     file?: string;
 };
+export interface SegmentMediaRef {
+    readonly type: string;
+    readonly media: MediaRef;
+}
+/**
+ * 从入站 canonical 段收集媒体引用（image / audio / video / file）。
+ * 兼容 canonical `data.media` 与旧轨 url/file/base64 字段；
+ * 无媒体段时返回空数组（调用方无需特判 undefined）。
+ */
+export declare function collectSegmentMedia(segments: readonly Segment[] | undefined): SegmentMediaRef[];

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

@@ -5,6 +5,13 @@ export function mediaRefFromLegacyData(data) {
         return data.media;
     }
     const mimeType = typeof data.mime_type === 'string' ? data.mime_type : undefined;
+    // 平台不透明文件引用（Telegram file_id / Milky resource_id 等）
+    const fileRef = typeof data.file_id === 'string' && data.file_id.trim()
+        ? data.file_id.trim()
+        : undefined;
+    if (fileRef) {
+        return { kind: 'file', value: fileRef, ...(mimeType ? { mime_type: mimeType } : {}) };
+    }
     const base64 = typeof data.base64 === 'string' && data.base64.trim()
         ? data.base64.trim()
         : typeof data.data === 'string' && data.data.trim() && !String(data.data).startsWith('http')
@@ -34,6 +41,29 @@ export function mediaRefToLegacyFields(media) {
         return { url: media.value, file: media.value };
     if (media.kind === 'path')
         return { file: media.value, url: media.value };
+    if (media.kind === 'file')
+        return { file: media.value, url: media.value };
     const encoded = media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
     return { file: encoded, url: encoded };
 }
+/** 入站段携带媒体引用的段类型（纯文本视图无法承载的信息）。 */
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+/**
+ * 从入站 canonical 段收集媒体引用（image / audio / video / file）。
+ * 兼容 canonical `data.media` 与旧轨 url/file/base64 字段；
+ * 无媒体段时返回空数组（调用方无需特判 undefined）。
+ */
+export function collectSegmentMedia(segments) {
+    if (!segments?.length)
+        return [];
+    const out = [];
+    for (const segment of segments) {
+        if (!segment || typeof segment.type !== 'string' || !MEDIA_SEGMENT_TYPES.has(segment.type)) {
+            continue;
+        }
+        const media = mediaRefFromLegacyData(segment.data ?? {});
+        if (media)
+            out.push({ type: segment.type, media });
+    }
+    return out;
+}

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

@@ -0,0 +1,7 @@
+import type { Segment } from './types.js';
+/**
+ * 提取纯文本视图：text 段原文拼接，mention/at 段渲染为 `@name`（无名回退
+ * `@target`，`all` → `@all`）；其余段类型不产生文本（媒体 / 回复等结构化
+ * 信息经 `segments` 轨道消费，不污染命令输入）。
+ */
+export declare function segmentsToPlainText(segments: readonly Segment[]): string;

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

@@ -0,0 +1,34 @@
+/**
+ * Canonical Segment[] → 纯文本视图（SSOT）。
+ * 入站双轨：结构化段为唯一内部契约，纯文本视图供命令匹配 / AI 兜底消费。
+ * @see docs/architecture/segment-content-model.md
+ */
+import { readMentionName, readMentionTarget } from './mention.js';
+/**
+ * 提取纯文本视图：text 段原文拼接，mention/at 段渲染为 `@name`（无名回退
+ * `@target`，`all` → `@all`）；其余段类型不产生文本（媒体 / 回复等结构化
+ * 信息经 `segments` 轨道消费，不污染命令输入）。
+ */
+export function segmentsToPlainText(segments) {
+    let out = '';
+    for (const segment of segments) {
+        // Segment 含 SegmentBase 兜底成员，type 窄化不能联动窄化 data，统一按字典读
+        const data = segment.data;
+        if (segment.type === 'text') {
+            if (typeof data.text === 'string')
+                out += data.text;
+            continue;
+        }
+        if (segment.type === 'mention' || segment.type === 'at') {
+            const name = readMentionName(data);
+            if (name) {
+                out += `@${name}`;
+                continue;
+            }
+            const target = readMentionTarget(data);
+            if (target)
+                out += `@${target}`;
+        }
+    }
+    return out;
+}

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

@@ -7,9 +7,13 @@ export interface SegmentBase {
     data: Record<string, unknown>;
     platform?: Record<string, unknown>;
 }
-/** 媒体引用占位（完整 schema 随 adapter 迁移补齐） */
+/**
+ * 媒体引用占位（完整 schema 随 adapter 迁移补齐）。
+ * kind=file：平台侧不透明文件引用（如 Telegram file_id、Milky resource_id），
+ * 非 URL/本地路径，消费方需经平台 API 解析。
+ */
 export interface MediaRef {
-    kind: 'url' | 'path' | 'base64';
+    kind: 'url' | 'path' | 'base64' | 'file';
     value: string;
     mime_type?: string;
 }

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

@@ -4,6 +4,7 @@ const mediaKindSchema = Schema.union([
     Schema.const('url'),
     Schema.const('path'),
     Schema.const('base64'),
+    Schema.const('file'),
 ]);
 export const mediaRefSchema = Schema.object({
     kind: mediaKindSchema.required(),

package/lib/command.d.ts

@@ -5,8 +5,11 @@ import { Plugin } from './plugin.js';
 type ConstructFirstParam<T extends new (...args: any[]) => any> = T extends new (...args: [infer U, ...any[]]) => any ? U : never;
 type ConstructSecondParam<T extends new (...args: any[]) => any> = T extends new (...args: [any, infer V, ...any[]]) => any ? V : never;
 /**
- * MessageCommand类：命令系统核心，基于segment-matcher实现。
- * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
+ * MessageCommand类：经典命令系统（segment-matcher）。
+ *
+ * @deprecated 新插件请用 `defineCommand`（`zhin.js/command`）+ `commands/` 约定目录。
+ * 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用；计划随经典
+ * Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
  */
 export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdapter> extends SegmentMatcher {
     #private;

package/lib/command.js

@@ -1,7 +1,10 @@
 import { SegmentMatcher } from 'segment-matcher';
 /**
- * MessageCommand类：命令系统核心，基于segment-matcher实现。
- * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
+ * MessageCommand类：经典命令系统（segment-matcher）。
+ *
+ * @deprecated 新插件请用 `defineCommand`（`zhin.js/command`）+ `commands/` 约定目录。
+ * 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用；计划随经典
+ * Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
  */
 export class MessageCommand extends SegmentMatcher {
     #callbacks = [];

package/lib/feature/adapter.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Adapter Feature — implementation in `@zhin.js/adapter`. */
+export * from '@zhin.js/adapter';

package/lib/feature/adapter.js

@@ -0,0 +1,2 @@
+/** Authoring API for Adapter Feature — implementation in `@zhin.js/adapter`. */
+export * from '@zhin.js/adapter';

package/lib/feature/command.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Command Feature — implementation in `@zhin.js/command`. */
+export * from '@zhin.js/command';

package/lib/feature/command.js

@@ -0,0 +1,2 @@
+/** Authoring API for Command Feature — implementation in `@zhin.js/command`. */
+export * from '@zhin.js/command';

package/lib/feature/component.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Component Feature — implementation in `@zhin.js/component`. */
+export * from '@zhin.js/component';

package/lib/feature/component.js

@@ -0,0 +1,2 @@
+/** Authoring API for Component Feature — implementation in `@zhin.js/component`. */
+export * from '@zhin.js/component';

package/lib/feature/middleware.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Middleware Feature — implementation in `@zhin.js/middleware`. */
+export * from '@zhin.js/middleware';

package/lib/feature/middleware.js

@@ -0,0 +1,2 @@
+/** Authoring API for Middleware Feature — implementation in `@zhin.js/middleware`. */
+export * from '@zhin.js/middleware';