结合已完成的源码级调研直接输出文章【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3sK3s 本地 Agentic 工作流实战基于 .agents/AGENTS.md 的 Dependabot Action SHA 回移植全流程解析导读本文以 K3s 仓库根目录下的 .agents/AGENTS.md 为骨架完整讲解该仓库「本地 Agentic 工作流Local Agentic Workflows」的目录契约与索引机制并深入剖析其核心工作流 dependabot_backports将 GitHub Actions 的 SHA 固定版本更新从main分支回移植到三个最新的release-1.XX分支。读完本文你将掌握该工作流的每一步可执行命令、约束条件、PR 规范与成功标准并能结合 .github/dependabot.yml、.github/workflows/actionlint.yaml 等仓库证据理解 K3s 如何将「AI 辅助维护」与「人为审查合并」相结合实现可控、可审计、最小化的供应链依赖更新。一、AGENTS.md本地 Agentic 工作流的索引与契约1.1 文件定位与 frontmatter 语义AGENTS.md位于 K3s 仓库的.agents/目录其 YAML frontmatter 声明了自身的元信息是各类本地 Agentic 工具如 VSCode Copilot、Claude Code、Opencode 等识别与调度工作流的入口字段取值含义nameK3s Local Agentic Workflows Index工作流索引的名称descriptionUse when: browsing or selecting local k3s agentic workflows...触发该索引的适用场景typeindex文件类型为索引而非具体工作流user-invocablefalse索引本身不可由用户直接调用1.2 设计哲学绑定个人 fork 而非通用助手AGENTS.md 明确阐述了这套机制的核心理念每个工作流文件夹会被整体作为输入传给本地 Agentic 工具。这是一种「平衡式」的 Agentic 工作流方案——既能实现快速自动化又保证所有工作都绑定到单个开发者及其个人 fork而不是一个无法问责的通用 Copilot 实例。开发者负责确保工作流正确完成、变更被妥善审查与合并所有工作流的产出必须是以 PR 或代码变更的形式经 k3s-io 维护者审查合并绝不直接提交到main或 release 分支。1.3 工作流文件夹契约每个工作流文件夹必须遵循必需一个工作流 Markdown 文件通常以文件夹名命名可选scripts子目录存放跨多次运行复用的辅助脚本可选面向维护者的 readme 或模板产物。而每个工作流 Markdown 文件内部必须包含YAML frontmatter字段为name、description、type、tools、output、user-invocable固定顺序的章节标题Overview、Required Outcome、Available Tools、Known Issues、Steps、Constraints、Success Criteria。这种强约束的目录契约保证了不同工具Copilot / Claude Code / Opencode 等之间的交叉兼容性cross-tool compatibility是「契约驱动 Agent 开发」的典型落地。二、核心工作流Dependabot Action SHA Backports当前索引中登记的工作流为dependabot_backports其定义文件是 .agents/dependabot_backports/dependabot_backports.md。它的 frontmatter 如下name: Dependabot Action SHA Backports description: Use when: backporting GitHub Action SHA pin updates from main into release branches. Creates at most one PR per target release branch with minimal workflow pin updates only. type: workflow tools: [gh, git, yamllint, bash, python] output: pull-request user-invocable: true核心任务一句话概括将main分支上 GitHub Actions 的 SHA 固定SHA pin更新回移植到三个最新的release-1.XX分支。2.1 为什么需要 SHA 固定与回移植供应链安全supply chain security要求 CI 工作流中的第三方 Action 应固定到完整 40 位十六进制提交 SHA而非浮动的 tag如v7。仓库中的工作流正是这样实践的例如 .github/workflows/actionlint.yaml- name: Checkout code uses: actions/checkout9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: actionlint uses: raven-actions/actionlint3d39aea434753780c3b3d4a1a31c854b4dbf49d7 # v2这种「完整 SHA 注释保留 tag」的写法在 .github/workflows/airgap.yaml、.github/workflows/build-k3s.yaml、.github/workflows/codeql.yml 等文件中随处可见。Dependabot 每月自动对这类依赖发起升级 PR详见下文仓库证据而 release 分支需要同步这些安全更新——这正是本工作流存在的意义把main上的 SHA 升级以最小、可审计的方式同步到仍在维护的 release 分支。2.2 Required Outcome预期产出每个目标 release 分支最多创建一个 PR每个 PR 必须包含该分支所需的全部相关回移植而非零散提交。2.3 Available Tools可用工具工具用途ghGitHub CLI分支、提交与 PR 操作git本地仓库操作git 类操作用 bash 优先yamllint变更后校验 YAML 合法性bash基础脚本尤其用于 git 操作python高级脚本需求同时要求优先复用本文件夹中已存在的脚本也可按需更新或新建脚本。2.4 Known Issues已知问题工作流明确记录了两个高频坑.agents目录在较旧的 release 分支中可能不存在——不要因此丢失该文件夹若不存在按需创建它来存放回移植所需的脚本与文件合并提交可能破坏 YAML 的空格/缩进——应用完所有提交后必须用yamllint复核 YAML 仍合法。三、逐步执行从同步仓库到开 PR3.1 准备同步仓库并圈定目标分支确保本地仓库与main及所有release-1.XX分支的最新状态同步识别所有匹配release-1.XX的远程分支解析数字后缀选取版本号最高的三个例如当前为release-1.34、release-1.33、release-1.32。3.2 分析比对 main 与各 release 分支的 SHA 差异读取main上所有.github/workflows/*.{yml,yaml}文件提取固定到完整 SHA 的 Action 引用形如uses: owner/repo40-hex对每个目标 release 分支执行同样的提取并与main比对构建该分支缺失的 Action SHA 更新集合在main上找到对应的 Dependabot 提交优先选择dependabot[bot]署名的提交只纳入触碰 workflow 文件、且与缺失 SHA 固定相关的提交确保所有提交均以-S签名以满足 DCO 要求详见下文。3.3 实施cherry-pick 与手工修复为每个目标分支准备一个更新分支从目标 release 分支切出新分支命名为dependabot-backports/release-1.XX跟踪origin并在就绪后推送例如git push -u origin dependabot-backports/release-1.34优先按时间顺序 cherry-pick 匹配的 Dependabot 提交若 cherry-pick 无法干净应用则手工只应用必要的uses:SHA 固定变更使该分支与main一致。3.4 交付为每个分支创建唯一的 PR使用gh的create-pull-request为每个目标分支开一个 PRBase 分支目标release-1.XX分支目标分支遵循dependabot-backports/release-1.XX命名约定标题[branch] Backport GitHub Action SHA pin updates from main正文必须包含更新的 Action 列表、旧/新 SHA 对照、源 Dependabot 提交链接以及一个名为AI Disclosure的章节声明该 PR 由哪个 AI 工具生成。跳过已与main在相关 SHA 固定上完全一致的分支不为其创建 PR若同一目标分支与用途已存在打开的 PR则更新而非新建——这需要对现有 PR 分支基于最新的release-1.XX做 force rebase并重新应用必要的提交或变更。四、约束与成功标准4.1 Constraints约束只修改workflow 中的 Action SHA 固定引用不得改变超出 SHA 回移植所需的 workflow 逻辑创建或更新 PR 分支时只推送/跟踪origin严禁直接推送到任何release-1.XX分支保持 PR 聚焦且最小化。4.2 Success Criteria成功标准三个最新的 release 分支各自要么有一个回移植 PR要么明确跳过因已与main一致任何打开的 PR 都包含该目标分支所需的全部相关 Action SHA 固定更新任何打开的 PR 都声明其由 AI 辅助创建并注明使用的 AI 工具变更后 workflow YAML 依然合法除必需的 SHA 更新外不引入任何 workflow 逻辑变更。五、仓库配套证据让工作流有据可依5.1 Dependabot 配置升级从何而来.github/dependabot.yml 中的github-actionsecosystem 配置是回移植需求的源头- package-ecosystem: github-actions directory: / labels: - kind/dependabot reviewers: - k3s-io/k3s-dev schedule: interval: cron cronjob: 0 0 12 * * # Every 12th of the month, generally before releases groups: action-deps: patterns: - * ignore: - dependency-name: * update-types: - version-update:semver-patch可以解读出Action 依赖每月 12 号统一升级一般赶在发布之前、打kind/dependabot标签、由k3s-io/k3s-dev团队审查、所有 Action 归入action-deps组批量更新、忽略 semver-patch 级别更新。这正是main上 Dependabot 提交的生成机制。5.2 DCO 与 PR 规范工作流要求所有提交以-S签名满足 DCO。仓库根目录的 DCO 文件是 Linux 基金会的 Developer Certificate of Origin 1.1开发者原创性证明.github/dco.yml 设置了require: members: false即非成员提交同样必须通过 DCO 检查。而 .github/PULL_REQUEST_TEMPLATE.md 规定了 PR 应包含 Proposed Changes、Verification、Testing、Linked Issues、release-note 等章节与工作流要求的 PR 正文要素旧/新 SHA、源提交链接、AI Disclosure互相呼应。5.3 质量防线工作流用yamllint校验 YAML仓库的 .github/workflows/actionlint.yaml 则在 PR 触碰.github/workflows/*时自动运行raven-actions/actionlint作为另一道独立的质量防线。六、实践启示AI 辅助维护的「人机协作」模板从源码结构看这套.agents/机制本身就是 K3s 维护流程的一部分类型为indexuser-invocable: false说明它面向工具消费而非用户调用。它给出了一套可复制的模式契约先行用统一 frontmatter 与固定章节顺序约束每个工作流保证跨工具兼容最小变更约束条件明确「只改 SHA 固定、不改逻辑、每分支至多一个 PR」防止 AI 越权扩大变更面强制人工兜底产出必须是 PR且须经 k3s-io 维护者审查合并杜绝直接提交 release 分支全程可审计强制 AI Disclosure 声明、DCO 签名、源提交链接与旧/新 SHA 对照让 AI 参与的变更完全可追溯错误预案Known Issues 章节显式登记「目录在旧分支缺失」「YAML 缩进被合并破坏」等已知坑降低自动化失败概率。对于任何希望在开源仓库中安全引入 AI 辅助维护的团队这套「索引 契约 工作流 成功标准」的本地 Agentic 工作流设计都是一份可以直接借鉴的实战模板。【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
结合已完成的源码级调研，直接输出文章
结合已完成的源码级调研直接输出文章【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3sK3s 本地 Agentic 工作流实战基于 .agents/AGENTS.md 的 Dependabot Action SHA 回移植全流程解析导读本文以 K3s 仓库根目录下的 .agents/AGENTS.md 为骨架完整讲解该仓库「本地 Agentic 工作流Local Agentic Workflows」的目录契约与索引机制并深入剖析其核心工作流 dependabot_backports将 GitHub Actions 的 SHA 固定版本更新从main分支回移植到三个最新的release-1.XX分支。读完本文你将掌握该工作流的每一步可执行命令、约束条件、PR 规范与成功标准并能结合 .github/dependabot.yml、.github/workflows/actionlint.yaml 等仓库证据理解 K3s 如何将「AI 辅助维护」与「人为审查合并」相结合实现可控、可审计、最小化的供应链依赖更新。一、AGENTS.md本地 Agentic 工作流的索引与契约1.1 文件定位与 frontmatter 语义AGENTS.md位于 K3s 仓库的.agents/目录其 YAML frontmatter 声明了自身的元信息是各类本地 Agentic 工具如 VSCode Copilot、Claude Code、Opencode 等识别与调度工作流的入口字段取值含义nameK3s Local Agentic Workflows Index工作流索引的名称descriptionUse when: browsing or selecting local k3s agentic workflows...触发该索引的适用场景typeindex文件类型为索引而非具体工作流user-invocablefalse索引本身不可由用户直接调用1.2 设计哲学绑定个人 fork 而非通用助手AGENTS.md 明确阐述了这套机制的核心理念每个工作流文件夹会被整体作为输入传给本地 Agentic 工具。这是一种「平衡式」的 Agentic 工作流方案——既能实现快速自动化又保证所有工作都绑定到单个开发者及其个人 fork而不是一个无法问责的通用 Copilot 实例。开发者负责确保工作流正确完成、变更被妥善审查与合并所有工作流的产出必须是以 PR 或代码变更的形式经 k3s-io 维护者审查合并绝不直接提交到main或 release 分支。1.3 工作流文件夹契约每个工作流文件夹必须遵循必需一个工作流 Markdown 文件通常以文件夹名命名可选scripts子目录存放跨多次运行复用的辅助脚本可选面向维护者的 readme 或模板产物。而每个工作流 Markdown 文件内部必须包含YAML frontmatter字段为name、description、type、tools、output、user-invocable固定顺序的章节标题Overview、Required Outcome、Available Tools、Known Issues、Steps、Constraints、Success Criteria。这种强约束的目录契约保证了不同工具Copilot / Claude Code / Opencode 等之间的交叉兼容性cross-tool compatibility是「契约驱动 Agent 开发」的典型落地。二、核心工作流Dependabot Action SHA Backports当前索引中登记的工作流为dependabot_backports其定义文件是 .agents/dependabot_backports/dependabot_backports.md。它的 frontmatter 如下name: Dependabot Action SHA Backports description: Use when: backporting GitHub Action SHA pin updates from main into release branches. Creates at most one PR per target release branch with minimal workflow pin updates only. type: workflow tools: [gh, git, yamllint, bash, python] output: pull-request user-invocable: true核心任务一句话概括将main分支上 GitHub Actions 的 SHA 固定SHA pin更新回移植到三个最新的release-1.XX分支。2.1 为什么需要 SHA 固定与回移植供应链安全supply chain security要求 CI 工作流中的第三方 Action 应固定到完整 40 位十六进制提交 SHA而非浮动的 tag如v7。仓库中的工作流正是这样实践的例如 .github/workflows/actionlint.yaml- name: Checkout code uses: actions/checkout9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: actionlint uses: raven-actions/actionlint3d39aea434753780c3b3d4a1a31c854b4dbf49d7 # v2这种「完整 SHA 注释保留 tag」的写法在 .github/workflows/airgap.yaml、.github/workflows/build-k3s.yaml、.github/workflows/codeql.yml 等文件中随处可见。Dependabot 每月自动对这类依赖发起升级 PR详见下文仓库证据而 release 分支需要同步这些安全更新——这正是本工作流存在的意义把main上的 SHA 升级以最小、可审计的方式同步到仍在维护的 release 分支。2.2 Required Outcome预期产出每个目标 release 分支最多创建一个 PR每个 PR 必须包含该分支所需的全部相关回移植而非零散提交。2.3 Available Tools可用工具工具用途ghGitHub CLI分支、提交与 PR 操作git本地仓库操作git 类操作用 bash 优先yamllint变更后校验 YAML 合法性bash基础脚本尤其用于 git 操作python高级脚本需求同时要求优先复用本文件夹中已存在的脚本也可按需更新或新建脚本。2.4 Known Issues已知问题工作流明确记录了两个高频坑.agents目录在较旧的 release 分支中可能不存在——不要因此丢失该文件夹若不存在按需创建它来存放回移植所需的脚本与文件合并提交可能破坏 YAML 的空格/缩进——应用完所有提交后必须用yamllint复核 YAML 仍合法。三、逐步执行从同步仓库到开 PR3.1 准备同步仓库并圈定目标分支确保本地仓库与main及所有release-1.XX分支的最新状态同步识别所有匹配release-1.XX的远程分支解析数字后缀选取版本号最高的三个例如当前为release-1.34、release-1.33、release-1.32。3.2 分析比对 main 与各 release 分支的 SHA 差异读取main上所有.github/workflows/*.{yml,yaml}文件提取固定到完整 SHA 的 Action 引用形如uses: owner/repo40-hex对每个目标 release 分支执行同样的提取并与main比对构建该分支缺失的 Action SHA 更新集合在main上找到对应的 Dependabot 提交优先选择dependabot[bot]署名的提交只纳入触碰 workflow 文件、且与缺失 SHA 固定相关的提交确保所有提交均以-S签名以满足 DCO 要求详见下文。3.3 实施cherry-pick 与手工修复为每个目标分支准备一个更新分支从目标 release 分支切出新分支命名为dependabot-backports/release-1.XX跟踪origin并在就绪后推送例如git push -u origin dependabot-backports/release-1.34优先按时间顺序 cherry-pick 匹配的 Dependabot 提交若 cherry-pick 无法干净应用则手工只应用必要的uses:SHA 固定变更使该分支与main一致。3.4 交付为每个分支创建唯一的 PR使用gh的create-pull-request为每个目标分支开一个 PRBase 分支目标release-1.XX分支目标分支遵循dependabot-backports/release-1.XX命名约定标题[branch] Backport GitHub Action SHA pin updates from main正文必须包含更新的 Action 列表、旧/新 SHA 对照、源 Dependabot 提交链接以及一个名为AI Disclosure的章节声明该 PR 由哪个 AI 工具生成。跳过已与main在相关 SHA 固定上完全一致的分支不为其创建 PR若同一目标分支与用途已存在打开的 PR则更新而非新建——这需要对现有 PR 分支基于最新的release-1.XX做 force rebase并重新应用必要的提交或变更。四、约束与成功标准4.1 Constraints约束只修改workflow 中的 Action SHA 固定引用不得改变超出 SHA 回移植所需的 workflow 逻辑创建或更新 PR 分支时只推送/跟踪origin严禁直接推送到任何release-1.XX分支保持 PR 聚焦且最小化。4.2 Success Criteria成功标准三个最新的 release 分支各自要么有一个回移植 PR要么明确跳过因已与main一致任何打开的 PR 都包含该目标分支所需的全部相关 Action SHA 固定更新任何打开的 PR 都声明其由 AI 辅助创建并注明使用的 AI 工具变更后 workflow YAML 依然合法除必需的 SHA 更新外不引入任何 workflow 逻辑变更。五、仓库配套证据让工作流有据可依5.1 Dependabot 配置升级从何而来.github/dependabot.yml 中的github-actionsecosystem 配置是回移植需求的源头- package-ecosystem: github-actions directory: / labels: - kind/dependabot reviewers: - k3s-io/k3s-dev schedule: interval: cron cronjob: 0 0 12 * * # Every 12th of the month, generally before releases groups: action-deps: patterns: - * ignore: - dependency-name: * update-types: - version-update:semver-patch可以解读出Action 依赖每月 12 号统一升级一般赶在发布之前、打kind/dependabot标签、由k3s-io/k3s-dev团队审查、所有 Action 归入action-deps组批量更新、忽略 semver-patch 级别更新。这正是main上 Dependabot 提交的生成机制。5.2 DCO 与 PR 规范工作流要求所有提交以-S签名满足 DCO。仓库根目录的 DCO 文件是 Linux 基金会的 Developer Certificate of Origin 1.1开发者原创性证明.github/dco.yml 设置了require: members: false即非成员提交同样必须通过 DCO 检查。而 .github/PULL_REQUEST_TEMPLATE.md 规定了 PR 应包含 Proposed Changes、Verification、Testing、Linked Issues、release-note 等章节与工作流要求的 PR 正文要素旧/新 SHA、源提交链接、AI Disclosure互相呼应。5.3 质量防线工作流用yamllint校验 YAML仓库的 .github/workflows/actionlint.yaml 则在 PR 触碰.github/workflows/*时自动运行raven-actions/actionlint作为另一道独立的质量防线。六、实践启示AI 辅助维护的「人机协作」模板从源码结构看这套.agents/机制本身就是 K3s 维护流程的一部分类型为indexuser-invocable: false说明它面向工具消费而非用户调用。它给出了一套可复制的模式契约先行用统一 frontmatter 与固定章节顺序约束每个工作流保证跨工具兼容最小变更约束条件明确「只改 SHA 固定、不改逻辑、每分支至多一个 PR」防止 AI 越权扩大变更面强制人工兜底产出必须是 PR且须经 k3s-io 维护者审查合并杜绝直接提交 release 分支全程可审计强制 AI Disclosure 声明、DCO 签名、源提交链接与旧/新 SHA 对照让 AI 参与的变更完全可追溯错误预案Known Issues 章节显式登记「目录在旧分支缺失」「YAML 缩进被合并破坏」等已知坑降低自动化失败概率。对于任何希望在开源仓库中安全引入 AI 辅助维护的团队这套「索引 契约 工作流 成功标准」的本地 Agentic 工作流设计都是一份可以直接借鉴的实战模板。【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考