GitHub Agentic Workflows 的智能体工作流规范与维护实证研究

开发者如何编写并维护 GitHub Agentic Workflows（gh-aw）的 Markdown 规范，以及其中写了哪些执行要求与防护，仍缺少实证。

• 场景与重要性：作者认为，智能体工作流把软件开发从单次提示词推进到由智能体自动执行的重复工作。gh-aw 用 Markdown 把自然语言指令与配置结合，再编译成 GitHub Actions。同一工作流会按日程或仓库事件反复调用智能体，不清晰或过时的要求可能影响后续多次运行。
• 现有工作的缺口：作者称，既有研究覆盖 GitHub Actions YAML 维护、CI 失败与恢复，以及智能体上下文和技能文件；GHAW-H 提供了把 gh-aw Markdown 历史与编译后 YAML 快照相连的数据集。作者认为这些工作仍未说明开发者如何维护“指令加执行配置”的 Markdown 源，包括采用后维护如何变化、编辑如何分布在配置与指令之间，以及开发者显式编码了哪些运行要求和防护。
• 核心观察：作者以 dotnet/runtime 的 CI 维护循环为例，指出重复执行同时依赖配置和自然语言指令，指令会随经验修订，而且 Markdown 本身可成为经人工审查的修订对象。作者称该例子不能说明这些现象在仓库间有多常见。
• 本文提出什么：一项关于 gh-aw Markdown 的结构、演化和指令内容的实证研究。作者分析 276 个仓库的 1,248 个文件、20,841 次文件级变更，并对 294 个文件的样本做人工标注，得到 288 组已解析标签。目标是为工作流审查和指令分析工具提供实证基础，并评估 LLM 能否识别指令类型。

• GitHub Actions 与 CI 维护：Kinsman 等与 Decan 等考察 GitHub Actions YAML 工作流的采用与维护；Valenzuela-Toledo 等提供提取构建指标的工具支持；Camilli 等研究微服务 CI 工作流的性能、失败与恢复。作者把这些工作当作仓库自动化维护的既有视角，并在 RQ2 中借鉴与项目代码比较工作流维护的做法。
• 智能体上下文与技能文件：作者引用对 agent context 与 skill 文件的研究，称其刻画了自然语言指导的结构、演化和内容，并把可读性与组织列为编写和维护这类指令时的关切。AGENTS.md 对编码智能体效率影响的研究也被列入相关讨论。
• gh-aw 数据与 CI 中的智能体：作者称 GHAW-H 提供了把 gh-aw Markdown 历史链接到编译 YAML 快照的数据集。另有工作讨论智能体 AI 在持续集成中的可靠性、智能体改动 CI/CD 配置的频率与成功率，以及 LLM 生成 GitHub Actions 配置。
• 基线与数据：本文没有把既有方法当作效果基线。语料来自 GitHub code search 命中的 gh-aw 生成 YAML，再映射到 Markdown；指令分类以两名作者解析后的人工标签为参照，LLM 分类与该标签集比较。

作者把本文定位为：在上述基础上，专门刻画开发者如何规定、维护和跨项目复用同时包含智能体指令与执行配置的 gh-aw Markdown。

作者对 gh-aw Markdown 做仓库挖掘：先定位编译产物再回溯源文件，然后分别回答结构、维护、指令类型和 LLM 标注四个研究问题。

问题设定与语料

• 对象：gh-aw 的源不是手写 Actions YAML。开发者通常在 .github/workflows/ 写 Markdown：YAML frontmatter 规定触发器、权限、模型或引擎、工具访问；正文描述任务、上下文、步骤和期望输出。编译器把它变成可由 GitHub 事件、日程或手动触发的 Actions 工作流。
• 检索：用 GitHub REST API code search，查询自动生成标记、路径 .github/workflows 和 yml 扩展名。单次查询最多 1,000 条，作者按文件大小分桶并继续拆分超过上限的桶，去重后得到 1,528 个仓库的 4,533 个生成 YAML。保留至少 10 star 的仓库后为 365 个仓库、1,435 个 YAML。
• 映射与清洗：优先用 YAML 源注释定位 Markdown；没有注释时把文件名后缀换成 .md。跨仓库引用同一 Markdown 时按仓库和路径去重。得到 281 个仓库的 1,295 个 Markdown。再去掉 29 个空正文和 18 个 langdetect 判定为非英语的文件，留下 276 个仓库的 1,248 个文件、7,446 个提交和 20,841 次文件级变更。提交历史跨度见 Table I：2025-07-31 至 2026-08-04。

结构与维护度量

• RQ1：对 1,248 个最新快照统计正文字数与行数、frontmatter 行数、代码块行数、H1–H6 标题，以及句子数、音节数和 Flesch Reading Ease。FRE 作用在完整 Markdown 正文，包含标题、表格、代码和模板表达式。词云去掉英语停用词和独立数字。
• RQ2：取首次与末次变更至少相隔 120 天的 43 个仓库、348 个文件，跟踪前四个月。Day 0 对文件是该路径首次出现，对项目是最早一份被收集 Markdown 的出现日。维护提交排除初始提交；无变更的月份仍保留。churn 为每月增删行数除以该月平均 Markdown 规模后再按每 100 行计。项目把文件规模和 churn 相加，但每个提交只计一次。维护提交占当月全部仓库提交的比例用 GitHub commits API 作分母。
• 检验：每个月与前一个月做项目配对 sign test，12 次比较用 Holm 校正。变更位置按“每个提交–Markdown 文件”计一次；同时改 frontmatter 和正文的事件计入两边。

指令分类法

• 抽样：用 Cochran 公式加有限总体校正，95% 置信、5% 误差、p=0.5，从 1,248 个文件抽出 294 个。只编码固定最新快照的 Markdown 正文，不展开 import，也不从 frontmatter 推断指令。多标签。
• 主题分析四步：两名作者先共同读 30 个文件校准，再独立标注；比较并合并重叠概念，例如把 Expert Role 与 Role Scope 并成 Role Assignment；最后按目的归成主题。解析前二分类文件–标签一致性为 83.61%（κ=0.61）。分歧经讨论得到完全一致的编码。流行度以解析后标签计算，每个文件每个标签只计一次，并排除 Cannot Label。
• 十类：TASK、OUTPUT、CONSTRAINT、PROCESS、RESOURCE、CONTEXT、EVALUATION、EXAMPLE、COMMUNICATION、SAFETY，共 42 个子类。分母为 288 个有解析语义标签的文件，294 个样本中 6 个为 Cannot Label。

LLM 标注与成功判定

• RQ4：作者评估 LLM 能否按该分类法给文件打多标签，以支持规模化指令分析。对照标准是解析后的人工标签。论文报告的分类器包括 Gemini 3.1 Pro、GLM-5.2 和 gpt-oss。指标为相对已解析人工标签的 F1 与 Cohen’s κ。作者称 κ=0.715 属于 substantial agreement。
• 本文不定义攻击是否成功：这是仓库挖掘与内容分析。安全相关内容只作为指令子类出现，例如 Execution Isolation、Prompt Injection Defense、Information Confidentiality 和 Vulnerability Handling，由人工判断正文是否涉及这些要求。

实验设置

• 语料：1,248 个 gh-aw Markdown，276 个仓库；7,446 个至少改动一个 Markdown 的提交；20,841 次文件级变更（Table I）。历史跨度 2025-07-31 至 2026-08-04。
• 维护子集：348 个文件、43 个仓库，每个文件首次与末次观测变更至少相隔 120 天。变更位置分析覆盖 8,575 次变更。
• 指令样本：294 个文件；6 个 Cannot Label 排除后，流行度分母为 288。两名作者解析前一致性 83.61%（κ=0.61）。
• 结构指标：正文/frontmatter/代码块行数、标题层级、词数、句子、音节、象形符号、Flesch Reading Ease（Table II）。标题词频见 Figure 4 的文字说明。
• 维护指标：每月维护提交数、月末规模、每 100 行 churn、维护提交占仓库提交比例；项目配对 sign test，Holm 校正，显著性阈值 p<0.05（Figure 6 注）。
• 分类模型与指标：Gemini 3.1 Pro、GLM-5.2、gpt-oss；相对已解析人工标签的 F1 与 Cohen’s κ。论文未在可见正文中给出各模型分开的完整分数表，也未报告温度、重复次数或与人工的逐类混淆矩阵。

主结果

据摘要、Table II、Table III 与 Figure 5–7 的中位数标注：

表格较宽，可左右滑动

指标	条件	数值	出处
正文词数中位数	1,248 个文件	556.5	Table II
含代码块的文件	1,248 个文件	62.1%	RQ1 正文
FRE 中位数	完整 Markdown 正文	38.8	Table II
第 4 个月仍更新	至少 120 天活动的文件	78.2%	摘要
触及 frontmatter / 正文	项目级中位数	74.5% / 50.0%	Figure 7
Prompt Injection Defense	288 个已解析文件	9.4%	Table III
LLM F1 / κ	相对已解析人工标签	0.818 / 0.715	摘要

• 结构：作者报告标题数中位 9，H2 与 H3 占全部标题 85.5%，每文件中位分别为 4 和 3。step、issue、phase 分别出现在 31.3%、28.4%、11.7% 的文件标题中。模板表达式出现在 60.4% 的文件，象形符号出现在 47.4%。作者认为这些分数落在 FRE 的 conventional difficult 区间，并称代码、模板和符号可能影响 FRE 所用的词数与句子数，分数本身并不能确立开发者很少需要阅读这些文件。
• 维护：作者报告，项目级 Markdown 总行数中位数从第 1 个月的 395 行升至第 2、3、4 个月的 429、430、467 行；第 1 到第 2 个月、第 3 到第 4 个月 Holm 调整后 p<0.001，第 2 到第 3 个月调整后 p=0.511。文件级规模中位数在四个月中保持在约 200 行（Figure 5 标注 201、206.5、203、201.5）。作者认为总规模上升可能来自新增工作流，但中位数本身不能确定增长来源。
• 指令：作者报告 TASK 97.6%、OUTPUT 95.8%、CONSTRAINT 93.8%、PROCESS 93.4%、RESOURCE 89.9%、CONTEXT 84.7%、EVALUATION 70.1%、EXAMPLE 68.1%、COMMUNICATION 63.9%、SAFETY 25.0%（Table III，分母 288）。子类最高的是 Required Sequence 88.2% 和 Decision Branch 87.2%。SAFETY 是最少的大类；其下 Prompt Injection Defense 为 9.4%，Information Confidentiality 为 7.3%，Vulnerability Handling 为 6.3%。

维护的节奏与改动位置

• churn：项目级中位数从第 1 个月每 100 行 31.2 行降到第 2 个月 5.6 行（调整后 p=0.011），其后相邻月份无统计上显著的差异。文件级中位数从 21.3 降到约 3–3.8（Figure 5）。作者认为早期修订更多，之后相对规模的编辑减少。
• 占仓库提交的比例：Figure 6(b) 中位数约为 2.4%、3.2%、2.5%、1.8%。作者报告所有相邻月份调整后 p≥0.561，称早期 churn 下降不应被当作“维护独立于项目整体活动而下降”的证据。
• 改哪里：在 8,575 次变更中，44.8% 只改 frontmatter，37.8% 只改正文，17.3% 两者都改，0.1% 无内容变化或位置未知。只改 frontmatter 的份额在第 1 至第 4 个月分别为 36.7%、29.9%、54.5%、71.7%。作者给出一种可能解释：日程、权限和工具访问等执行设置可能在任务不变时仍需调整。这是作者的解释，不是检验结果。

指令子类与 LLM 分类

• 高频子类：Scope Boundary 76.7%，Quality Standard 74.7%，Repository Context 70.1%，Output Template 61.1%，GitHub Interface 60.4%，Local Workspace 57.6%，Control Signal 52.1%，Evidence Investigation 51.7%（Table III）。
• 低频子类：Work Delegation 9.0%，Historical Context 8.3%，Evidence Credibility 11.1%，Execution Isolation 13.9%，Standalone Artifact 13.9%，Web Retrieval 14.2%。作者据此建议开发者在适用处考虑 prompt-injection 防御、资源预算和证据可信度检查；Resource Budget 的流行度为 38.2%，Evidence Credibility 为 11.1%。
• LLM：作者报告整体 F1=0.818、κ=0.715。解析前人工一致性为 κ=0.61。论文未在所附正文的完整表格中给出三个模型各自的 F1，因此这里不拆开填写。

其他消融与分析

• 复用：365 个有生成 YAML 的项目中，108 个（29.6%）至少有一个工作流引用其他仓库的 Markdown。
• FRE 对照只作语境：作者引用需求/用户故事均值 29.5–41.1、SE 摘要约 14–21、ChatGPT 回复中位 56.9、开发者提示词中位 68.8，并称这不是直接排名。
• 正文行数中位 104、frontmatter 中位 58、代码块行中位 5.5；正文词数最大 10,551，FRE 最小 -555.6、最大 84.8（Table II）。
• 象形符号均值 4.4、中位 0、最大 171；作者举 smoke-proxy 测试工作流用 171 个符号表示测试结果。
• 文件级维护提交中位数在 Figure 5 中为第 1 个月 5、其后 3、2、2。
• 论文未报告按编程语言、工作流用途或 star 数分层的流行度。

作者指出的局限与后续方向

• 源与引用：作者在研究设计中说明，编码不展开 import，也不从 YAML frontmatter 推断指令。因此共享指导和外部引用文件中的要求不进入标签。这限制了“文件里写了什么”对“运行时智能体实际看到什么”的覆盖。
• 样本与语言：非英语正文被移除 18 个；短文本或语言不确定的正文在非空时保留。作者未把这一过滤写成对结论的外推限制，但语料定义本身只保留 langdetect 未判为非英语的正文。
• 维护窗口：RQ2 只跟踪有至少 120 天观测活动的文件的前四个月，后进入的文件也计入项目合计。作者明确说，文件级面板与项目合计的口径不同，中位数不能单独确定规模增长来自扩写还是新增文件。
• 分类器用途：作者把 LLM 的 F1 和 κ 解释为与已解析人工标签有 substantial agreement，并称可用于规模化指令分析。作者同时把结果表述为 suggest，建议实践者考虑补充 prompt-injection 防御、资源预算和证据可信度检查，而不是声称这些缺失已经造成事故。
• 复制：作者计划通过 replication package 提供数据集、脚本、标注材料和实验，供后续复制和扩展。论文正文把这一点写成提供材料，而不是已经完成的下游工具评估。
• 论文未在所附正文的 Limitations 专节中逐条列出更多局限；上面各条对应 Study Design、Results 中作者自己标出的口径边界，以及摘要里的建议语气。

实验覆盖范围

• 仓库与文件：星标筛选后映射并清洗为 276 个仓库、1,248 个 Markdown；起点是 1,528 个仓库的 4,533 个生成 YAML，≥10 star 后为 365 个仓库、1,435 个 YAML（Section III-A、Table I）。
• 维护：43 个仓库、348 个文件、四个月；检验为 12 次项目配对 sign test 加 Holm 校正；位置统计为 8,575 次变更（RQ2）。
• 标注：294 个文件、两名作者、多标签；分母 288；十大类 42 子类（Section III-D、Table III）。
• 分类模型：论文写明 Gemini 3.1 Pro、GLM-5.2、gpt-oss，并给出合并后的 F1 与 κ。论文未报告每次调用的温度、重复次数，以及三个模型各自的分数。
• 未量化的量：论文未报告攻击或防御实验，也未报告这些指令在后续运行中是否被遵守。29.6% 的跨仓库引用只作为复用事实，没有单独跟踪上游变更被下游重新编译的比例。

这是一项对 GitHub Agentic Workflows Markdown 的仓库挖掘，目标是描述开发者如何规定并维护会反复执行的智能体工作。

• 问题：gh-aw 把触发器、权限、工具访问和自然语言任务写进同一 Markdown，再编译成 GitHub Actions。指令会反复生效，但开发者实际写了多长、如何改、写了哪些防护，此前缺少跨仓库证据。
• 做法：从带自动生成标记的 YAML 回溯 Markdown，清洗后分析 276 个仓库的 1,248 个文件和 20,841 次文件级变更。对至少观察 120 天的 348 个文件做四个月维护对比，并对 294 个文件做多标签主题分析。
• 结构：正文词数中位 556.5，62.1% 含代码块，60.4% 含模板表达式；FRE 中位 38.8。标题中位 9 个，H2 与 H3 占 85.5%。
• 维护：摘要称，至少 120 天活动的文件中 78.2% 在第 4 个月仍被更新。项目级规模归一化 churn 中位数从第 1 个月的 31.2 行/100 行降到第 2 个月的 5.6，之后相邻月份没有显著变化。维护占仓库提交的比例没有显著的逐月变化。项目级中位数上，74.5% 的维护变更触及 frontmatter，50.0% 触及正文。
• 指令与分类：在 288 个已解析文件中，TASK、OUTPUT、CONSTRAINT、PROCESS 均超过 93%。SAFETY 为 25.0%，其中 Prompt Injection Defense 为 9.4%。LLM 相对人工解析标签的 F1 为 0.818，κ 为 0.715。作者建议在适用处考虑补上注入防护、资源预算和证据可信度检查，并考虑被复制或引用的工作流仍会继续演化。