OpenSRE 架构解析五层依赖分层的 AI SRE 代码库与 CI 强制的包边界治理【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensreOpenSRE 是一套面向 AI 时代的开源 SRE 工具集其代码库由八个第一方包first-party packages组成并按五层依赖分层组织。本文以 docs/ARCHITECTURE.md 为核心骨架深入剖析每个包的职责、层间依赖规则以及这些规则如何通过make check-imports与 import-linter 契约在 CI 中成为真实不变量而非纸上愿景。读完本文你将掌握 OpenSRE 的分层栈结构、组合根composition root的运作方式、工具与集成的边界划分原则以及两条典型跨层调用链路的完整走向。分层栈总览依赖只能向下OpenSRE 的八个第一方包分布在五个层级中。核心规则只有一条高层可以导入低层低层永远不能导入高层同层包互为对等体peer是否允许互相导入由最后一列决定。这张表就是整个代码库的宪法层级包允许导入严禁导入对等规则1顶层surfaces,gatewaybootstrap,tools,integrations,core,infrastructure,config—独立对等体互相严禁导入例外仅有.importlinter.strict中记录的 3 条 CLI/REPL 通往 gateway 的命令边2bootstraptools,integrations,core,infrastructure,configsurfaces,gateway组合根。唯一被允许同时导入tools与integrations的包因为装配两者都需要3toolscore,infrastructure,configsurfaces,gateway,bootstrapintegrations的对等体严禁导入它。既有越界边作为债务记录在.importlinter.strict中3integrationscore,infrastructure,configtools,surfaces,gateway,bootstraptools的对等体严禁导入它4core,infrastructureconfigsurfaces,gateway,bootstrap,tools,integrations兄弟包允许互相交叉导入5底层config—不导入任何第一方包以上所有独立——不导入任何其他第一方包速记规则是依赖指针只向下。一个 surface 可以一路触达底层而config什么都够不到。唯一的刻意例外是core ⟷ infrastructure——按设计互相依赖的兄弟对详见下文。下图展示了相邻层级之间的依赖边为使图可读只画相邻边实际规则更宽一个层级可以导入其下方任意层级而非仅紧邻的一层——所以 surface 可以直接导入configtool 可以直接导入infrastructure。完整允许边集合请以上表 允许导入 列为准边界为什么是真实不变量CI 中的三段式导入检查文档强调这些依赖规则由make check-imports在 CI 中强制执行。从源码看这一目标由 .github/ci/check_imports.py 实现它一次串起三道检查循环检查check_import_cycles——基于 Tarjan SCC强连通分量算法检测模块加载环分层检查import-linter读取 .importlinter——默认模式保证config的独立性等核心契约直接边检查check_direct_imports——禁止所有被列为非法的顶层导入。Makefile 中定义了相应入口make check-imports运行上述全部三项make check-imports-strict别名make check-layers-strict额外传入--strict参数加载更完整的传递性分层契约 .importlinter.strict。make check则作为 pre-push 门禁将质量检查与受影响测试绑定在一起。具体契约文件揭示了比文档表格更细粒度的约束.importlinter 中定义了四条契约config独立性independencegateway.core位于 transports 与 web 之下forbiddengateway.web永不导入聊天 transportsgateway.transports.{slack,discord,telegram}彼此独立independence即各聊天通道 transport 是互不依赖的对等体。.importlinter.strict 定义了完整的五层传递性契约surfaces | gateway→bootstrap→tools | integrations→core : infrastructure→config其中:表示兄弟可互相导入|表示严格禁止。同时以ignore_imports方式显式登记了当前存在的债务边每一条都注明了归属模块例如surfaces.cli.commands.gateway - gateway.core.process、surfaces.gateway_entry - gateway.core.lifecycle.controller、surfaces.interactive_shell.command_registry.gateway_cmds - gateway.core.process即文档提到的 3 条 CLI/REPL gateway 命令边以及infrastructure.analytics.github_identity - integrations.github、tools.cross_vendor.fix_sentry_issue.runner - integrations.github等 Tier-4/Tier-3 债务。文件头部的注释说明了治理策略随着重构落地删除 ignore_imports 条目并关联修复的 PR/issue。这套机制意味着任何新增的越界导入都会让 CI 直接失败因此分层结构会持续自我强化而不是靠开发纪律自觉维持。各层详解Tier 1 —surfaces与gateway人与外部系统对话的入口顶层是人和外部系统直接对话的入口没有任何第一方包可以导入这一层因此增删一个 surface 不需要惊动下层。surfaces/——每个 UI/客户端一个目录surfaces/cli是无状态的opensre command运行器surfaces/interactive_shell是有状态的 REPLsurfaces/shared存放两个以上 surface 共用的代码。surface 自己拥有 I/O、提示词与呈现逻辑并通过组合下层来完成实际工作。两个终端 surface 互为对等体、互不导入——tests/shared/test_surface_border.py 用精确的 allowlist 把两个方向都钉死在零导入并用 AST 静态扫描断言任何新增边立即失败、任何不再使用的 allowlist 条目必须删除。两者共同需要的代码放在surfaces/sharedterminal/负责输出追踪、表格、提示词、banner、健康与反馈渲染另有llm_setup/、error_handling/或更下层。组合发生在两者之上的唯一位置surfaces/entrypoint.py即opensreconsole script 的入口——它把CliHost如何打开 shell、如何以附加方式运行 gateway交给 CLI同时把 CLI 的 Click 命令组交给 shell 用于 grounding。一个空参数opensre打开 shellopensre command跑 CLIopensre gateway start --foreground以附加方式启动 gateway。Slack 不是 surface其入站 transport 在gateway/transports/slack出站投递在integrations/slack。gateway/——面向入站聊天平台的独立消息网关gateway/transports/{telegram,slack,discord,buzz}是各通道 transportgateway/web/是 FastAPI surface健康检查、告警接收gateway/core/{session,storage,middleware}是每个 transport 都要组合的每轮次共享机制——其中middleware/持有入站决策、身份识别与审批步骤。它是surfaces的对等体而不是子级。Tier 2 —bootstrap唯一的组合根这是进程与 harness 装配的组合根。由于 hostssurfaces、gateway互不导入且tools/integrations是对等体互不导入而注册 harness 适配器又必须同时接触两个能力包bootstrap/便成为唯一被允许同时导入tools和integrations的包。每个入口都通过 bootstrap/process.py 的configure_process(profile)完成启动。源码揭示了其精巧设计Profile 是封闭集合ProcessName枚举cli、gateway、web、scheduler_worker、scheduled_command、embedded六种宿主只能从中选择不能自创 profile这保证了幂等键可枚举。步骤顺序由包固定BootStep枚举 _STEP_ORDER元组env→sentry→harness_adapters→scheduler_runners→capability_warnings→preload_llm。profile 只决定选哪些步骤永远不能发明新顺序——这正是文档所说profiles cannot invent a different sequence的源码实现。各固定 profile 的选择也印证了文档CLI_PROFILE仅选ENVCLI 自己持有 Sentry 与 Rich 产品适配器GATEWAY_PROFILE选ENV SENTRY HARNESS_ADAPTERS CAPABILITY_WARNINGS PRELOAD_LLMEMBEDDED_PROFILE在他人进程内驱动 agent只注册适配器把错误上报、调度与客户端预热留给宿主。configure_process本身是幂等的_configured_profiles去重并提供了reset_process_runtime_for_tests()供测试重新启动。适配器与调度器运行器的注册只存在于 bootstrap/adapters.py别无分店install_harness_adapters()同时调用integrations.harness_adapters.register_harness_adapters与tools.harness_adapters.register_harness_adapters缺了它harness 启动后没有任何工具可用scheduler_runners()组装调度任务分发的运行器scheduled_delivery_adapters()组装各厂商的定时投递适配器Telegram/Slack/Discord/RocketChat/交互式 shell。文件中明确指出surfaces 与 gateway 曾经各自维护一份字节相同的副本——不要重新引入这种重复。宿主自身的关切CLI/gateway 日志、Rich 产品端口、CLI 的容错 Sentry 初始化被刻意排除在此包之外。Tier 3 —tools与integrations能力层能力层负责对外部世界做一件事按职责一分为二integrations/——用户配置与外部客户端的边界每个厂商一个目录integrations/datadog、integrations/grafana、integrations/github、…包含厂商配置归一化、验证verifier.py、API 客户端client.py、解析凭据的 store/catalog以及集成本地辅助工具另有integrations/llm_cli等横切模块。tools/——agent 可调用的边界所有tool(...)函数与BaseTool子类、工具注册表、框架子系统tools/interactive_shell、tools/system/无厂商域目的的工具如fleet_monitoring、python_execution_tool、sre_guidance_tool以及tools/cross_vendor/逻辑横跨 2 个以上厂商集成的工具如fix_sentry_issue。工具是规划器planner选择、运行时执行的对象。两者之间的导入规则是单向的integrations严禁导入tools或surfaces因此厂商客户端永不依赖 agent 层、可独立复用反向边则被允许且常见——工具通过 integration 的客户端获取外部数据——所以integrations在依赖图中实际上比tools低一层。文档与源码都明确警告不要重新引入顶层vendors/或services/包——外部系统代码属于integrations/agent 可调用代码属于tools/。工具放置的完整决策规则见 docs/tool-placement-policy.md判定依据是工具领域逻辑触及的厂商集成数量而非便利性或文件大小。单厂商 →integrations/vendor/tools/完全无厂商 →tools/system/附带注为次要关切而顺便导入厂商客户端不算厂商特定判定标准是工具存在的原因而非文件中的每个 import真正横跨 2 厂商 →tools/cross_vendor/这是很窄的桶不能因为工具恰好为第二家厂商格式化输出就放进去纯 surface 级CLI REPL呈现重复 →surfaces/shared/。该文档还给出当前落位表如tools/system/fleet_monitoring/为本地 AI-agent 舰队监控、无厂商tools/cross_vendor/fix_sentry_issue/读取 Sentry issue 并把修复交给 Pi 编码 agent与注册机制tools/system/、tools/cross_vendor/通过各自__init__.py中的TOOL_MODULES元组声明内嵌工具包新增工具只需登记包名无需改注册表代码。Tier 4 —core与infrastructure共享运行时与横切服务这是能力层赖以构建的共享运行时与横切服务。core/——厂商无关的 agent 运行时think → 调用工具 → 观察的循环core/agent核心为core.agent.Agent、agent 状态core/state与上下文预算执行core/context_budget.py、工具契约/模式/注册表端口/执行/错误上报core/tool、工具编写辅助core/tool_framework、共享 LLM 客户端core/llm、agent harness 会话处理core/agent_harness以及纯领域规则core/domain。infrastructure/——自身不含 agent 逻辑的横切服务guardrails、掩码、沙箱、分析、认证、通知、可观测性、调度器、部署以及共享的turn hostinfrastructure/turn_host——交互式 shell 与每个 gateway transport 都通过同一个TurnRunner运行 turn两条入口路径因此不可能漂移。部署期资产在infrastructure/deployment/EC2/打包 Python 工具链与cloudflare_install_proxyedge worker它们不被应用导入。这两者是全栈唯一按设计双向依赖的一对core为 guardrails、掩码、可观测性与证据/日志压缩而触达infrastructureinfrastructure又回头借用core的共享状态与会话类型core.state、core.agent_harness.session。若把它们拆进不同层级就会禁止这条边所以它们共享同一层、互为兄弟。这一点在 .importlinter.strict 中体现为core : infrastructure:允许交叉导入注释也明确解释|会禁止 core ↔ infrastructure但两包互相依赖。TurnRunner单例值得单独展开infrastructure/turn_host/turn_runner.py 的模块文档写明这是唯一的 turn runner——Slack/Discord/Telegram 等 transport 只是入站适配器它们做鉴权、解析会话、构建 turn 输出然后调用这个回调。TurnRunner.run内部依次执行容量门turn_slot、宿主取消检查、准入钩子在容量槽内执行防止对拒绝的工作计费随后在traced_session与bound_usage_context上下文中通过SessionAgentPool复用按会话保持的HeadlessAgent每则消息都走agent.handle(..., TurnBinding(...))——与交互式 shell 的调用完全相同只是绑定了一个支持取消的控制台与输出钩子。每轮次还上报 started/completed/failed 三态分析事件PostHog并持久化 session goal。这正是交互式 shell 与 gateway 走同一条 turn 路径、不会漂移的机制保证。Tier 5 —config地板最底层是共享常量、提示词与 UI 主题。其上所有层都可以读取config但config不导入任何其他第一方包——让它保持叶子leaf状态意味着常量可以在任何地方被导入而不会拖带运行时。这与 .importlinter 中config独立性契约Config is independent相互印证。从源码看config/ 下既包括constants/每类集成一套常量、secrets/密钥后端与记录、llm_auth/LLM 凭据与提供商目录、runtime_metadata/等纯配置能力也包括repl_config.py、local_env.py这类被上层读取的配置逻辑但它们始终不反向依赖任何上层包。跨层流程控制下行、结果上行两个工作示例展示控制如何沿栈下行、结果如何沿栈上行。箭头只向下跨越边界。交互式 shell 的一次聊天 turnshell或某个 gateway transport把消息交给core/agent_harness中的共享 agent harness——surface 本身从不运行 agent 逻辑harness 运行 ReAct agentcore/agentthink → 调用工具 → 观察全程受上下文预算约束agent 选中的工具经integrations获取厂商客户端与解析后的凭据infrastructure为每次调用提供 guardrails 与掩码答案沿栈流回 surface由 surface 决定如何呈现或投递。一条入站 gateway 消息gateway收到消息后先从自己的存储解析会话状态然后组合与 surface 相同的 Tier-3 能力代码经共享bootstrap进程启动之后——由于两者是独立的 Tier-1 对等体gateway全程不需要导入surfaces。这一机制同样由 .importlinter 中的Gateway core sits below transports and web与Gateway transports are peers契约守护并由gateway/core的共享TurnRunner保证通道与 shell 的 turn 语义完全一致。延伸阅读docs/tool-placement-policy.md——工具放置的完整决策规则单厂商 / 无厂商 / 跨厂商 / surface 级以及当前各工具包的落位与注册机制。AGENTS.md——仓库地图与各区域的 files to touch 指南。.importlinter 与 .importlinter.strict——分层与独立性契约文件以及当前债务边的登记与清理策略。.github/ci/check_imports.py 与 Makefile——三段式导入检查的实现与make check-imports/make check-imports-strict的用法。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考