---
name: lingtai-ai/zhipu-coding-plan
source: https://app.decimal.ai/s/lingtai-ai-zhipu-coding-plan@1/SKILL.md
source_sha256: 0a1c5adb013f
---

# zhipu-coding-plan

> Thin pointer. Live docs are the source of truth — `curl` them when you need depth.

## Live Docs (canonical)

When you need details — current models, exact tool parameters, per-tier quotas, MCP package or endpoint changes — fetch these. Both regions publish equivalent content; pick the one matching the user's account. URLs verified live 2026-04-29.

| Topic | International (Z.AI) | Mainland (BigModel / 智谱) |
|---|---|---|
| Coding-plan overview | [`docs.z.ai/devpack/overview`](https://docs.z.ai/devpack/overview) | [`docs.bigmodel.cn/cn/coding-plan/overview`](https://docs.bigmodel.cn/cn/coding-plan/overview) |
| Vision MCP server | [`docs.z.ai/devpack/mcp/vision-mcp-server`](https://docs.z.ai/devpack/mcp/vision-mcp-server) | [`docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server`](https://docs.bigmodel.cn/cn/coding-plan/mcp/vision-mcp-server) |
| Web search MCP | [`docs.z.ai/devpack/mcp/search-mcp-server`](https://docs.z.ai/devpack/mcp/search-mcp-server) | [`docs.bigmodel.cn/cn/coding-plan/mcp/search-mcp-server`](https://docs.bigmodel.cn/cn/coding-plan/mcp/search-mcp-server) |
| Web reader MCP | [`docs.z.ai/devpack/mcp/reader-mcp-server`](https://docs.z.ai/devpack/mcp/reader-mcp-server) | [`docs.bigmodel.cn/cn/coding-plan/mcp/reader-mcp-server`](https://docs.bigmodel.cn/cn/coding-plan/mcp/reader-mcp-server) |
| Zread (GitHub repos) MCP | [`docs.z.ai/devpack/mcp/zread-mcp-server`](https://docs.z.ai/devpack/mcp/zread-mcp-server) | [`docs.bigmodel.cn/cn/coding-plan/mcp/zread-mcp-server`](https://docs.bigmodel.cn/cn/coding-plan/mcp/zread-mcp-server) |
| Doc index (use if any URL above stales) | [`docs.z.ai/llms.txt`](https://docs.z.ai/llms.txt) | [`docs.bigmodel.cn/llms.txt`](https://docs.bigmodel.cn/llms.txt) |

Note the URL pattern asymmetry: international is `/devpack/mcp/...`, mainland is `/cn/coding-plan/mcp/...`. If a path 404s, fetch the `llms.txt` index above to find the new path — they shift.

Always `curl` (or use `web_search(action="manual")`) when you need fresh info — the skill snapshot will go stale.

## What You Get With One Key

A single Z.AI / BigModel coding-plan key unlocks four MCP servers. Per-tier quotas (snapshot — verify against the live page):

| Capability | Lite | Pro | Max |
|---|---|---|---|
| **Vision MCP** (8 tools — see below) | shared | shared | shared |
| **Web search** (`webSearchPrime`) | 100 / total | 1,000 / total | 4,000 / total |
| **Web reader** (`webReader`) | 100 / total | 1,000 / total | 4,000 / total |
| **Zread** (3 tools) | 100 / total | 1,000 / total | 4,000 / total |

Quotas are *cumulative-total*, not daily — once exhausted, you're done until the plan period rolls over.

## The Four MCP Servers

| Modality | Server | Tools |
|---|---|---|
| **vision** | stdio: `npx -y @z_ai/mcp-server` | `image_analysis`, `extract_text_from_screenshot`, `ui_to_artifact`, `diagnose_error_screenshot`, `understand_technical_diagram`, `analyze_data_visualization`, `ui_diff_check`, `video_analysis` |
| **web search** | http: `https://api.z.ai/api/mcp/web_search_prime/mcp` | `webSearchPrime` |
| **web reader** | http: `https://api.z.ai/api/mcp/web_reader/mcp` | `webReader` |
| **zread** | http: `https://api.z.ai/api/mcp/zread/mcp` | `search_doc`, `get_repo_structure`, `read_file` |

**Mainland (BigModel) HTTP MCP host** is `https://open.bigmodel.cn/api/mcp/...` — substitute that origin for `https://api.z.ai` in the URLs above. (`api.bigmodel.cn` 301-redirects to `open.bigmodel.cn`.) Verified live 2026-04-29.

**MCP server registration is owned by the `mcp-manual` skill** (kernel `mcp` capability) — read it for how to register, activate, and troubleshoot MCP servers (registry route or legacy `mcp/servers.json`). This skill assumes the tools are already in your tool list. If the tool you need is *not* in your list, that's the signal to register the server first.

## Sourcing The API Key

**Never hardcode the key into `mcp/servers.json` or any committed file.** The `env` block (for stdio) and `headers` block (for http) are plain text — leak risk on commit, on backup, on screen-share.

Resolution order:

1. **`~/.lingtai-tui/.env`** — `ZHIPU_API_KEY=…`. The TUI populates this on firstrun.
2. **Process environment** — if already exported, MCP subprocesses inherit it.
3. **Ask the user** — if neither path resolves.

```bash
grep -E '^ZHIPU_API_KEY=' ~/.lingtai-tui/.env | cut -d= -f2- | tr -d ' '
```

The vision MCP also wants a `Z_AI_MODE` env var (`ZAI` for international, `ZHIPU` for mainland) — derive it from the region detection below.

## Picking The Region

Two ecosystems, **not interchangeable** — a key from one region returns auth errors against the other host.

| Region | Console | API host (HTTP MCP) | `Z_AI_MODE` |
|---|---|---|---|
| International (Z.AI) | `z.ai/manage-apikey/apikey-list` | `api.z.ai` | `ZAI` |
| Mainland (BigModel / 智谱) | `open.bigmodel.cn` | `open.bigmodel.cn` | `ZHIPU` |

The MCP server registration must match the region of the key being used.

**Auto-detect from the preset library.** Walk presets in `~/.lingtai-tui/presets/`
(`json`/`jsonc`); for each `manifest.llm.provider == "zhipu"`, read
`manifest.llm.base_url` and map it: `z.ai`/`api.z.ai` → International/`ZAI`,
`bigmodel.cn` → Mainland/`ZHIPU`.

If presets exist for **both** regions, the user has accounts in both — pick the one matching the key in `~/.lingtai-tui/.env`, or ask the user. If no Zhipu preset exists or the result is ambiguous, **ask the user**. Do not guess.

## When To Use This Skill

| Want to … | Use |
|---|---|
| Analyze image/screenshot/UI/diagram, no vision-capable LLM | This skill — vision MCP (8 specialized tools) |
| Search the web with rich snippets | This skill — `webSearchPrime` (or built-in `web_search` capability if Zhipu is your LLM provider — that path uses the same MCP) |
| Fetch and read a URL | This skill — `webReader` (or built-in `web_search` / `web-search-manual` for non-Zhipu free tier) |
| Browse a GitHub repo (search docs, list files, read code) | This skill — zread |
| Process a video file (≤8 MB) | This skill — `video_analysis` |
| Pure compute / code generation | Just use your LLM directly |

## Vision MCP — Tool Picker

The vision server exposes 8 tools, more specialized than MiniMax's single `understand_image`. Pick the right one:

| Want to … | Tool |
|---|---|
| General "what's in this image?" | `image_analysis` |
| OCR (extract text from screenshot) | `extract_text_from_screenshot` |
| Convert UI mockup → code/spec | `ui_to_artifact` |
| Debug an error screenshot | `diagnose_error_screenshot` |
| Read an architecture / system diagram | `understand_technical_diagram` |
| Read a chart / dashboard | `analyze_data_visualization` |
| Diff two UI screenshots | `ui_diff_check` |
| Analyze a video file (≤8 MB MP4/MOV/M4V) | `video_analysis` |

Using the right specialized tool gives noticeably better output than `image_analysis` for charts, diagrams, or OCR.

## Failure Modes

| Symptom | Likely cause | Fix |
|---|---|---|
| Tool not in your list | MCP server not registered | Use `mcp-manual` skill |
| `401 Unauthorized` / `Invalid API key` | Region mismatch, or stale key | Verify host matches account region; refresh `~/.lingtai-tui/.env` |
| `429 Rate limited` or quota error | Plan total exhausted | Live docs — check current quota; the cumulative-total clock resets per plan period |
| Vision MCP times out on video | File >8 MB or wrong format | Compress with ffmpeg or use a different format (MP4/MOV/M4V only) |
| `Z_AI_MODE not set` warnings | Missing env var on stdio MCP | Set `ZAI` (international) or `ZHIPU` (mainland) in the server's `env` block |

## Self-Healing

If the live docs contradict this skill, trust the docs and (if the human consents) update this file. The four MCP server URLs and the package name (`@z_ai/mcp-server`) are the highest-churn items — verify them against `docs.z.ai/llms.txt` first.

---
> **Found a bug or issue?** If you encounter any problems with this skill, load the `lingtai-issue-report` skill and follow its instructions to report it.