OpenSRE 新贡献者上手指南从 Good First Issue 到首个合并的 PR【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre本文是 OpenSRE面向 AI 时代的开源 AI SRE Agent 工具包为新贡献者准备的入门指南。你将了解Good First Issue首次友好任务的筛选标准、如何从 issue 列表中找到适合自己的任务、搭建本地开发环境的完整步骤以及从认领任务、编写代码、通过本地质量检查到提交 PR 并被合并的全过程。读完本文你可以独立完成 OpenSRE 的第一次真实贡献。什么是 Good First Issue在 OpenSRE 中good first issue是一个专门的 GitHub 标签用来标记适合新贡献者上手的小任务。它的核心设计目标不是简单而是风险可控、边界清晰。根据 docs/good-first-issues/README.md一个合格的 Good First Issue 必须同时满足三个条件Self-contained自包含任务本身是闭环的你不需要理解整个代码库就能解决它只需要掌握相关的一小片模块Well-scoped范围清晰期望产出有明确定义评审者知道做完了应该长什么样Low risk低风险即使实现有瑕疵也不会破坏关键路径比如核心 Agent 循环、消息管道等关键链路。这三个条件决定了这类任务适合在熟悉项目的过程中做出真实贡献——你在解决具体问题的同时自然地接触到仓库的目录结构、代码风格和协作流程而不是先花几周通读全部源码。从源码结构看这个标签在仓库内也有实际作用integrations/github/tools/work_status.py中维护的_HELP_WANTED_LABELS集合就包含good first issue这意味着 OpenSRE 的 GitHub 集成工具在分析仓库工作状态时会把这个标签识别为需要帮助的信号之一。另外docs/daily-updates/2026-05-01.mdx 记录了仓库维护的自动分配工作流good_first_issue_assign.py与对应的 GitHub Actions说明项目在持续优化新贡献者认领任务的体验。如何查找开放任务查找任务的方式很简单浏览仓库 GitHub 页面的 Issues 列表按good first issue标签筛选所有当前开放open状态的任务即可。原文档给出的筛选 URL 为is:open label:good first issue的查询组合这是 GitHub 标准的标签过滤语法你可以直接使用打开 Issues 标签页在搜索框中输入is:open label:good first issue点击搜索结果进入筛选后的任务列表。阅读任务时不要只看标题务必点开 issue 阅读完整描述和评论历史。很多 issue 会在描述中给出预期的实现方向、受影响的模块如surfaces/cli/、integrations/、tools/等以及验收标准这些信息能帮你判断任务是否真的适合自己。认领任务先声明再动手选中目标后不要直接闷头写代码。正确做法是在 issue 下评论认领例如发布一条Id like to work on this这样的评论让维护者知道你在做这件事并把任务分配给你。这样既能避免多人同时抢同一个任务造成重复劳动也能让维护者提前注意到你的进展。如果维护者配置了自动分配工作流仓库的每日更新记录中提到过声明认领后系统可能自动完成分配即便没有自动分配评论声明也是后续与维护者沟通的起点。搭建开发环境在开始改代码之前先让本地环境跑起来。完整的跨平台搭建说明见 SETUP.md这里给出关键步骤概览环境要求Python 3.12pyproject.toml中requires-python 3.12CI 使用 Python 3.13GituvPython 包管理器用于安装锁定版本的依赖MakemacOS/Linux 自带Windows 可通过 Chocolatey 或 winget 安装或使用 SETUP.md 中的无 Make替代方案。安装依赖# 1. Fork 仓库后克隆你自己的副本 git clone 你的 fork 地址 cd opensre # 2. 安装锁定版本的开发依赖等价于 uv sync --frozen --extra dev make installmake install会把当前仓库以 editable 模式安装进.venv并安装 git 钩子。之后在本仓库目录下运行 CLI 时优先使用uv run opensre …避免被 PATH 上其他版本的opensre干扰。如果你使用 VS Code还可以选择更省事的方式安装 Dev Containers 扩展后在仓库中执行Dev Containers: Reopen in Container直接复用.devcontainer/Dockerfile构建好的 Python 3.13 开发环境无需手动安装任何依赖。标准工作流从分支到 PR环境就绪后按照 docs/good-first-issues/README.md 中的标准流程推进浏览任务列表阅读 issue 描述和评论后再声明认领评论认领发布Id like to work on this让维护者分配搭建环境按照 SETUP.md 先跑通本地环境Fork 并创建分支git checkout -b issue/123-short-description分支命名约定详见 CONTRIBUTING.mdbug 修复用issue/或fix/前缀新功能用feat/前缀全小写、单词间用连字符分隔编写改动严格控制范围一个 issue 对应一个 PR不要顺手夹带无关重构在打开 PR 前运行本地检查make lint make format-check make typecheck make test-cov提交 PR在 PR 描述中用Fixes #123关联 issue合并时会自动关闭对应 issue。完整的贡献流程包括贡献类型选择、环境搭建、分支策略、测试与 PR 规范见 CONTRIBUTING.md。本地质量检查逐项解读上面第 6 步的四个命令是 OpenSRE 的强制门禁CI 会在任一环节失败时阻止合并。结合 Makefile 和 CONTRIBUTING.md 的源码定义它们的含义如下命令底层工具作用make lintruff代码风格检查含 import 排序可自动修复部分问题make format-checkruff只读检查格式化是否符合规范CI 强制执行的就是这一项make typecheckmypy严格类型注解检查捕获类型错误make test-covpytest pytest-xdist并行运行测试并输出覆盖率报告测试规范是贡献流程的重要一环详见 CONTRIBUTING.md新测试统一放在tests/目录并按源包结构镜像组织例如surfaces/cli/的测试放在tests/cli/不要直接在源码包内添加*_test.py内联测试Bug 修复必须附带一个如果没修就会失败的回归测试新功能必须有对应测试覆盖率目标为 80%可用make test-cov检查。调试时可以只跑相关测试不必每次跑全量。例如pytest tests/cli/test_smoke.py # 单个文件 pytest tests/tools/ -k test_registry # 按关键字筛选推送前的最后一道闸除了上面四条命令仓库还提供了make pre-push详见 CI.md。它会在临时 git worktree 中校验你将要推送的已提交版本并行执行 lint、格式化、类型、导入边界、集成/工具注册表、仓库级契约以及按 diff 选出的受影响测试目标在 60 秒内完成。未被提交的修改无法蒙混过关。可以用make pre-push ARGS--dry-run先预览它要执行的内容。提交 PR 与审查流程提交 PR 时使用仓库的 PR 模板打开 PR 时自动填充重点填写Issue 链接Fixes #123变更类型bug fix / feature / breaking change / docs描述改了什么、为什么改测试方式具体步骤与证据影响分析是否向后兼容、有无性能影响。提交后进入审查阶段完整机制见 docs/pr-review-flow.mdx。OpenSRE 的 PR 审查由三层组成CI 门禁必需检查必须全绿分支保护聚合器为 CI GateGreptile 自动审查在 PR 上评论greptile review触发通常 5–10 分钟出结果。目标是将 Confidence Score 打到5/5且无未解决评论。处理完反馈后重新评论触发直到达标维护者人工审查维护者会重点查看 PR 描述中的问题陈述与证据、AI 使用披露、改动范围是否聚焦一个 PR 一个关注点、行为变更是否有测试。Greptile 5/5 和 CI 绿只是必要信号不代表自动合并。关于 AI 辅助代码OpenSRE 允许使用 AI 辅助开发但要求你在提交时确认详见 CONTRIBUTING.md 的 AI-Assisted PRs 一节你逐行审阅过AI 生成的每一行代码并理解其逻辑、测试过边界情况、按项目代码质量标准调整过输出、且验证过测试通过。评审者会对 AI 辅助代码格外留意——原则是你能解释每一行代码而不只是复制粘贴。遇到困难时如何求助卡住了不要硬猜尽早开口。官方推荐的求助渠道有两个Discord#contribute频道适合问流程性问题、协调认领、以及在自动化流程卡住时联系维护者GitHub直接在对应 issue 下评论让关注该任务的人看到你的问题。求助前建议先自查一遍是否已经通读 CONTRIBUTING.md大多数问题在其中有答案是否已按 SETUP.md 完成环境搭建并能在本地跑通检查如果 issue 描述本身含糊不清也完全可以在写代码之前先评论提问确认方向——这比写完一大段代码后被要求返工高效得多。给新贡献者的几点建议先读 CONTRIBUTING.md 再动手它涵盖了贡献类型选择、分支命名、代码质量标准、测试与 PR 规范能回答你 80% 的疑问一个 PR 只解决一个关注点不要捆绑无关修复。仓库明确表示除非维护者明确要求不接受纯重构型 PR也不接受仅为追逐main上已知失败而开的测试/CI-only PR见 CONTRIBUTING.md动手前澄清需求issue 不清楚就问避免返工AI 辅助可以但要对自己负责你能解释每一行代码这是审查通过的前提善用本地门禁推送前运行make pre-push把问题挡在 CI 之前CI.md 是 push/PR 检查的最终权威。完成第一个 Good First Issue 后你就走通了 OpenSRE 贡献的完整闭环查找任务、声明认领、搭建环境、小步修改、本地验证、提交 PR、通过 AI 与人工双重审查、最终合并。这个流程不仅适用于首个任务也是后续所有贡献的通用模板。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考