如何为 OpenSRE 新增一个集成面向贡献者的完整教程【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensreOpenSRE 是一个开源的 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集成注册表IntegrationSpecintegrations/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），仅供参考