hyacinth-ai 0.9.6

package/dist/provider/model-router.js

@@ -0,0 +1,87 @@
+import { ModelChannelRegistry } from './model-channel-registry.js';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('model-router');
+const DEFAULT_MODELS_CONFIG = {
+    assessment: { source: 'main' },
+    planning: { source: 'main' },
+    compression: { source: 'main' },
+};
+/**
+ * ModelRouter — N 通道模型路由系统。
+ *
+ * 根据角色返回对应的 Provider。内部委托给 ModelChannelRegistry，
+ * 后者管理 .agent/model-channels.json 配置文件。
+ *
+ * 向后兼容：无配置文件时自动从 legacy models + provider 配置构建双通道。
+ */
+export class ModelRouter {
+    registry;
+    mainProvider;
+    modelsConfig;
+    localConfig;
+    constructor(mainProvider, modelsConfig, localConfig, registry) {
+        this.mainProvider = mainProvider;
+        this.modelsConfig = modelsConfig ?? DEFAULT_MODELS_CONFIG;
+        this.localConfig = localConfig ?? {};
+        // 使用外部传入的 registry，否则从 legacy 构建
+        this.registry = registry ?? ModelChannelRegistry.fromLegacy(mainProvider, this.modelsConfig, this.localConfig);
+    }
+    /**
+     * 注入外部 ModelChannelRegistry（从 factory.ts 初始化后调用）。
+     * 调用后 registry 接管通道管理，本地的 modelsConfig/localConfig 不再使用。
+     */
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    /**
+     * 根据角色返回对应的 Provider。
+     * 委托给 ModelChannelRegistry，自动包含降级逻辑。
+     */
+    getProvider(role) {
+        const provider = this.registry.getProvider(role);
+        if (provider)
+            return provider;
+        // 最终 fallback
+        logger.warn(`No provider for role "${role}", falling back to main`);
+        return this.mainProvider;
+    }
+    /**
+     * 热重载配置：尝试从 model-channels.json 重载，
+     * 若无文件则从 legacy config 重建。
+     */
+    setConfig(modelsConfig, localConfig) {
+        if (modelsConfig)
+            this.modelsConfig = modelsConfig;
+        if (localConfig)
+            this.localConfig = localConfig;
+        // 尝试从 disk 重载，若无文件则从 legacy 重建
+        this.registry.reload(this.mainProvider);
+        // 如果 reload 没有找到文件，registry 保持原状，此时用 legacy 覆盖
+        if (this.registry.listChannelNames().length === 0) {
+            this.registry.buildFromLegacy(this.modelsConfig, this.localConfig);
+            this.registry.initializeChannels();
+        }
+    }
+    /**
+     * 热重载通道配置（直接从 ModelChannelsConfig 对象）。
+     */
+    reloadChannels(config) {
+        this.registry.reloadFromConfig(config, this.mainProvider);
+    }
+    /**
+     * 主 Provider 切换时更新引用。
+     */
+    setMainProvider(provider, providerType) {
+        this.mainProvider = provider;
+        this.registry.setMainProvider(provider, providerType);
+    }
+    /** 获取底层 registry（供外部查询） */
+    getRegistry() {
+        return this.registry;
+    }
+    /** 直接通过通道名获取 Provider（不经过角色映射） */
+    getChannelProvider(name) {
+        return this.registry.getChannelProvider(name);
+    }
+}
+//# sourceMappingURL=model-router.js.map

package/dist/provider/openai.d.ts

@@ -0,0 +1,54 @@
+import type { Message, StreamEvent, ProviderType, ProviderConfig, ToolDefinition } from '../types.js';
+import type { Provider, ProviderCapabilities } from './interface.js';
+/** OpenAIProvider 构造选项 */
+export interface OpenAIProviderOptions {
+    /** 必须提供 apiKey，或通过 OPENAI_API_KEY 环境变量自动读取 */
+    apiKey?: string;
+    /** 可选自定义 base URL（代理/兼容端点） */
+    baseUrl?: string;
+    /** 模型名称，默认 gpt-4o */
+    model?: string;
+    /** 单次请求最大输出 token 数。兼容旧键名 maxTokens。 */
+    maxOutputTokens?: number;
+    /** @deprecated 使用 maxOutputTokens */
+    maxTokens?: number;
+    /** 缓存隔离 ID，区分不同产品的缓存池。默认 "hyacinth"。 */
+    userId?: string;
+}
+/**
+ * OpenAI Provider — 通过 openai SDK 实现流式调用。
+ *
+ * 支持：
+ * - 流式返回 StreamEvent（TEXT / TOOL_USE / USAGE / STOP）
+ * - 自动将内部 Message 格式转换为 OpenAI ChatCompletion 格式
+ * - 支持 reasoning_content（部分兼容端点用于 thinking 输出）
+ */
+export declare class OpenAIProvider implements Provider {
+    private client;
+    private model;
+    private maxTokens;
+    private thinkingEnabled;
+    private userId;
+    constructor(opts?: OpenAIProviderOptions);
+    getProviderType(): ProviderType;
+    getModel(): string;
+    getCapabilities(): ProviderCapabilities;
+    setThinking(enabled: boolean): void;
+    setUserId(userId: string): void;
+    createStream(messages: Message[], tools?: ToolDefinition[], signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    /**
+     * 将内部 Message[] 转换为 OpenAI ChatCompletionMessageParam[]。
+     *
+     * 关键差异：
+     * - Anthropic 格式中 tool_result 是 user 消息内的 content block
+     * - OpenAI 格式中 tool_result 是独立的 role='tool' 消息
+     * - Anthropic 格式中 tool_use 是 assistant 消息内的 content block
+     * - OpenAI 格式中 tool_use 是 assistant 消息的 tool_calls 字段
+     */
+    private convertMessages;
+    /** 将内部 ToolDefinition[] 转换为 OpenAI ChatCompletionTool[] */
+    private convertTools;
+}
+/** 便捷工厂：从 ProviderConfig 创建 OpenAIProvider */
+export declare function createOpenAIProvider(config: ProviderConfig): OpenAIProvider;
+//# sourceMappingURL=openai.d.ts.map

package/dist/provider/openai.js

@@ -0,0 +1,274 @@
+import OpenAI from 'openai';
+import { getModelInfo } from './catalog.js';
+import { DEFAULT_USER_ID } from './user-id.js';
+import { recoverToolArguments, logToolArgsWarning } from './tool-args-recovery.js';
+/**
+ * OpenAI Provider — 通过 openai SDK 实现流式调用。
+ *
+ * 支持：
+ * - 流式返回 StreamEvent（TEXT / TOOL_USE / USAGE / STOP）
+ * - 自动将内部 Message 格式转换为 OpenAI ChatCompletion 格式
+ * - 支持 reasoning_content（部分兼容端点用于 thinking 输出）
+ */
+export class OpenAIProvider {
+    client;
+    model;
+    maxTokens;
+    thinkingEnabled = false;
+    userId;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass apiKey in options.');
+        }
+        this.client = new OpenAI({
+            apiKey,
+            baseURL: opts.baseUrl ?? process.env.OPENAI_BASE_URL,
+        });
+        this.model = opts.model ?? 'gpt-4o';
+        this.maxTokens = opts.maxOutputTokens // ① 临时覆盖
+            ?? opts.maxTokens // 向后兼容
+            ?? getModelInfo('openai', this.model)?.maxOutputTokens // ② 本机模型目录
+            ?? 8192; // ③ 兜底
+        this.userId = opts.userId ?? DEFAULT_USER_ID;
+    }
+    getProviderType() {
+        return 'openai';
+    }
+    getModel() {
+        return this.model;
+    }
+    getCapabilities() {
+        const info = getModelInfo('openai', this.model);
+        return {
+            toolCalling: true,
+            streaming: true,
+            adapterSupport: false,
+            maxContextTokens: info?.contextWindow ?? 128000,
+            isLocal: false,
+            vision: info?.capabilities.vision ?? false,
+        };
+    }
+    setThinking(enabled) {
+        this.thinkingEnabled = enabled;
+    }
+    setUserId(userId) {
+        this.userId = userId;
+    }
+    async *createStream(messages, tools, signal) {
+        // ---- 构建请求参数 ----
+        const openaiMessages = this.convertMessages(messages);
+        const params = {
+            model: this.model,
+            messages: openaiMessages,
+            max_tokens: this.maxTokens,
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        if (tools && tools.length > 0) {
+            params.tools = this.convertTools(tools);
+        }
+        // thinking 默认 enabled，必须显式发送 disabled 才能关闭
+        params.extra_body = {
+            thinking: { type: this.thinkingEnabled ? 'enabled' : 'disabled' },
+        };
+        // 缓存隔离：同一 key 下不同 user_id 各自维护缓存池
+        params.user_id = this.userId;
+        // ---- 流式消费 ----
+        // 追踪正在构建的 tool calls（OpenAI 的 tool call 是按 index 分片传输的）
+        const toolCallAccumulators = new Map();
+        try {
+            const stream = await this.client.chat.completions.create(params, { signal });
+            for await (const chunk of stream) {
+                const choice = chunk.choices?.[0];
+                // ---- 处理 usage（最后一个 chunk） ----
+                if (chunk.usage) {
+                    yield {
+                        type: 'USAGE',
+                        input_tokens: chunk.usage.prompt_tokens,
+                        output_tokens: chunk.usage.completion_tokens,
+                        cache_hit_tokens: chunk.usage.prompt_cache_hit_tokens,
+                        cache_miss_tokens: chunk.usage.prompt_cache_miss_tokens,
+                    };
+                }
+                if (!choice)
+                    continue;
+                const delta = choice.delta;
+                // ---- 处理 reasoning_content（thinking） ----
+                if ('reasoning_content' in delta &&
+                    typeof delta.reasoning_content === 'string') {
+                    yield { type: 'THINKING', content: delta.reasoning_content };
+                }
+                // ---- 处理文本内容 ----
+                if (delta.content) {
+                    yield { type: 'TEXT', content: delta.content };
+                }
+                // ---- 处理 tool calls ----
+                if (delta.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index;
+                        if (!toolCallAccumulators.has(idx)) {
+                            toolCallAccumulators.set(idx, {
+                                id: tc.id ?? '',
+                                name: tc.function?.name ?? '',
+                                arguments: '',
+                            });
+                        }
+                        const acc = toolCallAccumulators.get(idx);
+                        // 首个分片包含 id 和 name
+                        if (tc.id)
+                            acc.id = tc.id;
+                        if (tc.function?.name)
+                            acc.name = tc.function.name;
+                        if (tc.function?.arguments)
+                            acc.arguments += tc.function.arguments;
+                    }
+                }
+                // ---- 处理 finish_reason ----
+                if (choice.finish_reason) {
+                    // 先 emit 所有累积的 tool_use
+                    for (const [, acc] of toolCallAccumulators) {
+                        const raw = acc.arguments || '';
+                        const { recovered, complete, error } = recoverToolArguments(raw, acc.name);
+                        if (!complete) {
+                            logToolArgsWarning('openai', acc.name, raw, error);
+                        }
+                        yield {
+                            type: 'TOOL_USE',
+                            id: acc.id,
+                            name: acc.name,
+                            input: recovered,
+                        };
+                    }
+                    toolCallAccumulators.clear();
+                    yield { type: 'STOP', reason: choice.finish_reason };
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof OpenAI.APIError) {
+                throw new Error(`OpenAI API error (${error.status}): ${error.message}`);
+            }
+            if (error instanceof Error) {
+                throw new Error(`OpenAI stream error: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    // ---- 内部转换方法 ----
+    /**
+     * 将内部 Message[] 转换为 OpenAI ChatCompletionMessageParam[]。
+     *
+     * 关键差异：
+     * - Anthropic 格式中 tool_result 是 user 消息内的 content block
+     * - OpenAI 格式中 tool_result 是独立的 role='tool' 消息
+     * - Anthropic 格式中 tool_use 是 assistant 消息内的 content block
+     * - OpenAI 格式中 tool_use 是 assistant 消息的 tool_calls 字段
+     */
+    convertMessages(messages) {
+        const result = [];
+        for (const msg of messages) {
+            const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+            if (msg.role === 'assistant') {
+                // ---- assistant 消息 ----
+                const textParts = [];
+                const toolCalls = [];
+                let reasoningContent;
+                for (const block of blocks) {
+                    if (block.type === 'text') {
+                        textParts.push(block.text);
+                    }
+                    else if (block.type === 'tool_use') {
+                        toolCalls.push({
+                            id: block.id,
+                            type: 'function',
+                            function: {
+                                name: block.name,
+                                arguments: JSON.stringify(block.input),
+                            },
+                        });
+                    }
+                    else if (block.type === 'thinking') {
+                        reasoningContent = block.thinking;
+                    }
+                    // tool_result 不应出现在 assistant 消息中，跳过
+                }
+                const assistantMsg = {
+                    role: 'assistant',
+                    content: textParts.length > 0 ? textParts.join('') : (toolCalls.length > 0 ? '' : null),
+                };
+                if (toolCalls.length > 0) {
+                    assistantMsg.tool_calls = toolCalls;
+                }
+                // 思考模型要求 reasoning_content 回传
+                // 当 assistant 只有 tool_calls 时不添加，避免 API 冲突
+                if (reasoningContent !== undefined) {
+                    assistantMsg.reasoning_content = reasoningContent;
+                }
+                else if (toolCalls.length === 0) {
+                    assistantMsg.reasoning_content = '';
+                }
+                result.push(assistantMsg);
+            }
+            else {
+                // ---- user 消息 ----
+                // OpenAI 要求 role='tool' 消息紧跟在 assistant(tool_calls) 之后，
+                // 不能被 user 文本消息隔开。因此先推 tool_result，再推 user 文本。
+                const textParts = [];
+                const toolResults = [];
+                const imageParts = [];
+                for (const block of blocks) {
+                    if (block.type === 'text') {
+                        textParts.push(block.text);
+                    }
+                    else if (block.type === 'tool_result') {
+                        toolResults.push({
+                            role: 'tool',
+                            tool_call_id: block.tool_use_id,
+                            content: block.content,
+                        });
+                    }
+                    else if (block.type === 'image') {
+                        const url = block.source.type === 'base64'
+                            ? `data:${block.source.media_type};base64,${block.source.data}`
+                            : block.source.url;
+                        imageParts.push({ type: 'image_url', image_url: { url } });
+                    }
+                }
+                result.push(...toolResults);
+                if (imageParts.length > 0) {
+                    const content = [
+                        ...imageParts,
+                        ...(textParts.length > 0 ? [{ type: 'text', text: textParts.join('') }] : []),
+                    ];
+                    result.push({ role: 'user', content });
+                }
+                else if (textParts.length > 0) {
+                    result.push({ role: 'user', content: textParts.join('') });
+                }
+            }
+        }
+        return result;
+    }
+    /** 将内部 ToolDefinition[] 转换为 OpenAI ChatCompletionTool[] */
+    convertTools(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.input_schema,
+            },
+        }));
+    }
+}
+/** 便捷工厂：从 ProviderConfig 创建 OpenAIProvider */
+export function createOpenAIProvider(config) {
+    return new OpenAIProvider({
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        model: config.model,
+        userId: config.userId,
+    });
+}
+//# sourceMappingURL=openai.js.map

package/dist/provider/qwen.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Qwen (阿里百炼) Provider — Anthropic 兼容协议。
+ *
+ * 阿里百炼的 Anthropic 兼容端点接受标准 Anthropic Messages API 格式，
+ * 支持 cache_control、thinking、tool_use 等全部 Anthropic 特性。
+ *
+ * 端点: https://dashscope.aliyuncs.com/apps/anthropic
+ * 认证: x-api-key 头（DASHSCOPE_API_KEY）
+ */
+import { AnthropicProvider } from './anthropic.js';
+import type { ProviderConfig } from '../types.js';
+export declare function createQwenProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    maxOutputTokens?: number;
+}): AnthropicProvider;
+export declare function createQwenFromConfig(config: ProviderConfig): AnthropicProvider;
+//# sourceMappingURL=qwen.d.ts.map

package/dist/provider/qwen.js

@@ -0,0 +1,30 @@
+/**
+ * Qwen (阿里百炼) Provider — Anthropic 兼容协议。
+ *
+ * 阿里百炼的 Anthropic 兼容端点接受标准 Anthropic Messages API 格式，
+ * 支持 cache_control、thinking、tool_use 等全部 Anthropic 特性。
+ *
+ * 端点: https://dashscope.aliyuncs.com/apps/anthropic
+ * 认证: x-api-key 头（DASHSCOPE_API_KEY）
+ */
+import { AnthropicProvider } from './anthropic.js';
+import { getProviderConfigLoader } from './config.js';
+export function createQwenProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('qwen');
+    return new AnthropicProvider({
+        apiKey: config?.apiKey ?? process.env.DASHSCOPE_API_KEY,
+        baseUrl: config?.baseUrl ?? provCfg?.baseUrl ?? 'https://dashscope.aliyuncs.com/apps/anthropic',
+        model: config?.model ?? provCfg?.defaultModel ?? 'qwen3-vl-plus',
+        maxOutputTokens: config?.maxOutputTokens,
+        providerType: 'qwen',
+    });
+}
+export function createQwenFromConfig(config) {
+    return createQwenProvider({
+        apiKey: config.apiKey,
+        model: config.model,
+        baseUrl: config.baseUrl,
+        maxOutputTokens: config.maxOutputTokens,
+    });
+}
+//# sourceMappingURL=qwen.js.map

package/dist/provider/resilient.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ResilientProvider — wraps any Provider with retry + circuit breaker.
+ *
+ * Retry: exponential backoff (1s → 2s → 4s → 8s, max 4 retries)
+ *   - Retryable: network errors, 5xx, 429 (rate limit)
+ *   - Non-retryable: 4xx auth/validation errors
+ *
+ * Circuit breaker: after N consecutive failures, open for cooldown period.
+ *   - Closed → Open (after failureThreshold consecutive failures)
+ *   - Open → Half-open (after cooldownMs)
+ *   - Half-open → Closed (on success) / Open (on failure)
+ */
+import type { Provider, ProviderCapabilities } from './interface.js';
+import type { Message, StreamEvent, ToolDefinition, ProviderType } from '../types.js';
+import type { RetryConfig } from './retry.js';
+export type { RetryConfig };
+export interface CircuitBreakerConfig {
+    /** Consecutive failures to open circuit (default: 5) */
+    failureThreshold: number;
+    /** Cooldown in ms before half-open (default: 30000) */
+    cooldownMs: number;
+}
+export declare const DEFAULT_CB: CircuitBreakerConfig;
+type CircuitState = 'closed' | 'open' | 'half-open';
+export declare class ResilientProvider implements Provider {
+    private inner;
+    private retryConfig;
+    private cbConfig;
+    private logger;
+    private cbState;
+    private failureCount;
+    private lastFailureTime;
+    private readonly name;
+    constructor(provider: Provider, retryConfig?: Partial<RetryConfig>, cbConfig?: Partial<CircuitBreakerConfig>);
+    getProviderType(): ProviderType;
+    getModel(): string;
+    getCapabilities(): ProviderCapabilities;
+    getInner(): Provider;
+    setThinking(enabled: boolean, effort?: string | number): void;
+    setUserId(userId: string): void;
+    getCircuitState(): CircuitState;
+    createStream(messages: Message[], tools?: ToolDefinition[], signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    private onSuccess;
+    private onFailure;
+}
+//# sourceMappingURL=resilient.d.ts.map