让单模态模型
看懂图片与视频

功能

4 个 MCP 工具

遵循 Model Context Protocol 标准，按输入形态划分，把 prompt 控制权交给基座模型。

核心特性

• 多轮迭代识别 — 基座模型可多次调用，边干边查，逐步精修对图片/视频的理解（详见下方）
• 本地 stdio 部署 — 走本地进程间通信，不依赖外部服务器，npx 一行启动
• 多 provider 架构 — VisionProvider 接口，支持 OpenAI Responses / Chat Completions / Anthropic 三协议
• 任意 provider 自配 — 接任何 OpenAI Responses / Chat Completions / Anthropic 兼容网关，不绑定单一模型厂商
• 零硬编码配置 — 全部配置走环境变量，代码内零硬编码
• 自动识别输入形态 — URL / 本地路径 / base64 三种形态兼容，适配不同 Agent 的传图方式

核心特色

多轮迭代识别

这是 picsense 最核心的差异化点——市面上几乎所有图片识别 MCP 都是一次性的，但一次性的视觉描述往往不够详细或不够准确。

使用方法

接入 AI 客户端

需要 Node.js ≥ 20。无需克隆仓库，npx 一行启动，配置一次永久生效。

一键接入（推荐）

把下面这段话原样复制发给你的 AI 助手（ZCode / Claude Code 等），它会先停下来向你要视觉模型信息，然后自动完成安装、MCP 配置与配套技能安装：

请帮我接入 picsense——本地图片/视频/文档识别 MCP 服务，并安装它的配套使用技能。

第一步：确认视觉模型信息。picsense 本身免费开源、本地运行，但识别图片/视频需要调用一个多模态视觉模型。检查我在对话中是否已给出「协议 + API Key + 模型名」；如果没有，停下来向我询问，并告诉我协议三选一：
1. OpenAI 官方 API，或任意 OpenAI 兼容网关（可配自定义 base URL）
2. Chat Completions 协议网关（腾讯 Coding Copilot、DeepSeek 等）
3. Anthropic 协议（官方 API，或 DeepSeek 等兼容端点）
注意：所选模型必须具备视觉（图片理解）能力。拿到信息之前不要进行后续步骤。

第二步：安装并配置 MCP 服务器（本地 stdio 传输）。
npm i -g @honlnk/picsense
按你所在环境的标准方式写入配置：
- ZCode：~/.zcode/cli/config.json 的 mcp.servers，形如 {"type":"stdio","command":"picsense","args":[],"env":{"DEFAULT_PROVIDER":"openai","OPENAI_API_KEY":"你的Key","OPENAI_MODEL":"模型名"},"timeoutMs":900000}（视频识别较慢，超时给足）
- Claude Code：claude mcp add picsense --env DEFAULT_PROVIDER=openai --env OPENAI_API_KEY=你的Key --env OPENAI_MODEL=模型名 -- picsense
- Claude Desktop / Cursor / 其他 MCP 客户端：mcpServers 配置节，command 用 npx、args 用 ["-y","@honlnk/picsense"]（Windows 需用 cmd /c 包裹 npx），env 同上
所选协议对应的环境变量见官网 https://picsense.honlnk.com/ 的「环境变量」一节；视频识别依赖 ffmpeg（安装时自动下载，pnpm 注意事项见官网「配置」一节）。

第三步：安装配套技能——只装 picsense-usage 这一个，不要把技能仓库里的其他技能装进技能目录。
git clone --depth 1 https://github.com/honlnk/honlnk-skills /tmp/honlnk-skills
把 /tmp/honlnk-skills/skills/picsense-usage 复制到你的技能目录（ZCode：~/.agents/skills/；Claude Code：~/.claude/skills/；其他 Agent：对应的技能发现目录），完成后删除 /tmp/honlnk-skills。
该技能承载「怎么用好这套工具」：读带图文章的完整链路、图片 URL 形态修正、全文标注与单图深读怎么选、session 多轮迭代、常见坑。

全部完成后重载配置或重启会话，确认工具列表出现 picsense 的 analyze_images / analyze_document 等工具即为接入成功，并向我报告结果。

1. 配置 AI 客户端

在你的 AI 客户端（ZCode / Claude Desktop / Cursor / 其他 MCP 客户端）的配置文件中加入。需提供自己的多模态模型 API Key（默认用 OpenAI Responses API，也可切换 Chat Completions / Anthropic 协议）：

{
  "mcpServers": {
    "picsense": {
      "command": "npx",
      "args": ["-y", "@honlnk/picsense"],
      "env": {
        "DEFAULT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-xxx",
        "OPENAI_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

{
  "mcpServers": {
    "picsense": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@honlnk/picsense"],
      "env": {
        "DEFAULT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-xxx",
        "OPENAI_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

切换协议（可选）

把 env 换成对应协议的三个变量即可，其余配置不变：

// Chat Completions —— 腾讯 Coding Copilot / DeepSeek 官方 / Qwen 等兼容网关
"DEFAULT_PROVIDER": "chat",
"CHAT_API_KEY": "ck-xxx",
"CHAT_MODEL": "hy4-preview",
"CHAT_BASE_URL": "https://copilot.tencent.com/v2"

// Anthropic —— Anthropic 官方 / DeepSeek 官方 /anthropic 端点
"DEFAULT_PROVIDER": "anthropic",
"ANTHROPIC_API_KEY": "sk-xxx",
"ANTHROPIC_MODEL": "deepseek-v4-flash-vision-exp",
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"

2. 验证

配置完成后，在 AI 客户端里粘贴一张图片提问，例如「描述这张 UI 截图的布局」。基座模型会自动调用 analyze_images 工具识别并返回描述。

使用示例

单图识别

analyze_images({
  image_sources: ["https://example.com/screenshot.png"],
  prompt: "描述这张 UI 截图的整体布局"
})

多轮迭代——细化局部

// 第 2 轮（复用上一轮返回的 session_id）
analyze_images({
  session_id: "<上一轮返回的 session_id>",
  prompt: "重点描述导航栏的样式，包括颜色、间距、字体"
})

视频识别

analyze_video({
  video_source: "https://example.com/demo.mp4",
  prompt: "描述这段视频的内容和关键画面"
})

配置

环境变量

全部配置走环境变量，代码内零硬编码。在 MCP 配置的 env 字段里传入。

* 默认 provider 的 Key/Model 必填；其他 provider 仅在切换使用时才需要。

视频识别的 ffmpeg 依赖

analyze_video 需要 ffmpeg。安装时自动下载内置的 ffmpeg-static 二进制；若下载失败（如 --ignore-scripts、企业内网代理），会自动 fallback 到系统 ffmpeg：

# macOS
brew install ffmpeg
# Debian / Ubuntu
apt install ffmpeg