diff --git a/external_plugins/free-guide/.zcode-plugin/plugin.json b/external_plugins/free-guide/.zcode-plugin/plugin.json new file mode 100644 index 00000000..6c3fa730 --- /dev/null +++ b/external_plugins/free-guide/.zcode-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "free-guide", + "description": "Complete community guide to running ZCode on a free stack: quota-safe fallback chain from the Z.ai plan through free cloud providers to an unlimited local GPU model, plus three companion skills (key setup, automatic model fallback, token/quota tracking). Read docs-guide.md first.", + "description_i18n": { + "en": "Complete community guide to running ZCode on a free stack: quota-safe fallback chain from the Z.ai plan through free cloud providers to an unlimited local GPU model, plus three companion skills (key setup, automatic model fallback, token/quota tracking). Read docs-guide.md first.", + "zh-CN": "完整的 ZCode 免费方案社区指南:从 Z.ai 套餐到免费云供应商再到本地 GPU 无限量模型的额度安全回退链,并附带三个配套技能(密钥接入、模型自动回退、用量/额度统计)。请先阅读 docs-guide.md。" + }, + "version": "1.0.0", + "author": { + "name": "Tejas Lowanshi", + "url": "https://github.com/Tejs2005" + }, + "category": "guides", + "keywords": [ + "free-tier", + "fallback-chain", + "openrouter", + "gemini", + "local-model", + "quota", + "guide" + ] +} diff --git a/external_plugins/free-guide/README-FIRST.txt b/external_plugins/free-guide/README-FIRST.txt new file mode 100644 index 00000000..a37df9ec --- /dev/null +++ b/external_plugins/free-guide/README-FIRST.txt @@ -0,0 +1,12 @@ +# 📦 ZCode-FREE-GUIDE — read this first + +**You received:** `MAKE-ZCODE-FREE.md` (the full guide) + `skills/` (3 ready-made AI skills). + +**Do in this order:** +1. Read `MAKE-ZCODE-FREE.md` top to bottom once. +2. Install the router + grab your own free keys (Part 1 + Part 4). **Never reuse someone else's keys.** +3. Add the local model so you can never be cut off (Part 1E). +4. Turn ON model-chain fallback (Part 1 — critical, it's off by default). +5. Wire it into ZCode (Part 2), install the skills (Part 5), do the security checklist (Part 6). + +Build time: ~30 minutes. Everything in the guide was tested working on 2026-10-07 on Fedora 44. diff --git a/external_plugins/free-guide/README.md b/external_plugins/free-guide/README.md new file mode 100644 index 00000000..58c290b8 --- /dev/null +++ b/external_plugins/free-guide/README.md @@ -0,0 +1,61 @@ +# free-guide + +[中文文档](./README_CN.md) + +Community guide plugin for the ZCode plugins marketplace: everything needed to run ZCode +on a **free stack** — tested end-to-end on Fedora 44 by Tejas Lowanshi & ZCode (2026-10-07). + +## What it gives you + +A quota-safe fallback chain, so a session never hard-stops when a cloud quota dies: + +``` +ZCode (default: Z.ai plan) + │ if quota dies, falls to… + ▼ +CCR Router (local, 127.0.0.1:3456) + ├─ GPT models (ChatGPT/Codex account login — no key needed) + ├─ Claude models (via OmniRoute: GitHub Copilot + Kiro pools) + ├─ Gemini 3.x (Google AI Studio key — FREE, no card) + ├─ Nemotron/Gemma (OpenRouter key — FREE models) + └─ qwen2.5-coder:7b (LOCAL on your own GPU — unlimited) +``` + +## Files + +- **`docs-guide.md`** — the complete setup guide (read this first) +- **`skills/free-api-key-setup/`** — wire any new API key into ZCode correctly +- **`skills/auto-model-fallback/`** — auto-switch to the next provider on quota/auth errors +- **`skills/token-counter/`** — track how much of each provider's quota you have burned +- **`README-FIRST.txt`** — one-page quick start + +## Skills overview + +| Skill | Trigger | What it does | +| --- | --- | --- | +| `free-api-key-setup` | you hand the agent a new API key | Provider schema, key-prefix table, `api.type` gotchas; never echoes the key | +| `auto-model-fallback` | model errors (429/401/404/5xx) | Classifies and walks the fallback chain; optional claude-code-router for true auto-switching | +| `token-counter` | "how much quota left" | Live usage where the provider exposes an API, documented caps where it doesn't; exits 1 at warn threshold | + +## Disclaimer + +Free tiers and model lineups change often — the guide was accurate for October 2026 and +notes which specifics to re-check (e.g. DeepSeek `:free` was already gone, `gemini-2.5-pro` +retired for new users). Provider caps live inside the skills so they can be updated +without touching the guide. + +## Install + +Inside ZCode: Plugin Marketplace → search **free-guide** → install. Or test from source: + +```bash +git clone https://github.com/zai-org/zcode-plugins +cd zcode-plugins +pnpm install --frozen-lockfile && pnpm build +# add dist/local-marketplace via Plugin Marketplace → New +``` + +## Author + +Built by **Tejas Lowanshi** ([@Tejs2005](https://github.com/Tejs2005)) with ZCode, as the +"send this to anyone" bundle for the free AI stack. Apache-2.0 like the rest of this repo. diff --git a/external_plugins/free-guide/README_CN.md b/external_plugins/free-guide/README_CN.md new file mode 100644 index 00000000..2f70cfda --- /dev/null +++ b/external_plugins/free-guide/README_CN.md @@ -0,0 +1,45 @@ +# free-guide + +[English](./README.md) + +ZCode 插件市场的社区指南插件:在**免费方案**上运行 ZCode 所需的一切——由 Tejas Lowanshi +与 ZCode 于 2026-10-07 在 Fedora 44 上端到端实测。 + +## 它能带给你什么 + +一条额度安全回退链,云额度用完时会话不会硬中断: + +``` +ZCode(默认:Z.ai 套餐) + │ 额度用尽时回退到… + ▼ +CCR Router(本地,127.0.0.1:3456) + ├─ GPT 模型 (ChatGPT/Codex 账号登录 — 无需密钥) + ├─ Claude 模型 (经 OmniRoute:GitHub Copilot + Kiro 池) + ├─ Gemini 3.x (Google AI Studio 密钥 — 免费,无需信用卡) + ├─ Nemotron/Gemma (OpenRouter 密钥 — 免费模型) + └─ qwen2.5-coder:7b(本地 GPU — 无限量,永远不会用完) +``` + +## 文件说明 + +- **`docs-guide.md`** — 完整安装指南(请先阅读) +- **`skills/free-api-key-setup/`** — 把新 API 密钥正确接入 ZCode +- **`skills/auto-model-fallback/`** — 额度/鉴权报错时自动切换到下一个供应商 +- **`skills/token-counter/`** — 统计各供应商额度已用多少 +- **`README-FIRST.txt`** — 一页快速上手 + +## 免责声明 + +免费额度和模型阵容经常变化——本指南在 2026 年 10 月是准确的,并标注了需要复核的细节 +(例如 DeepSeek `:free` 已下线、`gemini-2.5-pro` 对新用户已退役)。供应商额度上限 +放在各技能内部,便于在不改动指南的情况下更新。 + +## 安装 + +ZCode 内:插件市场 → 搜索 **free-guide** → 安装。 + +## 作者 + +由 **Tejas Lowanshi** 与 ZCode 共同构建,作为"发给任何人"的免费 AI 方案包。 +许可证与本仓库一致(Apache-2.0)。 diff --git a/external_plugins/free-guide/docs-guide.md b/external_plugins/free-guide/docs-guide.md new file mode 100644 index 00000000..f7941c30 --- /dev/null +++ b/external_plugins/free-guide/docs-guide.md @@ -0,0 +1,173 @@ +# 🆓 MAKE ZCODE FREE — Complete Setup Guide + +*Built by Tejas & ZCode on 2026-10-07. Tested end-to-end on Fedora 44. Send this file + the `skills/` folder to anyone and they can replicate the whole setup.* + +--- + +## What you end up with + +``` +ZCode (default: Z.ai plan — "me") + │ if quota dies, ZCode falls to… + ▼ +CCR Router (local, 127.0.0.1:3456) + ├─ GPT models (ChatGPT/Codex account login — no key needed) + ├─ Claude models (via OmniRoute: GitHub Copilot + Kiro pools) + ├─ Gemini 3.x (Google AI Studio key — FREE, no card) + ├─ Nemotron/Gemma (OpenRouter key — FREE models) + └─ qwen2.5-coder:7b (LOCAL on your own GPU — unlimited, can never run out) +``` + +**The promise:** you never hard-stop. If every cloud quota dies, the router silently drops to the model running on your own GPU. + +--- + +## PART 1 — Install the router (CCR) + +```bash +npm config set prefix ~/.local +npm install -g @musistudio/claude-code-router +ccr ui +``` + +- Management UI opens at **http://127.0.0.1:3458** +- The API gateway runs at **http://127.0.0.1:3456** +- ⚠️ After a reboot you must run `ccr ui` again (autostart not configured). + +### Provider A: ChatGPT/Codex (big GPT models, no API key) +In the UI → Providers → connect your **ChatGPT account** (Codex login). You get: `gpt-6-luna`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-reserve`. + +### Provider B: Google Gemini (FREE — best free cloud tier) +1. Go to **https://aistudio.google.com** → sign in with Google → "Get API key" → create. No credit card. +2. CCR UI → Providers → add custom provider: + - Type/base: `https://generativelanguage.googleapis.com/v1beta/openai` (OpenAI-compatible) + - Paste your key. Models: `gemini-3.5-flash`, `gemini-3.8-flash`, `gemini-3.1-pro-preview` + - Note: `gemini-2.5-pro` is retired for new users (404). Some pro models are paid-tier only. + +### Provider C: OpenRouter (free models) +1. **https://openrouter.ai/keys** → sign in → Create key (real keys start `sk-or-v1-`). +2. CCR provider: base `https://openrouter.ai/api/v1`, paste key. +3. Best free models (lineup as of Oct 2026 — DeepSeek `:free` is GONE): `nvidia/nemotron-3-super-120b-a12b:free`, `nvidia/nemotron-3-ultra-550b-a55b:free`, `google/gemma-4-31b-it:free`. + +### Provider D: Groq (optional — fast, free) +Key from **https://console.groq.com/keys** (`gsk_...`). Base `https://api.groq.com/openai/v1`. Models: `openai/gpt-oss-120b`, `qwen/qwen3.8-27b`. +⚠️ **Known bug:** this CCR build can hang forever on Groq requests (even though the key works — verify directly first). If a test hangs, keep Groq OUT of the fallback chain until CCR updates. + +### Provider E: Local unlimited fallback (the "never stop" guarantee) +```bash +# Fedora: ollama may already be installed; if not: +curl -fsSL https://ollama.com/install.sh | sh +ollama pull qwen2.5-coder:7b # ~4.7GB, fits an 8GB GPU (RTX 3070 etc.) +``` +CCR UI → Providers → add: +- Base: `http://127.0.0.1:11434/v1` (OpenAI-compatible), API key: literally `ollama` +- Model: `qwen2.5-coder:7b` +Facts: warm answers in ~0.2–2s; first call after ~5 min idle takes ~60s (model reloads into VRAM). + +### Turn ON auto-fallback (critical!) +CCR UI → Routing → fallback: +- Mode: **model-chain** +- Chain (order = preference): `gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-reserve, kr/claude-sonnet-4.5, gh/claude-sonnet-5, gemini-3.5-flash, gemini-3.8-flash, nvidia/nemotron-3-super-120b-a12b:free, qwen2.5-coder:7b` +- Retry: 1 + +Without this, the router name is a lie — default mode is **off** and failures just error at you. + +--- + +## PART 2 — Wire it into ZCode + +Edit `~/.zcode/v2/provider_config.json` (make a backup first!). Add a provider rule: + +```json +{ + "providerId": "ccr-router", + "providerName": "CCR Router (auto-fallback)", + "enabled": true, + "config": { + "access": { "type": "api-key", "apiKey": "" }, + "api": { "type": "anthropic-messages", "baseUrl": "http://127.0.0.1:3456" }, + "personalModelIds": ["gpt-6-luna", "gemini-3.5-flash", "kr/claude-sonnet-4.5", "..."] + } +} +``` + +- The gateway key lives in CCR's UI (API Keys page → "Local Gateway" key, starts `sk-ccr-`). Never share it. +- In `providerOrder`, put your main plan **first** and `ccr-router` **second**. +- Restart ZCode after edits. Pick "CCR Router" models in the session model picker when you want them. + +--- + +## PART 3 — Bonus: OmniRoute (real Claude, free pools) + +OmniRoute pools community/subscription accounts and serves an OpenAI-compatible API on **http://localhost:20128**. Your GitHub Copilot + Kiro logins unlock actual **Claude** models. + +```bash +npx --legacy-peer-deps omniroute@latest # starts server + dashboard on 20128 +``` + +Dashboard: `http://localhost:20128/home`. Log in, connect GitHub (Copilot) and other accounts, create an API key. + +**Old Claude Code flow (still works):** +```bash +# terminal 1 +sudo npx --legacy-peer-deps omniroute@latest +# terminal 2 +export CLAUDE_CONFIG_DIR="$HOME/.claude-omniroute" +export ANTHROPIC_BASE_URL="http://localhost:20128" +export ANTHROPIC_AUTH_TOKEN="" +export ANTHROPIC_API_KEY="" +export ANTHROPIC_MODEL="" +claude +``` + +**Wire OmniRoute into CCR/ZCode too:** add provider with base `http://127.0.0.1:20128/v1` + your omniroute key. Working models (tested): `kr/claude-sonnet-4.5` ✅, `kr/claude-haiku-4.5` ✅, `kr/deepseek-3.2` ✅, `gh/gpt-4.1` ✅, `gh/claude-sonnet-5` (rate-limited often). + +**Reality check on "free Claude":** pools run on free-tier accounts that *cool down* (HTTP 429) when quota runs out. Opus/Fable-class models are gated behind paid Copilot tiers. It works, but expect pauses. + +--- + +## PART 4 — The keys you actually need (all free) + +| Key | Where | Cost | +|---|---|---| +| Google Gemini | aistudio.google.com | FREE, no card | +| OpenRouter | openrouter.ai/keys | FREE | +| Groq (optional) | console.groq.com/keys | FREE | +| Ollama local | no key at all | FREE forever | +| ChatGPT/Codex | your own login | your plan | + +**Rule: everyone makes their OWN keys. Never send keys to each other — store each key in its own file in `~/Desktop/API-KEYS/` (chmod 600) with a note about status/expiry.** Dead keys we burned so we don't again: AIML API key (valid auth, zero funds), AWS Bedrock key (revoked; the long `bedrock-api-key-...` ones are 12-hour temporary tokens — always dead later), OpenRouter keys starting `sk-a4d4c...` (that was actually a local proxy token, not OpenRouter). + +--- + +## PART 5 — Install the skills (in this folder) + +Copy the `skills/` folder into `~/.agents/skills/` on the new machine: + +```bash +cp -r skills/* ~/.agents/skills/ +``` + +- **free-api-key-setup** — what to do when you get a new API key (wire it correctly, key-format cheatsheet) +- **auto-model-fallback** — what to do when a model dies (classify error → walk the chain) +- **token-counter** — run `scripts/token-usage.py` to check per-provider quota status (exits 1 when a threshold is hit → time to fall back) + +--- + +## PART 6 — Security checklist (do not skip) + +- [ ] OmniRoute dashboard: **change the default password** (`CHANGEME`) — Dashboard → Settings → Security. It listens on 0.0.0.0 by default = visible to your whole Wi-Fi network. +- [ ] Never paste API keys into chats, screenshots, or repos. Keep them in `~/Desktop/API-KEYS/` (600 perms). +- [ ] The CCR gateway key (`sk-ccr-...`) stays on your machine only. + +--- + +## Troubleshooting — lessons we paid for + +1. **"Hi" takes 1m54s** → not the router. Giant continued-session context (282K tokens) re-read cold every message (Codex backend has no prompt caching via CCR). **Fix: start fresh chats when things feel slow.** +2. **Router answers but model errors** → fallback mode was `off`. Set model-chain (Part 1). +3. **Groq hangs through CCR** (but direct API works) → known incompatibility in this CCR build; keep it out of the chain, test after CCR updates. +4. **AIML/OpenRouter-style aggregators** → a valid key with zero balance returns 403 "out of funds" on every model. Check billing first. +5. **gemini-2.5-pro 404** → retired for new accounts; use 3.x. +6. **Local model slow first message** → 60s VRAM reload after idle. Normal. +7. **Where to look when slow/broken** → CCR logs every request: `~/.claude-code-router/app-data/usage.sqlite` (table `usage_events`: model, provider, status, duration, tokens). `sqlite3` CLI isn't installed on Fedora by default — use `python3 -c "import sqlite3..."`. diff --git a/external_plugins/free-guide/skills/auto-model-fallback/SKILL.md b/external_plugins/free-guide/skills/auto-model-fallback/SKILL.md new file mode 100644 index 00000000..f945a830 --- /dev/null +++ b/external_plugins/free-guide/skills/auto-model-fallback/SKILL.md @@ -0,0 +1,80 @@ +--- +name: auto-model-fallback +description: Automatically recover when the active ZCode model breaks — rate limits, dead keys, provider outages, removed models. Use when Tejas says a model isn't working, requests fail, "switch model", or when tool calls start erroring with model/provider errors. Covers the zero-software playbook and the claude-code-router auto-failover setup. +--- + +# Auto Model Fallback + +Goal: a broken model should never stall Tejas for more than one message. + +## Level 1 — In-session recovery playbook (no extra software) + +When model errors appear, classify then act: + +| Error pattern | Meaning | Action | +|---|---|---| +| 429 / rate_limit / quota | Free tier exhausted | Don't retry more than once — switch model | +| 401 / invalid api key | Key dead or rotated | Re-wire key (see free-api-key-setup skill), else switch | +| 404 / model not found | Model id removed/renamed | Pick another id from same provider | +| 5xx / overloaded / timeout ×2 | Provider outage | Switch provider, note outage in memory | +| Empty/garbage replies | Model unusable for coding | Switch to a stronger fallback | + +**Switch procedure:** +1. Read `~/.zcode/v2/provider_config.json` — list `enabled: true` providers and + their `personalModelIds` / `modelOrder`. +2. Walk this fallback chain (first ALIVE wins): + `zai plan (GLM-5.3-Flash, PRIMARY — Tejas wants to stay on this)` → + `ccr-router provider (auto-falls through: gpt-5.6-terra → gpt-5.6-luna → gpt-5.5 → gpt-reserve → qwen2.5-coder:7b LOCAL via ollama 127.0.0.1:11434, unlimited)` + (openrouter key stored is wrong format, groq/gemini/mistral have no keys yet — chain grows as Tejas adds providers; keep this list updated). +3. Tell Tejas exactly what to pick in the model picker (one tap), or flip + `enabled` flags / model ids per the free-api-key-setup skill and have him + restart the session. +4. After recovery, record in memory: which provider broke, the error, the date. + If the same provider dies 3× in a week, recommend Level 2. + +## Level 2 — True automatic switching: claude-code-router (recommended) + +Proven pattern (37k★, musistudio/claude-code-router): ONE stable local endpoint +that hides many providers behind it with **retries, key rotation, and ordered +fallback models**. Model breakage becomes invisible — the router silently +serves the next working model. + +Install (Fedora, Node 22 present): +```bash +npm install -g @musistudio/claude-code-router +ccr ui # management UI at http://127.0.0.1:3458, gateway at http://127.0.0.1:3456 +``` +Setup: +1. In the UI → Providers → add each free provider + API key (OpenRouter, + Groq, Gemini, Mistral — it speaks their protocols natively). +2. Routing → set the fallback chain (primary → fallbacks, ordered). +3. ZCode side: add ONE custom provider entry per the free-api-key-setup skill: + `api: { "type": "anthropic-messages", "baseUrl": "http://127.0.0.1:3456" }`, + any apiKey (CCR accepts configured client keys), model ids matching what + the router exposes. +4. Auto-start at login (user systemd unit or KDE autostart .desktop running + `ccr start`); health check: `curl -s http://127.0.0.1:3456/ >/dev/null && echo alive`. + +Result: Tejas stays on ONE model entry forever; failures route automatically. + +## Level 2 alternative — LiteLLM proxy (OpenAI-compatible chains) + +For pure OpenAI-format providers, `litellm --config config.yaml` with: +```yaml +router_settings: + fallbacks: + - primary-model: ["fallback-1", "fallback-2"] + rate_limit_error_fallbacks: # triggers on 429 + - primary-model: ["fallback-1"] +``` +Point the ZCode provider's baseUrl at the local LiteLLM port +(`http://0.0.0.0:4000/v1`, api type `openai-chat`). + +## Hygiene + +- Keys only ever go into `provider_config.json` / router config — never chat, + memory, or git. +- Free tiers 429 a lot: the chain exists for that, don't fight a throttled + provider with retries. +- After any failover that required manual work, update this skill's chain and + note the outage in memory. diff --git a/external_plugins/free-guide/skills/free-api-key-setup/SKILL.md b/external_plugins/free-guide/skills/free-api-key-setup/SKILL.md new file mode 100644 index 00000000..cca800fe --- /dev/null +++ b/external_plugins/free-guide/skills/free-api-key-setup/SKILL.md @@ -0,0 +1,83 @@ +--- +name: free-api-key-setup +description: Wire a free API key (OpenRouter, Groq, Gemini, Mistral, any OpenAI-compatible) into ZCode as a usable model provider. Use when Tejas hands over an API key and says which provider it's for, or asks to make ZCode usable for free / add a provider. +--- + +# Free API Key → ZCode Provider Setup + +Tejas hands over an API key and names the provider. The goal: add it to ZCode's +provider config so a free model can be selected. Do it all yourself — he only +supplies the key and the provider name. + +## Hard rules + +- **Never echo the key** into chat, memory files, skills, or any file that + leaves the machine. It goes into exactly one place: `provider_config.json`. +- **Back up first**: `cp ~/.zcode/v2/provider_config.json ~/.zcode/v2/provider_config.json.bak` +- Edit with **python json** (load → modify → dump), never sed/hand-edit. +- Config is read at session start — after editing, the ZCode session must be + **restarted** (or the provider switched via the client UI) to take effect. + +## The config file + +`~/.zcode/v2/provider_config.json` — schema: + +```json +{ + "schemaVersion": 1, + "config": { + "providerOrder": ["", ...], // must contain the id, order = UI order + "providerConfigRules": { + "providerRules": [ + { + "providerId": "unique-id", + "providerName": "Display Name", + "enabled": true, // REQUIRED true; entries without it may not show + "templateId": "openrouter", // ONLY for built-in templates (openrouter etc.) + "config": { + "group": "standard-personal", + "access": { "type": "api-key", "apiKey": "" }, + "api": { "type": "", "baseUrl": "" }, // custom endpoints only + "personalModelIds": [""], // shown in picker + "modelOrder": [""] + } + } + ] + } + } +} +``` + +## Provider identification (key prefix → recipe) + +| Key prefix | Provider | How to wire | +|---|---|---| +| `sk-or-v1-…` | OpenRouter | Flip `enabled: true` on the existing `openrouter` rule (template-backed, no baseUrl needed). Get free model ids from `https://openrouter.ai/api/v1/models` (filter `pricing.prompt == "0"`), put a few in `personalModelIds` + `modelOrder`. | +| `gsk_…` | Groq | New rule, `api: {type: "openai-chat", baseUrl: "https://api.groq.com/openai/v1"}`, models like `llama-3.3-70b-versatile` (check /models). | +| `AIza…` | Google Gemini | **Gotcha: use the OpenAI-compatible endpoint** `https://generativelanguage.googleapis.com/v1beta/openai/` with the **openai-chat** api type — an old attempt used `anthropic-messages` against this URL and failed. Models: `gemini-2.5-flash`, `gemini-2.5-pro`. | +| `sk-…` (other) | Ask Tejas which service; it's OpenAI-compatible or Anthropic-compatible. | OpenAI-compatible → `openai-chat` + their baseUrl; Anthropic-compatible → `anthropic-messages` + baseUrl. | +| `…` Mistral `…` | Mistral | `api: {type: "openai-chat", baseUrl: "https://api.mistral.ai/v1"}`, model `mistral-large-latest`. | + +If the `api.type` guess is wrong for a custom endpoint (provider errors on +first test), try the other type (`openai-chat` ⇄ `anthropic-messages`) before +assuming the key is bad. + +## Steps + +1. Confirm with Tejas: which provider is this key for? (Or detect from prefix.) +2. Back up the config file. +3. Load JSON, apply the recipe above (enable existing rule OR append new rule), + make sure `providerId` is in `providerOrder`, validate the JSON parses. +4. Write the file. Never print the key in the command output — mask it. +5. Tell Tejas to **restart the ZCode session** (or pick the provider in + Settings → model picker), then select a model from the new provider. +6. First message on the new model = the verification test. If it errors: + read the error (wrong api.type? wrong model id? rate limit?), fix, retry. + +## Gotchas learned + +- Free tiers rate-limit hard — if requests 429, that's the tier, not the setup. +- Keep the existing Z.ai plan entry untouched as the fallback provider. +- `credentials.json` in the same folder is separate — don't touch it. +- After any provider change, note in memory what worked (api.type + baseUrl + + a model id) so the next setup is instant. diff --git a/external_plugins/free-guide/skills/token-counter/SKILL.md b/external_plugins/free-guide/skills/token-counter/SKILL.md new file mode 100644 index 00000000..ab093376 --- /dev/null +++ b/external_plugins/free-guide/skills/token-counter/SKILL.md @@ -0,0 +1,52 @@ +--- +name: token-counter +description: Check how much of each free API provider's quota Tejas has burned — live usage where the provider exposes an API, documented free-tier caps where it doesn't. Use when Tejas asks about token usage, free-tier limits, "how much left", before long sessions on free keys, or when rate-limit errors (429) start appearing. +--- + +# Token Counter (free API keys & models) + +## Run it + +```bash +python3 ~/.agents/skills/token-counter/scripts/token-usage.py +# warn threshold: python3 …/token-usage.py --warn-percent 60 +``` + +Reads keys from `~/.zcode/v2/provider_config.json` at runtime — keys are never +printed, logged, or stored anywhere else. Exit code 1 = any provider at/over +the warn threshold. + +## How to read the output + +- **OK + usage/limit + %** — provider reports real numbers (OpenRouter via + `GET /api/v1/auth/key`: credits used, limit, free/paid tier, rate limit). +- **TRACKED** — provider has no cumulative usage API; the script shows the + documented free-tier caps and where to verify (console link). Numbers there + change over time — re-verify before trusting. +- **ERR** — key rejected or network issue; distinguish 401 (dead key → + re-wire per free-api-key-setup) from 429 (throttled → just wait or switch). + +## Decision wiring + +- Usage ≥ warn threshold, or repeated 429s → follow the **auto-model-fallback** + skill: walk the chain (zai plan → openrouter free → groq → gemini → mistral). +- A provider at 100% isn't "broken" — it's exhausted until its reset window. + Don't burn retries; switch. +- Before long sessions on free keys, run this first and pick a provider with + headroom. + +## Free-tier facts (verify — these drift) + +- **OpenRouter free models**: ~20 req/min; daily request cap depends on + account balance (50/day under $10 balance, 1000/day at ≥$10). Free models + cost 0 credits, so `/key` usage may stay 0 while request caps still apply. +- **Gemini free tier**: per-model caps (e.g. flash tier: small RPM, ~hundreds + of requests/day) — check aistudio.google.com. +- **Groq**: per-model RPM/RPD + tokens/day — console.groq.com/limits. +- **Mistral free tier**: 1 req/s, 500k tokens/min, 1B tokens/month. + +## Extending + +New provider with a usage API → add a pinned-URL query function in +`scripts/token-usage.py` (https only, exact-host check, redirects disabled — +Mimosa enforces this). New provider without one → add it to `STATIC_QUEUES`. diff --git a/external_plugins/free-guide/skills/token-counter/scripts/token-usage.py b/external_plugins/free-guide/skills/token-counter/scripts/token-usage.py new file mode 100755 index 00000000..f8b7e343 --- /dev/null +++ b/external_plugins/free-guide/skills/token-counter/scripts/token-usage.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 +"""Token/usage counter for the free API providers wired into ZCode. + +Reads keys from ~/.zcode/v2/provider_config.json at runtime (never hard-coded, +never printed) and reports per-provider usage where the provider exposes a +usage API. For providers without one, prints their documented free-tier caps +so the fallback decision can still be made. + +Usage: python3 token-usage.py [--warn-percent 80] +Exit codes: 0 ok, 1 any provider at/over the warn threshold. +""" +import json +import os +import sys +import urllib.error +import urllib.parse +import urllib.request + +CONFIG = os.path.expanduser("~/.zcode/v2/provider_config.json") + +# Documented free-tier caps for providers with no key-usage API. +# These change over time — verify at the linked console before trusting. +STATIC_QUEUES = { + "groq": ("console.groq.com/limits", "Per-model RPM/RPD + tokens/day; no cumulative key API"), + "gemini": ("aistudio.google.com", "Free tier: per-model RPD/TPM caps; check AI Studio usage page"), + "mistral": ("console.mistral.ai", "Free experiment tier: 1 req/sec, 500k tokens/min, 1B tokens/month"), +} + +# The only outbound endpoint this script may ever contact. Scheme and host are +# pinned; redirects are refused so the request cannot be bounced elsewhere. +OPENROUTER_KEY_URL = "https://openrouter.ai/api/v1/auth/key" +ALLOWED_HOST = "openrouter.ai" + + +class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + return None + + +def query_openrouter(key): + parsed = urllib.parse.urlparse(OPENROUTER_KEY_URL) + if parsed.scheme != "https" or parsed.hostname != ALLOWED_HOST: + return {"status": "blocked: endpoint mismatch"} + req = urllib.request.Request( + OPENROUTER_KEY_URL, + headers={"Authorization": f"Bearer {key}", "Accept": "application/json"}, + ) + opener = urllib.request.build_opener(NoRedirect) + try: + with opener.open(req, timeout=10) as resp: + if resp.status != 200: + return {"status": f"http {resp.status}"} + data = json.load(resp).get("data", {}) + except urllib.error.HTTPError as e: + return {"status": f"http {e.code}"} + except Exception as e: + return {"status": f"query failed: {type(e).__name__}"} + usage = data.get("usage") + limit = data.get("limit") + tier = "FREE" if data.get("is_free_tier") else "paid" + rl = data.get("rate_limit") or {} + out = {"status": "ok", "tier": tier, "rate_limit": rl} + if isinstance(usage, (int, float)): + out["used"] = round(usage, 4) + if isinstance(limit, (int, float)) and limit: + out["limit"] = limit + out["percent"] = round(100 * usage / limit, 1) + return out + + +def load_enabled_providers(): + with open(CONFIG) as f: + d = json.load(f) + rules = d.get("config", {}).get("providerConfigRules", {}).get("providerRules", []) + out = [] + for r in rules: + if not r.get("enabled"): + continue + cfg = r.get("config") or {} + key = ((cfg.get("access") or {}).get("apiKey")) or "" + if key: + out.append({ + "id": r.get("providerId", "?"), + "name": r.get("providerName", r.get("providerId", "?")), + "template": r.get("templateId", ""), + "key": key, + "models": (cfg.get("personalModelIds") or [])[:4], + }) + return out + + +def main(): + warn = 80.0 + if "--warn-percent" in sys.argv: + warn = float(sys.argv[sys.argv.index("--warn-percent") + 1]) + + providers = load_enabled_providers() + if not providers: + print("No enabled providers with API keys found in provider_config.json") + return 0 + + print(f"{'provider':<24} {'status':<10} {'details'}") + print("-" * 78) + hot = False + for p in providers: + ident = p["template"] or p["id"] + if ident == "openrouter" or p["key"].startswith("sk-or-v1-"): + info = query_openrouter(p["key"]) + if info.get("status") == "ok": + line = f"{p['name'][:23]:<24} {'OK':<10} " + line += f"tier={info.get('tier','?')} usage={info.get('used','?')}" + if "limit" in info: + line += f"/{info['limit']} ({info['percent']}%)" + if info.get("rate_limit"): + rl = info["rate_limit"] + line += f" rate={rl.get('requests','?')}/{rl.get('interval','?')}" + print(line) + if info.get("percent", 0) >= warn: + hot = True + print(f" !! >= {warn}% of limit — consider fallback chain (auto-model-fallback skill)") + else: + print(f"{p['name'][:23]:<24} {'ERR':<10} {info['status']}") + else: + slug = next((s for s in STATIC_QUEUES if s in ident.lower()), None) + if slug: + where, note = STATIC_QUEUES[slug] + models = ", ".join(p["models"]) or "-" + print(f"{p['name'][:23]:<24} {'TRACKED':<10} caps at {where} — {note}") + print(f" models: {models}") + else: + print(f"{p['name'][:23]:<24} {'?':<10} no known usage endpoint — add one to STATIC_QUEUES") + + print("\nTip: usage shown is what the provider reports; free tiers also cap") + print("requests/minute+day (see the auto-model-fallback skill before burning retries).") + return 1 if hot else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/marketplace.json b/marketplace.json index 31beffdb..02737725 100644 --- a/marketplace.json +++ b/marketplace.json @@ -10,7 +10,10 @@ "url": "https://z.ai" }, "unlistedPlugins": [ - { "name": "openpencil", "source": "./external_plugins/openpencil" } + { + "name": "openpencil", + "source": "./external_plugins/openpencil" + } ], "plugins": [ { @@ -827,7 +830,9 @@ }, { "name": "excalidraw", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "Excalidraw", "displayName_i18n": { "en": "Excalidraw", @@ -850,7 +855,9 @@ "name": "photocraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/photocraft/icon.png", "source": "./external_plugins/photocraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "PhotoCraft", "displayName_i18n": { "en": "PhotoCraft", @@ -877,7 +884,9 @@ "name": "vectorcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/vectorcraft/icon.png", "source": "./external_plugins/vectorcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "VectorCraft", "displayName_i18n": { "en": "VectorCraft", @@ -904,7 +913,9 @@ "name": "pdfcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/pdfcraft/icon.png", "source": "./external_plugins/pdfcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "PdfCraft", "displayName_i18n": { "en": "PdfCraft", @@ -931,7 +942,9 @@ "name": "designcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/designcraft/icon.png", "source": "./external_plugins/designcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "DesignCraft", "displayName_i18n": { "en": "DesignCraft", @@ -958,7 +971,9 @@ "name": "wordcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/wordcraft/icon.png", "source": "./external_plugins/wordcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "WordCraft", "displayName_i18n": { "en": "WordCraft", @@ -985,7 +1000,9 @@ "name": "gridcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/gridcraft/icon.png", "source": "./external_plugins/gridcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "GridCraft", "displayName_i18n": { "en": "GridCraft", @@ -1012,7 +1029,9 @@ "name": "deckcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/deckcraft/icon.png", "source": "./external_plugins/deckcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "DeckCraft", "displayName_i18n": { "en": "DeckCraft", @@ -1039,7 +1058,9 @@ "name": "cadcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/cadcraft/icon.png", "source": "./external_plugins/cadcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "CADCraft", "displayName_i18n": { "en": "CADCraft", @@ -1066,7 +1087,9 @@ "name": "soundcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/soundcraft/icon.png", "source": "./external_plugins/soundcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "SoundCraft", "displayName_i18n": { "en": "SoundCraft", @@ -1149,7 +1172,9 @@ }, "category": "developer-tools", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/kicad/icon.png", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "KiCad", "displayName_i18n": { "en": "KiCad", @@ -1531,6 +1556,30 @@ "repository": "https://github.com/geer1895/rfauto", "license": "GPL-3.0-only", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/rfauto/icon.png" + }, + { + "name": "free-guide", + "source": "./external_plugins/free-guide", + "description": "Complete community guide to running ZCode on a free stack: quota-safe fallback chain from the Z.ai plan through free cloud providers to an unlimited local GPU model, plus three companion skills (key setup, automatic model fallback, token/quota tracking). Read docs-guide.md first.", + "description_i18n": { + "en": "Complete community guide to running ZCode on a free stack: quota-safe fallback chain from the Z.ai plan through free cloud providers to an unlimited local GPU model, plus three companion skills (key setup, automatic model fallback, token/quota tracking). Read docs-guide.md first.", + "zh-CN": "完整的 ZCode 免费方案社区指南:从 Z.ai 套餐到免费云供应商再到本地 GPU 无限量模型的额度安全回退链,并附带三个配套技能(密钥接入、模型自动回退、用量/额度统计)。请先阅读 docs-guide.md。" + }, + "version": "1.0.0", + "author": { + "name": "Tejas Lowanshi", + "url": "https://github.com/Tejs2005" + }, + "category": "guides", + "keywords": [ + "free-tier", + "fallback-chain", + "openrouter", + "gemini", + "local-model", + "quota", + "guide" + ] } ] } \ No newline at end of file