@eoasmxd/freya 0.3.0 → 0.4.1

package/src/packages/core/src/skill/skill-registry.ts

@@ -8,27 +8,66 @@ export interface FreyaSkill {
   name: string;
   description: string;
   content: string;
+  enabled: boolean;
+  source: 'builtin' | 'runtime';
 }
 
-/** 技能注册表，从 skills/ 目录加载 Markdown 格式技能 */
+/** 技能注册表，从 skills/ 目录加载 Markdown 格式技能并管理软开关状态 */
 export class FreyaSkillRegistry {
   private skills = new Map<string, FreyaSkill>();
+  private context?: FreyaContext;
 
   async loadSkills(context: FreyaContext): Promise<void> {
+    this.context = context;
     const runtimeSkillsDir = path.join(PROJECT_ROOT, 'skills');
     const defaultSkillsDir = path.join(APP_ROOT, 'skills');
+    const configSkillsPath = path.join(PROJECT_ROOT, 'config', 'skills.json');
+
     try {
       await fs.mkdir(runtimeSkillsDir, { recursive: true });
-      await this.loadSkillsFromDirectory(defaultSkillsDir, context);
-      await this.loadSkillsFromDirectory(runtimeSkillsDir, context);
-      context.logger.info(`动态技能扫描完成。共加载了 ${this.skills.size} 个物理技能。`);
+      await this.loadSkillsFromDirectory(defaultSkillsDir, 'builtin', context);
+      await this.loadSkillsFromDirectory(runtimeSkillsDir, 'runtime', context);
+
+      let configList: Array<{ id: string; enabled: boolean }> = [];
+      try {
+        const raw = await fs.readFile(configSkillsPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+          configList = parsed;
+        }
+      } catch {
+        configList = [];
+      }
+
+      const configMap = new Map<string, boolean>();
+      for (const item of configList) {
+        if (item && typeof item.id === 'string' && typeof item.enabled === 'boolean') {
+          configMap.set(item.id, item.enabled);
+        }
+      }
+
+      let configChanged = false;
+      for (const skill of this.skills.values()) {
+        if (configMap.has(skill.id)) {
+          skill.enabled = configMap.get(skill.id)!;
+        } else {
+          configChanged = true;
+        }
+      }
+
+      if (configChanged || configList.length !== this.skills.size) {
+        await this.persistSkillsConfig(configSkillsPath);
+      }
+
+      const enabledCount = Array.from(this.skills.values()).filter((s) => s.enabled).length;
+      context.logger.info(`动态技能扫描完成。共加载 ${this.skills.size} 个物理技能 (已启用: ${enabledCount})。`);
     } catch (err: any) {
       context.logger.error('扫描物理技能 skills 目录遭遇故障:', err);
     }
   }
 
   /** 从指定目录加载技能到内存注册表中 */
-  private async loadSkillsFromDirectory(dirPath: string, context: FreyaContext): Promise<void> {
+  private async loadSkillsFromDirectory(dirPath: string, source: 'builtin' | 'runtime', context: FreyaContext): Promise<void> {
     try {
       const files = await fs.readdir(dirPath);
       for (const file of files) {
@@ -36,11 +75,17 @@ export class FreyaSkillRegistry {
           const rawContent = await fs.readFile(path.join(dirPath, file), 'utf-8');
           const { metadata, content } = this.parseFrontmatter(rawContent);
           if (metadata.id) {
+            const defaultEnabled = metadata.defaultEnabled !== undefined
+              ? metadata.defaultEnabled !== 'false'
+              : source === 'builtin';
+
             this.skills.set(metadata.id, {
               id: metadata.id,
               name: metadata.name || file.replace('.md', ''),
               description: metadata.description || '',
-              content: content.trim()
+              content: content.trim(),
+              enabled: defaultEnabled,
+              source
             });
           }
         }
@@ -50,8 +95,55 @@ export class FreyaSkillRegistry {
     }
   }
 
-  getSkills(): Map<string, FreyaSkill> {
-    return this.skills;
+  /** 获取技能列表（默认只返回启用状态的技能） */
+  getSkills(onlyEnabled: boolean = true): Map<string, FreyaSkill> {
+    if (!onlyEnabled) {
+      return this.skills;
+    }
+    const filtered = new Map<string, FreyaSkill>();
+    for (const [id, skill] of this.skills.entries()) {
+      if (skill.enabled) {
+        filtered.set(id, skill);
+      }
+    }
+    return filtered;
+  }
+
+  /** 获取全量技能数组（供管理控制台使用） */
+  getAllSkills(): FreyaSkill[] {
+    return Array.from(this.skills.values());
+  }
+
+  /** 切换技能的启用/禁用状态并持久化 */
+  async toggleSkill(skillId: string, enabled: boolean): Promise<string> {
+    const skill = this.skills.get(skillId);
+    if (!skill) {
+      return `❌ 未找到 ID 为 "${skillId}" 的技能，请检查名称是否正确。`;
+    }
+
+    if (skill.enabled === enabled) {
+      return `ℹ️ 技能 "${skill.name || skillId}" 状态已是 ${enabled ? '启用' : '禁用'}。`;
+    }
+
+    skill.enabled = enabled;
+    const configSkillsPath = path.join(PROJECT_ROOT, 'config', 'skills.json');
+    try {
+      await this.persistSkillsConfig(configSkillsPath);
+      this.context?.logger.info(`技能 "${skill.name || skillId}" 已切换为: ${enabled ? '启用' : '禁用'}`);
+      return `✅ 技能 "${skill.name || skillId}" 已成功${enabled ? '启用' : '禁用'}。`;
+    } catch (err: any) {
+      return `❌ 技能状态变更成功，但写入 skills.json 失败: ${err.message}`;
+    }
+  }
+
+  /** 持久化当前所有技能启停状态至 skills.json */
+  private async persistSkillsConfig(configSkillsPath: string): Promise<void> {
+    await fs.mkdir(path.dirname(configSkillsPath), { recursive: true });
+    const payload = Array.from(this.skills.values()).map((s) => ({
+      id: s.id,
+      enabled: s.enabled
+    }));
+    await fs.writeFile(configSkillsPath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
   }
 
   get(id: string): FreyaSkill | undefined {

package/src/packages/core/src/tools/meta/index.ts

@@ -1,11 +1,13 @@
 import type { FreyaTool, FreyaToolbox } from '@eoasmxd/freya-sdk';
 import type { FreyaSessionManager } from '../../session/session-manager.js';
 import type { FreyaToolRegistry } from '../tool-registry.js';
+import type { FreyaSkillRegistry } from '../../skill/skill-registry.js';
 
 export class FreyaMetaToolbox implements FreyaToolbox {
   constructor(
     private sessionManager: FreyaSessionManager,
-    private toolRegistry?: FreyaToolRegistry
+    private toolRegistry?: FreyaToolRegistry,
+    private skillRegistry?: FreyaSkillRegistry
   ) {}
 
   getId(): string {
@@ -106,6 +108,12 @@ export class FreyaMetaToolbox implements FreyaToolbox {
           if (!sessionId) {
             return '❌ 错误：无法从执行上下文中提取当前会话ID。';
           }
+          if (this.skillRegistry) {
+            const skill = this.skillRegistry.get(skillId);
+            if (!skill || !skill.enabled) {
+              return `❌ 错误：技能 [${skillId}] 不存在或已被系统管理员禁用，无法切入该模式。`;
+            }
+          }
           await this.sessionManager.updateSession(sessionId, { activeSkillId: skillId });
           return `已成功切入 [${skillId}] 技能特长工作模式。`;
         }

package/src/packages/core/src/web/config-api.ts

@@ -199,6 +199,26 @@ export class FreyaConfigApi {
         return true;
       }
 
+      if (pathname === '/api/config/skills' && req.method === 'GET') {
+        const skills = this.configManager.listSkills();
+        res.writeHead(200, this.headers);
+        res.end(JSON.stringify({ success: true, data: skills }));
+        return true;
+      }
+
+      if (pathname === '/api/config/skills/toggle' && req.method === 'POST') {
+        const { skillId, enabled } = await this.getBody(req);
+        if (!skillId) {
+          res.writeHead(200, this.headers);
+          res.end(JSON.stringify({ success: false, error: '缺少必要参数: skillId' }));
+          return true;
+        }
+        const msg = await this.configManager.toggleSkill(skillId, enabled);
+        res.writeHead(200, this.headers);
+        res.end(JSON.stringify({ success: !msg.startsWith('❌'), message: msg }));
+        return true;
+      }
+
       const promptMatch = pathname.match(/^\/api\/config\/prompts\/([^/]+)$/);
       if (promptMatch && req.method === 'GET') {
         const promptName = decodeURIComponent(promptMatch[1]);

package/src/packages/ui/src/features/config/ConfigModal.tsx

@@ -3,6 +3,7 @@ import { GlobalConfigPanel } from './panels/GlobalConfigPanel.jsx';
 import { ProviderConfigPanel } from './panels/ProviderConfigPanel.jsx';
 import { PromptConfigPanel } from './panels/PromptConfigPanel.jsx';
 import { PluginConfigPanel } from './panels/PluginConfigPanel.jsx';
+import { SkillConfigPanel } from './panels/SkillConfigPanel.jsx';
 
 interface ConfigModalProps {
   onClose: () => void;
@@ -13,13 +14,14 @@ export const ConfigModal: React.FC<ConfigModalProps> = ({
   onClose,
   getApiUrl
 }) => {
-  const [activeTab, setActiveTab] = useState<'global' | 'providers' | 'prompts' | 'plugins'>('global');
+  const [activeTab, setActiveTab] = useState<'global' | 'providers' | 'prompts' | 'plugins' | 'skills'>('global');
 
   const getTabTitle = () => {
     if (activeTab === 'global') return '全局参数设置';
     if (activeTab === 'providers') return '大模型提供商与模型管理';
     if (activeTab === 'prompts') return '系统提示词管理';
     if (activeTab === 'plugins') return '扩展插件管理';
+    if (activeTab === 'skills') return '技能卡管理';
     return '';
   };
 
@@ -55,6 +57,12 @@ export const ConfigModal: React.FC<ConfigModalProps> = ({
             >
               扩展插件
             </button>
+            <button
+              className={`tab-btn ${activeTab === 'skills' ? 'active' : ''}`}
+              onClick={() => setActiveTab('skills')}
+            >
+              技能卡管理
+            </button>
           </div>
         </div>
 
@@ -85,6 +93,10 @@ export const ConfigModal: React.FC<ConfigModalProps> = ({
             {activeTab === 'plugins' && (
               <PluginConfigPanel getApiUrl={getApiUrl} />
             )}
+
+            {activeTab === 'skills' && (
+              <SkillConfigPanel getApiUrl={getApiUrl} />
+            )}
           </div>
         </div>
       </div>

package/src/packages/ui/src/features/config/panels/SkillConfigPanel.tsx

@@ -0,0 +1,137 @@
+import React, { useEffect, useState } from 'react';
+
+interface SkillEntry {
+  id: string;
+  name: string;
+  description: string;
+  enabled: boolean;
+  source: 'builtin' | 'runtime';
+}
+
+interface SkillConfigPanelProps {
+  getApiUrl: (path: string) => string;
+}
+
+export const SkillConfigPanel: React.FC<SkillConfigPanelProps> = ({ getApiUrl }) => {
+  const [skills, setSkills] = useState<SkillEntry[]>([]);
+  const [loading, setLoading] = useState<boolean>(true);
+  const [toasts, setToasts] = useState<{ id: string; message: string; type: 'success' | 'error' | 'info' }[]>([]);
+
+  const showToast = (message: string, type: 'success' | 'error' | 'info' = 'success') => {
+    const id = (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')
+      ? crypto.randomUUID()
+      : Math.random().toString(36).substring(2, 15);
+    setToasts(prev => [...prev, { id, message, type }]);
+    setTimeout(() => {
+      setToasts(prev => prev.filter(t => t.id !== id));
+    }, 3000);
+  };
+
+  const loadSkills = async () => {
+    try {
+      setLoading(true);
+      const res = await fetch(getApiUrl('/api/config/skills'));
+      const json = await res.json();
+      if (json.success && Array.isArray(json.data)) {
+        setSkills(json.data);
+      }
+    } catch (err) {
+      console.error('加载技能列表失败:', err);
+      showToast('加载技能列表失败', 'error');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    loadSkills();
+  }, []);
+
+  const toggleSkill = async (skillId: string, enabled: boolean) => {
+    try {
+      const res = await fetch(getApiUrl('/api/config/skills/toggle'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ skillId, enabled })
+      });
+      const json = await res.json();
+      if (json.success) {
+        showToast(`技能 "${skillId}" 已${enabled ? '启用' : '禁用'}`, 'success');
+        loadSkills();
+      } else {
+        showToast(`切换技能状态失败: ${json.message || json.error}`, 'error');
+      }
+    } catch (err) {
+      console.error('切换技能状态失败:', err);
+      showToast('切换技能状态失败', 'error');
+    }
+  };
+
+  if (loading && skills.length === 0) {
+    return <div style={{ padding: '1rem', color: 'var(--text-secondary)', fontSize: '0.85rem' }}>正在加载技能卡配置...</div>;
+  }
+
+  if (!loading && skills.length === 0) {
+    return (
+      <div style={{ padding: '2rem 1rem', textAlign: 'center', color: 'var(--text-secondary)', fontSize: '0.85rem' }}>
+        暂未扫描到任何技能卡。可在 <code>~/.freya/skills/</code> 目录下添加 <code>*.md</code> 技能卡文件。
+      </div>
+    );
+  }
+
+  return (
+    <div className="plugins-list">
+      {skills.map((skill) => {
+        const displayName = skill.name || skill.id;
+        const displayDesc = skill.description || '未提供描述信息';
+        const isBuiltin = skill.source === 'builtin';
+
+        return (
+          <div key={skill.id} className="plugin-card">
+            <div>
+              <div className="plugin-title">
+                {displayName}
+                <span style={{ fontSize: '0.72rem', color: 'var(--text-secondary)', fontWeight: 'normal', marginLeft: '0.5rem' }}>
+                  ({skill.id})
+                </span>
+                <span
+                  style={{
+                    fontSize: '0.68rem',
+                    marginLeft: '0.5rem',
+                    padding: '0.1rem 0.4rem',
+                    borderRadius: '4px',
+                    background: isBuiltin ? 'rgba(59, 130, 246, 0.15)' : 'rgba(16, 185, 129, 0.15)',
+                    color: isBuiltin ? '#60a5fa' : '#34d399'
+                  }}
+                >
+                  {isBuiltin ? '内置' : '自定义'}
+                </span>
+              </div>
+              <div className="plugin-desc">{displayDesc}</div>
+            </div>
+            <div>
+              <label className="switch">
+                <input
+                  type="checkbox"
+                  checked={skill.enabled}
+                  onChange={(e) => toggleSkill(skill.id, e.target.checked)}
+                />
+                <span className="slider" />
+              </label>
+            </div>
+          </div>
+        );
+      })}
+
+      {toasts.length > 0 && (
+        <div className="toast-container">
+          {toasts.map(t => (
+            <div key={t.id} className={`toast-card ${t.type}`}>
+              <span>{t.message}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/plugins/plugin-tool-mysql/src/audit.ts

@@ -0,0 +1,103 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { FreyaContext, LLMMessage } from '@eoasmxd/freya-sdk';
+
+export interface AuditResult {
+  passed: boolean;
+  reason: string;
+}
+
+/** 前置 SQL 安全与完整性审查审计服务 */
+export class SqlAuditService {
+  private cachedPrompt: string | null = null;
+
+  /** 双通道探针加载审计提示词模板 */
+  private async loadAuditPrompt(ctx: FreyaContext): Promise<string> {
+    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: any) {
+      ctx.logger.error(`加载内置 SQL 审计提示词模板失败: ${packageDefaultPath}`, err);
+      return '';
+    }
+  }
+
+  /** 执行前置独立 LLM 分析审查 */
+  public async audit(sql: string, connectionName: string, ctx: FreyaContext): Promise<AuditResult> {
+    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: LLMMessage[] = [
+      {
+        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: any) {
+      ctx.logger.error('前置 LLM SQL 审计过程发生异常', err);
+      return {
+        passed: false,
+        reason: `SQL 安全审查服务调用失败: ${err?.message || err}`
+      };
+    }
+  }
+}

package/src/plugins/plugin-tool-mysql/src/index.ts

@@ -0,0 +1,44 @@
+import type { FreyaContext, ToolPlugin, FreyaTool } from '@eoasmxd/freya-sdk';
+import { MysqlPoolManager } from './pool-manager.js';
+import { SqlAuditService } from './audit.js';
+import { MysqlQueryTool } from './tools.js';
+
+/** MySQL 数据库查询工具箱插件 */
+export default class MysqlToolsPlugin implements ToolPlugin {
+  type = 'tool' as const;
+
+  private poolManager?: MysqlPoolManager;
+  private auditService = new SqlAuditService();
+  private tools: FreyaTool[] = [];
+
+  async setup(ctx: FreyaContext): Promise<void> {
+    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(): string {
+    return 'mysql';
+  }
+
+  getInstructionPrompt(): string {
+    return 'plugin.prompt.mysql';
+  }
+
+  getTools(): FreyaTool[] {
+    return this.tools;
+  }
+
+  async stop(ctx: FreyaContext): Promise<void> {
+    if (this.poolManager) {
+      await this.poolManager.closeAll();
+      ctx.logger.info('MySQL 工具箱连接资源已全部释放。');
+    }
+  }
+}
+
+export const Plugin = MysqlToolsPlugin;

package/src/plugins/plugin-tool-mysql/src/pool-manager.ts

@@ -0,0 +1,132 @@
+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;
+}
+
+/** 安全解算嵌套或扁平配置值 */
+function getNestedConfig(config: Record<string, any>, keyPath: string): any {
+  if (!config) return undefined;
+  if (keyPath in config) return config[keyPath];
+  const parts = keyPath.split('.');
+  let current: any = 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 {
+  private pools = new Map<string, mysql.Pool>();
+  private connectionConfigs = new Map<string, MysqlConnectionConfig>();
+  private defaultConnectionName: string = 'default';
+
+  constructor(private ctx: FreyaContext) {
+    this.reloadConfigs();
+  }
+
+  /** 加载与同步配置 */
+  public reloadConfigs(): void {
+    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
+        });
+      }
+    }
+  }
+
+  /** 获取指定名称的数据库连接池 */
+  public getPool(targetName?: string): { pool: mysql.Pool; config: MysqlConnectionConfig } {
+    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 };
+  }
+
+  /** 获取所有可用连接名称 */
+  public getAvailableConnectionNames(): string[] {
+    return Array.from(this.connectionConfigs.keys());
+  }
+
+  /** 释放所有已建立的连接池资源 */
+  public async closeAll(): Promise<void> {
+    for (const [name, pool] of this.pools.entries()) {
+      try {
+        await pool.end();
+        this.ctx.logger.info(`MySQL 连接池已释放: [${name}]`);
+      } catch (err: any) {
+        this.ctx.logger.warn(`关闭 MySQL 连接池 [${name}] 时发生异常: ${err?.message || err}`);
+      }
+    }
+    this.pools.clear();
+  }
+}