Providers 與 effort profiles

Providers 與 effort profiles

Application 選擇 provider 與資源意圖；Desktop 使用者則在 Settings 中決定每個 profile 對應的實際 provider CLI 參數。

Provider code

固定的小寫 code 是 codex、antigravity、opencode、cursor、claude 與 ollama。listProviders() 只公開名稱、code、availability、isDefault 與錯誤訊息。isDefault 反映目前 Desktop 的 default provider，與 available 無關，即使 default provider unavailable 也仍為 true；credentials、model catalog、providerSettings 和 profile effortsArgs 不會穿過 SDK boundary。Application 可在 createSession({ model, effort? }) 傳入 explicit provider-native 設定；Pedelec 不維護 model catalog 或 capability matrix。SDK 與 Extension 會忽略 response 中新增的未知欄位，以保持 forward compatibility。

Effort levels

type EffortLevel = "default" | "low" | "high";

省略時使用 default。default 是使用者的正常 profile，大致代表 medium intent，但 Pedelec 不會強制 provider 的 native effort 值。Profile 可以只選 model、只選 native effort，或在 provider 支援時同時設定兩者；native 值不必和 Pedelec level 同名。

Provider 的 native value 仍會依支援的 provider CLI contract 驗證，不是任意 passthrough 字串。

Provider 可以省略：

await pedelec.createSession({ effortLevel: "high" });

也可以同時指定：

await pedelec.createSession({ provider: "codex", effortLevel: "low" });

非 Ollama provider 的空 low 或 high profile 不會傳送 explicit model/effort 參數，也不會 fallback 到 default。

Explicit model configuration

effortLevel 與 model 是互斥的兩種 mode。Profile mode 使用完整 Desktop profile：

await pedelec.createSession({
  provider: "codex",
  effortLevel: "high",
});

Explicit mode 只使用指定 model 與 optional native effort：

await pedelec.createSession({ provider: "codex", model: "gpt-x", effort: "max" });

只有 model 的 explicit mode 使用 provider default effort。Explicit 設定獨立 snapshot；之後修改 Desktop profile 不會改變已建立 session。Model validity、effort support、provider availability 與帳號 entitlement 由 provider 決定。

Explicit model 需要 Core 回傳 explicitModelConfigApplied: true；舊版 Extension/Desktop 若無法提供，SDK 會中止新 setup 並回報不相容。

SDK settings boundary

SDK 的 getSettings() 只有：

type PedelecSettings = {
  defaultProvider: ProviderCode | null;
};

實際 provider 設定、effort argv、credentials 與 Desktop profile 內的 model name 只能在 Desktop Settings 查看或修改；application 可在 explicit mode 傳入 model 與 optional effort。

Ollama

Ollama 的 profile mode 必須在選中的 profile 包含 --model pair，否則 Core 回傳 MODEL_REQUIRED，不會 fallback 到 default。Explicit { model } mode 直接提供 model，不需要 profile model；Ollama 目前不接受 explicit effort。Ollama 被選為 Desktop default provider 時，Default profile 必須有 model，Low/High 則可留空。

Provider-native skill isolation

Pedelec 會限制 provider 自己的 skill 或 command discovery，避免它和 App 定義的 Pedelec tool registry 競爭。這個 policy 不會移除 provider 原本的 sandbox/file 能力，也不會影響 Pedelec App tools。

目前 runtime 依 provider 採用不同策略：

• Codex 以 skills.include_instructions=false 啟動。
• Antigravity 以 --disable-slash-commands 啟動。
• Persistent Claude Code 不會帶 --disable-slash-commands，因此 Claude skills 仍可使用。
• OpenCode 在既有 permission value 能安全 parse 成 object 時，overlay "skill": "deny"；若 parent value invalid 或不是 object，則保留原值，不會用新的設定覆蓋。
• Cursor 與 Ollama 目前沒有額外 provider-native skill override。

這些屬於 runtime implementation detail，不是 SDK configuration。Application 應透過 skills.tools 定義希望 agent 使用的工具，不應依賴 provider-native skills 一定能被 discover。

Session snapshot

Core 在建立 session 時解析並驗證 profile，將 argv token snapshot 存入 thread。之後修改 Desktop Settings 不會改變既有或可 resume session 的 provider command。