skill-self-evolution 0.2.0__py3-none-any.whl

skill_self_evolution/__init__.py

@@ -0,0 +1,27 @@
+"""
+Skill Engine — 自进化框架核心。
+
+规则执行 → AI 常识判断 → 合理就过 / 不合理 AI 从原始数据重选 → 日志记录 → 离线进化 → 优化配置
+"""
+
+from skill_self_evolution.executor import SkillExecutor
+from skill_self_evolution.models import SkillInput, SkillOutput
+from skill_self_evolution.context import get_trace_id, set_trace_id
+from skill_self_evolution.logger import SkillLogger
+from skill_self_evolution.fallback import FallbackStrategy
+from skill_self_evolution.config_loader import ConfigVersionManager
+from skill_self_evolution.evolver import Evolver
+from skill_self_evolution.ai_assisted_executor import AiAssistedExecutor
+
+__all__ = [
+    "SkillExecutor",
+    "SkillInput",
+    "SkillOutput",
+    "get_trace_id",
+    "set_trace_id",
+    "SkillLogger",
+    "FallbackStrategy",
+    "ConfigVersionManager",
+    "Evolver",
+    "AiAssistedExecutor",
+]

skill_self_evolution/ai_assisted_executor.py

@@ -0,0 +1,244 @@
+"""
+AiAssistedExecutor — 通用 AI 辅助执行基类。
+
+提供「验证 + 重选」的通用流程模板，Skill 只需定义：
+  - ai_validate()：AI 常识判断（correction 角色） → AiValidationResult
+  - ai_reselect()：AI 重新选择/提取（correction 角色） → AiReselectionResult
+  - ai_enhance()：AI 增强（enhancement 角色） → dict | None
+
+框架自动处理：降级、熔断、is_failure 计算、JSONL 日志。
+"""
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import Any
+
+from skill_self_evolution.context import set_trace_id
+from skill_self_evolution.fallback import FallbackConfig, FallbackResult, FallbackStrategy
+from skill_self_evolution.loader import SkillModule
+from skill_self_evolution.logger import SkillLogger
+from skill_self_evolution.models import (
+    AiReselectionResult,
+    AiValidationResult,
+    SkillInput,
+    SkillOutput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AiAssistedExecutor(ABC):
+    """AI 辅助执行基类。
+
+    子类只需实现 2-3 个抽象方法，框架自动处理流程编排和降级。
+    """
+
+    @abstractmethod
+    async def ai_validate(
+        self,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+    ) -> AiValidationResult:
+        """AI 常识判断（correction 角色）。
+
+        Returns:
+            AiValidationResult: result=合理/不合理 + reason
+        """
+
+    @abstractmethod
+    async def ai_reselect(
+        self,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+    ) -> AiReselectionResult:
+        """AI 重新选择/提取（correction 角色）。
+
+        Returns:
+            AiReselectionResult: result=重选值（或"不合理"） + reason
+        """
+
+    async def ai_enhance(
+        self,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+    ) -> dict | None:
+        """AI 增强（enhancement 角色）。默认不增强，子类按需覆盖。"""
+        return None
+
+    async def run_correction_flow(
+        self,
+        skill: SkillModule,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+        fallback: FallbackStrategy,
+    ) -> SkillOutput:
+        """correction 角色完整流程：验证 → 重选。"""
+        t0 = time.monotonic()
+        warnings: list[str] = list(rule_output.warnings) if rule_output.warnings else []
+
+        # 1. 熔断检查
+        fb_check = fallback.check_before_ai()
+        if fb_check.skip_ai:
+            warnings.extend(fb_check.warnings)
+            elapsed = (time.monotonic() - t0) * 1000
+            rule_output.warnings = warnings
+            self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+            return rule_output
+
+        # 2. AI 验证
+        ai_validation: AiValidationResult | None = None
+        try:
+            ai_validation = await self.ai_validate(skill_input, rule_output, prompt_config)
+            rule_output.ai_validated = True
+        except Exception as e:
+            logger.warning("Skill [%s] AI 验证异常: %s", skill.skill_name, e)
+            fb_result = fallback.on_validate_failure(e)
+            warnings.extend(fb_result.warnings)
+            if fb_result.skip_ai:
+                elapsed = (time.monotonic() - t0) * 1000
+                rule_output.ai_validated = False
+                rule_output.warnings = warnings
+                is_failure = self._is_failure(skill.ai_role, rule_output, None, None)
+                self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+                return rule_output
+
+        # 3. 验证不合理 → 重选
+        if ai_validation and ai_validation.result == "不合理":
+            fb_reselect = fallback.check_before_ai()
+            if fb_reselect.skip_ai:
+                warnings.extend(fb_reselect.warnings)
+                elapsed = (time.monotonic() - t0) * 1000
+                is_failure = self._is_failure(skill.ai_role, rule_output, ai_validation, None)
+                rule_output.warnings = warnings
+                self._log(skill, skill_input, rule_output, ai_validation, None, rule_output, warnings, elapsed)
+                return rule_output
+
+            try:
+                ai_reselection = await self.ai_reselect(skill_input, rule_output, prompt_config)
+                if ai_reselection and ai_reselection.result != "不合理":
+                    final_result = ai_reselection.result
+                    final_output = SkillOutput(
+                        source="ai",
+                        result=final_result if isinstance(final_result, dict) else {"value": final_result},
+                        ai_validated=True,
+                        ai_reselected=True,
+                        warnings=warnings,
+                    )
+                    elapsed = (time.monotonic() - t0) * 1000
+                    is_failure = self._is_failure(skill.ai_role, rule_output, ai_validation, ai_reselection)
+                    self._log(skill, skill_input, rule_output, ai_validation, ai_reselection, final_output, warnings, elapsed)
+                    return final_output
+                else:
+                    warnings.append("AI 重选后仍不合理")
+                    rule_output.ai_reselected = True
+            except Exception as e:
+                logger.warning("Skill [%s] AI 重选异常: %s", skill.skill_name, e)
+                fb_result2 = fallback.on_reselect_failure(e)
+                warnings.extend(fb_result2.warnings)
+
+        # 4. 验证合理或重选失败 → 返回规则结果
+        rule_output.warnings = warnings
+        elapsed = (time.monotonic() - t0) * 1000
+        is_failure = self._is_failure(skill.ai_role, rule_output, ai_validation, None)
+        self._log(skill, skill_input, rule_output, ai_validation, None, rule_output, warnings, elapsed)
+        return rule_output
+
+    async def run_enhancement_flow(
+        self,
+        skill: SkillModule,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        prompt_config: dict | None,
+        fallback: FallbackStrategy,
+    ) -> SkillOutput:
+        """enhancement 角色流程：规则 + AI 增强。"""
+        t0 = time.monotonic()
+        warnings: list[str] = list(rule_output.warnings) if rule_output.warnings else []
+
+        fb_check = fallback.check_before_ai()
+        if fb_check.skip_ai:
+            warnings.extend(fb_check.warnings)
+            elapsed = (time.monotonic() - t0) * 1000
+            rule_output.warnings = warnings
+            self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+            return rule_output
+
+        try:
+            ai_result = await self.ai_enhance(skill_input, rule_output, prompt_config)
+            merged = {**rule_output.result} if isinstance(rule_output.result, dict) else {}
+            if ai_result:
+                merged.update(ai_result)
+            final_output = SkillOutput(
+                source=rule_output.source,
+                result=merged,
+                ai_validated=True,
+                ai_reselected=False,
+                warnings=warnings,
+            )
+            elapsed = (time.monotonic() - t0) * 1000
+            self._log(skill, skill_input, rule_output, None, None, final_output, warnings, elapsed)
+            return final_output
+        except Exception as e:
+            logger.warning("Skill [%s] AI 增强异常: %s", skill.skill_name, e)
+            elapsed = (time.monotonic() - t0) * 1000
+            rule_output.warnings = warnings
+            self._log(skill, skill_input, rule_output, None, None, rule_output, warnings, elapsed)
+            return rule_output
+
+    @staticmethod
+    def _is_failure(
+        ai_role: str,
+        rule_output: SkillOutput,
+        ai_validation: AiValidationResult | None,
+        ai_reselection: AiReselectionResult | None,
+    ) -> bool:
+        """根据 ai_role 计算 is_failure（Pydantic 属性访问）。"""
+        if ai_role == "enhancement":
+            return False
+        if ai_role == "correction":
+            if ai_validation and ai_validation.result == "不合理":
+                return True
+            if ai_reselection and ai_reselection.result == "不合理":
+                return True
+        return False
+
+    def _log(
+        self,
+        skill: SkillModule,
+        skill_input: SkillInput,
+        rule_output: SkillOutput,
+        ai_validation: AiValidationResult | None,
+        ai_reselection: AiReselectionResult | None,
+        final_output: SkillOutput,
+        warnings: list[str],
+        elapsed_ms: float,
+    ) -> None:
+        """写入 JSONL 日志（Pydantic LogEntry 校验）。"""
+        try:
+            log_writer = SkillLogger(skill.skill_name)
+            if skill.summarize_input:
+                input_summary = skill.summarize_input(skill_input.input_data)
+            elif isinstance(skill_input.input_data, dict):
+                keys = list(skill_input.input_data.keys())[:5]
+                input_summary = {k: str(skill_input.input_data[k])[:100] for k in keys}
+            else:
+                input_summary = {"type": type(skill_input.input_data).__name__}
+
+            log_writer.log_execution(
+                trace_id=skill_input.trace_id or "",
+                is_failure=(ai_validation is not None and ai_validation.result == "不合理"),
+                input_summary=input_summary,
+                rule_output=rule_output.result,
+                ai_validation=ai_validation.model_dump() if ai_validation else None,
+                ai_reselection=ai_reselection.model_dump() if ai_reselection else None,
+                final_output=final_output.result,
+                warnings=warnings,
+                elapsed_ms=elapsed_ms,
+            )
+        except Exception as e:
+            logger.warning("Skill 日志记录失败: %s", e)

skill_self_evolution/config.py

@@ -0,0 +1,87 @@
+"""
+?????? ? ? APP_ENV ?? DeepSeek API ???????
+
+- local: DeepSeek ?? API (api.deepseek.com)
+- test/prod: ??? MaaS (api.modelarts-maas.com/v2)
+"""
+
+import os
+
+from pydantic import BaseModel, Field
+
+__all__ = ["DeepSeekEnvConfig", "DbConfig", "get_deepseek_config", "get_db_config"]
+
+
+class DeepSeekEnvConfig(BaseModel):
+    """DeepSeek API ?????Pydantic ????"""
+
+    api_key: str = Field(default="", description="API Key")
+    api_base: str = Field(
+        default="https://api.deepseek.com/v1",
+        description="API ????",
+    )
+    model: str = Field(default="deepseek-chat", description="????")
+
+
+class DbConfig(BaseModel):
+    """????????Pydantic ????"""
+
+    host: str = Field(default="127.0.0.1")
+    port: int = Field(default=3306, ge=1, le=65535)
+    user: str = Field(default="root")
+    password: str = Field(default="")
+    database: str = Field(default="housekeeping_ai_match_dev")
+
+
+def _resolve_app_env() -> str:
+    return os.getenv("APP_ENV", "local").strip().lower()
+
+
+def get_deepseek_config(
+    api_key: str = "",
+    api_base: str = "",
+    model: str = "",
+) -> DeepSeekEnvConfig:
+    env = _resolve_app_env()
+    if api_key and api_base:
+        return DeepSeekEnvConfig(
+            api_key=api_key,
+            api_base=api_base,
+            model=model or "deepseek-chat",
+        )
+    if env == "local":
+        key = api_key or os.getenv("DEEPSEEK_API_KEY", "")
+        base = api_base or os.getenv("DEEPSEEK_API_BASE", "https://api.deepseek.com/v1")
+        m = model or os.getenv("DEEPSEEK_MODEL", "deepseek-chat")
+        return DeepSeekEnvConfig(api_key=key, api_base=base, model=m)
+    else:
+        key = api_key or os.getenv("WX_MATCH_DEEPSEEK_API_KEY", "")
+        base = api_base or os.getenv(
+            "WX_MATCH_DEEPSEEK_API_BASE", "https://api.modelarts-maas.com/v2"
+        )
+        m = model or os.getenv("WX_MATCH_AI_MODEL_NAME", "DeepSeek-V3.2")
+        return DeepSeekEnvConfig(api_key=key, api_base=base, model=m)
+
+
+def get_db_config(
+    host: str = "",
+    port: int = 0,
+    user: str = "",
+    password: str = "",
+    database: str = "",
+) -> DbConfig:
+    if host and user and password:
+        return DbConfig(
+            host=host,
+            port=port or 3306,
+            user=user,
+            password=password,
+            database=database or "housekeeping_ai_match_dev",
+        )
+    return DbConfig(
+        host=host or os.getenv("DB_HOST", "127.0.0.1"),
+        port=port or int(os.getenv("DB_PORT", "3306")),
+        user=user or os.getenv("DB_USER", "root"),
+        password=password or os.getenv("DB_PASSWORD", ""),
+        database=database or os.getenv("DB_NAME", "housekeeping_ai_match_dev"),
+    )

skill_self_evolution/config_loader.py

@@ -0,0 +1,241 @@
+"""
+配置版本管理器 — MySQL skill_config / skill_config_history 表操作。
+
+职责：
+- 从 MySQL 加载当前激活版本的 rules_config / prompt YAML
+- 写入新版本时自动归档旧版本到 skill_config_history
+- 支持回滚到任意历史版本
+
+housekeeping 项目的 VersionManager 可作为适配器实现同一接口。
+"""
+
+import logging
+from datetime import datetime
+from typing import Any
+
+import pymysql
+import yaml
+
+from skill_self_evolution.config import DbConfig, get_db_config
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigVersionManager:
+    """框架内置版本管理：version 递增 + 历史归档。"""
+
+    def __init__(self, db_config: dict[str, Any] | DbConfig | None = None):
+        from skill_self_evolution.config import DbConfig
+        if db_config is None:
+            self._db_config = get_db_config()
+        elif isinstance(db_config, DbConfig):
+            self._db_config = db_config
+        else:
+            self._db_config = db_config
+        self._conn: pymysql.Connection | None = None
+
+    def set_db_config(self, db_config: dict[str, Any] | DbConfig) -> None:
+        self._db_config = db_config
+
+    def _get_conn(self) -> pymysql.Connection:
+        """获取数据库连接（懒连接 + 自动重连）。兼容 dict 和 DbConfig。"""
+        if self._conn is None or not self._conn.open:
+            db = self._db_config
+            if isinstance(db, DbConfig):
+                host, port, user, password, database = (
+                    db.host, db.port, db.user, db.password, db.database
+                )
+            else:
+                host = db.get("host", "localhost")
+                port = db.get("port", 3306)
+                user = db.get("user", "root")
+                password = db.get("password", "")
+                database = db.get("database", "housekeeping")
+            self._conn = pymysql.connect(
+                host=host,
+                port=port,
+                user=user,
+                password=password,
+                database=database,
+                charset="utf8mb4",
+                autocommit=True,
+            )
+        return self._conn
+
+    def ensure_tables(self) -> None:
+        """自动建表（幂等）。首次使用时或部署阶段调用。"""
+        conn = self._get_conn()
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                CREATE TABLE IF NOT EXISTS skill_config (
+                    skill_name   VARCHAR(128) NOT NULL COMMENT 'Skill 名称',
+                    config_type  ENUM('rules_config','prompt') NOT NULL COMMENT '配置类型',
+                    content      MEDIUMTEXT NOT NULL COMMENT 'YAML 字符串',
+                    version      INT NOT NULL DEFAULT 1 COMMENT '版本号，每次更新递增',
+                    updated_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+                    PRIMARY KEY (skill_name, config_type)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+                """
+            )
+            cur.execute(
+                """
+                CREATE TABLE IF NOT EXISTS skill_config_history (
+                    id           BIGINT AUTO_INCREMENT PRIMARY KEY,
+                    skill_name   VARCHAR(128) NOT NULL,
+                    config_type  ENUM('rules_config','prompt') NOT NULL,
+                    content      MEDIUMTEXT NOT NULL,
+                    version      INT NOT NULL,
+                    archived_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                    INDEX idx_skill_version (skill_name, config_type, version)
+                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+                """
+            )
+        logger.info("skill_config / skill_config_history 表确认存在")
+
+    def load(self, skill_name: str, config_type: str) -> dict | None:
+        """从 MySQL 加载当前激活版本，返回解析后的 dict。
+        
+        Args:
+            skill_name: Skill 名称（如 "nickname-selector"）
+            config_type: "rules_config" 或 "prompt"
+        
+        Returns:
+            解析后的 YAML dict，未找到配置时返回 None
+        """
+        conn = self._get_conn()
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT content FROM skill_config WHERE skill_name = %s AND config_type = %s",
+                (skill_name, config_type),
+            )
+            row = cur.fetchone()
+        if row is None:
+            logger.debug("skill_config 未找到: %s/%s", skill_name, config_type)
+            return None
+        return yaml.safe_load(row[0])
+
+    def load_raw(self, skill_name: str, config_type: str) -> str | None:
+        """加载原始 YAML 字符串（用于进化分析 prompt 注入）。"""
+        conn = self._get_conn()
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT content FROM skill_config WHERE skill_name = %s AND config_type = %s",
+                (skill_name, config_type),
+            )
+            row = cur.fetchone()
+        return row[0] if row else None
+
+    def save(self, skill_name: str, config_type: str, content: str) -> int:
+        """写入新版本：先归档旧版本到 skill_config_history，再更新主表。
+
+        Args:
+            skill_name: Skill 名称
+            config_type: "rules_config" 或 "prompt"
+            content: YAML 字符串（非解析后的 dict）
+
+        Returns:
+            新版本号
+        """
+        conn = self._get_conn()
+        with conn.cursor() as cur:
+            # 查询当前版本号和内容
+            cur.execute(
+                "SELECT version, content FROM skill_config WHERE skill_name = %s AND config_type = %s",
+                (skill_name, config_type),
+            )
+            row = cur.fetchone()
+
+            if row:
+                old_version = row[0]
+                old_content = row[1]
+                new_version = old_version + 1
+                # 归档旧版本
+                cur.execute(
+                    "INSERT INTO skill_config_history (skill_name, config_type, content, version) "
+                    "VALUES (%s, %s, %s, %s)",
+                    (skill_name, config_type, old_content, old_version),
+                )
+                # 更新主表
+                cur.execute(
+                    "UPDATE skill_config SET content = %s, version = %s, updated_at = %s "
+                    "WHERE skill_name = %s AND config_type = %s",
+                    (content, new_version, datetime.now(), skill_name, config_type),
+                )
+            else:
+                new_version = 1
+                cur.execute(
+                    "INSERT INTO skill_config (skill_name, config_type, content, version) "
+                    "VALUES (%s, %s, %s, %s)",
+                    (skill_name, config_type, content, new_version),
+                )
+
+        logger.info("配置写入: %s/%s v%d", skill_name, config_type, new_version)
+        return new_version
+
+    def rollback(self, skill_name: str, config_type: str, target_version: int) -> bool:
+        """回滚到指定版本。
+
+        Args:
+            skill_name: Skill 名称
+            config_type: "rules_config" 或 "prompt"
+            target_version: 目标版本号
+
+        Returns:
+            True 表示回滚成功，False 表示目标版本不存在
+        """
+        conn = self._get_conn()
+        with conn.cursor() as cur:
+            # 查找目标版本
+            if target_version == 0:
+                # v0 = 删除当前配置
+                cur.execute(
+                    "DELETE FROM skill_config WHERE skill_name = %s AND config_type = %s",
+                    (skill_name, config_type),
+                )
+                logger.info("配置已删除（回滚到 v0）: %s/%s", skill_name, config_type)
+                return True
+
+            # 从历史表查找
+            cur.execute(
+                "SELECT content FROM skill_config_history "
+                "WHERE skill_name = %s AND config_type = %s AND version = %s "
+                "ORDER BY archived_at DESC LIMIT 1",
+                (skill_name, config_type, target_version),
+            )
+            hist = cur.fetchone()
+            if hist is None:
+                logger.warning("历史版本不存在: %s/%s v%d", skill_name, config_type, target_version)
+                return False
+
+            # 从主表获取当前版本以归档
+            cur.execute(
+                "SELECT version, content FROM skill_config WHERE skill_name = %s AND config_type = %s",
+                (skill_name, config_type),
+            )
+            current = cur.fetchone()
+
+            if current:
+                # 归档当前版本
+                cur.execute(
+                    "INSERT INTO skill_config_history (skill_name, config_type, content, version) "
+                    "VALUES (%s, %s, %s, %s)",
+                    (skill_name, config_type, current[1], current[0]),
+                )
+
+            # 写入目标版本内容
+            new_version = (current[0] + 1) if current else 1
+            cur.execute(
+                "REPLACE INTO skill_config (skill_name, config_type, content, version, updated_at) "
+                "VALUES (%s, %s, %s, %s, %s)",
+                (skill_name, config_type, hist[0], new_version, datetime.now()),
+            )
+
+        logger.info("配置回滚成功: %s/%s → v%d (from history v%d)", skill_name, config_type, new_version, target_version)
+        return True
+
+    def close(self) -> None:
+        """关闭数据库连接。"""
+        if self._conn and self._conn.open:
+            self._conn.close()
+            self._conn = None

skill_self_evolution/context.py

@@ -0,0 +1,22 @@
+"""
+trace_id 上下文管理 — 基于 contextvars 的全链路追踪。
+
+框架在 SkillExecutor.run() 入口自动生成 trace_id 并注入上下文，
+Skill 实现（run.py）无需手动处理。
+"""
+
+import contextvars
+
+_current_trace_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "trace_id", default=None
+)
+
+
+def get_trace_id() -> str | None:
+    """获取当前协程/线程的 trace_id。"""
+    return _current_trace_id.get()
+
+
+def set_trace_id(trace_id: str) -> None:
+    """设置当前协程/线程的 trace_id（框架内部使用）。"""
+    _current_trace_id.set(trace_id)