hyacinth-ai 0.9.6

package/dist/lifecycle/supervisor.js

@@ -0,0 +1,277 @@
+import { ProcessManager } from './manager.js';
+import { LocalModelManager } from './local-model.js';
+/**
+ * LifecycleSupervisor — 统一管理所有受管进程的生命周期。
+ *
+ * 职责：
+ *   1. 作为中心注册表，管理 LocalModel 和 MCP Server 的 ProcessManager
+ *   2. 提供统一的启动/停止/状态查询接口
+ *   3. 协调应用退出时的优雅关闭（按依赖顺序停止）
+ *   4. 暴露全局事件回调
+ */
+export class LifecycleSupervisor {
+    entities = [];
+    localModelManager = new LocalModelManager();
+    _shuttingDown = false;
+    backgroundRegistry;
+    /** 是否正在关闭中 */
+    get shuttingDown() {
+        return this._shuttingDown;
+    }
+    /** 获取所有实体的状态 */
+    getAllStatus() {
+        return this.entities.map((e) => ({
+            ...e.manager.getStatus(),
+            type: e.type,
+        }));
+    }
+    /** 获取特定实体的状态 */
+    getStatus(name) {
+        const entity = this.entities.find((e) => e.name === name);
+        if (!entity)
+            return null;
+        return { ...entity.manager.getStatus(), type: entity.type };
+    }
+    /** 获取指定类型的所有实体 */
+    getByType(type) {
+        return this.entities.filter((e) => e.type === type);
+    }
+    // ===== Local Model 管理 =====
+    /**
+     * 从项目目录加载并启动本地模型
+     * @returns 加载到的模型信息列表
+     */
+    async loadAndStartModels(projectDir) {
+        const callbacks = this.createCallbacks('local-model');
+        const models = await this.localModelManager.loadAndStart(projectDir, callbacks);
+        // 将每个模型的 ProcessManager 注册到监督器，确保优雅关闭时能停止模型进程
+        for (const m of models) {
+            const pm = this.localModelManager.getProcessManager(m.name);
+            if (pm) {
+                this.entities.push({
+                    type: 'local-model',
+                    manager: pm,
+                    name: `model-${m.name}`,
+                });
+            }
+        }
+        return models;
+    }
+    /** 启动指定模型 */
+    async startModel(name) {
+        await this.localModelManager.startModel(name);
+    }
+    /**
+     * 运行时按需启动模型。
+     * 用于 CLI 中用户切换 provider 到 local 时。
+     */
+    async startModelOnDemand(projectDir, modelKey) {
+        const callbacks = this.createCallbacks('local-model');
+        const info = await this.localModelManager.startModelOnDemand(projectDir, modelKey, callbacks);
+        if (info) {
+            const pm = this.localModelManager.getProcessManager(info.name);
+            if (pm) {
+                const existing = this.entities.find((e) => e.name === `model-${info.name}`);
+                if (!existing) {
+                    this.entities.push({
+                        type: 'local-model',
+                        manager: pm,
+                        name: `model-${info.name}`,
+                    });
+                }
+            }
+        }
+        return info;
+    }
+    /** 停止指定模型（同时检查 localModelManager 和 entities） */
+    async stopModel(name) {
+        await this.localModelManager.stopModel(name);
+        // 同时停止 supervisor 自己注册的 entity（如 Ollama）
+        const entityName = `model-${name}`;
+        const entity = this.entities.find((e) => e.name === entityName);
+        if (entity) {
+            await entity.manager.stop().catch(() => { });
+            this.entities = this.entities.filter((e) => e.name !== entityName);
+        }
+    }
+    /**
+     * 自动检测并启动 Ollama（无需预先配置模型注册表）。
+     * 用于 switchProvider("local") 时自动拉起。
+     */
+    async startOllamaOnDemand(projectDir) {
+        const { detectBackendBinary, detectLocalBackend } = await import('../provider/local-config.js');
+        const ollamaBin = detectBackendBinary('ollama');
+        if (!ollamaBin)
+            return null;
+        // 再次确认：可能第一次检测是假阴性（网络波动），实际已运行
+        const recheck = await detectLocalBackend();
+        if (recheck?.backend === 'ollama') {
+            // 已在运行，注册为受管 entity 以便 shutdown 时能尝试停止
+            const pm = new ProcessManager({ name: 'model-ollama', command: ollamaBin, args: ['serve'], autoRestart: false, healthCheck: { url: 'http://127.0.0.1:11434/api/tags', intervalMs: 5000, timeoutMs: 3000, maxRetries: 3 } }, this.createCallbacks('local-model'));
+            this.entities.push({ type: 'local-model', manager: pm, name: 'model-ollama' });
+            return { name: 'ollama', backend: 'ollama', modelName: 'ollama', port: 11434, baseUrl: 'http://127.0.0.1:11434/v1' };
+        }
+        // 未运行 → 拉起
+        const pm = new ProcessManager({
+            name: 'model-ollama',
+            command: ollamaBin,
+            args: ['serve'],
+            autoRestart: true,
+            maxRestarts: 3,
+            healthCheck: { url: 'http://127.0.0.1:11434/api/tags', intervalMs: 5000, timeoutMs: 3000, maxRetries: 6 },
+            startupTimeoutMs: 120000,
+        }, this.createCallbacks('local-model'));
+        await pm.start();
+        // 等待健康检查通过（最多 20 秒）
+        for (let i = 0; i < 20; i++) {
+            await new Promise((r) => setTimeout(r, 1000));
+            if (pm.getState() === 'running')
+                break;
+            // 即使进程状态不对，也检查端点是否可达（端口冲突时 ollama 可能外部已运行）
+            const alive = await detectLocalBackend();
+            if (alive?.backend === 'ollama')
+                break;
+        }
+        const isRunning = pm.getState() === 'running';
+        const isEndpointAlive = (await detectLocalBackend())?.backend === 'ollama';
+        if (!isRunning && !isEndpointAlive) {
+            await pm.stop().catch(() => { });
+            return null;
+        }
+        this.entities.push({ type: 'local-model', manager: pm, name: 'model-ollama' });
+        const info = {
+            name: 'ollama',
+            backend: 'ollama',
+            modelName: 'ollama',
+            port: 11434,
+            baseUrl: 'http://127.0.0.1:11434/v1',
+        };
+        return info;
+    }
+    /** 获取 LocalModelManager 实例（供 CLI 获取模型信息以配置 Provider） */
+    getModelManager() {
+        return this.localModelManager;
+    }
+    // ===== MCP Server 管理 =====
+    /** 注册一个 MCP Server 的 ProcessManager */
+    registerMCPServer(manager) {
+        this.entities.push({
+            type: 'mcp-server',
+            manager,
+            name: manager.config.name,
+        });
+    }
+    // ===== 通用进程注册 =====
+    /** 注册任意受管进程 */
+    register(name, type, manager) {
+        this.entities.push({ name, type, manager });
+    }
+    /** 注册后台进程注册表（用于异步工具如 bash async:true），关闭时自动清理 */
+    registerBackgroundRegistry(registry) {
+        this.backgroundRegistry = registry;
+    }
+    // ===== 全局优雅关闭 =====
+    /**
+     * 关闭所有受管进程。
+     * 关闭顺序：local-model → mcp-server → custom
+     * （模型和 MCP Server 无严格依赖，并行关闭即可）
+     */
+    async shutdownAll() {
+        if (this._shuttingDown)
+            return;
+        this._shuttingDown = true;
+        // 先停止后台进程（bash async:true 启动的进程）
+        if (this.backgroundRegistry) {
+            await this.backgroundRegistry.shutdownAll().catch(() => { });
+        }
+        const results = this.entities.map((e) => e.manager.stop().catch(() => {
+            // 单个关闭失败不影响其他
+        }));
+        await Promise.all(results);
+        this.entities = [];
+    }
+    // ===== 安装全局信号处理器 =====
+    /**
+     * 安装 SIGINT / SIGTERM / 进程退出处理器，实现优雅关闭。
+     *
+     * 三层防护：
+     *   1. SIGINT / SIGTERM → 异步优雅关闭
+     *   2. beforeExit      → 异步关闭（覆盖正常退出路径）
+     *   3. exit            → 同步 forceKill（最后防线，确保子进程不留孤儿）
+     *
+     * 返回一个函数，调用后可移除这些处理器。
+     */
+    installSignalHandlers() {
+        const onSigInt = async () => {
+            if (this._shuttingDown) {
+                process.exit(0);
+            }
+            this._shuttingDown = true;
+            process.stderr.write('\nShutting down managed processes...\n');
+            // 10 秒兜底：防止 shutdownAll() 卡住导致僵尸进程
+            const forceExit = setTimeout(() => {
+                process.stderr.write('\nShutdown timeout, forcing exit...\n');
+                process.exit(1);
+            }, 10_000);
+            await this.shutdownAll();
+            clearTimeout(forceExit);
+            process.exit(0);
+        };
+        const onSigTerm = async () => {
+            this._shuttingDown = true;
+            process.stderr.write('\nReceived SIGTERM, shutting down...\n');
+            const forceExit = setTimeout(() => {
+                process.stderr.write('\nShutdown timeout, forcing exit...\n');
+                process.exit(1);
+            }, 10_000);
+            await this.shutdownAll();
+            clearTimeout(forceExit);
+            process.exit(0);
+        };
+        const onBeforeExit = async () => {
+            if (!this._shuttingDown) {
+                await this.shutdownAll();
+            }
+        };
+        const onExit = () => {
+            this.forceKillAll();
+        };
+        process.on('SIGINT', onSigInt);
+        process.on('SIGTERM', onSigTerm);
+        process.on('beforeExit', onBeforeExit);
+        process.on('exit', onExit);
+        return () => {
+            process.removeListener('SIGINT', onSigInt);
+            process.removeListener('SIGTERM', onSigTerm);
+            process.removeListener('beforeExit', onBeforeExit);
+            process.removeListener('exit', onExit);
+        };
+    }
+    /**
+     * 同步强制杀死所有受管子进程。
+     * 用于 exit handler 中，不依赖异步操作。
+     */
+    forceKillAll() {
+        // 后台进程（bash async:true）
+        this.backgroundRegistry?.forceKillAll();
+        // 受管实体（local-model, mcp-server）
+        for (const entity of this.entities) {
+            entity.manager.forceKillAll();
+        }
+    }
+    // ===== 内部方法 =====
+    createCallbacks(type) {
+        return {
+            onCrash: (name, exitCode) => {
+                process.stderr.write(`[lifecycle] ${name} crashed with exit code ${exitCode}, auto-restarting...\n`);
+            },
+            onHealthFail: (name, error) => {
+                process.stderr.write(`[lifecycle] ${name} health check failed: ${error}\n`);
+            },
+            onHealthRecover: (name) => {
+                process.stderr.write(`[lifecycle] ${name} health recovered\n`);
+            },
+        };
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/lifecycle-integration-test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lifecycle-integration-test.d.ts.map

package/dist/lifecycle-integration-test.js

@@ -0,0 +1,72 @@
+import { LifecycleSupervisor } from './lifecycle/index.js';
+import { LocalProvider } from './provider/local.js';
+async function main() {
+    console.log('═══════════════════════════════════════');
+    console.log('Lifecycle 托管 → llama-server 完整测试');
+    console.log('═══════════════════════════════════════');
+    const supervisor = new LifecycleSupervisor();
+    supervisor.installSignalHandlers();
+    try {
+        // 1. Agent 启动 → 自动拉起 llama-server
+        console.log('\n1. Agent 启动, 加载本地模型...');
+        const models = await supervisor.loadAndStartModels(process.cwd());
+        console.log(`   加载了 ${models.length} 个模型`);
+        if (models.length === 0) {
+            console.log('   FAIL: 没有模型被加载');
+            process.exit(1);
+        }
+        const model = models[0];
+        console.log(`   名称: ${model.name} | 后端: ${model.backend} | 地址: ${model.baseUrl}`);
+        console.log('   PASS: 模型已启动\n');
+        // 2. 使用 LocalProvider 调用
+        console.log('2. 通过 LocalProvider 调用模型...');
+        const provider = new LocalProvider({
+            baseUrl: model.baseUrl,
+            model: model.modelName,
+        });
+        const messages = [
+            { role: 'system', content: { type: 'text', text: 'Reply in one short sentence. No thinking.' } },
+            { role: 'user', content: { type: 'text', text: 'Reply with just the word HELLO.' } },
+        ];
+        const stream = provider.createStream(messages);
+        let response = '';
+        for await (const event of stream) {
+            if (event.type === 'TEXT') {
+                process.stdout.write(event.content);
+                response += event.content;
+            }
+        }
+        console.log('');
+        console.log(response.length > 0 ? '   PASS: 模型调用成功\n' : '   WARN: 响应为空\n');
+        // 3. Agent 退出 → 自动关闭 llama-server
+        console.log('3. Agent 退出, 关闭本地模型...');
+        await supervisor.shutdownAll();
+        console.log('   PASS: shutdownAll() 完成\n');
+        // 4. 验证 llama-server 进程已完全终止
+        await new Promise(r => setTimeout(r, 2000));
+        console.log('4. 验证 llama-server 进程已终止...');
+        const { execSync } = await import('node:child_process');
+        try {
+            const result = execSync('tasklist /FI "IMAGENAME eq llama-server.exe"', { encoding: 'utf-8', timeout: 5000 });
+            if (result.includes('llama-server.exe')) {
+                console.log(`   FAIL: llama-server 进程仍在运行\n   ${result.split('\n').find(l => l.includes('llama-server'))}`);
+                process.exit(1);
+            }
+            else {
+                console.log('   PASS: llama-server 进程已完全终止');
+            }
+        }
+        catch {
+            console.log('   PASS: llama-server 进程已完全终止');
+        }
+        // 注意：端口 8080 可能处于 TIME_WAIT 状态（TCP 正常清理），这不是进程在运行
+    }
+    finally {
+        // 信号处理器在 supervisor 内部已通过 installSignalHandlers 注册
+    }
+    console.log('═══════════════════════════════════════');
+    console.log('全部通过: Agent 主进程完全托管 llama-server 生命周期');
+    console.log('═══════════════════════════════════════');
+}
+main().catch(console.error);
+//# sourceMappingURL=lifecycle-integration-test.js.map

package/dist/local-model/download-manager.d.ts

@@ -0,0 +1,59 @@
+/** check() 返回值 */
+export interface CheckResult {
+    installed: boolean;
+    path?: string;
+    version?: string;
+}
+/**
+ * llama.cpp 预编译包下载管理器。
+ *
+ * 使用 GitHub API 自动发现最新 Windows CUDA 预编译包，下载并解压到项目目录。
+ * 全部基于 Node.js 内置模块（https + zlib），零外部依赖。
+ *
+ * @example
+ * ```ts
+ * const dm = new DownloadManager();
+ *
+ * // 快速检测
+ * if (dm.isInstalled(projectRoot)) {
+ *   console.log('llama.cpp 已安装');
+ * }
+ *
+ * // 详细检测
+ * const result = dm.check(projectRoot);
+ * console.log(result); // { installed: true, path: '...', version: 'b4978' }
+ *
+ * // 自动下载安装
+ * const version = await dm.download(projectRoot, (pct, speed) => {
+ *   console.log(`${pct}% @ ${speed}`);
+ * });
+ * console.log(`已安装版本: ${version}`);
+ * ```
+ */
+export declare class DownloadManager {
+    /**
+     * 检测 llama.cpp（llama-server.exe）是否已安装。
+     *
+     * @param projectRoot - 项目根目录
+     * @returns 检测结果，包含安装状态、路径和版本信息
+     */
+    check(projectRoot: string): CheckResult;
+    /**
+     * 快速检测 llama.cpp 是否已安装。
+     *
+     * @param projectRoot - 项目根目录
+     * @returns true 表示 llama-server.exe 已存在
+     */
+    isInstalled(projectRoot: string): boolean;
+    /**
+     * 从 GitHub Releases 下载最新的 llama.cpp Windows CUDA 预编译包，
+     * 解压到 libs/llama.cpp/ 目录。
+     *
+     * @param projectRoot - 项目根目录
+     * @param onProgress - 可选进度回调 (百分比, 速度字符串)
+     * @returns 安装的版本号（GitHub release tag_name）
+     * @throws 网络错误、解压失败时抛出带手动安装指引的 Error
+     */
+    download(projectRoot: string, onProgress?: (percent: number, speed: string) => void): Promise<string>;
+}
+//# sourceMappingURL=download-manager.d.ts.map