OpenSRE 开发环境搭建完全指南从依赖安装、Dev Container 到 CI 质量门禁【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre本篇技术指南完整讲解 OpenSRE 开源仓库面向 AI 时代的开源 SRE Agent 工具包用于告警自动调查与根因分析的本地开发环境搭建全流程前置依赖与版本要求、支持平台与架构矩阵、全平台快速安装、VS Code Dev Container 一键环境、Windows 专项配置以及从启动能力告警到 CI 质量门禁的故障排查与验证方法。读完本文你将掌握从零搭建一个可开发、可测试、可提交 PR 的 OpenSRE 开发环境并理解make install、make test-cov等关键命令在仓库底层的真实行为。前置依赖与版本要求OpenSRE 的开发环境依赖四项基础工具仓库根目录的 pyproject.toml 与 .tool-versions 对版本有明确约束依赖版本要求说明Python3.12pyproject.toml中requires-python 3.12CI 工作流使用Python 3.13.tool-versions 固定为python 3.13.11Git任意较新版本克隆仓库与提交流程必需uv推荐最新版仓库锁定uv 0.11.11make install依赖它从 uv.lock 做锁定安装Make标准随 macOS/Linux 自带Windows 需额外安装见下文「Windows 专项设置」需要说明的是.tool-versions 中还固定了nodejs 25.2.1、pnpm 10.28.0、ruff 0.15.12、mypy 1.20.2这些条目主要为 mise/asdf 这类版本管理器用户服务属于可选项——常规流程下 ruff 与 mypy 会作为 dev 依赖直接装进.venv由make install/uv sync统一管理并不强制要求你先安装版本管理器。从 pyproject.toml 可以看到OpenSRE 的核心依赖覆盖面很广AI/Agent 侧anthropic、mcp、openai、litellm、数据校验pydantic v2、HTTP/异步httpx、aiohttp、fastapi、uvicorn、消息网关slack-sdk、discord.py、可观测性OpenTelemetry 全家桶、sentry-sdk、以及大量数据库与集成驱动pymongo、redis、pymysql、clickhouse-connect 等。这也解释了为什么推荐使用 uv 做锁定安装——依赖数量多且版本约束细手工管理极易出错。支持平台与架构矩阵OpenSRE 的发布可用性与默认 CI 覆盖范围并不完全一致。下表是官方支持矩阵SETUP.md 原文各平台请先按对应安装路径装好可执行文件再跟随 docs/quickstart.mdx 完成首次启动流程OS架构安装路径备注macOSarm64、x86_64curl 安装器、Homebrew tap、二进制归档darwin-arm64 / darwin-x64参见 macOS 安装步骤Linuxx86_64、arm64curl 安装器、Homebrew tap、二进制归档linux-x64 / linux-arm64参见 Linux 安装步骤Windowsx64PowerShell 安装器、x64 ZIP 二进制参见 Windows 安装步骤Windowsarm64—不支持。默认发布矩阵中不含该架构因为cryptography未发布 Windows arm64 的 wheel源码安装只能是尽力而为二进制下载链接对应的是滚动更新的main构建——与 curl 安装器默认使用的频道一致。若需要固定版本请从发布页下载与opensre_version_target命名匹配的资产每个归档旁边都附带对应的.sha256校验文件下载后可先行校验完整性。关于 CI 覆盖有个重要提醒主 CI 主要运行在ubuntu-latest上Windows CI 是可选的只有 PR 打上ci:windows标签才会运行。因此 Windows 平台的 CI 结果是有用的信号而非默认保证Windows 贡献者在提交 PR 前应格外依赖本地验证。快速安装全平台通用1. Fork 并克隆仓库git clone https://gitcode.com/GitHub_Trending/op/opensre.git cd opensre开发 OpenSRE 时通常先 Fork 再克隆便于后续通过 PR 贡献代码。2. 安装 uvmacOS / Linux执行curl -LsSf https://astral.sh/uv/install.sh | sh或按 uv 官方安装指南操作WindowsPowerShell执行irm https://astral.sh/uv/install.ps1 | iex或使用winget install --id astral-sh.uv -e安装完成后需要重启终端确保uv进入PATH。3. 安装依赖make install4. 验证make lint make format-check make typecheck make test-cov其中format-check是 CI 强制执行的格式检查提交 PR 之前务必包含这一项format才是实际改写代码的格式化命令format-check只读校验。不使用 Make 时的等价命令在没有 Make 的环境中make install等价于以下两条命令在仓库根目录执行uv sync --frozen --extra dev uv run python -m infrastructure.analytics.install源码视角make install到底做了什么从根目录 Makefile 看install目标并非简单的uv sync而是由三步组成install: uv sync --frozen --extra dev $(MAKE) install-hooks uv run python -m infrastructure.analytics.installuv sync --frozen --extra dev严格按照 uv.lock 锁定版本安装依赖--frozen表示不更新锁文件并安装dev可选依赖pytest、pytest-xdist、pytest-cov、ruff、mypy、import-linter、vulture、pre-commit 等见 pyproject.toml 的[project.optional-dependencies] dev段make install-hooks调用.github/ci/install_hooks.py安装阻塞式 push 校验钩子防止不符合质量门禁的提交被推送uv run python -m infrastructure.analytics.install执行一次性的安装检测上报见 infrastructure/analytics/install.py带 2 秒刷新超时不影响安装速度。安装完成后CLI 入口opensre由 pyproject.toml 的[project.scripts]注册opensre surfaces.entrypoint:main落地在.venv/bin/opensre。surfaces/entrypoint.py 是唯一知道全部入口CLI、交互式 Shell、Gateway的进程入口裸执行opensre打开交互 Shellopensre command走 CLIopensre gateway start --foreground启动网关。VS Code Dev Container 一键开发环境如果你希望环境开箱即用、免去本机依赖折腾可以使用仓库自带的 Dev Container在 VS Code 中安装Dev Containers扩展在宿主机启动 Docker Desktop、OrbStack、Colima 或其他 Docker 兼容运行时打开仓库后执行Dev Containers: Reopen in Container。容器镜像由 .devcontainer/Dockerfile 构建基于python:3.13-bookworm并预装了ca-certificates curl git make sudo以及名为vscode的开发用户。从 .devcontainer/devcontainer.json 可以看到更多细节postCreateCommand创建.venv-devcontainer虚拟环境并执行pip install -e .[dev]注意容器内走的是 pip 而非 uv与宿主机主流的make installuv run方案是两条并行且都有效的路径VS Code 使用的解释器是.venv-devcontainer/bin/pythonremoteEnv已将.venv-devcontainer/bin前置到PATH预装扩展Python、Pylance、Ruff、Docker、EditorConfig默认测试配置已指向tests目录并启用 pytest端口8000OpenSRE health app会在容器启动时自动转发remoteEnv暴露LOCAL_WORKSPACE_FOLDER容器内设置了PYTHONDONTWRITEBYTECODE1、PYTHONUTF81等环境变量。Windows 专项设置Windows 不自带make可按以下三种路径任选其一。选项 AChocolatey推荐以管理员身份打开 PowerShell安装 Chocolatey建议先审阅安装脚本内容Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString(https://community.chocolatey.org/install.ps1))安装 makechoco install make重启终端并验证make --version。选项 Bwingetwinget install GnuWin32.Make重启终端后执行make --version验证。选项 C不使用 Make在仓库根目录uv在PATH中的同一个 shell执行以下等价命令。需要说明的是test-cov的完整 pytest 命令行在 Makefile 的test-cov目标中pytest -n auto并行执行、覆盖率统计与忽略项只要条件允许都优先用make test-covuv sync --frozen --extra dev uv run python -m infrastructure.analytics.install uv run ruff check config core gateway integrations infrastructure surfaces tools tests/ uv run ruff format --check config core gateway integrations infrastructure surfaces tools tests/ uv run mypy config core gateway integrations infrastructure surfaces tools uv run pytest -n auto -v \ --covconfig --covcore --covgateway --covintegrations \ --covinfrastructure --covsurfaces --covtools --cov-reportterm-missing注意与 Makefile 目标的一致性lint对应ruff checkformat-check对应ruff format --checktypecheck对应mypy检查上述包路径test-cov对应pytest -n auto加覆盖率。这些命令实际由 .github/ci/run_checks.py 统一调度与 CI 完全同源。故障排查命令没有使用项目环境在仓库根目录优先使用uv run command需要刷新依赖时执行uv sync --frozen --extra dev。Command not found: python安装Python 3.12并确保其在PATH中python --version验证。Command not found: uv按上文方式安装 uv 后重启终端。make install/uv sync失败确认在仓库根目录执行且uv.lock存在升级 uvuv self update若锁文件与pyproject.toml不匹配在本地执行uv lock并提交更新后的锁文件或开一个 PR。make: command not foundWindows安装 make见上文或改用「选项 C不使用 Make」。运行代码时出现 Import 错误在仓库根目录使用uv run重新执行uv sync --frozen --extra dev。启动能力告警curl / shell / network / python 缺口OpenSRE 启动时若检测到PATH工具缺失或沙箱探针失败会记录非致命的告警日志。沙箱相关的告警形如capability is unavailable in this environment (probe returned unavailable) — the agent will not be able to use it.其中两行网络相关告警在普通机器上属于预期现象。完整对照表如下启动告警原因影响处理方法curl is not on PATHcurl不在PATH中Agent 被告知不要 shell 出去调用curlmacOS:brew install curlLinux:sudo apt-get install -y curlWindows:winget install cURL.cURLno interactive shell (bash/sh) on PATHbash与sh都不在PATH中Agent 被告知无法运行 shell 命令Linux:sudo apt-get install -y bashmacOS:保持/bin在PATH中Windows:安装 Git Bashwinget install Git.Git或 WSLnetwork egress is blocked for sandboxed code by default默认沙箱策略阻止出站 socket沙箱内的 Python 无法创建原始 socket预期现象忽略即可。出站 HTTP 请走已配置的集成。不要设置OPENSRE_ALLOW_NETWORK1——那只会掩盖告警network requests is unavailable in this environment沙箱网络探针使用相同的默认阻断与上一行相同预期现象同上python execution is unavailable in this environment沙箱无法运行短 Python 片段常见原因是 OpenSRE 临时目录不可写。该目录是 Python 进程临时目录tempfile.gettempdir()可能是$TMPDIR、%TEMP%、%TMP%或/tmp下的opensre并非固定路径Agent 被告知无法运行沙箱化 Python手动创建进程实际使用的目录日志会打印路径uv run python -c from pathlib import Path; import tempfile; p Path(tempfile.gettempdir()) / opensre; p.mkdir(parentsTrue, exist_okTrue); p.chmod(0o700); print(p)然后重新make install或uv sync --frozen --extra devshell commands is unavailable in this environmentbash/sh不在PATH与 shell 行同一检查Agent 被告知无法运行 shell 命令与no interactive shell (bash/sh) on PATH的安装步骤相同file reading is unavailable in this environment进程无法列出当前工作目录Agent 被告知无法读取本地文件确保在可读的检出目录中运行ls .应成功opensre没有加载本地代码改动make install会将本仓库以editable可编辑模式安装进.venv但PATH中可能还有另一个更靠前的opensre安装器二进制、版本管理器产物、~/.local/bin等抢占了入口。解决方式优先在仓库根目录使用uv run opensre …或手动前置 venvexport PATH$(pwd)/.venv/bin:$PATHmacOS/Linux随后执行hash -r或开新 shell并用which opensre确认其指向repo/.venv/bin/opensre。验证你的环境一切就绪后从仓库根目录执行完整质量门禁make lint make format-check make typecheck make test-cov这四条命令与 CI 使用的检查同源由 .github/ci/run_checks.py 驱动对应关系如下Make 目标底层命令作用make lintruff check静态检查代码规范make format-checkruff format --check只读校验格式CI 强制项make typecheckmypy对config core gateway integrations infrastructure surfaces tools做类型检查make test-covpytest -n auto 覆盖率并行执行测试并统计覆盖率补充几个对理解测试运行方式有用的源码事实pytest.ini 设置了testpaths覆盖tests、gateway/tests与core/agent_harness/prompts/skills下的技能测试、--import-modeimportlib避免同名测试文件导入冲突、timeout 600单测超时熔断并转储线程栈避免挂死测试烧掉整个 CI 作业时限并通过harness_providers_plugin为每个测试树注入工具/集成端口。若以上全部通过你的开发环境即告就绪。后续贡献流程请参阅 CONTRIBUTING.md更深度的贡献者主题架构基准、部署、遥测细节见 docs/DEVELOPMENT.md其中还包含包架构五层分层、工具注册表懒加载机制、部署速查与遥测/隐私开关矩阵等进阶内容。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
