OpenSRE 开发环境搭建完全指南：从依赖安装、Dev Container 到 CI 质量门禁-迪斯科星球

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 对版本有明确约束：

依赖	版本要求	说明
Python	3.12+（`pyproject.toml`中`requires-python = ">=3.12"`）	CI 工作流使用Python 3.13；.tool-versions 固定为`python 3.13.11`
Git	任意较新版本	克隆仓库与提交流程必需
uv	推荐最新版（仓库锁定`uv 0.11.11`）	`make 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	架构	安装路径	备注
macOS	arm64、x86_64	curl 安装器、Homebrew tap、二进制归档（darwin-arm64 / darwin-x64）	参见 macOS 安装步骤
Linux	x86_64、arm64	curl 安装器、Homebrew tap、二进制归档（linux-x64 / linux-arm64）	参见 Linux 安装步骤
Windows	x64	PowerShell 安装器、x64 ZIP 二进制	参见 Windows 安装步骤
Windows	arm64	—	不支持。默认发布矩阵中不含该架构，因为`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. 安装 uv

macOS / Linux：执行curl -LsSf https://astral.sh/uv/install.sh | sh（或按 uv 官方安装指南操作）
Windows（PowerShell）：执行irm https://astral.sh/uv/install.ps1 | iex，或使用winget install --id astral-sh.uv -e

安装完成后需要重启终端，确保uv进入PATH。

3. 安装依赖

make install

4. 验证

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.install

uv 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打开交互 Shell，opensre <command>走 CLI，opensre 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 install+uv run方案是两条并行且都有效的路径）；
VS Code 使用的解释器是.venv-devcontainer/bin/python（remoteEnv已将.venv-devcontainer/bin前置到PATH）；
预装扩展：Python、Pylance、Ruff、Docker、EditorConfig；
默认测试配置已指向tests目录并启用 pytest；
端口8000（OpenSRE health app）会在容器启动时自动转发；
remoteEnv暴露LOCAL_WORKSPACE_FOLDER，容器内设置了PYTHONDONTWRITEBYTECODE=1、PYTHONUTF8=1等环境变量。

Windows 专项设置

Windows 不自带make，可按以下三种路径任选其一。

选项 A：Chocolatey（推荐）

以管理员身份打开 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'))

安装 make：

choco install make

重启终端并验证：make --version。

选项 B：winget

winget install GnuWin32.Make

重启终端后执行make --version验证。

选项 C：不使用 Make

在仓库根目录（uv在PATH中的同一个 shell）执行以下等价命令。需要说明的是：test-cov的完整 pytest 命令行在 Makefile 的test-cov目标中（pytest -n auto并行执行、覆盖率统计与忽略项），只要条件允许都优先用make test-cov：

uv 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 \ --cov=config --cov=core --cov=gateway --cov=integrations \ --cov=infrastructure --cov=surfaces --cov=tools --cov-report=term-missing

注意与 Makefile 目标的一致性：lint对应ruff check，format-check对应ruff format --check，typecheck对应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存在；
升级 uv：uv self update；
若锁文件与pyproject.toml不匹配，在本地执行uv lock并提交更新后的锁文件（或开一个 PR）。

make: command not found（Windows）

安装 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 PATH`	`curl`不在`PATH`中	Agent 被告知不要 shell 出去调用`curl`	macOS:`brew install curl` Linux:`sudo apt-get install -y curl` Windows:`winget install cURL.cURL`
`no interactive shell (bash/sh) on PATH`	`bash`与`sh`都不在`PATH`中	Agent 被告知无法运行 shell 命令	Linux:`sudo apt-get install -y bash` macOS:保持`/bin`在`PATH`中 Windows:安装 Git Bash（`winget install Git.Git`）或 WSL
`network egress is blocked for sandboxed code by default`	默认沙箱策略阻止出站 socket	沙箱内的 Python 无法创建原始 socket	预期现象，忽略即可。出站 HTTP 请走已配置的集成。不要设置`OPENSRE_ALLOW_NETWORK=1`——那只会掩盖告警
`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(parents=True, exist_ok=True); p.chmod(0o700); print(p)"` 然后重新`make install`（或`uv sync --frozen --extra dev`）
`shell commands is unavailable in this environment`	`bash`/`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 …；
或手动前置 venv：export PATH="$(pwd)/.venv/bin:$PATH"（macOS/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 lint`	`ruff check`	静态检查代码规范
`make format-check`	`ruff format --check`	只读校验格式（CI 强制项）
`make typecheck`	`mypy`	对`config core gateway integrations infrastructure surfaces tools`做类型检查
`make test-cov`	`pytest -n auto`+ 覆盖率	并行执行测试并统计覆盖率

补充几个对理解测试运行方式有用的源码事实：pytest.ini 设置了testpaths（覆盖tests、gateway/tests与core/agent_harness/prompts/skills下的技能测试）、--import-mode=importlib（避免同名测试文件导入冲突）、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），仅供参考

企业官网建设流程全解析