hyacinth-ai 0.9.6

package/dist/hot-reload/manager.js

@@ -0,0 +1,243 @@
+import { createLogger } from '../logging/logger.js';
+// ─── HotReloadManager ─────────────────────────────────────────────
+export class HotReloadManager {
+    deps;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    watchers = [];
+    debounceTimers = new Map();
+    logger = createLogger('hot-reload:manager');
+    started = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // ── Static factory ──
+    static create(cwd, deps) {
+        const manager = new HotReloadManager(deps);
+        manager.start();
+        return manager;
+    }
+    // ── Lifecycle ──
+    start() {
+        if (this.started)
+            return;
+        const enabled = this.deps.configCenter.get('hotReload.enabled');
+        if (!enabled) {
+            this.logger.info('Hot reload is disabled via config');
+            return;
+        }
+        const debounceMs = this.deps.configCenter.get('hotReload.debounceMs') ?? 300;
+        this.logger.info('Starting hot reload watchers...');
+        // ── MCP config watcher ──
+        if (this.deps.configCenter.get('hotReload.watchMcp')) {
+            import('./mcp-watcher.js').then(({ watchMcpConfig }) => {
+                this.registerWatcher(watchMcpConfig, {
+                    mcpSystem: this.deps.mcpSystem,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load MCP watcher', { error: err.message });
+            });
+        }
+        // ── Plugin watcher ──
+        if (this.deps.configCenter.get('hotReload.watchPlugins')) {
+            import('./plugin-watcher.js').then(({ watchPluginsDir }) => {
+                this.registerWatcher(watchPluginsDir, {
+                    pluginManager: this.deps.pluginManager,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load plugin watcher', { error: err.message });
+            });
+        }
+        // ── Prompt watcher ──
+        if (this.deps.configCenter.get('hotReload.watchPrompts')) {
+            import('./prompt-watcher.js').then(({ watchPrompts }) => {
+                this.registerWatcher(watchPrompts, { debounceMs });
+            }).catch((err) => {
+                this.logger.warn('Failed to load prompt watcher', { error: err.message });
+            });
+        }
+        // ── Agent watcher ──
+        if (this.deps.configCenter.get('hotReload.watchAgents')) {
+            import('./agent-watcher.js').then(({ watchAgentsJson }) => {
+                this.registerWatcher(watchAgentsJson, {
+                    agentRegistry: this.deps.agentRegistry,
+                    contextComposer: this.deps.contextComposer,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load agent watcher', { error: err.message });
+            });
+        }
+        // ── Config watcher ──
+        if (this.deps.configCenter.get('hotReload.watchConfig')) {
+            import('./config-watcher.js').then(({ watchConfigJson }) => {
+                this.registerWatcher(watchConfigJson, {
+                    configCenter: this.deps.configCenter,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load config watcher', { error: err.message });
+            });
+        }
+        // ── Tool watcher ──
+        if (this.deps.configCenter.get('hotReload.watchTools')) {
+            import('./tool-watcher.js').then(({ watchTools }) => {
+                this.registerWatcher(watchTools, {
+                    toolRegistry: this.deps.toolRegistry,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load tool watcher', { error: err.message });
+            });
+        }
+        // ── Skill watcher ──
+        if (this.deps.configCenter.get('hotReload.watchSkills')) {
+            import('./skill-watcher.js').then(({ watchSkills }) => {
+                this.registerWatcher(watchSkills, {
+                    skillRegistry: this.deps.skillRegistry,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                    onSkillLoaded: (skill) => {
+                        // 文件 skill 热加载后补注册 lazy_expand ContextSource
+                        this.deps.contextComposer.registerSource({
+                            name: `skill-${skill.name}`,
+                            strategy: 'lazy_expand',
+                            cacheability: 'manifest',
+                            description: skill.description,
+                            getContent: () => {
+                                const s = this.deps.skillRegistry.get(skill.name);
+                                return s ? this.deps.skillRegistry.getFullDefinitions([skill.name]) : '';
+                            },
+                        });
+                    },
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load skill watcher', { error: err.message });
+            });
+        }
+        // ── Slash commands watcher（commands.json 外部配置，模型可写） ──
+        if (this.deps.configCenter.get('hotReload.watchCommands') !== false) {
+            import('./command-watcher.js').then(({ watchCommandsJson }) => {
+                this.registerWatcher(watchCommandsJson, {
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load command watcher', { error: err.message });
+            });
+        }
+        // ── Provider config watcher ──
+        if (this.deps.configCenter.get('hotReload.watchProviders')) {
+            import('./provider-watcher.js').then(({ watchProviderConfig }) => {
+                this.registerWatcher(watchProviderConfig, {
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load provider watcher', { error: err.message });
+            });
+        }
+        // ── Model catalog watcher ──
+        if (this.deps.configCenter.get('hotReload.watchModelCatalog')) {
+            import('./model-catalog-watcher.js').then(({ watchModelCatalogConfig }) => {
+                this.registerWatcher(watchModelCatalogConfig, {
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                    configCenter: this.deps.configCenter,
+                    currentModel: () => {
+                        const provider = this.deps.configCenter.get('session.provider');
+                        const model = this.deps.configCenter.get('session.model');
+                        if (!provider)
+                            return undefined;
+                        return { provider, model: model ?? '' };
+                    },
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load model catalog watcher', { error: err.message });
+            });
+        }
+        // ── Context manifest watcher ──
+        if (this.deps.configCenter.get('hotReload.watchContextManifest') !== false) {
+            import('./manifest-watcher.js').then(({ watchContextManifest }) => {
+                this.registerWatcher(watchContextManifest, {
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load manifest watcher', { error: err.message });
+            });
+        }
+        // ── Tool bundle watcher ──
+        if (this.deps.configCenter.get('hotReload.watchBundles') !== false) {
+            import('./bundle-watcher.js').then(({ watchBundles }) => {
+                this.registerWatcher(watchBundles, {
+                    registry: this.deps.bundleRegistry,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load bundle watcher', { error: err.message });
+            });
+        }
+        // ── Model channel watcher ──
+        if (this.deps.configCenter.get('hotReload.watchProviders') && this.deps.channelRegistry) {
+            import('./channel-watcher.js').then(({ watchModelChannels }) => {
+                this.registerWatcher(watchModelChannels, {
+                    channelRegistry: this.deps.channelRegistry,
+                    cwd: this.deps.cwd,
+                    debounceMs,
+                });
+            }).catch((err) => {
+                this.logger.warn('Failed to load channel watcher', { error: err.message });
+            });
+        }
+        this.started = true;
+        this.logger.info('Hot reload watchers registered');
+    }
+    stop() {
+        this.logger.info('Stopping hot reload watchers...');
+        // Close all watcher instances (FSWatcher / StatWatcher / custom handles)
+        for (const watcher of this.watchers) {
+            if (typeof watcher?.close === 'function')
+                watcher.close();
+        }
+        this.watchers = [];
+        // Clear all debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        this.started = false;
+        this.logger.info('Hot reload stopped');
+    }
+    // ── Helpers ──
+    /**
+     * Call a watcher factory function and store the returned FSWatcher(s).
+     * Handles both single FSWatcher and FSWatcher[] return values.
+     */
+    registerWatcher(fn, ...args) {
+        try {
+            const result = fn(...args);
+            if (Array.isArray(result)) {
+                for (const w of result) {
+                    this.watchers.push(w);
+                }
+                this.logger.debug('Watchers registered', { count: result.length, total: this.watchers.length });
+            }
+            else if (result) {
+                this.watchers.push(result);
+                this.logger.debug('Watcher registered', { total: this.watchers.length });
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to register watcher', err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/hot-reload/manifest-watcher.d.ts

@@ -0,0 +1,9 @@
+import fs from 'node:fs';
+import { ManifestLoader } from '../context/manifest-loader.js';
+export declare function getManifestLoader(cwd: string): ManifestLoader;
+export interface ManifestWatcherDeps {
+    cwd: string;
+    debounceMs: number;
+}
+export declare function watchContextManifest(deps: ManifestWatcherDeps): fs.FSWatcher[];
+//# sourceMappingURL=manifest-watcher.d.ts.map

package/dist/hot-reload/manifest-watcher.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ManifestLoader } from '../context/manifest-loader.js';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('hot-reload:manifest-watcher');
+const loaderInstances = new Map();
+export function getManifestLoader(cwd) {
+    const key = path.resolve(cwd);
+    let loader = loaderInstances.get(key);
+    if (!loader) {
+        loader = new ManifestLoader(key);
+        loaderInstances.set(key, loader);
+    }
+    return loader;
+}
+export function watchContextManifest(deps) {
+    const manifestPath = path.join(deps.cwd, '.agent', 'context-manifest.json');
+    const loader = getManifestLoader(deps.cwd);
+    loader.load();
+    let debounceTimer = null;
+    const handleChange = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            try {
+                loader.reload();
+                logger.info('context-manifest.json reloaded');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.warn('Failed to reload context-manifest.json', { error: msg });
+            }
+        }, deps.debounceMs);
+    };
+    const watcher = fs.watch(manifestPath, handleChange);
+    watcher.on('error', (err) => {
+        logger.warn(`Manifest watcher error: ${err.message}`);
+    });
+    logger.info(`Watching context manifest: ${manifestPath}`);
+    return [watcher];
+}
+//# sourceMappingURL=manifest-watcher.js.map

package/dist/hot-reload/mcp-watcher.d.ts

@@ -0,0 +1,18 @@
+import type { MCPSystem } from '../mcp/system.js';
+interface McpWatcherDeps {
+    mcpSystem: MCPSystem;
+    cwd: string;
+    debounceMs: number;
+}
+/**
+ * 监听 MCP 配置文件变化，自动增/删/改 MCP Server 连接。
+ *
+ * 监听两个文件：.agent/mcp.json 和 .mcp.json。
+ *
+ * 使用 fs.watchFile（原因同 provider-watcher）：
+ *   .agent/ 目录下文件变更频繁，fs.watch 会产生大量无效回调。
+ *   fs.watchFile 以固定间隔 stat 轮询，对极少变更的配置文件开销更低。
+ */
+export declare function watchMcpConfig(deps: McpWatcherDeps): any[];
+export {};
+//# sourceMappingURL=mcp-watcher.d.ts.map

package/dist/hot-reload/mcp-watcher.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createLogger } from '../logging/logger.js';
+/**
+ * 监听 MCP 配置文件变化，自动增/删/改 MCP Server 连接。
+ *
+ * 监听两个文件：.agent/mcp.json 和 .mcp.json。
+ *
+ * 使用 fs.watchFile（原因同 provider-watcher）：
+ *   .agent/ 目录下文件变更频繁，fs.watch 会产生大量无效回调。
+ *   fs.watchFile 以固定间隔 stat 轮询，对极少变更的配置文件开销更低。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function watchMcpConfig(deps) {
+    const logger = createLogger('hot-reload:mcp');
+    const { mcpSystem, cwd } = deps;
+    const watchPaths = [
+        path.join(os.homedir(), '.agent', 'mcp.json'),
+        path.join(cwd, '.mcp.json'),
+    ];
+    const POLL_INTERVAL_MS = 5_000; // 5s — 轻量 stat，对性能几乎无影响
+    let handleLock = false;
+    const lastMtimes = new Map();
+    for (const watchPath of watchPaths) {
+        try {
+            const stat = fs.statSync(watchPath);
+            lastMtimes.set(watchPath, stat.mtimeMs);
+        }
+        catch {
+            // 文件不存在
+        }
+    }
+    async function handleChange() {
+        if (handleLock)
+            return;
+        handleLock = true;
+        try {
+            await mcpSystem.reload();
+            logger.info('MCP configs reloaded via MCPSystem');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn('failed to reload MCP configs', { error: msg });
+        }
+        finally {
+            handleLock = false;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const watchers = [];
+    for (const watchPath of watchPaths) {
+        const watcher = fs.watchFile(watchPath, { interval: POLL_INTERVAL_MS }, (curr) => {
+            const prev = lastMtimes.get(watchPath) ?? 0;
+            if (curr.mtimeMs === prev)
+                return;
+            lastMtimes.set(watchPath, curr.mtimeMs);
+            handleChange();
+        });
+        watchers.push(watcher);
+    }
+    return watchers;
+}
+//# sourceMappingURL=mcp-watcher.js.map

package/dist/hot-reload/model-catalog-watcher.d.ts

@@ -0,0 +1,18 @@
+import type { RuntimeConfigCenter } from '../runtime/config-center.js';
+interface ModelCatalogWatcherDeps {
+    cwd: string;
+    debounceMs: number;
+    configCenter: RuntimeConfigCenter;
+    currentModel: () => {
+        provider: string;
+        model: string;
+    } | undefined;
+}
+/**
+ * 监听 models-catalog.json 文件变化，自动重载模型目录并同步 maxContext。
+ *
+ * 使用 fs.watchFile（原因同 provider-watcher）。
+ */
+export declare function watchModelCatalogConfig(deps: ModelCatalogWatcherDeps): any[];
+export {};
+//# sourceMappingURL=model-catalog-watcher.d.ts.map

package/dist/hot-reload/model-catalog-watcher.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { modelCatalog } from '../provider/catalog.js';
+import { createLogger } from '../logging/logger.js';
+import { getModelContextWindow } from '../setup/model-defaults.js';
+/**
+ * 监听 models-catalog.json 文件变化，自动重载模型目录并同步 maxContext。
+ *
+ * 使用 fs.watchFile（原因同 provider-watcher）。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function watchModelCatalogConfig(deps) {
+    const logger = createLogger('hot-reload:model-catalog');
+    const { cwd } = deps;
+    const watchPath = path.join(os.homedir(), '.agent', 'models-catalog.json');
+    const POLL_INTERVAL_MS = 5_000; // 5s — 轻量 stat，对性能几乎无影响
+    let lastMtime = 0;
+    try {
+        const stat = fs.statSync(watchPath);
+        lastMtime = stat.mtimeMs;
+    }
+    catch {
+        // 文件不存在
+    }
+    function handleChange() {
+        try {
+            modelCatalog.reload();
+            logger.info('model catalog reloaded');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn('failed to reload model catalog', { error: msg });
+            return;
+        }
+        try {
+            const current = deps.currentModel();
+            if (!current)
+                return;
+            const newMaxContext = getModelContextWindow(current.provider, current.model);
+            const currentMaxContext = deps.configCenter.get('session.maxContext');
+            if (currentMaxContext && currentMaxContext <= newMaxContext) {
+                logger.info('session.maxContext kept (user value within new model limit)', { current: currentMaxContext, newLimit: newMaxContext });
+                return;
+            }
+            deps.configCenter.set('session.maxContext', newMaxContext);
+            logger.info('session.maxContext synced after catalog reload', { maxContext: newMaxContext });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn('failed to sync session.maxContext after catalog reload', { error: msg });
+        }
+    }
+    const watcher = fs.watchFile(watchPath, { interval: POLL_INTERVAL_MS }, (curr) => {
+        if (curr.mtimeMs === lastMtime)
+            return;
+        lastMtime = curr.mtimeMs;
+        handleChange();
+    });
+    return [watcher];
+}
+//# sourceMappingURL=model-catalog-watcher.js.map

package/dist/hot-reload/plugin-watcher.d.ts

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import type { PluginManager } from '../plugins/manager.js';
+interface PluginWatcherDeps {
+    pluginManager: PluginManager;
+    cwd: string;
+    debounceMs: number;
+}
+/**
+ * 监听插件目录变化，自动重载插件。
+ *
+ * 监听两个目录：
+ *   - .agent/plugins/
+ *   - plugins/
+ *
+ * 任一目录发生变化时，debounce 后调用 pluginManager.loadAll() 重新扫描并协调。
+ * loadAll() 是幂等的（内部检查 this.plugins.has(manifest.id)）。
+ */
+export declare function watchPluginsDir(deps: PluginWatcherDeps): fs.FSWatcher[];
+export {};
+//# sourceMappingURL=plugin-watcher.d.ts.map

package/dist/hot-reload/plugin-watcher.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createLogger } from '../logging/logger.js';
+/**
+ * 监听插件目录变化，自动重载插件。
+ *
+ * 监听两个目录：
+ *   - .agent/plugins/
+ *   - plugins/
+ *
+ * 任一目录发生变化时，debounce 后调用 pluginManager.loadAll() 重新扫描并协调。
+ * loadAll() 是幂等的（内部检查 this.plugins.has(manifest.id)）。
+ */
+export function watchPluginsDir(deps) {
+    const logger = createLogger('hot-reload:plugins');
+    const userPluginsDir = path.join(os.homedir(), '.agent', 'plugins');
+    try {
+        fs.mkdirSync(userPluginsDir, { recursive: true });
+    }
+    catch { /* ignore */ }
+    const dirs = [userPluginsDir];
+    const projectPluginsDir = path.join(deps.cwd, 'plugins');
+    if (fs.existsSync(projectPluginsDir)) {
+        dirs.push(projectPluginsDir);
+    }
+    let timer = null;
+    const watchers = [];
+    for (const dir of dirs) {
+        try {
+            const watcher = fs.watch(dir, { recursive: false }, (_event, filename) => {
+                if (!filename)
+                    return;
+                if (timer)
+                    clearTimeout(timer);
+                timer = setTimeout(async () => {
+                    try {
+                        logger.info('plugins directory changed, reloading...');
+                        await deps.pluginManager.loadAll();
+                        logger.info('plugins reloaded');
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        logger.warn('plugin reload failed', { error: msg });
+                    }
+                }, deps.debounceMs);
+            });
+            watchers.push(watcher);
+        }
+        catch {
+            // 目录不存在或无法监听，静默跳过
+        }
+    }
+    return watchers;
+}
+//# sourceMappingURL=plugin-watcher.js.map

package/dist/hot-reload/prompt-watcher.d.ts

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+export interface PromptWatcherDeps {
+    debounceMs: number;
+}
+export declare function watchPrompts(deps: PromptWatcherDeps): fs.FSWatcher[];
+//# sourceMappingURL=prompt-watcher.d.ts.map

package/dist/hot-reload/prompt-watcher.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { clearPromptCache, getPromptsDir } from '../prompts/loader.js';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('hot-reload:prompt-watcher');
+export function watchPrompts(deps) {
+    const promptsDir = getPromptsDir();
+    const externalPromptsDir = path.join(os.homedir(), '.agent', 'prompts');
+    let debounceTimer = null;
+    const watchers = [];
+    const handleChange = (_eventType, filename) => {
+        if (!filename || !filename.endsWith('.md'))
+            return;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            clearPromptCache();
+            logger.info(`Prompt cache cleared due to file change: ${filename}`);
+        }, deps.debounceMs);
+    };
+    logger.info(`Watching prompts directory: ${promptsDir}`);
+    const internalWatcher = fs.watch(promptsDir, { recursive: true }, handleChange);
+    internalWatcher.on('error', (err) => {
+        logger.warn(`Prompt watcher error: ${err.message}`, { error: err.message });
+    });
+    watchers.push(internalWatcher);
+    if (fs.existsSync(externalPromptsDir)) {
+        logger.info(`Watching external prompts directory: ${externalPromptsDir}`);
+        const externalWatcher = fs.watch(externalPromptsDir, { recursive: true }, handleChange);
+        externalWatcher.on('error', (err) => {
+            logger.warn(`External prompt watcher error: ${err.message}`, { error: err.message });
+        });
+        watchers.push(externalWatcher);
+    }
+    return watchers;
+}
+//# sourceMappingURL=prompt-watcher.js.map

package/dist/hot-reload/provider-watcher.d.ts

@@ -0,0 +1,16 @@
+interface ProviderWatcherDeps {
+    cwd: string;
+    debounceMs: number;
+}
+/**
+ * 监听 providers.json 文件变化，自动重载 Provider 配置。
+ *
+ * 使用 fs.watchFile 而非 fs.watch：
+ *   providers.json 位于 .agent/ 目录中，该目录下还有其他频繁写入的文件
+ *   （sessions、kb.sqlite、scheduler 等）。fs.watch 会收到所有这些文件的变更事件，
+ *   导致大量无效回调。fs.watchFile 以固定间隔 stat 轮询，仅在文件 mtime 变化时触发，
+ *   对于极少变更的配置文件来说开销更低。
+ */
+export declare function watchProviderConfig(deps: ProviderWatcherDeps): any[];
+export {};
+//# sourceMappingURL=provider-watcher.d.ts.map

package/dist/hot-reload/provider-watcher.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getProviderConfigLoader } from '../provider/config.js';
+import { createLogger } from '../logging/logger.js';
+/**
+ * 监听 providers.json 文件变化，自动重载 Provider 配置。
+ *
+ * 使用 fs.watchFile 而非 fs.watch：
+ *   providers.json 位于 .agent/ 目录中，该目录下还有其他频繁写入的文件
+ *   （sessions、kb.sqlite、scheduler 等）。fs.watch 会收到所有这些文件的变更事件，
+ *   导致大量无效回调。fs.watchFile 以固定间隔 stat 轮询，仅在文件 mtime 变化时触发，
+ *   对于极少变更的配置文件来说开销更低。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function watchProviderConfig(deps) {
+    const logger = createLogger('hot-reload:provider');
+    const { cwd } = deps;
+    const watchPath = path.join(os.homedir(), '.agent', 'providers.json');
+    const POLL_INTERVAL_MS = 5_000; // 5s — 轻量 stat，对性能几乎无影响
+    let lastMtime = 0;
+    try {
+        const stat = fs.statSync(watchPath);
+        lastMtime = stat.mtimeMs;
+    }
+    catch {
+        // 文件不存在，下次创建时会触发
+    }
+    const watcher = fs.watchFile(watchPath, { interval: POLL_INTERVAL_MS }, async (curr) => {
+        if (curr.mtimeMs === lastMtime)
+            return;
+        lastMtime = curr.mtimeMs;
+        try {
+            const loader = getProviderConfigLoader();
+            await loader.reload();
+            logger.info('provider config reloaded');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn('failed to reload provider config', { error: msg });
+        }
+    });
+    return [watcher];
+}
+//# sourceMappingURL=provider-watcher.js.map

package/dist/hot-reload/skill-watcher.d.ts

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import type { SkillDefinition } from '../types.js';
+import type { SkillRegistry } from '../skills/registry.js';
+export interface SkillWatcherDeps {
+    skillRegistry: SkillRegistry;
+    cwd?: string;
+    debounceMs: number;
+    /** 文件 skill 加载/重载后的回调，用于补注册 ContextSource 等 */
+    onSkillLoaded?: (skill: SkillDefinition) => void;
+}
+/**
+ * 监视 skills 目录（用户级 + 项目级）的 .md 文件变更，自动重新加载 skill
+ *
+ * 监视目录：
+ * - ~/.agent/skills/
+ * - <cwd>/.agent/skills/（如果提供了 cwd）
+ */
+export declare function watchSkills(deps: SkillWatcherDeps): fs.FSWatcher[];
+//# sourceMappingURL=skill-watcher.d.ts.map