@ai-setting/roy-agent-cli 1.3.14 → 1.3.16

package/dist/core/src/env/component.d.ts

@@ -0,0 +1,187 @@
+import { ZodType, ZodTypeDef } from "zod";
+import type { Environment } from "./interface";
+import { HookManager, createHook, createPriorityHook } from "./hook";
+import type { Hook, HookContext, HookPhase, HookMeta, HookFn, HookManagerOptions } from "./hook";
+export type { Hook, HookContext, HookPhase, HookMeta, HookFn, HookManagerOptions };
+export { HookManager, createHook, createPriorityHook };
+/**
+ * Component 状态
+ */
+export type ComponentStatus = "created" | "initializing" | "running" | "stopping" | "stopped" | "error";
+/**
+ * Component 配置
+ */
+export interface ComponentConfig {
+    name: string;
+    version: string;
+    enabled: boolean;
+    options?: Record<string, unknown>;
+    /**
+     * Environment 实例（可选）
+     *
+     * 推荐在 init 时接收 env 实例，以便：
+     * - 通过 env.getComponent() 获取其他组件
+     * - 通过 env.pushEnvEvent() 发布事件
+     * - 通过 env.handle_query() 处理查询
+     *
+     * 如果未提供，部分 Component 仍可正常工作（如测试场景）
+     *
+     * @example
+     * ```typescript
+     * async onInit(): Promise<void> {
+     *   if (this.env) {
+     *     const configComp = this.env.getComponent("config");
+     *   }
+     * }
+     * ```
+     */
+    env?: Environment;
+}
+/**
+ * Component 路径声明
+ */
+export interface ComponentPaths {
+    base: "config" | "state" | "data" | "cache";
+    subPath: string;
+    isDirectory: boolean;
+}
+/**
+ * Component Schema（注册配置）
+ */
+export interface ComponentSchema {
+    /** Component 名称 */
+    name: string;
+    /** 配置 Schema（Zod） */
+    schema: ZodType<unknown, ZodTypeDef, unknown>;
+    /** 默认值（从 Schema 提取） */
+    defaults: Record<string, unknown>;
+    /** 路径声明 */
+    paths?: Record<string, ComponentPaths>;
+    /** 元信息 */
+    metadata?: {
+        description?: string;
+        version?: string;
+        author?: string;
+    };
+}
+/**
+ * Component 配置变更事件
+ */
+export interface ComponentConfigChangeEvent {
+    /** Component 名称 */
+    component: string;
+    /** 变更的配置键 */
+    key: string;
+    /** 旧值 */
+    oldValue: unknown;
+    /** 新值 */
+    newValue: unknown;
+    /** 是否持久化 */
+    persisted: boolean;
+    /** 时间戳 */
+    timestamp: number;
+}
+/**
+ * Component 配置监听回调
+ */
+export type ComponentWatchCallback = (event: ComponentConfigChangeEvent) => void | Promise<void>;
+/**
+ * Component 基类接口
+ */
+export interface Component {
+    /** Component 名称 */
+    readonly name: string;
+    /** Component 版本 */
+    readonly version: string;
+    /** 获取状态 */
+    getStatus(): ComponentStatus;
+    /** 获取配置 */
+    getConfig(): ComponentConfig;
+    /** 初始化 */
+    init(config: ComponentConfig): Promise<void>;
+    /** 启动 */
+    start(): Promise<void>;
+    /** 停止 */
+    stop(): Promise<void>;
+}
+/**
+ * Component 基类实现
+ */
+export declare abstract class BaseComponent implements Component {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    protected _status: ComponentStatus;
+    protected _enabled: boolean;
+    protected env: Environment;
+    /** Hook 管理器 - 子类初始化时由构造函数设置 */
+    readonly hookManager: HookManager;
+    constructor();
+    getStatus(): ComponentStatus;
+    getConfig(): ComponentConfig;
+    /**
+     * 检查 Environment 是否已初始化
+     */
+    protected isEnvInitialized(): boolean;
+    protected setStatus(status: ComponentStatus): void;
+    /**
+     * 获取 Environment 实例
+     */
+    protected getEnv(): Environment;
+    init(config?: ComponentConfig): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * 子类可覆盖的钩子方法
+     */
+    protected onInit(): Promise<void>;
+    protected onStart(): Promise<void>;
+    protected onStop(): Promise<void>;
+    /**
+     * 注册 Hook
+     *
+     * @param hookPoint Hook 点名称
+     * @param hook Hook 实例
+     */
+    protected registerHook<T = unknown>(hookPoint: string, hook: Hook<T>): void;
+    /**
+     * 便捷方法：快速注册 Hook
+     */
+    protected addHook<T = unknown>(hookPoint: string, name: string, fn: HookFn<T>, priority?: number): void;
+    /**
+     * 便捷方法：按名称取消注册 Hook
+     */
+    protected removeHook(hookPoint: string, name: string): boolean;
+    /**
+     * 执行 Hook
+     */
+    protected executeHooks<T = unknown>(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * 获取 ConfigComponent 实例
+     *
+     * 子类可使用此方法获取配置组件，支持热更新
+     */
+    protected getConfigComponent(): {
+        get(key: string): unknown;
+    } | undefined;
+    /**
+     * 动态获取运行时配置值
+     *
+     * 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+     * 适用于运行时可能变化的配置（如 API Keys、模型参数）
+     *
+     * @param key 配置键（支持点号分隔的路径，如 "llm.temperature"）
+     * @param defaultValue 默认值
+     * @returns 配置值或默认值
+     *
+     * @example
+     * ```typescript
+     * // 获取 LLM 温度配置（可能支持热更新）
+     * const temperature = this.getRuntimeConfig("llm.temperature", 0.7);
+     *
+     * // 获取 API Key
+     * const apiKey = this.getRuntimeConfig<string>("llm.providers.openai.apiKey");
+     * ```
+     */
+    protected getRuntimeConfig<T>(key: string, defaultValue: T): T;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/core/src/env/component.js

@@ -0,0 +1,160 @@
+// 导入 Hook 系统
+import { HookManager, createHook, createPriorityHook } from "./hook/index.js";
+export { HookManager, createHook, createPriorityHook };
+/**
+ * Component 基类实现
+ */
+export class BaseComponent {
+    _status = "created";
+    _enabled = true;
+    env; // 非可选，使用 definite assignment assertion
+    /** Hook 管理器 - 子类初始化时由构造函数设置 */
+    hookManager;
+    constructor() {
+        // 创建 HookManager，稍后在 init 中更新组件信息
+        this.hookManager = new HookManager();
+    }
+    getStatus() {
+        return this._status;
+    }
+    getConfig() {
+        return {
+            name: this.name,
+            version: this.version,
+            enabled: this._enabled,
+            env: this.env,
+        };
+    }
+    /**
+     * 检查 Environment 是否已初始化
+     */
+    isEnvInitialized() {
+        return this._status !== "created";
+    }
+    setStatus(status) {
+        this._status = status;
+    }
+    /**
+     * 获取 Environment 实例
+     */
+    getEnv() {
+        return this.env;
+    }
+    async init(config) {
+        // 如果提供了 env，则注入
+        if (config?.env) {
+            this.env = config.env;
+        }
+        this.setStatus("initializing");
+        // 只有当 name/version 未在子类中定义时才从 config 注入
+        // 注意：如果子类已定义这些属性，Object.defineProperty 会失败
+        try {
+            if (config?.name)
+                Object.defineProperty(this, "name", { value: config.name, writable: false });
+            if (config?.version)
+                Object.defineProperty(this, "version", { value: config.version, writable: false });
+        }
+        catch {
+            // 忽略错误（属性可能已在子类中定义）
+        }
+        if (config?.enabled !== undefined)
+            this._enabled = config.enabled;
+        // 更新 HookManager 的组件信息
+        this.hookManager.setComponentInfo(this.name, this.version);
+        await this.onInit();
+        this.setStatus("running");
+    }
+    async start() {
+        // 使用内部标志跟踪 start() 是否已调用
+        // 这是必要的，因为 init() 会将状态设为 "running"，但组件的 start() 仍需被调用
+        if (this._started)
+            return;
+        this._started = true;
+        await this.onStart();
+        this.setStatus("running");
+    }
+    async stop() {
+        this.setStatus("stopping");
+        // 清理 Hooks
+        this.hookManager.clear();
+        await this.onStop();
+        this.setStatus("stopped");
+    }
+    /**
+     * 子类可覆盖的钩子方法
+     */
+    async onInit() { }
+    async onStart() { }
+    async onStop() { }
+    // ========================================================================
+    // Hook 便捷方法
+    // ========================================================================
+    /**
+     * 注册 Hook
+     *
+     * @param hookPoint Hook 点名称
+     * @param hook Hook 实例
+     */
+    registerHook(hookPoint, hook) {
+        this.hookManager.register(hookPoint, hook);
+    }
+    /**
+     * 便捷方法：快速注册 Hook
+     */
+    addHook(hookPoint, name, fn, priority) {
+        this.hookManager.register(hookPoint, createHook({ name, priority }, fn));
+    }
+    /**
+     * 便捷方法：按名称取消注册 Hook
+     */
+    removeHook(hookPoint, name) {
+        return this.hookManager.unregister(hookPoint, name);
+    }
+    /**
+     * 执行 Hook
+     */
+    async executeHooks(hookPoint, data, metadata) {
+        await this.hookManager.execute(hookPoint, data, metadata);
+    }
+    // ========================================================================
+    // 配置统一管理方法
+    // ========================================================================
+    /**
+     * 获取 ConfigComponent 实例
+     *
+     * 子类可使用此方法获取配置组件，支持热更新
+     */
+    getConfigComponent() {
+        return this.env?.getComponent("config");
+    }
+    /**
+     * 动态获取运行时配置值
+     *
+     * 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+     * 适用于运行时可能变化的配置（如 API Keys、模型参数）
+     *
+     * @param key 配置键（支持点号分隔的路径，如 "llm.temperature"）
+     * @param defaultValue 默认值
+     * @returns 配置值或默认值
+     *
+     * @example
+     * ```typescript
+     * // 获取 LLM 温度配置（可能支持热更新）
+     * const temperature = this.getRuntimeConfig("llm.temperature", 0.7);
+     *
+     * // 获取 API Key
+     * const apiKey = this.getRuntimeConfig<string>("llm.providers.openai.apiKey");
+     * ```
+     */
+    getRuntimeConfig(key, defaultValue) {
+        const configComponent = this.getConfigComponent();
+        if (configComponent) {
+            const value = configComponent.get(key);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+        return defaultValue;
+    }
+}
+//# sourceMappingURL=component.js.map

package/dist/core/src/env/constants.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview 统一常量定义
+ *
+ * 定义事件名称和错误消息常量，避免硬编码字符串
+ */
+/**
+ * Agent 相关事件名称
+ */
+export declare const AgentEvents: {
+    readonly RUN_START: "agent.run.start";
+    readonly RUN_COMPLETE: "agent.run.complete";
+    readonly RUN_ERROR: "agent.run.error";
+    readonly TOOL_CALLED: "agent.tool.called";
+    readonly TOOL_RESULT: "agent.tool.result";
+    readonly LLM_REQUEST: "agent.llm.request";
+    readonly LLM_RESPONSE: "agent.llm.response";
+    readonly ITERATION_START: "agent.iteration.start";
+    readonly ITERATION_COMPLETE: "agent.iteration.complete";
+};
+/**
+ * Tool 相关事件名称
+ */
+export declare const ToolEvents: {
+    readonly EXECUTE_START: "tool.execute.start";
+    readonly EXECUTE_COMPLETE: "tool.execute.complete";
+    readonly EXECUTE_ERROR: "tool.execute.error";
+    readonly REGISTERED: "tool.registered";
+    readonly UNREGISTERED: "tool.unregistered";
+};
+/**
+ * Component 生命周期事件名称
+ */
+export declare const ComponentEvents: {
+    readonly INIT_START: "component.init.start";
+    readonly INIT_COMPLETE: "component.init.complete";
+    readonly START: "component.start";
+    readonly STOP: "component.stop";
+};
+/**
+ * Session 相关事件名称
+ */
+export declare const SessionEvents: {
+    readonly CREATED: "session.created";
+    readonly DELETED: "session.deleted";
+    readonly MESSAGE_ADDED: "session.message.added";
+};
+/**
+ * Agent 错误消息
+ */
+export declare const AgentErrorMessages: {
+    readonly notFound: (name: string) => string;
+    readonly alreadyRunning: (name: string) => string;
+    readonly notRunning: (name: string) => string;
+    readonly runFailed: (name: string, reason?: string) => string;
+};
+/**
+ * Tool 错误消息
+ */
+export declare const ToolErrorMessages: {
+    readonly notFound: (name: string) => string;
+    readonly disabled: (name: string) => string;
+    readonly executionFailed: (name: string, reason?: string) => string;
+    readonly validationFailed: (name: string, reason?: string) => string;
+};
+/**
+ * LLM 错误消息
+ */
+export declare const LLMErrorMessages: {
+    readonly providerNotFound: (provider: string) => string;
+    readonly apiKeyMissing: (provider: string) => string;
+    readonly invocationFailed: (provider: string, reason?: string) => string;
+    readonly timeout: (provider: string) => string;
+};
+/**
+ * Component 错误消息
+ */
+export declare const ComponentErrorMessages: {
+    readonly notFound: (name: string) => string;
+    readonly notRegistered: (name: string) => string;
+    readonly notRunning: (name: string) => string;
+    readonly initFailed: (name: string, reason?: string) => string;
+};
+/**
+ * 检查是否是 Agent 事件
+ */
+export declare function isAgentEvent(event: string): event is typeof AgentEvents[keyof typeof AgentEvents];
+/**
+ * 检查是否是 Tool 事件
+ */
+export declare function isToolEvent(event: string): event is typeof ToolEvents[keyof typeof ToolEvents];
+/**
+ * 检查是否是 Component 事件
+ */
+export declare function isComponentEvent(event: string): event is typeof ComponentEvents[keyof typeof ComponentEvents];
+/**
+ * 检查是否是 Session 事件
+ */
+export declare function isSessionEvent(event: string): event is typeof SessionEvents[keyof typeof SessionEvents];
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/src/env/constants.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview 统一常量定义
+ *
+ * 定义事件名称和错误消息常量，避免硬编码字符串
+ */
+/**
+ * Agent 相关事件名称
+ */
+export const AgentEvents = {
+    RUN_START: "agent.run.start",
+    RUN_COMPLETE: "agent.run.complete",
+    RUN_ERROR: "agent.run.error",
+    TOOL_CALLED: "agent.tool.called",
+    TOOL_RESULT: "agent.tool.result",
+    LLM_REQUEST: "agent.llm.request",
+    LLM_RESPONSE: "agent.llm.response",
+    ITERATION_START: "agent.iteration.start",
+    ITERATION_COMPLETE: "agent.iteration.complete",
+};
+/**
+ * Tool 相关事件名称
+ */
+export const ToolEvents = {
+    EXECUTE_START: "tool.execute.start",
+    EXECUTE_COMPLETE: "tool.execute.complete",
+    EXECUTE_ERROR: "tool.execute.error",
+    REGISTERED: "tool.registered",
+    UNREGISTERED: "tool.unregistered",
+};
+/**
+ * Component 生命周期事件名称
+ */
+export const ComponentEvents = {
+    INIT_START: "component.init.start",
+    INIT_COMPLETE: "component.init.complete",
+    START: "component.start",
+    STOP: "component.stop",
+};
+/**
+ * Session 相关事件名称
+ */
+export const SessionEvents = {
+    CREATED: "session.created",
+    DELETED: "session.deleted",
+    MESSAGE_ADDED: "session.message.added",
+};
+/**
+ * Agent 错误消息
+ */
+export const AgentErrorMessages = {
+    notFound: (name) => `Agent not found: ${name}`,
+    alreadyRunning: (name) => `Agent ${name} is already running`,
+    notRunning: (name) => `Agent ${name} is not running`,
+    runFailed: (name, reason) => reason ? `Agent ${name} run failed: ${reason}` : `Agent ${name} run failed`,
+};
+/**
+ * Tool 错误消息
+ */
+export const ToolErrorMessages = {
+    notFound: (name) => `Tool not found: ${name}`,
+    disabled: (name) => `Tool ${name} is disabled`,
+    executionFailed: (name, reason) => reason ? `Tool ${name} execution failed: ${reason}` : `Tool ${name} execution failed`,
+    validationFailed: (name, reason) => reason ? `Tool ${name} validation failed: ${reason}` : `Tool ${name} validation failed`,
+};
+/**
+ * LLM 错误消息
+ */
+export const LLMErrorMessages = {
+    providerNotFound: (provider) => `LLM provider not found: ${provider}`,
+    apiKeyMissing: (provider) => `API key missing for provider: ${provider}`,
+    invocationFailed: (provider, reason) => reason ? `LLM ${provider} invocation failed: ${reason}` : `LLM ${provider} invocation failed`,
+    timeout: (provider) => `LLM ${provider} invocation timeout`,
+};
+/**
+ * Component 错误消息
+ */
+export const ComponentErrorMessages = {
+    notFound: (name) => `Component not found: ${name}`,
+    notRegistered: (name) => `Component ${name} is not registered`,
+    notRunning: (name) => `Component ${name} is not running`,
+    initFailed: (name, reason) => reason ? `Component ${name} init failed: ${reason}` : `Component ${name} init failed`,
+};
+/**
+ * 检查是否是 Agent 事件
+ */
+export function isAgentEvent(event) {
+    return event.startsWith("agent.");
+}
+/**
+ * 检查是否是 Tool 事件
+ */
+export function isToolEvent(event) {
+    return event.startsWith("tool.");
+}
+/**
+ * 检查是否是 Component 事件
+ */
+export function isComponentEvent(event) {
+    return event.startsWith("component.");
+}
+/**
+ * 检查是否是 Session 事件
+ */
+export function isSessionEvent(event) {
+    return event.startsWith("session.");
+}
+//# sourceMappingURL=constants.js.map

package/dist/core/src/env/constants.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=constants.test.d.ts.map

package/dist/core/src/env/constants.test.js

@@ -0,0 +1,55 @@
+import { describe, test, expect } from "bun:test";
+import { AgentEvents, AgentErrorMessages, ToolEvents, ToolErrorMessages, LLMErrorMessages, ComponentEvents, isAgentEvent, isToolEvent, } from "./constants.js";
+describe("常量定义", () => {
+    describe("AgentEvents", () => {
+        test("应该定义正确的事件名称", () => {
+            expect(AgentEvents.RUN_START).toBe("agent.run.start");
+            expect(AgentEvents.RUN_COMPLETE).toBe("agent.run.complete");
+            expect(AgentEvents.RUN_ERROR).toBe("agent.run.error");
+            expect(AgentEvents.TOOL_CALLED).toBe("agent.tool.called");
+            expect(AgentEvents.TOOL_RESULT).toBe("agent.tool.result");
+            expect(AgentEvents.LLM_REQUEST).toBe("agent.llm.request");
+            expect(AgentEvents.LLM_RESPONSE).toBe("agent.llm.response");
+        });
+    });
+    describe("ToolEvents", () => {
+        test("应该定义正确的事件名称", () => {
+            expect(ToolEvents.EXECUTE_START).toBe("tool.execute.start");
+            expect(ToolEvents.EXECUTE_COMPLETE).toBe("tool.execute.complete");
+            expect(ToolEvents.EXECUTE_ERROR).toBe("tool.execute.error");
+            expect(ToolEvents.REGISTERED).toBe("tool.registered");
+        });
+    });
+    describe("ComponentEvents", () => {
+        test("应该定义正确的事件名称", () => {
+            expect(ComponentEvents.INIT_START).toBe("component.init.start");
+            expect(ComponentEvents.INIT_COMPLETE).toBe("component.init.complete");
+            expect(ComponentEvents.STOP).toBe("component.stop");
+        });
+    });
+    describe("错误消息函数", () => {
+        test("AgentErrorMessages 应该生成正确的消息", () => {
+            expect(AgentErrorMessages.notFound("my-agent")).toBe("Agent not found: my-agent");
+            expect(AgentErrorMessages.alreadyRunning("my-agent")).toBe("Agent my-agent is already running");
+        });
+        test("ToolErrorMessages 应该生成正确的消息", () => {
+            expect(ToolErrorMessages.notFound("readFile")).toBe("Tool not found: readFile");
+            expect(ToolErrorMessages.disabled("writeFile")).toBe("Tool writeFile is disabled");
+        });
+        test("LLMErrorMessages 应该生成正确的消息", () => {
+            expect(LLMErrorMessages.providerNotFound("openai")).toBe("LLM provider not found: openai");
+            expect(LLMErrorMessages.apiKeyMissing("anthropic")).toBe("API key missing for provider: anthropic");
+        });
+    });
+    describe("类型守卫", () => {
+        test("isAgentEvent 应该正确识别 Agent 事件", () => {
+            expect(isAgentEvent("agent.run.start")).toBe(true);
+            expect(isAgentEvent("tool.execute.start")).toBe(false);
+        });
+        test("isToolEvent 应该正确识别 Tool 事件", () => {
+            expect(isToolEvent("tool.execute.start")).toBe(true);
+            expect(isToolEvent("agent.run.start")).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=constants.test.js.map