@zhin.js/core 1.3.2 → 1.3.4

package/README.md

@@ -13,7 +13,7 @@ Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、Message
 ```typescript
 import { usePlugin, MessageCommand } from '@zhin.js/core'
 
-const { addCommand, addTool, addCron, onMounted, onDispose } = usePlugin()
+const { addCommand, addTool, addSchedule, onMounted, onDispose } = usePlugin()
 
 onMounted(() => console.log('插件已挂载'))
 onDispose(() => console.log('插件已卸载'))
@@ -55,7 +55,7 @@ Feature (抽象基类)
 ├── CommandFeature    — 消息命令       addCommand()
 ├── ToolFeature       — AI 可调用工具   addTool()
 ├── SkillFeature      — 技能记录       Agent 从 SKILL.md 注入
-├── CronFeature       — 定时任务       addCron()
+├── ScheduleFeature   — 调度任务       addSchedule()
 ├── DatabaseFeature   — 数据模型       defineModel()
 ├── ComponentFeature  — 消息组件       addComponent()
 ├── ConfigFeature     — 插件配置       addConfig()
@@ -150,9 +150,9 @@ class MyAdapter extends Adapter {
 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<IcqqEndpoint> {
@@ -197,7 +197,7 @@ Core **不包含** ZhinAgent 实现。IM 侧的 AI 对话、工具收集、执
 |------|----------|
 | Provider | `OpenAIProvider`、`OllamaProvider`、`AnthropicProvider` 等 |
 | Agent 原语 | `Agent`、`createAgent`、`ModelRegistry` |
-| 会话 / 上下文 | `SessionManager`（遗留）、`ContextRepository`、`ImTranscriptStore`、`ContextManager`、`ConversationMemory` |
+| 会话 / 上下文 | `ContextRepository`、`ImTranscriptStore`、`ContextManager`、`ConversationMemory` |
 | 压缩 / 限流 / 输出 | `compactSession`、`RateLimiter`、`parseOutput`、`CostTracker` |
 
 完整 Agent 能力与配置见 [`@zhin.js/agent`](../agent/README.md) 与 [AI 模块](https://zhin.js.org/advanced/ai)。
@@ -212,7 +212,7 @@ export { Plugin, usePlugin, getPlugin, definePlugin } from './plugin.js'
 
 // 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'
@@ -236,7 +236,7 @@ export { htmlToFallbackText, coerceHtmlSegmentsToText, registerHtmlSegmentFallba
 // AI 原语（来自 @zhin.js/ai，非 ZhinAgent）
 export {
   OpenAIProvider, OllamaProvider, Agent, createAgent, ModelRegistry,
-  SessionManager, ContextManager, ConversationMemory, compactSession, ...
+  ContextRepository, ContextManager, ConversationMemory, compactSession, ...
 } from '@zhin.js/ai'
 ```
 

package/lib/adapter.d.ts

@@ -6,8 +6,10 @@ 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实例。
@@ -26,6 +28,13 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
     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;
@@ -47,6 +56,11 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
     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 时的字段定义 */
@@ -72,6 +86,13 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
      */
     protected renderSendMessage(options: SendOptions): Promise<SendOptions>;
     sendMessage(options: SendOptions): Promise<string>;
+    /**
+     * 编辑已发送的消息。
+     * - 如果 Endpoint 实现了 $editMessage，调用平台编辑 API
+     * - 否则 fallback 到发送新消息
+     * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
+     */
+    editMessage(options: EditMessageOptions): Promise<string>;
     start(): Promise<void>;
     /**
      * 停止适配器，断开并移除所有 Endpoint 实例
@@ -113,4 +134,3 @@ export declare namespace Adapter {
      */
     function register(name: string, factory: Factory): void;
 }
-//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.js

@@ -3,6 +3,8 @@ 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_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";
 import { segment } from "./utils.js";
@@ -24,6 +26,15 @@ export class Adapter extends EventEmitter {
     static capabilities = DEFAULT_ENDPOINT_CAPABILITIES;
     /** 出站富媒体段渲染策略（子类 override static） */
     static outboundRichSegmentPolicy = DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY;
+    /** 交互段出站策略：native 保留按钮段，text 降级为编号文本 */
+    static interactivePolicy = DEFAULT_INTERACTIVE_POLICY;
+    /** AI 结构化出站能力声明（mentions / richSegments / interactive） */
+    static aiOutboundCapabilities = DEFAULT_AI_OUTBOUND_CAPABILITIES;
+    /** 平台特有 extensions schema + 解析（对齐各 SDK 文档子集） */
+    static aiOutboundExtensions;
+    getInteractivePolicy() {
+        return this.constructor.interactivePolicy;
+    }
     /** 入站消息并发计数 */
     #pendingMessages = 0;
     /** 并发上限，0 表示不限制（默认） */
@@ -104,6 +115,21 @@ export class Adapter extends EventEmitter {
     binding(plugin) {
         this.plugin = plugin;
     }
+    /**
+     * 同步等待入站管线结束（middleware → dispatcher → 生命周期 → 观察者）。
+     * 用于 QQ 等需在被动回复完成后再 ack 交互的平台事件。
+     */
+    async receiveMessageAwait(message) {
+        if (this.inboundPipeline.shouldDropDueToBackpressure()) {
+            this.logger.warn(formatCompact({ drop: 'concurrency', limit: this.maxConcurrentMessages }));
+            return false;
+        }
+        this.#pendingMessages++;
+        await this.inboundPipeline.receive(message, () => {
+            EventEmitter.prototype.emit.call(this, 'message.receive', message);
+        });
+        return true;
+    }
     /**
      * 出站富媒体能力（Publisher 按此过滤/降级；各 adapter 可覆盖）。
      */
@@ -140,6 +166,10 @@ export class Adapter extends EventEmitter {
                     },
                 })),
             };
+            options = {
+                ...options,
+                content: resolveInteractiveSegments(options.content, this.getInteractivePolicy()),
+            };
             const mediaKinds = collectOutboundMediaKinds(options.content);
             if (mediaKinds.length > 0) {
                 this.logger.debug(formatContentChainLog({
@@ -164,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)),
@@ -180,6 +210,47 @@ export class Adapter extends EventEmitter {
         });
         return messageId;
     }
+    /**
+     * 编辑已发送的消息。
+     * - 如果 Endpoint 实现了 $editMessage，调用平台编辑 API
+     * - 否则 fallback 到发送新消息
+     * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
+     */
+    async editMessage(options) {
+        const endpoint = this.endpoints.get(options.endpoint);
+        if (!endpoint)
+            throw new Error(`Endpoint ${options.endpoint} not found`);
+        assertOutbound(endpoint);
+        const editable = endpoint;
+        if (editable.$editMessage) {
+            const rendered = await this.renderSendMessage({
+                context: options.context,
+                endpoint: options.endpoint,
+                id: options.id,
+                type: options.type,
+                content: options.content,
+            });
+            await editable.$editMessage({ ...options, content: rendered.content });
+            this.logger.debug(formatCompact({
+                edit: `${options.type}(${options.id})`,
+                endpoint: options.endpoint,
+                messageId: options.messageId,
+            }));
+            return options.messageId;
+        }
+        this.logger.debug(formatCompact({
+            editFallback: 'sendMessage',
+            endpoint: options.endpoint,
+            reason: '$editMessage not implemented',
+        }));
+        return this.sendMessage({
+            context: options.context,
+            endpoint: options.endpoint,
+            id: options.id,
+            type: options.type,
+            content: options.content,
+        });
+    }
     async start() {
         if (this.endpoints.size > 0) {
             await this.stop();
@@ -264,4 +335,3 @@ export class Adapter extends EventEmitter {
     }
     Adapter.register = register;
 })(Adapter || (Adapter = {}));
-//# sourceMappingURL=adapter.js.map

package/lib/agent-prompt.d.ts

@@ -38,4 +38,3 @@ export interface AgentPromptContributor {
     /** Non-null replaces default TF-IDF deferred tool selection. */
     selectDeferredTools?(query: string, goal: string, catalog: DeferredToolCatalogItem[], maxTools: number): DeferredToolCatalogItem[] | null;
 }
-//# sourceMappingURL=agent-prompt.d.ts.map

package/lib/agent-prompt.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=agent-prompt.js.map

package/lib/built/adapter-process.d.ts

@@ -51,4 +51,3 @@ declare module '../adapter.js' {
         process: ProcessAdapter;
     }
 }
-//# sourceMappingURL=adapter-process.d.ts.map

package/lib/built/adapter-process.js

@@ -121,4 +121,3 @@ export class ProcessAdapter extends Adapter {
         return new ProcessEndpoint(this, config);
     }
 }
-//# sourceMappingURL=adapter-process.js.map

package/lib/built/agent-preset.d.ts

@@ -62,4 +62,3 @@ export declare class AgentPresetFeature extends Feature<AgentPreset> {
     }): AgentPreset[];
     toJSON(pluginName?: string): FeatureJSON;
 }
-//# sourceMappingURL=agent-preset.d.ts.map

package/lib/built/agent-preset.js

@@ -77,4 +77,3 @@ export class AgentPresetFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=agent-preset.js.map

package/lib/built/ai-access.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AI Access Gate — 控制 LLM 回复路径是否对当前会话开放（平台 AIGC 合规等）
+ */
+import type { Message } from '../message.js';
+export type AIAccessMode = 'open' | 'closed' | 'whitelist';
+/** Endpoint 或全局 ai.access 配置块 */
+export interface AIAccessScopeConfig {
+    mode?: AIAccessMode;
+    /** 允许触发 AI 的 sender.id */
+    users?: string[];
+    /** 允许触发 AI 的 group/channel id */
+    groups?: string[];
+    /** 私聊拒绝时的回复文案 */
+    denyMessage?: string;
+}
+/** 全局 ai.access 配置（与 AIAccessScopeConfig 同形） */
+export type AIAccessConfig = AIAccessScopeConfig;
+export interface ResolvedAIAccessConfig {
+    mode: AIAccessMode;
+    users: string[];
+    groups: string[];
+    denyMessage: string;
+}
+export interface AIAccessResult {
+    allowed: boolean;
+    reason: string;
+    /** 私聊拒绝时返回；群/频道拒绝为 undefined（静默） */
+    replyMessage?: string;
+}
+export declare const DEFAULT_AI_ACCESS_DENY_MESSAGE = "\u5F53\u524D\u4F1A\u8BDD\u672A\u5F00\u653E AI \u529F\u80FD\u3002";
+export declare function resolveAIAccessConfig(global: AIAccessConfig | undefined, endpointScope?: AIAccessScopeConfig): ResolvedAIAccessConfig;
+/**
+ * 判定当前消息是否允许进入 AI Handler（LLM 回复路径）。
+ * 不影响命令、游戏等其它 Dispatcher 分支。
+ */
+export declare function checkAIAccess(message: Message<any>, globalConfig: AIAccessConfig | undefined, endpointScope?: AIAccessScopeConfig): AIAccessResult;

package/lib/built/ai-access.js

@@ -0,0 +1,46 @@
+export const DEFAULT_AI_ACCESS_DENY_MESSAGE = '当前会话未开放 AI 功能。';
+const DEFAULT_MODE = 'open';
+export function resolveAIAccessConfig(global, endpointScope) {
+    const base = global ?? {};
+    const endpoint = endpointScope ?? {};
+    return {
+        mode: endpoint.mode ?? base.mode ?? DEFAULT_MODE,
+        users: endpoint.users ?? base.users ?? [],
+        groups: endpoint.groups ?? base.groups ?? [],
+        denyMessage: endpoint.denyMessage ?? base.denyMessage ?? DEFAULT_AI_ACCESS_DENY_MESSAGE,
+    };
+}
+function isWhitelisted(message, config) {
+    const userId = String(message.$sender?.id ?? '');
+    if (userId && config.users.includes(userId))
+        return true;
+    const scope = message.$channel?.type;
+    if (scope === 'group' || scope === 'channel') {
+        const channelId = String(message.$channel?.id ?? '');
+        if (channelId && config.groups.includes(channelId))
+            return true;
+    }
+    return false;
+}
+function denyResult(message, config, reason) {
+    const scope = message.$channel?.type;
+    const replyMessage = scope === 'private' ? config.denyMessage : undefined;
+    return { allowed: false, reason, replyMessage };
+}
+/**
+ * 判定当前消息是否允许进入 AI Handler（LLM 回复路径）。
+ * 不影响命令、游戏等其它 Dispatcher 分支。
+ */
+export function checkAIAccess(message, globalConfig, endpointScope) {
+    const config = resolveAIAccessConfig(globalConfig, endpointScope);
+    if (config.mode === 'open') {
+        return { allowed: true, reason: 'mode: open' };
+    }
+    if (config.mode === 'closed') {
+        return denyResult(message, config, 'mode: closed');
+    }
+    if (isWhitelisted(message, config)) {
+        return { allowed: true, reason: 'whitelist: matched' };
+    }
+    return denyResult(message, config, 'whitelist: not matched');
+}

package/lib/built/ai-outbound/adapter-access.d.ts

@@ -0,0 +1,3 @@
+import { type AiOutboundCapabilities, type AiOutboundExtensionDefinition } from './types.js';
+export declare function getAdapterAiOutboundCapabilities(adapterInstance: object): AiOutboundCapabilities;
+export declare function getAdapterAiOutboundExtensions(adapterInstance: object): readonly AiOutboundExtensionDefinition[];

package/lib/built/ai-outbound/adapter-access.js

@@ -0,0 +1,9 @@
+import { DEFAULT_AI_OUTBOUND_CAPABILITIES, } from './types.js';
+export function getAdapterAiOutboundCapabilities(adapterInstance) {
+    const ctor = adapterInstance.constructor;
+    return ctor.aiOutboundCapabilities ?? DEFAULT_AI_OUTBOUND_CAPABILITIES;
+}
+export function getAdapterAiOutboundExtensions(adapterInstance) {
+    const ctor = adapterInstance.constructor;
+    return ctor.aiOutboundExtensions ?? [];
+}

package/lib/built/ai-outbound/extensions/onebot-keyboard.d.ts

@@ -0,0 +1,2 @@
+import type { AiOutboundExtensionDefinition } from '../types.js';
+export declare const ONEBOT_KEYBOARD_AI_OUTBOUND_EXTENSION: AiOutboundExtensionDefinition;

package/lib/built/ai-outbound/extensions/onebot-keyboard.js

@@ -0,0 +1,67 @@
+import { KeyboardSegment } from '../../interactive-segments/keyboard-segment.js';
+const ONEBOT_KEYBOARD_SCHEMA = {
+    type: 'object',
+    properties: {
+        rows: {
+            type: 'array',
+            items: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        label: { type: 'string' },
+                        payload: { type: 'string' },
+                        id: { type: 'string' },
+                    },
+                    required: ['label', 'payload'],
+                },
+            },
+        },
+    },
+    required: ['rows'],
+};
+function toKeyboardSegment(ext) {
+    if (!ext || typeof ext !== 'object')
+        return null;
+    const obj = ext;
+    const rowsRaw = obj.rows;
+    if (!Array.isArray(rowsRaw))
+        return null;
+    const rows = [];
+    for (const row of rowsRaw) {
+        if (!Array.isArray(row))
+            continue;
+        const buttons = [];
+        for (const btn of row) {
+            if (!btn || typeof btn !== 'object')
+                continue;
+            const b = btn;
+            const label = typeof b.label === 'string' ? b.label : '';
+            const payload = typeof b.payload === 'string' ? b.payload : '';
+            if (!label || !payload)
+                continue;
+            buttons.push({
+                id: typeof b.id === 'string' ? b.id : payload,
+                label,
+                payload,
+                disabled: b.disabled === true,
+            });
+        }
+        if (buttons.length)
+            rows.push(buttons);
+    }
+    if (!rows.length)
+        return null;
+    return new KeyboardSegment({ rows }).toElement();
+}
+export const ONEBOT_KEYBOARD_AI_OUTBOUND_EXTENSION = {
+    key: 'onebot.keyboard',
+    schema: ONEBOT_KEYBOARD_SCHEMA,
+    examples: [
+        '{"extensions":{"onebot.keyboard":{"rows":[[{"label":"确认","payload":"ok","id":"ok"}]]}}}',
+    ],
+    toMessageElements(ext, _ctx) {
+        const seg = toKeyboardSegment(ext);
+        return seg ? [seg] : [];
+    },
+};

package/lib/built/ai-outbound/extensions/qq-message.d.ts

@@ -0,0 +1,3 @@
+import type { AiOutboundExtensionDefinition } from '../types.js';
+export declare const QQ_MARKDOWN_AI_OUTBOUND_EXTENSION: AiOutboundExtensionDefinition;
+export declare const QQ_AI_OUTBOUND_EXTENSIONS: readonly AiOutboundExtensionDefinition[];

package/lib/built/ai-outbound/extensions/qq-message.js

@@ -0,0 +1,23 @@
+const QQ_MARKDOWN_SCHEMA = {
+    type: 'object',
+    properties: {
+        content: { type: 'string' },
+    },
+    required: ['content'],
+};
+export const QQ_MARKDOWN_AI_OUTBOUND_EXTENSION = {
+    key: 'qq.markdown',
+    schema: QQ_MARKDOWN_SCHEMA,
+    examples: ['{"extensions":{"qq.markdown":{"content":"# Title\\nBody"}}}'],
+    toMessageElements(ext, _ctx) {
+        if (!ext || typeof ext !== 'object')
+            return [];
+        const content = ext.content;
+        if (typeof content !== 'string' || !content.trim())
+            return [];
+        return [{ type: 'markdown', data: { content: content.trim() } }];
+    },
+};
+export const QQ_AI_OUTBOUND_EXTENSIONS = [
+    QQ_MARKDOWN_AI_OUTBOUND_EXTENSION,
+];

package/lib/built/ai-outbound/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './parse.js';
+export * from './plain-mention-rewrite.js';
+export * from './resolve.js';
+export * from './prompt.js';
+export * from './structured-detect.js';
+export * from './adapter-access.js';
+export * from './extensions/onebot-keyboard.js';
+export * from './extensions/qq-message.js';

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

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './parse.js';
+export * from './plain-mention-rewrite.js';
+export * from './resolve.js';
+export * from './prompt.js';
+export * from './structured-detect.js';
+export * from './adapter-access.js';
+export * from './extensions/onebot-keyboard.js';
+export * from './extensions/qq-message.js';

package/lib/built/ai-outbound/parse.d.ts

@@ -0,0 +1,13 @@
+import type { Segment } from '../segment-contract/types.js';
+import type { ZhinAiOutboundPayload } from './types.js';
+/** 解析单条 outbound segment（canonical 或 legacy kind/mode）。 */
+export declare function parseOutboundSegment(raw: unknown): Segment | null;
+/** 去掉嵌入 JSON 候选末尾的 markdown 围栏（模型常见 ```json … ``` 误输出）。 */
+export declare function trimTrailingMarkdownFence(raw: string): string;
+export declare function unwrapAiOutboundJsonCandidate(raw: string): string;
+/** 从「正文 + 嵌入 JSON」混合文本中提取 AI outbound JSON（协作群常见误输出）。 */
+export declare function extractEmbeddedAiOutboundJson(plain: string): {
+    prose: string;
+    jsonRaw: string;
+} | null;
+export declare function parseAiOutboundJson(raw: string): ZhinAiOutboundPayload | null;

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

@@ -0,0 +1,108 @@
+import { isCanonicalSegment } from '../segment-contract/assert.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 解析单条 outbound segment（canonical 或 legacy kind/mode）。 */
+export function parseOutboundSegment(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const type = typeof raw.type === 'string' && raw.type.trim()
+        ? raw.type.trim()
+        : typeof raw.kind === 'string' && raw.kind.trim()
+            ? raw.kind.trim()
+            : undefined;
+    if (!type)
+        return null;
+    const data = isPlainObject(raw.data) ? raw.data : {};
+    const platform = isPlainObject(raw.platform) ? raw.platform : undefined;
+    const segment = platform ? { type, data, platform } : { type, data };
+    return isCanonicalSegment(segment) ? segment : null;
+}
+/** 去掉嵌入 JSON 候选末尾的 markdown 围栏（模型常见 ```json … ``` 误输出）。 */
+export function trimTrailingMarkdownFence(raw) {
+    let s = raw.trim();
+    if (s.endsWith('```'))
+        s = s.slice(0, -3).trimEnd();
+    return s;
+}
+export function unwrapAiOutboundJsonCandidate(raw) {
+    const trimmed = raw.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);
+}
+/** 从「正文 + 嵌入 JSON」混合文本中提取 AI outbound JSON（协作群常见误输出）。 */
+export function extractEmbeddedAiOutboundJson(plain) {
+    const trimmed = plain.trim();
+    if (!trimmed.includes('{'))
+        return null;
+    const fenced = readMarkdownFence(trimmed);
+    if (fenced) {
+        const jsonRaw = trimTrailingMarkdownFence(fenced.body.trim());
+        const payload = parseAiOutboundJson(jsonRaw);
+        if (payload?.mentions?.length && payload.text?.trim()) {
+            const prose = trimmed.slice(0, fenced.start).trim();
+            return { prose, jsonRaw };
+        }
+    }
+    let idx = trimmed.indexOf('{');
+    while (idx >= 0) {
+        const jsonRaw = trimTrailingMarkdownFence(trimmed.slice(idx).trim());
+        const payload = parseAiOutboundJson(jsonRaw);
+        if (payload?.mentions?.length && payload.text?.trim()) {
+            return { prose: trimmed.slice(0, idx).trim(), jsonRaw };
+        }
+        idx = trimmed.indexOf('{', idx + 1);
+    }
+    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('{'))
+        return null;
+    try {
+        const parsed = JSON.parse(candidate);
+        const text = typeof parsed.text === 'string' ? parsed.text.trim() : undefined;
+        const mentionsRaw = parsed.mentions;
+        const mentions = Array.isArray(mentionsRaw)
+            ? mentionsRaw.map((m) => String(m).trim()).filter(Boolean)
+            : undefined;
+        const segmentsRaw = parsed.segments;
+        const segments = Array.isArray(segmentsRaw)
+            ? segmentsRaw
+                .map((item) => parseOutboundSegment(item))
+                .filter((s) => s != null)
+            : undefined;
+        const extensions = parsed.extensions != null && typeof parsed.extensions === 'object' && !Array.isArray(parsed.extensions)
+            ? parsed.extensions
+            : undefined;
+        if (!text && !mentions?.length && !segments?.length && !extensions)
+            return null;
+        if (mentions?.length && !text)
+            return null;
+        return { text, mentions, segments, extensions };
+    }
+    catch {
+        return null;
+    }
+}

package/lib/built/ai-outbound/plain-mention-rewrite.d.ts

@@ -0,0 +1,6 @@
+import type { AiOutboundMentionResolver, ZhinAiOutboundPayload } from './types.js';
+/**
+ * 从正文中提取 cell roster 可识别的假 @（@researcher / @210723495 等），
+ * 剥离后返回等效 ZhinAiOutboundPayload。
+ */
+export declare function rewritePlainTextMentions(plainText: string, mentionResolver: AiOutboundMentionResolver): ZhinAiOutboundPayload | null;

package/lib/built/ai-outbound/plain-mention-rewrite.js

@@ -0,0 +1,37 @@
+const PLAIN_MENTION_PATTERN = /@([\w-]+)/g;
+/**
+ * 从正文中提取 cell roster 可识别的假 @（@researcher / @210723495 等），
+ * 剥离后返回等效 ZhinAiOutboundPayload。
+ */
+export function rewritePlainTextMentions(plainText, mentionResolver) {
+    const trimmed = plainText.trim();
+    if (!trimmed)
+        return null;
+    const mentions = [];
+    let rewritten = trimmed;
+    for (const match of trimmed.matchAll(PLAIN_MENTION_PATTERN)) {
+        const token = match[1];
+        if (!token)
+            continue;
+        const endpointId = mentionResolver(token);
+        if (!endpointId)
+            continue;
+        const ref = token;
+        if (!mentions.includes(ref))
+            mentions.push(ref);
+    }
+    if (mentions.length === 0)
+        return null;
+    rewritten = trimmed.replace(PLAIN_MENTION_PATTERN, (full, token) => {
+        const endpointId = mentionResolver(token);
+        return endpointId ? '' : full;
+    });
+    rewritten = rewritten
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/^\s+|\s+$/g, '')
+        .trim();
+    if (!rewritten)
+        return null;
+    return { mentions, text: rewritten };
+}