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

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

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Commands Component Types
+ *
+ * 定义 CommandsComponent 的类型系统（收藏式）
+ */
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * CommandsComponent 配置（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface CommandsComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "COMMAND"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<CommandsComponentConfig>;
+}
+/**
+ * CommandsComponent 配置
+ */
+export interface CommandsComponentConfig {
+    /** User 级别命令目录 */
+    userCommandsDir?: string;
+    /** 项目级别命令目录 */
+    projectCommandsDir?: string;
+    /** 描述缓存目录 */
+    cacheDir?: string;
+}
+/**
+ * 命令来源
+ */
+export type CommandSource = 'user' | 'project';
+/**
+ * 命令索引
+ */
+export interface CommandIndex {
+    /** 命令名称（文件名） */
+    name: string;
+    /** 命令路径 */
+    path: string;
+    /** 来源类型 */
+    source: CommandSource;
+    /** 简短描述（从 --help 第一行提取） */
+    shortDescription: string;
+    /** 最后获取描述时间 */
+    lastFetched?: number;
+}
+/**
+ * 来源统计
+ */
+export interface SourceStats {
+    /** User 级别命令数 */
+    userCount: number;
+    /** Project 级别命令数 */
+    projectCount: number;
+}
+/**
+ * 扫描结果
+ */
+export interface ScanResult {
+    /** 命令列表 */
+    commands: CommandIndex[];
+    /** 来源统计 */
+    stats: SourceStats;
+}
+/**
+ * 发现选项
+ */
+export interface DiscoverOptions {
+    /** glob 过滤模式 */
+    pattern?: string;
+    /** 来源过滤 */
+    source?: CommandSource;
+}
+/**
+ * 添加命令选项
+ */
+export interface AddCommandOptions {
+    /** 命令名称 */
+    name: string;
+    /** 目标路径或命令 */
+    target: string;
+    /** 来源类型 */
+    source?: CommandSource;
+    /** 功能描述（用于 Prompt 注入） */
+    description?: string;
+    /** 探索提示（用于 Prompt 注入） */
+    tips?: string;
+}
+/**
+ * 命令元信息（用于 Prompt 注入）
+ */
+export interface CommandMeta {
+    /** 命令名称 */
+    name: string;
+    /** 功能描述 */
+    description: string;
+    /** 探索提示 */
+    tips?: string;
+    /** meta.md 文件路径 */
+    filePath: string;
+    /** 来源类型 */
+    source: CommandSource;
+}
+/**
+ * 移除命令选项
+ */
+export interface RemoveCommandOptions {
+    /** 命令名称 */
+    name: string;
+    /** 来源类型（可选，不指定则尝试两个目录） */
+    source?: CommandSource;
+}
+/**
+ * 执行结果
+ */
+export interface ExecutionResult {
+    /** 标准输出 */
+    stdout: string;
+    /** 标准错误 */
+    stderr: string;
+    /** 退出码 */
+    exitCode: number;
+    /** 是否成功 */
+    success: boolean;
+}

package/dist/env/component.d.ts

@@ -0,0 +1,186 @@
+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;
+}

package/dist/env/constants.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @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;
+};
+/**
+ * 「工具不可用」错误判定 —— 单一事实来源。
+ *
+ * 语义：工具**根本不存在**（未注册 / 被 allowedTools|deniedTools 过滤 / 被禁用），
+ * 属于「prompt 承诺的工具 ≠ 实际工具表」的**配置错误**，必须显式可见
+ * （2026-10-16 空 checkpoint 事故正是因为这类失败被静默吞掉）。
+ *
+ * 刻意**不**覆盖工具自身的运行时失败（bash exit!=0、grep 无匹配、文件不存在等），
+ * 那些是正常运行时结果，标成 ERROR 会让 trace 被红色噪音淹没、反而掩盖真问题。
+ *
+ * 消费方：AgentComponent.executeTool / ToolComponent.execute 的 @TracedAs errorIf。
+ */
+export declare const TOOL_UNAVAILABLE_ERROR_RE: RegExp;
+export declare function isToolUnavailableError(message: unknown): boolean;
+/**
+ * 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];