OpenSRE 核心代码库命名规范让core/里的每个文件与类型名如其义【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre本文是 OpenSRE 开源仓库core/目录的命名规范技术指南。它定义了一套小而可执行的词汇表与命名纪律目标是让任何读者仅凭文件名与类型名就能区分“数据类型”与“运行进程”、“可变状态”与“冻结快照”并推断出某个包的核心职责。读完本文你将掌握 OpenSRE 核心包docs/NAMING.md中从模块命名、类型命名到导入路径的完整约定并理解这些约定在 core/agent 与 core/agent_harness 源码中的真实落地方式可以直接指导你在此仓库中的阅读、评审与二次开发。一、术语表一个术语只表达一个含义OpenSRE 的命名哲学首先体现在“一词一义”上。core/中最容易混淆的几个概念在规范中都被严格收敛为单一含义术语含义仓库示例State在一次运行中逐步演变的可变 agent/会话事实AgentState、harness 端口SessionStateStorage/Repo持久化存储后端而非内存中的回合端口SessionStore、SessionRepo、JsonlSessionStoreSnapshot在某个边界回合开始、运行开始捕获的冻结视图TurnSnapshotRunInput/RunResult一次Agent.run()边界的输入与输出AgentRunInput、AgentRunResultResources单次工具调用中传给工具执行器的句柄ToolCallResourcesBudgetLLM token/上下文窗口策略——不是应用状态enforce_token_budgetHost算法所驱动的回调契约一个ProtocolLoopHost这组区分在源码中都有对应实体且命名与职责高度一致State 是“活”的Snapshot 是“冻”的SessionState定义于 core/agent_harness/ports.py是一个runtime_checkable的Protocol描述引擎在回合中读写的可变字段——会话历史history、session_id、推理强度reasoning_effort、集成解析缓存resolved_integrations_cache等而TurnSnapshotcore/agent_harness/turns/turn_snapshot.py是回合开始时通过TurnSnapshot.from_session构建一次的不可变上下文快照下游 prompt 构建器只读它写入仍走实时 session。一个词是活状态另一个词是边界冻结视图互不越界。State 与 Storage 分家InMemorySessionStatecore/agent_harness/turns/headless_adapters.py是无头headless模式下的内存态而SessionStore/SessionRepo是两个持久化Protocolcore/agent_harness/session/persistence/contracts.py 与 #L133JSONL 落地实现是JsonlSessionStorecore/agent_harness/session/persistence/jsonl_store.py。Store/Repo 一词只留给持久化后端。Budget 不是状态上下文预算控制由 core/context_budget.py 中的enforce_context_budget#L394等纯函数承担它是一套 token/window 策略不属于会话状态字段因此名字里不带任何 State 字样。二、模块命名{domain}_{role}.py规范要求用文件所承载的概念命名而不是用笼统的桶词。core/agent/目录是教科书式的范例七个文件各司其职、一读即懂core/agent/ agent.py # the Agent facade门面 react_loop.py # ReactLoop run_react_loop算法本身 loop_host.py # LoopHost回调契约 run_io.py # AgentRunInput, AgentRunResult运行边界的 I/O mixins.py # the reusable *Mixin behaviors可复用行为 provider_hooks.py # ProviderHookDelegate从源码可以验证这组职责划分是真实、可执行的agent.py里的Agent是一个薄门面它持有配置LLM、system prompt、工具、迭代上限run()把一次运行解析为AgentRunInput后交给run_react_loop自身不包含循环逻辑见 core/agent/agent.pyreact_loop.py是思考 → 调用工具 → 观察结果的循环算法本体ReactLoop运行循环、run_react_loop是单行函数式入口循环本身对Agent一无所知core/agent/react_loop.pyloop_host.py只声明LoopHost这一个Protocol即循环需要驱动方提供的回调集合core/agent/loop_host.py。文件名与内容一一对应、无歧义这就是{domain}_{role}.py约定的价值看到react_loop.py就知道是算法看到loop_host.py就知道是回调契约看到run_io.py就知道是边界数据。三、类型命名三条铁律3.1 Mixin 必须带Mixin后缀Mixin 不能独立存在——它们假设宿主提供了某些字段/方法。因此规范要求强制携带后缀例如EventEmitterMixin、ToolFilterMixin、SteeringMixin。在 core/agent/mixins.py 中EventEmitterMixin把(kind, data)元组事件与类型化运行时事件分发给监听回调且回调失败会被吞掉——事件渲染绝不能打断循环ToolFilterMixin提供_filter_tools钩子用于收窄 agent 可见的工具列表默认恒等SteeringMixin提供steer()在下一次 LLM 回合前注入用户消息与follow_up()在循环本将停止时追加消息。Agent正是由EventEmitterMixin, ToolFilterMixin, SteeringMixin组合而成core/agent/agent.py并在__init__中初始化 mixin 依赖的_steering_messages/_follow_up_messages队列。后缀即契约看到Mixin就知道它依赖宿主环境、不能单独实例化。3.2 Protocol 按角色命名不挂Protocol后缀与标准库Iterable、SupportsRead的风格一致OpenSRE 的Protocol按它是什么角色命名而不是叫XxxProtocol。LoopHost就是典型——它不叫LoopHostProtocol。这一点在 core/agent_harness/ports.py 中同样成立OutputSink输出渲染、SessionState会话可变状态都是按角色命名的Protocol。结构化的好处是Session无需继承SessionState只要字段与方法结构匹配即可满足协议鸭子类型run_react_loop只依赖LoopHostAgentRunInput任何具备这些方法的对象都能驱动循环不必认识Agent。3.3 不要用包名给类型加前缀在core/agent/内部类是EventEmitterMixin而不是AgentEventEmitter——命名空间本身已经声明了 agent重复前缀纯属噪音。这一点在 core/agent/init.py 的包注释中得到呼应每个文件只放一个职责类型名自解释无需包名前缀兜底。四、反模式清单新代码不要踩的坑规范明确列出了core/中禁止新增的反模式每一类都有清晰的替代方案反模式问题正确做法context.py出现在core/或core/agent/根context 一词在仓库中已严重重载直接命名概念如run_io.py、turn_snapshot.py只装运行 I/O 的models.py过于含糊无法表达模型是什么说清模型用途如run_io.py无领域前缀的*Context当已有同名类型存在时产生歧义与误引带领域前缀包内只有一个子包的包多余的包裹层折叠掉包装层把可变 harness 会话端口叫SessionStoreStore 专指持久化端口是SessionState无头模式用InMemorySessionStateJSONL 持久化保持SessionStore/SessionRepo模块级可变全局量承载 当前会话隐藏依赖、难以测试显式传递SessionState配合 no-globals 设计其中Store 与 State 分家这条在仓库中尤其重要SessionState端口在无头/测试运行里由InMemorySessionState满足core/agent_harness/turns/headless_adapters.py而需要落盘时用JsonlSessionStore。同一份会话事实内存态与持久态用完全不同的词杜绝了存了却不知道存哪的歧义。core/state/README.mdcore/state/README.md也印证了这套边界纪律该包只放跨回合对话状态MutableAgentState与 transcript 窗口压缩助手上下文裁剪/排序/预算逻辑留在 core/context_budget.py终端 UI、REPL 会话状态、slash 命令留在surfaces/interactive_shell/集成客户端留在integrations/基础设施服务留在infrastructure/——每个词、每个目录只表达一件事。五、导入约定全限定路径 单符号重导出代码内部使用全限定路径导入文档/口语中使用简短的心理标签。规范给出了两组对应关系心理标签导入语句ReAct 运行 I/Ofrom core.agent.run_io import AgentRunInput, AgentRunResultReAct 循环from core.agent.react_loop import run_react_loopLoop 回调契约from core.agent.loop_host import LoopHostAgent 原语from core.agent import AgentHarness 回合快照from core.agent_harness.turns.turn_snapshot import TurnSnapshot重导出规则同样克制包__init__.py只为唯一权威符号做重导出而不是把包内一切全部导出。core/agent/__init__.pycore/agent/init.py只重导出Agent与AgentRunResult两个符号——from core.agent import Agent是入口其余符号一律走全限定子模块路径。这样做避免了from core.agent import *式的命名空间污染读者永远知道一个名字来自哪个模块重命名与静态分析也更为安全。六、这套规范的实践价值命名规范看似文风问题在 OpenSRE 这种多 surface交互式 shell、gateway、headless API共享同一核心运行时的仓库里它实际上是可维护性的基础设施降低认知成本TurnSnapshot一定不可变、SessionState一定可变、SessionStore一定持久化——读到名字即获得契约信息无需追读实现保证架构边界Store/Repo 只归持久化、State 只归运行期可变事实、Budget 只归 token 策略反模式清单阻止新代码悄悄模糊这些边界例如把内存端口误命名为SessionStore服务代码评审与 AI 辅助开发全限定导入 单符号重导出让依赖关系一目了然LoopHost这类按角色命名的Protocol也使循环算法可以被任何结构化兼容的对象驱动测试与替换实现都极其轻量。如果你正在为 OpenSRE 贡献新模块请把这份规范当作core/的母语先问这个概念在术语表里叫什么再问文件名能否用{domain}_{role}.py说清职责最后检查类型名是否满足 Mixin 后缀、Protocol 按角色命名、不加包名前缀这三条铁律。遵循它你的代码在仓库中就会名如其义。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenSRE 核心代码库命名规范：让 `core/` 里的每个文件与类型名如其义
OpenSRE 核心代码库命名规范让core/里的每个文件与类型名如其义【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre本文是 OpenSRE 开源仓库core/目录的命名规范技术指南。它定义了一套小而可执行的词汇表与命名纪律目标是让任何读者仅凭文件名与类型名就能区分“数据类型”与“运行进程”、“可变状态”与“冻结快照”并推断出某个包的核心职责。读完本文你将掌握 OpenSRE 核心包docs/NAMING.md中从模块命名、类型命名到导入路径的完整约定并理解这些约定在 core/agent 与 core/agent_harness 源码中的真实落地方式可以直接指导你在此仓库中的阅读、评审与二次开发。一、术语表一个术语只表达一个含义OpenSRE 的命名哲学首先体现在“一词一义”上。core/中最容易混淆的几个概念在规范中都被严格收敛为单一含义术语含义仓库示例State在一次运行中逐步演变的可变 agent/会话事实AgentState、harness 端口SessionStateStorage/Repo持久化存储后端而非内存中的回合端口SessionStore、SessionRepo、JsonlSessionStoreSnapshot在某个边界回合开始、运行开始捕获的冻结视图TurnSnapshotRunInput/RunResult一次Agent.run()边界的输入与输出AgentRunInput、AgentRunResultResources单次工具调用中传给工具执行器的句柄ToolCallResourcesBudgetLLM token/上下文窗口策略——不是应用状态enforce_token_budgetHost算法所驱动的回调契约一个ProtocolLoopHost这组区分在源码中都有对应实体且命名与职责高度一致State 是“活”的Snapshot 是“冻”的SessionState定义于 core/agent_harness/ports.py是一个runtime_checkable的Protocol描述引擎在回合中读写的可变字段——会话历史history、session_id、推理强度reasoning_effort、集成解析缓存resolved_integrations_cache等而TurnSnapshotcore/agent_harness/turns/turn_snapshot.py是回合开始时通过TurnSnapshot.from_session构建一次的不可变上下文快照下游 prompt 构建器只读它写入仍走实时 session。一个词是活状态另一个词是边界冻结视图互不越界。State 与 Storage 分家InMemorySessionStatecore/agent_harness/turns/headless_adapters.py是无头headless模式下的内存态而SessionStore/SessionRepo是两个持久化Protocolcore/agent_harness/session/persistence/contracts.py 与 #L133JSONL 落地实现是JsonlSessionStorecore/agent_harness/session/persistence/jsonl_store.py。Store/Repo 一词只留给持久化后端。Budget 不是状态上下文预算控制由 core/context_budget.py 中的enforce_context_budget#L394等纯函数承担它是一套 token/window 策略不属于会话状态字段因此名字里不带任何 State 字样。二、模块命名{domain}_{role}.py规范要求用文件所承载的概念命名而不是用笼统的桶词。core/agent/目录是教科书式的范例七个文件各司其职、一读即懂core/agent/ agent.py # the Agent facade门面 react_loop.py # ReactLoop run_react_loop算法本身 loop_host.py # LoopHost回调契约 run_io.py # AgentRunInput, AgentRunResult运行边界的 I/O mixins.py # the reusable *Mixin behaviors可复用行为 provider_hooks.py # ProviderHookDelegate从源码可以验证这组职责划分是真实、可执行的agent.py里的Agent是一个薄门面它持有配置LLM、system prompt、工具、迭代上限run()把一次运行解析为AgentRunInput后交给run_react_loop自身不包含循环逻辑见 core/agent/agent.pyreact_loop.py是思考 → 调用工具 → 观察结果的循环算法本体ReactLoop运行循环、run_react_loop是单行函数式入口循环本身对Agent一无所知core/agent/react_loop.pyloop_host.py只声明LoopHost这一个Protocol即循环需要驱动方提供的回调集合core/agent/loop_host.py。文件名与内容一一对应、无歧义这就是{domain}_{role}.py约定的价值看到react_loop.py就知道是算法看到loop_host.py就知道是回调契约看到run_io.py就知道是边界数据。三、类型命名三条铁律3.1 Mixin 必须带Mixin后缀Mixin 不能独立存在——它们假设宿主提供了某些字段/方法。因此规范要求强制携带后缀例如EventEmitterMixin、ToolFilterMixin、SteeringMixin。在 core/agent/mixins.py 中EventEmitterMixin把(kind, data)元组事件与类型化运行时事件分发给监听回调且回调失败会被吞掉——事件渲染绝不能打断循环ToolFilterMixin提供_filter_tools钩子用于收窄 agent 可见的工具列表默认恒等SteeringMixin提供steer()在下一次 LLM 回合前注入用户消息与follow_up()在循环本将停止时追加消息。Agent正是由EventEmitterMixin, ToolFilterMixin, SteeringMixin组合而成core/agent/agent.py并在__init__中初始化 mixin 依赖的_steering_messages/_follow_up_messages队列。后缀即契约看到Mixin就知道它依赖宿主环境、不能单独实例化。3.2 Protocol 按角色命名不挂Protocol后缀与标准库Iterable、SupportsRead的风格一致OpenSRE 的Protocol按它是什么角色命名而不是叫XxxProtocol。LoopHost就是典型——它不叫LoopHostProtocol。这一点在 core/agent_harness/ports.py 中同样成立OutputSink输出渲染、SessionState会话可变状态都是按角色命名的Protocol。结构化的好处是Session无需继承SessionState只要字段与方法结构匹配即可满足协议鸭子类型run_react_loop只依赖LoopHostAgentRunInput任何具备这些方法的对象都能驱动循环不必认识Agent。3.3 不要用包名给类型加前缀在core/agent/内部类是EventEmitterMixin而不是AgentEventEmitter——命名空间本身已经声明了 agent重复前缀纯属噪音。这一点在 core/agent/init.py 的包注释中得到呼应每个文件只放一个职责类型名自解释无需包名前缀兜底。四、反模式清单新代码不要踩的坑规范明确列出了core/中禁止新增的反模式每一类都有清晰的替代方案反模式问题正确做法context.py出现在core/或core/agent/根context 一词在仓库中已严重重载直接命名概念如run_io.py、turn_snapshot.py只装运行 I/O 的models.py过于含糊无法表达模型是什么说清模型用途如run_io.py无领域前缀的*Context当已有同名类型存在时产生歧义与误引带领域前缀包内只有一个子包的包多余的包裹层折叠掉包装层把可变 harness 会话端口叫SessionStoreStore 专指持久化端口是SessionState无头模式用InMemorySessionStateJSONL 持久化保持SessionStore/SessionRepo模块级可变全局量承载 当前会话隐藏依赖、难以测试显式传递SessionState配合 no-globals 设计其中Store 与 State 分家这条在仓库中尤其重要SessionState端口在无头/测试运行里由InMemorySessionState满足core/agent_harness/turns/headless_adapters.py而需要落盘时用JsonlSessionStore。同一份会话事实内存态与持久态用完全不同的词杜绝了存了却不知道存哪的歧义。core/state/README.mdcore/state/README.md也印证了这套边界纪律该包只放跨回合对话状态MutableAgentState与 transcript 窗口压缩助手上下文裁剪/排序/预算逻辑留在 core/context_budget.py终端 UI、REPL 会话状态、slash 命令留在surfaces/interactive_shell/集成客户端留在integrations/基础设施服务留在infrastructure/——每个词、每个目录只表达一件事。五、导入约定全限定路径 单符号重导出代码内部使用全限定路径导入文档/口语中使用简短的心理标签。规范给出了两组对应关系心理标签导入语句ReAct 运行 I/Ofrom core.agent.run_io import AgentRunInput, AgentRunResultReAct 循环from core.agent.react_loop import run_react_loopLoop 回调契约from core.agent.loop_host import LoopHostAgent 原语from core.agent import AgentHarness 回合快照from core.agent_harness.turns.turn_snapshot import TurnSnapshot重导出规则同样克制包__init__.py只为唯一权威符号做重导出而不是把包内一切全部导出。core/agent/__init__.pycore/agent/init.py只重导出Agent与AgentRunResult两个符号——from core.agent import Agent是入口其余符号一律走全限定子模块路径。这样做避免了from core.agent import *式的命名空间污染读者永远知道一个名字来自哪个模块重命名与静态分析也更为安全。六、这套规范的实践价值命名规范看似文风问题在 OpenSRE 这种多 surface交互式 shell、gateway、headless API共享同一核心运行时的仓库里它实际上是可维护性的基础设施降低认知成本TurnSnapshot一定不可变、SessionState一定可变、SessionStore一定持久化——读到名字即获得契约信息无需追读实现保证架构边界Store/Repo 只归持久化、State 只归运行期可变事实、Budget 只归 token 策略反模式清单阻止新代码悄悄模糊这些边界例如把内存端口误命名为SessionStore服务代码评审与 AI 辅助开发全限定导入 单符号重导出让依赖关系一目了然LoopHost这类按角色命名的Protocol也使循环算法可以被任何结构化兼容的对象驱动测试与替换实现都极其轻量。如果你正在为 OpenSRE 贡献新模块请把这份规范当作core/的母语先问这个概念在术语表里叫什么再问文件名能否用{domain}_{role}.py说清职责最后检查类型名是否满足 Mixin 后缀、Protocol 按角色命名、不加包名前缀这三条铁律。遵循它你的代码在仓库中就会名如其义。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考