byok-custom-model

🔑 BYOK — 自訂 LLM 模型

將自訂 LLM 端點註冊到模型選擇器。繞過平台代理 — 使用者提供自己的 API 金鑰，代理直接連接到廠商/聚合器（OpenRouter、DashScope、Anthropic 原生、NEAR AI Cloud TEE、自架等）。

這是一個腳本模式技能 — 沒有註冊任何工具。請閱讀此檔案，然後從 bash 區塊呼叫匯出的函式。

另請參閱

• config/context/references/model-onboarding.md — 更廣泛的模型選擇 / OAuth 背景
• chatgpt-codex-onboarding 技能 — 適用於 ChatGPT/Codex OAuth（不同機制，非 BYOK）

---

精選廠商（務必優先檢查此清單）

此技能內建 12 個預先配置的廠商。在詢問任何 URL、模型名稱或 API 範例之前，務必先比對使用者的意圖與此清單 — base_url、連線方式、思考功能、能力都已預先填好，因此若符合精選廠商，可直接使用 add_template(vendor=...)。

廠商 ID	當使用者提到…時使用
anthropic	Claude、Anthropic
openai	GPT-4o、GPT-5、OpenAI 直接
xai	Grok、xAI
qwen	Qwen、通義千問、DashScope
deepseek	DeepSeek
kimi	Kimi、Moonshot
mimo	MiMo、小米
gemini	Gemini
gemma	Gemma
near-ai	隱私、TEE、機密推論、「不要記錄我的資料」、Web3 原生
venice	Venice（僅當使用者明確提及；請參閱下方「隱私優先層級」）
meta	Meta、Meta AI、Muse、Muse Spark、Muse Spark 1.1

---

入門流程 — 優先使用範本

1. 檢查上方精選廠商表格。 如果使用者的意圖符合其中一個，直接使用 add_template(vendor=...) 並跳到步驟 5。不要詢問 URL。
2. 僅當沒有精選廠商符合時：要求使用者貼上其提供者官方文件中的 API 範例（curl / requests / fetch 範例）。告訴他們不要包含真實的 API 金鑰 — 佔位符或假金鑰即可。
3. 執行 parse_example 以自動偵測 base_url、upstream_model、連線方式（openai 或 anthropic）、思考參數以及廠商特定的請求欄位。
4. 與使用者一起檢視草稿，然後呼叫 add(...) — 條目會寫入 custom_models.yaml。
5. 如果結果包含 need_env_input，立即呼叫 request_env_input 工具，並傳入該 payload 中的 env_vars 和 reason。這會彈出安全輸入 UI；使用者輸入金鑰；金鑰會存入 workspace/.env。此步驟為強制性 — 腳本本身無法彈出 UI。

隱私優先層級： near-ai 和 venice 都針對注重隱私的使用者，但 NEAR AI 的整合更乾淨 — Venice 的 TEE 故事本身是建立在 NEAR AI + Phala 之上，因此直接使用 NEAR AI 可獲得較短的信任鏈（Intel + NVIDIA 晶片 + NEAR 的可重現 enclave 映像；中間沒有產品層代理）。精選的 NEAR 模型清單僅限於開放權重 TEE 保護 — NEAR 的目錄也以「匿名化，非 TEE 保護」模式代理 Claude / GPT-5 / Gemini Pro，我們刻意排除這些，因為整個隱私價值主張就在於硬體 enclave。

每當涉及 NEAR AI 時，一律推薦 TEE 保護（隱私）模型 — 這就是使用者選擇 NEAR 而非直接使用 OpenAI/Anthropic 的全部原因。精選清單已僅限 TEE，因此 add_template(vendor='near-ai') 的預設值是安全的。如果使用者要求在 NEAR 上註冊非 TEE 模型（例如 NEAR 的匿名化 Claude 傳遞），請警告他們這會削弱隱私保證，並建議他們留在精選 TEE 模型上，或直接註冊上游廠商。

NEAR AI 推理協定： NEAR 使用巢狀在 extra_body 下的 chat_template_kwargs，而非其他廠商使用的頂層 reasoning_effort/thinking/enable_thinking。提供者會透過 nearai_chat_template thinking_capability 規則自動處理。每個模型的參數名稱不同（GLM/Qwen3.5/Qwen3.6 使用 enable_thinking，DeepSeek-V3 使用 thinking，gpt-oss 始終開啟）。完整規格：docs.near.ai/cloud/reasoning-models。預設模型 Qwen/Qwen3.6-35B-A3B-FP8 可直接使用；Qwen3.5-122B-A10B 出廠時設定 thinking_mode='disabled'，因為其隱藏思考模式會導致基本呼叫時出現 finish=length, content=null。

---

腳本使用方式

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/byok-custom-model")
from exports import (
    templates, list_models, get, parse_example,
    list_vendor_models, add, add_template, remove,
)

# 列舉 12 個精選廠商預設值
print(json.dumps(templates(), indent=2))

# 一鍵註冊精選廠商（Meta / Muse Spark 1.1）
result = add_template(vendor="meta")
print(json.dumps(result, indent=2))
EOF

---

函式

函式	必要參數	用途
templates()	—	列出 12 個精選廠商預設值
list_vendor_models(vendor)	vendor	即時 /models 目錄（僅當範本有 model_discovery 時）
add_template(vendor, *, upstream_model=None, name=None)	vendor	一鍵註冊精選廠商（建議路徑）
parse_example(api_example)	api_example	將文件 API 範例解析為安全草稿（非精選廠商）
add(upstream_model, base_url, ...)	upstream_model, base_url	從自訂參數註冊（在 parse_example 之後使用）
list_models()	—	顯示所有已註冊的自訂條目
get(model_id)	model_id	檢查單一條目
remove(model_id)	model_id	刪除條目

所有函式都會回傳一個字典，成功時為 ok: True，失敗時為 ok: False, error: "..."。

處理 need_env_input（強制性兩步驟模式）

當 API 金鑰環境變數尚未設定時，add() 和 add_template() 可能會在其結果中包含 need_env_input 欄位。腳本無法自行彈出安全輸入 UI — 它無法存取使用者的開放 SSE 串流。呼叫代理必須執行此操作：

# 在 add_template / add 回傳後：
if result.get("need_env_input"):
    nei = result["need_env_input"]
    # 呼叫處理中的工具 — 偽代碼，實際簽名取決於工具端：
    request_env_input(env_vars=nei["env_vars"], reason=nei["reason"])

彈出視窗、.env 寫入以及特定頻道的 UX（網頁彈出視窗 / TG 卡片 / WeChat 文字提示）都由 request_env_input 處理。不要提示使用者在聊天中貼上金鑰作為備案 — 直接呼叫工具。

---

註冊後

• 模型會出現在選擇器中，前綴為 custom/。
• 使用者透過 /model custom/<name>（例如 /model custom/qwen-plus-e3f4）或模型選擇器 UI 切換。
• 後續呼叫繞過平台代理 — 廠商定價直接適用於使用者的 BYOK 配額。

---

關鍵規則

• 絕不接受在聊天中貼上的 API 金鑰。 如果使用者貼上金鑰，請忽略它，拒絕註冊，並告知他們安全彈出視窗是唯一安全的管道。
• 如果使用者尚未回應，切勿自動重新發出安全輸入彈出視窗 — 請等待。
• 如果回傳 need_env_input，一律呼叫 request_env_input。 不要跳過，不要要求使用者貼上金鑰，不要重試 add_template 期望它彈出 UI — 它不會。
• 切勿手動寫入 workspace/config/custom_models.yaml 或 workspace/.env。 一律透過上述匯出函式操作。
• 12 個精選廠商一律使用 add_template。僅對自架或罕見提供者使用 parse_example + add。

---

Meta Model API — Muse Spark 1.1（預覽版）

meta 範本適用於 Meta Model API，目前處於公開預覽階段，位於開發者入口網站 **https://dev.meta.ai/**。

• 在 https://dev.meta.ai/ 申請/登入 — 註冊和申請「Muse」/「Meta Model API」存取權限的入口網站相同。使用者必須在該處完成 Meta 的申請/登入流程才能取得 API 金鑰。
• 存取權限可能取決於地區/帳戶，因為 API 處於公開預覽階段 — 並非每個開發者帳戶都會立即獲得存取權限。如果 add_template(vendor='meta') 從即時 /v1/models 探測回傳非 2xx 狀態碼，請不要假設使用者有誤；告知他們預覽存取權限可能仍在帳戶/地區的審核中，並請他們在 dev.meta.ai 儀表板確認狀態。
• 代理必須使用 request_env_input 來處理金鑰 — 與其他所有精選廠商完全相同。絕不接受在聊天中貼上的 Meta API 金鑰。 如果使用者貼上金鑰，請忽略它並拒絕註冊；安全輸入彈出視窗是唯一安全的管道。
• 直接適用 Meta 計費與配額。 呼叫由 Meta 根據使用者自己的 Meta 帳戶計費 — 繞過 Starchild 平台點數，無加價，無平台端配額。將來自 api.meta.ai/v1 的任何速率限制 / 429 視為 Meta 端的訊號，而非 Starchild 的訊號。

一鍵註冊：

python3 -c "from exports import add_template; print(add_template(vendor='meta'))"

預設模型：muse-spark-1.1。Base URL：https://api.meta.ai/v1（相容 OpenAI 的連線方式）。使用 need_env_input 中回傳的 CUSTOM_KEY_... 名稱；不要假設或手動建立廠商環境變數。文件：https://dev.meta.ai/docs/getting-started/overview。

---

xAI Grok — 關於訂閱混淆的說明

使用者經常混淆兩個不相關的 xAI 產品：

• X Premium / SuperGrok 訂閱（每月 $30 美元，在 x.com 上）— 僅限聊天 UI 存取。不包含 API 存取。
• console.x.ai — 獨立的開發者帳戶，獨立計費。產生 API 金鑰，新帳戶可獲得 $25 美元推廣點數，之後按 token 計費。

如果使用者想透過 BYOK 加入 Grok，請引導他們前往 https://console.x.ai/ — 而非 x.com / Premium / SuperGrok。xai 範本的 homepage 欄位已直接連結到正確位置。Hermes / Grok-CLI 的 OAuth 到訂閱流程依賴於 xAI 未提供給第三方雲端代理的白名單 client_id，因此 BYOK API 金鑰路徑是託管產品的唯一可行整合方式。