alpsla/evolution-engine

# Evolution Engine [](https://pypi.org/project/evolution-engine/) [](https://pypi.org/project/evolution-engine/) [](LICENSE) []() **AI 编程工具编写的看似正确的代码，会在不知不觉中破坏你的架构。Evolution Engine 能够检测到这种偏移，为你指出具体的 commit，并提供证据让你的 AI 去修复它。** 基于 200 多个开源仓库进行了校准。分析了 618 万个信号。你的代码永远不会离开你的本地机器。 **[codequal.dev](https://codequal.dev)** | [快速开始](QUICKSTART.md) | [PyPI](https://pypi.org/project/evolution-engine/)  ## 问题所在 AI 编程助手（Cursor, Copilot, Claude Code, Codex）生成的代码能够通过测试，且孤立地看也是正确的。但随着时间的推移，它们会引入**架构偏移** —— 散乱的文件更改、意外的依赖项激增、破坏的结构模式 —— 没有任何单一工具能够捕捉到这些问题。 Evolution Engine 是一款专为 AI 辅助开发设计的**偏移检测器**。它能学习*你的*仓库在结构上的正常状态，在开发模式发生转变时发出警告，精准定位发生偏移的具体 commit，并将证据传递给你的 AI agent 进行修复。 ### 闭环：检测 → 证据 → 修复 → 验证 ``` evo analyze . What changed? Is it unusual for THIS repo? | evo analyze . --show-prompt Copy the investigation prompt with evidence | You + your AI tool Paste into Claude Code / Cursor / Copilot to fix | evo analyze . --verify Did the fix resolve the drift? Or make it worse? | evo accept . 1 2 Expected change? Accept it. Move on. ``` EE 会生成证据和提示词 —— 你只需带上你自己的 AI 工具进行调查和修复。然后 EE 会验证偏移是否已解决。没有其他工具能完成这一闭环。 ### 报告示例

Analyze Report	Verification Report
Findings, patterns, and investigation prompt	Verification banner shows what resolved

### 工作原理（5 阶段 Pipeline） ``` Your Repo → Phase 1 (Record events) → Phase 2 (Detect deviation from YOUR baseline) | Phase 5 (Advisory) ← Phase 4 (Match known patterns) ← Phase 3 (Explain) | HTML Report + PR/MR Comments | HUMAN decides: investigate / fix / accept ``` | 阶段 | 功能说明 | |-------|-------------| | **Phase 1** | 记录不可变事件 —— commit、构建、依赖、发布 | | **Phase 2** | 计算单仓库基准，标记统计偏差 (MAD/IQR) | | **Phase 3** | 用人类语言解释信号 —— 对 PM 友好，有据可查 | | **Phase 4** | 与来自 200 多个仓库的 44 种已验证模式进行匹配 | | **Phase 5** | 提供按优先级排序的咨询建议，包含严重程度、证据和行动项 | ## 快速开始 ``` pip install evolution-engine evo analyze . ``` ### 三种集成路径 | 路径 | 命令 | 适用场景 | |------|---------|-------------| | **CLI 探索** | `evo analyze .` | 从这里开始 —— 手动分析、报告、调查 | | **Git Hooks** | `evo init . --path hooks` | 本地自动化 —— 在每次 commit 或 push 时进行分析 | | **GitHub Action** | `evo init . --path action` | CI 自动化 —— PR 评论中附带风险标记 | 从 CLI 开始。当你信任其输出结果后，再进阶到 hooks。添加 GitHub Action 以实现团队范围的覆盖。请参阅 [QUICKSTART.md](QUICKSTART.md) 获取完整指南。 ``` # 路径 1：CLI Explorer（从这里开始） evo analyze . # Run the full pipeline evo report . --open # Visual HTML report evo status # Detected adapters and run info # 路径 2：Git Hooks（本地自动化） evo init . --path hooks # Install post-commit hook evo watch . # Or poll for commits continuously # 路径 3：GitHub Action（CI） evo init . --path action # Generate workflow file, then push # 同时运行所有路径 evo init . --path all ``` 免费版涵盖路径 1 (CLI)。Pro 版解锁路径 2 (hooks) 和路径 3 (CI 集成)，外加 AI 调查、AI 修复循环以及 PR 内联审查评论。 ### 环境变量 ``` # .env 文件（全部可选） GITHUB_TOKEN=ghp_xxx # Unlocks CI, deployment, security adapters GITLAB_TOKEN=glpat-xxx # Unlocks GitLab CI, releases adapters EVO_LICENSE_KEY=xxx # Pro features (free tier works without) ANTHROPIC_API_KEY=sk-ant-xxx # For evo fix automated loop (Pro) ``` ## 数据源家族与自动检测 适配器注册中心会自动在三个层级中检测可用的数据源： ### 第 1 层 — 基于文件（零配置，始终离线可用） | 家族 | 检测依据 | 观察内容 | |--------|------------|-----------------| | Version Control | `.git/` | Commits、文件更改、结构耦合、同变更新颖性 | | Dependency Graph | `requirements.txt`, `package-lock.json`, `go.mod`, `Cargo.lock`, `Gemfile.lock` | 依赖项数量、变动率、传递深度 | | Configuration | `*.tf`, `docker-compose.yml` | 资源数量、配置变动率 | | Schema / API | `openapi.yaml`, `*.graphql` | Endpoint 增长、字段更改 | ### 第 2 层 — API 增强（可选 token 可解锁更多功能） | 家族 | Token | 观察内容 | |--------|-------|-----------------| | CI / Build Pipeline | `GITHUB_TOKEN` | 构建持续时间、失败率 | | Deployment | `GITHUB_TOKEN` | 发布节奏、预发布、资产数量 | | Security Scanning | `GITHUB_TOKEN` | 漏洞数量、严重程度、Dependabot 警报 | ### 第 3 层 — 社区插件（可通过 pip 安装） 已经在使用像 **Snyk**, **SonarQube**, **Jenkins**, **ArgoCD**, **GitLab CI**, **Datadog**, 或者 **PagerDuty** 这样的工具了吗？Evo 不会取代它们 —— 而是向它们学习。安装或构建一个适配器，将它们的数据输入到 pipeline 中，Evo 会将其与你的 git 历史记录、依赖项及其他来源相关联，从而发现跨工具模式。 ``` pip install evo-adapter-jenkins # Jenkins CI adapter pip install evo-adapter-snyk # Snyk security adapter pip install evo-adapter-argocd # ArgoCD deployment adapter evo analyze . # Auto-detected! ``` 插件通过 Python `entry_points` 自动发现。如果目前还没有适用于你所用工具的适配器，你可以[构建一个](#building-adapters)或[申请一个](#cli-commands)（`evo adapter request`）。 ### 历史回放 **Git History Walker** 从 git 历史记录中提取依赖、schema 和配置文件，创建时间演变时间线（而不仅仅是当前状态的快照）。这使得 Phase 4 能够将依赖项的更改与 CI 故障、部署以及其他随时间推移发生的事件关联起来。 ## CLI 命令 ``` # 核心分析 evo analyze [path] # Detect adapters, run full pipeline evo analyze . --families git,ci # Override auto-detection evo report [path] # Generate HTML report from last run evo status # Show detected adapters and event counts evo analyze . --show-prompt # Copy investigation prompt for your AI tool evo fix [path] --dry-run # Generate evidence-backed fix prompt (Pro) evo fix [path] --dry-run --residual # Iteration-aware prompt (what's fixed vs still broken) evo fix [path] # Automated fix-verify loop with CLI agent (Pro, advanced) evo verify # Compare current state to a previous advisory # 设置与集成 evo init [path] # Detect environment and suggest integration path evo init . --path hooks # Install git hooks for auto-analysis evo init . --path action # Generate GitHub Action workflow evo init . --path all # Set up all integration paths evo setup [path] # Interactive configuration wizard evo setup --ui # Browser-based settings page evo watch [path] # Watch for commits and auto-analyze evo watch . --daemon # Run watcher in background evo hooks install [path] # Install git hooks evo hooks uninstall [path] # Remove git hooks evo hooks status [path] # Show hook status # 模式与 Knowledge Base evo patterns list # Show discovered patterns evo patterns pull [path] # Fetch community patterns from registry evo patterns push [path] # Share anonymized patterns (requires privacy_level >= 1) evo patterns export # Export anonymized pattern digests evo patterns import # Import community patterns evo patterns packages # List pattern packages + cache status evo patterns new # Scaffold a pattern package evo patterns validate # Validate a pattern package evo patterns publish # Publish pattern package to PyPI evo patterns add # Subscribe to a pattern package evo patterns remove # Unsubscribe from a pattern package evo patterns block # Block a pattern package evo patterns unblock # Unblock a pattern package # Adapter 生态 evo adapter list # Show detected adapters with trust badges evo adapter discover [path] # Find available adapters for your tools evo adapter validate # Run 13-check certification evo adapter validate --security # + security scan evo adapter security-check # Standalone security scan evo adapter guide # How to build an adapter evo adapter new --family ci # Scaffold a pip-installable package evo adapter prompt --family ci # Generate AI prompt for building evo adapter request # Request an adapter from the community evo adapter block -r "reason" # Block an adapter locally evo adapter unblock # Unblock a blocked adapter evo adapter check-updates # Check PyPI for plugin updates evo adapter report # Report a broken/malicious adapter # 配置与历史 evo config list # Show all settings evo config set # Update a setting evo license status # Check license tier evo history list [path] # Show run history evo history diff [r1 r2] # Compare two runs ``` ## 构建适配器 Evolution Engine 支持插件生态系统。第三方适配器是可通过 pip 安装的包，通过 Python `entry_points` 自动注册。 ### 快速路径 ``` # 搭建一个完整的 pip package evo adapter new jenkins --family ci # 或者生成一个 AI prompt 并将其粘贴到你的编码助手 evo adapter prompt jenkins --family ci --copy ``` ### 认证 在发布之前，请验证你的适配器是否通过了全部 13 项契约检查： ``` cd evo-adapter-jenkins pip install -e . evo adapter validate evo_jenkins.JenkinsAdapter ``` 适配器在获得认证前，需通过 13 项结构检查 + 安全扫描。 ### 了解更多 ``` evo adapter guide # Full tutorial with contract details ``` ## 模式知识库 Evolution Engine 会自动发现跨家族模式： - **Pearson correlation**：偏差幅度同步追踪 (|r| >= 0.3) - **基于提升的共现 (Lift-based co-occurrence)**：偏差同时发生的频率高于偶然情况 (lift >= 1.5) - **基于存在 (Presence-based)**：当事件同时发生时，指标分布存在差异 (Cohen's d >= 0.2) 模式的范围会依次递进：**local**（此仓库）-> **community**（匿名共享）-> **confirmed**（local + community 匹配）。 社区模式通过两个冗余渠道分发： - **Registry**（实时）—— 用户推送的模式可通过 `codequal.dev/api` 立即使用 - **PyPI packages**（持久）—— 作为 [`evo-patterns-community`](https://pypi.org/project/evo-patterns-community/) 发布的定期快照，无需 `pip install` 即可自动获取 如果 registry 不可用，PyPI packages 仍然有效。在执行 `evo analyze` 时会自动检查两者。 ### 模式分发 ``` # 每次运行 `evo analyze` 时会自动获取 — 无需手动安装 evo analyze . # 从 community registry 导入了 25 个 pattern # 从 community packages 导入了 25 个 pattern # 从 community registry 拉取/推送 pattern evo patterns pull . evo patterns push . # requires: evo config set sync.privacy_level 2 # 将第三方 pattern package 添加到你的来源中 evo patterns add evo-patterns-web-security # 屏蔽不需要的 package evo patterns block evo-patterns-untrusted # 构建并发布你自己的 pattern package evo patterns new my-patterns # ... 编辑 patterns.json ... evo patterns validate evo-patterns-my-patterns evo patterns publish evo-patterns-my-patterns ``` ## 项目结构 ``` evolution-engine/ ├── evolution/ │ ├── cli.py # Click-based CLI (evo command) │ ├── orchestrator.py # Pipeline orchestration (detect → P1-P5) │ ├── registry.py # 3-tier adapter auto-detection │ ├── phase1_engine.py # Phase 1: Observation │ ├── phase2_engine.py # Phase 2: Baselines (MAD/IQR) │ ├── phase3_engine.py # Phase 3: Explanations (template-based) │ ├── phase4_engine.py # Phase 4: Pattern discovery │ ├── phase5_engine.py # Phase 5: Advisory │ ├── knowledge_store.py # SQLite knowledge base │ ├── kb_export.py # Anonymized pattern export/import │ ├── kb_security.py # Import validation (XSS, injection, traversal) │ ├── pattern_registry.py # Auto-fetch pattern packages from PyPI │ ├── pattern_validator.py # Pattern package validation │ ├── pattern_scaffold.py # Pattern package scaffolding │ ├── report_generator.py # Standalone HTML report generator │ ├── investigator.py # AI investigation engine (Pro) │ ├── fixer.py # AI fix-verify loop (evo fix, Pro) │ ├── adapter_validator.py # 13-check adapter certification │ ├── adapter_scaffold.py # Package scaffolding + AI prompt gen │ ├── license.py # License tier gating │ ├── data/ │ │ ├── universal_patterns.json # Bundled universal patterns │ │ ├── pattern_index.json # Known pattern packages │ │ └── pattern_blocklist.json # Blocked pattern packages │ └── adapters/ │ ├── git/ # Version Control (+ Git History Walker) │ ├── ci/ # CI / Build Pipeline (GitHub Actions) │ ├── testing/ # Test Execution (JUnit XML) │ ├── dependency/ # Dependency Graph (pip, npm, go, cargo, bundler) │ ├── schema/ # Schema / API (OpenAPI) │ ├── deployment/ # Deployment (GitHub Releases) │ ├── config/ # Configuration (Terraform) │ └── security/ # Security Scanning (Trivy, Dependabot) ├── tests/ │ ├── conftest.py # Shared fixtures │ ├── unit/ # 1500+ unit tests │ │ ├── test_phase2_deviation.py │ │ ├── test_phase4_cooccurrence.py │ │ ├── test_phase5_advisory.py │ │ ├── test_knowledge_store.py │ │ ├── test_registry.py │ │ ├── test_adapter_validator.py │ │ ├── test_adapter_scaffold.py │ │ ├── test_kb_export.py │ │ ├── test_kb_security.py │ │ ├── test_license.py │ │ ├── test_report_generator.py │ │ └── adapters/ # Lockfile parser tests │ └── integration/ │ └── test_pipeline_e2e.py # Full pipeline integration test ├── scripts/ │ └── aggregate_calibration.py # Cross-repo pattern aggregation ├── docs/ │ ├── ARCHITECTURE_VISION.md # Constitution │ ├── IMPLEMENTATION_PLAN.md # Roadmap │ ├── PHASE_*_CONTRACT.md # Phase contracts (2, 3, 4, 5) │ ├── PHASE_*_DESIGN.md # Phase designs (2, 3, 4, 5) │ ├── ADAPTER_CONTRACT.md # Universal adapter contract │ └── adapters/ # 8 family contracts ├── pyproject.toml # Package config (entry point: evo) └── .env # Environment config (optional) ``` ## 诞生背景 AI 编程工具生成的代码量前所未有。团队发布速度加快 —— 但在系统崩溃之前，结构质量始终是不可见的。EE 提供了缺失的反馈闭环：一道护栏，在开发模式偏离项目正常状态时，告知你（以及你的 AI）。 基于 **200 多个开源仓库**、**618 万个 SDLC 信号**和 **210 万次 commit** 进行了校准。包含 44 种已验证的跨信号模式。1.6% 的误报率。 ## 开源核心模式 | 开源 (MIT) | 专有 (BSL 1.1) | |-------------------|-------------| | 所有适配器 | Phase 2-5 引擎 | | CLI, registry, orchestrator | 知识库 | | Phase 1 引擎 | | | 知识库导出/导入/安全 | | | 报告生成器 | | | 适配器脚手架和验证器 | | 开放的适配器生态系统确保任何人都可以连接新的数据源。分析引擎则是其专有的核心部分。 ## 文档 请参阅 [`docs/README.md`](docs/README.md) 获取完整的文档结构和权威层级。 核心文档： - **[架构愿景](docs/ARCHITECTURE_VISION.md)** —— 系统存在的原因及其工作原理 - **[实施计划](docs/IMPLEMENTATION_PLAN.md)** —— 已完成的工作，接下来的计划 - **[适配器世界地图](docs/adapters/README.md)** —— 全部 8 个数据源家族 ## 核心原则 1. 观察先于解释 2. 历史记录不可篡改；解释随时可弃 3. 确定性胜过智能 4. 本地基准优于全局启发式方法 5. 多个微弱信号胜过一个强烈的主观判断 6. 没有信号并不代表安全 7. 是在必要时上报给人类，而不是取代人类 8. 证据是采取行动的前提 ## 许可证 Evolution Engine 采用双重许可模式： | 组件 | 许可证 | 文件 | |-----------|---------|------| | CLI, adapters, plugins, GitHub Action | [MIT](LICENSE-MIT) | `LICENSE-MIT` | | 核心分析引擎 (Phases 2-5) | [BSL 1.1](LICENSE) | `LICENSE` | | 社区模式 | CC0-1.0 | — | BSL 1.1 许可证允许在没有商业许可证的情况下进行非生产环境使用。生产环境使用需要[订阅 Pro 版](https://codequal.dev/#pricing)。在 **2029-02-20**，核心引擎将自动转换为 MIT 许可证。

标签：AI辅助开发, Git分析, SOC Prime, 开发工具, 本地部署, 架构漂移检测, 网络安全研究, 逆向工具