企业官网建设流程全解析

Aspire 仓库 PR 代码审查技能（code-review）全指南：从分支准备到问题上报的完整工作流

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire

本指南以 microsoft/aspire 仓库（即当前 GitHub Trending 精选项目 aspire）中.agents/skills/code-review/SKILL.md这一代码审查技能文档为骨架，系统拆解一个面向 AI 审查代理（Copilot/Agent）的 PR 审查流程：从解析 PR 标识、本地分支准备，到变更分类、逐层代码审查（含影响分析、测试覆盖审查、条件测试选择审查），再到问题汇总与用户三选一后的评论发布。文中所有规则与示例均可回溯到仓库源码、配置与测试，读者阅读后可以完整复现这一套"只报问题、不夸风格"的工程级审查方法，并理解其背后的仓库约束（如 AGENTS.md、test-trigger-map.yml）是如何被审查代理消费的。

一、技能定位：这是一份给 AI 审查代理的工作说明书

.agents/skills/code-review/SKILL.md是一个标准化的 Agent Skill 描述文件。文件头部的 YAML front-matter 定义了技能的调用元数据：

--- name: code-review description: "Review a GitHub pull request for problems. Use when asked to review a PR, do a code review, check a PR for issues, or review pull request changes. Focuses only on identifying problems — not style nits or praise." ---

• name：技能标识code-review，与 AGENTS.md 中"Available Skills"清单里列出的技能一一对应（同目录下还有api-review、fix-flaky-test、test-management、reviewing-aspire-architecture等兄弟技能）。
• description：触发条件与边界——只审查问题（bugs、安全问题、正确性错误、性能回退、系统边界缺失的错误处理、仓库约定违规），不评论风格偏好、不写赞美、不提出非修复性建议。

该技能的核心定位是：microsoft/aspire 仓库专用的"问题发现代理"。它不是一个通用 lint 器，而是一条有严格步骤顺序、有明确"该报什么 / 不该报什么"边界的工程审查流水线。

二、严格步骤顺序：为什么必须先完成本地分支准备

文档开篇用CRITICAL: Step Ordering强制约束执行顺序：

在 Step 1（本地 checkout）解决之前，禁止调用mcp_github_pull_request_read的get_diff/get_files获取 PR 差异或文件列表。分支发现类调用（如gh pr view获取分支名）是允许的。

这样设计的原因在于：如果跳过本地 checkout 而只基于 GitHub 的 diff 审查，代理将无法读取周边代码上下文，审查质量会显著下降。而分支发现（仅读元数据）不会消耗评审上下文，所以被允许提前执行。

2.1 解析用户请求

审查代理需要从用户请求中提取两个要素：

1. PR 标识—— 可以是 PR 号（如7890）或完整 URL；
2. 仓库—— 默认为microsoft/aspire，除非用户另行指定。

如果用户没有给出 PR 号，则检查当前分支是否关联了已打开的 PR：

gh pr view --json number,title,headRefName 2>/dev/null

2.2 Step 1：确保 PR 分支在本地可用（阻塞步骤）

获取 PR 分支名，并判断当前是否已在该分支上：

# 获取 PR 分支名 gh pr view <number> --repo microsoft/aspire --json headRefName --jq '.headRefName' # 检查当前所在分支 git branch --show-current

• 若当前分支匹配PR 分支，直接进入 Step 2；
• 若不匹配，向用户提供两个选项：
  • 选项 1（推荐）：切换到 PR 分支——先git status --porcelain检查未提交改动，必要时git stash push -m "auto-stash before PR review of #<number>"，再执行gh pr checkout <number> --repo microsoft/aspire（该命令同时兼容同仓库与 fork 的 PR）。好处是周边代码在本地，上下文最完整。
  • 选项 2：仅基于 GitHub diff 审查，不触碰工作树；代价是审查质量可能下降。

2.3 Step 2：收集 PR 上下文

Step 2 依赖 GitHub MCP 集成（mcp_github_*工具）；若 MCP 服务器未配置，则回退到ghCLI 完成等价操作：

2.4 Step 3：按领域分类变更，决定审查深度

文档给出了一张"领域 → 路径 → 审查焦点"的映射表，这是仓库目录结构在审查流程中的直接落地：

这些路径与仓库实际结构完全吻合：src/Aspire.Hosting*/**、src/Aspire.Dashboard/**、src/Components/**、src/Aspire.Cli/**、tests/**、extension/**在 AGENTS.md 的"Project Layout and Architecture"一节均有对应说明。

三、Step 4 核心：审查方法学

3.1 变更的影响分析（Impact Analysis for Tests and Regressions）

文档明确要求审查者不要止步于"测试通过了"或"有测试"，而是先做基于代码的影响分析，把变更代码路径映射到可能回退的行为，再与 PR 的测试变更对照。对每个非平凡的生产代码变更，识别五要素：

1. 变更的行为—— 使用 diff 中的具体代码路径、方法或配置名描述；
2. 受影响面—— 哪些用户/系统面能观察到变更：公共 API、AppHost 模型、DCP/运行时编排、CLI、Dashboard、部署输出、VS Code 扩展、生成工件、日志/遥测、配置、持久化、网络或安全敏感流；
3. 回退风险—— 变更可能破坏既有场景的具体方式：时序/顺序变化、持久化状态兼容、重启/重试、资源清理、跨资源引用、环境变量、连接字符串、端点 URL、端口分配、平台/容器运行时差异；
4. 期望的回退覆盖—— 若修复缺失，哪些针对性测试或场景测试应当失败，或能捕获风险行为的再次变化；
5. 覆盖缺口—— 受影响但未被 PR 测试或明显相关既有测试覆盖的行为。

文档给出了示范性结论句式：

"This changesDcpExecutor.PrepareServices()port allocation timing, but there is no regression test showing a dependent resource can resolve the endpoint before workload creation."

（该示例同时暗示了仓库内部实现类DcpExecutor及其PrepareServices()方法的存在——它位于src/Aspire.Hosting的 DCP 编排层。）

3.2 条件测试选择审查（Conditional Test Selection Impact）

这是本技能中与 Aspire 仓库 CI 体系耦合最深的部分。审查代理必须应用 AGENTS.md 中的仓库级条件测试选择规则，把新增的测试项目、CI 任务、工作流、脚本、松散输入追溯到其真实消费方，再判断触发映射是否需要变更。

具体审查点包括：

• Layer 1 vs Layer 2 的归属：被Aspire.slnx的 ProjectGraph 求值的文件属于 Layer 1（零维护，由tools/SelectTests在进程内计算ProjectReference反向闭包）；图外的项目是 Layer 2 盲区。
• Layer 2 输入路由：路由到精确消费方、ALL（广泛影响）或显式置于选择器之外；不允许用ignore或 prefilter 条目隐藏真实的 PR-CI 消费方。
• 运行时包与 fixture 消费：检查 E2E 测试中的运行时包与 fixture 消费，包括aspire add、生成的 AppHost 包集、包过滤器、模板、工作区副本。若 PR 增删这些消费方，必须要求同一 PR 中affected_project_rules或path_rules相应条目同步变更。
• QuarantinedTest/ActiveIssue/OuterloopTest的变更：对运行时消费的 E2E 场景，regular-PR 目标只能包含符合常规 PR CI 资格的消费方；资格变化时要求精确的映射边与聚焦的回退覆盖同步变更。
• 项目名模式是 glob 而非正则：对昂贵或按类分片的门控目标，标记那些包含目标并未实际执行的家族 glob；只有每个当前与未来匹配项目都应当选中目标时才可使用家族 glob，否则维护审计过的精确消费方列表。
• reason字段的纪律：简明陈述规则覆盖范围或消费原因，不写 PR 叙述、不重复完整规则、不保留调查历史；targets字段拥有目标列表，不要在reason中重复目标名。
• run_*接线：门控的job:目标必须有run_*输出接线，门控外目标标记为 advisory，可复用工作流实现必须路由到其实现的任务。

文档强调选择器行为变更必须保持"动作、工作流门、工具、映射、测试、权威文档"六者同步，并要求真实映射测试：每个不同路由边界一个代表性正向用例、被刻意排除消费方的聚焦负向用例、跨规则类型重复消费方列表的结构化断言。完整契约见 docs/ci/test-trigger-map.md。

从源码看，这一整套机制的实现分散在：

• 机器可读映射：eng/github-ci/test-trigger-map.yml（579 行，含groups、conventions、prefilter、ignore、path_rules、affected_project_rules、derived_targets五类匹配器）；
• 选择器工具：tools/SelectTests（TestSelector、TriggerMap、ChangedFileFilter、GraphAffectedProjects、SelectionTrace等类型）；
• 路由边界回归测试：tests/Infrastructure.Tests/TestTriggerMap（SelectTestsAcceptanceTests、SelectTestsCliTests、SelectTestsWorkflowTests、SelectTestsLayer1IntegrationTests、GraphAffectedProjectsTests、TestTriggerMapTests）。

设计文档 docs/ci/test-trigger-map.md 还给出了审查代理可直接使用的验证命令：

# 对本地变更集计算权威选择结果（与 CI 同源） dotnet run --project tools/SelectTests -- --changed-files changed-files.txt --explain # 运行触发映射的聚焦测试套件 dotnet test --project tests/Infrastructure.Tests/Infrastructure.Tests.csproj \ --no-launch-profile -- \ --filter-namespace "Infrastructure.Tests.TestTriggerMap" \ --filter-not-trait "quarantined=true" \ --filter-not-trait "outerloop=true"

3.3 测试覆盖审查（Test Coverage Review）

文档规定：每次审查都必须评估 PR 是否为被变更的行为类型提供了恰当的测试。纯机械重构、注释、纯文档变更不要求测试；但当生产行为变化且 PR 无明确、有说服力的理由时，缺失或不足的覆盖必须标记。回退覆盖尤其重要：bug 修复与行为变更应包含在修复前会失败的测试，而不只是宽泛的快乐路径覆盖或重新生成的快照。

文档给出了一张"变更类型 → 期望覆盖"的映射表：

对于部署变更尤其严格：仅更新 Helm 图表、Kubernetes YAML、Docker Compose、Bicep、JSON 清单或快照文件只能证明序列化器输出正确；若 PR 改变部署行为、资源连通性、预置顺序、基础设施组合、环境变量、端点暴露、健康、清理或升级行为，必须寻找一个真正部署并验证场景的部署测试。

当专门覆盖缺失且合适形态不明确时，可引用相关技能作为参考：cli-e2e-testing、dashboard-testing、deployment-e2e-testing、vscode-extension。

3.4 该报什么（What to Flag）：15 类问题清单

文档列出了审查代理必须标记的实际问题类别：

1. Bugs—— 逻辑错误、差一错误、空引用、缺失 await、竞态条件、错误的资源释放；
2. Security—— 注入风险、凭据暴露、不安全默认值、OWASP Top 10 违规；
3. Correctness—— 相对 PR 描述或既有契约的错误行为，以及对用于多语言 SDK 生成的稳定 Aspire Type System (ATS) 面的破坏性变更；
4. 行为契约变更—— 类型被替换/删除/重构时，静默改变的行为契约（如"先前非法访问会抛异常，现在返回默认值"）；
5. 弱化的不变量—— 重构中校验被放松（如SingleOrDefault被换成FirstOrDefault、Debug.Assert守卫应改为if+throw、前置条件检查被删除）；
6. 系统边界的缺失错误处理—— 未校验的外部输入、公共 API 入口缺失空检查（类型系统已保证非空的不标记）；
7. 性能回退—— 热路径中不必要的分配、N+1 查询、阻塞异步调用（Task.Result、.Wait()）；
8. 并发问题—— 并发代码中的线程不安全集合、缺失同步、死锁风险；
9. 时序耦合与初始化安全—— 初始化为null!且必须在使用前调用独立Initialize()的字段、依赖调用顺序的 DI 注册、遗漏调用会导致运行时 NRE 且无编译期保障的模式；
10. 资源泄漏—— 创建但从未释放的IDisposable对象（如CancellationTokenSource、SemaphoreSlim）；
11. 死代码与过期注释—— 描述已不存在行为的注释、未使用变量、带"materialize to check count"注释但从不检查计数的ToList()；
12. 仓库约定违规—— 依据 AGENTS.md 规则：手动编辑api/*.cs、手动编辑*.xlf、向NuGet.config添加未批准的 feed、修改global.json、用== null而非is null；
13. 代码注释问题—— 应用 AGENTS.md 的注释准则，只标记具体问题（注释与代码矛盾、无跟踪链接的 workaround 注释、解析器/协议/日志解析未包含理解边界情况所需的原始形态、隐私/安全敏感行为注释未解释 opt-in/范围/WHY）；
14. 测试问题—— 易碎模式：线程不安全的测试 fake、基于日志的就绪检查而非WaitForHealthyAsync()、共享超时预算、硬编码端口、测试中使用Directory.SetCurrentDirectory、注释掉的测试；
15. 缺失或不足的测试覆盖—— 生产行为变化而无对应面覆盖，或 bug 修复缺少修复前会失败的聚焦回退测试。

3.5 不该报什么（What NOT to Flag）

• .editorconfig或格式化器已处理的风格偏好；
• 缺失的 XML doc 注释（除非公共 API 完全无文档）；
• 与无关代码的重构建议；
• 缺失 API 文件重新生成（开发期预期行为）；
• 纯文档/纯注释/机械重命名/可证明保持行为的重构缺少测试；
• 纯视觉样式变更缺少测试；
• 标准 C# API 审查关注点（命名、命名空间、框架设计准则、一般 .NET/C# API 破坏性变更）——由专用api-review技能处理，本技能只检查用于多语言 SDK 生成的稳定 ATS 面；
• 含<SuppressFinalPackageVersion>true</SuppressFinalPackageVersion>的包或[Experimental]/ATS 实验元数据导出的 API 的 ATS 破坏性变更；
• extension-release.yml为机器人作者extension-release/*PR 创建的 extension/CHANGELOG.md 初始占位条目（预期行为，由extension-changelog.md异步替换、extension-changelog-finalized.yml合并门控）。

3.6 审查重构/移动的代码

当代码从一文件移动到另一文件时，视同新写代码处理：

• 标记移动代码中的既有问题—— 有 bug 或不安全代码被复制到新文件也要标记，并注明"Pre-existing issue, good opportunity to fix during this refactoring"；
• 对比新旧行为—— 类型被删除并替换时，显式比较新旧实现，查找被移除的 override、改变的异常行为、放松的校验、丢失的不变量检查；
• 检查被删除类型的调用方——OldClass被NewClass<T>替换后，验证依赖OldClass特定行为的所有调用点仍工作正常。

3.7 Aspire 领域升级（Aspire-domain escalation）

文档明确：先完成通用审查，再考虑调用reviewing-aspire-architecture技能。绝不允许仅因 PR 触及 hosting 核心、Azure 集成、Dashboard、CLI、组件、资源类型、App 模型或部署行为就优先调用领域技能。

通用审查通过后，仅当全部满足以下条件时才进行聚焦架构升级：

1. diff 提供正确性问题的具体证据；
2. 解决该问题依赖本技能规则之外的、有命名的 Aspire 特定契约或生命周期规则；
3. 通用审查无法从 diff、周边代码、测试与既有注释判断行为是否正确；
4. 升级可表达为一个聚焦问题，附带相关文件、证据、错误的后果以及需要专家知识的原因。

禁止为已是具体通用结论的问题、仅高风险代码、寻求第二意见或对更高置信度的广泛期望而升级。保留已完成的通用结论，对变更集修订版最多运行一次聚焦升级，且只合并净新增的高置信专家结论——领域专家返回后不重跑通用审查。

这一升级路径在 .agents/skills/reviewing-aspire-architecture/SKILL.md 中有完整呼应：该技能仅用于"用户显式请求深度架构审查"或"通用审查者升级无法解决的、有命名的 Aspire 领域问题"两种场景，并带有调用守卫（父代理加载一次、启动一个领域代理；当前代理已是领域代理则不再调用）。

四、Step 5 & 6：问题呈现与评论发布

4.1 不自动发布，先让用户分诊

文档强调Do not post a review automatically。审查代理把所有发现整理为编号列表，按潜在影响排序呈现给用户，然后询问下一步：

• "Add 1, 3, 5 as comments"—— 只发布这些编号项；
• "Add all"—— 发布全部；
• "Add none"—— 跳过发布；
• 其他任意选择或修改指令。

4.2 自动合并安全检查

在提交带event: "APPROVE"的审查之前，先检查 PR 是否启用自动合并：

gh pr view <number> --repo microsoft/aspire --json autoMergeRequest --jq '.autoMergeRequest'

若结果为非空（自动合并已启用）且审查包含评论，必须警告用户：批准很可能在作者处理评论前触发自动合并。提供两个选项：

1. 仍然批准—— 以 APPROVE 提交（自动合并可能立即执行）；
2. 降级为评论—— 以 COMMENT 提交，让作者先处理反馈。

用户选择选项 2 时，使用event: "COMMENT"而非"APPROVE"。

4.3 发布审查的三步流程

1. 创建待定审查：mcp_github_pull_request_review_write的create方法（不传event参数）；
2. 为每个选中的发现添加行内评论：mcp_github_add_comment_to_pending_review，将评论放在 diff 的特定行：
   • subjectType：LINE为行级评论，FILE为文件级评论；
   • side：RIGHT表示针对新代码；
   • path：相对文件路径；
   • line：diff 中的行号；
   • body：问题与修复方式的简洁描述；
3. 提交审查：mcp_github_pull_request_review_write的submit_pending方法：
   • 已发布评论且用户显式要求批准：仅在未启用自动合并（或用户确认自动合并警告）时用event: "APPROVE"；
   • 已发布评论但用户未要求批准：用event: "COMMENT"；
   • 两种情况都应在 summary body 中按类别列出问题数量；除非用户显式要求，不使用REQUEST_CHANGES；
   • 用户选择不添加任何评论：不创建也不提交审查，向用户确认未发布审查。

4.4 审查质量规则

• 只报具体、高置信的问题—— 确定的缺陷（bug、安全问题、正确性错误、性能回退、系统边界缺失错误处理、仓库约定违规），不报投机性顾虑、设计反馈或无法用 diff 中具体证据支持的问题；
• 一条评论一个问题—— 不把多个问题打包进单条评论；
• 要具体—— 引用存在问题的确切行、变量或条件；
• 给出修复方向—— 修复不明显时附带简要建议或代码片段；
• 不重复既有审查评论—— 发布前先检查既有讨论线程。

五、技能背后的仓库支撑体系

本技能并非孤立文档，而是 Aspire 仓库 Agent 工具链的一环。在 AGENTS.md 的 "Available Skills" 清单中，code-review与以下技能分工协作：

• api-review—— .NET API 面审查（设计准则），处理本技能明确划出的标准 C# API 审查关注点；
• reviewing-aspire-architecture—— 架构/模式审查，本技能升级路径的目标技能；
• cli-e2e-testing / dashboard-testing / deployment-e2e-testing / vscode-extension—— 各类专门测试技能，本技能在专门覆盖缺失时引用它们；
• ci-test-failures / fix-flaky-test / test-management—— 测试失败诊断与易碎测试治理，与本技能的测试审查点（QuarantinedTest/ActiveIssue/OuterloopTest属性）配套。

仓库还通过 Pattern-Based Instructions 为审查提供补充规则：例如tests/**/*.cs匹配 .github/instructions/test-review-guidelines.instructions.md（易碎测试模式表：线程不安全集合、基于日志的就绪检查、共享超时预算、端口冲突、文件锁定、顺序依赖状态、快照漂移等），src/Aspire.Hosting/**/*.cs匹配 hosting-core 审查模式，src/Aspire.Hosting.Azure*/**/*.cs匹配 hosting-azure 审查模式等。本技能 Step 4 中"flaky patterns per the test review guidelines"的引用即指向该文件。

测试属性层面，仓库实际代码中大量使用了技能提到的三个属性：例如 tests/Aspire.Cli.EndToEnd.Tests/KubernetesPublishTests.cs 同时带有[ActiveIssue]与[QuarantinedTest]，tests/Aspire.Cli.EndToEnd.Tests/KubernetesDeployWithNatsTests.cs 带有[QuarantinedTest]，tests/Aspire.Cli.EndToEnd.Tests/ConfigMigrationTests.cs 带有[ActiveIssue]。这些属性在 AGENTS.md 中有完整定义：QuarantinedTest用于易碎测试（运行于tests-quarantine.yml），ActiveIssue用于因已知 bug 持续失败的测试（完全跳过），OuterloopTest用于长耗时/资源密集型测试（运行于tests-outerloop.yml）。

六、实践要点速查

七、总结

.agents/skills/code-review/SKILL.md是一份高度工程化的 PR 审查技能定义。它的核心设计哲学可以概括为三点：

1. 只报问题：15 类可标记问题与 7 类禁止标记事项划定了审查代理的精确行为边界，杜绝风格噪音与无证据猜测；
2. 证据驱动：每条结论都要落到 diff 中的具体行、变量或条件，并给出修复方向；
3. 流程受控：从本地分支准备（阻塞步骤）、按领域分类、影响分析驱动测试覆盖审查、条件测试选择映射审计，到升级路径与自动合并安全门——每个环节都有明确的顺序约束与决策条件。

这套技能与 AGENTS.md、eng/github-ci/test-trigger-map.yml、docs/ci/test-trigger-map.md、.agents/skills/reviewing-aspire-architecture/SKILL.md 以及 .github/instructions 目录下的模式化审查指令共同构成了 Aspire 仓库的 AI 审查基础设施。对于希望为自己的开源仓库搭建类似"AI PR 审查代理"的工程团队，这份文档是可直接借鉴的完整范式：它展示了如何把一个大型 .NET 分布式应用仓库（Hosting/Dashboard/Components/CLI/Deployment/Extension 六大领域 + 选择性 CI 体系）的审查经验，固化为可复现、可验证、可路由的 Agent 工作流。

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire