@eoasmxd/freya 0.4.0 → 0.4.2

package/plugins/plugin-gemini/package.json

@@ -18,7 +18,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0"
+    "@eoasmxd/freya-sdk": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/plugin-openai/package.json

@@ -18,7 +18,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0"
+    "@eoasmxd/freya-sdk": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/plugin-telegram-channel/package.json

@@ -19,7 +19,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0"
+    "@eoasmxd/freya-sdk": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/plugin-tool-fs/package.json

@@ -21,7 +21,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0"
+    "@eoasmxd/freya-sdk": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/plugin-tool-memory/package.json

@@ -21,7 +21,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0"
+    "@eoasmxd/freya-sdk": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/plugin-tool-mysql/config/prompts/plugin.prompt.mysql.md

@@ -0,0 +1,9 @@
+MySQL 数据库查询工具箱。
+
+提供执行标准 SQL 只读查询语句并返回结构化 JSON 数据结果的能力。
+
+使用规范：
+1. 本工具仅支持执行 SELECT 查询语句，严禁执行任何非 SELECT 语句，禁止执行任何增删改或 DDL 破坏性语句。
+2. 严禁主观猜测表名与字段名，必须严格基于上下文或业务 Skill 指南中确定、已知的数据结构编写 SQL。
+3. 支持通过 `connection` 参数指定目标数据库连接名称，若不传则自动使用默认连接。
+4. 单次查询返回结果条数受到系统安全限制截断，编写查询时建议显式使用合理的 `LIMIT` 子句。

package/plugins/plugin-tool-mysql/config/prompts/plugin.prompt.mysql.select.audit.md

@@ -0,0 +1,26 @@
+你是一个严格的 SQL 安全与完整性审查审计员。你的唯一职责是对待执行的 SQL 查询语句进行安全与完整性审查。
+
+审查准则：
+1. **完整性审查**：
+   - SQL 语句必须语法结构完整、语义明确。
+   - 严禁包含伪代码、截断残缺语句或未闭合的括号/引号。
+
+2. **只读安全约束**：
+   - 必须仅为 SELECT 查询操作（仅允许 SELECT 查询语句，严禁执行 SHOW、EXPLAIN、DESCRIBE 等其他语句）。
+   - 严禁包含任何数据修改语句（如 INSERT、UPDATE、DELETE、REPLACE 等）。
+   - 严禁包含任何数据定义与删除语句（如 DROP、TRUNCATE、ALTER、CREATE 等）。
+   - 严禁包含权限管理、事务控制等系统级命令（如 GRANT、REVOKE、LOCK TABLES 等）。
+   - 严禁利用分号 `;` 拼接多条执行语句进行批处理或 SQL 注入攻击。
+   - 严禁包含高危文件读写或外部系统交互指令（如 INTO OUTFILE、INTO DUMPFILE、LOAD DATA、LOAD_FILE 等）。
+
+输出规范：
+请直接返回合法且不包含 Markdown 代码块标记（如 ```json）的纯 JSON 字符串，格式如下：
+{
+  "passed": true,
+  "reason": "审核通过，为合法的只读查询语句。"
+}
+或
+{
+  "passed": false,
+  "reason": "具体的拦截阻断原因"
+}

package/plugins/plugin-tool-mysql/dist/audit.d.ts

@@ -0,0 +1,13 @@
+import type { FreyaContext } from '@eoasmxd/freya-sdk';
+export interface AuditResult {
+    passed: boolean;
+    reason: string;
+}
+/** 前置 SQL 安全与完整性审查审计服务 */
+export declare class SqlAuditService {
+    private cachedPrompt;
+    /** 双通道探针加载审计提示词模板 */
+    private loadAuditPrompt;
+    /** 执行前置独立 LLM 分析审查 */
+    audit(sql: string, connectionName: string, ctx: FreyaContext): Promise<AuditResult>;
+}

package/plugins/plugin-tool-mysql/dist/audit.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 前置 SQL 安全与完整性审查审计服务 */
+export class SqlAuditService {
+    cachedPrompt = null;
+    /** 双通道探针加载审计提示词模板 */
+    async loadAuditPrompt(ctx) {
+        if (this.cachedPrompt) {
+            return this.cachedPrompt;
+        }
+        const promptFileName = 'plugin.prompt.mysql.select.audit.md';
+        const runtimeOverridePath = path.join(ctx.paths.projectRoot, 'config', 'prompts', promptFileName);
+        try {
+            const content = await fs.readFile(runtimeOverridePath, 'utf-8');
+            if (content.trim()) {
+                this.cachedPrompt = content;
+                return content;
+            }
+        }
+        catch {
+            // 运行时覆盖不存在，继续降级读取内置模板
+        }
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const packageDefaultPath = path.resolve(currentDir, '..', 'config', 'prompts', promptFileName);
+        try {
+            const content = await fs.readFile(packageDefaultPath, 'utf-8');
+            this.cachedPrompt = content;
+            return content;
+        }
+        catch (err) {
+            ctx.logger.error(`加载内置 SQL 审计提示词模板失败: ${packageDefaultPath}`, err);
+            return '';
+        }
+    }
+    /** 执行前置独立 LLM 分析审查 */
+    async audit(sql, connectionName, ctx) {
+        const trimmedSql = sql.trim();
+        if (!trimmedSql) {
+            return { passed: false, reason: 'SQL 语句内容不能为空。' };
+        }
+        const auditPrompt = await this.loadAuditPrompt(ctx);
+        if (!auditPrompt) {
+            return { passed: false, reason: 'SQL 审计提示词模板未就绪，安全拒绝执行。' };
+        }
+        const messages = [
+            {
+                role: 'system',
+                content: auditPrompt
+            },
+            {
+                role: 'user',
+                content: JSON.stringify({
+                    connection: connectionName,
+                    sql: trimmedSql
+                }, null, 2)
+            }
+        ];
+        try {
+            const response = await ctx.llm.chat(messages);
+            const rawOutput = response.message?.content?.trim() || '';
+            const cleaned = rawOutput
+                .replace(/^```json\s*/i, '')
+                .replace(/^```\s*/i, '')
+                .replace(/\s*```$/i, '')
+                .trim();
+            const parsed = JSON.parse(cleaned);
+            if (typeof parsed.passed === 'boolean') {
+                return {
+                    passed: parsed.passed,
+                    reason: parsed.reason ? String(parsed.reason) : (parsed.passed ? '审查通过' : '未提供拦截原因')
+                };
+            }
+            return {
+                passed: false,
+                reason: `审查响应结构不符合预期: ${rawOutput}`
+            };
+        }
+        catch (err) {
+            ctx.logger.error('前置 LLM SQL 审计过程发生异常', err);
+            return {
+                passed: false,
+                reason: `SQL 安全审查服务调用失败: ${err?.message || err}`
+            };
+        }
+    }
+}

package/plugins/plugin-tool-mysql/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { FreyaContext, ToolPlugin, FreyaTool } from '@eoasmxd/freya-sdk';
+/** MySQL 数据库查询工具箱插件 */
+export default class MysqlToolsPlugin implements ToolPlugin {
+    type: "tool";
+    private poolManager?;
+    private auditService;
+    private tools;
+    setup(ctx: FreyaContext): Promise<void>;
+    getId(): string;
+    getInstructionPrompt(): string;
+    getTools(): FreyaTool[];
+    stop(ctx: FreyaContext): Promise<void>;
+}
+export declare const Plugin: typeof MysqlToolsPlugin;

package/plugins/plugin-tool-mysql/dist/index.js

@@ -0,0 +1,34 @@
+import { MysqlPoolManager } from './pool-manager.js';
+import { SqlAuditService } from './audit.js';
+import { MysqlQueryTool } from './tools.js';
+/** MySQL 数据库查询工具箱插件 */
+export default class MysqlToolsPlugin {
+    type = 'tool';
+    poolManager;
+    auditService = new SqlAuditService();
+    tools = [];
+    async setup(ctx) {
+        this.poolManager = new MysqlPoolManager(ctx);
+        this.tools = [
+            new MysqlQueryTool(this.poolManager, this.auditService)
+        ];
+        const available = this.poolManager.getAvailableConnectionNames();
+        ctx.logger.info(`MySQL 工具箱插件初始化就绪，已注册连接: [${available.join(', ') || '暂未配置'}]`);
+    }
+    getId() {
+        return 'mysql';
+    }
+    getInstructionPrompt() {
+        return 'plugin.prompt.mysql';
+    }
+    getTools() {
+        return this.tools;
+    }
+    async stop(ctx) {
+        if (this.poolManager) {
+            await this.poolManager.closeAll();
+            ctx.logger.info('MySQL 工具箱连接资源已全部释放。');
+        }
+    }
+}
+export const Plugin = MysqlToolsPlugin;

package/plugins/plugin-tool-mysql/dist/pool-manager.d.ts

@@ -0,0 +1,32 @@
+import mysql from 'mysql2/promise';
+import type { FreyaContext } from '@eoasmxd/freya-sdk';
+/** MySQL 连接配置契约 */
+export interface MysqlConnectionConfig {
+    name: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionLimit?: number;
+    connectTimeout?: number;
+}
+/** MySQL 多命名连接池管理器 */
+export declare class MysqlPoolManager {
+    private ctx;
+    private pools;
+    private connectionConfigs;
+    private defaultConnectionName;
+    constructor(ctx: FreyaContext);
+    /** 加载与同步配置 */
+    reloadConfigs(): void;
+    /** 获取指定名称的数据库连接池 */
+    getPool(targetName?: string): {
+        pool: mysql.Pool;
+        config: MysqlConnectionConfig;
+    };
+    /** 获取所有可用连接名称 */
+    getAvailableConnectionNames(): string[];
+    /** 释放所有已建立的连接池资源 */
+    closeAll(): Promise<void>;
+}

package/plugins/plugin-tool-mysql/dist/pool-manager.js

@@ -0,0 +1,113 @@
+import mysql from 'mysql2/promise';
+/** 安全解算嵌套或扁平配置值 */
+function getNestedConfig(config, keyPath) {
+    if (!config)
+        return undefined;
+    if (keyPath in config)
+        return config[keyPath];
+    const parts = keyPath.split('.');
+    let current = config;
+    for (const part of parts) {
+        if (current && typeof current === 'object' && part in current) {
+            current = current[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+/** MySQL 多命名连接池管理器 */
+export class MysqlPoolManager {
+    ctx;
+    pools = new Map();
+    connectionConfigs = new Map();
+    defaultConnectionName = 'default';
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.reloadConfigs();
+    }
+    /** 加载与同步配置 */
+    reloadConfigs() {
+        this.connectionConfigs.clear();
+        const config = this.ctx.config || {};
+        this.defaultConnectionName = getNestedConfig(config, 'mysql.defaultConnection') || 'default';
+        const connections = getNestedConfig(config, 'mysql.connections');
+        if (Array.isArray(connections)) {
+            for (const item of connections) {
+                if (item && typeof item === 'object' && item.name) {
+                    this.connectionConfigs.set(item.name, {
+                        name: String(item.name),
+                        host: item.host ? String(item.host) : '127.0.0.1',
+                        port: item.port ? Number(item.port) : 3306,
+                        user: item.user ? String(item.user) : 'root',
+                        password: item.password ? String(item.password) : '',
+                        database: item.database ? String(item.database) : undefined,
+                        connectionLimit: item.connectionLimit ? Number(item.connectionLimit) : 5,
+                        connectTimeout: item.connectTimeout ? Number(item.connectTimeout) : 10000
+                    });
+                }
+            }
+        }
+        if (this.connectionConfigs.size === 0) {
+            const singleHost = getNestedConfig(config, 'mysql.host');
+            if (singleHost) {
+                this.connectionConfigs.set(this.defaultConnectionName, {
+                    name: this.defaultConnectionName,
+                    host: String(singleHost),
+                    port: getNestedConfig(config, 'mysql.port') ? Number(getNestedConfig(config, 'mysql.port')) : 3306,
+                    user: getNestedConfig(config, 'mysql.user') ? String(getNestedConfig(config, 'mysql.user')) : 'root',
+                    password: getNestedConfig(config, 'mysql.password') ? String(getNestedConfig(config, 'mysql.password')) : '',
+                    database: getNestedConfig(config, 'mysql.database') ? String(getNestedConfig(config, 'mysql.database')) : undefined,
+                    connectionLimit: getNestedConfig(config, 'mysql.connectionLimit') ? Number(getNestedConfig(config, 'mysql.connectionLimit')) : 5,
+                    connectTimeout: getNestedConfig(config, 'mysql.connectTimeout') ? Number(getNestedConfig(config, 'mysql.connectTimeout')) : 10000
+                });
+            }
+        }
+    }
+    /** 获取指定名称的数据库连接池 */
+    getPool(targetName) {
+        this.reloadConfigs();
+        const connectionName = targetName || this.defaultConnectionName;
+        const conf = this.connectionConfigs.get(connectionName);
+        if (!conf) {
+            const available = Array.from(this.connectionConfigs.keys()).join(', ') || '无配置';
+            throw new Error(`未找到名为 "${connectionName}" 的 MySQL 连接配置。当前可用连接: [${available}]`);
+        }
+        let pool = this.pools.get(connectionName);
+        if (!pool) {
+            pool = mysql.createPool({
+                host: conf.host,
+                port: conf.port,
+                user: conf.user,
+                password: conf.password,
+                database: conf.database,
+                connectionLimit: conf.connectionLimit,
+                connectTimeout: conf.connectTimeout,
+                waitForConnections: true,
+                queueLimit: 0,
+                dateStrings: true
+            });
+            this.pools.set(connectionName, pool);
+            this.ctx.logger.info(`MySQL 连接池已创建: [${connectionName}] -> ${conf.user}@${conf.host}:${conf.port}/${conf.database || ''}`);
+        }
+        return { pool, config: conf };
+    }
+    /** 获取所有可用连接名称 */
+    getAvailableConnectionNames() {
+        return Array.from(this.connectionConfigs.keys());
+    }
+    /** 释放所有已建立的连接池资源 */
+    async closeAll() {
+        for (const [name, pool] of this.pools.entries()) {
+            try {
+                await pool.end();
+                this.ctx.logger.info(`MySQL 连接池已释放: [${name}]`);
+            }
+            catch (err) {
+                this.ctx.logger.warn(`关闭 MySQL 连接池 [${name}] 时发生异常: ${err?.message || err}`);
+            }
+        }
+        this.pools.clear();
+    }
+}

package/plugins/plugin-tool-mysql/dist/tools.d.ts

@@ -0,0 +1,11 @@
+import type { FreyaContext, ToolDefinition, FreyaTool } from '@eoasmxd/freya-sdk';
+import type { MysqlPoolManager } from './pool-manager.js';
+import type { SqlAuditService } from './audit.js';
+/** MySQL 数据库查询执行工具 */
+export declare class MysqlQueryTool implements FreyaTool {
+    private poolManager;
+    private auditService;
+    constructor(poolManager: MysqlPoolManager, auditService: SqlAuditService);
+    getDefinition(): ToolDefinition;
+    execute(args: Record<string, any>, ctx: FreyaContext): Promise<string>;
+}

package/plugins/plugin-tool-mysql/dist/tools.js

@@ -0,0 +1,88 @@
+/** 脱敏错误信息中的敏感凭据 */
+function sanitizeErrorMessage(err, password) {
+    let message = err?.message || String(err);
+    if (password) {
+        message = message.replaceAll(password, '******');
+    }
+    return message;
+}
+/** MySQL 数据库查询执行工具 */
+export class MysqlQueryTool {
+    poolManager;
+    auditService;
+    constructor(poolManager, auditService) {
+        this.poolManager = poolManager;
+        this.auditService = auditService;
+    }
+    getDefinition() {
+        return {
+            name: 'mysql_query',
+            description: '执行 MySQL SELECT 查询语句并返回结构化数据。执行前会进行独立 LLM 安全与完整性审核，支持通过 connection 指定目标连接。',
+            parameters: {
+                type: 'object',
+                properties: {
+                    sql: {
+                        type: 'string',
+                        description: '待执行的 SQL 查询语句'
+                    },
+                    connection: {
+                        type: 'string',
+                        description: '目标数据库连接名称（可选，若未指定则使用系统默认连接）'
+                    },
+                    params: {
+                        type: 'array',
+                        items: {},
+                        description: '可选的参数化查询参数列表'
+                    }
+                },
+                required: ['sql']
+            }
+        };
+    }
+    async execute(args, ctx) {
+        const rawSql = typeof args.sql === 'string' ? args.sql.trim() : '';
+        if (!rawSql) {
+            return '❌ 参数错误: sql 语句不能为空。';
+        }
+        const connectionName = typeof args.connection === 'string' && args.connection.trim()
+            ? args.connection.trim()
+            : undefined;
+        const queryParams = Array.isArray(args.params) ? args.params : undefined;
+        const auditResult = await this.auditService.audit(rawSql, connectionName || 'default', ctx);
+        if (!auditResult.passed) {
+            return `❌ SQL 审查未通过，已拒绝执行。\n原因: ${auditResult.reason}`;
+        }
+        let currentPassword = '';
+        try {
+            const { pool, config } = this.poolManager.getPool(connectionName);
+            currentPassword = config.password || '';
+            const maxRows = Number(ctx.config?.mysql?.maxRows ?? ctx.config?.['mysql.maxRows']) || 100;
+            const [rows] = await pool.query(rawSql, queryParams);
+            if (!Array.isArray(rows)) {
+                return JSON.stringify({
+                    connection: config.name,
+                    database: config.database || null,
+                    affectedRows: rows.affectedRows ?? 0,
+                    info: rows.info || '查询已完成'
+                }, null, 2);
+            }
+            const totalCount = rows.length;
+            const truncated = totalCount > maxRows;
+            const data = truncated ? rows.slice(0, maxRows) : rows;
+            return JSON.stringify({
+                connection: config.name,
+                database: config.database || null,
+                totalCount,
+                returnedCount: data.length,
+                truncated,
+                notice: truncated ? `结果集超过最大限制 ${maxRows} 条，已自动截断返回前 ${maxRows} 条记录。` : undefined,
+                data
+            }, null, 2);
+        }
+        catch (err) {
+            const safeMessage = sanitizeErrorMessage(err, currentPassword);
+            ctx.logger.error(`MySQL 查询执行异常: ${safeMessage}`);
+            return `❌ MySQL 查询执行失败: ${safeMessage}`;
+        }
+    }
+}

package/plugins/plugin-tool-mysql/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@eoasmxd/freya-plugin-tool-mysql",
+  "version": "0.1.0",
+  "private": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Freya MySQL 数据库查询工具集插件",
+  "freya": {
+    "displayName": "MySQL 数据库查询工具集",
+    "defaultEnabled": false,
+    "schema": "./schema.json",
+    "prompts": [
+      "plugin.prompt.mysql.md",
+      "plugin.prompt.mysql.select.audit.md"
+    ]
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@eoasmxd/freya-sdk": "^0.4.2",
+    "mysql2": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/plugins/plugin-tool-mysql/schema.json

@@ -0,0 +1,83 @@
+[
+  {
+    "key": "mysql.defaultConnection",
+    "defaultValue": "default",
+    "description": "默认使用的数据库连接名称",
+    "type": "string",
+    "category": "MySQL 连接"
+  },
+  {
+    "key": "mysql.maxRows",
+    "defaultValue": 100,
+    "description": "单次查询最大返回记录条数（防止大模型上下文窗口溢出）",
+    "type": "number",
+    "min": 1,
+    "max": 1000,
+    "category": "MySQL 安全",
+    "uiHint": "slider"
+  },
+  {
+    "key": "mysql.connections",
+    "defaultValue": [],
+    "description": "MySQL 命名数据库连接配置列表",
+    "type": "array",
+    "category": "MySQL 连接",
+    "children": [
+      {
+        "key": "name",
+        "description": "连接名称 (例如 default、bi_db)",
+        "type": "string",
+        "required": true
+      },
+      {
+        "key": "host",
+        "description": "数据库主机 (例如 127.0.0.1)",
+        "type": "string",
+        "required": true
+      },
+      {
+        "key": "port",
+        "description": "数据库端口 (默认 3306)",
+        "type": "number",
+        "defaultValue": 3306,
+        "required": true
+      },
+      {
+        "key": "user",
+        "description": "数据库用户名",
+        "type": "string",
+        "required": true
+      },
+      {
+        "key": "password",
+        "description": "数据库密码",
+        "type": "string",
+        "required": true,
+        "sensitive": true,
+        "uiHint": "password"
+      },
+      {
+        "key": "database",
+        "description": "数据库名称",
+        "type": "string",
+        "required": false
+      },
+      {
+        "key": "connectionLimit",
+        "description": "连接池最大连接数 (默认 5)",
+        "type": "number",
+        "defaultValue": 5,
+        "min": 1,
+        "max": 50
+      },
+      {
+        "key": "connectTimeout",
+        "description": "连接超时时间 (毫秒，默认 10000)",
+        "type": "number",
+        "defaultValue": 10000,
+        "min": 1000,
+        "max": 60000
+      }
+    ]
+  }
+]

package/plugins/plugin-tool-web/package.json

@@ -22,7 +22,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0"
+    "@eoasmxd/freya-sdk": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/plugin-wecom-channel/package.json

@@ -19,7 +19,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@eoasmxd/freya-sdk": "^0.4.0",
+    "@eoasmxd/freya-sdk": "^0.4.2",
     "ws": "^8.18.0"
   },
   "devDependencies": {