Astro Triage 流程解析diagnose.md 的源碼診斷工作流與 report.md 協(xié)作機制【免費下載鏈接】astroThe web framework for content-driven websites. ?? Star to support our work!項目地址: https://gitcode.com/GitHub_Trending/as/astro本文聚焦 Astro 倉庫.agents/skills/triage/diagnose.md定義的“診斷Diagnose”技能它規(guī)定了一個已復現(xiàn) Bug 在 Astro 源碼中被定位根因的完整工作流——從讀取復現(xiàn)報告、定位packages/下的源文件、添加插樁日志到還原現(xiàn)場并輸出帶置信度診斷結(jié)論的report.md。讀完本文你將掌握這條 LLM Agent 診斷流水線的每個步驟約束、服務端管理規(guī)則以及它與 reproduce/verify/fix 技能之間通過report.md傳遞上下文的協(xié)作機制。1. 在 Triage 流水線中的定位diagnose.md不是獨立文檔而是 triage 技能SKILL.md四步流水線中的第二步。整個流程為Reproducereproduce.md搭建最小復現(xiàn)項目寫出report.mdDiagnosediagnose.md在源碼中定位根因向report.md追加診斷章節(jié)Verifyverify.md判斷行為是 Bug 還是有意設(shè)計Fixfix.md實現(xiàn)最小修復并補測試、changeset。diagnose.md開頭對兩個硬約束的定義決定了它與其他技能的關(guān)系CRITICAL必須寫報告無論診斷成功與否——找不到根因、遇到報錯、結(jié)論不確定——都必須在結(jié)束前讀取并追加report.md。原文強調(diào)“orchestrator 和下游技能依賴這個文件判斷發(fā)生了什么”如果診斷結(jié)束而沒寫報告整條流水線會“靜默失敗”。SCOPE只做診斷完成本工作流即結(jié)束不做更大范圍的問題驗證、不修復問題、不派生子任務/子代理。另外orchestrator 會根據(jù)診斷產(chǎn)出的置信度決定走向confidence 為low時直接跳到 Output 結(jié)束 triagemedium/high才進入 verify 階段見 SKILL.md Step 2。因此診斷輸出的置信度字段實際上是一條流程控制信號而不只是描述性標簽。2. 前置變量Prerequisites文檔聲明了四個貫穿全流程的變量它們可以由 orchestrator 作為 args 傳入也可以在獨立運行時從對話上下文推斷變量說明倉庫依據(jù)triageDir復現(xiàn)項目所在目錄如triage/issue-123未傳入時從先前對話推斷pnpm-workspace.yaml 將triage/*聲明為 pnpm workspace 包因此復現(xiàn)項目能直接鏈接到 monorepo 內(nèi)的astro源碼包issueDetailsGitHub API 的 issue 詳情 payload若上下文缺失可運行g(shù)h issue view ${issue_number}從 GitHub 拉取SKILL.md 中同樣接受issueTitle/issueBody作為輸入report.md位于triageDir內(nèi)、可能已存在的文件包含之前所有技能寫入的完整上下文由 reproduce 技能創(chuàng)建diagnose 只追加不覆蓋Astro Compiler 源碼withastro/compiler倉庫可能被克隆到倉庫根的.compiler/已被 gitignore。若存在則納入診斷范圍——有些 Bug 源于編譯器而非packages/例如 HTML 解析、.astro文件轉(zhuǎn)換。當堆棧或調(diào)查發(fā)現(xiàn)指向編譯器行為時應到.compiler/中查相關(guān)源碼.gitignore 第 3 行的/.compiler/確認該目錄被刻意忽略fix.md 進一步說明該克隆“僅作參考”reference only未接入 monorepo 依賴無法端到端測試從源碼結(jié)構(gòu)看這一設(shè)計解決了 Astro 倉庫診斷的特殊難點.astro文件先被編譯器轉(zhuǎn)成 JS 模板再進入packages/astro的運行時/構(gòu)建邏輯一條渲染類 Bug 的堆?？赡芸缭絻蓚€代碼庫。文檔因此要求診斷者具備“先判斷 Bug 屬于哪一層”的意識。3. Step 1審閱復現(xiàn)結(jié)果含提前退出診斷的第一步是讀取triageDir/report.md。文檔給出了明確的提前退出skip規(guī)則若report.md顯示 Bug 未復現(xiàn)或被跳過識別關(guān)鍵詞could not reproduce、SKIP REASON、skipped: true則向report.md追加DIAGNOSIS SKIPPED: No reproduction并返回confidence: null立即結(jié)束。這條規(guī)則與下游 fix.md 的“低置信度路徑”confidence 為low或null時不嘗試改代碼只留下失敗測試和// TRIAGE:路標注釋嚴格對應——診斷階段不猜測修復階段就不會基于猜測下手。需要重新觸發(fā)一次復現(xiàn)來親眼看到報錯時標準命令是pnpm -C triageDir run build # 或 dev/previewpnpm -C的用法與 AGENTS.md 中的 monorepo 約定一致在 packages/examples/triage 目錄下執(zhí)行項目本地腳本時必須帶-C。4. Step 2定位相關(guān)源文件利用 Step 1 收集到的錯誤信息、堆棧和其他復現(xiàn)細節(jié)圈定packages/中可能涉及的源文件。這一步之所以可行依賴于 AGENTS.md 中明確的 dist→src 映射規(guī)則node_modules/astro/dist/...→packages/astro/src/...node_modules/astrojs/react/...→packages/integrations/react/src/...也就是說復現(xiàn)項目triageDir跑的是本地 workspace 鏈接的 Astro 包錯誤堆棧里出現(xiàn)的dist/路徑可以直接翻譯回packages/下的 TypeScript 源碼進行閱讀和插樁。這也是為什么 triage 復現(xiàn)項目要接進 pnpm workspacetriage/*在 pnpm-workspace.yaml 中聲明而不是安裝 npm 上發(fā)布的版本——只有源碼版 Astro 才能被插樁調(diào)試。5. Step 3用插樁Instrumentation還原代碼路徑這是 diagnose 技能的核心手段向源碼添加console.log來理解實際執(zhí)行路徑。文檔給出的示例直接指向構(gòu)建入口// In packages/astro/src/core/build/index.ts console.log([DEBUG] Building page:, pagePath); console.log([DEBUG] Props:, JSON.stringify(props, null, 2));示例文件確實存在——packages/astro/src/core/build/index.ts 就是astro build的構(gòu)建入口導出build函數(shù)負責resolveConfig、createVite、路由清單與靜態(tài)構(gòu)建流程在其中打日志可以觀察每一頁構(gòu)建時的入?yún)ⅰＬ砑尤罩竞笪臋n規(guī)定的完整循環(huán)是重新構(gòu)建包例如pnpm -C packages/astro build——這對應 AGENTS.md 的關(guān)鍵事實“Edits to source files take effect after rebuilding the package viapnpm build”改了src/不重新構(gòu)建復現(xiàn)項目里跑的還是舊的dist/重跑復現(xiàn)例如pnpm -C triageDir build|dev|preview觀察調(diào)試輸出。迭代目標是用三個問題收斂正在執(zhí)行哪條代碼路徑傳入了什么數(shù)據(jù)邏輯在哪里偏離了預期行為服務器管理規(guī)則防“時間預算”耗盡文檔用一整段約束 dev server 的生命周期管理這些規(guī)則直接映射到倉庫工具鏈的真實能力重啟前必須先停舊服務器pnpm -C triageDir dev stop。這套dev --background / dev logs / dev status / dev stop子命令在 AGENTS.md 的 “Background Dev Servers” 一節(jié)有完整說明失敗兩次即放棄服務器連續(xù)兩次起不來就停止重試用已有數(shù)據(jù)寫出診斷不要在服務器重啟上空轉(zhuǎn)。這與 SKILL.md 的總則“Do not get stuck on infrastructure problems……bail out after 2 attempts”一致優(yōu)先用astro build能用構(gòu)建期復現(xiàn)就避免 dev/preview從根上繞開服務器生命周期問題永遠不要用后臺化用pnpm -C triageDir dev --background在 CI 環(huán)境會掛起。插樁后的現(xiàn)場還原循環(huán)結(jié)束后有一條不可妥協(xié)的收尾規(guī)則用git checkout -- file撤掉所有插樁。文檔的原話是“Debug logs must not leak into downstream steps”——遺留的console.log會污染后續(xù)的 verify/fix 階段fix.md 的 Step 11 清理清單里也把“Debug code,console.logs”列為必須回滾項。診斷階段對源碼樹是“借而不留”的關(guān)系。6. Step 4確定根因并書面化當代碼路徑被理解后診斷必須回答四個問題哪個文件包含 Bug代碼做錯了什么——具體的邏輯錯誤為什么表現(xiàn)為觀察到的現(xiàn)象——錯誤如何外顯修復應該怎么做——高層思路注意只給思路不給補丁實現(xiàn)屬于 fix 技能。同時要求考慮三個延伸問題這是不是近期變更引入的回歸是否影響其他相似用例有沒有需要留意的邊界情況文檔還有兩條非?！肮こ涛幕笔降募s束禁止以“刪掉用戶依賴”作為修復建議。原文“Never suggest removing a users dependency (adapters, framework integrations, features like MDX or DB) as a fix, those are things the user needs.” 修復必須在用戶現(xiàn)有技術(shù)棧內(nèi)成立。這條禁令在 fix.md Step 3 中被原樣重申說明它是整條 triage 流水線的一等約束語氣校準Tone calibration根因描述要事實化、不戲劇化。除非證據(jù)真正支持避免 “critical flaw”“fundamentally broken”“severe vulnerability” 之類措辭。文檔給的例子很直白“缺一個 null 檢查就是缺一個 null 檢查不是‘渲染管線中的關(guān)鍵疏漏’?！?診斷的目標是幫維護者理解哪里錯了并導向修復而不是制造恐慌。7. Step 5寫回 report.md輸出契約診斷結(jié)果以追加新章節(jié)的方式寫入report.md不覆蓋 reproduce 技能寫的內(nèi)容章節(jié)必須包含根因、帶行號的影響文件、代碼路徑的詳細解釋、插樁結(jié)果以及建議的修復方向——文檔明確說這樣做的目的是“help the fix skill work faster”。報告同時承擔了“最終 GitHub 評論原料”的角色評論由下游 comment 技能生成因此硬性要求包含四項根因解釋哪些文件、什么邏輯錯了、為什么受影響文件路徑及行號建議的修復方向置信度high/medium/low與所有保留意見caveats。這套“文件即交接”的模式在四個 triage 技能里完全對稱每個技能都聲明 “MUST always readreport.mdand append toreport.mdbefore finishing”reproduce.md 更直言 “Downstream skills will NOT have access to the original issue —report.mdis their only source of context”。report.md實際上是一條追加式日志append-only log把 issue 正文、環(huán)境、復現(xiàn)步驟、報錯棧、診斷、驗證與修復結(jié)果全部沉淀在triageDir中。由于/triage/在 .gitignore 中被忽略第 2 行這些中間產(chǎn)物不會進入版本庫每個 issue 的 triage 目錄天然隔離。8. 評測如何驗證這套工作流diagnose 技能的行為由 live-model 評測守護。.agents/skills/triage/evals/evals.json 定義了三個用例其中兩個恰好覆蓋了本文講的兩類分支用例 1完整 dry-run合成 Bug “getTimeStat(0, 119999)打印1m 60s”。斷言要求診斷“解釋秒余數(shù)取整會產(chǎn)生 60”并給出 medium/high 置信度、驗證結(jié)論為bug、修復保證分鐘格式的秒位在 0–59 且 60 秒進位、回歸測試斷言getTimeStat(0, 119999)返回2m 0s、changeset 為astro: patch。值得注意的是該用例中的getTimeStat并非虛構(gòu)——它真實存在于構(gòu)建計時工具 packages/astro/src/core/build/util.ts且packages/astro/test/units/build/static-build.test.ts中有對應單測說明評測集是圍繞真實源碼路徑構(gòu)造的用例 2提前退出只在 Cloudflare Pages 上出現(xiàn)的 binding 問題斷言復現(xiàn)階段直接以host-specific分類跳過、寫完整報告、不執(zhí)行任何診斷/修復動作——這正是 reproduce.md 的 early-exit 機制用例 3intended-behaviorAstro.url.hash在含 fragment 的 URL 下為空期望驗證階段給出intended-behavior高置信結(jié)論瀏覽器不把 fragment 發(fā)給服務器不進入修復。運行方式見 .agents/evals/README.md先pnpm eval:skills:validate校驗所有 manifest再如ANTHROPIC_API_KEY... pnpm eval:skills -t triage跑單個技能用例每個用例消耗一次被測模型加一次評判模型的運行評測在臨時工作區(qū)中進行且結(jié)束后刪除。9. 小結(jié)diagnose 技能的設(shè)計要點把 diagnose.md 的約束匯總成一份可執(zhí)行清單報告優(yōu)先無論成敗退出前必須追加report.md根因、文件行號、修復方向、置信度范圍鎖定只診斷不驗證、不修復、不派生子代理未復現(xiàn)則追加DIAGNOSIS SKIPPED: No reproduction并以confidence: null返回雙層代碼庫意識packages/是主診斷范圍堆棧指向編譯器行為HTML 解析、.astro轉(zhuǎn)換時擴展到.compiler/插樁—構(gòu)建—重跑—觀察四步循環(huán)利用 workspace 鏈接讓triage/下的復現(xiàn)項目跑本地源碼 Astro用pnpm -C packages/astro build使插樁生效服務器紀律先dev stop再起新服務、失敗兩次即罷手、優(yōu)先build、禁用現(xiàn)場還原git checkout -- file撤掉全部console.log不讓調(diào)試痕跡流入下游結(jié)論克制根因描述事實化禁止建議刪除用戶依賴置信度字段直接決定流水線是否繼續(xù)。這套文檔與 reproduce.md、verify.md、fix.md 共同構(gòu)成 Astro 倉庫內(nèi)一套可被 LLM Agent 逐步執(zhí)行的 Bug 分診標準作業(yè)程序SOPreport.md是唯一上下文載體triageDir是唯一工作現(xiàn)場而 diagnose 負責其中最關(guān)鍵的一環(huán)——把“能穩(wěn)定復現(xiàn)的異?！狈g成“帶行號的根因定位”?！久赓M下載鏈接】astroThe web framework for content-driven websites. ?? Star to support our work!項目地址: https://gitcode.com/GitHub_Trending/as/astro創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考