Skip to content

feat(free-guide): add complete free-stack guide plugin with three companion skills - #197

Open
Tejs2005 wants to merge 1 commit into
zai-org:mainfrom
Tejs2005:free-guide-plugin
Open

Tejs2005 wants to merge 1 commit into
zai-org:mainfrom
Tejs2005:free-guide-plugin

Conversation

@Tejs2005

Copy link
Copy Markdown

Plugin type (required) / 插件类型(必填)

  • UI Plugin / 是 UI 插件
  • Standard plugin / 普通插件(非 UI) — skills + docs only, no MCP Apps interactive pages
  • Not applicable / 不适用

Affected plugin name(s) / 涉及的插件名称:free-guide (Standard)

What / 改动内容

New community plugin in the currently-empty guides category: a complete, battle-tested guide to running ZCode on a free stack with a quota-safe fallback chain, so a session never hard-stops when a cloud quota dies:

ZCode (default: Z.ai plan)
   │  quota dies →
   ▼
CCR Router (local, 127.0.0.1:3456)
   ├─ GPT models        (ChatGPT/Codex account login — no key)
   ├─ 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 GPU — unlimited last resort)

Structure (external_plugins/free-guide/, 80 KB):

  • .zcode-plugin/plugin.json — manifest, category guides
  • docs-guide.md — the complete setup guide (install CCR, provider setup per provider, fallback chain config, ZCode wiring, OmniRoute bonus, security checklist, troubleshooting lessons)
  • skills/free-api-key-setup/ — wire any new API key into ZCode correctly (key-prefix table, api.type gotchas; never echoes the key)
  • skills/auto-model-fallback/ — on model errors (429/401/404/5xx), classify and walk the fallback chain
  • skills/token-counter/ + scripts/token-usage.py — live per-provider quota status (exits 1 at warn threshold → time to fall back)
  • README.md + README_CN.md — equivalent bilingual docs

No secrets included. The package was scrubbed: no API keys, no key fragments, no machine-specific paths. Free-tier lineups and caveats are dated (October 2026) and flagged in the docs for re-checking.

Self-check / 自查清单

  • Plugin name is unique kebab-case; new external plugin directory is external_plugins/<name>/; existing fixes retain ownership
  • Usage category is set independently of publisher ownership (guides)
  • Plugin type and affected names are declared above (free-guide, Standard)
  • version bumped in BOTH plugin.json and marketplace.json (both 1.0.0, new plugin)
  • README.md (EN) and README_CN.md (中文) both updated and equivalent
  • description_i18n has both en and zh-CN (in manifest and marketplace entry)
  • No secrets, machine-specific paths, or private dependencies
  • Model/API/network dependencies documented (guide describes every provider, key source, and base URL; all are user-created free accounts)
  • python3 scripts/validate.py passes (OK: 56 plugin(s) validated)
  • ⚠️ python3 scripts/build_dist.py fails on pre-existing excalidraw et al. in a plain source checkout (UI plugins need compiled dist/ which only the release pipeline builds — per the README). The free-guide plugin itself contains no build artifacts and validates cleanly.

Complete guide to running ZCode on a free stack: Z.ai plan ->
CCR router fallback chain (ChatGPT/Codex login, Gemini free key,
OpenRouter free models) -> local qwen2.5-coder as unlimited last resort.
Ships three companion skills: free-api-key-setup, auto-model-fallback,
token-counter. No secrets included (verified).
@panda920

Copy link
Copy Markdown
Collaborator

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants