ZenML Agent 协作规范全解AGENTS.md 分层规则体系与 AI 编码代理的工程约束设计【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml本文以 ZenML 仓库根目录的 AGENTS.md 为核心完整解读该项目面向 AI 编码代理Codex/Claude 等设计的全套贡献规范体系根级常载规则、七个目录级 AGENTS.md 子规范以及按需加载的 zenml-repo-workflows 技能文件。读完本文你将理解一个大型 MLOps 框架如何用分层 Markdown 规则约束 AI 代理的代码风格、导入边界、迁移流程与 PR 评审并能将同样的方法迁移到自己的仓库中。一、三层规则架构常载规则、目录规则与按需技能根目录 AGENTS.md 开篇即声明其定位这是每个 Codex 会话都必须加载must be loaded for every Codex session的根指南负责保留安全规则、通用约定和最常用命令而更长的流程配方、示例和子系统清单则放在 .agents/skills/zenml-repo-workflows/SKILL.md 中按需读取。整个体系分为三层层级文件加载时机职责根级常载规则AGENTS.md每次会话必载项目结构、代码风格、常用命令、分支/PR/安全规则、架构与 API 安全、FastAPI/数据库规则、子系统指针、评审清单、文档规则目录级规则各子目录下 7 个 AGENTS.md代理进入对应目录时加载该子系统的专属硬约束导入边界、关键文件、失败案例按需技能SKILL.md规则不足以支撑具体任务时加载详细工作流配方环境搭建、CI、迁移测试、过滤器联动、编排器实现清单、SQL 查询等目录级 AGENTS.md 的完整清单均由根指南的 Subsystem Pointers 一节索引docs/book/AGENTS.md — 文档源、GitBook 链接与文档检查src/zenml/cli/AGENTS.md — CLI 导入规则与 filter/client 耦合src/zenml/integrations/AGENTS.md — 集成 flavor 导入规则src/zenml/models/AGENTS.md — 领域模型兼容性与 filter 字段src/zenml/orchestrators/AGENTS.md — 编排器 run ID 与动态 pipelinesrc/zenml/zen_server/AGENTS.md — 服务端导入边界与端点形状src/zenml/zen_stores/migrations/AGENTS.md — Alembic 迁移指南src/zenml/zen_stores/schemas/AGENTS.md — ORM schema 与 SQL 导入规则。这种根规则保底 目录规则就地约束 技能文件深度配方的设计本质上是用文件位置隐式控制上下文注入代理在src/zenml/integrations/下工作时才会被 flavor 导入规则命中避免无关规则污染上下文窗口。二、项目结构与 Always-Loaded 通用规则根指南首先声明仓库布局作为所有规则的空间坐标src/zenml/— 核心源码tests/— 单元与集成测试docs/book/— 文档源examples/— 示例项目scripts/— 开发工具脚本。代码风格与 Python 规范根指南的 Always-Loaded Rules 一节列出逐条硬约束代码、注释、docstring 与文档统一使用美式英语拼写使用Python 3.10 兼容代码。这一约束与 pyproject.toml 中第 43 行的requires-python 3.10,3.15相互印证说明规则不是空话而是与打包元数据对齐的函数参数与返回值必须带类型注解docstring 遵循Google Python 风格按函数契约需要包含Args、Returns、Yields、Raises各节——明确禁止只写一句摘要来省略适用小节的偷懒写法优先用清晰的命名和小的函数代替解释性注释注释应解释意图、权衡、约束、不变量与棘手的边界情况避免复述显而易见的代码禁止用多行横幅注释banner comments给类或函数分组优先用类型化契约替代getattr/hasattr能力探测单下划线前缀的私有方法/函数不得在所属类或模块之外被调用集成代码应避免使用 ZenML 私有方法因为外置化externalized后的集成包不再受仓库内 mypy 检查保护。常用命令格式化、质量检查与测试纪律根指南 Common Commands 一节给出的可执行命令# 提交前格式化 bash scripts/format.sh # 质量检查 bash scripts/lint.sh # 只跑定向测试 pytest tests/unit/path/to/test_file.py pytest tests/unit/path/to/test_file.py::test_specific_function三条测试纪律值得注意默认禁止运行完整本地测试套件——很多测试依赖特殊环境测试运行后若又做了改动必须重跑相关测试测试目标是验证你改的那一块而不是刷覆盖率。SKILL.md 进一步补充了scripts/lint.sh的内部构成它串联运行 Ruff、pydoclint针对src/zenml tests/harness、yamlfix、zizmor、未使用导入/变量检查、Ruff 格式检查与 mypy并提醒完整 mypy 在全仓库上很慢聚焦开发时应只对改动文件/包运行 mypy。分支、Git 与 PR 流程develop才是主工作分支不是main新工作一律从develop切出PR 目标分支为developmain只在发布时更新使用定向git add不得暂存无关文件design/目录下的任何内容永远不得进入 git 历史PR 标题要简洁、人类可读不要feat:之类前缀每个 PR 必须恰好打一个 release-notes 标签release-notes或no-release-notes。SKILL.md 给出了判定标准——面向用户的特性、API 变更、重要修复用release-notes内部工作、CI 修复、重构、纯小文档改动、维护性工作用no-release-notes向已打开的 PR 推送新提交时检查 PR 描述是否需要同步更新。CI 采用双层结构SKILL.md Continuous Integration 一节Fast CI 覆盖所有 PR跑基础测试、lint 与类型检查Full CI 含集成测试与更广覆盖由run-slow-ci标签触发维护者按需添加——如果改动触及集成或核心行为应在 PR 中主动提出需要跑 Full CI。安全规则永不提交密钥、API key、token、密码或凭据敏感数据走环境变量或 ZenML 的 secret 管理校验并净化用户输入密钥被误提交时立即通知团队。三、架构与导入边界四条红线Architecture and API Safety 一节是根指南中最具工程判断力的部分改公共接口前先查导出修改任何看起来是公共的类或函数前先检查它是否从zenml.__init__导出根导出及其方法属于公共 API需要向后兼容演化或弃用deprecation流程内部非下划线方法改动时搜索全部用法并更新所有内部调用方警惕 model 一词的三重含义它可能指 Pydantic 模型、机器学习模型或 ZenML 的 model 命名空间——写代码和评审时都要显式指明横切特性要追踪全链路修改跨切面功能时必须追踪 CLI、client、server、models、schemas、migrations、tests、docs 的完整路径。导入边界是四条永不违反NEVER红线分别约束三个子系统红线约束内容依据文件服务端边界src/zenml/zen_server/之外的代码永不导入zen_server/src/zenml/zen_server/AGENTS.md存储边界zen_stores/之外的代码不得直接导入 SQL 相关代码走Client或很少地client.zen_storesrc/zenml/zen_stores/schemas/AGENTS.md集成边界flavor 文件顶层永不导入第三方集成库src/zenml/integrations/AGENTS.md客户端运行时客户端机器上 FastAPI/uvicorn 等服务端依赖是可选的src/zenml/zen_server/AGENTS.md这些红线在 SKILL.md 的 Review Checklist 中再次出现为自动评审项nozen_serverimports outsidezen_server、no direct SQL imports outsidezen_stores形成规则—约束—评审的闭环。FastAPI 与运行时规则针对 ZenML OSS 的服务端开发根指南要求技术栈预期为FastAPI SQLModel SQLAlchemy 2.0 Pydantic v2范式OSS 贡献中的路由处理函数使用同步def实现SKILL.md 说明这是 OSS Codex contributions 的约定共享状态只能放在 FastAPI 依赖注入或应用工厂内永不在初始化之外引入新的全局变量路由、依赖、服务一律以卫语句guard clauses开头预期错误抛出带精确状态码的HTTPException路由输入输出全部使用 Pydantic 模型OTel 联动约束升级服务端框架如 fastapi或数据库库版本时要检查 OpenTelemetry SDK、exporter 与 instrumentation 依赖是否需要同步升级——被插桩库的破坏性变更可能要求 OTel 协调更新且 OTel SDK/exporter 版本要与对应的 instrumentation beta 线保持一致。这是整个规范中最容易被忽略、却最可能导致线上观测链路静默失效的规则。四、数据库与迁移规则滚动升级优先ZenML 的数据层约束Database and Storage Rules使用 SQLModel SQLAlchemy非必要不写原始 SQLschema 变更必须走Alembic 迁移永不修改已存在于main或develop上的既有迁移任何迁移都要考虑滚动部署rolling deployment的向后兼容有意义的 schema 变更用alembic upgrade head验证升级路径。迁移操作的完整配方在 SKILL.md 的 Database and Migrations 一节中# 创建描述性迁移 alembic revision -m Add X to Y table # 验证升级路径 alembic upgrade head # 校验迁移分支一致性 bash scripts/check-alembic-branches.sh配套的四步迁移测试工作流检出develop或相关旧版本用该版本灌入数据库切到特性分支运行alembic upgrade head。两点补充downgrade 测试是可选的因为 ZenML 一般不支持回滚需要时 schema 变更与数据迁移要一并包含。SKILL.md 还给出了一段用于外键依赖追踪的 MySQL 查询基于INFORMATION_SCHEMA.KEY_COLUMN_USAGE关联REFERENTIAL_CONSTRAINTS明确建议在做级联行为、删列删表、调试外键失败或审计 delete rule 之前先执行它——这是从生产环境经验固化下来的操作配方。五、目录级规范深读每条规则背后的真实失败场景目录级 AGENTS.md 的共同特征是少而硬并且往往带有一个具体的失败案例。以下按子系统逐一展开。5.1 集成flavor 导入规则与正确范式src/zenml/integrations/AGENTS.md 将规则升级为最高级措辞NEVER import integration libraries at the top level in flavor files顶层永不导入集成库。原因写得很直白Flavor 文件位于src/zenml/integrations/*/flavors/*.py会被 ZenML 的 server 和 client 导入以做栈组件发现。像boto3、sagemaker、kubernetes这样的可选依赖未必安装。一个模块级导入可能破坏整个 ZenML而不仅仅是那个集成。flavor 文件中允许的内容标准库导入、Pydantic 与 ZenML 核心导入、if TYPE_CHECKING:下的集成类型导入、只在组件被使用时才执行的implementation_class属性内的实现导入。不允许顶层导入集成库、顶层导入自身就依赖集成库的实现模块、用第三方集成类直接给配置字段定型。SKILL.md 给出了标准正确范式懒加载实现类from typing import TYPE_CHECKING, Type from zenml.orchestrators import BaseOrchestratorConfig from zenml.orchestrators.base_orchestrator import BaseOrchestratorFlavor if TYPE_CHECKING: from zenml.integrations.aws.orchestrators import SagemakerOrchestrator class SagemakerOrchestratorFlavor(BaseOrchestratorFlavor): property def implementation_class(self) - Type[SagemakerOrchestrator]: from zenml.integrations.aws.orchestrators import SagemakerOrchestrator return SagemakerOrchestrator集成包的目录形态约定为__init__.py集成注册flavors/orchestrators/、step_operators/、materializers/等实现目录。Step operator 集成要求实现异步优先的生命周期方法submit(...)、get_status(...)、wait(...)、cancel(...)并且在提交后立即把后端 job ID 存入 run 元数据保证 status/cancel/wait 可靠工作。依赖版本方面偏好含下界、排上界的区间写法且放弃对旧版本的支持即为破坏性变更需在 release notes 中说明。5.2 领域模型filter 字段三处联动src/zenml/models/AGENTS.md 定义了模型的核心模式Request 表示创建载荷、Update 表示部分修改载荷、Response 由 Body/Metadata/Resources 三段组成、Filter 定义查询字段、操作符、排序、作用域与分页作用域选择要遵循最窄所有权语义global/user/project。最有操作价值的是filter 字段联动清单——给 filter 模型加一个字段必须同步更新三处filter 模型字段本身对应的Client列表方法签名该 client 方法内部对 filter 模型的实例化。如果该字段不应暴露为 CLI 选项则把它加入 filter 模型的CLI_EXCLUDE_FIELDS基于关系的 filter 字段还可能需要 store 层的自定义 ORM join 逻辑。这条规则有源码级实证src/zenml/cli/utils.py 中list_options第 2998 行装饰器从 filter 模型字段自动生成 CLI 选项并在第 3034 行通过if k not in filter_model.CLI_EXCLUDE_FIELDS过滤掉不应暴露的字段——CLI 选项与 filter 模型是运行时耦合的漏改第 2、3 处就会在用户侧炸出TypeError: list_pipeline_runs() got an unexpected keyword argument new_field这正是 src/zenml/cli/AGENTS.md 中记载的Failure story。兼容性判定同样被显式化加可选属性通常安全删属性、改属性名、把必填字段改成旧代码无法容忍的可选、不兼容地改类型——均属高危或破坏性演化。SKILL.md 还给出了模型层的基类模式BaseRequest→{Entity}Request、BaseUpdate→{Entity}Update、BaseResponse[Body, Metadata, Resources]、BaseFilter/UserScopedFilter/ProjectScopedFilter/TaggableFilter新增实体通常意味着实现 Request、ResponseBody、ResponseMetadata、ResponseResources、Response、Filter 一整套类。5.3 CLI命令族与导入规则src/zenml/cli/AGENTS.md 列出关键文件地图utils.py含list_options、pipeline.pypipeline/run/legacy schedule/replay/resume、trigger.py原生 schedule 与 platform-event 触发器、resource_pool.py与resource_request.py资源池管理与队列检查、stack.py、base.py。命令族划分对应两套并存的调度体系zenml pipeline schedule ...— legacy schedule 记录pipeline.pyzenml trigger schedule ...— 原生 schedule 触发器trigger.pyzenml trigger platform-event ...— 平台事件触发器trigger.py。这与根指南评审清单中Scheduling changes: check both legacy schedule and trigger stacks调度改动要同时检查两套栈相呼应——双栈并存是当前代码库的客观状态任何调度相关改动都必须双轨验证。CLI 导入规则与集成边界一致CLI 文件中不在模块级导入集成库、不从zen_server/导入、不直接导入zen_stores/的 SQL schema走Client重量的可选导入留在具体命令函数内部。5.4 编排器run ID 语义与动态 pipelinesrc/zenml/orchestrators/AGENTS.md 的关键文件为base_orchestrator.py、containerized_orchestrator.py、step_launcher.py、step_runner.py及utils.py/cache_utils.py/input_utils.py/publish_utils.py。两条核心规则提交方法分工submit_pipeline(...)用于 DAG 已知的静态 pipelinesubmit_dynamic_pipeline(...)用于运行期 DAG 可变的动态 pipeline动态支持可能还需 isolated-step APIsubmit_isolated_step、get_isolated_step_status、wait_for_isolated_step、stop_isolated_step。剪枝只发生在基类BaseOrchestrator.run(...)在提交前已剔除被 replay 或客户端缓存跳过的步骤集成编排器不要重复实现该剪枝。get_orchestrator_run_id的语义约束是整份规范中最精细的一条返回值必须a跨后端 run 唯一b对同一次 ZenML pipeline run 内的所有步骤相同c在同一次动态编排环境的重试中保持稳定。文档明确警告不要返回固定字符串也不要返回在步骤之间变化的值。Kubernetes 被单独标注为特例——它对静态 pipeline 也有编排容器静态 run 优先取配置好的 K8s run ID动态 run 取父 K8s job 名仅在 job 查询失败时回退。动态子 pipeline 的联动检查面被完整列出src/zenml/execution/pipeline/dynamic/、src/zenml/pipelines/dynamic/、src/zenml/orchestrators/step_launcher.py以及 pipeline run 模型、schemas、migrations、tests、docs并指出后果——若 child key 或后端 run ID 在重试/恢复期间变化ZenML 会找不到已有的子 run 而重复启动工作。SKILL.md 的 Orchestrators 一节补全了实现清单继承ContainerizedOrchestrator步骤跑在容器里时、正确实现get_orchestrator_run_id()、实现submit_pipeline()/submit_dynamic_pipeline()、按需补 isolated-step 方法、处理调度 hook、尊重 CPU/内存/GPU 资源设置、同步执行时返回带wait_for_completion的SubmissionResult、用self.get_image(deployment, step_name)取镜像、用orchestrator_utils.get_step_entrypoint_command(...)生成入口命令。5.5 ORM schema 与服务端src/zenml/zen_stores/schemas/AGENTS.md 规定继承BaseSchema或NamedSchema使用显式tableTrue与__tablename__的声明式 SQLModel 风格新 schema 必须从src/zenml/zen_stores/schemas/__init__.py导出字符串列一般限制在约250 字符MySQL 原因外键一律用schema_utils.build_foreign_key_field构造关系两侧都要定义且back_populates对称多对多使用复合主键的 link model转换方法齐备to_model、from_request/from_model、update/update_from_model变更时刷新updated。预加载策略也给了精确判据集合用selectinloadjoinedload作用于集合会成倍放大行数、单值关系在关联行通常存在的 get 路径用joinedload、可空且通常为空的外键保持selectinload。src/zenml/zen_server/AGENTS.md 定义了标准端点五步序授权 → 检查 entitlement功能门控时→ 校验 RBAC 权限 → 调用zen_store()做数据操作 → 按既有路由风格使用 async 兼容包装器。另有一条极易踩坑的约束调用任何项目级资源的zen_store().list_*时必须在 filter 上设置project...否则查询会跨所有项目执行——这是把多租户隔离要求写进了规范。5.6 文档与迁移子规范docs/book/AGENTS.md 确立docs/book/为文档唯一真相源docs/mkdocs/、docs/site/等生成目录不可直接编辑增删移页面必须同步更新相应的toc.md资产文件放在与toc.md同级的.gitbook目录GitBook URL 跟随 TOC 层级而非文件系统路径跨主要文档区块OSS 文档与 Pro 文档的链接使用绝对地址。验证手段改动相对链接时跑相应本地链接检查大批量链接改动用lychee --offline --no-progress docs/book/**/*.md。src/zenml/zen_stores/migrations/AGENTS.md 则强调迁移工作的协调性迁移往往需要同步更新 ORM schema、领域模型、store 方法、client 方法、CLI 命令、测试与文档——单点改迁移文件几乎必然造成跨层不一致。六、评审清单与 SKILL.md 工作流配方根指南末尾的 Reviewer Checklist 是十项可勾选的验收标准完整继承如下集成 PRflavor 文件无顶层集成库导入编排器 PRget_orchestrator_run_id每次 run 唯一、且对该 run 内所有步骤稳定Filter 模型变更对应 client 方法签名与方法体已同步更新私有方法变更所有内部用法已更新导入检查zen_server之外无zen_server导入导入检查zen_stores之外无直接 SQL 导入模型变更加属性通常安全删除/改名/不兼容类型变更属高危依赖升级放弃旧版本支持即为破坏性变更调度变更同时检查 legacy schedule 与 trigger 两套栈Step operator 变更检查BaseStepOperator、StepLauncher与至少一个具体集成。SKILL.md 的开头还保留了一份 Moved Content Index列出了历史上位于根文件、现迁移至本技能文件的 30 多个主题代码风格、FastAPI Agent Profile、开发工作流、PR 指南、核心概念、集成添加等——这份索引本身就是规则演化的考古证据说明该规范体系经历了有意识的瘦身 分层重构根文件只保留每次会话都值得占用的内容。开发环境的配方同样具体推荐用uv安装依赖开发时建议设置ZENML_LOGGING_VERBOSITYDEBUG、MLSTACKS_ANALYTICS_OPT_OUTtrue、AUTO_OPEN_DASHBOARDfalse、ZENML_ENABLE_RICH_TRACEBACKfalse、TOKENIZERS_PARALLELISMfalse必须设置ZENML_ANALYTICS_OPT_INfalse与ZENML_DEBUGtrue后者让分析数据发往开发用 analytics server 而非官方服务器且由于 client-server 架构中 server 控制客户端分析状态即使 opt-in 为 true 也必须设置。辅助函数的落位也有判据SKILL.md Helper Placement只在某类上下文有意义、或子类频繁调用时放类上跨无关模块共享的通用行为放工具模块——文中以BaseOrchestrator.requires_resources_in_orchestration_environment为例说明它虽是全局可用的逻辑但因编排器子类调用频繁且属于编排执行决策的一部分而留在基类。常用工具位置src/zenml/utils/、src/zenml/orchestrators/utils.py、src/zenml/orchestrators/step_run_utils.py、src/zenml/orchestrators/publish_utils.py。七、这套规范体系的可复用设计要点从源码结构与规范文本可以归纳出四条值得借鉴的设计规则即失败案例的固化flavor 顶层导入禁令、zen_server导入边界、filter 字段TypeError、K8s run ID 重试问题——每条硬规则背后都有一个具体的事故或故障模式代理读到的是为什么而不仅仅是做什么上下文按目录注入目录级 AGENTS.md 只在该目录会话生效根文件保持精简技能文件按需加载三层结构直接对应了上下文窗口的经济分配规则、约束、评审三段闭环同一约束在根规则写规范、子目录 AGENTS.md就地约束、Reviewer Checklist出口检查中各出现一次任何一环被忽略都会被下一环拦截与代码事实强耦合requires-python约束、list_options/CLI_EXCLUDE_FIELDS机制、alembic脚本scripts/format.sh、scripts/lint.sh、scripts/check-alembic-branches.sh均可在仓库中直接验证规范文档因此不会被代码演化拖成过期宪法。对贡献者而言这套体系也明确了人机分工人类贡献者的入口是 CONTRIBUTING.md根指南末行即指向它AI 代理则以根 AGENTS.md 为唯一必载契约。理解了这套分层规则就等于拿到了 ZenML 仓库的贡献地形图——哪些边界不可越、哪些改动必须跨层追踪、哪些检查在合并前会被强制执行。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考