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 和 effortsArgs 不會穿過 SDK boundary。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。

SDK settings boundary

SDK 的 getSettings() 只有：

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

實際 provider 設定、effort argv、credentials 與 model name 只能在 Desktop Settings 查看或修改。

Ollama

選中的 Ollama profile 必須包含 --model pair。若為空，Core 回傳 MODEL_REQUIRED，不會 fallback 到 default；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。