zcode

command
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 31 Imported by: 0

README

ZCode (智谱 z.ai) native CPA plugin

This directory is a single package main that builds as a CLIProxyAPI native plugin. It implements the ZCode free-quota channel without the obsolete browser / Aliyun-captcha inference machinery.

Protocol facts

  • Inference endpoint: POST https://zcode.z.ai/api/v1/zcode-plan/anthropic/v1/messages. This is Anthropic Messages with streaming SSE. There is no OpenAI-shaped /v1/chat/completions path under zcode-plan (it returns 404).
  • Executor format: input and output are both anthropic. CPA maps that literal to its Claude format and performs any OpenAI↔Anthropic conversion itself. The plugin only injects the identity structure and relays complete Anthropic SSE frames.
  • Identity gate: system is an array of separate text blocks in the order official CLI prefix → official stable sections → # Environment → caller system, and the first user turn begins with the official <system-reminder> date block. Flattening the first ~2900 characters into one block still triggers upstream code 3012; the structure is required. The constants in identity_constants.go were programmatically extracted from the TypeScript reference. Do not reformat them.
  • 3012 warning: a mismatch carries an account penalty — 30 minutes, 24 hours from the third occurrence within 24 hours, disablement on the fifth. The plugin never automatically retries a 3012, and no test contacts the live endpoint.
  • Captcha: empirical verification shows inference succeeds without any captcha header; a deliberately bogus captcha parameter also succeeds. The official client now uses the captcha header only on billing/claim, reactively. This plugin never opens a browser and never mints captchas. A claim is attempted without the header and reports an explicit 3007 error if the server demands one.
  • Models: only GLM-5.3 and GLM-5.3-Flash are exposed. The other two ids in the upstream pool return empty responses under Start Plan (measured 0/3 versus 3/3 for GLM-5.3). Context/output/vision/reasoning data is read from client/configs, with the measured table as a fallback.
  • Thinking level wire field: output_config.effort, not reasoning_effort. Upstream's own client/configs publishes that path.
  • Credential: zcode_jwt is a long-lived JWT with no exp claim. user_id is the stable account identity; device_mid is locally generated per login and must not be used for de-duplication. It is nevertheless a hard request requirement: omitting X-Device-Mid yields HTTP 400 / code 3001.
  • Login: server-mediated device authorization — /oauth/cli/init, user opens the authorize URL, /oauth/cli/poll/<flow_id>. No local callback listener.
  • Quota/check-in: billing/balance; then for the daily allowance, report app_launch and app_daily_active before billing/preview, then claim each returned plan. Balance units are rendered as tokens, using the upstream unit_type / meter fields.

Optional official-client credential import

The management login page can optionally adopt the official client's ~/.zcode/v2/credentials.json when import_client_credential: true. The primary path remains the plugin's own login.

An encrypted value has the exact shape:

enc:v1:<base64url(iv)>.<base64url(authTag)>.<base64url(ciphertext)>

with AES-256-GCM, a 12-byte IV, and a 16-byte authentication tag. The key is:

sha256("zcode-credential-fallback:" + platform + ":" + homedir + ":" + username)

or sha256($ZCODE_CREDENTIAL_SECRET) when that variable is set. Any deviation in prefix, platform spelling, home directory, username (whose failure fallback is the literal unknown), separator or order produces a GCM authentication failure. Values without the enc:v1: prefix are plaintext and are returned unchanged.

Network rule

The plugin never opens a network connection. Every HTTP request goes through (*abiboot.Host).HTTPDo, inheriting CPA's proxy, TLS and request logging. net/http is used only for method/header/status types.

Offline tests

testdata/captured_stream.json is a scrubbed fixture matching the verified live capture shape (identity block, GLM-5.3-Flash, max_tokens: 64, Anthropic SSE with message start, ping, thinking/signature deltas, text delta, block stops, usage and message stop). It contains placeholders, not a live token. All tests are deterministic and use an in-process fake host transport.

Documentation

Overview

Command zcode builds the CPA c-shared plugin library for the ZCode (智谱 z.ai) provider.

This file is the cgo ABI glue and is deliberately a byte-for-byte sibling of the other provider plugins: `//export` is only honoured in package main, so the four C symbols have to live here, and keeping the plugin implementation in the same package is what lets `go build -buildmode=c-shared ./plugins/zcode` emit the shared object directly from this directory.

Command zcode builds the CPA c-shared plugin library for the ZCode (智谱 z.ai) provider.

Both files in this directory are package main: main.go carries the exported cgo ABI and plugin.go carries the abiboot.Plugin implementation. Keeping the plugin implementation in the same package is what lets `go build -buildmode=c-shared ./plugins/zcode` emit the shared object directly from this directory.

What this provider is, in one paragraph: ZCode's free-quota channel speaks **Anthropic Messages** and nothing else — the OpenAI-shaped `/v1/chat/completions` under `zcode-plan` does not exist — and it admits a request only when the body carries the official client's identity block as a structured `system` array. Credentials are static (the JWT has no `exp`), a device id is required but not validated, and the daily allowance is claimed through `event/report` → `billing/preview` → `billing/claim`. The plugin never mints a captcha: that machinery was measured to be unnecessary for inference and the header now appears only on the claim endpoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL