如何为 OpenSRE 新增一个集成：面向贡献者的完整教程
【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre
OpenSRE 是一个开源的 AI SRE 智能体框架（Build your own AI SRE agents），它通过集成 Datadog、Grafana、Trello 等 60 多个工具，让 AI 运维智能体在你的自有基础设施上排查生产事故。想让 OpenSRE 接入你团队正在使用的新平台？本文是一份面向新手贡献者的完整教程：从创建集成目录、编写配置与客户端，到注册、写工具、跑检查、提交 PR，一步步带你为 OpenSRE 新增一个集成。
一、什么是 OpenSRE 集成？
在 OpenSRE 中，一个"集成"（Integration）代表一个外部服务（如 Trello、PagerDuty、MongoDB），它由四个部分组成：
| 组件 | 文件 | 作用 |
|---|---|---|
| 配置模型 | config.py | 定义连接参数、环境变量解析与校验 |
| API 客户端 | client.py | 封装对第三方 API 的调用 |
| 验证器 | verifier.py | 本地验证凭据与连通性 |
| 智能体工具 | tools/ | AI 智能体可实际调用的能力 |
所有集成统一放在integrations/<名称>/目录下。以最小的集成 Trello 为例，它只包含 4 个文件：init.py、config.py、client.py、verifier.py，是学习新集成的最佳范本。
二、快速准备开发环境：3 步搞定
在动手之前，先按 CONTRIBUTING.md 和 SETUP.md 准备好环境：
- 克隆仓库：
git clone https://gitcode.com/GitHub_Trending/op/opensre - 安装依赖：
make install（需先安装 uv） - 调用 CLI 时优先使用
uv run opensre …
如果偏好 VS Code，可以直接使用仓库自带的 devcontainer，详见 docs/DEVELOPMENT.md。
三、第一步：创建集成目录与配置模块
在你的分支下新建integrations/你的集成名/目录。参考 Trello 的做法：
config.py：用 Pydantic 定义一个XxxConfig模型，声明base_url、api_key、timeout_seconds等字段，并提供build_xxx_config()（从存储数据构建）与xxx_config_from_env()（从环境变量加载）两个函数。注意：读取密钥类环境变量必须使用resolve_env_credential，而不能使用裸的os.getenv（详见 docs/adding-tools-and-integrations.md 中的 Credential resolution 章节）。client.py：封装对第三方 API 的 HTTP 调用，例如validate_xxx_connection()。verifier.py：接收配置对象，调用客户端做连通性验证，返回ok与人类可读的detail，并复用integrations/_validation_helpers.py中的report_validation_failure。__init__.py：保持为一行 docstring 加必要的公开 API 再导出，作为包门面。
可以对照 integrations/trello/config.py 与 integrations/trello/verifier.py 逐行学习。
四、第二步：注册集成，让它被系统发现
目录建好后，还需要在两个地方"接线"，集成才会生效：
- 注册表：在 integrations/registry.py 中添加一条
IntegrationSpec(service="你的集成名")（参考其中 Trello 的注册项）。 - 目录解析：在 integrations/catalog.py / integrations/_catalog_impl.py 中把集成解析进共享运行时配置，并在 integrations/verify.py 中接入本地验证路径。
完成后运行make verify-integrations，可以确认你的集成被正确加载和验证。
五、第三步：为集成添加智能体工具（可选但推荐）
如果希望 AI 智能体能直接"动手"操作该服务，在integrations/你的集成名/tools/<工具名>_tool/下添加工具包。两个关键规则：
- 放置策略：单厂商工具放
integrations/<vendor>/tools/，跨厂商工具才放tools/cross_vendor/，完整规则见 docs/tool-placement-policy.md。 - 工具契约：元数据（
name、description、source、surfaces、requires）必须完整；input_schema与实际参数一致；失败时应返回结构化错误而不是抛出异常，让智能体友好处理。
简单的单文件工具可以直接用@tool(...)装饰器注册（示例见 CONTRIBUTING.md 的 "Add a Tool" 章节）；较复杂的工具则拆分为tool.py、models.py、validation.py等兄弟模块。
六、第四步：文档与测试，缺一不可
OpenSRE 对新集成有明确的"完成定义"（Definition of Done），核心要求：
- 文档：新增
docs/你的集成名.mdx页面，并在 docs/docs.json 中注册（不带.mdx后缀），文档站导航才会显示它。 - 测试：在
tests/integrations/下添加配置/校验的单元测试；若带工具，还需在tests/tools/添加契约测试，并至少使用一份真实结构的 fixture 测试 payload 解析（理想化的 mock 不算通过）。 - 凭据：新的环境变量写入
.env.example（绝不写.env）。 - 端到端：新集成最终门槛包括一段截图或演示 GIF、一个 E2E 测试，且 CI 全部通过。
七、第五步：运行本地检查并提交 PR
提交前，以下四条命令必须全部通过，否则 CI 会阻止合并：
make lint # ruff 代码风格检查 make format-check # ruff 格式检查（只读） make typecheck # mypy 类型检查 make test-cov # pytest 测试 + 覆盖率提交 PR 时请关联 issue、说明改了什么以及为什么。完整的提交检查清单见 docs/adding-tools-and-integrations.md。
八、关键文件速查表
| 文件 | 说明 |
|---|---|
| docs/adding-tools-and-integrations.md | 新增工具与集成的官方检查清单 |
| docs/tool-placement-policy.md | 工具放置位置策略 |
| integrations/registry.py | 集成注册表（IntegrationSpec） |
| integrations/catalog.py | 集成目录与运行时配置解析 |
| integrations/verify.py | 本地验证路径接线 |
| integrations/trello/ | 最小完整集成示例（4 个文件） |
| CONTRIBUTING.md | 贡献流程与 PR 规范 |
| SETUP.md | 开发环境搭建指南 |
常见问题
Q：新增集成一定要写工具吗？不一定。配置、客户端与验证器是基础骨架；只有需要智能体直接调用该服务时才添加工具。
Q：密钥应该怎么处理？遵循凭据解析契约：读取用resolve_env_credential（优先环境变量，其次凭据文件），绝不裸用os.getenv读取*_TOKEN、*_KEY等敏感变量。
Q：如何确认我的集成能被发现？运行make verify-integrations，并参考tests/integrations/下现有测试补充一个注册/发现测试，确保集成出现在预期的表面上。
按照以上五步，你就能像仓库中的 Trello、Opsgenie 等集成一样，为自己的工具生态贡献一个标准的 OpenSRE 集成。动手之前，不妨先通读一遍 docs/adding-tools-and-integrations.md，祝你顺利提交第一个 PR！
【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
