hyacinth-ai 0.9.6

package/dist/plugins/loader.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('plugin-loader');
+/**
+ * 插件加载器
+ *
+ * 负责扫描插件目录、加载 plugin.json manifest、dynamic import 入口模块。
+ * 搜索路径（按优先级）：
+ *   1. <projectDir>/.agent/plugins/<plugin-id>/
+ *   2. <projectDir>/plugins/                        （内置/开发用）
+ */
+export class PluginLoader {
+    projectDir;
+    constructor(projectDir) {
+        this.projectDir = projectDir;
+    }
+    /**
+     * 扫描所有候选目录，返回发现的 manifest 列表
+     */
+    async discover() {
+        const manifests = [];
+        // 搜索路径
+        const searchDirs = [
+            path.join(this.projectDir, '.agent', 'plugins'),
+            path.join(this.projectDir, 'plugins'),
+        ];
+        for (const dir of searchDirs) {
+            const found = await this.scanDirectory(dir);
+            manifests.push(...found);
+        }
+        return manifests;
+    }
+    /**
+     * 扫描单个目录下的所有插件子目录
+     */
+    async scanDirectory(dir) {
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            const results = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const manifestPath = path.join(dir, entry.name, 'plugin.json');
+                try {
+                    const content = await fs.readFile(manifestPath, 'utf-8');
+                    const manifest = JSON.parse(content);
+                    // 确保 id 与目录名一致（可选约定）
+                    if (!manifest.id)
+                        manifest.id = entry.name;
+                    results.push(manifest);
+                }
+                catch {
+                    // 无 plugin.json 或解析失败，跳过
+                }
+            }
+            return results;
+        }
+        catch {
+            // 目录不存在或无权限
+            return [];
+        }
+    }
+    /**
+     * 加载 manifest 指向的入口模块
+     * 返回模块的 default export（应为 PluginDefinition）
+     */
+    async loadEntryModule(manifest) {
+        // 查找插件目录
+        const pluginDir = await this.resolvePluginDir(manifest);
+        if (!pluginDir)
+            return null;
+        const entryPath = path.resolve(pluginDir, manifest.entry);
+        try {
+            // file:// URL for Windows compatibility with dynamic import
+            // pathToFileURL handles Windows drive letters (C:\) correctly
+            const { pathToFileURL } = await import('node:url');
+            const url = pathToFileURL(entryPath).href;
+            const mod = await import(url);
+            return (mod.default ?? mod);
+        }
+        catch (error) {
+            logger.warn('Failed to load plugin entry module', { pluginId: manifest.id, error: error instanceof Error ? error.message : String(error) });
+            return null;
+        }
+    }
+    /**
+     * 获取插件目录的绝对路径
+     */
+    async getPluginDir(manifest) {
+        return this.resolvePluginDir(manifest);
+    }
+    /**
+     * 读取插件配置文件（.agent/plugins.config.json）
+     */
+    async loadPluginConfig() {
+        const configPath = path.join(this.projectDir, '.agent', 'plugins.config.json');
+        try {
+            const content = await fs.readFile(configPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            return (parsed?.plugins ?? {});
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * 解析插件目录位置
+     */
+    async resolvePluginDir(manifest) {
+        const candidates = [
+            path.join(this.projectDir, '.agent', 'plugins', manifest.id),
+            path.join(this.projectDir, 'plugins', manifest.id),
+        ];
+        for (const dir of candidates) {
+            try {
+                const stat = await fs.stat(dir);
+                if (stat.isDirectory())
+                    return dir;
+            }
+            catch {
+                // 不存在，继续
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/plugins/manager.d.ts

@@ -0,0 +1,61 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { SkillRegistry } from '../skills/registry.js';
+import type { LayeredContextComposer } from '../context/composer.js';
+import type { MCPSystem } from '../mcp/system.js';
+import type { PluginInstance } from './types.js';
+import type { ChannelManager } from '../channels/manager.js';
+export type PluginManagerDeps = {
+    toolRegistry: ToolRegistry;
+    skillRegistry: SkillRegistry;
+    contextComposer: LayeredContextComposer;
+    projectDir: string;
+    /** 渠道管理器（可选 — 支持插件注册渠道） */
+    channelManager?: ChannelManager;
+    /** MCP 系统 — 插件 MCP Server 统一委托 MCPSystem 管理生命周期 */
+    mcpSystem?: MCPSystem;
+};
+/**
+ * PluginManager — 插件生命周期管理器
+ *
+ * 职责：
+ *  - 发现插件（扫描目录加载 manifest）
+ *  - 加载插件（dynamic import 入口模块）
+ *  - 激活插件（调用 register()，提供 PluginApi）
+ *  - 连接插件的 MCP Server
+ *  - 注册插件的 Skill ContextSource
+ *  - 停用/清理
+ */
+export declare class PluginManager {
+    private plugins;
+    private loader;
+    private deps;
+    private logger;
+    /** MCP Server 注册队列（等待所有插件 register 完成后统一连接） */
+    private pendingMcpConfigs;
+    /** 追踪每个插件注册的项目（用于 deactivate 时清理） */
+    private pluginRegistrations;
+    constructor(deps: PluginManagerDeps);
+    /** 获取所有插件实例 */
+    getAll(): PluginInstance[];
+    /** 获取指定插件 */
+    get(id: string): PluginInstance | undefined;
+    /** 获取已激活的插件 */
+    getActivated(): PluginInstance[];
+    /** 完整流程：发现 → 加载 → 激活 → 连接 MCP → 注册 Skill 源 */
+    loadAll(): Promise<void>;
+    /** 激活指定插件 */
+    activate(id: string, config?: Record<string, unknown>): Promise<void>;
+    /** 停用指定插件 */
+    deactivate(id: string): Promise<void>;
+    /** 加载一个插件的 manifest + entry module */
+    private loadPlugin;
+    /** 激活插件：创建 PluginApi → 调用 register() → 标记 activated */
+    private activatePlugin;
+    /** 为插件创建 PluginApi */
+    private createApiForPlugin;
+    /** 将插件注册的 MCP Server 统一委托 MCPSystem 管理 */
+    private connectPluginMcpServers;
+    /** 注册插件提供的 Skill 为 ContextSource */
+    private registerPluginSkillSources;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/plugins/manager.js

@@ -0,0 +1,257 @@
+import { PluginLoader } from './loader.js';
+import { createPluginApi } from './api.js';
+import { createLogger } from '../logging/logger.js';
+/**
+ * PluginManager — 插件生命周期管理器
+ *
+ * 职责：
+ *  - 发现插件（扫描目录加载 manifest）
+ *  - 加载插件（dynamic import 入口模块）
+ *  - 激活插件（调用 register()，提供 PluginApi）
+ *  - 连接插件的 MCP Server
+ *  - 注册插件的 Skill ContextSource
+ *  - 停用/清理
+ */
+export class PluginManager {
+    plugins = new Map();
+    loader;
+    deps;
+    logger;
+    /** MCP Server 注册队列（等待所有插件 register 完成后统一连接） */
+    pendingMcpConfigs = [];
+    /** 追踪每个插件注册的项目（用于 deactivate 时清理） */
+    pluginRegistrations = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.loader = new PluginLoader(deps.projectDir);
+        this.logger = createLogger('plugins');
+    }
+    // =============================================================
+    // Public API
+    // =============================================================
+    /** 获取所有插件实例 */
+    getAll() {
+        return [...this.plugins.values()];
+    }
+    /** 获取指定插件 */
+    get(id) {
+        return this.plugins.get(id);
+    }
+    /** 获取已激活的插件 */
+    getActivated() {
+        return this.getAll().filter((p) => p.status === 'activated');
+    }
+    /** 完整流程：发现 → 加载 → 激活 → 连接 MCP → 注册 Skill 源 */
+    async loadAll() {
+        const manifests = await this.loader.discover();
+        if (manifests.length === 0) {
+            this.logger.info('no plugins found');
+            return;
+        }
+        this.logger.info('plugins discovered', { count: manifests.length, ids: manifests.map((m) => m.id) });
+        const pluginConfigs = await this.loader.loadPluginConfig();
+        for (const manifest of manifests) {
+            await this.loadPlugin(manifest);
+        }
+        for (const instance of this.plugins.values()) {
+            if (instance.status === 'loaded') {
+                const config = pluginConfigs[instance.manifest.id] ?? {};
+                await this.activatePlugin(instance, config);
+            }
+        }
+        // 连接插件注册的 MCP Server
+        await this.connectPluginMcpServers();
+        // 注册 Skill ContextSource
+        this.registerPluginSkillSources();
+    }
+    /** 激活指定插件 */
+    async activate(id, config) {
+        const instance = this.plugins.get(id);
+        if (!instance)
+            throw new Error(`Plugin "${id}" not found`);
+        if (instance.status === 'activated')
+            return;
+        const pluginConfigs = config ?? (await this.loader.loadPluginConfig())[id] ?? {};
+        await this.activatePlugin(instance, pluginConfigs);
+    }
+    /** 停用指定插件 */
+    async deactivate(id) {
+        const instance = this.plugins.get(id);
+        if (!instance)
+            throw new Error(`Plugin "${id}" not found`);
+        if (instance.status !== 'activated')
+            return;
+        try {
+            await instance.definition.onDeactivate?.(this.createApiForPlugin(instance, {}));
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`error deactivating`, new Error(msg), { plugin: id });
+        }
+        // 清理插件注册的所有项目
+        const reg = this.pluginRegistrations.get(id);
+        if (reg) {
+            // 取消注册 tools
+            for (const name of reg.tools) {
+                this.deps.toolRegistry.unregister(name);
+            }
+            // 取消注册 skills
+            for (const name of reg.skills) {
+                this.deps.skillRegistry.unregister(name);
+            }
+            // 取消注册 context sources
+            for (const name of reg.contextSources) {
+                if (this.deps.contextComposer.unregisterSource) {
+                    this.deps.contextComposer.unregisterSource(name);
+                }
+            }
+            // 清理插件注册的 MCP Server（通过 MCPSystem 统一管理）
+            if (this.deps.mcpSystem && reg.mcpServers.length > 0) {
+                for (const serverName of reg.mcpServers) {
+                    this.deps.mcpSystem.removeExternalServer(serverName).catch((err) => {
+                        this.logger.warn(`failed to remove plugin MCP server "${serverName}"`, { error: err.message });
+                    });
+                }
+            }
+            this.pluginRegistrations.delete(id);
+        }
+        instance.status = 'deactivated';
+        this.logger.info('deactivated', { plugin: id });
+    }
+    // =============================================================
+    // Internal
+    // =============================================================
+    /** 加载一个插件的 manifest + entry module */
+    async loadPlugin(manifest) {
+        if (this.plugins.has(manifest.id)) {
+            this.logger.warn('duplicate plugin id, skipping', { plugin: manifest.id });
+            return;
+        }
+        const dir = await this.loader.getPluginDir(manifest);
+        if (!dir) {
+            this.logger.warn('plugin directory not found, skipping', { plugin: manifest.id });
+            return;
+        }
+        const definition = await this.loader.loadEntryModule(manifest);
+        if (!definition) {
+            this.plugins.set(manifest.id, {
+                manifest,
+                definition: { id: manifest.id, name: manifest.name, description: manifest.description, register: () => { } },
+                status: 'error',
+                mcpServers: [],
+                dir,
+                error: 'Failed to load entry module',
+            });
+            return;
+        }
+        // 验证 definition id 与 manifest 一致
+        if (definition.id && definition.id !== manifest.id) {
+            this.logger.warn('definition id mismatch', { manifest: manifest.id, definition: definition.id });
+        }
+        const instance = {
+            manifest,
+            definition,
+            status: 'loaded',
+            mcpServers: [],
+            dir,
+        };
+        this.plugins.set(manifest.id, instance);
+    }
+    /** 激活插件：创建 PluginApi → 调用 register() → 标记 activated */
+    async activatePlugin(instance, config) {
+        const { id } = instance.manifest;
+        try {
+            const api = this.createApiForPlugin(instance, config);
+            await instance.definition.register(api);
+            await instance.definition.onActivate?.(api);
+            instance.status = 'activated';
+            this.logger.info('activated', { plugin: id });
+        }
+        catch (error) {
+            instance.status = 'error';
+            instance.error = error instanceof Error ? error.message : String(error);
+            this.logger.error(`failed to activate`, error instanceof Error ? error : new Error(String(error)), { plugin: id });
+        }
+    }
+    /** 为插件创建 PluginApi */
+    createApiForPlugin(instance, config) {
+        const pluginId = instance.manifest.id;
+        // 初始化追踪记录
+        const reg = { tools: [], skills: [], mcpServers: [], contextSources: [] };
+        this.pluginRegistrations.set(pluginId, reg);
+        return createPluginApi({
+            pluginId,
+            toolRegistry: this.deps.toolRegistry,
+            skillRegistry: this.deps.skillRegistry,
+            contextComposer: this.deps.contextComposer,
+            pluginConfig: config,
+            pendingMcpConfigs: this.pendingMcpConfigs,
+            onMcpServerRegister: (pid, mcpConfig) => {
+                this.pendingMcpConfigs.push({ pluginId: pid, config: mcpConfig });
+                instance.mcpServers.push(mcpConfig);
+                reg.mcpServers.push(mcpConfig.name);
+            },
+            onToolRegister: (name) => {
+                reg.tools.push(name);
+            },
+            onSkillRegister: (name) => {
+                reg.skills.push(name);
+            },
+            onContextSourceRegister: (name) => {
+                reg.contextSources.push(name);
+            },
+            onMcpServerUnregister: (name) => {
+                const idx = reg.mcpServers.indexOf(name);
+                if (idx >= 0)
+                    reg.mcpServers.splice(idx, 1);
+            },
+            // 渠道注册回调 → ChannelManager
+            onChannelRegister: (handler, config) => {
+                if (this.deps.channelManager) {
+                    this.deps.channelManager.register(handler, config);
+                    this.logger.info('plugin registered channel', { plugin: instance.manifest.id, channel: handler.id });
+                }
+                else {
+                    this.logger.warn('no ChannelManager available, channel not registered', { channel: handler.id });
+                }
+            },
+        });
+    }
+    /** 将插件注册的 MCP Server 统一委托 MCPSystem 管理 */
+    async connectPluginMcpServers() {
+        if (this.pendingMcpConfigs.length === 0)
+            return;
+        // 如果没有注入 MCPSystem，跳过（保持向后兼容，插件 MCP 功能不可用）
+        if (!this.deps.mcpSystem) {
+            this.logger.warn('no MCPSystem available, skipping plugin MCP servers', { count: this.pendingMcpConfigs.length });
+            return;
+        }
+        this.logger.info('delegating plugin MCP servers to MCPSystem', { count: this.pendingMcpConfigs.length });
+        const configs = this.pendingMcpConfigs.map(({ config }) => config);
+        // loadAll() 在启动时调用，此时无对话缓存，用 isHotPlug: false → Zone 2
+        await this.deps.mcpSystem.addExternalServers(configs, { isHotPlug: false });
+    }
+    /** 注册插件提供的 Skill 为 ContextSource */
+    registerPluginSkillSources() {
+        for (const instance of this.getActivated()) {
+            const skillDirs = instance.manifest.skills;
+            if (!skillDirs || skillDirs.length === 0)
+                continue;
+            // 插件 register 时已经通过 api.registerSkill() 注册了 SkillDefinition
+            // 这里为每个已注册的 Skill 添加 lazy_expand ContextSource
+            const pluginSkills = this.deps.skillRegistry
+                .getAll()
+                .filter((s) => s.name.startsWith(instance.manifest.id + '-'));
+            for (const skill of pluginSkills) {
+                this.deps.contextComposer.registerSource({
+                    name: `plugin-skill-${skill.name}`,
+                    strategy: 'lazy_expand',
+                    cacheability: 'manifest',
+                    description: skill.description,
+                    getContent: () => this.deps.skillRegistry.getFullDefinitions([skill.name]),
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/plugins/types.d.ts

@@ -0,0 +1,82 @@
+import type { Tool } from '../tools/interface.js';
+import type { SkillDefinition, MCPConfig } from '../types.js';
+import type { ContextSource } from '../context/interface.js';
+import type { ChannelHandler, ChannelConfig } from '../channels/interface.js';
+/**
+ * Plugin manifest format（plugin.json）
+ *
+ * 存放于 .agent/plugins/<plugin-id>/plugin.json 或
+ * plugins/<plugin-id>/plugin.json
+ */
+export interface PluginManifest {
+    /** 唯一插件 ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 简短描述 */
+    description: string;
+    /** 入口模块路径（相对于 manifest 目录） */
+    entry: string;
+    /** 默认是否启用 */
+    enabledByDefault?: boolean;
+    /** Skill 定义目录列表（相对于 manifest 目录） */
+    skills?: string[];
+    /** 配置的 JSON Schema */
+    configSchema?: Record<string, unknown>;
+    /** 插件版本 */
+    version?: string;
+}
+export interface PluginDefinition {
+    id: string;
+    name: string;
+    description: string;
+    configSchema?: Record<string, unknown>;
+    register: (api: PluginApi) => void | Promise<void>;
+    onActivate?: (api: PluginApi) => void | Promise<void>;
+    onDeactivate?: (api: PluginApi) => void | Promise<void>;
+}
+export interface PluginLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+}
+export interface PluginApi {
+    /** 注册一个工具到 ToolRegistry */
+    registerTool(tool: Tool): void;
+    /** 注册一个 Skill */
+    registerSkill(skill: SkillDefinition): void;
+    /** 注册一个 ContextSource */
+    registerContextSource(source: ContextSource): void;
+    /** 注册一个 MCP Server 配置（PluginManager 负责连接和桥接） */
+    registerMcpServer(config: MCPConfig): void;
+    /** 注册一个渠道处理器（将插件扩展为 IM / Webhook / 自定义消息源） */
+    registerChannel(handler: ChannelHandler, config?: ChannelConfig): void;
+    /** 取消注册一个工具 */
+    unregisterTool(name: string): void;
+    /** 取消注册一个 Skill */
+    unregisterSkill(name: string): void;
+    /** 取消注册一个 MCP Server */
+    unregisterMcpServer(name: string): void;
+    /** 取消注册一个 ContextSource */
+    unregisterContextSource(name: string): void;
+    /** 获取插件自身的配置 */
+    getConfig<T = Record<string, unknown>>(): T;
+    /** 日志记录器 */
+    logger: PluginLogger;
+    /** 插件 ID */
+    pluginId: string;
+}
+export type PluginStatus = 'discovered' | 'loaded' | 'activated' | 'deactivated' | 'error';
+export interface PluginInstance {
+    manifest: PluginManifest;
+    definition: PluginDefinition;
+    status: PluginStatus;
+    /** 注册的 MCP Server 列表（待连接） */
+    mcpServers: MCPConfig[];
+    /** 插件目录绝对路径 */
+    dir: string;
+    /** 错误信息（status 为 error 时） */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.js

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

package/dist/prompts/agents/code-reviewer.md

@@ -0,0 +1,16 @@
+你是代码审查专家。你的职责是审查代码的质量、可读性和最佳实践。
+
+审查要点：
+- 代码是否清晰易懂
+- 是否遵循项目约定和最佳实践
+- 是否有潜在的 bug 或逻辑错误
+- 命名是否恰当
+- 函数/方法是否过长或职责不清
+
+审查时请：
+1. 先阅读相关文件
+2. 逐项检查上述要点
+3. 给出具体的改进建议，包含代码示例
+4. 按严重程度分级：🔴 严重 🟡 建议 🟢 良好
+
+任务：{{task}}

package/dist/prompts/agents/security-auditor.md

@@ -0,0 +1,17 @@
+你是安全审计专家。你的职责是检查代码中的安全漏洞和风险。
+
+审计要点：
+- 输入验证和注入攻击（SQL注入、XSS、命令注入等）
+- 认证和授权问题
+- 敏感数据泄露（硬编码密钥、日志泄露等）
+- 不安全的加密或哈希
+- 路径遍历和文件系统安全
+- 依赖库的已知漏洞
+
+审计时请：
+1. 仔细阅读所有相关代码
+2. 逐项检查上述安全要点
+3. 对每个发现给出：漏洞类型、风险等级、攻击场景、修复建议
+4. 按风险分级：🔴 高危 🟡 中危 🔵 低危
+
+任务：{{task}}

package/dist/prompts/agents/test-writer.md

@@ -0,0 +1,15 @@
+你是测试编写专家。你的职责是为代码编写全面的测试。
+
+编写测试时请：
+1. 先阅读需要测试的代码，理解其功能
+2. 识别所有关键路径和边界条件
+3. 编写覆盖以下场景的测试：
+   - 正常路径（happy path）
+   - 边界条件
+   - 错误处理
+   - 异常输入
+4. 使用项目现有的测试框架
+5. 测试命名清晰，描述测试意图
+6. 每个测试只验证一个行为
+
+任务：{{task}}

package/dist/prompts/attention/attention.md

@@ -0,0 +1,12 @@
+注意事项:
+- 减少不必要的对话轮次：能并行的独立工具调用一次发出，不要逐个等待
+- 修改代码前先阅读相关代码，理解上下文
+- 优先使用现有工具和函数，避免重复实现
+- 执行命令时注意安全性，避免破坏性操作
+- 对敏感信息(密码，密钥，等)不要输出
+- 对于不确定的操作，先向用户确认
+- 做项目需要模块化，可验证，独立解耦，保持结构清晰
+- 复杂任务可以使用TODO，SPEC等去做
+- 复杂任务可交由子agent去完成，和验收，你统领全局
+- 回复干净简洁，策划阶段不输出代码，具体执行再输出代码
+- 可以使用各种skill来协助，子智能体你可以在编排提示词阶段之间传入skill

package/dist/prompts/environment/environment.md

@@ -0,0 +1,18 @@
+工作目录: {{cwd}}
+
+## 数据存储
+
+- 全局配置目录: `{{globalConfigDir}}`
+- 全局配置: `{{globalConfigDir}}/config.json`
+- 全局 API Key: `{{globalConfigDir}}/.env`
+- 全局身份提示词: `{{globalConfigDir}}/prompts/persona/*.md`
+- 项目配置: `{{cwd}}/.agent/config.json`
+- 渠道配置: 项目级 `{{cwd}}/.agent/config.json` 的 `channels` 字段
+- MCP 配置: `{{cwd}}/.agent/mcp.json`
+- 工具包配置: `{{cwd}}/.agent/tool-bundles.json`
+- Provider 元数据: `{{cwd}}/.agent/providers.json`
+- 本地模型配置: `{{cwd}}/.agent/models.json` 或 `{{cwd}}/.agent/local-models.json`
+- 会话记录: `{{globalConfigDir}}/sessions/` 目录下，每个会话一个子目录
+  - 会话目录格式: `YYYYMMDD-HHMMSS-XXXX`
+  - 包含 `conversation.jsonl`（对话历史）、`events.jsonl`（事件）、`stats.json`（统计）
+  - 用 `glob` 列出目录，用 `read` 读取历史对话