@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/hook/global-hook-manager.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Global HookManager - 全局 Hook 单例
+ *
+ * 所有 Component 的 Hook 都注册到统一的全局实例
+ */
+import { HookManager } from "./hook-manager";
+import type { HookResult } from "./types";
+/**
+ * 全局 HookManager 实例
+ *
+ * 所有 Agent/LLM/Tool hooks 都注册到这个实例
+ */
+export declare const globalHookManager: HookManager<unknown>;
+/**
+ * Agent Hook 点（新版统一命名）
+ */
+export declare const AgentHookPoints: {
+    readonly BEFORE_START: "agent:before.start";
+    readonly BEFORE_LLM: "agent:before.llm";
+    readonly AFTER_LLM: "agent:after.llm";
+    readonly BEFORE_TOOL: "agent:before.tool";
+    readonly AFTER_TOOL: "agent:after.tool";
+    readonly ON_ITERATION: "agent:on.iteration";
+    readonly ON_THRESHOLD: "agent:on.threshold";
+    readonly AFTER_COMPLETE: "agent:after.complete";
+    readonly ON_ERROR: "agent:on.error";
+};
+/**
+ * LLM Hook 点
+ */
+export declare const LLMHookPoints: {
+    readonly BEFORE_INVOKE: "llm:before.invoke";
+    readonly AFTER_INVOKE: "llm:after.invoke";
+    readonly ON_STREAM: "llm:on.stream";
+};
+/**
+ * Tool Hook 点
+ */
+export declare const ToolHookPoints: {
+    readonly BEFORE_EXECUTE: "tool:before.execute";
+    readonly AFTER_EXECUTE: "tool:after.execute";
+    readonly BEFORE_REGISTER: "tool:before.register";
+    readonly AFTER_REGISTER: "tool:after.register";
+    readonly ON_ERROR: "tool:on.error";
+};
+/**
+ * 旧版 Tool Hook 点别名映射（向后兼容）
+ */
+export declare const LegacyToolHookPoints: {
+    readonly BEFORE_EXECUTE: "tool:before.execute";
+    readonly AFTER_EXECUTE: "tool:after.execute";
+    readonly BEFORE_REGISTER: "tool:before.register";
+    readonly AFTER_REGISTER: "tool:after.register";
+    readonly ON_ERROR: "tool:on.error";
+    readonly BEFORE_TOOL: "before.tool";
+    readonly AFTER_TOOL: "after.tool";
+};
+/**
+ * 执行 Agent Hook（不带干预）
+ */
+export declare function executeAgentHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * 执行 Agent Hook（带干预检查）
+ */
+export declare function executeAgentHookWithIntervention(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<HookResult>;
+/**
+ * 执行 LLM Hook（不带干预）
+ */
+export declare function executeLLMHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * 执行 Tool Hook（不带干预）
+ */
+export declare function executeToolHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;

package/dist/env/hook/hook-manager.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Hook Manager - 统一管理 Component 的 Hook
+ *
+ * 提供：
+ * - Hook 注册和管理
+ * - 按优先级排序执行
+ * - 错误隔离
+ * - 动态添加/移除
+ * - 干预机制（executeWithIntervention）
+ */
+import type { Hook, HookResult } from "./types";
+/**
+ * HookManager 配置
+ */
+export interface HookManagerOptions {
+    /** 组件名称（用于上下文） */
+    componentName?: string;
+    /** 组件版本（用于上下文） */
+    componentVersion?: string;
+    /** 默认优先级 */
+    defaultPriority?: number;
+}
+/**
+ * HookManager
+ *
+ * 统一管理 Component 的 Hook
+ *
+ * @example
+ * ```typescript
+ * const manager = new HookManager<MyContext>();
+ *
+ * // 注册 Hook
+ * manager.register("before-action", {
+ *   name: "my-hook",
+ *   priority: 10,
+ *   execute: async (ctx) => { /* ... *\/ }
+ * });
+ *
+ * // 执行 Hooks
+ * await manager.execute("before-action", data);
+ * ```
+ */
+export declare class HookManager<T = unknown> {
+    private _hooks;
+    private componentName;
+    private componentVersion;
+    private defaultPriority;
+    constructor(options?: HookManagerOptions);
+    /**
+     * 注册 Hook 到指定 hook 点
+     */
+    register(hookPoint: string, hook: Hook<T>): void;
+    /**
+     * 注册多个 Hook
+     */
+    registerMany(hookPoint: string, hooks: Hook<T>[]): void;
+    /**
+     * 按名称取消注册 Hook
+     * @returns 是否成功取消注册
+     */
+    unregister(hookPoint: string, name: string): boolean;
+    /**
+     * 取消注册所有指定 hook 点的 Hook
+     */
+    unregisterAll(hookPoint: string): void;
+    /**
+     * 执行指定 hook 点的所有 Hook
+     *
+     * 支持 pluginEnabled 检查：
+     * - 如果 hook 有 pluginName 和 sourceId，则检查 metadata.pluginEnabled[key] 是否为 true
+     * - 如果未启用，则跳过该 hook
+     * - 如果 hook 没有 pluginName/sourceId，则总是执行
+     *
+     * 也会从线程变量 EnvContext 中获取信息补充到 metadata
+     */
+    execute(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * 执行指定 hook 点的所有 Hook 并收集返回值
+     */
+    executeAndCollect<R>(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<R[]>;
+    /**
+     * 获取指定 hook 点的 Hook 数量
+     */
+    count(hookPoint: string): number;
+    /**
+     * 清空所有 Hook
+     */
+    clear(): void;
+    /**
+     * 获取所有已注册的 hook 点
+     */
+    getHookPoints(): string[];
+    /**
+     * 检查 hook 点是否有任何 Hook
+     */
+    hasHooks(hookPoint: string): boolean;
+    /**
+     * 设置组件信息
+     */
+    setComponentInfo(name: string, version: string): void;
+    /**
+     * 获取所有注册的 hooks（只读副本）
+     */
+    get hooks(): ReadonlyMap<string, Hook<T>[]>;
+    /**
+     * 执行 Hook 并支持干预机制
+     *
+     * 如果任何一个 Hook 返回 { stop: true }，执行会停止
+     * Hook 可以通过返回 HookResult 来执行干预动作
+     *
+     * @param hookPoint Hook 点
+     * @param data 数据
+     * @param metadata 元数据
+     * @returns 执行结果
+     */
+    executeWithIntervention(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<HookResult>;
+    /**
+     * 获取或创建 hook 列表
+     */
+    private getOrCreateHooks;
+    /**
+     * 按优先级排序 Hook
+     *
+     * 优先级相同时保持原顺序（稳定排序）
+     */
+    private sortHooks;
+    /**
+     * 创建 Hook 上下文
+     */
+    private createContext;
+    /**
+     * 安全执行 Hook（错误隔离）
+     */
+    private safeExecute;
+    /**
+     * 安全执行 Hook 并返回结果
+     */
+    private safeExecuteAndReturn;
+}

package/dist/env/hook/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Hook 系统统一导出
+ *
+ * 注意：HookContext 泛型版本从 ./types 导出
+ * Agent 特有的 HookContext 包含 iteration, maxIterations 等字段，在 ./agent/types.ts 中
+ */
+export { type HookPhase, type HookMeta, type HookContext, type Hook, type HookFn, type HookActionType, type HookAction, type HookResult, type HookContext as BaseHookContext, type Hook as BaseHook, type HookFn as BaseHookFn, createHook, createPriorityHook, } from "./types";
+export { HookManager, type HookManagerOptions } from "./hook-manager";
+export { globalHookManager, AgentHookPoints, LLMHookPoints, ToolHookPoints, executeAgentHook, executeAgentHookWithIntervention, executeLLMHook, executeToolHook, } from "./global-hook-manager";

package/dist/env/hook/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Hook 系统统一类型定义
+ *
+ * 提供所有 Component 使用的统一 Hook 接口
+ */
+/**
+ * Hook 执行阶段
+ */
+export type HookPhase = "before" | "after" | "error";
+/**
+ * Hook 元信息
+ */
+export interface HookMeta {
+    /** Hook 唯一名称 */
+    name: string;
+    /** 执行优先级，默认 0，数值越小越先执行 */
+    priority?: number;
+    /** 描述 */
+    description?: string;
+    /** Plugin 名称（EventSource 加载的 plugin） */
+    pluginName?: string;
+    /** 事件源 ID（EventSource 加载的 plugin） */
+    sourceId?: string;
+}
+/**
+ * 统一 Hook 上下文
+ *
+ * 泛型参数 T 表示该 Component 的上下文数据类型
+ */
+export interface HookContext<T = unknown> {
+    /** 当前组件信息 */
+    component: {
+        /** 组件名称 */
+        name: string;
+        /** 组件版本 */
+        version: string;
+    };
+    /** 上下文数据（Component 特定） */
+    data: T;
+    /** 元数据（可用于传递额外信息） */
+    metadata: Record<string, unknown>;
+    /** 执行阶段 */
+    phase: HookPhase;
+    /** 关联的 hook 点名称 */
+    hookPoint: string;
+}
+/**
+ * 统一 Hook 接口
+ *
+ * 所有 Component 的 Hook 都应实现此接口
+ */
+export interface Hook<T = unknown> extends HookMeta {
+    /** 执行 Hook
+     * @param ctx 上下文
+     */
+    execute(ctx: HookContext<T>): void | Promise<void>;
+}
+/**
+ * Hook 函数类型（便捷别名）
+ */
+export type HookFn<T = unknown> = (ctx: HookContext<T>) => void | Promise<void>;
+/**
+ * Hook 干预动作类型
+ */
+export type HookActionType = "stop" | "retry" | "compress" | "extract_memory" | "inject_message" | "skip_tool" | "custom";
+/**
+ * Hook 干预动作
+ */
+export interface HookAction {
+    /** 动作类型 */
+    type: HookActionType;
+    /** 动作参数 */
+    params?: Record<string, unknown>;
+    /** 动作描述 */
+    description?: string;
+}
+/**
+ * Hook 执行结果
+ */
+export interface HookResult {
+    /** 是否被停止 */
+    stopped?: boolean;
+    /** 干预动作（如果有） */
+    action?: HookAction;
+    /** 执行结果数据 */
+    results?: unknown[];
+}
+/**
+ * 创建 Hook 的工厂函数
+ *
+ * @param meta Hook 元信息
+ * @param fn 执行函数
+ * @returns Hook 实例
+ *
+ * @example
+ * ```typescript
+ * const hook = createHook(
+ *   { name: "my-hook", priority: 10 },
+ *   async (ctx) => { console.log(ctx.data); }
+ * );
+ * ```
+ */
+export declare function createHook<T = unknown>(meta: HookMeta, fn: HookFn<T>): Hook<T>;
+/**
+ * 创建带优先级的 Hook 的便捷函数
+ */
+export declare function createPriorityHook<T = unknown>(name: string, fn: HookFn<T>, priority: number): Hook<T>;

package/dist/env/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Environment Module
+ *
+ * 导出 Environment 相关的类型和实现。
+ */
+export type { Environment } from "./interface";
+export type { EnvironmentConfig, BaseEnvironmentConfig, EnvEvent, EnvEventMetadata, EnvEventHandler, Action, ToolResult, Context, } from "./types";
+export { BaseEnvironment } from "./environment";
+export { type Component, type ComponentConfig, type ComponentSchema, type ComponentPaths, type ComponentStatus, type ComponentConfigChangeEvent, type ComponentWatchCallback, BaseComponent, } from "./component";
+export { type Hook, type HookContext, type HookPhase, type HookMeta, type HookFn, type HookManagerOptions, createHook, createPriorityHook, HookManager, } from "./hook";
+export { type EnvContext, getEnvContext, getEnvContextOrEmpty, hasEnvContext, runWithEnvContext, runWithEnvContextAsync, createEnvContext, mergeEnvContext, } from "./context";
+export { type XDGPaths, type XDGDirType, XDG_PATHS, getXDGPaths, getXDGPath, } from "./paths";
+export { AgentComponent, type AgentComponentConfig, AgentComponentConfigSchema, type AgentInstance, type AgentInstanceConfig, type AgentRunResult, type AgentContext, type Plugin, type HookContext as AgentHookContext, type HookPoint, type HookResult, type HookActionType, type Tool, type ToolCall, type ToolResult as AgentToolResult, type ToolCallResult, type LLMOutput, } from "./agent";
+export { TaskComponent, type TaskComponentOptions, } from "./task";
+export type { Task, TaskOperation, TaskStatus, TaskPriority, ActionType, CreateTaskOptions, UpdateTaskOptions, ListTasksOptions, CreateOperationOptions, ListOperationsOptions, TaskConfig, } from "./task/types";
+export { McpComponent, } from "./mcp";
+export type { McpComponentConfig, McpComponentOptions, McpPath, McpServerConfig, McpServerStatus, DiscoveredMcpServer, } from "./mcp";
+export { EventSourceComponent, larkCliHandler, builtInHandlers, } from "./event-source/event-source-component";
+export type { EventSourceConfig, EventSourceStatus, EventSourceType, EventSourceEvent, EventSourceEventPayload, EventSourceEventHandler, EventSourceStatusChangeEvent, EventSourcePersistenceConfig, EventSourceComponentInterface, EventSourceHandler, EventSourceInstance, EventSourceAgentHandlerConfig, BUILT_IN_EVENT_SOURCE_TYPES, } from "./event-source/types";
+export { EventSourceInitHooks, isValidEventSourceType, isBuiltInEventSourceType, getDefaultConfigForType, validateEventSourceConfig, } from "./event-source/types";
+export { WorkflowComponent, } from "./workflow/workflow-component";
+export type { WorkflowComponentConfig, } from "./workflow/workflow-component";
+export { PluginComponent, } from "./plugin/plugin-component";
+export type { PluginComponentOptions, } from "./plugin/plugin-component";

package/dist/env/index.js

@@ -1,6 +1,6 @@
 import {
   BaseEnvironment
-} from "../shared/@ai-setting/roy-agent-core-rcfewbzr.js";
+} from "../shared/@ai-setting/roy-agent-core-4sx6sdb2.js";
 import {
   TaskComponent
 } from "../shared/@ai-setting/roy-agent-core-39xejr39.js";
@@ -15,7 +15,7 @@ import {
   EventSourceComponent,
   builtInHandlers,
   larkCliHandler
-} from "../shared/@ai-setting/roy-agent-core-ezgsem94.js";
+} from "../shared/@ai-setting/roy-agent-core-ph5qbqcx.js";
 import {
   EventSourceInitHooks,
   getDefaultConfigForType,
@@ -24,7 +24,7 @@ import {
   validateEventSourceConfig
 } from "../shared/@ai-setting/roy-agent-core-ck60j1q9.js";
 import"../shared/@ai-setting/roy-agent-core-rnwr39b0.js";
-import"../shared/@ai-setting/roy-agent-core-pkpkctvf.js";
+import"../shared/@ai-setting/roy-agent-core-hch2geta.js";
 import"../shared/@ai-setting/roy-agent-core-yhsssn86.js";
 import"../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../shared/@ai-setting/roy-agent-core-gdsqp6j8.js";
@@ -32,7 +32,7 @@ import"../shared/@ai-setting/roy-agent-core-brwzs8wf.js";
 import"../shared/@ai-setting/roy-agent-core-j8e92gj8.js";
 import {
   WorkflowComponent
-} from "../shared/@ai-setting/roy-agent-core-s214vmmd.js";
+} from "../shared/@ai-setting/roy-agent-core-4vpk40ss.js";
 import"../shared/@ai-setting/roy-agent-core-vrsxhw9e.js";
 import"../shared/@ai-setting/roy-agent-core-h0x19xgn.js";
 import"../shared/@ai-setting/roy-agent-core-1ce3fqrk.js";

package/dist/env/interface.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Environment Interface
+ *
+ * Environment 是智能体运行时的核心抽象。
+ *
+ * 设计原则：
+ * 1. Environment 只做两件事：
+ *    - 组件管理：持有、注册、获取组件
+ *    - 核心调度：handle_query / handle_action / EnvEvent
+ * 2. 其他能力归属到对应 Component
+ *
+ * 服务配置能力：
+ * - loadServiceConfig(): 从配置文件加载服务配置
+ * - generateComponentOptions(): 生成组件初始化选项
+ * - registerComponentWithConfig(): 注册并用配置初始化组件
+ * - initFromConfig(): 从配置文件初始化整个环境
+ */
+import type { Component } from "./component";
+import type { EnvEvent, EnvEventHandler, EnvEventInput, EnvironmentConfig, Action, ToolResult, Context } from "./types";
+import type { AgentContext } from "./agent/types";
+import type { ContentPart } from "./llm/types";
+import type { ConfigComponent } from "../config/config-component";
+export type { AgentContext };
+/**
+ * 服务配置接口
+ */
+export interface ServiceConfig {
+    /** 环境配置 */
+    environment?: {
+        name?: string;
+        version?: string;
+    };
+    /** 组件配置映射 */
+    components?: Record<string, ComponentConfigEntry>;
+}
+/**
+ * 组件配置项
+ */
+export interface ComponentConfigEntry {
+    /** 配置文件路径（可选） */
+    configPath?: string;
+    /** 环境变量前缀（可选） */
+    envPrefix?: string;
+    /** 直接配置对象（可选） */
+    config?: Record<string, unknown>;
+    /** 是否启用（可选，默认 true） */
+    enabled?: boolean;
+}
+/**
+ * 组件初始化选项（由 generateComponentOptions 生成）
+ */
+export interface GeneratedComponentOptions {
+    /** ConfigComponent 实例 */
+    configComponent: ConfigComponent;
+    /** 配置文件路径 */
+    configPath?: string;
+    /** 环境变量前缀 */
+    envPrefix?: string;
+    /** 直接配置对象 */
+    config?: Record<string, unknown>;
+    /** 允许的其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * Environment 接口
+ *
+ * 定义 Agent 运行时的核心能力接口。
+ */
+export interface Environment {
+    /** 环境名称 */
+    readonly name: string;
+    /** 环境版本 */
+    readonly version: string;
+    /** 获取环境配置 */
+    getConfig(): EnvironmentConfig;
+    /**
+     * 注册组件
+     */
+    registerComponent(component: Component): void;
+    /**
+     * 注销组件
+     */
+    unregisterComponent(name: string): void;
+    /**
+     * 获取组件
+     */
+    getComponent<T extends Component>(name: string): T | undefined;
+    /**
+     * 列出所有组件
+     */
+    listComponents(): Component[];
+    /**
+     * 处理自然语言查询（核心入口）
+     *
+     * @param query 用户查询（文本 string 或多模态 ContentPart[]）
+     * @param context 执行上下文（可选）
+     * @returns 完整的文本响应
+     */
+    handle_query(query: string | ContentPart[], context?: AgentContext): Promise<string>;
+    /**
+     * 处理动作
+     */
+    handle_action(action: Action, context: Context): Promise<ToolResult>;
+    /**
+     * 订阅 EnvEvent（返回取消订阅函数）
+     */
+    subscribe(handler: EnvEventHandler): () => void;
+    /**
+     * 订阅指定类型事件
+     */
+    subscribeTo(eventType: string | string[], handler: EnvEventHandler): () => void;
+    /**
+     * 订阅所有事件（通配符）
+     */
+    subscribeAll(handler: EnvEventHandler): () => void;
+    /**
+     * 推送事件
+     *
+     * @param event EnvEvent 或 EnvEventInput（部分属性）
+     */
+    pushEnvEvent(event: EnvEvent | EnvEventInput): void;
+    /**
+     * 从配置文件加载服务配置
+     *
+     * @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+     * @returns 解析后的服务配置对象
+     */
+    loadServiceConfig(configPath: string): Promise<ServiceConfig>;
+    /**
+     * 生成组件初始化选项
+     *
+     * 根据组件配置项生成可用于初始化的选项对象。
+     *
+     * @param componentName 组件名称
+     * @param configEntry 组件配置项
+     * @returns 生成的组件初始化选项
+     */
+    generateComponentOptions(componentName: string, configEntry: ComponentConfigEntry): GeneratedComponentOptions;
+    /**
+     * 注册组件并用配置初始化
+     *
+     * 便捷方法：注册组件并通过 ConfigComponent 初始化。
+     *
+     * @param component 要注册的组件实例
+     * @param configEntry 组件配置项
+     */
+    registerComponentWithConfig(component: Component, configEntry: ComponentConfigEntry): Promise<void>;
+    /**
+     * 从配置文件初始化整个环境
+     *
+     * 加载服务配置，注册并初始化所有配置的组件。
+     *
+     * @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+     */
+    initFromConfig(configPath: string): Promise<void>;
+}

package/dist/env/lark-mention-utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 飞书消息 <at> 提及语法规范化工具
+ *
+ * ## 背景
+ *
+ * LLM 在生成消息时经常使用自闭合 XML 语法 `<at user_id="ou_xxx"/>` 来表达 @-mention，
+ * 但飞书 API 实际只识别 **带显式结束标签** 的形式：
+ *   - `<at user_id="ou_xxx">name</at>` — 带显示名
+ *   - `<at user_id="ou_xxx"></at>` — 空显示名（仍然会触发 @ 通知）
+ *
+ * 自闭合形式 `<at user_id="ou_xxx"/>` 会被飞书当作 **纯文本字面量** 展示，
+ * 收件人既看不到 mention，也不会收到通知。
+ *
+ * ## 解决方案
+ *
+ * 在发消息前调用 `normalizeLarkAtMentions(content)`，把所有自闭合 `<at>` 转为标准
+ * `<at user_id="..."></at>` 形式。如果调用方传入了 userId → name 的映射表，
+ * 还会把显示名填进去（更好的视觉提示）。
+ *
+ * ## 参考
+ *
+ * - lark-im skill: `lark-cli skills read lark-im/references/lark-im-messages-send.md`
+ *   "## @Mention Format" 章节
+ *   - `text`: `<at user_id="ou_xxx">name</at>` (inner optional, `<at user_id="ou_xxx"></at>` works)
+ *   - `post` + `md`: 同 text 的 inline form
+ *   - `post` + `at` element: `{"tag":"at","user_id":"ou_xxx"}`
+ *   - @all: `<at user_id="all"></at>`
+ */
+/**
+ * 规范化消息中的飞书 @-mention 语法
+ *
+ * 把 LLM 经常输出的自闭合形式 `<at user_id="ou_xxx"/>` 转换为飞书识别的
+ * 标准形式 `<at user_id="ou_xxx"></at>`，触发实际的 @ 通知。
+ *
+ * @param content 原始 markdown 消息文本
+ * @param nameMap 可选的 userId → displayName 映射；如果提供，会把名字填到
+ *                `<at>` 内部，让收件人看到"@张三"而不是"@"
+ * @returns 规范化后的内容
+ *
+ * @example
+ * // 基础用法：自闭合 → 空闭合
+ * normalizeLarkAtMentions('<at user_id="ou_123"/>收到')
+ * // → '<at user_id="ou_123"></at>收到'
+ *
+ * @example
+ * // 带名字映射
+ * normalizeLarkAtMentions(
+ *   '<at user_id="ou_123"/>收到',
+ *   new Map([['ou_123', '张三']])
+ * )
+ * // → '<at user_id="ou_123">张三</at>收到'
+ */
+export declare function normalizeLarkAtMentions(content: string, nameMap?: ReadonlyMap<string, string>): string;
+/**
+ * 检测消息内容是否包含飞书 mention 语法（任何形式）
+ *
+ * 用于调试/日志：在 send 之前打印"包含 N 个 mention"，方便 trace。
+ */
+export declare function countLarkMentions(content: string): number;

package/dist/env/llm/adapter-ai-sdk.d.ts

@@ -0,0 +1,10 @@
+import type { LLMAdapter, ChatRequest, ChatResponse, StreamHandle, ResolvedProvider, EmbedRequest, EmbedResponse } from "./adapter";
+export declare class AiSdkAdapter implements LLMAdapter {
+    readonly name: "ai-sdk";
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): Promise<StreamHandle>;
+    embed(req: EmbedRequest): Promise<EmbedResponse>;
+    resolveProvider(provider: string, modelId: string): Promise<ResolvedProvider>;
+    private toInvokeConfig;
+    private toInvokeOptions;
+}

package/dist/env/llm/adapter-pi-ai.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview PiAiAdapter — 包装 @earendil-works/pi-ai。
+ *
+ * 这是 roy-agent 默认的 LLM 适配层（ROY_LLM_PROVIDER=pi-ai 时启用）。
+ * 把 ChatRequest / ChatResponse / StreamHandle 翻译成 pi-ai 的
+ * complete() / stream() / getModel() 三件套。
+ *
+ * 关键映射：
+ * - provider/modelId → getModel(provider, modelId)
+ * - LLMMessage[] → pi-ai Context.messages
+ * - AssistantMessage.stopReason → ChatResponse.finishReason
+ * - usage {input, output, totalTokens} → UsageInfo
+ */
+import { type Model, type Context } from "@earendil-works/pi-ai";
+import type { LLMAdapter, ChatRequest, ChatResponse, StreamHandle, ResolvedProvider, EmbedRequest, EmbedResponse } from "./adapter";
+import type { LLMMessage, ToolInfo } from "./types";
+/**
+ * Resolve built-in models and models declared by roy-agent configuration.
+ * pi-ai's generated registry only contains its bundled provider/model pairs;
+ * custom provider ids (for example minimax-openai) need a complete Model
+ * descriptor before complete()/stream() can dispatch by API.
+ */
+export declare function resolvePiModel(provider: string, modelId: string, baseURL?: string): Model<any>;
+/**
+ * 将 LLMMessage 转换为 pi-ai 的消息结构
+ */
+export declare function toPiMessages(messages: LLMMessage[]): Context["messages"];
+export declare function extractSystemPrompt(messages: LLMMessage[]): string | undefined;
+export declare function toPiTools(tools: ToolInfo[] | undefined): Context["tools"];
+export declare class EmbeddingNotSupportedError extends Error {
+    constructor(adapter: string);
+}
+export declare class PiAiAdapter implements LLMAdapter {
+    readonly name: "pi-ai";
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): Promise<StreamHandle>;
+    embed(_req: EmbedRequest): Promise<EmbedResponse>;
+    resolveProvider(provider: string, modelId: string): Promise<ResolvedProvider>;
+}