@ai-setting/roy-agent-cli 1.3.18 → 1.3.22

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

@@ -1,349 +0,0 @@
-/**
- * @fileoverview AgentComponent - Agent执行核心组件
- *
- * 基于 roy-agent docs/agent-component-design.md
- * 参考 agent-core Agent.run 实现
- *
- * 核心功能：
- * - ReAct 循环编排
- * - Hook 机制和 Plugin 扩展
- * - 多 Agent 管理
- * - 工具调用
- *
- * 依赖：
- * - ../llm - LLMComponent 用于 LLM 调用
- * - ../log-trace/logger - createLogger 用于日志
- */
-import { BaseComponent, type ComponentConfig } from "../component";
-import type { AgentInstance, AgentInstanceConfig, AgentRunResult, AgentContext, Plugin, Tool } from "./types";
-import type { ModelMessage } from "ai";
-import { z } from "zod";
-import type { ConfigComponent } from "../../config/config-component";
-/**
- * AgentComponent 配置 Schema
- */
-export declare const AgentComponentConfigSchema: z.ZodObject<{
-    defaultAgent: z.ZodObject<{
-        type: z.ZodDefault<z.ZodEnum<["primary", "sub"]>>;
-        systemPrompt: z.ZodOptional<z.ZodString>;
-        behaviorSpecId: z.ZodOptional<z.ZodString>;
-        model: z.ZodOptional<z.ZodString>;
-        maxIterations: z.ZodDefault<z.ZodNumber>;
-        maxErrorRetries: z.ZodDefault<z.ZodNumber>;
-        doomLoopThreshold: z.ZodDefault<z.ZodNumber>;
-        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        deniedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        toolTimeout: z.ZodDefault<z.ZodNumber>;
-        toolRetries: z.ZodDefault<z.ZodNumber>;
-        /** 是否过滤 history 中的 tool 消息（默认不过滤，保留完整上下文） */
-        filterHistory: z.ZodDefault<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
-        type?: "primary" | "sub";
-        model?: string;
-        maxIterations?: number;
-        systemPrompt?: string;
-        behaviorSpecId?: string;
-        maxErrorRetries?: number;
-        doomLoopThreshold?: number;
-        allowedTools?: string[];
-        deniedTools?: string[];
-        toolTimeout?: number;
-        toolRetries?: number;
-        filterHistory?: boolean;
-    }, {
-        type?: "primary" | "sub";
-        model?: string;
-        maxIterations?: number;
-        systemPrompt?: string;
-        behaviorSpecId?: string;
-        maxErrorRetries?: number;
-        doomLoopThreshold?: number;
-        allowedTools?: string[];
-        deniedTools?: string[];
-        toolTimeout?: number;
-        toolRetries?: number;
-        filterHistory?: boolean;
-    }>;
-}, "strip", z.ZodTypeAny, {
-    defaultAgent?: {
-        type?: "primary" | "sub";
-        model?: string;
-        maxIterations?: number;
-        systemPrompt?: string;
-        behaviorSpecId?: string;
-        maxErrorRetries?: number;
-        doomLoopThreshold?: number;
-        allowedTools?: string[];
-        deniedTools?: string[];
-        toolTimeout?: number;
-        toolRetries?: number;
-        filterHistory?: boolean;
-    };
-}, {
-    defaultAgent?: {
-        type?: "primary" | "sub";
-        model?: string;
-        maxIterations?: number;
-        systemPrompt?: string;
-        behaviorSpecId?: string;
-        maxErrorRetries?: number;
-        doomLoopThreshold?: number;
-        allowedTools?: string[];
-        deniedTools?: string[];
-        toolTimeout?: number;
-        toolRetries?: number;
-        filterHistory?: boolean;
-    };
-}>;
-export type AgentComponentConfig = z.infer<typeof AgentComponentConfigSchema>;
-/**
- * AgentComponent 配置选项（通过 options 传递）
- *
- * 配置加载顺序（优先级从低到高）：
- * 1. File - 配置文件（通过 configPath 指定）
- * 2. Env - 环境变量（通过 envPrefix 配置前缀）
- * 3. Object - 直接传入的 config 对象（最高优先级）
- */
-export interface AgentComponentOptions {
-    /** ConfigComponent 实例（必填） */
-    configComponent: ConfigComponent;
-    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
-    configPath?: string;
-    /** 环境变量前缀（可选，默认 "AGENT"） */
-    envPrefix?: string;
-    /** 直接传入的配置对象（可选，优先级最高） */
-    config?: Partial<AgentComponentConfig>;
-}
-/**
- * AgentComponent
- *
- * 提供 Agent 执行能力和 Hook 扩展机制
- */
-export declare class AgentComponent extends BaseComponent {
-    readonly name = "agent";
-    readonly version = "1.0.0";
-    private agents;
-    private config;
-    private llmComponent;
-    private toolComponent;
-    private aborted;
-    private abortControllers;
-    private defaultTools;
-    private doomLoopCaches;
-    /** ConfigComponent 用于配置管理 */
-    private configComponent?;
-    /** 配置变更 watcher 清理函数 */
-    private configWatcher?;
-    /** Session 消息转换器 */
-    private messageConverter;
-    /** 构造函数传入的配置（最高优先级） */
-    private _constructorConfig?;
-    /** Run ID 计数器（用于生成唯一的 runId） */
-    private runCounter;
-    constructor(options?: {
-        config?: Partial<AgentComponentConfig>;
-    });
-    /**
-     * 初始化组件
-     *
-     * 配置加载优先级（从高到低）：
-     * 1. Object - 直接传入的 config 对象
-     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
-     * 3. File - 配置文件（通过 configPath 指定）
-     */
-    init(config: ComponentConfig): Promise<void>;
-    /**
-     * 注册配置到 ConfigComponent
-     *
-     * 配置加载顺序（优先级从低到高）：
-     * 1. Defaults - 默认值（最低）
-     * 2. FileSource - 从配置文件加载
-     * 3. EnvSource - 从环境变量加载
-     * 4. config 对象 - 直接传入的配置（最高）
-     */
-    private registerConfig;
-    /**
-     * 将配置对象展平为点号路径
-     */
-    private flattenConfig;
-    /**
-     * 注册配置热更新监听
-     */
-    private registerConfigWatcher;
-    /**
-     * 处理配置变更
-     */
-    protected onConfigChange(event: {
-        key: string;
-        oldValue?: unknown;
-        newValue?: unknown;
-    }): void;
-    /**
-     * 组件停止时的清理逻辑
-     *
-     * 清理内容：
-     * 1. 终止所有正在运行的 Agent（调用 abort() 以中断 LLM 调用）
-     * 2. 清空 AbortController 注册表
-     * 3. 清空 Doom Loop 缓存
-     * 4. 取消配置变更监听
-     * 5. 清空 Agent 注册表
-     */
-    protected onStop(): Promise<void>;
-    /**
-     * 刷新依赖组件引用
-     *
-     * 当组件被添加到 Environment 后调用，以确保获取到最新的组件引用
-     */
-    refreshDependencies(): void;
-    /**
-     * 获取 Agent 实例
-     */
-    getAgent(agentName: string): AgentInstance | undefined;
-    /**
-     * 获取所有 Agent 实例
-     */
-    listAgents(): AgentInstance[];
-    /**
-     * Add placeholder tool results for remaining unprocessed tool calls
-     *
-     * This ensures that the message history maintains a 1:1 correspondence
-     * between tool-calls and tool-results, which is required by AI SDK v6.
-     *
-     * @param ctx - Hook context containing messages
-     * @param allToolCalls - All tool calls from the LLM response
-     * @param processedCount - Number of tool calls that have been processed
-     * @param reason - Reason for the abort/interruption
-     */
-    private addRemainingToolResults;
-    /**
-     * 注册 Agent
-     *
-     * 配置优先级（从高到低）：
-     * 1. registerAgent 传入的 config（来自 PromptComponent）
-     * 2. defaultAgent 配置（来自 ConfigComponent，作为 fallback）
-     */
-    registerAgent(name: string, config: Partial<AgentInstanceConfig>): AgentInstance;
-    /**
-     * 注销 Agent
-     */
-    unregisterAgent(name: string): boolean;
-    /**
-     * 注册 Plugin 到指定 Agent
-     */
-    registerPlugin(agentName: string, plugin: Plugin): void;
-    /**
-     * 注销 Plugin
-     */
-    unregisterPlugin(agentName: string, pluginName: string): boolean;
-    /**
-     * 设置默认工具列表
-     */
-    setDefaultTools(tools: Tool[]): void;
-    /**
-     * 获取可用工具
-     */
-    getAvailableTools(agent: AgentInstance, context?: AgentContext): Tool[];
-    /**
-     * 执行 Agent
-     *
-     * @param agentName Agent 名称
-     * @param query 用户查询
-     * @param context 执行上下文
-     * @returns Agent 执行结果
-     */
-    run(agentName: string, query: string, context?: AgentContext): Promise<AgentRunResult>;
-    private pushMessage;
-    /**
-     * 执行 Agent（核心方法，内部实现）
-     */
-    private _run;
-    /**
-     * 中止 Agent
-     *
-     * 调用此方法会：
-     * 1. 设置 aborted 标志（用于 ReAct 循环检查）
-     * 2. 触发 AbortController.abort()（用于中断正在进行的 LLM 调用）
-     *
-     * 注意：不直接修改 agent.status，由 _run() 的 finally 统一处理
-     */
-    abort(agentName: string): void;
-    /**
-     * 构建消息列表
-     *
-     * 注意：ctx.messages 已经包含了历史消息（包括 system prompt 和 user query）
-     * 这里只需要构建当前请求的消息，不重复添加
-     */
-    private buildMessages;
-    /**
-     * 调用 LLM
-     *
-     * 流式事件由 LLMComponent 通过 env.pushEnvEvent() 发布
-     */
-    private invokeLLM;
-    /**
-     * 执行工具
-     */
-    private executeTool;
-    /**
-     * 执行 Plugin Hooks (Agent 特有的 Hook 执行机制)
-     */
-    private executePluginHooks;
-    /**
-     * 处理 Hook 动作
-     */
-    private handleHookAction;
-    /**
-     * 通知消息添加（扩展点）
-     */
-    protected notifyMessageAdded(message: ModelMessage): void;
-    /**
-     * 结束结果
-     */
-    private finalizeResult;
-    /**
-     * Record messages to session
-     *
-     * 存储策略：
-     * 1. 存储 allMessages 中的所有 user、assistant、tool 消息
-     * 2. 跳过 system 消息
-     * 3. 跳过空内容的 assistant/tool 消息
-     */
-    private recordSessionMessages;
-    /**
-     * 检查消息内容是否为空
-     *
-     * 空内容定义：
-     * - 空字符串 ""
-     * - 空数组 []
-     * - null
-     * - undefined
-     *
-     * @param content - 消息内容
-     * @returns 是否为空
-     */
-    private isEmptyMessage;
-    /**
-     * 通过 Environment 发送事件
-     */
-    private pushEnvEvent;
-    /**
-     * 获取会话对话历史
-     *
-     * 核心逻辑：
-     * 1. 使用 sessionComponent.getContext() 获取消息（自动从 checkpoint 开始）
-     * 2. 根据 messageLimit 限制消息数量（向后兼容 minUserMessages）
-     * 3. 过滤掉 tool_call/tool_result 消息（如果 filterHistory=true）
-     *
-     * 关键改进：利用 checkpoint 概念，避免重复获取已压缩的历史消息，
-     * 从而减少重复触发压缩的问题。
-     *
-     * @param sessionComponent - SessionComponent 实例
-     * @param sessionId - 会话 ID
-     * @param options - 配置选项
-     * @param options.minUserMessages - 最少包含的 user 消息数量（默认 100）
-     * @param options.filterHistory - 是否过滤 tool 消息（默认 true）
-     * @returns 过滤后的会话消息列表
-     */
-    private getConversationHistory;
-}
-//# sourceMappingURL=agent-component.d.ts.map