GEPA 开源贡献指南：从环境搭建、代码质量规范到 Adapter 开发与 PR 提交全流程

AI Agent提示工程模型优化【免费下载链接】gepaOptimize prompts, code, and more with AI-powered Reflective Optimization项目地址https://gitcode.com/gh_mirrors/ge/gepa点击查看免费下载GEPAGenetic-Pareto是一个基于 LLM 反思与帕累托进化搜索的优化框架用于优化提示词、代码片段、Agent 架构与配置等任意文本组件。本篇贡献指南面向所有希望参与该项目的开发者你将掌握基于 uv 或 conda 的开发环境搭建方法熟悉 pre-commit、ruff、pyright 组成的代码质量流水线学会运行与标记测试、构建本地文档并了解从 Bug 报告、Feature 请求到新增 Adapter 与提交 Pull Request 的完整贡献路径最终把你自己的优化场景接入 GEPA 引擎。GEPA 项目概览与仓库布局GEPA 的核心思想是只要可度量就可优化它不依赖强化学习或梯度方法把执行轨迹压缩为单一标量奖励而是让 LLM 直接阅读完整执行轨迹错误信息、性能数据、推理日志来诊断候选方案失败的原因再通过迭代式反思、变异与帕累托感知选择以最少的评估次数进化出高性能变体。在动手贡献之前先了解仓库结构可对照根目录 AGENTS.md 与 README.mdsrc/gepa/— 主包源码core/存放优化循环、状态与评估逻辑proposer/负责候选方案生成与变异adapters/集成 DSPy、RAG、MCP 等外部系统strategies/实现批采样与候选选择logging/提供实验跟踪与日志tests/— pytest 测试套件docs/— mkdocs 文档站点本站即由此构建。环境搭建Python 3.10 与 uv推荐项目要求Python 3.10 或更高版本。pyproject.toml中声明了requires-python 3.10, 3.15开发调试建议使用 3.11。使用 uv 一键同步推荐uv 是 Rust 编写的快速 Python 包管理器安装后即可完成克隆与依赖同步# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 克隆并初始化开发环境 git clone https://gitcode.com/gh_mirrors/ge/gepa cd gepa uv sync --extra dev --python 3.11 # 验证安装 uv run pytest tests/关键点说明--extra dev会安装pyproject.toml中定义的dev可选依赖组其内容为gepa[test]、gepa[build]、pre-commit、build1.0.3与ruff0.3.0即一次性覆盖测试、构建、钩子与静态检查所需工具见 pyproject.toml所有 Python 命令都必须使用uv run前缀例如uv run python script.py因为 uv 创建了独立的虚拟环境uv run负责把命令指向该环境根目录 CONTRIBUTING.md 还给出了更贴近 CI 的验证命令uv run pytest -m not llm_live and not extra——这与pyproject.toml中注册的 pytest 标记一致llm_live标记调用真实语言模型的测试默认 CI 跳过extra标记依赖可选扩展包的测试。备选方案conda pip不习惯 uv 时可使用 conda 创建环境并以可编辑模式安装conda create -n gepa-dev python3.11 conda activate gepa-dev pip install -e .[dev] # 验证安装 pytest tests/注意pip install -e .[dev]依赖 setuptools 构建后端——项目正是以 setuptools 作为 build-backend见 pyproject.toml源代码采用src布局[tool.setuptools.packages.find] where [src]。代码质量pre-commit、ruff 与 pyrightGEPA 用三道闸门保证代码质量pre-commit 钩子在提交时自动执行检查ruff 负责 lint 与格式化pyright 负责类型检查。pre-commit 钩子仓库根目录的 .pre-commit-config.yaml 定义了全部钩子首次克隆后执行一次性安装# 安装钩子一次性 uv run pre-commit install # 提交时钩子自动运行 git add . git commit -m your message # 或手动运行 uv run pre-commit run --all-files配置细节来自仓库实际配置默认语言版本固定为python3.11钩子默认挂载在pre-commit阶段ruff-pre-commit固定v0.12.10ruff-check钩子以--fix、--fix-only、--exit-non-zero-on-fix参数运行只做可安全自动修复的修改仍有改动时以非零码退出提示另附ruff-format负责格式化pre-commit-hooks v5.0.0包含check-yaml允许多文档、不安全标签、check-toml、check-added-large-files阈值 3000KB、check-merge-conflict与debug-statements拦截残留的pdb等调试语句。如果钩子自动修改了文件需要把这些改动重新暂存并提交。迭代期间也可以只检查特定文件uv run pre-commit run --files path/to/file1.py path/to/file2.py。代码风格遵循 Google Python Style Guide项目遵循 Google Python Style Guide 的[tool.ruff]段line-length 120缩进 4 空格target-version py310include [src/**/*.py]启用规则覆盖Epycodestyle、W、Fpyflakes、Iisort、C、Bbugbear、UP、N命名、RUF、Q引号等同时通过ignore显式豁免复杂度告警C901、行长检查E501交由格式化器处理等强制禁止相对导入ban-relative-imports all并针对tests/**/*.py、__init__.py、gskill、examples设置了按文件的忽略规则格式化风格为双引号、空格缩进与 AGENTS.md 中line length 120, double quotes, space indent的说明一致。日常开发中可手动执行uv run ruff check src/与uv run ruff format src/。类型检查Pyright提交前运行 Pyright 检查类型回归# 全量检查 uv run pyright # 或针对特定模块 uv run pyright src/gepa/strategies/pyrightconfig.json 配置了include: [src]与typeCheckingMode: standard并排除了依赖外部包的 adapter 模块dspy、RAG、anymaths、terminal_bench、confidence、langchain、gskill 及tests/——这些目录往往需要额外的可选依赖才能通过类型检查因此不被纳入默认范围。运行测试测试是贡献质量的最后防线。GEPA 的测试套件位于tests/目录常见用法# 运行全部测试 uv run pytest tests/ # 运行单个测试文件 uv run pytest tests/test_optimize.py # 带覆盖率运行 uv run pytest tests/ --covgepa结合仓库与 CI 约定还需了解两类标记测试定义于 pyproject.tomlllm_live调用真实语言模型的端到端测试CI 默认跳过需要 API 密钥时在本地单独运行uv run pytest -m llm_liveextra依赖可选扩展包的测试CI 默认同样跳过。因此默认套件指的是uv run pytest -m not llm_live and not extra这既是验证环境搭建是否成功的命令也是提 PR 前必须全绿的门槛。仓库中已有覆盖优化主流程、回调集成、并行提案、实验跟踪、各类 Adapter 与可视化的大量测试如tests/test_optimize.py、tests/test_parallel_proposals.py、tests/test_callbacks_integration/等新增功能时建议仿照现有结构补上对应测试。文档工作流GEPA 的文档站由 MkDocs Material 构建源码在docs/目录下。本地构建文档cd docs pip install -r requirements.txt python scripts/generate_api_docs.py mkdocs serve然后访问http://localhost:8000预览。docs/requirements.txt列出了文档构建所需依赖mkdocs1.6.0、mkdocs-material9.5.0含 imaging、mkdocstrings与mkdocstrings-python自动生成 API 文档、mkdocs-jupyter嵌入 notebook 教程、mkdocs-rss-plugin、mkdocs-redirects以及用于社交预览图的playwright、pillow等。自动生成 API 文档python scripts/generate_api_docs.py从 docs/scripts/generate_api_docs.py 中的API_MAPPING表自动生成 mkdocstrings 指令式 Markdown 页面并按optimize_anything、gepa_engine、core、callbacks、stop_conditions、adapters、proposers、logging、strategies等类别组织导航。该脚本还支持三个有用参数--validate校验API_MAPPING中所有条目能否成功导入--skip-adapters跳过gepa.adapters.*的导入校验adapter 常依赖 dspy、mcp 等外部包本地未必安装--print-nav打印可直接粘贴进mkdocs.yml的 API 导航结构。编写文档的约定使用 Google 风格 docstringshow_source: true、docstring_style: google等 mkdocstrings 选项正是从 docstring 中提取内容在 docstring 中包含示例新增功能时同步更新相关指南如docs/docs/guides/下的 quickstart、adapters 等页面。贡献类型Bug 报告提交 Issue 时请包含以下信息便于快速定位GEPA 版本Python 版本最小可复现代码期望行为与实际行为的对比。Feature 请求在 Issue 中描述清楚使用场景use case提议的解决方案考虑过的替代方案。Pull Request提 PR 的完整流程Fork 本仓库git checkout -b feature/my-feature创建功能分支完成你的改动运行测试与 lintuv run pytest、uv run ruff check src/、uv run pyright src/提交带清晰描述的 PR。新增 Adapter把自定义系统接入 GEPAGEPA 可以优化任何由文本组件构成的系统其单点集成接口就是GEPAAdapter协议。仓库欢迎新 Adapter 的贡献完整接口说明见 创建 Adapter 指南基本步骤如下在src/gepa/adapters/下新建目录实现GEPAAdapter协议添加说明用法的README.md补充测试提交 PR。从 src/gepa/core/adapter.py 的源码看该协议要求实现两个核心方法evaluate(batch, candidate, capture_tracesFalse) - EvaluationBatch执行候选方案并返回逐样本分数。EvaluationBatch定义于 src/gepa/core/adapter.py承载原始输出outputs、数值scores、可选执行轨迹trajectories供反思数据集使用与可选的objective_scores多目标分数make_reflective_dataset(candidate, eval_batch, components_to_update) - dict[str, list[dict]]为每个待更新组件构造 JSON 可序列化的反思数据集供教师 LM 提出改进后的组件文本。此外还有两个可选扩展点propose_new_texts自定义提案逻辑替代默认的 instruction proposal以及get_adapter_state/set_adapter_state跨 checkpoint 保存与恢复 adapter 私有状态。仓库中已有大量现成实现可作参照例如 dspy_adapter、generic_rag_adapter、mcp_adapter、langchain_adapter 与 default_adapter 等。行为准则与沟通渠道社区氛围要求相互尊重、建设性沟通——我们是一起在建造一些东西。在贡献过程中遇到问题可以通过项目维护的 Discord、Slack 社区或 GitHub Issues 渠道提问开发者参与规范还建议遵循 AGENTS.md 中关于 Agent Skill.claude/skills/gepa-optimize-anything/的约定——如果你以编码 Agent 身份使用本项目进行自动优化应优先阅读并遵循该 Skill 指引。赞分享AI Agent提示工程模型优化【免费下载链接】gepaOptimize prompts, code, and more with AI-powered Reflective Optimization项目地址https://gitcode.com/gh_mirrors/ge/gepa点击查看免费下载相关推荐marimo 贡献指南从环境搭建、代码规范到提交高质量 PR 的完整开发流程marimo 贡献指南从环境搭建、代码规范到提交高质量 PR 的完整开发流程 marimo 是一个用 Python 编写的响应式reactivenoteb数据科学前端后端AI 应用OpenJarvis 贡献开发指南开发环境搭建、测试与代码规范、PR 提交流程全解析OpenJarvis 贡献开发指南开发环境搭建、测试与代码规范、PR 提交流程全解析 本篇指南以 OpenJarvis 官方贡献文档为骨架系统讲解从零搭建supermemory 开源贡献指南Monorepo 开发环境搭建、代码规范与提交流程supermemory 开源贡献指南Monorepo 开发环境搭建、代码规范与提交流程 supermemory 是一个面向 AI 时代的记忆层Memory人工智能RAGAgent 记忆AI Agent后端MCP 服务知识图谱前端上一篇Dio日志安全敏感信息脱敏与保护下一篇Readest服务器配置自托管同步服务指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考