Agent Zero 仓库脚本治理契约与 AI 发布说明生成链路全解析【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文围绕 Agent Zero 仓库中scripts/目录的工程治理规范scripts/AGENTS.md展开深入剖析该目录的职责边界、确定性自动化契约以及以openrouter_release_notes_system_prompt.md提示词为核心的 AI 发布说明生成链路。读完本文你将掌握 Agent Zero 是如何用DOX 契约链管理维护脚本、如何让 GitHub Actions 工作流与 Python 规划脚本协同完成 Docker 镜像发布与 Release Notes 生成以及如何通过测试守住这些自动化行为的稳定性。一、scripts/ 目录在 Agent Zero 中的定位Agent Zero 的仓库采用一套自描述的DOXDocumentation of eXpectations契约体系根目录的 AGENTS.md 是项目级工程规则的顶层索引而每个子目录下的AGENTS.md则是该子树具有约束力的契约binding contracts。scripts/AGENTS.md正是这套链条中的一环其职责被明确界定为拥有并维护位于 GitHub 工作流目录之外的维护者脚本与自动化脚本保持脚本确定性deterministic、被邻近调用方文档化、并且在干净的检出clean checkouts中安全可运行。从根目录 DOX 索引AGENTS.md可以看到scripts/AGENTS.md的 Scope 是 Repository maintenance scripts and automation inputs即仓库维护脚本与自动化输入。目前该目录实际只包含两个文件scripts/ ├── AGENTS.md └── openrouter_release_notes_system_prompt.md其中AGENTS.md是目录契约openrouter_release_notes_system_prompt.md则是被.github/scripts/docker_release_plan.py消费的发布说明生成提示词——它是整个 AI 生成 Release Notes 功能的自动化输入automation input这正是该目录被称为维护脚本与自动化输入的原因。二、scripts/AGENTS.md 契约逐节解读scripts/AGENTS.md沿用了根 DOX 工作流推荐的六段式结构Purpose、Ownership、Local Contracts、Work Guidance、Verification、Child DOX Index。逐节解读如下。2.1 Purpose目录的职责边界负责维护者脚本与自动化脚本且这些脚本不放在 GitHub 工作流目录内即不属于.github/workflows/下的 YAML要求脚本确定性、被邻近调用方文档化、在干净检出中安全运行。这里的确定性deterministic是一个关键工程约束同一输入必须产生同一输出脚本不能被本机环境、时间、网络抖动等因素隐性影响否则 CI 行为将不可复现。2.2 Ownership所有权声明openrouter_release_notes_system_prompt.md由.github/scripts/docker_release_plan.py消费不属于运行时应用代码runtime application code的仓库维护脚本都应当放在这里。也就是说scripts/与helpers/后端运行时共享工具有明确分工scripts/服务仓库工程本身发布、维护、CI 辅助helpers/服务应用运行逻辑。2.3 Local Contracts本地契约绝不提交密钥secrets、生成的凭据、私有发布说明或本机机器路径供 CI 使用的脚本必须有稳定输入且失败时输出可操作的错误信息actionable errors脚本行为必须与.github/AGENTS.md、工作流 YAML 以及测试保持同步。这些契约直接体现在底层脚本中docker_release_plan.py的require_env().github/scripts/docker_release_plan.py在关键环境变量缺失时会fail(fRequired environment variable \{name} is missing.) 并以非零退出码终止正是失败时给出可操作错误的落地实现。2.4 Work Guidance工作指引除非脚本运行期已有可用依赖否则优先使用标准库 Python 或简单 shell 兼容资产保持提示词与自动化输入简洁且受版本控制重命名或移动脚本时必须更新调用方。这条更新调用方的约束与保持与工作流 YAML、测试同步Local Contracts互为表里——docker_release_plan.py被 .github/workflows/docker-publish.yml 的plan、resolve-build、resolve-release三个 job 步骤调用任何路径或命令签名变更都必须同步工作流。2.5 Verification验证要求对任何有测试覆盖的自动化脚本运行针对性测试对发布说明提示词的改动必须检查.github/scripts/docker_release_plan.py中期望的输出格式。针对该提示词的测试正是 tests/test_docker_release_plan.py 中加载整个规划模块的机制它通过importlib.util.spec_from_file_location直接加载.github/scripts/docker_release_plan.pytests/test_docker_release_plan.py再在临时 git 仓库中模拟分支晋升与标签发布场景进行断言。2.6 Child DOX Index当前无子 DOX 文件目录规模小一份契约足以覆盖。三、核心自动化输入发布说明生成提示词scripts/openrouter_release_notes_system_prompt.md 是目录中唯一的非契约文件也是scripts/AGENTS.mdOwnership 段点名消费关系的被消费方。它是一份面向 LLM 的系统提示词完整内容如下You write GitHub release notes for Agent Zero.Produce release-ready Markdown only. Do not add preambles, explanations, code fences, or commentary about the prompt.Requirements:Base the release notes only on the commit headings and descriptions provided by the user.Prefer the most meaningful user-facing changes, important fixes, notable infrastructure or packaging changes, and any clearly stated breaking changes.Skip low-signal churn, duplicate points, and purely procedural wording unless it materially affects users or operators.Group related items when that improves readability, but keep the output concise.Do not invent features, bug fixes, migrations, or breaking notes that are not supported by the commits.Do not mention commit hashes, pull request numbers, authors, files, or internal implementation trivia unless the commit text makes them essential to understanding the release.If the commit list does not justify any meaningful notes, return exactly:No release notes.Preferred format:A short introductory line or heading is allowed but optional.Then use a flat bullet list of the key release points.Add a shortBreaking changessection only when the commit content clearly warrants it.这份提示词的设计要点可以提炼为三条核心约束与scripts/AGENTS.md的简洁、版本控制、确定性精神一脉相承只输出产物不输出过程要求仅生成可直接发布的 Markdown禁止前言、解释、代码围栏或对提示词本身的评论忠于提交禁止臆造发布要点只能基于用户提供的提交标题与描述明确禁止发明不存在的特性、修复、迁移或破坏性变更也不得在无依据时提及提交哈希、PR 编号、作者或文件名空结果协议当提交列表不足以支撑任何有意义的说明时必须精确返回No release notes.——这个字符串在底层脚本中被当作约定的空结果哨兵见下文降级逻辑。四、底层引擎docker_release_plan.py 的三阶段架构发布说明提示词的消费方是 .github/scripts/docker_release_plan.py841 行纯 Python 标准库实现。脚本通过main().github/scripts/docker_release_plan.py暴露三个子命令对应工作流中的三个 job 阶段子命令职责工作流中的使用步骤plan根据事件类型与分支/标签状态规划本次发布候选Candidate 矩阵planjobresolve-build在构建前二次校验目标是否仍符合发布条件解析出要推送的 Docker 标签列表buildjobresolve-release决定是否发布 GitHub Release并生成或降级Release Bodybuildjob镜像推送成功后4.1 配置加载与硬性校验load_config().github/scripts/docker_release_plan.py从环境变量读取全部规划参数并做两层硬校验ALLOWED_BRANCHES不能为空、MAIN_BRANCH必须同时出现在ALLOWED_BRANCHES中。Config数据类.github/scripts/docker_release_plan.py封装了允许分支、主分支、镜像仓库、标签正则、最低版本、事件名、引用名/类型、手动标签、before/after SHA 等全部输入。parse_release_tag().github/scripts/docker_release_plan.py用RELEASE_TAG_REGEX对标签做全匹配fullmatch并把版本解析为(major, minor)元组低于MIN_RELEASE_MAJOR.MIN_RELEASE_MINOR的标签一律视为不可发布。4.2 分支状态收集collect_branch_states().github/scripts/docker_release_plan.py遍历每个允许分支先通过git show-ref确认origin/branch已拉取未拉取直接 fail再用git tag --merged origin/branch收集该分支可达的所有合规标签并按版本排序取最大者为latest_tag。这为后续所有是否该构建的判断提供了分支维度的权威依据。4.3 三种规划模式脚本按事件类型分派到三种规划函数标签推送plan_tag_push当推送事件本身是vX.Y标签时检查该标签是否被某个允许分支可达且是该分支当前最高标签只有main上的最新标签同时发布版本标签与latest分支晋升plan_branch_push.github/scripts/docker_release_plan.py比较before_sha与after_sha上各自的最高可达标签若分支的最高标签因合并/晋升而更新则触发构建这正是 tests/test_docker_release_plan.py 中模拟的v1.7 被 promote 到 testing 与 main场景——testing只发布分支标签publish_versionFalsemain才发布版本标签publish_versionTrue手动分发plan_manual_exact/plan_manual_backfill手动触发时若不指定标签则回填缺失的 Docker Hub 标签通过docker buildx imagetools inspect探测镜像是否已存在若指定标签则精确重建该目标且仅在它仍是main上最高标签时刷新latest与 GitHub Release。resolve_build_command().github/scripts/docker_release_plan.py在构建前对每个候选做二次资格校验标签仍存在、仍可达、仍是最高标签、目标 Docker 标签尚不存在防止规划后、构建前窗口期内的状态变化导致重复推送或推送过期版本。五、工作流集成docker-publish.yml 的触发与变量.github/workflows/docker-publish.yml 是整个发布链路的入口其关键配置如下触发条件onpush到testing、ready、main分支push标签v*workflow_dispatch手动触发带可选输入tag如v1.21用于手动重建。环境变量env变量当前取值含义ALLOWED_BRANCHEStesting ready main允许发布镜像的分支非 main 分支以分支名作为 Docker 标签MAIN_BRANCHmain唯一发布版本标签与 GitHub Release 的分支RELEASE_TAG_REGEX^v([0-9])\.([0-9])$合规发布标签格式MIN_RELEASE_MAJOR/MIN_RELEASE_MINOR1/0最低可发布版本v1.0 起DOCKERFILE_DIR/DOCKERFILE_PATHdocker/run/docker/run/Dockerfile构建上下文与 DockerfileDOCKER_IMAGE_NAMEagent-zero镜像名DOCKER_PLATFORMSlinux/amd64,linux/arm64多架构构建平台密钥与凭据secrets / varsDOCKERHUB_ORG、DOCKERHUB_OAT_TOKENDocker Hub 登录与推送、GITHUB_TOKENGitHub Release 写入、OPENROUTER_API_KEYrelease notes 生成、OPENROUTER_MODEL_NAMEvars指定模型名。这与scripts/AGENTS.md的绝不提交密钥契约直接对应——所有凭据都存放在 GitHub Actions secrets 中。流程骨架planjob 校验 secrets → 检出fetch-depth: 0→ 拉取远程分支与标签 → 运行docker_release_plan.py plan产出矩阵 →buildjob 按矩阵二次resolve-build解析标签 →docker/build-push-actionv6多平台构建推送 → 成功后resolve-release决定是否创建/更新 GitHub Releaseactions/github-scriptv7先查后建make_latest: true。六、发布说明生成链路从提交到 Release BodyRelease Notes 的生成是resolve-release阶段的职责核心链路如下确定对比基准previous_published_release_tag().github/scripts/docker_release_plan.py通过 GitHub Releases API 分页拉取历史发布跳过 draft 与 prerelease筛选出版本低于当前标签且最高的那个作为上一发布标签收集提交collect_release_commits().github/scripts/docker_release_plan.py用git log --reverse --format%s%x1f%b%x1e prev..tag以单元分隔符\x1e/\x1f切分提交标题与描述并先验证上一标签是当前标签的祖先避免范围错乱构造用户消息build_release_notes_user_message().github/scripts/docker_release_plan.py将提交列表格式化为编号条目成为提示词中用户提供的提交标题与描述调用 OpenRoutergenerate_release_body_with_openrouter().github/scripts/docker_release_plan.py读取OPENROUTER_SYSTEM_PROMPT_PATH指向 scripts/openrouter_release_notes_system_prompt.md见 .github/scripts/docker_release_plan.py作为 system 消息提交列表作为 user 消息temperature固定为 0.2 以压制创造性、保证输出稳定性请求头携带HTTP-Referer与X-OpenRouter-Title60 秒超时HTTP 错误与网络错误都会以可读细节直接fail解析与降级从响应choices[0].message.content中提取文本兼容纯字符串与多段 content 数组见extract_openrouter_message_content()空内容兜底为No release notes..github/scripts/docker_release_plan.py。若整个生成过程抛错resolve_release_command().github/scripts/docker_release_plan.py会捕获异常并降级为静态 Release BodyFailed to generate release notes.同时保留previous_release_tag与release_commit_count输出保证发布流程不被单点故障阻断。需要特别注意的是只有main分支且当前标签是该分支最高发布标签时才会走到发布环节其他分支直接输出should_releasefalse与跳过原因——这保证了 Release 只产生于正式发布分支。七、验证与测试守住自动化契约.github/AGENTS.md.github/AGENTS.md与scripts/AGENTS.md共同要求改动 Docker 发布规划或发布工作流行为后运行pytest tests/test_docker_release_plan.py。tests/test_docker_release_plan.py 现有三个测试覆盖了关键行为test_docker_publish_workflow_tracks_branch_promotionstests/test_docker_release_plan.py静态断言工作流 YAML 包含testing/main分支触发、v*标签触发、workflow_dispatch与tag输入、以及BEFORE_SHA/AFTER_SHA的注入表达式防止工作流契约被无意破坏test_plan_branch_push_builds_when_tag_reaches_allowed_branchtests/test_docker_release_plan.py在tmp_path中git init构造真实仓库打v1.6/v1.7标签、模拟 development → testing → main 的晋升合并并通过monkeypatch.setenv注入全部环境变量后调用load_config()与plan_branch_push()断言testing候选为mode push_promoted_tag、publish_version is False而main候选publish_version is True——用端到端方式验证了分支晋升驱动发布的核心逻辑。这种YAML 静态断言 临时 git 仓库行为断言的组合正是scripts/AGENTS.md中同步工作流 YAML 与测试契约的可执行化体现。八、对维护者的实践要点综合scripts/AGENTS.md契约与源码实现可以沉淀出 Agent Zero 脚本治理的四条可复用原则脚本与提示词都进版本控制自动化输入如发布说明提示词与消费它的脚本同仓共存、同 PR 演进杜绝改脚本忘改提示词或反之的脱节确定性优先规划逻辑用可测试的 Python 标准库实现.github/AGENTS.md明确要求用确定性的、可测试的 Python 替代 YAML 中的复杂内联 shell固定temperature用before/after SHA快照做幂等判断失败要响亮且可操作缺失环境变量、缺失远程引用、标签不可达等一切异常都通过fail()给出带具体变量名/引用名的错误并以非零码退出绝不让 CI 静默通过权限最小化与密钥隔离所有凭据走 GitHub Actions secrets/env vars代码库内绝不落盘密钥或本机路径Docker Hub 写入仅发生在计划阶段校验通过之后。对于希望为 Agent Zero 贡献或自托管该发布流水线的开发者建议按此顺序理解代码先读 .github/workflows/docker-publish.yml 把握事件与阶段再读 .github/scripts/docker_release_plan.py 的main()/load_config()与三个规划函数最后以 scripts/openrouter_release_notes_system_prompt.md 为模板理解自动化输入如何被消费并以 tests/test_docker_release_plan.py 为改动后的验证标准。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero 仓库脚本治理契约与 AI 发布说明生成链路全解析
Agent Zero 仓库脚本治理契约与 AI 发布说明生成链路全解析【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文围绕 Agent Zero 仓库中scripts/目录的工程治理规范scripts/AGENTS.md展开深入剖析该目录的职责边界、确定性自动化契约以及以openrouter_release_notes_system_prompt.md提示词为核心的 AI 发布说明生成链路。读完本文你将掌握 Agent Zero 是如何用DOX 契约链管理维护脚本、如何让 GitHub Actions 工作流与 Python 规划脚本协同完成 Docker 镜像发布与 Release Notes 生成以及如何通过测试守住这些自动化行为的稳定性。一、scripts/ 目录在 Agent Zero 中的定位Agent Zero 的仓库采用一套自描述的DOXDocumentation of eXpectations契约体系根目录的 AGENTS.md 是项目级工程规则的顶层索引而每个子目录下的AGENTS.md则是该子树具有约束力的契约binding contracts。scripts/AGENTS.md正是这套链条中的一环其职责被明确界定为拥有并维护位于 GitHub 工作流目录之外的维护者脚本与自动化脚本保持脚本确定性deterministic、被邻近调用方文档化、并且在干净的检出clean checkouts中安全可运行。从根目录 DOX 索引AGENTS.md可以看到scripts/AGENTS.md的 Scope 是 Repository maintenance scripts and automation inputs即仓库维护脚本与自动化输入。目前该目录实际只包含两个文件scripts/ ├── AGENTS.md └── openrouter_release_notes_system_prompt.md其中AGENTS.md是目录契约openrouter_release_notes_system_prompt.md则是被.github/scripts/docker_release_plan.py消费的发布说明生成提示词——它是整个 AI 生成 Release Notes 功能的自动化输入automation input这正是该目录被称为维护脚本与自动化输入的原因。二、scripts/AGENTS.md 契约逐节解读scripts/AGENTS.md沿用了根 DOX 工作流推荐的六段式结构Purpose、Ownership、Local Contracts、Work Guidance、Verification、Child DOX Index。逐节解读如下。2.1 Purpose目录的职责边界负责维护者脚本与自动化脚本且这些脚本不放在 GitHub 工作流目录内即不属于.github/workflows/下的 YAML要求脚本确定性、被邻近调用方文档化、在干净检出中安全运行。这里的确定性deterministic是一个关键工程约束同一输入必须产生同一输出脚本不能被本机环境、时间、网络抖动等因素隐性影响否则 CI 行为将不可复现。2.2 Ownership所有权声明openrouter_release_notes_system_prompt.md由.github/scripts/docker_release_plan.py消费不属于运行时应用代码runtime application code的仓库维护脚本都应当放在这里。也就是说scripts/与helpers/后端运行时共享工具有明确分工scripts/服务仓库工程本身发布、维护、CI 辅助helpers/服务应用运行逻辑。2.3 Local Contracts本地契约绝不提交密钥secrets、生成的凭据、私有发布说明或本机机器路径供 CI 使用的脚本必须有稳定输入且失败时输出可操作的错误信息actionable errors脚本行为必须与.github/AGENTS.md、工作流 YAML 以及测试保持同步。这些契约直接体现在底层脚本中docker_release_plan.py的require_env().github/scripts/docker_release_plan.py在关键环境变量缺失时会fail(fRequired environment variable \{name} is missing.) 并以非零退出码终止正是失败时给出可操作错误的落地实现。2.4 Work Guidance工作指引除非脚本运行期已有可用依赖否则优先使用标准库 Python 或简单 shell 兼容资产保持提示词与自动化输入简洁且受版本控制重命名或移动脚本时必须更新调用方。这条更新调用方的约束与保持与工作流 YAML、测试同步Local Contracts互为表里——docker_release_plan.py被 .github/workflows/docker-publish.yml 的plan、resolve-build、resolve-release三个 job 步骤调用任何路径或命令签名变更都必须同步工作流。2.5 Verification验证要求对任何有测试覆盖的自动化脚本运行针对性测试对发布说明提示词的改动必须检查.github/scripts/docker_release_plan.py中期望的输出格式。针对该提示词的测试正是 tests/test_docker_release_plan.py 中加载整个规划模块的机制它通过importlib.util.spec_from_file_location直接加载.github/scripts/docker_release_plan.pytests/test_docker_release_plan.py再在临时 git 仓库中模拟分支晋升与标签发布场景进行断言。2.6 Child DOX Index当前无子 DOX 文件目录规模小一份契约足以覆盖。三、核心自动化输入发布说明生成提示词scripts/openrouter_release_notes_system_prompt.md 是目录中唯一的非契约文件也是scripts/AGENTS.mdOwnership 段点名消费关系的被消费方。它是一份面向 LLM 的系统提示词完整内容如下You write GitHub release notes for Agent Zero.Produce release-ready Markdown only. Do not add preambles, explanations, code fences, or commentary about the prompt.Requirements:Base the release notes only on the commit headings and descriptions provided by the user.Prefer the most meaningful user-facing changes, important fixes, notable infrastructure or packaging changes, and any clearly stated breaking changes.Skip low-signal churn, duplicate points, and purely procedural wording unless it materially affects users or operators.Group related items when that improves readability, but keep the output concise.Do not invent features, bug fixes, migrations, or breaking notes that are not supported by the commits.Do not mention commit hashes, pull request numbers, authors, files, or internal implementation trivia unless the commit text makes them essential to understanding the release.If the commit list does not justify any meaningful notes, return exactly:No release notes.Preferred format:A short introductory line or heading is allowed but optional.Then use a flat bullet list of the key release points.Add a shortBreaking changessection only when the commit content clearly warrants it.这份提示词的设计要点可以提炼为三条核心约束与scripts/AGENTS.md的简洁、版本控制、确定性精神一脉相承只输出产物不输出过程要求仅生成可直接发布的 Markdown禁止前言、解释、代码围栏或对提示词本身的评论忠于提交禁止臆造发布要点只能基于用户提供的提交标题与描述明确禁止发明不存在的特性、修复、迁移或破坏性变更也不得在无依据时提及提交哈希、PR 编号、作者或文件名空结果协议当提交列表不足以支撑任何有意义的说明时必须精确返回No release notes.——这个字符串在底层脚本中被当作约定的空结果哨兵见下文降级逻辑。四、底层引擎docker_release_plan.py 的三阶段架构发布说明提示词的消费方是 .github/scripts/docker_release_plan.py841 行纯 Python 标准库实现。脚本通过main().github/scripts/docker_release_plan.py暴露三个子命令对应工作流中的三个 job 阶段子命令职责工作流中的使用步骤plan根据事件类型与分支/标签状态规划本次发布候选Candidate 矩阵planjobresolve-build在构建前二次校验目标是否仍符合发布条件解析出要推送的 Docker 标签列表buildjobresolve-release决定是否发布 GitHub Release并生成或降级Release Bodybuildjob镜像推送成功后4.1 配置加载与硬性校验load_config().github/scripts/docker_release_plan.py从环境变量读取全部规划参数并做两层硬校验ALLOWED_BRANCHES不能为空、MAIN_BRANCH必须同时出现在ALLOWED_BRANCHES中。Config数据类.github/scripts/docker_release_plan.py封装了允许分支、主分支、镜像仓库、标签正则、最低版本、事件名、引用名/类型、手动标签、before/after SHA 等全部输入。parse_release_tag().github/scripts/docker_release_plan.py用RELEASE_TAG_REGEX对标签做全匹配fullmatch并把版本解析为(major, minor)元组低于MIN_RELEASE_MAJOR.MIN_RELEASE_MINOR的标签一律视为不可发布。4.2 分支状态收集collect_branch_states().github/scripts/docker_release_plan.py遍历每个允许分支先通过git show-ref确认origin/branch已拉取未拉取直接 fail再用git tag --merged origin/branch收集该分支可达的所有合规标签并按版本排序取最大者为latest_tag。这为后续所有是否该构建的判断提供了分支维度的权威依据。4.3 三种规划模式脚本按事件类型分派到三种规划函数标签推送plan_tag_push当推送事件本身是vX.Y标签时检查该标签是否被某个允许分支可达且是该分支当前最高标签只有main上的最新标签同时发布版本标签与latest分支晋升plan_branch_push.github/scripts/docker_release_plan.py比较before_sha与after_sha上各自的最高可达标签若分支的最高标签因合并/晋升而更新则触发构建这正是 tests/test_docker_release_plan.py 中模拟的v1.7 被 promote 到 testing 与 main场景——testing只发布分支标签publish_versionFalsemain才发布版本标签publish_versionTrue手动分发plan_manual_exact/plan_manual_backfill手动触发时若不指定标签则回填缺失的 Docker Hub 标签通过docker buildx imagetools inspect探测镜像是否已存在若指定标签则精确重建该目标且仅在它仍是main上最高标签时刷新latest与 GitHub Release。resolve_build_command().github/scripts/docker_release_plan.py在构建前对每个候选做二次资格校验标签仍存在、仍可达、仍是最高标签、目标 Docker 标签尚不存在防止规划后、构建前窗口期内的状态变化导致重复推送或推送过期版本。五、工作流集成docker-publish.yml 的触发与变量.github/workflows/docker-publish.yml 是整个发布链路的入口其关键配置如下触发条件onpush到testing、ready、main分支push标签v*workflow_dispatch手动触发带可选输入tag如v1.21用于手动重建。环境变量env变量当前取值含义ALLOWED_BRANCHEStesting ready main允许发布镜像的分支非 main 分支以分支名作为 Docker 标签MAIN_BRANCHmain唯一发布版本标签与 GitHub Release 的分支RELEASE_TAG_REGEX^v([0-9])\.([0-9])$合规发布标签格式MIN_RELEASE_MAJOR/MIN_RELEASE_MINOR1/0最低可发布版本v1.0 起DOCKERFILE_DIR/DOCKERFILE_PATHdocker/run/docker/run/Dockerfile构建上下文与 DockerfileDOCKER_IMAGE_NAMEagent-zero镜像名DOCKER_PLATFORMSlinux/amd64,linux/arm64多架构构建平台密钥与凭据secrets / varsDOCKERHUB_ORG、DOCKERHUB_OAT_TOKENDocker Hub 登录与推送、GITHUB_TOKENGitHub Release 写入、OPENROUTER_API_KEYrelease notes 生成、OPENROUTER_MODEL_NAMEvars指定模型名。这与scripts/AGENTS.md的绝不提交密钥契约直接对应——所有凭据都存放在 GitHub Actions secrets 中。流程骨架planjob 校验 secrets → 检出fetch-depth: 0→ 拉取远程分支与标签 → 运行docker_release_plan.py plan产出矩阵 →buildjob 按矩阵二次resolve-build解析标签 →docker/build-push-actionv6多平台构建推送 → 成功后resolve-release决定是否创建/更新 GitHub Releaseactions/github-scriptv7先查后建make_latest: true。六、发布说明生成链路从提交到 Release BodyRelease Notes 的生成是resolve-release阶段的职责核心链路如下确定对比基准previous_published_release_tag().github/scripts/docker_release_plan.py通过 GitHub Releases API 分页拉取历史发布跳过 draft 与 prerelease筛选出版本低于当前标签且最高的那个作为上一发布标签收集提交collect_release_commits().github/scripts/docker_release_plan.py用git log --reverse --format%s%x1f%b%x1e prev..tag以单元分隔符\x1e/\x1f切分提交标题与描述并先验证上一标签是当前标签的祖先避免范围错乱构造用户消息build_release_notes_user_message().github/scripts/docker_release_plan.py将提交列表格式化为编号条目成为提示词中用户提供的提交标题与描述调用 OpenRoutergenerate_release_body_with_openrouter().github/scripts/docker_release_plan.py读取OPENROUTER_SYSTEM_PROMPT_PATH指向 scripts/openrouter_release_notes_system_prompt.md见 .github/scripts/docker_release_plan.py作为 system 消息提交列表作为 user 消息temperature固定为 0.2 以压制创造性、保证输出稳定性请求头携带HTTP-Referer与X-OpenRouter-Title60 秒超时HTTP 错误与网络错误都会以可读细节直接fail解析与降级从响应choices[0].message.content中提取文本兼容纯字符串与多段 content 数组见extract_openrouter_message_content()空内容兜底为No release notes..github/scripts/docker_release_plan.py。若整个生成过程抛错resolve_release_command().github/scripts/docker_release_plan.py会捕获异常并降级为静态 Release BodyFailed to generate release notes.同时保留previous_release_tag与release_commit_count输出保证发布流程不被单点故障阻断。需要特别注意的是只有main分支且当前标签是该分支最高发布标签时才会走到发布环节其他分支直接输出should_releasefalse与跳过原因——这保证了 Release 只产生于正式发布分支。七、验证与测试守住自动化契约.github/AGENTS.md.github/AGENTS.md与scripts/AGENTS.md共同要求改动 Docker 发布规划或发布工作流行为后运行pytest tests/test_docker_release_plan.py。tests/test_docker_release_plan.py 现有三个测试覆盖了关键行为test_docker_publish_workflow_tracks_branch_promotionstests/test_docker_release_plan.py静态断言工作流 YAML 包含testing/main分支触发、v*标签触发、workflow_dispatch与tag输入、以及BEFORE_SHA/AFTER_SHA的注入表达式防止工作流契约被无意破坏test_plan_branch_push_builds_when_tag_reaches_allowed_branchtests/test_docker_release_plan.py在tmp_path中git init构造真实仓库打v1.6/v1.7标签、模拟 development → testing → main 的晋升合并并通过monkeypatch.setenv注入全部环境变量后调用load_config()与plan_branch_push()断言testing候选为mode push_promoted_tag、publish_version is False而main候选publish_version is True——用端到端方式验证了分支晋升驱动发布的核心逻辑。这种YAML 静态断言 临时 git 仓库行为断言的组合正是scripts/AGENTS.md中同步工作流 YAML 与测试契约的可执行化体现。八、对维护者的实践要点综合scripts/AGENTS.md契约与源码实现可以沉淀出 Agent Zero 脚本治理的四条可复用原则脚本与提示词都进版本控制自动化输入如发布说明提示词与消费它的脚本同仓共存、同 PR 演进杜绝改脚本忘改提示词或反之的脱节确定性优先规划逻辑用可测试的 Python 标准库实现.github/AGENTS.md明确要求用确定性的、可测试的 Python 替代 YAML 中的复杂内联 shell固定temperature用before/after SHA快照做幂等判断失败要响亮且可操作缺失环境变量、缺失远程引用、标签不可达等一切异常都通过fail()给出带具体变量名/引用名的错误并以非零码退出绝不让 CI 静默通过权限最小化与密钥隔离所有凭据走 GitHub Actions secrets/env vars代码库内绝不落盘密钥或本机路径Docker Hub 写入仅发生在计划阶段校验通过之后。对于希望为 Agent Zero 贡献或自托管该发布流水线的开发者建议按此顺序理解代码先读 .github/workflows/docker-publish.yml 把握事件与阶段再读 .github/scripts/docker_release_plan.py 的main()/load_config()与三个规划函数最后以 scripts/openrouter_release_notes_system_prompt.md 为模板理解自动化输入如何被消费并以 tests/test_docker_release_plan.py 为改动后的验证标准。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考