github-agentic-workflows

GitHub Agentic Workflows

流程

步骤 1：识别仓库状态

1. 检查工作区中的 .github/workflows/、.github/agents/、现有 .lock.yml 文件，以及任何 gh aw 用法。
2. 如果有 Node 运行时，执行 node skills/github-agentic-workflows/scripts/find-gh-aw-targets.mjs .。
3. 在做出与编译器相关的决策前，运行 gh aw version，确保工作流编写方式与已安装的 CLI 行为一致。
4. 如果仓库中有多个候选工作流，优先选择用户指定的工作流，或与当前 issue、拉取请求或自动化界面最相关的工作流。
5. 如果仓库尚未配置 GH-AW，且任务是创建或维护 Agentic 工作流，请在编辑前阅读 references/authoring.md。
6. 如果任务仅涉及标准的确定性 GitHub Actions YAML，不涉及 Agentic Markdown 工作流，请停止并说明此技能不适用。

步骤 2：选择工作模式

1. 将任务归类为以下模式之一：仓库设置、新建工作流、修改工作流、从其他仓库安装工作流、安全审查或故障排查。
2. 如果任务需要定时报告、issue 或 PR 分流、编排或 Agent 移交的起始模式，请阅读 references/examples.md。
3. 如果工作流涉及安全输出、网络策略、身份验证、锁定、防威胁检测或运行可观测性，请阅读 references/security-and-operations.md。
4. 如果工作流在编译、安装、身份验证、执行安全输出或访问工具时发生故障，请阅读 references/troubleshooting.md。 第 3 步：编写或修订工作流源文件
5. 将工作流的唯一事实来源保留在 .github/workflows/<workflow-name>.md 中。
6. 创建新工作流时，使用 assets/workflow.template.md 作为基础结构。
7. 选择满足任务要求的最小可行触发范围和仓库角色范围。
8. 除非工作流在 Agent 部分之外确实需要更广泛的 GitHub Actions 权限，否则将 permissions: 保持为只读。
9. 优先使用 safe-outputs: 处理评论、议题、标签、PR、Agent 分配和编排，而不是授予 Agent 直接写入权限。
10. 在使用安全输出的工作流中，指示 Agent 在无需采取操作时调用 noop。
11. 将 tools: 和 toolsets: 精简至任务所需的范围。
12. 默认使用 engine: copilot，除非任务明确要求使用其他引擎，且仓库已为该引擎的身份验证模式做好准备。实验性多提供方路由使用 engine: pi，Copilot SDK 模式使用 copilot-sdk: true。第三方引擎（cursor、kiro、aider、crush、opencode）可通过 gh aw add 导入。
13. 遵循最小权限原则配置 network:。如果编译器支持，优先使用 node、python 或 github 等生态标识符，而不是单个注册表域名。
14. 如果工作流按计划运行，或可能触发大量 Agent 轮次，请设置 max-ai-credits:，以限制每次运行的 AI Credits（AIC）支出，防止其不断增加。
15. 如果严格模式和已安装的 CLI 拒绝工作流仍需使用的自定义域名，请在确定性的设置步骤中预取外部来源，并将本地文件传给 Agent，而不是大范围放宽防火墙限制。
16. 不要依赖 ${{ steps.<id>.outputs.* }} 占位符在实际运行中传递到 Agent 可见的 Markdown 正文中。如果提示词指令依赖运行时的值，请在设置期间将这些值写入确定性的本地文件，并告知 Agent 读取该文件。
17. 仅当仓库确实能从共享逻辑或编排中受益时，才使用导入的或可复用的工作流。
18. 对动态输入集中的重复工作，优先使用可复用的 GH-AW worker，并配合确定性的 YAML 包装器进行发现和矩阵扇出。
19. 从矩阵调用可复用的 GH-AW worker 时，不要使用默认的共享工作流级并发组。应设置一个以矩阵输入或提示词标识为键的显式并发组，以免 GitHub 的“一个运行中、一个待处理”并发行为取消并行任务。
20. 更改 frontmatter、导入内容或其他编译时配置后，重新编译工作流。
21. 如果只更改了 Markdown 正文，且直接在 GitHub.com 上编辑工作流，则无需仅为正文更改重新编译。
22. 在本地编译、验证或试运行期间，将 .github/aw/ 视为临时 GH-AW 运行时和编译器暂存目录，除非工作流有意使用该路径中的已提交文件。 步骤 4：配置仓库前置条件和身份验证
23. 首次配置仓库前，阅读 references/authoring.md。
24. 如果仓库尚未配置为 GH-AW 创作仓库，且用户希望进行持久化设置，请运行 gh aw init。
25. 使用 gh aw secrets bootstrap 或 gh aw secrets set 配置引擎机密。
26. 使用 COPILOT_GITHUB_TOKEN 或 copilot-requests Actions 权限进行 Copilot 引擎身份验证。
27. 对于 Copilot 运行，请在 COPILOT_GITHUB_TOKEN 中使用细粒度 PAT；通用的 gho_... OAuth 令牌可能通过机密检查，但仍可能无法执行实际的 Copilot 操作。
28. 使用 gh aw trial 时，请确认宿主仓库也具有所需的引擎机密。逻辑仓库或源仓库中的机密不会自动复制到临时或可复用的宿主仓库中。
29. 扩展升级或重新安装后，重新检查 gh aw version，确保仓库指南与编译器行为保持一致。
30. 如果确定性封装器调用可复用工作器，请确保调用方工作流的权限至少与嵌套工作器请求的 actions、contents 和 pull-requests 范围一样宽泛，否则运行可能会在 Agent 执行开始前失败。
31. 如果工作流需要跨仓库读取或写入、Projects 访问、远程 GitHub 工具模式或高级安全输出，请使用 GitHub App 或自定义 GitHub 令牌。
32. 如果仓库是公开的，且工作流将检查不可信的外部内容，除非任务明确属于低风险公开工作流，否则请保留锁定和审批控制。

步骤 5：验证、编译和执行

1. 如果工作流使用了已弃用的字段，或者编译器指出存在可通过 codemod 修正的偏差，请运行 gh aw fix --write。
2. 在将工作流视为就绪之前，运行 gh aw validate --strict。
3. 如果 CLI 版本发生变化，或工作流依赖较新的 frontmatter 行为，请运行 gh aw compile --verbose，以便查看警告和生成版本的变化。
4. 验证成功后运行 gh aw compile，并同时提交 .md 源文件和生成的 .lock.yml 文件。
5. 使用 gh aw run <workflow> --dry-run 验证远程分发行为，尤其是在怀疑存在分支、触发器或工作流发现问题时。
6. 如果需要在推送前执行本地工作流源文件，请使用 gh aw trial ./.github/workflows/<workflow>.md。显式的 ./ 路径很重要；如果省略，CLI 可能会将参数解析为仓库规格，而不是本地文件。
7. 只有在工作流源文件或锁文件确实存在于目标分支上之后，才使用 gh aw run <workflow> 直接执行。
8. 更改后，使用 gh aw status、gh aw logs、gh aw audit 和 gh aw health 检查状态、失败、成本、工具使用情况和成功趋势。

步骤 6：专业地运行和改进

1. 检查工作流是否可以简化、拆分为更小的工作流，或转换为共享组件。
2. 对于会大规模创建问题、评论或拉取请求的工作流，初次部署时优先使用分阶段安全输出。
3. 对于定期维护，请有意固定或检查已安装的 gh-aw 版本，并通过 gh aw update 或 gh aw upgrade 更新工作流，而不要临时复制粘贴。
4. 让工作流提示词具体、范围明确且可审计。如果多个工作流需要相同规则，请将宽泛的策略移至可复用导入项或 Agent 文件中。

错误处理

• 如果 gh extension install github/gh-aw 失败，请使用 references/troubleshooting.md 中记录的独立安装程序路径。
• 如果编译失败，请先修复 frontmatter 语法、已弃用字段、导入项或权限不匹配，再继续。
• 如果编译器的行为与所读文档不符，请以已安装的 gh aw version 为准，并先针对该版本进行验证，再重写工作流结构。
• 如果 gh aw trial 将 .github/workflows/<name>.md 判定为无效的仓库规范，请改用显式本地路径重试，例如 ./.github/workflows/<name>.md。
• 如果可复用工作器单独运行成功，但包装工作流运行时启动失败，请先检查调用方工作流的 permissions: 继承情况，再修改工作器逻辑。
• 如果可复用 GH-AW 工作器的矩阵任务有大多数分支立即取消，请先检查被调用工作流的并发组。即使 cancel-in-progress 为 false，共享的工作流级并发组仍会取消待处理分支。
• 如果试运行在激活步骤因 Validate COPILOT_GITHUB_TOKEN secret 失败，请使用 gh secret list -R <host-repo> 检查宿主仓库。源仓库的机密不会继承到试运行宿主仓库。
• 如果 gh aw trial --force-delete-host-repo-before 失败，请确认你对宿主仓库拥有管理员权限，且当前 GitHub 身份验证令牌包含 delete_repo 范围。
• 如果工作流提示词在执行期间仍显示未解析的运行时占位符，请将这些值移入生成的本地上下文文件，并让 Agent 显式读取该文件。
• 如果本地 gh aw compile、gh aw validate 或 gh aw trial 命令生成了 .github/aw/ 文件（例如 actions-lock.json 或日志），请将其视为临时产物，提交前删除，除非仓库有意保留这些文件。
• 如果安全输出没有任何效果，请确认是否有意启用了暂存模式，并确认提示词明确要求 Agent 在不需要写入操作时调用 noop。
• 如果 gh aw mcp inspect 在检查已编译的定时工作流源时因模糊的计划解析错误而失败，请首先将其视为检查路径限制。重新运行 gh aw compile，优先使用已安装的工作流或基于运行日志进行调试；如果验证和编译已通过，不要假定工作流本身无效。
• 如果编译器拒绝了根据旧示例看似有效的引擎字段或工具条目，请以已安装的架构为准。在 gh aw v0.58.3 中，Copilot 不支持 engine.max-turns，bash 必须为 true、false 或允许列表；不接受布尔值的地方则接受裸 edit: / web-fetch: 键。
• 如果 URL 被清理为 (redacted)，或工具无法访问所需服务，请审慎收紧并扩展 network.allowed，而不是禁用防火墙。
• 如果 Copilot 推理在配置令牌后仍失败，请确认 PAT 所有者确实拥有 Copilot 许可证和推理访问权限。
• 如果公共仓库工作流未能获取外部贡献者的内容，请先确认 GitHub 锁定模式是否屏蔽了这些内容，再修改工作流逻辑。