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

package/dist/env/plugin/notification-channel.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Notification Channel Abstraction
+ *
+ * Plugin 通知通道抽象。Plugin 通过 `PluginEnv.notify(options)` 发送通知，
+ * PluginComponent 负责把通知路由到已注册的 NotificationChannel 实例。
+ *
+ * ## 默认实现
+ *
+ * `EventBusNotificationChannel` —— 默认通道，把通知转成 roy-agent 自身
+ * `env.pushEnvEvent` 事件，事件命名空间 `plugin.notification.<type>`，
+ * metadata.source 固定为 `plugin:<pluginName>`。
+ *
+ * ## Legacy 实现（@deprecated）
+ *
+ * `LarkCliNotificationChannel` —— 历史默认通道，直接通过 `lark-cli` 子进程
+ * 发飞书消息。保留为可选/opt-in；标记为 @deprecated，新代码请用
+ * `EventBusNotificationChannel`，配合 env-level event subscriber 自定义
+ * 飞书投递逻辑。
+ *
+ * ## 自定义通道
+ *
+ * 实现 `NotificationChannel` 接口，并通过 `PluginComponent.setNotificationChannels()`
+ * 注入。PluginComponent 按 channels 数组顺序选第一个 `canRoute() === true` 的通道。
+ *
+ * @example
+ * ```ts
+ * // 1. 自定义通道（IM-implementable）
+ * class WebhookChannel implements NotificationChannel {
+ *   readonly name = "webhook";
+ *   canRoute(opts, extras, ctx) { return !!ctx.replyChannel?.params?.webhookUrl; }
+ *   async send(opts, extras, ctx) { await fetch(...); }
+ * }
+ *
+ * // 2. 注册到 PluginComponent
+ * component.setNotificationChannels([
+ *   new WebhookChannel(),
+ *   EventBusNotificationChannel(),  // 兜底
+ * ]);
+ * ```
+ */
+/**
+ * EnvContext 简化视图（通道只用 replyChannel，传入最小必需字段即可）。
+ *
+ * 通过 `getEnvContextOrEmpty()` 获取当前 ALS 中的 EnvContext。
+ */
+export interface EnvContextLike {
+    /** Reply channel（IM 通道路由信息） */
+    replyChannel?: {
+        /** 渠道类型，如 lark-cli, bounty-im */
+        type?: string;
+        /** app ID */
+        appId?: string;
+        /** chat ID */
+        chatId?: string;
+        /** message ID（用于 reply） */
+        messageId?: string;
+        /** raw command（IM 场景下的原始指令） */
+        rawCommand?: string;
+        /**
+         * lark-cli profile（多 appId 场景下指定用哪个 lark-cli profile 发消息）
+         *
+         * 当 replyChannel.type 含 'lark' 时，LarkCliNotificationChannel 会读取此字段
+         * 决定是否在 args 头部插入 `--profile <name>` flag。
+         */
+        profile?: string;
+        /** 其他参数（由 EventSource 注入） */
+        params?: Record<string, unknown>;
+    };
+}
+/**
+ * Plugin 调用 `env.notify(options)` 时传入的选项。
+ *
+ * 设计原则：
+ * - `type` 是必填的"通知类型"，EventBus 通道会把它转换成
+ *   `plugin.notification.<type>` 事件
+ * - `title` / `content` 是人类可读的展示文本（IM 通知渲染用）
+ * - `metadata` 是结构化扩展字段（透传到 event.metadata 中）
+ */
+export interface NotificationOptions {
+    /**
+     * 通知类型（必填）
+     *
+     * 推荐使用下划线分隔的 snake_case，例如：
+     * - "visualization_ready"
+     * - "task_completed"
+     * - "report_uploaded"
+     */
+    type: string;
+    /** 通知标题 */
+    title: string;
+    /** 通知内容（人类可读文本，可包含 markdown） */
+    content: string;
+    /** 额外元数据（透传到 event.metadata） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * PluginComponent 调用 `channel.send(options, extras, envContext)` 时附带的额外信息。
+ *
+ * PluginChannel 不需要知道是哪个 Plugin 在调用 — extras 提供必要的绑定信息。
+ */
+export interface NotificationSendExtras {
+    /** Plugin 名称（用于 metadata.source = `plugin:<pluginName>`） */
+    pluginName: string;
+    /**
+     * Environment 实例（用于 EventBusNotificationChannel 调用 pushEnvEvent）
+     *
+     * 在单测场景或某些 PluginContext 下可能为 undefined；EventBusNotificationChannel
+     * 应当 silent skip 而不是抛错。
+     */
+    envInstance?: {
+        pushEnvEvent(event: unknown): void;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Notification Channel - Plugin 通知通道抽象
+ *
+ * PluginComponent 按 channels 数组顺序选第一个 `canRoute() === true` 的通道。
+ * 如果所有通道都返回 false，则通知被丢弃（log warn）。
+ */
+export interface NotificationChannel {
+    /** 通道名称（log / debug 用） */
+    readonly name: string;
+    /**
+     * 当前 channel 是否能处理这条通知
+     *
+     * @param options 通知选项
+     * @param extras PluginComponent 注入的上下文
+     * @param envContext 当前 ALS 中的 EnvContext（可能为空）
+     */
+    canRoute(options: NotificationOptions, extras: NotificationSendExtras, envContext: EnvContextLike): boolean;
+    /**
+     * 发送通知
+     *
+     * - 实现方负责 swallow 内部异常，避免污染 Plugin 主流程
+     * - 应当支持并发调用（不同 Plugin 异步触发）
+     *
+     * @param options 通知选项
+     * @param extras PluginComponent 注入的上下文
+     * @param envContext 当前 ALS 中的 EnvContext（可能为空）
+     */
+    send(options: NotificationOptions, extras: NotificationSendExtras, envContext: EnvContextLike): Promise<void>;
+}

package/dist/env/plugin/plugin-component.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview PluginComponent - 统一插件管理组件
+ *
+ * 提供统一的插件注册、注销、查询接口
+ */
+import { BaseComponent, type ComponentConfig } from "../component";
+import { BasePlugin } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+import type { NotificationChannel } from "./notification-channel";
+/**
+ * 从 resolvedPath（指向 plugin 入口文件）向上查找最近的 package.json 并读取 version。
+ *
+ * **Task #2903 修复说明（version drift）**：
+ * 实际加载的 plugin 代码可能与 plugins.json 声明的 version 不一致 —
+ * 例如 `~/.roy-agent/node_modules/@scope/pkg/index.js` 是旧版 cp 副本
+ * （v2.5.7），但 plugins.json 记的是新版本（v2.5.9）。这个 helper 通过
+ * 入口路径找到最近的 package.json，读出真实 version，给上层做对比。
+ *
+ * 算法：从 resolvedPath 所在目录开始，向上走 dir.parent 直到文件系统根，
+ *          命中第一个 package.json 即返回。
+ *
+ * 找不到 / 解析失败 → 返回 null（不抛异常）。
+ *
+ * 导出供测试调用。
+ */
+export declare function readActualVersion(resolvedPath: string): string | null;
+/**
+ * 对比 declared version vs loaded version，不一致时 warn。
+ *
+ * **Task #2903 修复说明（startup warn）**：
+ * PluginComponent 启动时遍历 plugins.json，对每个插件做一次 version drift 校验。
+ * 如果 loaded version 找不到（resolvedPath 无效），返回 { drifted: false } —
+ * 这种情况下 import 都成功了，version 字段缺失是 plugin 自己的问题，不归我们管。
+ *
+ * 返回结构：
+ *   { declared, actual, resolvedPath, drifted }
+ *
+ * - declared: plugins.json 声明的 version
+ * - actual: 磁盘上 plugin 入口的 package.json 实际 version（找不到 = null）
+ * - resolvedPath: 传入的入口路径（透传，方便用户诊断）
+ * - drifted: actual != null && actual !== declared
+ *
+ * 如果 logger 提供且 drifted=true，会调 logger.warn 输出一行 warning。
+ * warning 包含 packageName（推断自 resolvedPath 末段）、declared、actual、resolvedPath。
+ *
+ * 导出供测试调用。
+ */
+export interface VersionDriftLogger {
+    warn: (msg: string) => void;
+}
+export declare function checkVersionDrift(declaredVersion: string, resolvedPath: string, logger?: VersionDriftLogger): {
+    declared: string;
+    actual: string | null;
+    resolvedPath: string;
+    drifted: boolean;
+};
+/**
+ * PluginComponent 配置选项
+ */
+export interface PluginComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "PLUGIN"）*/
+    envPrefix?: string;
+}
+/**
+ * PluginComponent - 统一插件管理组件
+ *
+ * 功能：
+ * - 管理所有插件的注册和生命周期
+ * - 提供统一的 PluginEnv 给每个插件
+ * - 通过 --plugin 参数加载的插件都注册到此组件
+ */
+export declare class PluginComponent extends BaseComponent {
+    name: string;
+    version: string;
+    /** 插件注册表 */
+    private registry;
+    /** 组件引用缓存 */
+    private componentCache;
+    /** 日志器 */
+    private logger;
+    /** ConfigComponent 引用 */
+    private configComponent?;
+    /**
+     * NotificationChannel 列表（按顺序遍历，第一个 canRoute=true 的被选中）
+     *
+     * 默认 = [EventBusNotificationChannel()]
+     *
+     * LarkCliNotificationChannel（legacy）不在默认列表中 —— 它是 opt-in，
+     * 需要通过 setNotificationChannels() 显式注册。
+     */
+    private notificationChannels;
+    constructor();
+    /**
+     * Initialize the component
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 从 ~/.roy-agent/plugins.json 读取并加载已安装的插件
+     *
+     * 对每个插件：
+     * 1. 通过 import(packageName) 动态导入插件模块
+     * 2. 调用 register() 注册
+     */
+    private loadInstalledPlugins;
+    /**
+     * 从已安装的 npm 包加载插件
+     *
+     * 通过 import(packageName) 动态导入插件模块
+     * 插件模块应导出实现了 BasePlugin 接口的实例
+     *
+     * 支持多种导出方式：
+     * - default export: 插件实例 / 类
+     * - named export 'plugin': 插件实例 / 类
+     *
+     * 类型检查：优先 instanceof BasePlugin（内部插件），fallback 到 duck-type（外部插件）
+     * duck-type 要求：name (string) + init (function) + 可选 dispose (function)
+     *
+     * **Task #2903 修复说明（version drift warn）**：
+     * 加载成功后，如果传入 declaredVersion，对比实际加载的 plugin 入口的
+     * package.json version，不一致就 warn（带 resolvedPath 帮助用户诊断）。
+     *
+     * **Task #2908 修复说明（npm global root fallback）**：
+     * import(packageName) 默认不解析 npm global root（不在 Node 模块解析路径
+     * 中），所以 `roy-agent install --global <pkg>` 后 `roy-agent run` 永远
+     * 找不到 plugin。修复：在 PRIMARY import() 失败后的 fallback chain 头部
+     * 插入 npm global root 查询（`npm root -g`）。
+     *
+     * 完整加载顺序（new）：
+     *   PRIMARY: import(packageName)            (Node default resolution)
+     *   失败 → fallback chain:
+     *     1. <npm global root>/<packageName>/  ← NEW (Task #2899 authoritative)
+     *     2. ./.roy/plugins/<packageName>/     (project local)
+     *     3. ~/.roy-agent/node_modules/<pkg>/  (cp copy — deprecated but kept for back-compat)
+     */
+    private loadPluginFromPackage;
+    /**
+     * 注册插件
+     *
+     * 创建 PluginEnv 并调用 plugin.init()
+     *
+     * @param plugin - 要注册的插件实例
+     * @throws 如果插件名称已存在
+     */
+    register(plugin: BasePlugin): Promise<void>;
+    /**
+     * 注销插件
+     *
+     * 调用 plugin.dispose() 并从注册表移除
+     *
+     * @param name - 插件名称
+     * @returns 是否成功注销
+     */
+    unregister(name: string): boolean;
+    /**
+     * 获取插件
+     *
+     * @param name - 插件名称
+     * @returns 插件实例，如果不存在则返回 undefined
+     */
+    get(name: string): BasePlugin | undefined;
+    /**
+     * 获取所有插件
+     *
+     * @returns 插件数组
+     */
+    list(): BasePlugin[];
+    /**
+     * 检查插件是否已注册
+     *
+     * @param name - 插件名称
+     */
+    has(name: string): boolean;
+    /**
+     * 获取插件配置
+     *
+     * Overload 1: 无参 → 返回组件自身配置（继承自 BaseComponent.getConfig）
+     * Overload 2: 带 name → 返回指定插件配置
+     *
+     * @param name - 插件名称
+     * @returns 插件配置，如果不存在则返回 undefined
+     */
+    getConfig(): ComponentConfig;
+    getConfig(name: string): any;
+    /**
+     * 批量注册插件
+     *
+     * @param plugins - 插件数组
+     */
+    registerAll(plugins: BasePlugin[]): Promise<void>;
+    /**
+     * 设置 NotificationChannel 列表
+     *
+     * PluginComponent 按数组顺序选第一个 canRoute=true 的通道处理 notify 调用。
+     *
+     * 传空数组 → 禁用所有通知通道（notify 会成为 noop）。
+     *
+     * @example
+     * ```ts
+     * // 完全替换默认
+     * component.setNotificationChannels([
+     *   new EventBusNotificationChannel(),
+     *   new LarkCliNotificationChannel(),  // opt-in legacy
+     * ]);
+     * ```
+     */
+    setNotificationChannels(channels: NotificationChannel[]): void;
+    /**
+     * 获取当前 NotificationChannel 名称列表
+     */
+    getNotificationChannelNames(): string[];
+    /**
+     * 把 notify 调用路由到第一个 canRoute=true 的 channel
+     *
+     * - channel 异常被 swallow（不污染 Plugin 主流程）
+     * - 所有 channel 都不路由 → log warn（不影响 notify 调用方）
+     */
+    private routeNotification;
+    /**
+     * 停止组件
+     *
+     * 调用所有已注册插件的 dispose() 方法
+     */
+    stop(): Promise<void>;
+    /**
+     * 创建 PluginEnv
+     */
+    private createPluginEnv;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview Unified Plugin System Types
+ *
+ * 统一插件接口定义
+ */
+import type { HookContext, HookResult } from "../hook/types";
+import type { ILogger as Logger } from "../log-trace/logger";
+import type { NotificationOptions } from "./notification-channel";
+/**
+ * Hook 处理函数
+ */
+export type HookHandler = (ctx: HookContext) => void | Promise<void> | HookResult | Promise<HookResult>;
+/**
+ * Hook 定义
+ */
+export interface HookDefinition {
+    /** Hook 点名称 */
+    point: string;
+    /** 优先级（数字越大越先执行，默认 0）*/
+    priority?: number;
+    /** 处理函数 */
+    handler: HookHandler;
+}
+/**
+ * Plugin 环境接口
+ *
+ * 注入到每个 Plugin 的统一环境
+ */
+export interface PluginEnv {
+    /** 获取组件 */
+    getComponent<T>(name: string): T | undefined;
+    /** 注册 Agent */
+    registerAgent(config: AgentInstanceConfig): void;
+    /** 注册 Tool */
+    registerTool(tool: ToolDefinition): void;
+    /** 注册 Hook */
+    registerHook(hook: HookDefinition): void;
+    /**
+     * 发送通知
+     *
+     * Plugin 调用此方法发出"通知"，由 PluginComponent 路由到已注册的
+     * NotificationChannel（默认 EventBusNotificationChannel）。
+     *
+     * 注意：
+     * - 此方法不抛错（channel.send 异常会被 swallow）
+     * - 如果没有任何 channel 能路由（canRoute 全 false），通知被丢弃
+     *
+     * @example
+     * ```ts
+     * await env.notify({
+     *   type: "visualization_ready",
+     *   title: "Viz Ready",
+     *   content: "Chart rendered",
+     *   metadata: { taskId: 42 },
+     * });
+     * ```
+     */
+    notify(options: NotificationOptions): Promise<void>;
+    /** 日志器 */
+    logger: Logger;
+}
+/**
+ * Agent 实例配置（Plugin 注册时需要）
+ */
+export interface AgentInstanceConfig {
+    name: string;
+    description?: string;
+    systemPrompt?: string;
+    tools?: string[];
+    model?: string;
+    maxIterations?: number;
+}
+/**
+ * Tool 定义（Plugin 注册时需要）
+ */
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    parameters?: any;
+    handler: (...args: any[]) => any;
+}
+/**
+ * Plugin 基类
+ *
+ * 所有插件都必须继承此类或实现相同接口
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin {
+ *   readonly name = "my-plugin";
+ *   readonly version = "1.0.0";
+ *
+ *   constructor(config?: MyConfig) {
+ *     super();
+ *     this.config = config;
+ *   }
+ *
+ *   init(env: PluginEnv): void {
+ *     env.registerHook({
+ *       point: "agent:before.llm",
+ *       handler: this.onBeforeLLM.bind(this),
+ *     });
+ *   }
+ *
+ *   private async onBeforeLLM(ctx: HookContext): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BasePlugin {
+    /** 插件唯一名称 */
+    abstract readonly name: string;
+    /** 插件版本 */
+    readonly version: string;
+    /** 插件描述 */
+    readonly description?: string;
+    /** 插件优先级（数字越大优先级越高，默认 0）*/
+    readonly priority: number;
+    /**
+     * 构造函数
+     *
+     * 子类可覆盖以接收配置参数
+     */
+    constructor();
+    /**
+     * 初始化
+     *
+     * 在插件注册到 PluginComponent 时调用
+     * - 获取依赖组件
+     * - 注册 Hooks
+     * - 注册 Agents/Tools
+     *
+     * @param env - Plugin 环境
+     */
+    init(env: PluginEnv): void | Promise<void>;
+    /**
+     * 销毁
+     *
+     * 在插件注销时调用
+     * - 清理资源
+     * - 关闭连接
+     */
+    dispose(): void | Promise<void>;
+}
+export type { HookContext, HookResult } from "../hook/types";

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview PromptComponent 导出
+ */
+export { PromptComponent, type PromptComponentOptions } from "./prompt-component";
+export { PromptRenderer } from "./renderer";
+export type { PromptConfig, PromptPath, PromptEntry, PromptSource, PromptHook, RenderHookContext, PromptHookMap, } from "./types";
+export { PromptConfigSchema, PromptPathSchema } from "./types";