From ec78c066f9c6627f9365333f5d129d2491de7e0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E5=91=98=E9=98=BF=E6=B1=9F=28Relakkes?= =?UTF-8?q?=29?= Date: Tue, 7 Apr 2026 11:11:34 +0800 Subject: [PATCH] docs: add provider preset redesign spec Preset-based provider configuration inspired by cc-switch. Presets: Official, DeepSeek, ZhipuGLM, Kimi, MiniMax, Custom. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-04-07-provider-preset-redesign.md | 184 ++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-07-provider-preset-redesign.md diff --git a/docs/superpowers/specs/2026-04-07-provider-preset-redesign.md b/docs/superpowers/specs/2026-04-07-provider-preset-redesign.md new file mode 100644 index 00000000..b5900c6f --- /dev/null +++ b/docs/superpowers/specs/2026-04-07-provider-preset-redesign.md @@ -0,0 +1,184 @@ +# Provider Preset Redesign + +## Overview + +Replace the manual provider configuration UI with a preset-based system inspired by [cc-switch](https://github.com/farion1231/cc-switch) (MIT License, Copyright 2025 Jason Young). Users select a preset provider, enter an API key, and the system writes the correct env vars to `~/.claude/settings.json`. + +## Presets + +Six presets, each with pre-configured baseUrl and model mapping: + +| ID | Name | baseUrl | Main Model | API Key Required | +|---|---|---|---|---| +| `official` | Claude Official | _(clear env)_ | _(default)_ | No | +| `deepseek` | DeepSeek | `https://api.deepseek.com/anthropic` | `DeepSeek-V3.2` | Yes | +| `zhipuglm` | Zhipu GLM | `https://open.bigmodel.cn/api/anthropic` | `glm-5` | Yes | +| `kimi` | Kimi | `https://api.moonshot.cn/anthropic` | `kimi-k2.5` | Yes | +| `minimax` | MiniMax | `https://api.minimaxi.com/anthropic` | `MiniMax-M2.7` | Yes | +| `custom` | Custom | User-provided | User-provided | Yes | + +Each preset defaults Haiku/Sonnet/Opus to the same as main model. Users can override via advanced settings. + +## Data Flow + +``` +Preset Provider List (frontend hardcoded) + | +User selects preset -> enters API Key -> optionally customizes model mapping + | +Save -> write ~/.claude/cc-haha/providers.json (index of saved providers) + -> write ~/.claude/settings.json env block (active provider only) + | +Claude Code reads settings.json on next session +``` + +## Storage + +### Index File: `~/.claude/cc-haha/providers.json` + +Stores all saved provider profiles for switching. Lightweight — no full settingsConfig, just what's needed to reconstruct the env block. + +```json +{ + "activeId": "deepseek-1", + "providers": [ + { + "id": "deepseek-1", + "presetId": "deepseek", + "name": "DeepSeek", + "apiKey": "sk-xxx", + "baseUrl": "https://api.deepseek.com/anthropic", + "models": { + "main": "DeepSeek-V3.2", + "haiku": "DeepSeek-V3.2", + "sonnet": "DeepSeek-V3.2", + "opus": "DeepSeek-V3.2" + }, + "notes": "" + } + ] +} +``` + +For `custom` preset, `baseUrl` is user-provided. For other presets, `baseUrl` comes from the preset default but can be overridden. + +### settings.json env block (written on activation) + +Third-party provider activation writes 6 keys: + +```json +{ + "env": { + "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", + "ANTHROPIC_AUTH_TOKEN": "sk-xxx", + "ANTHROPIC_MODEL": "DeepSeek-V3.2", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "DeepSeek-V3.2", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "DeepSeek-V3.2", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "DeepSeek-V3.2" + } +} +``` + +Official provider activation removes these 6 keys from env, preserving all other settings.json fields. + +## Frontend UI + +### ProviderSettings Component + +Replaces current provider list + modal with: + +1. **Preset chip bar** — horizontal row: `官方` | `DeepSeek` | `ZhipuGLM` | `Kimi` | `MiniMax` | `自定义` +2. **Saved provider list** — cards showing each saved provider with active badge, switch/edit/delete actions +3. **Add/Edit form** (inline or modal): + - Preset selector (chips, pre-fills form) + - API Key input (not shown for official) + - Base URL input (only shown for custom preset, or editable in advanced) + - Model mapping (collapsible advanced section): Main / Haiku / Sonnet / Opus inputs, pre-filled from preset + - Notes (optional) + - Test Connection button + - Save / Cancel buttons + +### Activation Flow + +- Click "Activate" on a saved provider card +- Backend writes env to settings.json +- UI updates active badge +- Official preset clears env keys + +### Delete Provider + +- Cannot delete the active provider (must switch first, or switch to official) +- Confirmation dialog before delete + +## Backend Changes + +### New: `src/server/config/providerPresets.ts` + +Shared preset definitions used by both API validation and settings generation. + +```typescript +export type ProviderPreset = { + id: string + name: string + baseUrl: string + models: { main: string; haiku: string; sonnet: string; opus: string } + needsApiKey: boolean + websiteUrl: string +} +``` + +### Modified: `src/server/services/providerService.ts` + +- Change storage path from `~/.claude/providers.json` to `~/.claude/cc-haha/providers.json` +- Simplify provider data structure (remove ProviderModel array, use models record) +- `syncToSettings()` writes all 6 env keys +- New `clearProviderFromSettings()` for official preset — removes the 6 env keys +- Remove `activateProvider(id, modelId)` modelId param — models stored in provider config +- Ensure `~/.claude/cc-haha/` directory is created on first write + +### Modified: `src/server/api/providers.ts` + +- Update activate endpoint: `POST /api/providers/:id/activate` (no body needed) +- Add preset list endpoint: `GET /api/providers/presets` (returns preset definitions) + +### Deleted after migration + +- Old `~/.claude/providers.json` is not migrated — users reconfigure (acceptable since this is pre-release) + +## Frontend File Changes + +| Action | File | Description | +|--------|------|-------------| +| New | `desktop/src/config/providerPresets.ts` | Frontend preset definitions | +| Rewrite | `desktop/src/pages/Settings.tsx` ProviderSettings section | Preset-based UI | +| Modify | `desktop/src/types/provider.ts` | Simplify types (remove ProviderModel, add models record) | +| Modify | `desktop/src/stores/providerStore.ts` | Align with new API shape | +| Modify | `desktop/src/api/providers.ts` | Update activate call (remove modelId), add presets endpoint | + +## Backend File Changes + +| Action | File | Description | +|--------|------|-------------| +| New | `src/server/config/providerPresets.ts` | Preset definitions | +| Modify | `src/server/services/providerService.ts` | New storage path, simplified model structure, full env write | +| Modify | `src/server/types/provider.ts` | Simplify schema | +| Modify | `src/server/api/providers.ts` | Update routes | + +## Attribution + +```typescript +// Provider presets inspired by cc-switch (https://github.com/farion1231/cc-switch) +// Original work by Jason Young, MIT License +``` + +Added as comment header in preset configuration files. + +## Testing + +1. Select DeepSeek preset, enter API key, save — verify `~/.claude/cc-haha/providers.json` and `~/.claude/settings.json` written correctly +2. Switch to Kimi — verify settings.json updated, index updated +3. Switch to Official — verify env keys removed from settings.json +4. Edit a provider's model mapping — verify changes persisted +5. Test Connection — verify connectivity check works +6. Delete non-active provider — verify removed from index +7. Custom preset — verify baseUrl input appears, full flow works