# 執行期模型目錄以 models.dev 為資料來源 **Status**: accepted. 「資料與能力」與「快取與新鮮度」兩節已被 [ADR-0005](0005-official-model-list-as-free-model-source.md) 取代(資料改取官方清單、不再使用 models.dev);「可見性與探測」與「面板語意」仍有效。 ## Context 只使用 pi-ai 內建清單會讓新模型與能力更新受宿主依賴版本限制;手寫能力表或猜測 上下文上限則可能讓 DSH 使用錯誤設定。models.dev 的 `deprecated` 也不能單獨證明 Zen 已停止供應模型。因此 metadata、上游在列與模型探測必須分開。 ## Decision ### 資料與能力 - 執行時讀取 models.dev 的 `opencode.models`,保留 cost 全零且狀態為 active、 deprecated 或未提供狀態的記錄;其餘狀態排除。 - 能力由該模型的 metadata 推導,不繼承其他模型的能力:上下文、輸出上限、 text/image 輸入與已發布推理等級。未發布等級不猜測;`off` 表示不送推理參數。 - pi-ai 內建表只提供已知通道與離線兜底。通道優先採已知對應,再由 metadata 推導, 最後使用既有 OpenAI-compatible 後備;模板只提供 provider identity。 - Zen `/inference/v1/models` 是獨立的在列條件,不是完整能力資料來源。 未知項目只作診斷提示,不以名稱猜測能力或加入選單。 - 相容性驗證的官方動態目標依 [ADR-0004](0004-official-dynamic-compat-targets.md), 不得以本插件目錄取代。官方已發布的端點資料也不能因舊調查未取得而視為不存在。 ### 可見性與探測 - 模型選單與詳情頁共用同一份可見性決策;隱藏模型不探測,目錄保留其 metadata。 - `ok`、`dead`、`inconclusive` 分開。只有明確的模型層級拒絕且所有實作通道都拒絕, 才可持久保存 `dead`。舊判定沒有完成通道掃描標記時,允許重新檢查一次。 - 准入拒絕、額度、key、傳輸失敗與空回覆不構成下架證據,也不持久保存為模型判定。 呼叫端層級拒絕不反覆切換通道重試;多通道結果按證據強度整合,不只採最後結果。 - `dead` 不自動重探,且原記錄仍保留於目錄,避免下次同步丟失判定。 清單缺席只改變在列狀態;重新列出可以恢復,與 `dead` 不同。 - Zen 清單失敗或空回應不收窄既有清單。每輪先讀清單,已不在列者不送推理請求。 - 探測按順序執行,預算 1024 tokens、每模型 15 秒;自動輪次以本地日為界, 手動輪次有最短間隔。匿名准入宣告在最終 payload 邊界再次確保存在。 目前操作間隔與快取復原步驟只在[使用指南](../usage.zh-TW.md)維護。 ### 快取與新鮮度 - 快取只存模型資料、明確判定與去敏輪次摘要,以暫存檔加 rename 原子寫入; ETag 用於條件更新。無可用快取時保留內建兜底,更新失敗不清空既有選單。 - models.dev 與 Zen 在列有獨立惰性更新軸,不新增計時器。models.dev 預設 24 小時, 上次回應為 `304` 才縮為 6 小時;完整回應回到 24 小時。 - Zen 在列間隔為 30 分鐘,由單一 single-flight 寫入者更新,與 metadata 更新互不阻塞。 在列時間與 `304` 狀態不落盤,重啟不保證沿用較短窗口。 - 輪次摘要可跨重啟,但不參與可見性判定;損壞或缺失視為沒有報告。 「當輪未測到」不能變成持久模型結論。 ### 面板語意 - 能力徽標與探測結果同時顯示;目錄依 id 穩定排序,面板只將啟用模型分組置前。 - 進度含本輪 targets,範圍外模型不顯示等待或失敗;結束後保留摘要與時間。 - 失敗原因、HTTP 狀態、准入 marker、新移除或既有判定分開表示並由 locale 翻譯。 灰色未測到與紅色不可用不可混用;保留的舊拒絕不能呈現為當前狀態。 ## Alternatives and consequences 手寫表、建置期快照與等待 pi-ai 升版都無法獨立跟隨上游,故採執行期同步。 代價是私有快取、首次下載與真實探測額度。暫不增加探測併發、縮減預算、跨 provider 猜測未知能力、HTTP Range 切片、第三方轉發服務或額外冷啟動重試階梯。 若取得更完整 metadata、可重現的品質/成本改善或持續的逾時證據,再重審對應取捨; 原始測量與各項重審條件見封存紀錄。