Astro Triage 流水线中的 Bug 复现阶段reproduce 技能从 Issue 校验到 report.md 输出的完整工作流【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astroAstro 仓库内置了一套面向 AI Agent 的 bug 分诊triage流水线其中 reproduce.md 定义了流水线的第一个阶段把一个 GitHub issue 变成可在本地运行的最小复现项目并产出供下游 Agent 使用的report.md。本文围绕该文档的完整工作流展开——输入校验、六类提前退出条件、五类复现项目的搭建方式、复现验证步骤、服务器生命周期管理规则以及report.md的输出契约并结合 pnpm-workspace.yaml、.gitignore 与 examples/ 模板说明其在本仓库 monorepo 中的落地机制。读完后你可以理解 Astro 团队如何让 Agent 在有限时间预算内可靠地判定“一个 issue 是否真实可复现”。复现阶段在整体流水线中的位置Triage 流水线由 SKILL.md 编排共四个阶段Reproduce本文主题读取并遵循 reproduce.md隔离上下文中执行Diagnose读取 diagnose.md在packages/源码中定位根因Verify读取 verify.md判定行为是 bug 还是有意设计Fix读取 fix.md实现最小修复、补单测、创建 changeset。复现阶段的输出结果直接决定后续走向issue 被跳过host-specific、版本过旧等→ 直接进入 Output无法复现→ 进入 Output成功复现→ 继续诊断阶段。各阶段之间不共享对话上下文唯一的上下文载体是triageDir目录下的report.md。reproduce 文档对此有明确的强约束CRITICAL无论结果如何——即使复现失败、遇到意外错误或中途放弃——都必须写出report.md因为编排器和下游技能依赖该文件判断发生了什么如果没写整条流水线会“静默失败”。同时文档用 SCOPE 约束了本阶段的边界只负责复现完成工作流后立即结束不做根因诊断、不修 bug、不派生子任务。两个前置变量文档定义了贯穿全流程的两个变量可由编排器以 args 传入也可在独立运行时从对话上下文推断triageDir— 复现项目所在的目录例如triage/issue-123。未传入时应从之前的对话中推断issueDetails— GitHub API 返回的 issue 详情载荷必须由用户显式提供或来自之前的工具调用结果若缺失可运行gh issue view ${issue_number}直接从 GitHub 拉取。仓库侧为这套约定提供了配套支持pnpm-workspace.yaml 的 workspace 列表中包含triage/*意味着每个triage/gh-issue_number目录都会被纳入 pnpm workspace同时 .gitignore 中有/triage/条目保证这些一次性复现项目不会污染仓库状态。Step 1确认 Bug 细节首要任务是确认issueDetails已就位否则直接失败——没有细节就无法分诊。拿到细节后需要仔细阅读四部分信息bug 描述以及期望行为与实际行为的对照issue 中提供的复现步骤环境细节特别是astro info输出中的 Astro 版本评论区中可能澄清问题的讨论。Step 2提前退出条件Early Exit在动手复现之前先判断该 issue 是否因“沙箱复现环境的限制”而应被跳过。命中任一条件就跳到 Step 5在report.md中写明跳过原因skip details。一个关键的动态规则评论会使早期退出失效。提前退出只有在该 issue 的后续评论没有“推翻”它时才成立。文档给出的例子若原报告者使用的是 Astro 3.0初次运行会以unsupported-version退出但在一次后续运行中如果有评论者发布了基于最新 Astro 版本的类似复现那么这就不再是有效的提前退出而应继续走完整工作流。文档明确支持的六类提前退出条件如下条件标识判定依据非可执行报告not-actionableissue 不是 bug 报告。该工作流只分诊 bug——功能请求、建议、讨论都不在此范围内缺少细节missing-detailsissue 缺少有效复现见 Step 3 的复现形式列表或缺少对用户期望结果的描述例如 issue 模板中“期望结果”一节未填写。两者都是成功复现和后续验证所必需的不支持的 Astro 版本unsupported-versionbug 针对 Astro 4.x 或更早版本。从astro info输出或 package.json 中查找版本号宿主平台专属问题host-specificbug 只能在特定托管平台Vercel、Netlify、Cloudflare、Deno Deploy 等上复现。信号包括issue 引用了宿主专属 adapterastrojs/vercel、astrojs/netlify、astrojs/cloudflare或 bug 只“在生产环境/部署后”出现在 dev 与本地 preview 构建中均无法复现运行时专属问题unsupported-runtimebug 只出现在 Bun 或 Deno 上。沙箱只支持 Node.js维护者覆盖maintainer-override仓库维护者在评论中表示不应在此复现该 issue。判断评论者是否为维护者检查issueDetails中该评论的authorAssociation字段值为MEMBER、COLLABORATOR或OWNER即视为维护者Step 3搭建复现项目每份 bug 报告都应包含某种形式的复现。复现项目放入triageDir例如triage/gh-123未提供triageDir时默认为triage/gh-issue_number。文档按 issue 提供的复现形式分五种情况处理。形式一StackBlitz 项目 URLhttps://stackblitz.com/edit/...用stackblitz-clone下载到triageDirnpx stackblitz-clonelatest stackblitz-url triageDir形式二StackBlitz GitHub URLhttps://stackblitz.com/github/...这是 StackBlitz 上常见的“在 StackBlitz 中打开 GitHub 仓库”的专用 URL。收到此类链接时解析出 GitHub 的 org 与 repo 名然后按下面的“GitHub URL”方式处理。形式三GitHub 仓库 URLhttps://github.com/...克隆到 triage 目录并删除.git目录以避免与宿主仓库冲突git clone https://github.com/owner/repo.git triageDir rm -rf triageDir/.git若 issue 中指明了特定分支或子目录在删除.git之前先 checkout 该分支或只拷贝相关子目录。形式四Gist URLhttps://gist.github.com/通过 GitHub API 拉取 gist 内容以理解复现curl -s https://api.github.com/gists/gist-id此时往往仍需要从零搭建一个项目走下面的手动步骤回退路径再把 gist 中的文件应用进去。形式五手动步骤无复现 URL若没有提供复现 URL则按 issue 作者给出的手动步骤操作未指明模板时默认使用仓库的minimal模板# 1. 列出可用的示例模板 ls examples/ # 2. 删除所选模板的 node_modules避免 cp -r 出问题 rm -rf examples/template/node_modules # 3. 将所选模板拷贝到 triage 目录 cp -r examples/template triageDir # 4. 在工作区根目录重新安装补回缺失的 node_modules 依赖 pnpm install --no-frozen-lockfile创建后用cat triageDir/package.json验证项目落在正确位置。为什么pnpm install --no-frozen-lockfile能把复现项目“接进” monorepo从 pnpm-workspace.yaml 可以看到triage/*是 workspace glob且配置了preferWorkspacePackages: true与linkWorkspacePackages: true——因此复现项目如 examples/minimal/package.json 中声明的astro依赖在 workspace 根目录安装后会优先解析到本仓库packages/astro的源码版本而非注册表中的已发布包。这正是 triage 工作流能够针对当前检出中的代码验证 bug 的关键同时--no-frozen-lockfile允许为复现项目新增依赖如astrojs/react等集成时更新锁文件。复现项目搭好后按 issue 需要最小化地改造它更新astro.config.mjs中必要的配置变更增改依赖或 Astro 集成astrojs/react等增改触发 bug 的页面、组件、中间件等增改 issue 中提到的其他文件。文档强调保持复现尽可能小——只添加 issue 报告者记录为触发 bug 所必需的内容。Step 4在 Triage 项目中尝试复现可使用一切可用工具——pnpm run dev|build|preview|test、curl、agent-browser等。复现验证分三步触发 bug按 issue 的复现步骤操作确认 bug 出现验证基线移除或反转触发代码确认项目在不带触发代码时工作正常。这是防止误报的保护——如果去掉触发代码项目仍然是坏的说明问题可能出在你的环境搭建而不是报告中的 bug记录观察记录精确的错误信息与堆栈、触发问题的具体命令以及问题是稳定复现还是间歇性的。服务器管理规则dev/preview 服务器经常是复现必需的但服务器问题不能吃掉时间预算。文档给出五条硬性规则连续两次启动失败就放弃Bail out after 2 failed server starts。若astro dev --background或手动服务器命令连续失败两次停止重试不要带着各种变体无限循环。用已有信息写报告。重启前必须先停掉旧服务器。启动新 dev 服务器前先执行pnpm -C triageDir dev stop若无效回退到pkill -f astro dev\|astro preview\|node.*entry.mjs再失败就换一个端口--port 4322而不是与残留进程死磕。一轮复现就够One reproduction run is enough。确认或否认 bug 之后不要为了微调配置的再测而重启服务器。追加测试属于 diagnose 阶段不属于这里——写完发现就继续。尽量用astro build而非 dev/preview。构建期复现可以完全绕开服务器生命周期问题。只有当 bug 明确依赖运行中的服务器HMR、运行时 SSR、请求处理时才用 dev/preview。永远使用 Astro 的后台 dev 服务器——绝不用。不要用后台化服务器例如pnpm dev 这在 CI 中会挂起。dev 服务器生命周期统一用pnpm -C triageDir dev --background/pnpm -C triageDir dev stop管理。这些规则与 SKILL.md 的全局原则一脉相承不要在基础设施问题上卡死——服务器起不来、端口被占、CI 环境缺工具时两次尝试后就用已有数据写报告一份带着扎实发现的“部分报告”永远比因耗尽时间在僵死进程上而交不出报告更有价值。Step 5写出report.mdreport.md写到 triage 目录中。它的定位很明确写给下一个 LLM 阶段看的详细内部报告不是写给人看的——下游技能访问不到原始 issuereport.md是它们唯一的上下文来源。因此要写得详尽包含原始 issue 的标题、描述及 issue 正文中一切相关细节。“包含太多上下文”永远好过“太少”没人知道哪条信息会在后续例如在代码库中找修复时派上用场完整的环境细节所有已尝试的步骤及其结果完整的错误信息与堆栈对代码库的观察、关于根因的猜想任何能让下一阶段工作更快的信息。报告还必须包含日后由 comment 技能生成最终 GitHub 评论所需的全部信息环境细节包版本、Node.js 版本、包管理器复现步骤编号列表期望结果与实际结果的对照错误信息与堆栈该 issue 是被复现、未复现还是跳过以及原因。从下游技能可以印证这份契约的分量diagnose.md 第一步就是读report.md未复现/跳过时直接追加 “DIAGNOSIS SKIPPED: No reproduction”fix.md 则在未复现时追加 “FIX SKIPPED: Not reproduced” 并返回fixed: false。所有阶段都只读、只追加同一个文件形成一条以report.md为总线的单向信息流。仓库中的可验证证据这份工作流不是停留在纸面的提示词仓库中有多处相互印证的实现与验证设施workspace 接线pnpm-workspace.yaml 中的triage/*glob 加上preferWorkspacePackages: true/linkWorkspacePackages: true使triage/gh-n下的复现项目在 workspace 根目录执行pnpm install --no-frozen-lockfile后链接到packages/下的源码目录可丢弃性.gitignore 中的/triage/与.compiler/条目保证复现项目与可选克隆的编译器源码withastro/compiler供 diagnose.md 与 verify.md 在涉及.astro文件转换时查阅都不进入版本历史默认模板examples/minimal/ 即“手动步骤”回退路径的默认起点其 package.json 声明node 22.12.0与astro依赖对应 fix 阶段要求运行时代码面向 Node.js22.12.0的约束技能评测evals/evals.json 中第 2 条评测“Runtime binding is undefined only after deploying to Cloudflare Pages”直接验证了本文 Step 2 的host-specific提前退出断言要求triage/evals/cloudflare-binding/report.md存在且明确分类为host-specific跳过且不得执行任何项目搭建、安装、构建、起服务器或诊断动作——正是“命中提前退出后跳过 Step 3/4、直接写 report.md”这一流程的自动化验证。小结reproduce.md是 Astro triage 流水线的守门阶段其设计要点可以归纳为四条输入校验不通过就失败、命中六类提前退出条件就快速止损并如实记录复现项目按 issue 提供的五种形式StackBlitz URL、StackBlitz GitHub URL、GitHub URL、Gist、手动步骤落到triageDir并通过 workspace 机制链接到本仓库源码复现验证遵循“触发—基线—记录”三步与严格的服务器管理规则防止在僵死进程上耗尽预算最终无论成败report.md都必须承载 issue 全量上下文、环境细节、步骤结果与错误证据成为 diagnose、verify、fix 各阶段以及最终 GitHub 评论的唯一事实来源。理解这套契约就能理解 Astro 如何用可验证的 Agent 技能把“issue 是否可复现”变成一个有明确边界、可评测、可追溯的自动化环节。【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考