<div align="center">

# Pi Vision Bridge — 让纯文本模型看懂图片

**让纯文本模型（DeepSeek、Llama、Qwen、本地 Ollama 模型）也能看图——无需在任务中途切换模型。**

[![License](https://img.shields.io/badge/License-MIT-green?logo=opensourceinitiative&logoColor=white)](./LICENSE)
[![Pi](https://img.shields.io/badge/Pi-0.83+-6B5B95?logo=pi&logoColor=white)](https://pi.dev)
[![Zero Deps](https://img.shields.io/badge/Zero-Dependencies-2E8B57?logo=npm&logoColor=white)](./package.json)
[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen?logo=github)](https://github.com/wuxiangru915/pi-vision-bridge/pulls)

[English](README.md) | [中文](README_CN.md)

</div>

---

你的编码 Agent 运行在纯文本模型上，全程负责执行任务。当它需要理解一张图片——页面截图、报错信息、UI 设计稿——它委托给视觉模型，拿回文字描述，然后继续干活。主模型从不切换。

## 功能特性

- **`describe_image` 工具** — Agent 在任务执行中的任何时刻都可调用：传入图片路径和可选问题，返回文字描述。支持 pi 能调用的任何视觉模型。
- **粘贴图片自动转文字** — 在纯文本模型下粘贴/上传图片，会在到达模型前被描述，对话照常进行，不报错。
- **自动发现 + 失败回退** — 自动从 pi 模型注册表里找到可用的视觉模型；某个候选失败时，自动尝试下一个。
- **双 API 格式支持** — 开箱支持 OpenAI 兼容端点（`/chat/completions`）和 Google Generative AI（`generateContent`）。
- **代理感知** — 支持标准 `HTTPS_PROXY` / `HTTP_PROXY` / `PI_VISION_PROXY` 环境变量，通过零依赖 CONNECT 隧道。
- **零运行时依赖** — 无 npm 包，无二进制下载。

## 工作原理

```
你的 Agent（纯文本模型，如 DeepSeek）
    │  正在执行一个长任务
    │  ── 需要看图 ──▶ 调用 describe_image(路径, 问题)
    │                       │
    │                       ▼
    │              视觉模型（Gemini / 通义千问VL / GLM / ...）
    │                       │
    │  ◀── 拿到文字描述 ────┘
    │  继续执行任务，模型从未切换
```

## 安装

```bash
pi install npm:@wuxiangru/pi-vision-bridge
```

或通过 git 安装：

```bash
pi install git:github.com/wuxiangru915/pi-vision-bridge
```

或先快速试用（不写入配置）：

```bash
pi -e git:github.com/wuxiangru915/pi-vision-bridge
```

> **注意：** pi 扩展拥有完整的系统访问权限。安装前请先审查源码。

## 配置

视觉模型从 pi 的模型注册表（`~/.pi/agent/models.json`）解析，因此 pi 能认证的任何提供商都可以直接使用。

### 方式 A：自动发现（默认）

未显式配置时，扩展会自动选择支持图片、已配置认证、且在常见对话格式中评分最高的模型——优先当前 provider，其余按候选排序，失败自动回退。

### 方式 B：显式配置（推荐）

用环境变量指定提供商/模型：

```bash
export PI_VISION_PROVIDER=google
export PI_VISION_MODEL=gemini-3-flash-preview
```

两者必须都设置，优先级高于自动发现。提供商和模型需在 `~/.pi/agent/models.json` 中定义，且 `"input": ["text", "image"]`：

```json
{
  "providers": {
    "google": {
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
      "api": "google-generative-ai",
      "apiKey": "$GEMINI_API_KEY",
      "models": [
        { "id": "gemini-3-flash-preview", "input": ["text", "image"], "contextWindow": 1000000 }
      ]
    }
  }
}
```

### 支持的视觉模型

任何 pi 能认证和调用的模型：

| 提供商 | 示例模型 | API 格式 |
|--------|---------|---------|
| Google Gemini | `gemini-3-flash-preview`、`gemini-2.5-pro` | `google-generative-ai` |
| 阿里云百炼（通义千问） | `qwen-vl-max`、`qwen2.5-vl` | OpenAI 兼容 |
| 智谱 GLM | `glm-4v`、`glm-4v-plus` | OpenAI 兼容 |
| OpenAI | `gpt-4o-mini`、`gpt-4o` | OpenAI 兼容 |
| 本地 | Ollama 视觉模型（`llama3.2-vision`） | OpenAI 兼容 |

### 代理（可选）

如果视觉模型 API 需要代理，设置标准环境变量（扩展也支持 `PI_VISION_PROXY`）：

```bash
export HTTPS_PROXY=http://your-proxy:port
```

## 使用方法

- **Agent 驱动** — 任务涉及图片时，Agent 会自行调用 `describe_image`。你也可以主动指示：*"截个图，检查设计是否符合要求。"*
- **用户驱动** — 直接在对话中粘贴/上传图片。如果你的模型是纯文本模型，图片会自动转成描述。

## 环境要求

- pi v0.83+（使用 `ctx.modelRegistry.getApiKeyAndHeaders`）
- 在 `~/.pi/agent/models.json` 中配置了视觉模型（或设置 `PI_VISION_PROVIDER` / `PI_VISION_MODEL`）
- 能访问视觉模型 API 的网络

## 许可证

MIT