scaffold-github-cloud-agent-environment

scaffold-github-cloud-agent-environment

让目标仓库做好准备，以便 Copilot 云端 Agent 构建并验证更改。先收集仓库和会话证据；如果平台约定不明确、已过时或正在变化，请查阅相关 GitHub 官方文档。

决策树

用户想做什么？

• 尚不存在 .github/workflows/copilot-setup-steps.yml： 审查仓库，核实尚未解决的平台假设，拟定计划，解决重要阻碍，然后预览并搭建工作流。
• 已有 copilot-setup-steps.yml 文件，但内容不够完善、已过时或有误： 检查工作流和故障证据，然后在保留自定义步骤的同时，进行有依据的最小修复。只有在有意替换时才重新生成，并且要先预览差异并确保有可恢复的备份。
• 搭建后 Agent 运行失败或行为异常： 先运行 doctor 模式，利用会话日志证据和仓库事实判断修复应在仓库内还是 GitHub 设置中进行，然后只修改证据支持的部分。
• 用户只想了解情况或制定计划： 只阅读解决当前问题所需的参考资料，然后直接回答，不搭建工作流。

快速参考

任务	操作
确认不明确的平台约定	从 references/live-docs.md 选择相关官方 URL
审查目标仓库	运行 scripts/audit_project.sh /path/to/project
根据仓库事实拟定计划	运行 python3 scripts/suggest_plan.py --project /path/to/project
预览生成的工作流	在有意写入前，运行 python3 scripts/render_setup_workflow.py --project /path/to/project --plan /path/to/plan.json --stdout
诊断现有设置	运行 python3 scripts/doctor.py --project /path/to/project --symptom "describe the failure" --json
了解写入文件前应询问的仓库相关问题	阅读 references/project-analysis.md
选择生态系统专用的依赖项步骤	阅读 references/patterns.md
根据症状查找修复方法	阅读 references/doctor-mode.md

不可妥协的工作流

1. 对于稳定且已知的修复，使用仓库文件、已安装工具的帮助信息／版本证据以及会话日志。若这些证据不足、似乎已过时，或平台契约将发生变化，请查阅相关的官方最新文档；无需每次修复都获取所有页面。
2. 在选择步骤、运行器或环境假设之前，先审查仓库。
3. 区分仓库本地修复与 GitHub 设置修复：
   • 仓库本地：.github/workflows/copilot-setup-steps.yml、.github/copilot-instructions.md、包管理器设置、LFS 检出、服务容器
   • 设置层面：运行器策略、防火墙允许列表、工作流审批、copilot 环境密钥或变量
4. 将项目特定的判断放在计划 JSON 中，不要埋进渲染器里。
5. 首先根据仓库证据消除实质性歧义，然后针对阻碍项提出具体问题。将建议性的选择记录为假设，不要让它们阻碍安全工作。潜在阻碍项包括：
   • 仓库显示使用 Windows，但需求未明确
   • 多个包管理器或多套工具链相互竞争
   • 存在私有注册表或内部主机
   • 可能需要自托管或更大型的运行器
   • 测试依赖的服务无法明确地表示为 GitHub Actions services
6. 将工作流固定在 .github/workflows/copilot-setup-steps.yml，其中只有一个名为 copilot-setup-steps 的作业。
7. 对该作业仅使用有文档说明的作业键。内置允许列表为 steps、permissions、runs-on、services、snapshot 和 timeout-minutes；扩展之前，请核实相关契约是否有变化。渲染器并未实现平台支持的所有键。
8. 将设置步骤失败视为环境降级，而不是硬性停止。文档说明，Copilot 会跳过剩余的设置步骤，并在当时已有的环境中继续运行。
9. 默认采用确定性的依赖安装，以及为获得可用环境所需的有限代码生成或准备工作。默认不要重复完整的 CI 生命周期。通过仓库说明提供构建和验证命令。
10. 在 doctor 模式下，从会话日志和观察到的症状入手。不要猜测日志或仓库事实无法支持的修复方案。

契约证据

遇到未解决的平台问题时，使用相关的 GitHub 官方文档页面进行确认；此目录用于查找来源，并非必须逐一阅读的清单：

• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-firewall
• https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/troubleshoot-cloud-agent
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/track-copilot-sessions
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/configuring-agent-settings
• https://docs.github.com/en/copilot/tutorials/cloud-agent/get-the-best-results
• https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions

有关针对性更新指南和建议的更新流程，请参阅 references/live-docs.md。内置示例中的版本、运行器标签、键允许列表和限制均为快照，并非永久性的升级要求。

项目分析规则

在编写或替换 copilot-setup-steps.yml 之前，请检查：

• .github/workflows/copilot-setup-steps.yml 是否已存在
• 包管理器、锁文件和工具链版本文件
• CI 工作流以及已有的运行器选择
• .github/copilot-instructions.md、.github/instructions/**/*.instructions.md、AGENTS.md、CLAUDE.md 和 GEMINI.md
• .gitattributes 中的 Git LFS 使用情况
• .devcontainer/、Dockerfile、Compose 文件和服务要求
• 私有注册表配置文件，例如 .npmrc、.yarnrc.yml、pip.conf、.pypirc、.cargo/config.toml、nuget.config 或 settings.xml
• 仅限 Windows 或内部网络的信号

先运行 scripts/audit_project.sh，需要完整检查清单和问题集时，再阅读 references/project-analysis.md。

确定性工作与启发式工作

以下部分应保持确定性：

• 工作流路径和作业名称
• 针对已验证平台契约的明确支持作业键
• 有界超时（随附基线中记录的最大值为 59；渲染器不会强制执行此限制）
• 便于手动测试和 PR 测试的验证触发条件
• 低权限 permissions
• 仓库明确使用 Git LFS 时启用 LFS
• 针对缺少工作流、作业名称错误、不支持的作业键、缺少 checkout，以及仅设置导致的失败模式所进行的 doctor 检查

以下部分可以保留启发式处理，但必须明确说明假设：

• 哪种运行器策略适合该仓库
• 工作流应设置一种还是多种工具链
• 具体的依赖安装命令
• 在 services 中声明服务容器是否安全
• 仓库是否需要仓库级或组织级防火墙或运行器更改

如果某项启发式选择会实质影响正确性或安全性，请将其添加到 questions，并在应用受影响的更改之前解决。带有标签的预览可以保留未解决的阻碍项，但不能作为可部署的建议。将非阻碍性假设放入 assumptions 或 notes。

重复运行规则

再次对项目调用此技能时：

• 如果证据不足或已过时，或平台相关契约即将变更，请重新查阅相关官方文档。
• 在假定现有方案仍然适用之前，先重新审查仓库。
• 尽量采用最小补丁，保留自定义步骤、注释和仓库固定项。渲染器会替换整个工作流，而不是合并内容；请先使用 --stdout 检查输出，并在有意替换之前保留可恢复的备份。方案的 mode 不是防止覆盖的保护措施。
• 每次更新都保留必需的作业名称和路径。
• 优先改进薄弱的设置，而不是添加第二套相互竞争的设置文件。
• 用户报告真实 Agent 运行失败时，优先使用 doctor 模式。

脚手架规则

• 写入 .github/workflows/copilot-setup-steps.yml，而不是使用其他名称的通用设置工作流。
• 只保留一个名为 copilot-setup-steps 的作业。
• 该作业中只使用受支持的作业键。
• 将 timeout-minutes 设为 59 或更低。
• 除非用户明确希望采用触发频率更低的验证方式，否则添加 workflow_dispatch、push 和 pull_request 触发器，并将其范围限定为工作流文件。
• 如果工作流会检出仓库，则添加 contents: read。
• 如果仓库使用 Git LFS，请在兼容且符合仓库版本固定要求的 actions/checkout 版本中启用 lfs: true。附带的 @v5 示例只是历史默认值，并非永久的平台要求，也不是升级指令。
• 不要依赖自定义的 fetch-depth 值。实时文档说明 Copilot 会覆盖该值。
• 对于自托管运行器，要求用户禁用集成防火墙，并允许文档中列出的 GitHub 和 Copilot 主机。
• 对于 Windows 运行器，将网络控制视为明确的设计决策，因为集成防火墙与 Windows 不兼容。
• 切勿内联凭据或机密值。通过 GitHub 文档所述的环境/设置机制配置机密和 Agent 级变量。非机密设置常量可以放在文档所述的工作流 env 位置（该辅助工具支持步骤级 env）；设置作业受限的允许列表并不意味着支持作业级 env。
• 如果 Copilot 需要明确的构建、测试或验证命令，请将 .github/copilot-instructions.md 作为配套文件。

Doctor 模式

Doctor 模式适用于脚手架生成后出现的实际故障，或现有设置存疑的仓库。

运行 python3 scripts/doctor.py --project /path/to/project --symptom "what failed" --json，然后根据检查结果决定下一步操作：

• 本地工作流修复：对 copilot-setup-steps.yml 进行最小幅度的补丁修改；只有在经过审查的替代方案中才重新生成
• 仓库设置修复：更新防火墙或工作流审批设置
• 组织设置修复：更新运行器默认设置或仓库覆盖策略
• 会话调查：先检查实时会话日志，再修改文件

阅读 references/doctor-mode.md 了解症状对应表，阅读 references/gotchas.md 了解较隐蔽的陷阱。

建议的源文件更新

如果证据表明指导内容已过时，请记录受影响的段落、当前官方来源及适用版本/日期、建议的更改和回归检查。只有在维护工作属于当前范围时，才编辑规范源代码包；否则应报告建议，绝不要悄悄修改已安装的副本。对于经授权的契约变更，应同步调整文档和辅助工具的行为，同时保留最低权限原则、机密处理方式和仓库版本固定要求。依赖生成结果前，请参阅 references/scaffold-layout.md，了解已验证的辅助工具限制。

阅读指南

需求	阅读
官方 URL 和更新策略	references/live-docs.md
选择步骤或运行器前的检查事项	references/project-analysis.md
生成文件布局和计划 JSON 结构	references/scaffold-layout.md
生态系统设置模式及何时提问	references/patterns.md
基于会话日志进行故障排查	references/doctor-mode.md
默认分支、防火墙、工作流审批和运行器陷阱	references/gotchas.md

运维脚本

• scripts/audit_project.sh 检查目标仓库，并以 JSON 格式报告与环境相关的事实。
• scripts/suggest_plan.py 根据仓库事实生成包含假设、手动设置和问题的计划草案。
• scripts/render_setup_workflow.py 根据明确计划生成或刷新 .github/workflows/copilot-setup-steps.yml。
• scripts/doctor.py 诊断现有设置问题，并区分仓库更改与 GitHub 设置更改。
• scripts/validate.py 检查结构、交叉引用和必需的支持文件。
• scripts/test_skill.py 在临时仓库中运行轻量级语法和集成检查。

注意事项

1. 工作流只有存在于默认分支后才会生效。功能分支上的正确文件对于实际 Copilot 运行仍然不起作用。
2. 实时文档说明，在 copilot-setup-steps 作业中，只有 steps、permissions、runs-on、services、snapshot 和 timeout-minutes 会被采用。额外的作业键看起来可能有效，但会被忽略。
3. 如果某个设置步骤以非零状态退出，Copilot 会跳过其余设置步骤并继续运行。
4. 自托管运行器需要在仓库设置中禁用集成防火墙。
5. Windows 运行器与集成防火墙不兼容。
6. 组织级运行器策略可能会悄然覆盖仓库首选的 runs-on。
7. 除非有人批准，或仓库设置允许自动运行，否则 Copilot 推送代码时，GitHub Actions 工作流不会自动运行。
8. Copilot 的平台行为会覆盖 actions/checkout 的 fetch-depth 设置，因此不要依赖自定义的浅克隆深度。
9. 防火墙仅适用于 Actions 设备中由 Agent 启动的进程。它不保护设置步骤或 MCP 服务。
10. 如果仓库依赖私有注册表或内部主机，通常真正的解决方案是结合使用 copilot 环境机密或变量，以及防火墙或运行器配置更改，而不只是修改 YAML。