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,143 @@
+---
+summary: "z.ai provider data sources: API token in config/env and quota API response parsing."
+read_when:
+  - Debugging z.ai token storage or quota parsing
+  - Updating z.ai API endpoints
+---
+
+# z.ai provider
+
+z.ai is API-token based. No browser cookies.
+
+## Token sources (fallback order)
+1) Config token (`~/.config/codexbar/config.json` or legacy `~/.codexbar/config.json` → `providers[].apiKey`).
+2) Environment variable `Z_AI_API_KEY`.
+
+### Config location
+- New installs: `~/.config/codexbar/config.json`
+- Legacy installs: `~/.codexbar/config.json`
+- Override for scripts/tests: `CODEXBAR_CONFIG=/path/to/config.json`
+
+## Setup
+
+Set **API region** to **Global (api.z.ai)** or **BigModel CN (open.bigmodel.cn)**.
+
+- UI: Settings → Providers → z.ai. For team usage, add a token account, turn on **Team mode**, then enter the API key,
+  Organization ID, and Project ID.
+- CLI personal:
+
+  ```bash
+  printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin
+  ```
+
+- CLI team:
+
+  ```bash
+  printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin \
+    --label Team \
+    --usage-scope team \
+    --organization-id org_... \
+    --workspace-id proj_...
+  ```
+
+- Check:
+
+  ```bash
+  codexbar config validate
+  codexbar usage --provider zai --account Team
+  ```
+
+Personal config can use `providers[].apiKey`. Team config uses `tokenAccounts`:
+
+```json
+{
+  "id": "zai",
+  "enabled": true,
+  "region": "bigmodel-cn",
+  "tokenAccounts": {
+    "version": 1,
+    "activeIndex": 0,
+    "accounts": [
+      {
+        "id": "00000000-0000-0000-0000-000000000001",
+        "label": "Team",
+        "token": "<z.ai API key>",
+        "addedAt": 0,
+        "lastUsed": null,
+        "usageScope": "team",
+        "organizationId": "org_...",
+        "workspaceID": "proj_..."
+      }
+    ]
+  }
+}
+```
+
+Keep `organizationId` and `workspaceID` single-line. Do not paste display names, URLs, or multiple IDs.
+
+## Finding the BigModel team IDs
+For BigModel China team usage, CodexBar needs the `Bigmodel-Organization` and `Bigmodel-Project` request headers:
+
+1. Open the BigModel API-key page and create/copy the API key:
+   - `https://bigmodel.cn/usercenter/proj-mgmt/apikeys`
+   - Some accounts still redirect through `https://open.bigmodel.cn/usercenter/apikeys`.
+2. Open the team usage dashboard:
+   - `https://bigmodel.cn/coding-plan/team/usage-stats`
+3. Select the organization/team and project to track.
+4. Open browser DevTools → Network, refresh the team usage page, and inspect the
+   request to `api/monitor/usage/quota/limit` or `api/monitor/usage/model-usage`. Copy these request headers:
+   - `Bigmodel-Organization` → `organizationId`
+   - `Bigmodel-Project` → `workspaceID`
+
+Copy each value once, on one line. Multi-line or duplicated IDs can make the API return `data: {}`, leaving MCP,
+5-hour, and hourly usage empty.
+
+## API endpoint
+- `GET https://api.z.ai/api/monitor/usage/quota/limit`
+- BigModel (China mainland) host: `https://open.bigmodel.cn`
+- Override host via Providers → z.ai → *API region* or `Z_AI_API_HOST=open.bigmodel.cn`.
+- Override the full quota URL (e.g. coding plan endpoint) via `Z_AI_QUOTA_URL=https://open.bigmodel.cn/api/coding/paas/v4`.
+- Endpoint overrides must be explicit HTTPS URLs or bare hosts/paths that CodexBar normalizes to HTTPS. Explicit
+  `http://` overrides fail closed before the bearer token is attached to a request. If both z.ai overrides are set,
+  `Z_AI_QUOTA_URL` has priority for quota requests; a stale lower-priority `Z_AI_API_HOST` is ignored for that quota
+  path, but direct model-usage requests still validate `Z_AI_API_HOST` before sending bearer auth.
+- Headers:
+  - `authorization: Bearer <token>`
+  - `accept: application/json`
+
+### BigModel team usage
+- The default usage scope is **personal**. Only a token account with `usageScope: team` is queried as team usage.
+- Each z.ai token account can enable **Team mode** via UI, CLI, or config. Team accounts store:
+  - `usageScope`: `team`
+  - `organizationId`: BigModel organization id
+  - `workspaceID`: BigModel project id
+- Team quota scope appends `type=2`; team hourly model usage appends `type=3`. Both send the BigModel selectors:
+  - `Bigmodel-Organization: <org id>`
+  - `Bigmodel-Project: <project id>`
+- Live API checks return success with empty limits when one of the selectors is missing, so CodexBar treats both
+  Organization ID and Project ID as required for team usage.
+
+## Usage dashboard
+- Global: `https://z.ai/manage-apikey/coding-plan/personal/my-plan`
+- BigModel China: `https://bigmodel.cn/coding-plan/personal/usage`
+- BigModel China team: `https://bigmodel.cn/coding-plan/team/usage-stats`
+- CodexBar's Usage Dashboard action follows the configured API region.
+
+## Parsing + mapping
+- Response fields:
+  - `data.limits[]` → each limit entry.
+  - `data.planName` (or `plan`, `plan_type`, `packageName`) → plan label.
+- Limit types:
+  - `TOKENS_LIMIT` → primary (tokens window).
+  - `TIME_LIMIT` → secondary (MCP/time window) if tokens also present.
+- Window duration:
+  - Unit + number → minutes/hours/days.
+- Reset:
+  - `nextResetTime` (epoch ms) → date.
+- Usage details:
+  - `usageDetails[]` per model (MCP usage list).
+
+## Key files
+- `Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift`
+- `Sources/CodexBarCore/Providers/Zai/ZaiSettingsReader.swift`
+- `Sources/CodexBar/ZaiTokenStore.swift` (legacy migration helper)