pulse-coder-engine 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/index.d.cts

@@ -0,0 +1,573 @@
+import { C as ClarificationRequest, T as Tool, L as LLMProviderFactory, S as SystemPromptOption, E as EngineHookMap, a as Context, b as ToolExecutionContext, c as EnginePluginLoadOptions, d as ToolHooks, I as ILogger, P as PlanMode, e as EngineHookName } from './index-BeWyLfso.cjs';
+export { A as AfterLLMCallInput, f as AfterRunInput, g as AfterToolCallInput, h as AfterToolCallResult, B as BeforeLLMCallInput, i as BeforeLLMCallResult, j as BeforeRunInput, k as BeforeRunResult, l as BeforeToolCallInput, m as BeforeToolCallResult, n as BuiltInPlanModeService, o as BuiltInSkillRegistry, p as EnginePlugin, q as EnginePluginContext, M as ModePolicy, r as PlanIntentLabel, s as PlanModeEvent, t as PlanModeEventName, u as PlanModeService, v as PlanModeTransitionResult, w as ToolCategory, x as ToolMeta, y as ToolRisk, z as builtInMCPPlugin, D as builtInPlanModePlugin, F as builtInPlugins, G as builtInSkillsPlugin } from './index-BeWyLfso.cjs';
+import { StepResult, ModelMessage, ToolSet, streamText, Tool as Tool$1 } from 'ai';
+import { z } from 'zod';
+import 'events';
+
+/**
+ * Hook arrays passed into the loop by Engine.
+ * Each array may contain handlers from multiple plugins + EngineOptions.
+ */
+interface LoopHooks {
+    beforeLLMCall?: Array<EngineHookMap['beforeLLMCall']>;
+    afterLLMCall?: Array<EngineHookMap['afterLLMCall']>;
+    beforeToolCall?: Array<EngineHookMap['beforeToolCall']>;
+    afterToolCall?: Array<EngineHookMap['afterToolCall']>;
+}
+interface LoopOptions {
+    onText?: (delta: string) => void;
+    onToolCall?: (toolCall: any) => void;
+    onToolResult?: (toolResult: any) => void;
+    onStepFinish?: (step: StepResult<any>) => void;
+    onClarificationRequest?: (request: ClarificationRequest) => Promise<string>;
+    onCompacted?: (newMessages: ModelMessage[]) => void;
+    onResponse?: (messages: StepResult<ToolSet>['response']['messages']) => void;
+    abortSignal?: AbortSignal;
+    tools?: Record<string, Tool>;
+    /** Custom LLM provider factory. Overrides the default provider when set. */
+    provider?: LLMProviderFactory;
+    /** Model name passed to the provider. Overrides DEFAULT_MODEL when set. */
+    model?: string;
+    /** Custom system prompt. See SystemPromptOption for the three supported forms. */
+    systemPrompt?: SystemPromptOption;
+    /** Engine hook arrays – managed by Engine, not by callers directly. */
+    hooks?: LoopHooks;
+}
+declare function loop(context: Context, options?: LoopOptions): Promise<string>;
+
+/**
+ * 用户配置插件接口 - 面向终端用户
+ * 使用声明式配置扩展引擎能力
+ */
+interface UserConfigPlugin {
+    version: string;
+    name?: string;
+    description?: string;
+    tools?: Record<string, ToolConfig>;
+    mcp?: {
+        servers: MCPServerConfig[];
+    };
+    prompts?: {
+        system?: string;
+        user?: string;
+        assistant?: string;
+    };
+    subAgents?: SubAgentConfig[];
+    skills?: {
+        directories?: string[];
+        autoScan?: boolean;
+        cache?: boolean;
+    };
+    env?: Record<string, string>;
+    conditions?: {
+        environment?: string;
+        features?: string[];
+    };
+}
+/**
+ * 工具配置接口
+ */
+declare const ToolConfigSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        bash: "bash";
+        http: "http";
+        javascript: "javascript";
+        skill: "skill";
+        custom: "custom";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodAny>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    method: z.ZodOptional<z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+        PATCH: "PATCH";
+    }>>;
+    url: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodAny>;
+    params: z.ZodOptional<z.ZodAny>;
+    data: z.ZodOptional<z.ZodAny>;
+    code: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    conditions: z.ZodOptional<z.ZodObject<{
+        environment: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ToolConfig = z.infer<typeof ToolConfigSchema>;
+/**
+ * MCP 服务器配置接口
+ */
+declare const MCPServerConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodAny>;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+/**
+ * 子代理配置接口
+ */
+declare const SubAgentConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    trigger: z.ZodArray<z.ZodString>;
+    prompt: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type SubAgentConfig = z.infer<typeof SubAgentConfigSchema>;
+/**
+ * 用户配置插件加载选项
+ */
+interface UserConfigPluginLoadOptions {
+    configs?: UserConfigPlugin[];
+    dirs?: string[];
+    scan?: boolean;
+}
+
+interface StreamOptions {
+    abortSignal?: AbortSignal;
+    onStepFinish?: (event: StepResult<any>) => void;
+    onChunk?: (event: {
+        chunk: any;
+    }) => void;
+    toolExecutionContext?: ToolExecutionContext;
+    /** Custom LLM provider. Falls back to the default CoderAI provider when not set. */
+    provider?: LLMProviderFactory;
+    /** Model name to pass to the provider. Falls back to DEFAULT_MODEL when not set. */
+    model?: string;
+    /** Custom system prompt. See SystemPromptOption for the three supported forms. */
+    systemPrompt?: SystemPromptOption;
+}
+declare const streamTextAI: (messages: ModelMessage[], tools: Record<string, Tool>, options?: StreamOptions) => ReturnType<typeof streamText> & {
+    steps: StepResult<any>[];
+    finishReason: string;
+};
+
+type CompactResult = {
+    didCompact: boolean;
+    reason?: string;
+    newMessages?: ModelMessage[];
+};
+declare const maybeCompactContext: (context: Context, options?: {
+    force?: boolean;
+    provider?: LLMProviderFactory;
+    model?: string;
+}) => Promise<CompactResult>;
+
+interface ClarifyInput {
+    question: string;
+    context?: string;
+    defaultAnswer?: string;
+    timeout?: number;
+}
+interface ClarifyOutput {
+    answer: string;
+    timedOut: boolean;
+}
+declare const ClarifyTool: Tool<ClarifyInput, ClarifyOutput>;
+
+declare const ReadTool: Tool<{
+    filePath: string;
+    offset?: number;
+    limit?: number;
+}, {
+    content: string;
+    totalLines?: number;
+}>;
+
+declare const WriteTool: Tool<{
+    filePath: string;
+    content: string;
+}, {
+    success: boolean;
+    created: boolean;
+    bytes: number;
+}>;
+
+declare const EditTool: Tool<{
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}, {
+    success: boolean;
+    replacements: number;
+    preview?: string;
+}>;
+
+declare const GrepTool: Tool<{
+    pattern: string;
+    path?: string;
+    glob?: string;
+    type?: string;
+    outputMode?: 'content' | 'files_with_matches' | 'count';
+    context?: number;
+    caseInsensitive?: boolean;
+    headLimit?: number;
+    offset?: number;
+    multiline?: boolean;
+}, {
+    output: string;
+    matches?: number;
+}>;
+
+declare const LsTool: Tool<{
+    path?: string;
+}, {
+    files: string[];
+}>;
+
+declare const BashTool: Tool<{
+    command: string;
+    timeout?: number;
+    cwd?: string;
+    description?: string;
+}, {
+    output: string;
+    error?: string;
+    exitCode?: number;
+}>;
+
+declare const TavilyTool: Tool<{
+    query: string;
+    maxResults?: number;
+}, {
+    results: Array<{
+        title: string;
+        url: string;
+        content: string;
+        score?: number;
+    }>;
+}>;
+
+declare const BuiltinTools: readonly [Tool<{
+    filePath: string;
+    offset?: number;
+    limit?: number;
+}, {
+    content: string;
+    totalLines?: number;
+}>, Tool<{
+    filePath: string;
+    content: string;
+}, {
+    success: boolean;
+    created: boolean;
+    bytes: number;
+}>, Tool<{
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}, {
+    success: boolean;
+    replacements: number;
+    preview?: string;
+}>, Tool<{
+    pattern: string;
+    path?: string;
+    glob?: string;
+    type?: string;
+    outputMode?: "content" | "files_with_matches" | "count";
+    context?: number;
+    caseInsensitive?: boolean;
+    headLimit?: number;
+    offset?: number;
+    multiline?: boolean;
+}, {
+    output: string;
+    matches?: number;
+}>, Tool<{
+    path?: string;
+}, {
+    files: string[];
+}>, Tool<{
+    command: string;
+    timeout?: number;
+    cwd?: string;
+    description?: string;
+}, {
+    output: string;
+    error?: string;
+    exitCode?: number;
+}>, Tool<{
+    query: string;
+    maxResults?: number;
+}, {
+    results: Array<{
+        title: string;
+        url: string;
+        content: string;
+        score?: number;
+    }>;
+}>, Tool<ClarifyInput, ClarifyOutput>];
+declare const BuiltinToolsMap: Record<string, any>;
+declare const getFinalToolsMap: (customTools?: Record<string, Tool$1>) => Record<string, any>;
+
+/**
+ * 引擎配置选项
+ */
+interface EngineOptions {
+    enginePlugins?: EnginePluginLoadOptions;
+    userConfigPlugins?: UserConfigPluginLoadOptions;
+    disableBuiltInPlugins?: boolean;
+    config?: Record<string, any>;
+    /**
+     * 自定义 LLM Provider。
+     * 接收模型名称，返回 Vercel AI SDK LanguageModel 实例。
+     * 未设置时使用环境变量配置的默认 Provider（OpenAI / Anthropic）。
+     *
+     * @example
+     * import { createOpenAI } from '@ai-sdk/openai';
+     * const engine = new Engine({
+     *   llmProvider: createOpenAI({ apiKey: 'sk-...', baseURL: 'https://my-proxy/v1' }).chat,
+     *   model: 'gpt-4o',
+     * });
+     */
+    llmProvider?: LLMProviderFactory;
+    /**
+     * 模型名称，传递给 llmProvider。未设置时使用 DEFAULT_MODEL。
+     */
+    model?: string;
+    /**
+     * 直接注册自定义工具，无需创建 EnginePlugin。
+     * 这些工具会与内置工具以及插件注册的工具合并。
+     * 若与内置工具同名，自定义工具优先级更高。
+     *
+     * @example
+     * import { z } from 'zod';
+     * const engine = new Engine({
+     *   tools: {
+     *     myTool: {
+     *       name: 'myTool',
+     *       description: '查询内部数据库',
+     *       inputSchema: z.object({ query: z.string() }),
+     *       execute: async ({ query }) => fetchFromDB(query),
+     *     },
+     *   },
+     * });
+     */
+    tools?: Record<string, Tool>;
+    /**
+     * 自定义 System Prompt，三种形式：
+     * - `string` — 完全替换内置 prompt
+     * - `() => string` — 工厂函数，每次请求调用（支持动态 prompt）
+     * - `{ append: string }` — 在内置 prompt 末尾追加业务上下文
+     *
+     * @example
+     * const engine = new Engine({
+     *   systemPrompt: { append: '公司规范：所有变量使用 camelCase。禁止使用 any 类型。' },
+     * });
+     */
+    systemPrompt?: SystemPromptOption;
+    /**
+     * Tool 执行钩子，在每次工具调用前/后触发。
+     * - `onBeforeToolCall` 可以修改入参，或抛错来拦截调用。
+     * - `onAfterToolCall` 可以修改返回值（如脱敏、截断）。
+     *
+     * Backward-compatible shorthand — internally converted to
+     * beforeToolCall / afterToolCall engine hooks.
+     *
+     * @example
+     * const engine = new Engine({
+     *   hooks: {
+     *     onBeforeToolCall: (name, input) => {
+     *       if (name === 'bash') throw new Error('bash 工具已被禁用');
+     *     },
+     *     onAfterToolCall: (name, input, output) => {
+     *       auditLogger.log({ name, input, output });
+     *       return output;
+     *     },
+     *   },
+     * });
+     */
+    hooks?: ToolHooks;
+    /**
+     * 自定义日志实现。未设置时使用 console.*。
+     * 兼容 winston / pino 等主流日志库。
+     *
+     * @example
+     * import pino from 'pino';
+     * const logger = pino();
+     * const engine = new Engine({ logger });
+     */
+    logger?: ILogger;
+}
+/**
+ * 重构后的引擎类
+ * 自动包含内置插件，支持可选禁用
+ */
+declare class Engine {
+    private pluginManager;
+    private tools;
+    private options;
+    private config;
+    constructor(options?: EngineOptions);
+    /**
+     * 初始化引擎和插件系统
+     * 自动包含内置插件
+     */
+    initialize(): Promise<void>;
+    /**
+     * 准备引擎插件列表（包含内置插件）
+     */
+    private prepareEnginePlugins;
+    /**
+     * Collect all hooks for a given loop invocation.
+     * Merges plugin hooks with the legacy EngineOptions.hooks (ToolHooks).
+     */
+    private collectLoopHooks;
+    /**
+     * 运行AI循环
+     */
+    run(context: Context, options?: LoopOptions): Promise<string>;
+    /**
+     * 获取插件状态
+     */
+    getPluginStatus(): {
+        enginePlugins: string[];
+        userConfigPlugins: string[];
+        tools: string[];
+        hooks: {
+            [k: string]: number;
+        };
+        services: string[];
+    };
+    /**
+     * 获取工具
+     */
+    getTools(): Record<string, any>;
+    /**
+     * 获取服务
+     */
+    getService<T>(name: string): T | undefined;
+    /**
+     * 获取 plan mode 服务
+     */
+    private getPlanModeService;
+    /**
+     * 获取当前模式
+     */
+    getMode(): PlanMode | undefined;
+    /**
+     * 设置当前模式
+     */
+    setMode(mode: PlanMode, reason?: string): boolean;
+    /**
+     * 获取配置
+     */
+    getConfig<T>(key: string): T | undefined;
+    /**
+     * 设置配置
+     */
+    setConfig<T>(key: string, value: T): void;
+}
+
+/**
+ * 插件管理器 - 管理双轨插件系统
+ */
+declare class PluginManager {
+    private enginePlugins;
+    private userConfigPlugins;
+    private tools;
+    private hooks;
+    private services;
+    private config;
+    private events;
+    private logger;
+    constructor(logger?: ILogger);
+    /**
+     * 初始化插件系统
+     */
+    initialize(options?: {
+        enginePlugins?: EnginePluginLoadOptions;
+        userConfigPlugins?: UserConfigPluginLoadOptions;
+    }): Promise<void>;
+    /**
+     * 加载引擎插件
+     */
+    private loadEnginePlugins;
+    /**
+     * 扫描引擎插件目录
+     */
+    private scanEnginePlugins;
+    /**
+     * 加载单个引擎插件文件
+     */
+    private loadEnginePluginFile;
+    /**
+     * 初始化单个引擎插件
+     */
+    private initializeEnginePlugin;
+    /**
+     * 加载用户配置插件
+     */
+    private loadUserConfigPlugins;
+    /**
+     * 扫描用户配置插件目录
+     */
+    private scanUserConfigPlugins;
+    /**
+     * 加载单个用户配置文件
+     */
+    private loadUserConfigFile;
+    /**
+     * 应用用户配置
+     */
+    private applyUserConfig;
+    /**
+     * 验证核心能力
+     *
+     * - requiredCapabilities: 任意一个别名匹配即可，缺失时 **抛错** 阻止启动。
+     * - recommendedCapabilities: 缺失时仅 warn，不影响启动。
+     */
+    private validateCoreCapabilities;
+    /**
+     * 插件依赖排序
+     */
+    private sortPluginsByDependencies;
+    /**
+     * 工具获取
+     */
+    getTools(): Record<string, any>;
+    /**
+     * 获取指定类型的 hook 处理函数数组
+     */
+    getHooks<K extends EngineHookName>(hookName: K): Array<EngineHookMap[K]>;
+    /**
+     * 服务获取
+     */
+    getService<T>(name: string): T | undefined;
+    /**
+     * 获取插件状态
+     */
+    getStatus(): {
+        enginePlugins: string[];
+        userConfigPlugins: string[];
+        tools: string[];
+        hooks: {
+            [k: string]: number;
+        };
+        services: string[];
+    };
+    /**
+     * 解析路径（支持 ~ 和相对路径）
+     */
+    private resolvePath;
+}
+
+export { BashTool, BuiltinTools, BuiltinToolsMap, ClarificationRequest, ClarifyTool, Context, EditTool, Engine, EngineHookMap, EngineHookName, GrepTool, ILogger, LLMProviderFactory, LsTool, PlanMode, PluginManager, Engine as PulseAgent, ReadTool, SystemPromptOption, TavilyTool, Tool, ToolExecutionContext, ToolHooks, type UserConfigPlugin, type UserConfigPluginLoadOptions, WriteTool, getFinalToolsMap, loop, maybeCompactContext, streamTextAI };