hyacinth-ai 0.9.6

package/dist/provider/catalog.d.ts

@@ -0,0 +1,58 @@
+import type { ProviderType } from '../types.js';
+/** 模型能力标记 */
+export interface ModelCapabilities {
+    streaming: boolean;
+    toolCalling: boolean;
+    thinking: boolean;
+    vision: boolean;
+    inputTypes: ('text' | 'image' | 'document')[];
+}
+/** 模型定价（每 1M token，美元） */
+export interface ModelCost {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** 模型元信息 */
+export interface ModelInfo {
+    id: string;
+    name: string;
+    provider: ProviderType;
+    /** 最大输入上下文窗口（token 数） */
+    contextWindow: number;
+    /** 单次请求最大输出 token 数 */
+    maxOutputTokens: number;
+    capabilities: ModelCapabilities;
+    cost?: ModelCost;
+    status: 'available' | 'preview' | 'deprecated' | 'disabled';
+    replacedBy?: string;
+    /** 推理/思考强度（仅支持 reasoning 的模型有效） */
+    reasoningEffort?: 'high' | 'max';
+}
+/**
+ * ModelCatalog — 全局模型注册表。
+ *
+ * 集中存放所有支持的模型元信息：contextWindow、maxTokens、capabilities、cost。
+ * 各 Provider 实例可通过 lookup() 查询模型信息，用于 capacity planning 和成本估算。
+ */
+export declare class ModelCatalog {
+    private models;
+    private initialized;
+    constructor();
+    register(model: ModelInfo): void;
+    registerAll(models: ModelInfo[]): void;
+    lookup(provider: ProviderType, modelId: string): ModelInfo | undefined;
+    getByProvider(provider: ProviderType): ModelInfo[];
+    getAvailable(): ModelInfo[];
+    getAll(): ModelInfo[];
+    getDefault(provider: ProviderType): ModelInfo | undefined;
+    init(cwd: string): void;
+    reload(): void;
+    private registerDefaults;
+}
+/** 全局单例 */
+export declare const modelCatalog: ModelCatalog;
+/** 便捷查询 */
+export declare function getModelInfo(provider: ProviderType, modelId: string): ModelInfo | undefined;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/provider/catalog.js

@@ -0,0 +1,97 @@
+import { getModelCatalogLoader } from './model-catalog-loader.js';
+function entryToModelInfo(entry) {
+    return {
+        id: entry.id,
+        name: entry.name,
+        provider: entry.provider,
+        contextWindow: entry.contextWindow,
+        maxOutputTokens: entry.maxOutputTokens,
+        reasoningEffort: entry.reasoningEffort,
+        capabilities: {
+            streaming: entry.capabilities.streaming,
+            toolCalling: entry.capabilities.toolCalling,
+            thinking: entry.capabilities.thinking,
+            vision: entry.capabilities.vision,
+            inputTypes: entry.capabilities.inputTypes,
+        },
+        cost: entry.cost ? { ...entry.cost } : undefined,
+        status: entry.status,
+        replacedBy: entry.replacedBy,
+    };
+}
+/**
+ * ModelCatalog — 全局模型注册表。
+ *
+ * 集中存放所有支持的模型元信息：contextWindow、maxTokens、capabilities、cost。
+ * 各 Provider 实例可通过 lookup() 查询模型信息，用于 capacity planning 和成本估算。
+ */
+export class ModelCatalog {
+    models = new Map();
+    initialized = false;
+    constructor() {
+        this.registerDefaults();
+    }
+    register(model) {
+        const key = `${model.provider}:${model.id}`;
+        this.models.set(key, model);
+    }
+    registerAll(models) {
+        for (const m of models)
+            this.register(m);
+    }
+    lookup(provider, modelId) {
+        return this.models.get(`${provider}:${modelId}`);
+    }
+    getByProvider(provider) {
+        const result = [];
+        for (const [, info] of this.models) {
+            if (info.provider === provider)
+                result.push(info);
+        }
+        return result;
+    }
+    getAvailable() {
+        const result = [];
+        for (const [, info] of this.models) {
+            if (info.status === 'available' || info.status === 'preview')
+                result.push(info);
+        }
+        return result;
+    }
+    getAll() {
+        return Array.from(this.models.values());
+    }
+    getDefault(provider) {
+        return this.models.get(`${provider}:__default__`);
+    }
+    init(cwd) {
+        getModelCatalogLoader(cwd);
+        if (!this.initialized) {
+            this.registerDefaults();
+        }
+    }
+    reload() {
+        this.models.clear();
+        this.initialized = false;
+        const loader = getModelCatalogLoader();
+        loader.reload();
+        this.registerDefaults();
+    }
+    registerDefaults() {
+        if (this.initialized)
+            return;
+        const loader = getModelCatalogLoader();
+        const config = loader.load();
+        for (const entry of config.models) {
+            this.register(entryToModelInfo(entry));
+        }
+        this.initialized = true;
+    }
+}
+/** 全局单例 */
+export const modelCatalog = new ModelCatalog();
+/** 便捷查询 */
+export function getModelInfo(provider, modelId) {
+    return modelCatalog.lookup(provider, modelId);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/provider/compatible.d.ts

@@ -0,0 +1,89 @@
+import type { Message, StreamEvent, ProviderType, ToolDefinition } from '../types.js';
+import type { Provider, ProviderCapabilities } from './interface.js';
+/** OpenAICompatibleProvider 构造选项 */
+export interface OpenAICompatibleOptions {
+    /** API key */
+    apiKey?: string;
+    /** 环境变量名（用于自动读取） */
+    envKey?: string;
+    /** API 基础 URL */
+    baseUrl: string;
+    /** 环境变量中的 base URL 覆盖 */
+    baseUrlEnv?: string;
+    /** 默认模型 */
+    model: string;
+    /** Provider 类型标识 */
+    providerType: ProviderType;
+    /** 单次请求最大输出 token 数。兼容旧键名 maxTokens。 */
+    maxOutputTokens?: number;
+    /** @deprecated 使用 maxOutputTokens */
+    maxTokens?: number;
+    /** 额外的 HTTP 头（如 OpenRouter 要求的 HTTP-Referer / X-Title） */
+    headers?: Record<string, string>;
+    /** DeepSeek 缓存隔离 ID，区分不同产品的缓存池。默认 "hyacinth"。 */
+    userId?: string;
+}
+/**
+ * OpenAICompatibleProvider — 通用 OpenAI 兼容 API Provider。
+ *
+ * 用一个类覆盖所有使用 OpenAI Chat Completions 格式的 Provider：
+ *   - Groq (api.groq.com)
+ *   - xAI / Grok (api.x.ai)
+ *   - Mistral (api.mistral.ai)
+ *   - OpenRouter (openrouter.ai)
+ *   - Moonshot / Kimi (api.moonshot.cn)
+ *
+ * 用法：通过工厂函数设置各自的默认值。
+ */
+/** DeepSeek 思考强度选项 */
+export type DeepSeekReasoningEffort = 'high' | 'max';
+export declare class OpenAICompatibleProvider implements Provider {
+    private client;
+    private model;
+    private maxTokens;
+    private providerType;
+    private thinkingEnabled;
+    private reasoningEffort;
+    private userId;
+    constructor(opts: OpenAICompatibleOptions);
+    getProviderType(): ProviderType;
+    getModel(): string;
+    getCapabilities(): ProviderCapabilities;
+    setModel(model: string): void;
+    setThinking(enabled: boolean, effort?: DeepSeekReasoningEffort): void;
+    setUserId(userId: string): void;
+    createStream(messages: Message[], tools?: ToolDefinition[], signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    private convertMessages;
+    private convertTools;
+}
+/** Groq — 高速推理 */
+export declare function createGroqProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    userId?: string;
+}): OpenAICompatibleProvider;
+/** xAI / Grok */
+export declare function createXAIProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    userId?: string;
+}): OpenAICompatibleProvider;
+/** Mistral AI */
+export declare function createMistralProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    userId?: string;
+}): OpenAICompatibleProvider;
+/** OpenRouter — 聚合网关（200+ 模型） */
+export declare function createOpenRouterProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    userId?: string;
+}): OpenAICompatibleProvider;
+/** Moonshot / Kimi */
+export declare function createMoonshotProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    userId?: string;
+}): OpenAICompatibleProvider;
+//# sourceMappingURL=compatible.d.ts.map

package/dist/provider/compatible.js

@@ -0,0 +1,328 @@
+import OpenAI from 'openai';
+import { getModelInfo } from './catalog.js';
+import { getProviderConfigLoader } from './config.js';
+import { DEFAULT_USER_ID } from './user-id.js';
+import { recoverToolArguments, logToolArgsWarning } from './tool-args-recovery.js';
+export class OpenAICompatibleProvider {
+    client;
+    model;
+    maxTokens;
+    providerType;
+    thinkingEnabled = false;
+    reasoningEffort;
+    userId;
+    constructor(opts) {
+        const apiKey = opts.apiKey ?? (opts.envKey ? process.env[opts.envKey] : undefined);
+        if (!apiKey) {
+            throw new Error(`${opts.providerType} API key is required. Set ${opts.envKey ?? 'API_KEY'} environment variable or pass apiKey.`);
+        }
+        const baseURL = opts.baseUrlEnv
+            ? (process.env[opts.baseUrlEnv] ?? opts.baseUrl)
+            : opts.baseUrl;
+        this.client = new OpenAI({
+            apiKey,
+            baseURL,
+            ...(opts.headers ? { defaultHeaders: opts.headers } : {}),
+        });
+        this.model = opts.model;
+        const modelInfo = getModelInfo(opts.providerType, opts.model);
+        this.maxTokens = opts.maxOutputTokens // ① 临时覆盖
+            ?? opts.maxTokens // 向后兼容
+            ?? modelInfo?.maxOutputTokens // ② 本机模型目录
+            ?? 8192; // ③ 兜底
+        this.reasoningEffort = modelInfo?.reasoningEffort ?? 'high';
+        this.providerType = opts.providerType;
+        this.userId = opts.userId ?? DEFAULT_USER_ID;
+    }
+    getProviderType() {
+        return this.providerType;
+    }
+    getModel() {
+        return this.model;
+    }
+    getCapabilities() {
+        const info = getModelInfo(this.providerType, this.model);
+        return {
+            toolCalling: true,
+            streaming: true,
+            adapterSupport: false,
+            maxContextTokens: info?.contextWindow ?? 128000,
+            isLocal: false,
+            vision: info?.capabilities.vision ?? false,
+        };
+    }
+    setModel(model) {
+        this.model = model;
+    }
+    setThinking(enabled, effort) {
+        this.thinkingEnabled = enabled;
+        if (effort)
+            this.reasoningEffort = effort;
+    }
+    setUserId(userId) {
+        this.userId = userId;
+    }
+    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 },
+        };
+        // DeepSeek: user_id 放顶层 body 做缓存隔离
+        params.user_id = this.userId;
+        if (tools && tools.length > 0) {
+            params.tools = this.convertTools(tools);
+        }
+        // DeepSeek thinking：默认 enabled，必须显式发送 disabled 才能关闭
+        params.extra_body = {
+            thinking: { type: this.thinkingEnabled ? 'enabled' : 'disabled' },
+        };
+        if (this.thinkingEnabled) {
+            params.reasoning_effort = this.reasoningEffort;
+        }
+        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,
+                        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 };
+                }
+                // text
+                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('compatible', acc.name, raw, error);
+                        }
+                        // Even on incomplete recovery, still emit — allows partial execution
+                        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(`${this.providerType} API error (${error.status}): ${error.message}`);
+            }
+            if (error instanceof Error) {
+                throw new Error(`${this.providerType} 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 = [];
+                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;
+                    }
+                }
+                const assistantMsg = {
+                    role: 'assistant',
+                    content: textParts.length > 0 ? textParts.join('') : (toolCalls.length > 0 ? '' : null),
+                };
+                if (toolCalls.length > 0) {
+                    assistantMsg.tool_calls = toolCalls;
+                }
+                // DeepSeek V4 等思考模型要求所有 assistant 消息必须带 reasoning_content
+                // 参考 OpenClaw: ensureDeepSeekV4AssistantReasoningContent
+                // 但当 assistant 只有 tool_calls 时，不添加 reasoning_content
+                // 因为 DeepSeek 不接受 tool_calls + reasoning_content 的组合
+                if (reasoningContent !== undefined) {
+                    assistantMsg.reasoning_content = reasoningContent;
+                }
+                else if (toolCalls.length === 0) {
+                    assistantMsg.reasoning_content = '';
+                }
+                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') {
+                        // 非视觉模型 → 降级为文本占位符
+                        if (!this.getCapabilities().vision) {
+                            const src = block.source;
+                            const label = src.type === 'base64'
+                                ? `[Image: ${src.media_type}]`
+                                : `[Image URL: ${src.url}]`;
+                            textParts.push(label);
+                        }
+                        else {
+                            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 } });
+                        }
+                    }
+                }
+                // tool_result 必须先于 user content
+                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;
+    }
+    convertTools(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.input_schema,
+            },
+        }));
+    }
+}
+// ===== 工厂函数 =====
+/** Groq — 高速推理 */
+export function createGroqProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('groq');
+    return new OpenAICompatibleProvider({
+        apiKey: config?.apiKey,
+        envKey: 'GROQ_API_KEY',
+        baseUrl: provCfg?.baseUrl ?? 'https://api.groq.com/openai/v1',
+        model: config?.model ?? provCfg?.defaultModel ?? 'unknown',
+        providerType: 'groq',
+        userId: config?.userId,
+    });
+}
+/** xAI / Grok */
+export function createXAIProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('xai');
+    return new OpenAICompatibleProvider({
+        apiKey: config?.apiKey,
+        envKey: 'XAI_API_KEY',
+        baseUrl: provCfg?.baseUrl ?? 'https://api.x.ai/v1',
+        model: config?.model ?? provCfg?.defaultModel ?? 'unknown',
+        providerType: 'xai',
+        userId: config?.userId,
+    });
+}
+/** Mistral AI */
+export function createMistralProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('mistral');
+    return new OpenAICompatibleProvider({
+        apiKey: config?.apiKey,
+        envKey: 'MISTRAL_API_KEY',
+        baseUrl: provCfg?.baseUrl ?? 'https://api.mistral.ai/v1',
+        model: config?.model ?? provCfg?.defaultModel ?? 'unknown',
+        providerType: 'mistral',
+        userId: config?.userId,
+    });
+}
+/** OpenRouter — 聚合网关（200+ 模型） */
+export function createOpenRouterProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('openrouter');
+    return new OpenAICompatibleProvider({
+        apiKey: config?.apiKey,
+        envKey: 'OPENROUTER_API_KEY',
+        baseUrl: provCfg?.baseUrl ?? 'https://openrouter.ai/api/v1',
+        model: config?.model ?? provCfg?.defaultModel ?? 'unknown',
+        providerType: 'openrouter',
+        userId: config?.userId,
+        headers: {
+            'HTTP-Referer': process.env.OPENROUTER_REFERER ?? 'http://localhost:3000',
+            'X-Title': process.env.OPENROUTER_TITLE ?? 'Agent',
+        },
+    });
+}
+/** Moonshot / Kimi */
+export function createMoonshotProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('moonshot');
+    return new OpenAICompatibleProvider({
+        apiKey: config?.apiKey,
+        envKey: 'MOONSHOT_API_KEY',
+        baseUrl: provCfg?.baseUrl ?? 'https://api.moonshot.cn/v1',
+        model: config?.model ?? provCfg?.defaultModel ?? 'unknown',
+        providerType: 'moonshot',
+    });
+}
+//# sourceMappingURL=compatible.js.map

package/dist/provider/config.d.ts

@@ -0,0 +1,23 @@
+export interface ProviderMeta {
+    id: string;
+    name: string;
+    baseUrl: string;
+    defaultModel: string;
+    envKey: string;
+}
+export interface ProvidersConfig {
+    providers: Record<string, ProviderMeta>;
+}
+export declare const DEFAULT_PROVIDERS: ProvidersConfig;
+export declare class ProviderConfigLoader {
+    private configPath;
+    private cache;
+    constructor(cwd: string);
+    load(): Promise<ProvidersConfig>;
+    getProvider(id: string): ProviderMeta | undefined;
+    getAll(): ProviderMeta[];
+    reload(): Promise<ProvidersConfig>;
+    private writeDefault;
+}
+export declare function getProviderConfigLoader(cwd?: string): ProviderConfigLoader;
+//# sourceMappingURL=config.d.ts.map