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. 除非工作流确实需要更广泛的 GitHub Actions 权限（且这些权限不属于 Agentic 部分），否则将 permissions: 保持为只读。
9. 使用 safe-outputs: 处理评论、议题、标签、PR、Agent 分配和编排，而不是授予 Agent 直接写入权限。
10. 在使用安全输出的工作流中，指示 Agent 在无需执行任何操作时调用 noop。
11. 仅配置任务所需的 tools: 和 toolsets:。
12. 默认使用 engine: copilot，除非任务明确要求使用其他引擎，且仓库已针对该引擎的身份验证模式做好准备。
13. 按最小权限原则配置 network:。如果编译器支持，优先使用 node、python 或 github 等生态系统标识，而非单个注册表域名。
14. 如果严格模式和已安装的 CLI 拒绝工作流仍需使用的自定义域名，请在确定性的设置步骤中预取外部源，并将本地文件传给 Agent，而不要大幅放宽防火墙限制。
15. 不要依赖 ${{ steps.<id>.outputs.* }} 占位符在实际运行中传递到 Agent 可见的 Markdown 正文中。如果提示词指令依赖运行时值，请在设置期间将这些值写入确定性的本地文件，并告知 Agent 读取该文件。
16. 仅当仓库确实能从共享逻辑或编排中受益时，才使用导入或可复用工作流。
17. 对于需要在动态输入集合中重复执行的工作，优先使用可复用的 GH-AW worker，并搭配用于发现输入和展开矩阵的确定性 YAML 包装器。
18. 如果从矩阵调用可复用的 GH-AW worker，请勿让它使用默认的工作流级共享并发组。请设置一个以矩阵输入或提示词身份为键的显式并发组，以免并行任务因 GitHub 的“一次运行、一次待处理”并发行为而被取消。
19. 修改 frontmatter、导入项或其他编译时配置后，重新编译工作流。
20. 如果只修改了 Markdown 正文，且工作流是在 GitHub.com 上直接编辑的，则无需仅因正文变更而重新编译。
21. 在本地编译、验证或试运行期间，将 .github/aw/ 视为 GH-AW 的临时运行时和编译器暂存空间，除非工作流有意使用该路径中已提交的文件。 步骤 4：配置仓库前置条件和身份验证
22. 首次设置仓库前，阅读 references/authoring.md。
23. 如果仓库尚未配置 GH-AW 编写环境，且用户希望进行持久化设置，请运行 gh aw init。
24. 使用 gh aw secrets bootstrap 或 gh aw secrets set 配置引擎机密。
25. 使用 COPILOT_GITHUB_TOKEN 进行 Copilot 引擎身份验证。
26. 对于 Copilot 运行，请在 COPILOT_GITHUB_TOKEN 中使用细粒度 PAT；通用的 gho_... OAuth 令牌可能通过机密检查，但仍可能无法执行实际的 Copilot 任务。
27. 使用 gh aw trial 时，请确认主机仓库也配置了所需的引擎机密。逻辑仓库或源仓库中的机密不会自动复制到临时或可复用的主机仓库。
28. 扩展升级或重新安装后，请再次运行 gh aw version，确保仓库指南与编译器行为保持一致。
29. 如果确定性包装器调用可复用工作器，请确保调用方工作流权限至少与嵌套工作器请求的 actions、contents 和 pull-requests 权限范围一样广，否则运行可能会在 Agent 执行开始前失败。
30. 如果工作流需要跨仓库读取或写入、Projects 访问权限、远程 GitHub 工具模式或高级安全输出，请使用 GitHub App 或自定义 GitHub 令牌。
31. 如果仓库是公开的，且工作流将检查不受信任的外部内容，请保留锁定和审批控制，除非任务明确属于低风险公开工作流。

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

1. 如果工作流使用已弃用的字段，或编译器指出存在可通过代码修改工具修复的偏差，请运行 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 锁定模式是否屏蔽了这些内容，再修改工作流逻辑。