点睛 · pi-vision-native

画龙点睛——让纯文本模型看见。 Give text-only pi models (DeepSeek, Llama, ...) real vision.

pi-vision-native（点睛）是一个 Pi Coding Agent 视觉扩展：当主模型是纯文本（如 DeepSeek V4 Flash）时，它会自动把聊天中粘贴/附加的图片交给视觉模型分析，并把文字描述注入对话，让主模型"看得见"图片——同时支持任意 OpenAI 兼容的视觉端点，不绑定任何一家服务商。

✨ 特性

特性	说明
🖼️ 附件自动读图	聊天里粘贴图片或 @文件 附加图片，自动交给视觉模型分析并注入描述，纯文本主模型无需换模型即可看图
🧠 能力感知	检测当前主模型是否多模态：支持图片的主模型（Qwen3-VL、GPT-4o…）原图直通、零委托；仅纯文本主模型才走视觉桥接
🎯 意图检测	你明确问图（"描述这张图片"）→ 视觉模型直接回答；图片只是素材（"根据截图实现这个 UI"）→ 视觉模型只提取事实、绝不越权实现，真正干活的是主模型
🔌 服务商无关	任何 OpenAI 兼容视觉端点：ModelScope、硅基流动、OpenRouter、智谱 GLM、本地 Ollama… 一个命令切换
🔁 韧性	内容寻址缓存（同图重复分析零 API 调用）+ 429/5xx/网络错误指数退避重试 + fallback 备用模型
🛠️ 双工具	vision-describe / vision-ask 两个工具，可让视觉模型单独完成任意任务（识别、OCR、提取数据…）
📝 审计日志	可选每调用一行日志，便于排查

📦 安装

pi install npm:pi-vision-native
# 或试用不安装
pi -e npm:pi-vision-native

安装后 /reload，然后配置：

/vision key        # 设置视觉 API 密钥（任意服务商）
/vision model      # 设置视觉模型 ID
/vision config     # 查看当前配置

🚀 快速上手

场景 1：纯文本主模型看附件图片

你：[粘贴一张截图] 描述一下这张图片
→ 插件自动调用视觉模型，把图片描述注入消息
→ DeepSeek 基于描述回答

场景 2：根据图片实现功能（视觉只负责"看"）

你：[附加 UI 设计图] 根据图片实现这个日历界面
→ 视觉模型只提取事实（布局/文字/颜色…），不输出实现方案
→ DeepSeek 基于描述真正实现代码

场景 3：让视觉模型单独干活

你：用 vision-ask 提取这张图片里的表格数据，生成 JSON
→ agent 调用 vision-ask 工具，视觉模型直接输出结果

⚙️ 配置命令

/vision                       # 显示全部配置状态
/vision model <id>            # 设置视觉模型（如 Qwen/Qwen3-VL-32B-Instruct）
/vision base-url <url>        # 切换服务商端点
/vision key                   # 设置 API 密钥
/vision fallback <id>         # 设置备用模型（主模型失败时自动切换）
/vision fallback-key <key>    # 备用模型密钥（可选，默认用主密钥）
/vision fallback-url <url>    # 备用模型端点（可选）
/vision fallback-clear        # 清除备用模型
/vision cache [clear]         # 查看/清空缓存
/vision persist [on|off]      # 跨会话磁盘缓存开关
/vision audit [on|off]        # 审计日志开关

兼容别名：/modelscope-vision 仍然可用。

服务商示例

服务商	base-url	模型示例
ModelScope	https://api-inference.modelscope.cn/v1	Qwen/Qwen3-VL-235B-A22B-Instruct
硅基流动	https://api.siliconflow.cn/v1	Qwen/Qwen2.5-VL-72B-Instruct
智谱 GLM	https://open.bigmodel.cn/api/paas/v4	glm-4v-flash（免费）
OpenRouter	https://openrouter.ai/api/v1	qwen/qwen-2.5-vl-72b-instruct
本地 Ollama	http://localhost:11434/v1	qwen2.5vl:7b

🔬 工作原理

用户粘贴/附加图片
        │
        ▼
┌─ input 事件拦截（agent 处理之前）─────────────┐
│  有图？否 → continue（零开销）                │
│  主模型多模态？是 → 原图透传（零委托）         │
│  纯文本主模型？                                 │
│    ├─ 意图检测：问图 / 当素材？                 │
│    ├─ 缓存命中 → 直接注入（0 API 调用）         │
│    ├─ 视觉模型调用（指数退避重试）              │
│    └─ 失败 → fallback 备用模型                 │
│  注入文字描述 + 清空原图 → 交给主模型           │
└──────────────────────────────────────────┘

• 为什么清空原图：纯文本主模型收到图片只会被 pi 替换成 (image omitted: ...) 占位符，毫无意义；注入文字描述才能被真正"看见"
• 为什么不越权：素材模式下视觉模型的 prompt 明确禁止输出实现建议/代码，保证 DeepSeek 这类主模型始终是执行者

📦 发布与开发

git clone https://github.com/fengxbin/pi-vision-native   # 或先 fork
npm install                                          # 安装 devDependencies
npm pack                                             # 本地验证打包内容
npm publish                                          # 发布到 npm（需先 npm login）

发布后 pi.dev 市场自动收录（包带 pi-package keyword）。

📄 License

MIT

派生自 @lokiyou/modelscope-vision（MIT），在原「工具调用 + 独立配置」基础上新增：附件自动读图、能力感知、意图检测、缓存/重试/fallback、多服务商支持、命令改名 /vision。