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 解析用户请求审查代理需要从用户请求中提取两个要素PR 标识—— 可以是 PR 号如7890或完整 URL仓库—— 默认为microsoft/aspire除非用户另行指定。如果用户没有给出 PR 号则检查当前分支是否关联了已打开的 PRgh pr view --json number,title,headRefName 2/dev/null2.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 完成等价操作信息工具方法用途PR 元数据mcp_github_pull_request_read→get标题、描述、基线分支、作者变更文件列表mcp_github_pull_request_read→get_files文件过多时分页完整差异mcp_github_pull_request_read→get_diff逐行审查依据已有评论mcp_github_pull_request_read→get_review_comments避免重复评论既有意见2.4 Step 3按领域分类变更决定审查深度文档给出了一张领域 → 路径 → 审查焦点的映射表这是仓库目录结构在审查流程中的直接落地领域路径审查焦点Hostingsrc/Aspire.Hosting*/**资源生命周期、连接字符串、健康检查、参数校验Dashboardsrc/Aspire.Dashboard/**Blazor 组件逻辑、数据绑定、可访问性Integrations/Componentssrc/Components/**客户端配置、DI 注册、连接处理CLIsrc/Aspire.Cli/**命令解析、错误处理、退出码Teststests/**易碎测试模式见下文、测试隔离、断言质量Deploymentsrc/Aspire.Hosting.Azure*/**、src/Aspire.Hosting.Docker/**、src/Aspire.Hosting.Kubernetes/**、tests/Aspire.Hosting.*Kubernetes.Tests/**、tests/Aspire.Cli.EndToEnd.Tests/**/Kubernetes*、tests/Aspire.Deployment.EndToEnd.Tests/**Kubernetes/Helm、Docker、Azure 工件及真实部署行为、预置与清理Build/Infraeng/**、*.props、*.targets意外副作用、被破坏的条件逻辑API filessrc/*/api/*.cs严禁手动编辑——若被修改必须标记Extensionextension/**本地化、TypeScript 用法Docs/Configdocs/**、*.md、*.json仅核对准确性这些路径与仓库实际结构完全吻合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 的测试变更对照。对每个非平凡的生产代码变更识别五要素变更的行为—— 使用 diff 中的具体代码路径、方法或配置名描述受影响面—— 哪些用户/系统面能观察到变更公共 API、AppHost 模型、DCP/运行时编排、CLI、Dashboard、部署输出、VS Code 扩展、生成工件、日志/遥测、配置、持久化、网络或安全敏感流回退风险—— 变更可能破坏既有场景的具体方式时序/顺序变化、持久化状态兼容、重启/重试、资源清理、跨资源引用、环境变量、连接字符串、端点 URL、端口分配、平台/容器运行时差异期望的回退覆盖—— 若修复缺失哪些针对性测试或场景测试应当失败或能捕获风险行为的再次变化覆盖缺口—— 受影响但未被 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.yml579 行含groups、conventions、prefilter、ignore、path_rules、affected_project_rules、derived_targets五类匹配器选择器工具tools/SelectTestsTestSelector、TriggerMap、ChangedFileFilter、GraphAffectedProjects、SelectionTrace等类型路由边界回归测试tests/Infrastructure.Tests/TestTriggerMapSelectTestsAcceptanceTests、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 quarantinedtrue \ --filter-not-trait outerlooptrue3.3 测试覆盖审查Test Coverage Review文档规定每次审查都必须评估 PR 是否为被变更的行为类型提供了恰当的测试。纯机械重构、注释、纯文档变更不要求测试但当生产行为变化且 PR 无明确、有说服力的理由时缺失或不足的覆盖必须标记。回退覆盖尤其重要bug 修复与行为变更应包含在修复前会失败的测试而不只是宽泛的快乐路径覆盖或重新生成的快照。文档给出了一张变更类型 → 期望覆盖的映射表变更类型期望的覆盖核心逻辑、资源模型、集成、解析器、校验、错误处理、公共 API 行为匹配的tests/*.*Tests/项目中的单元或集成测试用户可见的 CLI 命令、提示、终端工作流、安装/更新行为、命令输出契约tests/Aspire.Cli.EndToEnd.Tests/下的 CLI 端到端覆盖外加可行的聚焦单元测试Dashboard UI 逻辑、浏览器独有功能行为、认证流、bUnit 无法实际模拟的交互tests/Aspire.Dashboard.Tests/Integration/Playwright/下的 Dashboard Playwright 覆盖外加tests/Aspire.Dashboard.Tests/或tests/Aspire.Dashboard.Components.Tests/的逻辑/组件覆盖纯视觉 CSS、主题、颜色、透明度、光标、交互状态外观无需自动化覆盖不得仅为这些变更要求计算样式、精确颜色或截图断言部署、发布、预置、生成的 Kubernetes/Helm/Bicep/Docker 工件、Azure 资源接线、部署后端点行为tests/Aspire.Deployment.EndToEnd.Tests/下的部署端到端覆盖仅生成工件快照测试不足以证明部署行为VS Code 扩展命令、树视图、调试器流、RPC/DCP/MCP 集成、扩展 UI、通过 VS Code 可见的 CLI 集成extension/src/test-e2e/下的 VS Code 扩展 E2E 覆盖外加可行的extension/src/test/Mocha 单元测试对于部署变更尤其严格仅更新 Helm 图表、Kubernetes YAML、Docker Compose、Bicep、JSON 清单或快照文件只能证明序列化器输出正确若 PR 改变部署行为、资源连通性、预置顺序、基础设施组合、环境变量、端点暴露、健康、清理或升级行为必须寻找一个真正部署并验证场景的部署测试。当专门覆盖缺失且合适形态不明确时可引用相关技能作为参考cli-e2e-testing、dashboard-testing、deployment-e2e-testing、vscode-extension。3.4 该报什么What to Flag15 类问题清单文档列出了审查代理必须标记的实际问题类别Bugs—— 逻辑错误、差一错误、空引用、缺失 await、竞态条件、错误的资源释放Security—— 注入风险、凭据暴露、不安全默认值、OWASP Top 10 违规Correctness—— 相对 PR 描述或既有契约的错误行为以及对用于多语言 SDK 生成的稳定 Aspire Type System (ATS) 面的破坏性变更行为契约变更—— 类型被替换/删除/重构时静默改变的行为契约如先前非法访问会抛异常现在返回默认值弱化的不变量—— 重构中校验被放松如SingleOrDefault被换成FirstOrDefault、Debug.Assert守卫应改为ifthrow、前置条件检查被删除系统边界的缺失错误处理—— 未校验的外部输入、公共 API 入口缺失空检查类型系统已保证非空的不标记性能回退—— 热路径中不必要的分配、N1 查询、阻塞异步调用Task.Result、.Wait()并发问题—— 并发代码中的线程不安全集合、缺失同步、死锁风险时序耦合与初始化安全—— 初始化为null!且必须在使用前调用独立Initialize()的字段、依赖调用顺序的 DI 注册、遗漏调用会导致运行时 NRE 且无编译期保障的模式资源泄漏—— 创建但从未释放的IDisposable对象如CancellationTokenSource、SemaphoreSlim死代码与过期注释—— 描述已不存在行为的注释、未使用变量、带materialize to check count注释但从不检查计数的ToList()仓库约定违规—— 依据 AGENTS.md 规则手动编辑api/*.cs、手动编辑*.xlf、向NuGet.config添加未批准的 feed、修改global.json、用 null而非is null代码注释问题—— 应用 AGENTS.md 的注释准则只标记具体问题注释与代码矛盾、无跟踪链接的 workaround 注释、解析器/协议/日志解析未包含理解边界情况所需的原始形态、隐私/安全敏感行为注释未解释 opt-in/范围/WHY测试问题—— 易碎模式线程不安全的测试 fake、基于日志的就绪检查而非WaitForHealthyAsync()、共享超时预算、硬编码端口、测试中使用Directory.SetCurrentDirectory、注释掉的测试缺失或不足的测试覆盖—— 生产行为变化而无对应面覆盖或 bug 修复缺少修复前会失败的聚焦回退测试。3.5 不该报什么What NOT to Flag.editorconfig或格式化器已处理的风格偏好缺失的 XML doc 注释除非公共 API 完全无文档与无关代码的重构建议缺失 API 文件重新生成开发期预期行为纯文档/纯注释/机械重命名/可证明保持行为的重构缺少测试纯视觉样式变更缺少测试标准 C# API 审查关注点命名、命名空间、框架设计准则、一般 .NET/C# API 破坏性变更——由专用api-review技能处理本技能只检查用于多语言 SDK 生成的稳定 ATS 面含SuppressFinalPackageVersiontrue/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被NewClassT替换后验证依赖OldClass特定行为的所有调用点仍工作正常。3.7 Aspire 领域升级Aspire-domain escalation文档明确先完成通用审查再考虑调用reviewing-aspire-architecture技能。绝不允许仅因 PR 触及 hosting 核心、Azure 集成、Dashboard、CLI、组件、资源类型、App 模型或部署行为就优先调用领域技能。通用审查通过后仅当全部满足以下条件时才进行聚焦架构升级diff 提供正确性问题的具体证据解决该问题依赖本技能规则之外的、有命名的 Aspire 特定契约或生命周期规则通用审查无法从 diff、周边代码、测试与既有注释判断行为是否正确升级可表达为一个聚焦问题附带相关文件、证据、错误的后果以及需要专家知识的原因。禁止为已是具体通用结论的问题、仅高风险代码、寻求第二意见或对更高置信度的广泛期望而升级。保留已完成的通用结论对变更集修订版最多运行一次聚焦升级且只合并净新增的高置信专家结论——领域专家返回后不重跑通用审查。这一升级路径在 .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若结果为非空自动合并已启用且审查包含评论必须警告用户批准很可能在作者处理评论前触发自动合并。提供两个选项仍然批准—— 以 APPROVE 提交自动合并可能立即执行降级为评论—— 以 COMMENT 提交让作者先处理反馈。用户选择选项 2 时使用event: COMMENT而非APPROVE。4.3 发布审查的三步流程创建待定审查mcp_github_pull_request_review_write的create方法不传event参数为每个选中的发现添加行内评论mcp_github_add_comment_to_pending_review将评论放在 diff 的特定行subjectTypeLINE为行级评论FILE为文件级评论sideRIGHT表示针对新代码path相对文件路径linediff 中的行号body问题与修复方式的简洁描述提交审查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.ymlActiveIssue用于因已知 bug 持续失败的测试完全跳过OuterloopTest用于长耗时/资源密集型测试运行于tests-outerloop.yml。六、实践要点速查阶段关键动作关键命令/工具解析请求提取 PR 号/URL 与仓库无 PR 号时查当前分支gh pr view --json number,title,headRefName分支准备阻塞匹配分支则继续否则二选一gh pr checkout number --repo microsoft/aspire收集上下文PR 元数据、文件列表、diff、既有评论mcp_github_pull_request_readget/get_files/get_diff/get_review_comments或ghCLI 回退分类变更按领域表确定审查深度领域 → 路径映射表影响分析变更行为 → 受影响面 → 回退风险 → 期望覆盖 → 缺口五要素模板条件测试选择追溯消费方检查触发映射六同步eng/github-ci/test-trigger-map.yml、tools/SelectTests --explain测试覆盖审查按变更类型映射期望覆盖变更类型 → 覆盖映射表发现问题只报 15 类实际问题不报风格What to Flag 清单架构升级通用审查完成后按 4 条件聚焦升级.agents/skills/reviewing-aspire-architecture/SKILL.md呈现与发布编号列表让用户分诊自动合并检查三步发布mcp_github_pull_request_review_write七、总结.agents/skills/code-review/SKILL.md是一份高度工程化的 PR 审查技能定义。它的核心设计哲学可以概括为三点只报问题15 类可标记问题与 7 类禁止标记事项划定了审查代理的精确行为边界杜绝风格噪音与无证据猜测证据驱动每条结论都要落到 diff 中的具体行、变量或条件并给出修复方向流程受控从本地分支准备阻塞步骤、按领域分类、影响分析驱动测试覆盖审查、条件测试选择映射审计到升级路径与自动合并安全门——每个环节都有明确的顺序约束与决策条件。这套技能与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aspire 仓库 PR 代码审查技能（code-review）全指南：从分支准备到问题上报的完整工作流
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 解析用户请求审查代理需要从用户请求中提取两个要素PR 标识—— 可以是 PR 号如7890或完整 URL仓库—— 默认为microsoft/aspire除非用户另行指定。如果用户没有给出 PR 号则检查当前分支是否关联了已打开的 PRgh pr view --json number,title,headRefName 2/dev/null2.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 完成等价操作信息工具方法用途PR 元数据mcp_github_pull_request_read→get标题、描述、基线分支、作者变更文件列表mcp_github_pull_request_read→get_files文件过多时分页完整差异mcp_github_pull_request_read→get_diff逐行审查依据已有评论mcp_github_pull_request_read→get_review_comments避免重复评论既有意见2.4 Step 3按领域分类变更决定审查深度文档给出了一张领域 → 路径 → 审查焦点的映射表这是仓库目录结构在审查流程中的直接落地领域路径审查焦点Hostingsrc/Aspire.Hosting*/**资源生命周期、连接字符串、健康检查、参数校验Dashboardsrc/Aspire.Dashboard/**Blazor 组件逻辑、数据绑定、可访问性Integrations/Componentssrc/Components/**客户端配置、DI 注册、连接处理CLIsrc/Aspire.Cli/**命令解析、错误处理、退出码Teststests/**易碎测试模式见下文、测试隔离、断言质量Deploymentsrc/Aspire.Hosting.Azure*/**、src/Aspire.Hosting.Docker/**、src/Aspire.Hosting.Kubernetes/**、tests/Aspire.Hosting.*Kubernetes.Tests/**、tests/Aspire.Cli.EndToEnd.Tests/**/Kubernetes*、tests/Aspire.Deployment.EndToEnd.Tests/**Kubernetes/Helm、Docker、Azure 工件及真实部署行为、预置与清理Build/Infraeng/**、*.props、*.targets意外副作用、被破坏的条件逻辑API filessrc/*/api/*.cs严禁手动编辑——若被修改必须标记Extensionextension/**本地化、TypeScript 用法Docs/Configdocs/**、*.md、*.json仅核对准确性这些路径与仓库实际结构完全吻合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 的测试变更对照。对每个非平凡的生产代码变更识别五要素变更的行为—— 使用 diff 中的具体代码路径、方法或配置名描述受影响面—— 哪些用户/系统面能观察到变更公共 API、AppHost 模型、DCP/运行时编排、CLI、Dashboard、部署输出、VS Code 扩展、生成工件、日志/遥测、配置、持久化、网络或安全敏感流回退风险—— 变更可能破坏既有场景的具体方式时序/顺序变化、持久化状态兼容、重启/重试、资源清理、跨资源引用、环境变量、连接字符串、端点 URL、端口分配、平台/容器运行时差异期望的回退覆盖—— 若修复缺失哪些针对性测试或场景测试应当失败或能捕获风险行为的再次变化覆盖缺口—— 受影响但未被 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.yml579 行含groups、conventions、prefilter、ignore、path_rules、affected_project_rules、derived_targets五类匹配器选择器工具tools/SelectTestsTestSelector、TriggerMap、ChangedFileFilter、GraphAffectedProjects、SelectionTrace等类型路由边界回归测试tests/Infrastructure.Tests/TestTriggerMapSelectTestsAcceptanceTests、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 quarantinedtrue \ --filter-not-trait outerlooptrue3.3 测试覆盖审查Test Coverage Review文档规定每次审查都必须评估 PR 是否为被变更的行为类型提供了恰当的测试。纯机械重构、注释、纯文档变更不要求测试但当生产行为变化且 PR 无明确、有说服力的理由时缺失或不足的覆盖必须标记。回退覆盖尤其重要bug 修复与行为变更应包含在修复前会失败的测试而不只是宽泛的快乐路径覆盖或重新生成的快照。文档给出了一张变更类型 → 期望覆盖的映射表变更类型期望的覆盖核心逻辑、资源模型、集成、解析器、校验、错误处理、公共 API 行为匹配的tests/*.*Tests/项目中的单元或集成测试用户可见的 CLI 命令、提示、终端工作流、安装/更新行为、命令输出契约tests/Aspire.Cli.EndToEnd.Tests/下的 CLI 端到端覆盖外加可行的聚焦单元测试Dashboard UI 逻辑、浏览器独有功能行为、认证流、bUnit 无法实际模拟的交互tests/Aspire.Dashboard.Tests/Integration/Playwright/下的 Dashboard Playwright 覆盖外加tests/Aspire.Dashboard.Tests/或tests/Aspire.Dashboard.Components.Tests/的逻辑/组件覆盖纯视觉 CSS、主题、颜色、透明度、光标、交互状态外观无需自动化覆盖不得仅为这些变更要求计算样式、精确颜色或截图断言部署、发布、预置、生成的 Kubernetes/Helm/Bicep/Docker 工件、Azure 资源接线、部署后端点行为tests/Aspire.Deployment.EndToEnd.Tests/下的部署端到端覆盖仅生成工件快照测试不足以证明部署行为VS Code 扩展命令、树视图、调试器流、RPC/DCP/MCP 集成、扩展 UI、通过 VS Code 可见的 CLI 集成extension/src/test-e2e/下的 VS Code 扩展 E2E 覆盖外加可行的extension/src/test/Mocha 单元测试对于部署变更尤其严格仅更新 Helm 图表、Kubernetes YAML、Docker Compose、Bicep、JSON 清单或快照文件只能证明序列化器输出正确若 PR 改变部署行为、资源连通性、预置顺序、基础设施组合、环境变量、端点暴露、健康、清理或升级行为必须寻找一个真正部署并验证场景的部署测试。当专门覆盖缺失且合适形态不明确时可引用相关技能作为参考cli-e2e-testing、dashboard-testing、deployment-e2e-testing、vscode-extension。3.4 该报什么What to Flag15 类问题清单文档列出了审查代理必须标记的实际问题类别Bugs—— 逻辑错误、差一错误、空引用、缺失 await、竞态条件、错误的资源释放Security—— 注入风险、凭据暴露、不安全默认值、OWASP Top 10 违规Correctness—— 相对 PR 描述或既有契约的错误行为以及对用于多语言 SDK 生成的稳定 Aspire Type System (ATS) 面的破坏性变更行为契约变更—— 类型被替换/删除/重构时静默改变的行为契约如先前非法访问会抛异常现在返回默认值弱化的不变量—— 重构中校验被放松如SingleOrDefault被换成FirstOrDefault、Debug.Assert守卫应改为ifthrow、前置条件检查被删除系统边界的缺失错误处理—— 未校验的外部输入、公共 API 入口缺失空检查类型系统已保证非空的不标记性能回退—— 热路径中不必要的分配、N1 查询、阻塞异步调用Task.Result、.Wait()并发问题—— 并发代码中的线程不安全集合、缺失同步、死锁风险时序耦合与初始化安全—— 初始化为null!且必须在使用前调用独立Initialize()的字段、依赖调用顺序的 DI 注册、遗漏调用会导致运行时 NRE 且无编译期保障的模式资源泄漏—— 创建但从未释放的IDisposable对象如CancellationTokenSource、SemaphoreSlim死代码与过期注释—— 描述已不存在行为的注释、未使用变量、带materialize to check count注释但从不检查计数的ToList()仓库约定违规—— 依据 AGENTS.md 规则手动编辑api/*.cs、手动编辑*.xlf、向NuGet.config添加未批准的 feed、修改global.json、用 null而非is null代码注释问题—— 应用 AGENTS.md 的注释准则只标记具体问题注释与代码矛盾、无跟踪链接的 workaround 注释、解析器/协议/日志解析未包含理解边界情况所需的原始形态、隐私/安全敏感行为注释未解释 opt-in/范围/WHY测试问题—— 易碎模式线程不安全的测试 fake、基于日志的就绪检查而非WaitForHealthyAsync()、共享超时预算、硬编码端口、测试中使用Directory.SetCurrentDirectory、注释掉的测试缺失或不足的测试覆盖—— 生产行为变化而无对应面覆盖或 bug 修复缺少修复前会失败的聚焦回退测试。3.5 不该报什么What NOT to Flag.editorconfig或格式化器已处理的风格偏好缺失的 XML doc 注释除非公共 API 完全无文档与无关代码的重构建议缺失 API 文件重新生成开发期预期行为纯文档/纯注释/机械重命名/可证明保持行为的重构缺少测试纯视觉样式变更缺少测试标准 C# API 审查关注点命名、命名空间、框架设计准则、一般 .NET/C# API 破坏性变更——由专用api-review技能处理本技能只检查用于多语言 SDK 生成的稳定 ATS 面含SuppressFinalPackageVersiontrue/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被NewClassT替换后验证依赖OldClass特定行为的所有调用点仍工作正常。3.7 Aspire 领域升级Aspire-domain escalation文档明确先完成通用审查再考虑调用reviewing-aspire-architecture技能。绝不允许仅因 PR 触及 hosting 核心、Azure 集成、Dashboard、CLI、组件、资源类型、App 模型或部署行为就优先调用领域技能。通用审查通过后仅当全部满足以下条件时才进行聚焦架构升级diff 提供正确性问题的具体证据解决该问题依赖本技能规则之外的、有命名的 Aspire 特定契约或生命周期规则通用审查无法从 diff、周边代码、测试与既有注释判断行为是否正确升级可表达为一个聚焦问题附带相关文件、证据、错误的后果以及需要专家知识的原因。禁止为已是具体通用结论的问题、仅高风险代码、寻求第二意见或对更高置信度的广泛期望而升级。保留已完成的通用结论对变更集修订版最多运行一次聚焦升级且只合并净新增的高置信专家结论——领域专家返回后不重跑通用审查。这一升级路径在 .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若结果为非空自动合并已启用且审查包含评论必须警告用户批准很可能在作者处理评论前触发自动合并。提供两个选项仍然批准—— 以 APPROVE 提交自动合并可能立即执行降级为评论—— 以 COMMENT 提交让作者先处理反馈。用户选择选项 2 时使用event: COMMENT而非APPROVE。4.3 发布审查的三步流程创建待定审查mcp_github_pull_request_review_write的create方法不传event参数为每个选中的发现添加行内评论mcp_github_add_comment_to_pending_review将评论放在 diff 的特定行subjectTypeLINE为行级评论FILE为文件级评论sideRIGHT表示针对新代码path相对文件路径linediff 中的行号body问题与修复方式的简洁描述提交审查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.ymlActiveIssue用于因已知 bug 持续失败的测试完全跳过OuterloopTest用于长耗时/资源密集型测试运行于tests-outerloop.yml。六、实践要点速查阶段关键动作关键命令/工具解析请求提取 PR 号/URL 与仓库无 PR 号时查当前分支gh pr view --json number,title,headRefName分支准备阻塞匹配分支则继续否则二选一gh pr checkout number --repo microsoft/aspire收集上下文PR 元数据、文件列表、diff、既有评论mcp_github_pull_request_readget/get_files/get_diff/get_review_comments或ghCLI 回退分类变更按领域表确定审查深度领域 → 路径映射表影响分析变更行为 → 受影响面 → 回退风险 → 期望覆盖 → 缺口五要素模板条件测试选择追溯消费方检查触发映射六同步eng/github-ci/test-trigger-map.yml、tools/SelectTests --explain测试覆盖审查按变更类型映射期望覆盖变更类型 → 覆盖映射表发现问题只报 15 类实际问题不报风格What to Flag 清单架构升级通用审查完成后按 4 条件聚焦升级.agents/skills/reviewing-aspire-architecture/SKILL.md呈现与发布编号列表让用户分诊自动合并检查三步发布mcp_github_pull_request_review_write七、总结.agents/skills/code-review/SKILL.md是一份高度工程化的 PR 审查技能定义。它的核心设计哲学可以概括为三点只报问题15 类可标记问题与 7 类禁止标记事项划定了审查代理的精确行为边界杜绝风格噪音与无证据猜测证据驱动每条结论都要落到 diff 中的具体行、变量或条件并给出修复方向流程受控从本地分支准备阻塞步骤、按领域分类、影响分析驱动测试覆盖审查、条件测试选择映射审计到升级路径与自动合并安全门——每个环节都有明确的顺序约束与决策条件。这套技能与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考