pi-zai-vision

Pi extension: Z.AI GLM-4.6V vision tools — native pi integration of the official Z.AI vision MCP server capabilities.

Tools

General Vision

| Tool | Description | |------|-------------| | image_analysis | General-purpose image analysis — describe, identify, extract, answer |

Specialized Image Tools

| Tool | Description | |------|-------------| | extract_text_from_screenshot | OCR text extraction with formatting preservation | | diagnose_error_screenshot | Error diagnosis with root cause analysis and fix guidance | | understand_technical_diagram | Architecture/UML/flowchart/ER diagram interpretation | | analyze_data_visualization | Chart/graph/dashboard analysis — trends, anomalies, recommendations | | ui_diff_check | Compare two UI screenshots — visual regression testing | | ui_to_artifact | UI screenshot → code (HTML/CSS), spec, prompt, or description |

Video

| Tool | Description | |------|-------------| | video_analysis | Video content analysis — scenes, actions, events (MP4/MOV/M4V/AVI/WebM/WMV)

Prerequisites

• A Zhipu / Z.AI API key with GLM-4.6V access
• Pi installed (npm install -g @ghoulm370/pi-web)

Quick Start

1. Install

# From local path (development)
pi install /path/to/pi-zai-vision

# From npm (once published)
pi install npm:@ghoulm370/pi-zai-vision

2. Configure

方式一：配置文件（推荐，~/.pi/agent/pi-zai-vision.json）

{
  "apiKey": "your-api-key",
  "mode": "ZAI"
}

方式二：环境变量（优先级更高）

export Z_AI_API_KEY="your-api-key"
export Z_AI_MODE="ZAI"       # ZHIPU | ZHIPU_CODING | ZAI | ZAI_CODING

优先级：环境变量 > 配置文件 > 默认值

| 配置项 | 环境变量 | 配置文件 key | 默认值 | |--------|----------|-------------|--------| | API Key | Z_AI_API_KEY | apiKey | (required) | | 平台 | Z_AI_MODE | mode | ZAI | | 模型 | Z_AI_MODEL | model | glm-4.6v | | Thinking | Z_AI_THINKING | thinking | true | | 超时(秒) | Z_AI_TIMEOUT | timeoutSecs | 300 | | 图片上限(MB) | Z_AI_MAX_IMAGE_SIZE_MB | maxImageSizeMB | 5 | | 视频上限(MB) | Z_AI_MAX_VIDEO_SIZE_MB | maxVideoSizeMB | 8 |

3. Use

pi

Then in your pi session:

> Describe this screenshot: image_analysis(imagePath="error.png", prompt="What's wrong?")

> Extract the code from this screenshot: extract_text_from_screenshot(imagePath="code.png", programmingLanguage="typescript")

> Diagnose this error: diagnose_error_screenshot(imagePath="stacktrace.png", context="Running cargo build")

Platform Endpoints

Coding Plan（编码套餐）用户：智谱用 ZHIPU_CODING，Z.AI 用 ZAI_CODING。 Coding Plan 支持的 OpenAI Chat Completion 端点见 官方文档。

| Mode | Endpoint | 适用 | |------|----------|------| | ZHIPU | https://open.bigmodel.cn/api/paas/v4/ | 智谱（标准 / 按量计费） | | ZHIPU_CODING | https://open.bigmodel.cn/api/coding/paas/v4/ | 智谱 Coding Plan | | ZAI | https://api.z.ai/api/paas/v4/ | Z.AI（标准 / 按量计费） | | ZAI_CODING | https://api.z.ai/api/coding/paas/v4/ | Z.AI Coding Plan |

Architecture

This package ports the official @z_ai/mcp-server vision tools into pi-native custom tools using pi.registerTool(). System prompts are sourced directly from the official MCP server (verified via glm-vision-rs).

Unlike an MCP server (which requires a separate npx process and MCP protocol), pi-native tools:

• Appear in pi's system prompt and tool list automatically
• Support pi's native cancellation signals
• Work in all pi modes: TUI, RPC, print
• Show streaming progress via onUpdate

Development

# Test with pi
pi -e ./extensions/index.ts

# From a local path
pi install ./pi-zai-vision

License

MIT