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