chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00
commit fc4fcbab58
1848 changed files with 472303 additions and 0 deletions
@@ -0,0 +1,50 @@
+---
+summary: "Moonshot / Kimi API provider data sources: API key + balance endpoint."
+read_when:
+  - Adding or tweaking Moonshot balance parsing
+  - Updating Moonshot / Kimi API key handling
+  - Documenting Moonshot / Kimi API provider behavior
+---
+
+# Moonshot / Kimi API provider
+
+Moonshot / Kimi API is API-only. Balance is reported by `GET /v1/users/me/balance`,
+so CodexBar only needs a valid API key to show the current account balance.
+
+## Rationale
+
+Kimi API docs use the Moonshot API surface for current Kimi models: examples read
+`MOONSHOT_API_KEY` and call `https://api.moonshot.ai/v1`, including the Kimi K2.6
+quickstart. This provider is therefore named after the account and billing surface,
+not a specific Kimi model version.
+
+The existing `Kimi K2` provider remains separate because it targets the legacy
+`kimi-k2.ai` credit endpoint. Migrating or deprecating that provider should be a
+separate cleanup so existing user settings are not silently repointed.
+
+## Data sources
+
+1. **API key** stored in `~/.codexbar/config.json` or supplied via `MOONSHOT_API_KEY` / `MOONSHOT_KEY`.
+   CodexBar stores the key in config after you paste it in Settings → Providers → Moonshot / Kimi API.
+2. **Region**
+   - International: `https://api.moonshot.ai/v1/users/me/balance`
+   - China mainland: `https://api.moonshot.cn/v1/users/me/balance`
+   - Configure with Settings → Providers → Moonshot → API region or `MOONSHOT_REGION`.
+3. **Balance endpoint**
+   - Request headers: `Authorization: Bearer <api key>`, `Accept: application/json`
+   - Response contains `available_balance`, `voucher_balance`, and `cash_balance`.
+
+## Usage details
+
+- The menu card shows the available balance.
+- If `cash_balance` is negative, the card also surfaces the deficit.
+- There is no session or weekly window — Moonshot / Kimi API does not expose per-window quota via API.
+- Settings config takes precedence over environment variables when both are present.
+
+## Key files
+
+- `Sources/CodexBarCore/Providers/Moonshot/MoonshotProviderDescriptor.swift` (descriptor + fetch strategy)
+- `Sources/CodexBarCore/Providers/Moonshot/MoonshotUsageFetcher.swift` (HTTP client + JSON parser)
+- `Sources/CodexBarCore/Providers/Moonshot/MoonshotSettingsReader.swift` (env var resolution)
+- `Sources/CodexBar/Providers/Moonshot/MoonshotProviderImplementation.swift` (settings field + activation logic)
+- `Sources/CodexBar/Providers/Moonshot/MoonshotSettingsStore.swift` (SettingsStore extension)