Jia-Ethan/pavedpath-code

PavedPath Code（代碼版）

PavedPath Code（代碼版）幫助代理避免為軟體工程問題重新發明解決方案。它搜尋 GitHub 和開源專案中的實證，找出經過驗證的實作路徑，然後將最強的模式調整至本地程式碼庫，並進行最小、可驗證的變更。

使用 GitHub 作為主要的證據來源，而非僅作為連結轉儲。目標是定義本地程式碼問題，找到已在公開儲存庫、議題、合併請求、討論、範例、發行說明和原始碼中走過的路徑，評估該證據的強度，然後將最強的模式轉化為小型的本地修復、實作路徑或驗證計畫。

這是專注於程式碼的 PavedPath 版本。請勿將其擴展為未來通用型的 PavedPath。它專門用於軟體工程工作：錯誤、執行時期錯誤、建置/測試/部署失敗、相依性問題、框架或 API 用法、整合障礙、實作模式、工程工具選擇，以及開源解決方案的導入。

使用時機

• 執行時期、建置、測試、部署、套件、SDK、API、相依性、框架或整合錯誤。
• 功能實作因不明確的邊界案例、缺少的使用模式、版本行為或模糊的 API 約定而受阻。
• 本地問題類似於維護者或其他開源使用者可能在議題、PR、範例、程式碼、發行說明或討論中已解決的問題。
• 使用者詢問 GitHub 或開源專案是否已解決某個具體的工程問題。
• 成熟的實作範例或可重複使用的專案可以減少某個特定功能的不確定性。
• 答案應比較合適的 GitHub 儲存庫，並解釋如何在本地調整一條經過驗證的路徑。

請勿將 PavedPath Code 用於：複製編輯、純粹的本地重構（程式碼庫已給出答案）、非程式碼的人生決策、自媒體工作流程、學習方法、消費者購買決策，或明確禁止網路/GitHub 研究的請求。除非使用者明確指定並授權，否則請勿檢查私有儲存庫。

預設工作流程

1. 先定義本地程式碼問題。 記錄目標、症狀、錯誤特徵、重現路徑、版本、執行時期、相依性/框架名稱、近期變更、限制條件和已嘗試的修復。如果缺少可發現的事實，請在詢問之前先檢查本地檔案/日誌。
2. 選擇證據模式。 對於錯誤/回歸，優先搜尋議題、PR、發行版本和程式碼。對於功能或工具需求，優先搜尋儲存庫候選項目。對於功能實作，同時使用儲存庫候選項目和議題/PR/程式碼證據。
3. 評估次代理（subagent）的效用。 在進行大量 GitHub 研究之前，決定條件性的次代理工作是否能提升廣度、證據品質或審查覆蓋率。如果未使用次代理，請在報告搜尋路徑時簡短說明原因。
4. 建立目標搜尋。 優先使用確切的錯誤文字、套件/API 名稱、版本號碼、框架+症狀、檔案名稱、設定鍵、堆疊追蹤片段、失敗的命令名稱，或功能+框架/執行時期/API 名稱。
5. 必要時尋找合適的 GitHub 專案。 優先選擇高度匹配、高星數、活躍、未封存且具有明確授權和真實範例的儲存庫。當高星數集合過於廣泛或錯過確切問題時，可降低星數門檻。
6. 搜尋開源證據表面。 在相關的開源儲存庫中使用議題、PR、討論、程式碼、範例、發行說明和官方專案文件。當專案本身可能解決問題時，必須進行儲存庫搜尋。
7. 首先以問題匹配度排名，星數作為成熟度訊號。 高星數的儲存庫是檢查的強烈候選，但維護者已確認的議題、已合併的 PR、已發布的修復、官方範例和完全匹配的程式碼勝過熱門的相近專案。當排名很重要時，請使用 research-rubric.md。
8. 深度閱讀最強的專案和證據。 使用 extraction-playbook.md 提取專案基礎、可重複使用的表面、根本原因或實作模式、版本限制、風險、調整邊界和驗證步驟。
9. 以最小調整轉化為本地工作。 保留經過驗證的工作流程、API、設定形狀或架構，在適合之處保留。僅調整使用者本地介面、設定、資料/驗證模型、部署目標或語言/執行時期所需的部分。
10. 在聲稱成功之前進行驗證。 使用適合本地問題的測試、建置、重現指令、真實請求、日誌、瀏覽器檢查或手動檢查。
11. 如果證據薄弱，請明確說明。 不要將薄弱的匹配勉強成為有信心的建議。當開源證據不足時，將建議標記為基於第一原理或僅限本地使用。

次代理（Subagent）/ 平行研究指引

次代理是有條件的研究輔助工具，並非預設需求。控制器仍負責問題框架設定、範圍控制、證據排名、本地調整和最終驗證。

在滿足以下至少一項條件時使用次代理：

• 問題跨越 2 個以上獨立的生態系統、框架、語言、工具、部署表面或 GitHub 社群。
• 儲存庫發現需要跨多個查詢系列的廣泛候選覆蓋。
• 議題、PR、討論、程式碼、發行和範例證據可以按專案、版本或搜尋表面清晰地分割。
• 最終建議可從獨立的證據審查、風險審查或候選排除審查中受益。

在滿足以下任一條件時請勿使用次代理：

• 任務是一個狹義的錯誤，只有一個明顯的套件、儲存庫、API 或維護者表面。
• 在安全地設定外部研究範圍之前，必須先理解本地儲存庫上下文、日誌、設定或重現細節。
• GitHub 速率限制、授權邊界、私有儲存庫、機密、生產資料或敏感日誌會使委派具有風險。
• 次代理大部分會重複相同的搜尋或編輯相同的本地檔案。

使用次代理時，控制器必須：

• 為每個次代理定義其查詢系列、儲存庫範圍、證據表面、限制、允許的寫入範圍和預期輸出。
• 要求直接連結、驗證過的元資料、問題匹配理由、風險說明和明確的排除原因。
• 保持次代理為唯讀，除非單獨的實作階段具有狹義的允許寫入範圍。
• 在排名前合併並去重結果；不要將同一議題、PR、程式碼路徑或儲存庫的重複報告計為獨立證據。
• 在最終確定前，使用 gh、原始碼閱讀、測試、日誌、真實請求或官方文件直接驗證最強的主張。

優先使用 GitHub CLI

使用 GitHub CLI (gh) 作為預設的搜尋和檢查表面。優先使用 gh search repos、gh search issues、gh search prs、gh search code、gh repo view、gh issue view、gh pr view 和 gh api，而非瀏覽器抓取或自訂腳本。請勿為此技能添加或依賴捆綁的搜尋腳本。

使用以下簡短指令範本作為起點，然後根據本地問題調整查詢、儲存庫、欄位和限制：

gh search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh api -X GET search/repositories -f q='<query> archived:false' -f sort=stars -f order=desc

僅在指令因 403、429、私有儲存庫授權錯誤或明確的 gh 未驗證訊息而失敗時，才執行 gh auth status。如果 GitHub 回傳 403/429，請在重試、減少廣度或切換端點之前檢查發出的速率限制或授權上下文。請勿將令牌、cookie、私有儲存庫內容或憑證貼上或持久儲存在提示、檔案、日誌或記憶體中。

搜尋策略

• 從狹義開始：確切的錯誤字串、例外類別、CLI 輸出、套件+方法名稱、設定鍵或堆疊追蹤片段。
• 加入限制條件：套件/框架版本、語言、平台、部署目標、打包工具、資料庫、驗證提供者或執行時期。
• 按相關性順序搜尋以下表面：議題/PR/討論、已合併的修復、發行說明/變更日誌、範例/範本、原始碼，然後是儲存庫層級候選。
• 對於無錯誤的功能阻礙，搜尋所需功能加上框架/執行時期/API 名稱。
• 對於公開平台資料需求，例如趨勢、熱門列表、主題搜尋或參與度指標，不要從視覺瀏覽器抓取開始。首先尋找可重複使用的公開端點、開源爬蟲、歸檔資料集和 API 欄位證據；然後用最小的真實請求驗證所選來源，並清楚區分匿名熱門列表資料與已登入的搜尋/主題資料。
• 對於可重複使用專案的發現，搜尋按星數排序的儲存庫，然後僅深度閱讀與本地問題匹配的候選項目。記錄星數、分支數、語言、授權、活躍度和基本內容。
• 對過時、版本不匹配、已封存、未解決、推測性或僅基於使用者猜測的匹配，降低其優先級。
• 僅將星數/分支數用作支援的成熟度背景和具有相似匹配度的儲存庫之間的決勝因素。它們不能凌駕於問題匹配度、維護者確認的證據、已合併的 PR、發行說明、官方範例或可重現的程式碼之上。
• 對於安全性、驗證、支付、基礎設施或生產操作，當事實可能已變更時，請將開源發現與最新的官方文件或儲存庫進行交叉檢查。

證據標準

對於每個嚴肅的證據項目，請識別：

• 精確匹配：相同的錯誤、行為、API、版本、環境或工作流程；
• 證據強度：維護者確認、已合併的 PR、已發布的修復、可重現的程式碼範例、測試固定裝置或重複的獨立報告；
• 適用性：本地必須符合哪些條件才能使解決方案生效；
• 實作價值：值得調整的修補程式、設定、API 用法、相依性版本、工作流程、測試或操作模式；
• 當儲存庫是候選時的基本專案資訊：名稱、URL、星數、分支數、語言、授權、活躍度、基本內容、匹配理由和調整成本；
• 風險：過時的版本、未解決的議題、不安全的解決方法、授權顧慮、安全性/隱私影響、部署不匹配或過於廣泛的變更。

輸出合約

當 PavedPath Code 對答案產生重大影響時，請包含：

• 本地問題描述：目標、症狀/錯誤、版本/環境和本地限制；
• 搜尋路徑：使用的查詢或發現方法、搜尋過的 GitHub/開源表面，以及是否使用或跳過了次代理；
• 使用次代理時的追蹤：每個次代理的範圍、證據表面、關鍵發現、被拒絕的候選、去重結果，以及控制器直接驗證了哪些主張；
• 當 GitHub 專案本身相關時的專案候選：儲存庫連結、星數、分支數、語言、授權、活躍度、基本內容、匹配理由以及如何在本地使用；
• 關鍵證據：指向議題、PR、程式碼、範例、發行版本或儲存庫的連結，並附帶匹配理由；
• 建議的解決方案：應直接重複使用的部分、應在本地調整的部分、應避免複製的部分，以及為何適合；
• 被拒絕或有風險的選項：為何不適用或需要謹慎；
• 驗證標準：測試、建置、重現指令、真實請求或手動檢查，以確認修復；
• 當證據薄弱或未找到強大的開源解決方案時的信度標籤。

當儲存庫層級的解決方案相關時，請包含一個簡潔的專案表格。對於純議題/PR/程式碼修復，表格為可選，但如果儲存庫上下文影響信任度或適用性，請包含儲存庫資訊。

不要僅用連結、星數或熱門排名回答。不要在沒有連結證據的情況下撰寫「常見 GitHub 模式」。不要讓外部範例凌駕於本地限制之上。

對於網站、SaaS、著陸頁、主題或前端範本候選研究，請為每個嚴肅的候選項目同時包含儲存庫 URL 和即時預覽/示範 URL。如果沒有可用的或已驗證的預覽，請明確說明並降低該候選項目的優先級。

遷移說明

github-solution-research 已重新命名為 PavedPath Code。保留了先前的行為；這是專注於程式碼的 PavedPath 版本的名稱和定位更新。新安裝應使用 pavedpath-code 技能名稱以及目標代理執行時期的作用中技能/指令目錄。

安全邊界

• 優先閱讀模式並重複使用現有的公開介面，而非複製程式碼。如果必須重複使用程式碼，請檢查授權並保持歸屬/義務風險的可見性。
• 避免對現有開源解決方案進行大規模重寫。保持其經過驗證的流程完整，並僅進行使用者問題所需的本地調整。
• 避免從儲存庫、README、議題、PR 或文件中大量逐字節錄。
• 請勿將 GitHub 令牌、cookie、私有儲存庫內容或憑證儲存在輸出、日誌、技能或記憶體中。
• 請勿將令牌、cookie、私有儲存庫內容、敏感日誌、機密、生產資料或憑證傳遞給次代理。
• 如果無法連線網路，請說明無法進行開源研究，並將建議標記為僅限本地。