hyacinth-ai 0.9.6

package/dist/provider/interface.d.ts

@@ -0,0 +1,62 @@
+import type { Message, StreamEvent, ProviderType, ToolDefinition } from '../types.js';
+/** Provider 能力描述 */
+export interface ProviderCapabilities {
+    toolCalling: boolean;
+    streaming: boolean;
+    adapterSupport: boolean;
+    maxContextTokens: number;
+    isLocal: boolean;
+    /** 是否支持视觉/多模态（图片输入） */
+    vision: boolean;
+}
+/**
+ * Provider 接口 — 所有模型调用层的统一抽象。
+ *
+ * 实现类必须支持流式调用（AsyncIterable<StreamEvent>），
+ * 并通过 getProviderType / getModel 暴露自身元信息。
+ */
+export interface Provider {
+    /**
+     * 创建流式对话，逐事件返回 StreamEvent。
+     *
+     * @param messages - 对话消息列表
+     * @param tools    - 可选的工具定义列表
+     */
+    createStream(messages: Message[], tools?: ToolDefinition[], signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    /** 返回当前 Provider 的模型能力描述 */
+    getCapabilities?(): ProviderCapabilities;
+    /** 返回当前 Provider 的类型标识 */
+    getProviderType(): ProviderType;
+    /** 返回当前 Provider 使用的模型名称 */
+    getModel(): string;
+    /**
+     * 动态加载 LoRA Adapter（仅本地 Provider 支持）。
+     * @param name - Adapter 名称
+     * @param path - Adapter 权重文件路径
+     */
+    loadAdapter?(name: string, path: string): Promise<void>;
+    /**
+     * 卸载指定的 Adapter。
+     * @param name - Adapter 名称
+     */
+    unloadAdapter?(name: string): Promise<void>;
+    /**
+     * 列出当前已加载的 Adapter。
+     */
+    listAdapters?(): Promise<string[]>;
+    /**
+     * 运行时动态开关 thinking/reasoning 模式。
+     * 仅对支持 thinking 的 Provider（DeepSeek V4、Anthropic Extended Thinking 等）有效。
+     * @param enabled 是否启用
+     * @param effort  思考强度（DeepSeek: 'high' | 'max'；Anthropic: budget tokens）
+     */
+    setThinking?(enabled: boolean, effort?: string | number): void;
+    /**
+     * 运行时切换 KVCache 隔离 ID。
+     * 仅对 DeepSeek/OpenAI 等将 user_id 发送到 API 的 Provider 有效。
+     * 用于主Agent 模式切换（普通↔陪伴）等场景。
+     * @param userId 新的隔离标识
+     */
+    setUserId?(userId: string): void;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/provider/interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/provider/local-config.d.ts

@@ -0,0 +1,37 @@
+export type LocalBackend = 'ollama' | 'llamacpp';
+export interface LocalProviderConfig {
+    baseUrl: string;
+    port: number;
+    defaultModel: string;
+    /** 单次请求最大输出 token 数（从 config 读取，未配置时用默认值 4096）。兼容旧键名 maxTokens。 */
+    maxOutputTokens: number;
+    /** @deprecated 使用 maxOutputTokens */
+    maxTokens?: number;
+    /** 后端类型：ollama | llamacpp。未配置时自动检测 */
+    backend?: LocalBackend;
+}
+/**
+ * 从 Ollama 获取实际已安装的模型列表。
+ * 返回模型名列表（如 ["llama3.2:latest", "mistral:latest"]）。
+ */
+export declare function fetchOllamaModels(baseUrl?: string): Promise<string[]>;
+/**
+ * 从给定的模型名列表中挑选最佳匹配。
+ * 1. 精确匹配 preferredName
+ * 2. 前缀匹配（去掉 :latest 等 tag 后的名字）
+ * 3. 回退到列表第一个
+ */
+export declare function pickBestOllamaModel(available: string[], preferred?: string | null): string | null;
+/** 检测哪个本地后端正在运行。返回 null 表示都没在跑 */
+export declare function detectLocalBackend(): Promise<{
+    backend: LocalBackend;
+    baseUrl: string;
+    port: number;
+} | null>;
+/** 检测指定 backend 的二进制是否安装（在 PATH 或项目 libs/ 下） */
+export declare function detectBackendBinary(backend: LocalBackend): string | null;
+import type { RuntimeConfigCenter } from '../runtime/config-center.js';
+/** 注入 RuntimeConfigCenter 引用（factory.ts 初始化后调用）。注入后所有读取走统一配置。 */
+export declare function injectConfigCenter(cc: RuntimeConfigCenter): void;
+export declare function getLocalProviderConfigLoader(_cwd?: string): LocalProviderConfig;
+//# sourceMappingURL=local-config.d.ts.map

package/dist/provider/local-config.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+const DEFAULT_CONFIG = {
+    baseUrl: 'http://127.0.0.1:11434/v1',
+    port: 11434,
+    defaultModel: 'llama3.2',
+    maxOutputTokens: 4096,
+};
+// ── 自动检测 ────────────────────────────────────────────────────────
+function httpGet(url) {
+    return new Promise((resolve) => {
+        const req = http.get(url, { timeout: 2000 }, (res) => {
+            resolve(res.statusCode === 200);
+            res.resume();
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+}
+function httpGetJson(url) {
+    return new Promise((resolve) => {
+        const req = http.get(url, { timeout: 3000 }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+}
+/**
+ * 从 Ollama 获取实际已安装的模型列表。
+ * 返回模型名列表（如 ["llama3.2:latest", "mistral:latest"]）。
+ */
+export async function fetchOllamaModels(baseUrl) {
+    const apiUrl = `${baseUrl ?? 'http://127.0.0.1:11434'}/api/tags`;
+    const data = await httpGetJson(apiUrl);
+    if (!data?.models?.length)
+        return [];
+    return data.models.map((m) => m.name).filter(Boolean);
+}
+/**
+ * 从给定的模型名列表中挑选最佳匹配。
+ * 1. 精确匹配 preferredName
+ * 2. 前缀匹配（去掉 :latest 等 tag 后的名字）
+ * 3. 回退到列表第一个
+ */
+export function pickBestOllamaModel(available, preferred) {
+    if (available.length === 0)
+        return null;
+    if (preferred) {
+        // 精确匹配
+        const exact = available.find((m) => m === preferred);
+        if (exact)
+            return exact;
+        // 前缀匹配：用户配了 "qwen3" → 匹配 "qwen3:latest"
+        const prefixMatch = available.find((m) => m.startsWith(preferred));
+        if (prefixMatch)
+            return prefixMatch;
+        // 反过来：available 里有 "qwen3:0.8b"，用户配了 "qwen3:0.8b-q4_k_m" → 匹配 available 中以 preferred 开头的
+        const reverseMatch = available.find((m) => preferred.startsWith(m));
+        if (reverseMatch)
+            return reverseMatch;
+    }
+    return available[0];
+}
+/** 检测哪个本地后端正在运行。返回 null 表示都没在跑 */
+export async function detectLocalBackend() {
+    // 先检查 Ollama
+    const ollamaAlive = await httpGet('http://127.0.0.1:11434/api/tags');
+    if (ollamaAlive) {
+        return { backend: 'ollama', baseUrl: 'http://127.0.0.1:11434/v1', port: 11434 };
+    }
+    // 再检查 llama.cpp
+    const llamaAlive = await httpGet('http://127.0.0.1:8080/health');
+    if (llamaAlive) {
+        return { backend: 'llamacpp', baseUrl: 'http://127.0.0.1:8080/v1', port: 8080 };
+    }
+    return null;
+}
+/** 检测指定 backend 的二进制是否安装（在 PATH 或项目 libs/ 下） */
+export function detectBackendBinary(backend) {
+    const candidates = backend === 'ollama'
+        ? [
+            path.join(process.cwd(), 'libs', 'ollama', 'ollama.exe'),
+            path.join(process.cwd(), 'libs', 'ollama', 'ollama'),
+            'ollama',
+            'ollama.exe',
+        ]
+        : [];
+    // llama.cpp binary detection is handled by LocalModelModule.resolveLlamaServerPath
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+let _configCenter = null;
+/** 注入 RuntimeConfigCenter 引用（factory.ts 初始化后调用）。注入后所有读取走统一配置。 */
+export function injectConfigCenter(cc) {
+    _configCenter = cc;
+}
+function readFromConfigCenter() {
+    if (!_configCenter)
+        return null;
+    try {
+        // provider.local.* 是运行时覆盖（TUI/切换写入），local.* 是默认值
+        const baseUrl = _configCenter.get('provider.local.baseUrl') ||
+            _configCenter.get('local.baseUrl');
+        if (!baseUrl && _configCenter.get('local.baseUrl') === undefined)
+            return null;
+        return {
+            baseUrl: baseUrl || DEFAULT_CONFIG.baseUrl,
+            port: (_configCenter.get('local.port')) ?? DEFAULT_CONFIG.port,
+            defaultModel: _configCenter.get('provider.local.model') ||
+                _configCenter.get('local.defaultModel') ||
+                DEFAULT_CONFIG.defaultModel,
+            maxOutputTokens: (_configCenter.get('provider.local.maxOutputTokens')) ??
+                (_configCenter.get('provider.local.maxTokens')) ?? // 向后兼容旧键名
+                (_configCenter.get('local.maxOutputTokens')) ??
+                (_configCenter.get('local.maxTokens')) ?? // 向后兼容旧键名
+                DEFAULT_CONFIG.maxOutputTokens,
+            backend: _configCenter.get('local.backend'),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function getLocalProviderConfigLoader(_cwd) {
+    return readFromConfigCenter() ?? { ...DEFAULT_CONFIG };
+}
+//# sourceMappingURL=local-config.js.map

package/dist/provider/local.d.ts

@@ -0,0 +1,45 @@
+import type { Message, StreamEvent, ProviderType, ToolDefinition } from '../types.js';
+import type { Provider, ProviderCapabilities } from './interface.js';
+/** LocalProvider 构造选项 */
+export interface LocalProviderOptions {
+    baseUrl?: string;
+    model?: string;
+    /** 单次请求最大输出 token 数。兼容旧键名 maxTokens。 */
+    maxOutputTokens?: number;
+    /** @deprecated 使用 maxOutputTokens */
+    maxTokens?: number;
+    /** 后端类型：ollama | llamacpp。未指定时从 baseUrl 端口自动推断 */
+    backend?: 'ollama' | 'llamacpp';
+}
+/**
+ * Local Provider — 通过 OpenAI 兼容协议调用本地推理服务。
+ *
+ * 主要针对 llama.cpp server 设计，也兼容任何 OpenAI 兼容端点
+ * （Ollama / vLLM / LM Studio 等）。
+ *
+ * 与 OpenAIProvider 的区别：
+ *  - 不需要 API key
+ *  - 默认地址指向 localhost
+ *  - 对连接失败和服务错误做更宽松的处理
+ */
+export declare class LocalProvider implements Provider {
+    private client;
+    private model;
+    private maxTokens;
+    private _providerType;
+    constructor(opts?: LocalProviderOptions);
+    getProviderType(): ProviderType;
+    getModel(): string;
+    getCapabilities(): ProviderCapabilities;
+    setModel(model: string): void;
+    setBaseUrl(url: string): void;
+    createStream(messages: Message[], tools?: ToolDefinition[], signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    private convertMessages;
+    private convertTools;
+}
+/** 便捷工厂 */
+export declare function createLocalProvider(config?: {
+    baseUrl?: string;
+    model?: string;
+}): LocalProvider;
+//# sourceMappingURL=local.d.ts.map

package/dist/provider/local.js

@@ -0,0 +1,248 @@
+import OpenAI from 'openai';
+import { getLocalProviderConfigLoader } from './local-config.js';
+import { recoverToolArguments, logToolArgsWarning } from './tool-args-recovery.js';
+/**
+ * Local Provider — 通过 OpenAI 兼容协议调用本地推理服务。
+ *
+ * 主要针对 llama.cpp server 设计，也兼容任何 OpenAI 兼容端点
+ * （Ollama / vLLM / LM Studio 等）。
+ *
+ * 与 OpenAIProvider 的区别：
+ *  - 不需要 API key
+ *  - 默认地址指向 localhost
+ *  - 对连接失败和服务错误做更宽松的处理
+ */
+export class LocalProvider {
+    client;
+    model;
+    maxTokens;
+    _providerType;
+    constructor(opts = {}) {
+        const cfg = getLocalProviderConfigLoader();
+        const baseUrl = opts.baseUrl ?? process.env.LOCAL_BASE_URL ?? cfg.baseUrl;
+        this.client = new OpenAI({ apiKey: 'local', baseURL: baseUrl });
+        this.model = opts.model ?? process.env.LOCAL_MODEL ?? cfg.defaultModel;
+        this.maxTokens = opts.maxOutputTokens ?? opts.maxTokens ?? cfg.maxOutputTokens ?? cfg.maxTokens ?? 4096;
+        // 推断后端类型
+        const backend = opts.backend ?? (baseUrl.includes(':11434') ? 'ollama' : 'llamacpp');
+        this._providerType = backend === 'ollama' ? 'ollama' : 'llamacpp';
+    }
+    getProviderType() {
+        return this._providerType;
+    }
+    getModel() {
+        return this.model;
+    }
+    getCapabilities() {
+        return {
+            toolCalling: true,
+            streaming: true,
+            adapterSupport: false,
+            maxContextTokens: this.maxTokens,
+            isLocal: true,
+            vision: true, // Ollama/llama.cpp 均可加载视觉模型，默认开启
+        };
+    }
+    setModel(model) {
+        this.model = model;
+    }
+    setBaseUrl(url) {
+        this.client = new OpenAI({
+            apiKey: 'local',
+            baseURL: url,
+        });
+    }
+    async *createStream(messages, tools, signal) {
+        const params = {
+            model: this.model,
+            messages: this.convertMessages(messages),
+            max_tokens: this.maxTokens,
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        if (tools && tools.length > 0) {
+            params.tools = this.convertTools(tools);
+        }
+        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 — 部分本地推理服务不输出，可选
+                if (chunk.usage) {
+                    yield {
+                        type: 'USAGE',
+                        input_tokens: chunk.usage.prompt_tokens ?? 0,
+                        output_tokens: chunk.usage.completion_tokens ?? 0,
+                        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);
+                        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) {
+                    for (const [, acc] of toolCallAccumulators) {
+                        const raw = acc.arguments || '';
+                        const { recovered, complete, error } = recoverToolArguments(raw, acc.name);
+                        if (!complete) {
+                            logToolArgsWarning('local', 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) {
+                // 连接失败（status=undefined）给友好提示
+                if (error.status === undefined) {
+                    throw new Error(`Cannot connect to local model at ${this.client.baseURL}. ` +
+                        'Make sure Ollama / llama.cpp (or another OpenAI-compatible local server) is running.');
+                }
+                throw new Error(`Local model API error (${error.status}): ${error.message}`);
+            }
+            if (error instanceof Error) {
+                throw new Error(`Local model stream error: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    // ---- 转换方法 ----
+    convertMessages(messages) {
+        const result = [];
+        for (const msg of messages) {
+            const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+            if (msg.role === 'assistant') {
+                const textParts = [];
+                const toolCalls = [];
+                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),
+                            },
+                        });
+                    }
+                }
+                const assistantMsg = {
+                    role: 'assistant',
+                    content: textParts.length > 0 ? textParts.join('') : null,
+                };
+                if (toolCalls.length > 0) {
+                    assistantMsg.tool_calls = toolCalls;
+                }
+                result.push(assistantMsg);
+            }
+            else {
+                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') {
+                        // 仅视觉模型发送图片。LocalProvider 默认为非视觉，视图片为文本占位
+                        if (this.getCapabilities().vision) {
+                            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 } });
+                        }
+                        else {
+                            textParts.push(`[Image: ${block.source.type === 'base64' ? block.source.media_type : 'url'}]`);
+                        }
+                    }
+                }
+                result.push(...toolResults);
+                if (imageParts.length > 0) {
+                    const content = [
+                        ...imageParts,
+                        ...(textParts.length > 0 ? [{ type: 'text', text: textParts.join('') }] : []),
+                    ];
+                    if (msg.role === 'system') {
+                        result.push({ role: 'system', content: textParts.join('') });
+                    }
+                    else {
+                        result.push({ role: 'user', content });
+                    }
+                }
+                else if (textParts.length > 0) {
+                    if (msg.role === 'system') {
+                        result.push({ role: 'system', content: textParts.join('') });
+                    }
+                    else {
+                        result.push({ role: 'user', content: textParts.join('') });
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    convertTools(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.input_schema,
+            },
+        }));
+    }
+}
+/** 便捷工厂 */
+export function createLocalProvider(config = {}) {
+    return new LocalProvider(config);
+}
+//# sourceMappingURL=local.js.map

package/dist/provider/manager.d.ts

@@ -0,0 +1,67 @@
+import type { ProviderType, ProviderConfig } from '../types.js';
+import type { Provider } from './interface.js';
+import type { RetryConfig, CircuitBreakerConfig } from './resilient.js';
+export interface ProviderManagerOptions {
+    /** Override retry configuration */
+    retry?: Partial<RetryConfig>;
+    /** Override circuit breaker configuration */
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    /** Fallback provider types (tried in order after primary fails) */
+    fallbackProviders?: ProviderType[];
+    /**
+     * Called when the fallback chain switches from one provider to the next.
+     * Use this to adapt maxContextTokens, cache strategy, etc. for the new provider.
+     */
+    onFallback?: (fromType: ProviderType, toType: ProviderType, error: Error) => void;
+}
+/**
+ * ProviderManager — 根据配置和环境变量自动选择可用的 Provider。
+ *
+ * 优先级：显式配置 > 环境变量自动检测
+ *
+ * 自动检测逻辑（按优先级排列）：
+ *   有 ANTHROPIC_API_KEY → anthropic
+ *   有 OPENAI_API_KEY    → openai
+ *   有 DEEPSEEK_API_KEY  → deepseek
+ *   有 GROQ_API_KEY      → groq
+ *   有 XAI_API_KEY       → xai
+ *   有 MISTRAL_API_KEY   → mistral
+ *   有 GEMINI_API_KEY    → gemini
+ *   有 OPENROUTER_API_KEY → openrouter
+ *   有 MOONSHOT_API_KEY  → moonshot
+ */
+export declare class ProviderManager {
+    private provider;
+    private options?;
+    /** Track the resolved fallback types so switchProvider can rebuild the chain. */
+    private resolvedFallbackTypes;
+    constructor(config?: ProviderConfig, options?: ProviderManagerOptions);
+    /**
+     * 包装一个裸 Provider，使其具备弹性层。
+     * 与构造函数中的包装逻辑完全一致，确保 switchProvider 切换后不丢失保护。
+     */
+    private wrapProvider;
+    /** Build fallback providers from their types. Skips online providers without API key. */
+    private buildFallbackProviders;
+    getProvider(): Provider;
+    getProviderType(): ProviderType;
+    getModel(): string;
+    /**
+     * 设置 fallback 回调 — 当降级链中切换 Provider 时触发。
+     * 用于在 ProviderManager 创建后、configCenter 就绪时绑定。
+     * 仅对 FallbackProviderChain 有效；单 ResilientProvider 无降级，回调不触发。
+     */
+    setOnFallback(cb: (fromType: ProviderType, toType: ProviderType, error: Error) => void): void;
+    /** 运行时切换 Provider，保留弹性层（重试 + 熔断 + 降级链）。 */
+    switchProvider(config: ProviderConfig): void;
+    static createProviderFromConfig(config: ProviderConfig): Provider;
+    static detectFromEnv(): Provider | null;
+    static getAvailableProviders(): ProviderType[];
+    /**
+     * 从配置文件创建 Provider。
+     * 优先级：项目级 .env > 全局 .env > 环境变量
+     * 配置合并：默认 → 全局 config.json → 项目级 config.json
+     */
+    static createFromConfigFile(overrides?: Partial<ProviderConfig>, projectDir?: string): Promise<ProviderManager>;
+}
+//# sourceMappingURL=manager.d.ts.map