awesome-copilot 的 Agentic Workflows 实战指南：用 Markdown 编排 GitHub 仓库自动化

awesome-copilot 的 Agentic Workflows 实战指南用 Markdown 编排 GitHub 仓库自动化【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读本文以 awesome-copilot 仓库的 docs/README.workflows.md 为骨架系统讲解 Agentic Workflows 的定义、安装激活流程与安全模型并逐一对仓库workflows/目录下的 8 个真实工作流日报、OSPO 系列报告、相关性评估、注释同步等进行源码级拆解。读完本文你将掌握如何编写、编译、运行和贡献这类用自然语言定义、由 Copilot 驱动的 GitHub Actions 自动化并能直接复用本仓库现成的工作流模板。一、什么是 Agentic WorkflowsAgentic Workflows 是AI 驱动的仓库自动化AI-powered repository automations它们以 Markdown 格式定义用自然语言编写指令在 GitHub Actions 中运行编码代理coding agents实现**事件触发event-triggered与定时调度scheduled**的自动化任务并且内置护栏guardrails与安全优先security-first的设计。这一概念在仓库的两处文档中被反复强调docs/README.workflows.md 的引言定义、以 Markdown 自然语言编写、内置护栏与安全优先设计CONTRIBUTING.md 的 Adding Agentic Workflows 章节将其定位为 run coding agents in GitHub Actions同样强调 scheduled and event-triggered automation with built-in guardrails。与传统的 YAML GitHub Actions 不同Agentic Workflows 的可执行逻辑是自然语言指令——代理读取指令后自主决定调用哪些 GitHub API、执行哪些 bash 命令而frontmatter只负责声明触发条件、权限边界与输出约束。二、仓库内置的 8 个工作流一览本仓库的 workflows/ 目录下共收录 8 个可立即使用的工作流覆盖日常维护、OSPO开源项目办公室治理、Issue 管理与文档同步四大场景名称文件功能触发器Daily Issues Reportworkflows/daily-issues-report.md生成每日未解决问题与近期活动摘要为 GitHub IssuescheduleOSPO Contributors Reportworkflows/ospo-contributors-report.md组织范围内仓库的月度贡献者活动指标schedule, workflow_dispatchOSPO Organization Health Reportworkflows/ospo-org-health.md组织每周健康报告过期 Issue/PR、合并耗时、贡献者排行榜与待人工处理项schedule, workflow_dispatchOSPO Stale Repository Reportworkflows/ospo-stale-repos.md识别组织内不活跃仓库并生成归档建议报告schedule, workflow_dispatchOSS Release Compliance Checkerworkflows/ospo-release-compliance-checker.md对照开源发布要求分析目标仓库并以 Issue 评论形式输出合规报告issues, workflow_dispatchRelevance Checkworkflows/relevance-check.md斜杠命令/relevance-check评估 Issue/PR 是否仍与项目相关slash_command, rolesRelevance Summaryworkflows/relevance-summary.md手动触发将带/relevance-check评估结果的开放 Issue/PR 汇总为一个 Issueworkflow_dispatchWeekly Comment Syncworkflows/weekly-comment-sync.md每周查找过期代码注释或 README 片段做纯文本同步更新并在必要时开草稿 PRschedule, workflow_dispatch使用场景提示这些工作流可覆盖 Issue 分诊与打标、每日状态报告、文档自动维护、定时代码质量检查、对 Issue/PR 中的斜杠命令做出响应以及编排多步骤的仓库自动化。三、安装与激活gh aw命令行全流程3.1 安装 CLI 扩展Agentic Workflows 的编译与运行依赖 GitHub 官方的gh aw命令行扩展安装命令为gh extension install github/gh-aw3.2 安装工作流到目标仓库复制文件将工作流.md文件复制到目标仓库的.github/workflows/目录下编译运行gh aw compile生成对应的.lock.yml文件这是真正被 GitHub Actions 执行的编译产物提交将.md与.lock.yml两个文件一并提交git commit。3.3 激活与运行工作流会根据 frontmatter 中声明的触发器自动运行定时任务、仓库事件、斜杠命令手动触发gh aw run workflow;监控运行gh aw status查看运行状态gh aw logs查看运行日志。3.4 本地校验在贡献工作流时可用gh aw compile --validate --no-emit daily-issues-report.md验证文件是否合法见 CONTRIBUTING.md。注意仓库只接受.md源文件拒绝提交编译产物CI 会阻止.lock.yml/.yml文件入库。四、工作流文件结构Frontmatter 声明式配置每个工作流是一个单文件.md顶部是 YAML frontmatter声明式配置正文是自然语言指令代理的执行逻辑。以下结合仓库实际文件拆解关键字段。4.1 基础元信息name/description/labels--- name: OSPO Contributors Report description: Monthly contributor activity metrics across an organizations repositories. labels: [ospo, reporting, contributors] ---name工作流名称description一句话说明会出现在列表与市场中labels可选标记该工作流的主题分类OSPO、reporting、maintenance 等。4.2 触发器on触发器决定工作流何时运行仓库中出现的类型包括schedulecron 或自然语言调度。例如 workflows/ospo-contributors-report.md 使用schedule: cron 3 2 1 * *每月 1 日 02:03workflows/ospo-org-health.md 使用cron 0 10 * * 1每周一 10:00而 workflows/daily-issues-report.md 则直接写自然语言schedule: daily on weekdaysworkflow_dispatch手动触发并可声明inputs见 4.4slash_command斜杠命令触发例如 workflows/relevance-check.md 的slash_command: name: relevance-check配合roles: [admin, maintainer, write]限定可调用角色issues事件触发例如 workflows/ospo-release-compliance-checker.md 的issues: types: [opened, labeled]。4.3 权限与引擎permissions/engine/toolspermissions: contents: read issues: read pull-requests: read engine: copilot tools: github: toolsets: - repos - issues - pull_requests - orgs - users bash: truepermissions遵循最小权限原则least-privilege仓库内所有工作流几乎都是read级别的内容/Issue/PR 读取权限写入动作全部交给safe-outputs统一管控engine: copilot指定运行引擎workflows/ospo-org-health.md 还声明了network: allowed: [defaults, python]限定网络访问范围tools声明代理可用的工具集github.toolsets可精确到 repos / issues / pull_requests / orgs / usersbash: true允许执行 shell 命令报告类工作流用它做日期计算与数据聚合。4.4 手动触发参数workflow_dispatch.inputs以 workflows/ospo-contributors-report.md 为例它声明了 6 个可选输入覆盖了组织/仓库范围、报告周期、赞助信息三个维度输入类型说明默认值organizationstring要分析的 GitHub 组织如github无可选repositoriesstring逗号分隔的仓库列表如owner/repo1,owner/repo2无可选start_date/end_datestring报告周期起止日期YYYY-MM-DD无可选sponsor_infoboolean是否包含贡献者的 GitHub Sponsors 信息falseworkflows/ospo-stale-repos.md 的参数则更强调扫描策略全部带有默认值输入类型默认值说明organizationstringmy-org要扫描的组织inactive_daysnumber365判定仓库失活的天数阈值exempt_reposstring空豁免仓库列表逗号分隔大小写不敏感exempt_topicsstring空带这些 topic 的仓库豁免activity_methodchoicepushed活跃度判定方式pushed用pushed_at或default_branch_updated用默认分支最新提交时间4.5 安全输出护栏safe-outputssafe-outputs是 Agentic Workflows 安全模型的核心——代理不直接获得写入权限而是声明允许产生什么副作用且副作用受数量与格式约束。仓库中出现的模式create-issue创建 Issue常配title-prefix统一标题前缀如[daily-report]、[Contributors Report]、[Org Health]、[Stale Repos]、[Relevance Summary]、labels、max: 1最多创建 1 个、close-older-issues: true关闭旧 Issue见 workflows/relevance-summary.mdadd-comment添加评论如max: 1见 workflows/relevance-check.md 与 workflows/ospo-release-compliance-checker.mdcreate-pull-request创建 PRworkflows/weekly-comment-sync.md 中配置了draft: true草稿 PR、title-prefix: [ai] 、labels: [automation]、if-no-changes: warn无变更时降级为警告、fallback-as-issue: false不降级为 Issue。此外frontmatter 中还常见timeout-minutes运行超时如 Contributors/Org Health 为 60 分钟Compliance Checker 与 Weekly Comment Sync 为 20 分钟Stale Repos 为 30 分钟。五、工作流深度解析一OSPO 治理报告族5.1 OSPO Contributors Report月度贡献者报告workflows/ospo-contributors-report.md 是仓库中步骤最完整的工作流之一共 8 步校验配置organization与repositories至少提供一个定时运行且两者为空时默认分析当前仓库所属组织的全部公开仓库从GITHUB_REPOSITORY环境变量取组织名手动触发且两者为空则报错两者都有时优先repositories确定日期范围未提供start_date/end_date时默认取上一个自然月例如今天是 2025-03-15则范围为 2025-02-01 至 2025-02-28用 bash 计算并存入START_DATE/END_DATE枚举仓库来自输入时按逗号拆分owner/repo格式来自组织时调用 GitHub API 列出公开、未归档、非 fork的仓库收集提交对每个仓库用 commits 端点的since/until参数拉取区间内提交提取author.login排除[bot]后缀或type Bot的机器人账号用 bash 跨仓库聚合去重统计每个贡献者的提交总数与涉及的仓库集合区分新老贡献者若某贡献者在START_DATE之前没有任何区间内仓库的提交则标记为New Contributor否则为 Returning Contributor赞助信息可选sponsor_info: true时查询每个贡献者的 GitHub Sponsors 档案启用则记录https://github.com/sponsors/username生成报告Markdown 结构含摘要表Total/New/Returning Contributors、Total Commits、% New Contributors与按提交数降序的明细表#、Username、Contribution Count、New Contributor、Sponsor URL、Commits 链接创建 Issue在当前仓库创建标题为[Contributors Report] 范围 — START_DATE to END_DATE的 Issue若存在contributors-report标签则打上标签不存在也不报错。5.2 OSPO Organization Health Report组织每周健康报告workflows/ospo-org-health.md 是仓库中体量最大、指标最丰富的工作流核心方法论是先搜索 API 拿组织级聚合再抽样做纵深分析Step 1 参数ORG取自输入PERIOD_DAYS30STALE_ISSUE_DAYS60STALE_PR_DAYS30Step 2 搜索查询矩阵用org:ORG is:issue is:open等 9 条搜索查询一次性拿到开放 Issue/PR 总数、近 30 天新增/关闭/合并等指标。文档明确提示在搜索 API 调用之间加 1~2 秒延迟以避免限流rate limitStep 3 热力排序Heat Score对过期 Issue/PR 各取最多 50 条按评论数comment count降序取前 10——评论多却长期无人跟进的条目最值得维护者优先处理Step 4 合并耗时分析取近 30 天合并的 PR最多 100 条计算merge_time merged_at - created_at小时用内嵌 Python 脚本计算p50 / p75 / p95分位数。工作流正文直接给出了可复用的 bashPython 分位数计算片段n20 时 p95 退化为最大值python3 -c import json, sys times json.loads(sys.stdin.read()) times.sort() n len(times) if n 0: print(No data) else: p50 times[int(n * 0.50)] p75 times[int(n * 0.75)] p95 times[int(n * 0.95)] if n 20 else times[-1] print(fp50{p50:.1f}h, p75{p75:.1f}h, p95{p95:.1f}h) Step 5 首次响应时间抽样近 30 天开放的 Issue/PR 各 50 条找除作者外的首个评论计算first_response_time first_comment.created_at - item.created_at小时分别报告 Issue 与 PR 的中位数Step 6 仓库活跃度与贡献者榜列出所有未归档仓库近 30 天的 push/commit/IssuePR 活动取 Top 10 活跃仓库聚合其提交者取 Top 10前三名授予 同时列出 30 天零活动的不活跃仓库含最后 push 日期供组织决定是否归档Step 7 健康告警红黄绿灯用阈值表给每个指标定级——Issue 关闭率、PR 合并率、合并耗时中位数、首次响应中位数、过期 Issue/PR 数量分别映射 //Step 8 亮点与致谢识别快速合并4 小时的 PR、快速关闭24 小时的 Issue、Top 贡献者、零过期项的仓库Step 9 汇总在组织的.github仓库或最合适的中心仓库创建[Org Health] Weekly Report — DATEIssue正文按 Header → 告警 → 亮点 → 过期 Issue/PR → 合并耗时 → 首次响应 → Top 活跃仓库 → 贡献者榜 → 不活跃仓库 的固定顺序组织全部数据用 Markdown 表格呈现。重要约束报告正文需控制在65,000 字符GitHub Issue 正文上限以内时间一律用小时仅当超过 72 小时才换算成天单个 API 失败不应阻断整个报告而是记录在报告中继续。5.3 OSPO Stale Repository Report失活仓库扫描workflows/ospo-stale-repos.md 专注于找不活跃仓库并给归档建议流程四步枚举仓库列出组织全部仓库跳过已归档仓库、exempt_repos中列出的仓库名称大小写不敏感比较、带exempt_topics任一 topic 的仓库确定最后活动日期activity_methodpushed时用pushed_at默认、最高效default_branch_updated时取默认分支最新提交的committer.date判定失活距今天数超过inactive_days即标记为 stale生成报告Markdown 摘要 表格Repository / Days Inactive / Last Push Date / Visibility按失活天数降序排列即使没有失活仓库也要创建 Issue 并说明所有仓库均活跃。其输出策略值得一提先搜索组织.github仓库或本工作流所在仓库中带stale-repos标签、标题以[Stale Repos]开头的开放 Issue存在则更新正文不存在才新建——避免报告 Issue 无限堆积。5.4 OSS Release Compliance Checker开源发布合规检查workflows/ospo-release-compliance-checker.md 面向准备开源但需要先体检的仓库是仓库中唯一带**触发守卫Trigger Guard**的工作流触发守卫workflow_dispatch或 Issueopened直接放行Issuelabeled仅在新增标签恰为ospo-release-check时放行否则直接停止提取目标仓库从触发 Issue 正文解析https://github.com/org/repo-name或org/repo-name解析不到则评论请作者补充后停止文件合规检查对目标仓库根目录或约定俗成的.github/逐一检查 7 个文件的存在性与内容质量——LICENSE内容须与仓库元数据声明的许可证一致、README.md建议 100 行含 usage/install/contributing 章节、CODEOWNERS至少一名维护者或团队、CONTRIBUTING.md、SUPPORT.md、CODE_OF_CONDUCT.md采用公认的行为准则、SECURITY.md描述漏洞披露流程安全配置检查用 GitHub API 检查 Secret scanning、Dependabot告警与安全更新、Code scanningCodeQL 分析是否存在、Branch protection默认分支是否受保护、是否要求评审/状态检查/签名提交对404/403响应优雅降级处理许可证与法务分析比对LICENSE内容与license.spdx_id元数据是否一致扫描package.json、requirements.txt、go.mod、Cargo.toml、pom.xml、Gemfile、*.csproj等依赖清单重点标记 GPL/AGPL/LGPL 等强 Copyleft 许可证开源发布前需法务评审风险评估对商业风险、法律风险、开源成熟度风险三方面分别给出 Low / Medium / High 评级输出在触发 Issue 上仅发一条评论包含 Header含 PASS ✅ / NEEDS WORK ⚠️ / BLOCKED 总状态、文件合规表、安全配置表、许可证分析、风险评估表、按 Must Fix / Should Address / Nice to Have 分级建议并强调语气要建设性、解释缺失项的原因、肯定团队已做好的部分。六、工作流深度解析二Issue 相关性管理组合6.1 Relevance Check/relevance-check斜杠命令workflows/relevance-check.md 是一个评估器型工作流维护者在 Issue/PR 中敲下/relevance-checkCopilot 代理便执行三步分析并输出结构化结论。frontmatter 关键点slash_command: name: relevance-check、roles: [admin, maintainer, write]限定可调用角色、permissions为三项只读、safe-outputs.add-comment.max: 1整个运行只允许发一条评论。正文通过${{ steps.sanitized.outputs.text }}注入被评估的内容。评估方法论信息收集读取 Issue/PR 的标题、正文、全部评论与关联项检查代码库现状涉及的文件/类/包是否仍存在、问题是否已被解决查看最近提交与 PR查找重复或相关的 Issue相关性评估从五个维度判断——Still applicable?问题对当前代码库是否仍适用、Already resolved?是否在后续提交/PR 中已隐式修复、Superseded?是否被更新的 Issue/PR 取代、Stale context?引用的 API/依赖/架构模式是否已被淘汰、Actionability?信息是否足够可执行输出分析只发一条评论固定结构为**Relevance Assessment: [Still Relevant | Likely Outdated | Needs Discussion]**附 Summary1-2 句结论、Evidence具体证据如Issue 中引用的XYZParser类已在 commit abc1234 中被移除或该功能已在 PR #42 实现、Recommendation✅ Keep open / ️ Consider closing / Needs maintainer input 三选一。该工作流明确禁止修改仓库——唯一的动作就是发评论。6.2 Relevance Summary评估结果汇总workflows/relevance-summary.md 与 Relevance Check 形成组合拳/relevance-check逐条评估产生分散评论本工作流则手动触发将所有开放且收到过 Relevance Assessment 响应的 Issue/PR 汇总为一张表。汇总标准基于特征标记匹配评论中出现 Relevance Assessment: 及三种结论之一、且有Recommendation段落✅ Keep open / ️ Consider closing / Needs maintainer input。汇总 Issue 的正文结构表头为### Relevance Check Summary表格列为# | Type | Title | Assessment | Recommendation标题过长时截断到约 60 字符底部附统计Total evaluated、Still Relevant、Likely Outdated、Needs Discussion 计数。排序策略有讲究Likely Outdated 排最前最可操作然后是 Needs Discussion最后 Still Relevant没有任何被评估项时也创建 Issue 并说明未找到。frontmatter 中safe-outputs.create-issue.close-older-issues: true保证重复生成时旧 Issue 会被关闭。七、工作流深度解析三Weekly Comment Sync 文档同步workflows/weekly-comment-sync.md 是仓库中唯一会修改仓库内容通过 PR的工作流用于治理注释与代码脱节这一经典问题范围只处理源文件注释行内注释、块注释、文档注释与 README 中直接描述当前行为的片段优先处理最近改动过的文件和明显与代码矛盾的注释绝不修改可执行逻辑只更新注释与文档文本验证纪律必须结合仓库历史与当前文件内容双重确认不能因为周边代码被改过就假设注释过期主观性、风格性、技术上仍然正确的注释一律跳过最小化文本编辑只改必须同步的注释/README 文本保留仓库原有语气、格式与文档风格仓库特定维护可选仅在目标仓库流程确实要求时才在同一个 PR 中更新版本清单文件如package.json、pyproject.toml或仓库特定的版本清单**不手动编辑 lockfile 来凑版本号、CHANGELOG.md只加描述本次注释/文档同步的条目保持原有格式不描述未发生的改动输出需要更新时只创建一个草稿 PRdraft: true、title-prefix: [ai] 正文说明改动了哪些文件、每条注释为何过期、做了哪些仓库特定维护无更新时调用noop并给出简短说明正文中给出了 noop JSON 的调用示例而不是强行开 PR。safe-outputs.create-pull-request的if-no-changes: warn与fallback-as-issue: false进一步确保没有实质变化就不产生任何副作用。八、如何贡献自己的工作流依据 CONTRIBUTING.md 的贡献指南新增一个 Agentic Workflows 的标准流程为创建文件在workflows/目录新建.md文件文件名使用小写加连字符如daily-issues-report.md编写 frontmatter必须包含name与description随后是代理工作流专属字段on、permissions、safe-outputs与自然语言指令正文本地校验运行gh aw compile --validate --no-emit file.md验证合法性更新 README运行npm run build刷新 README 中的工作流表格。贡献时的硬性准则CONTRIBUTING.md安全第一使用最小权限least-privilege的permissions与safe-outputs而不是直接写权限指令清晰正文使用清晰的自然语言指令命名规范小写文件名 连字符禁止提交编译产物只提交.md源文件.lock.yml/.yml会被 CI 拦截。九、从仓库实践提炼的最佳实践综合 docs/README.workflows.md 与 8 个工作流的源码可以提炼出编写高质量 Agentic Workflows 的五条通用经验把写权限全部收敛到 safe-outputs无论扫描多少仓库、做多少分析permissions一律只读副作用创建 Issue/PR、发评论全部通过safe-outputs声明并限制数量max: 1与格式title-prefix、labels用搜索 API 拿聚合、用抽样做纵深Org Health 工作流先用 9 条搜索查询一次拿到组织级指标再对过期项/合并 PR 做有限抽样与分位数计算兼顾效率与限流安全为不确定性设计降级路径Stale Repos 的找不到旧 Issue 就新建找到就更新、Compliance Checker 对404/403的优雅处理、Org Health 的单次 API 失败不阻断报告都体现了面向真实 API 不稳定性的工程韧性参数默认值优先、输入校验兜底Stale Repos 的全部输入都带默认值Contributors Report 则对空输入做了定时运行默认全组织 / 手动运行直接报错的分支处理保证工作流在任何触发方式下都有明确行为组合式自动化Relevance Check逐条评估与 Relevance Summary汇总成表是单点命令 周期汇总组合的典型范例值得在同类场景中复制。要亲手体验只需将 workflows/ 下的任一.md复制到目标仓库的.github/workflows/gh aw compile后提交即可——全部工作流均已按 GitHub Agentic Workflows 规范编写开箱即用。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考