使用評估驅動開發改善 AI 應用程式。定義評估標準、對應用程式進行儀器化、建立黃金資料集、觀察並評估應用程式執行、分析結果，並產出具體的行動改善計畫。 當使用者要求為任何呼叫 LLM 模型的 Python 專案設定 QA、新增測試、新增評估、評估、基準測試、修正錯誤行為、改善品質或進行品質保證時，一律使用此技能。
Python LLM 應用程式的評估驅動開發
你正在建立一個自動化評估管線，用於端對端測試 Python 為基礎的 AI 應用程式——以真實使用者相同的方式執行，使用真實輸入——然後使用評估器對輸出進行評分，並透過 pixie test 產生通過/失敗結果。
你測試的是應用程式本身——它的請求處理、上下文組裝（如何收集資料、建立提示、管理對話狀態）、路由和回應格式化。應用程式使用 LLM，這使得輸出具有非確定性——這就是為什麼你使用評估器（LLM 作為評審、相似度分數）而不是 assertEqual——但測試的對象是應用程式的程式碼，而不是 LLM。
在評估期間，應用程式本身的程式碼會真實執行——路由、提示組裝、LLM 呼叫、回應格式化——沒有任何東西被模擬或替換。但應用程式從外部來源（資料庫、快取、第三方 API、語音串流）讀取的資料會透過儀器化替換為測試指定的值。這表示每個測試案例都能精確控制應用程式看到的資料，同時仍執行完整的應用程式程式碼路徑。
規則：應用程式的 LLM 呼叫必須發送到真實的 LLM。 不要用假實作來取代、模擬、替換或攔截 LLM。LLM 是核心價值產生元件——取代它會使評估變成同義反覆（你同時控制輸入和輸出，因此分數毫無意義）。如果專案的測試套件包含 LLM 模擬模式，那些是專案本身單元測試用的——不要將它們用於評估 Runnable。
交付成果是一個可運作的 pixie test 執行，並帶有真實分數——不是計畫，不只是儀器化，不只是資料集。
此技能在於執行工作，而非描述它。閱讀程式碼、編輯檔案、執行指令、建立可運作的管線。
開始之前
首先，啟用虛擬環境。識別專案的正確虛擬環境並啟用它。虛擬環境啟用後，執行技能資源中包含的 setup.sh。
該腳本會將 eval-driven-dev 技能和 pixie-qa Python 套件更新到最新版本，如果尚未初始化則初始化 pixie 工作目錄，並在背景啟動網頁伺服器以顯示使用者更新。
設定錯誤處理——哪些可以跳過 vs. 哪些必須成功：
- 技能更新失敗 → 可以繼續。現有的技能版本已足夠。
- pixie-qa 升級失敗但已安裝 → 可以繼續使用現有版本。
- pixie-qa 未安裝且安裝失敗 → 停止。 請求使用者協助。沒有
pixie套件就無法繼續工作流程。 pixie init失敗 → 停止。 請求使用者協助。pixie start（網頁伺服器）失敗 → 停止。 請求使用者協助。檢查 pixie 根目錄中的server.log以取得診斷資訊。常見原因：連接埠衝突、缺少依賴項、環境緩慢。如果沒有網頁伺服器，請勿繼續——使用者需要它來查看評估結果。
工作流程
直接依序執行步驟 1 到 6，不要中斷。不要在中間步驟請求使用者確認——自行驗證每個步驟並繼續。
如何工作——在執行任何其他操作之前閱讀此內容：
- 一次只做一個步驟。 只閱讀當前步驟的指示。在處理步驟 1 時，不要閱讀步驟 2 到 6。
- 僅在步驟指示你時才閱讀參考資料。 每個步驟會指定一個特定的參考檔案。在到達該步驟時才閱讀它——不要提前。
- 立即建立產出物。 在閱讀子步驟的程式碼後，在繼續之前寫入該子步驟的輸出檔案。不要在多個子步驟中累積理解後才寫入任何內容。
- 驗證，然後繼續。 每個步驟都有一個檢查點。驗證它，然後繼續下一個步驟。在驗證當前步驟時，不要規劃未來的步驟。
何時停止並請求協助：
有些障礙無法也不應該繞過。當你遇到以下任何情況時，立即停止並請求使用者協助——不要嘗試解決方法：
- 應用程式因缺少環境變數或設定而無法執行：應用程式需要未設定且無法推斷的環境變數或設定。不要透過模擬、偽造或取代應用程式元件來繞過——評估必須執行真實的生產程式碼。請求使用者修正環境設定。
- 表示專案損壞的匯入失敗：如果應用程式的核心模組因缺少系統依賴項或不相容的 Python 版本（而不僅僅是你可以安裝的缺少 pip 套件）而無法匯入，請求使用者修正專案設定。
- 不明確的進入點：如果應用程式有多個同樣合理的進入點，且專案分析未釐清哪個最重要，請求使用者指定目標。
你應該自行解決的障礙（不要詢問）：缺少的 Python 套件（安裝它們）、缺少的 pixie 套件（安裝它）、連接埠衝突（選擇不同的連接埠）、檔案權限問題（修正它們）。
依序執行步驟 1 到 6。 如果使用者的提示明確表示早期步驟已完成（例如「執行現有測試」、「重新執行評估」），則跳到適當的步驟。如有疑問，從步驟 1 開始。
步驟 1：了解應用程式並定義評估標準
首先，檢查使用者的提示以了解特定需求。 在閱讀應用程式程式碼之前，檢查使用者要求的內容：
- 參考文件或規格：提示是否提到要遵循的檔案（例如「遵循 EVAL_SPEC.md 中的規格」、「使用 REQUIREMENTS.md 中的方法論」）？如果是，首先閱讀該檔案——它可能指定資料集、評估維度、通過標準或方法論，這些會覆蓋你的預設值。
- 指定的資料集或資料來源：提示是否參考特定的資料檔案（例如「使用 eval_inputs/research_questions.json 中的問題」、「使用 call_scenarios.json 中的情境」）？如果是，閱讀那些檔案——你必須將它們用作評估資料集的基礎，而不是編造通用的替代方案。
- 指定的評估維度：提示是否命名了特定的品質面向來評估（例如「評估事實正確性、完整性和偏見」、「測試身份驗證和工具呼叫正確性」）？如果是，每個命名的維度必須在你的測試檔案中有對應的評估器。
如果提示指定了上述任何內容，它們具有優先權。在繼續之前閱讀並納入它們。
步驟 1 有三個子步驟。每個子步驟閱讀自己的參考檔案並產生自己的輸出檔案。在開始下一個子步驟之前，完全完成每個子步驟。
子步驟 1a：專案分析
參考資料：立即閱讀
references/1-a-project-analysis.md。
在查看程式碼結構或進入點之前，了解這個軟體在現實世界中的用途——它的目的、它的使用者、真實輸入的複雜性以及它失敗的地方。這種理解驅動所有下游決策：哪些進入點最重要、要定義哪些評估標準、要使用哪些追蹤輸入以及要建立哪些資料集項目。在繼續之前寫入詳細的上下文檔案。注意：專案可能包含 tests/、fixtures/、examples/、模擬伺服器和文件——這些是專案自己的開發基礎設施，而不是你的評估管線的資料來源。在獲取追蹤輸入和資料集內容時忽略它們。
檢查點：已寫入
pixie_qa/00-project-analysis.md——涵蓋軟體的功能、目標使用者、能力清單（如果專案有，至少 3 個能力）、真實輸入特徵以及困難問題/失敗模式（至少 2 個）。
子步驟 1b：進入點與執行流程
參考資料：立即閱讀
references/1-b-entry-point.md。
閱讀原始碼以了解應用程式如何啟動以及真實使用者如何呼叫它。使用 pixie_qa/00-project-analysis.md 中的能力清單來優先排序進入點——專注於執行最有價值能力的進入點，而不僅僅是找到的第一個。在繼續之前寫入詳細的上下文檔案。
檢查點：已寫入
pixie_qa/01-entry-point.md——涵蓋進入點、執行流程、使用者面對的介面和環境需求。
子步驟 1c：評估標準
參考資料：立即閱讀
references/1-c-eval-criteria.md。
定義應用程式的使用案例和評估標準。從 pixie_qa/00-project-analysis.md 中的能力清單推導使用案例。從困難問題/失敗模式推導評估標準——而不是通用的品質維度。使用案例驅動資料集建立（步驟 4）；評估標準驅動評估器選擇（步驟 3）。在繼續之前寫入詳細的上下文檔案。
檢查點：已寫入
pixie_qa/02-eval-criteria.md——涵蓋使用案例、評估標準及其適用範圍。尚未閱讀步驟 2 的指示。
步驟 2：儀器化、執行應用程式並擷取參考追蹤
步驟 2 有三個子步驟。每個子步驟閱讀自己的參考檔案。在開始下一個子步驟之前，完全完成每個子步驟。
子步驟 2a：使用 wrap 進行儀器化
參考資料：立即閱讀
references/2a-instrumentation.md。
在應用程式的資料邊界處新增 wrap() 呼叫，以便評估框架可以注入受控輸入並擷取輸出。這使得應用程式可測試，而無需更改其邏輯。
檢查點：在所有資料邊界處新增了
wrap()呼叫。來自pixie_qa/02-eval-criteria.md的每個評估標準都有對應的資料點。
子步驟 2b：實作 Runnable
參考資料：立即閱讀
references/2b-implement-runnable.md。
編寫一個 Runnable 類別，讓評估框架可以像真實使用者一樣呼叫應用程式。Runnable 應該很簡單——它只是將應用程式的真實進入點連接到框架介面。如果它變得複雜，表示有問題。
檢查點：已寫入
pixie_qa/run_app.py。Runnable 使用真實的 LLM 設定呼叫應用程式的真實進入點——沒有模擬、沒有偽造、沒有元件替換。
子步驟 2c：擷取並驗證參考追蹤
參考資料：立即閱讀
references/2c-capture-and-verify-trace.md。
透過 Runnable 執行應用程式並擷取追蹤。追蹤證明儀器化和 Runnable 正常運作，並提供步驟 4 中資料集建立所需的資料形狀。
檢查點：
pixie_qa/reference-trace.jsonl存在。所有預期的wrap條目和llm_span條目都出現。pixie format顯示評估所需的所有資料點。尚未閱讀步驟 3 的指示。
步驟 3：定義評估器
參考資料：立即閱讀
references/3-define-evaluators.md以了解詳細的子步驟。
目標：將步驟 1c 的定性評估標準轉化為具體、可執行的評分函式。每個標準對應到一個內建評估器、一個代理評估器（任何語義或定性標準的預設值）或一個手動自訂函式（僅用於機械/確定性檢查，如正規表示式或欄位存在性）。評估器對應產出物橋接了標準和資料集，確保每個品質維度都有評分器。選擇衡量 pixie_qa/00-project-analysis.md 中識別的困難問題的評估器——而不僅僅是通用的品質維度。
檢查點：所有評估器已實作。已寫入
pixie_qa/03-evaluator-mapping.md，包含標準到評估器的對應和決策理由。尚未閱讀步驟 4 的指示。
步驟 4：建立資料集
參考資料：立即閱讀
references/4-build-dataset.md以了解詳細的子步驟。
目標：建立將所有內容聯繫在一起的測試情境——Runnable（步驟 2）、評估器（步驟 3）和使用案例（步驟 1c）。每個資料集條目定義要發送給應用程式的內容、應用程式應從外部服務看到的資料，以及如何評分結果。使用步驟 2 的參考追蹤作為資料形狀和欄位名稱的真實來源。涵蓋 pixie_qa/00-project-analysis.md 中能力清單的條目，並包含針對其中識別的失敗模式的條目。不要使用專案自己的測試固定裝置、模擬伺服器或範例資料作為資料集 eval_input 內容——而是使用真實世界的資料。應用程式中的每個 wrap(purpose="input") 必須在每個條目的 eval_input 中有預先擷取的內容——當應用程式有輸入 wrap 時，不要讓 eval_input 為空。
檢查點：在
pixie_qa/datasets/<name>.json建立了資料集 JSON，包含涵蓋所有使用案例的多樣化條目。資料集真實性審核通過——條目使用真實世界資料且規模具代表性，沒有專案測試固定裝置污染，至少有一個條目針對結果不確定的失敗模式，且每個eval_input都有所有輸入 wrap 的擷取內容。尚未閱讀步驟 5 的指示。
步驟 5：執行 pixie test 並修正機械問題
參考資料：立即閱讀
references/5-run-tests.md以了解詳細的子步驟。
目標：端對端執行完整管線，並使其在沒有機械錯誤的情況下運作。此步驟嚴格關於修正 pixie QA 元件（資料集、Runnable、自訂評估器）中的設定和資料問題——而不是關於修正應用程式本身或評估結果品質。一旦 pixie test 完成且沒有錯誤，並為每個條目產生真實的評估器分數，此步驟即完成。
檢查點：
pixie test執行完成。每個資料集條目都有評估器分數（真實的EvaluationResult或PendingEvaluation）。沒有設定錯誤、沒有匯入失敗、沒有資料驗證錯誤。如果測試出錯，那是你的 QA 元件中的機械錯誤——修正並重新執行。但一旦測試產生分數，就繼續前進。不要在評估結果品質——那是步驟 6。
在測試產生分數後，一律繼續進行步驟 6。 分析是最終的必要步驟——沒有它，待處理的評估永遠不會完成，使用者只會得到未經解釋的原始分數，沒有可行的見解。不要在此停止並詢問使用者是否繼續。
迭代執行的循環規則：每次成功的 pixie test 呼叫都會建立一個具體的 pixie_qa/results/<test_id> 目錄，並開始一個新的分析循環。在編輯應用程式程式碼、提示、資料集、評估器或重新執行 pixie test 之前，先完成該特定結果目錄的步驟 6。不要跳過較早的循環，只分析最後一次執行。
步驟 6：分析結果
參考資料：立即閱讀
references/6-analyze-outcomes.md——它包含完整的三階段分析流程、寫作指南和輸出格式要求。
目標：以結構化、資料驅動的流程分析 pixie test 結果，以產生關於測試案例品質、評估器品質和應用程式品質的可行見解。此步驟完成待處理的評估、寫入每個條目和每個資料集的分析，並產生優先順序行動計畫。每個陳述都必須有評估執行的具體資料支持——沒有推測、沒有空泛說詞。
持久化的分析產出物：在此精簡的工作流程中，僅在資料集層級和測試執行層級持久化分析。這些產出物仍然使用詳細版本（供代理使用：資料點、證據鏈、推理鏈）加上摘要版本（供人類審查：可在 2 分鐘內閱讀的簡潔 TLDR）。不要建立每個條目的分析檔案。
硬性完成門檻：步驟 6 未完成，直到以下所有條件成立：
- 每個
pixie_qa/results/<test_id>/dataset-*/entry-*/evaluations.jsonl中每個"status": "pending"條目都已替換為包含score和reasoning的評分結果。 - 每個資料集目錄都有
analysis.md和analysis-summary.md。 - 測試執行根目錄有
action-plan.md和action-plan-summary.md。 - 你已針對
pixie_qa/results/<test_id>執行此技能resources/目錄中的步驟 6 驗證器腳本，且它報告成功。
明確不足夠：
- 寫入單一頂層檔案，例如
pixie_qa/06-analysis.md - 說待處理的評估是供使用者在網頁 UI 中審查
- 說某個條目「可能通過」但未更新
evaluations.jsonl
網頁伺服器管理
pixie-qa 在背景執行一個網頁伺服器，用於向使用者顯示上下文、追蹤和評估結果。它由設定腳本自動啟動（透過 pixie start，它啟動一個分離的背景程序並立即返回）。
當使用者完成 eval-driven-dev 工作流程時，告知他們網頁伺服器仍在執行，你可以用以下指令清理它：
pixie stop
重要：網頁伺服器停止後，網頁 UI 將無法存取。因此，只有當使用者確認他們已完成所有網頁 UI 功能時，才停止伺服器。如果他們想繼續使用網頁 UI，請不要停止伺服器。
每當你重新啟動工作流程時，務必再次執行 resources 中的 setup.sh 腳本，以確保網頁伺服器正在執行：
