seed-viz

视觉分析 CLI + MCP 服务器，支持字节跳动 Seed 2.0 视觉模型（火山方舟），或任意 OpenAI 兼容端点（LiteLLM 代理、OpenAI、Anthropic 代理等）。

快速开始

npm install -g @joezm/seed-viz

验证安装：

seed-viz --help

在项目目录创建最小的 .env：

SEED_VIZ_API_KEY=你的火山方舟-key

在火山引擎 Ark 控制台获取 API Key。

测试一下：

seed-viz general-image your-image.png

配置

CLI 启动时自动按顺序查找第一个 .env：当前目录 → ~/.seed-viz.env → $XDG_CONFIG_HOME/seed-viz/.env（XDG_CONFIG_HOME 未设时默认 ~/.config/seed-viz/.env）。Shell 中 export 的环境变量优先级高于 .env 文件。

环境变量

| 变量 | 默认值 | 用途 | |---|---|---| | SEED_VIZ_API_KEY | （必填） | 全局 API 密钥（所有未单独配置的档位都使用它） | | SEED_VIZ_BASE_URL | https://ark.cn-beijing.volces.com/api/v3 | 全局 OpenAI 兼容 base URL | | SEED_VIZ_MODEL_PRO | doubao-seed-2-0-pro-260215 | Pro 模型 ID 或别名 | | SEED_VIZ_MODEL_STD | doubao-seed-2-0-lite-260428 | Std 模型 ID 或别名 | | SEED_VIZ_MODEL_LITE | doubao-seed-2-0-mini-260428 | Lite 模型 ID 或别名 | | SEED_VIZ_API_KEY_PRO / _STD / _LITE | （未设则用全局） | 各档位专用 API 密钥 | | SEED_VIZ_BASE_URL_PRO / _STD / _LITE | （未设则用全局） | 各档位专用 base URL | | SEED_VIZ_TIMEOUT | 300000 | 请求超时（毫秒） | | SEED_VIZ_THINKING | 1 | 设为 0 关闭请求体中的 thinking 字段 |

三个档位对应 Seed 系列三个模型尺寸，能力 / 价格严格递减：pro（Seed Pro，高价值推理）> std（Seed Lite，常规任务）> lite（Seed Mini，最便宜）。

供应商配置示例

直连火山方舟（默认）：

SEED_VIZ_API_KEY=你的-key
SEED_VIZ_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
SEED_VIZ_MODEL_PRO=doubao-seed-2-0-pro-260215
SEED_VIZ_MODEL_STD=doubao-seed-2-0-lite-260428
SEED_VIZ_MODEL_LITE=doubao-seed-2-0-mini-260428

通过 LiteLLM 网关（任意 OpenAI 兼容代理）：

SEED_VIZ_API_KEY=sk-litellm-master-key
SEED_VIZ_BASE_URL=http://localhost:4000/v1
SEED_VIZ_MODEL_PRO=seed-pro        # LiteLLM config.yaml 中定义的别名
SEED_VIZ_MODEL_STD=seed-lite
SEED_VIZ_MODEL_LITE=seed-mini
SEED_VIZ_THINKING=0                # 上游不支持 thinking 字段时设 0

混用多供应商（按档位独立配置）：

当不同档位来自不同供应商时，为各档位单独配置凭证。未设置的档位回退到全局变量。

# PRO → OpenAI gpt-4o
SEED_VIZ_API_KEY_PRO=sk-openai-key
SEED_VIZ_BASE_URL_PRO=https://api.openai.com/v1
SEED_VIZ_MODEL_PRO=gpt-4o

# STD → Anthropic 代理（OpenAI 兼容）
SEED_VIZ_API_KEY_STD=sk-anthropic-key
SEED_VIZ_BASE_URL_STD=https://proxy.anthropic.example/v1
SEED_VIZ_MODEL_STD=claude-sonnet-4-6

# LITE 沿用全局 SEED_VIZ_API_KEY / SEED_VIZ_BASE_URL

MCP 服务器

同一个 seed-viz 可执行文件同时可作为 MCP 服务器运行。两种方式接入 MCP 客户端：

方式一 —— npx（无需预安装）：

{
  "mcpServers": {
    "seed-viz": {
      "command": "npx",
      "args": ["-y", "@joezm/seed-viz", "--mcp"]
    }
  }
}

方式二 —— 全局安装 + 绝对路径（冷启动更快，无需每次下载）：

npm install -g @joezm/seed-viz

查找二进制路径后配置：

which seed-viz
# → 例如 /usr/local/bin/seed-viz

{
  "mcpServers": {
    "seed-viz": {
      "command": "node",
      "args": ["/usr/local/bin/seed-viz", "--mcp"]
    }
  }
}

服务器暴露单个工具 analyze_image，通过 action 枚举覆盖全部 7 种分析类型，并提供 extra_prompt 参数用于任意自定义。

各客户端中的工具名： 各 agent 会按自己的命名空间重命名 MCP 工具，实际可调用名取决于接入方式：

• Claude Code（mcpServers.seed-viz）：mcp__seed-viz__analyze_image
• 直连注册：analyze_image 或 mcp__seed-viz__analyze_image
• 经 LiteLLM 聚合工具集（重命名为 visual-analyze_image）：mcp__common__visual-analyze_image

CLI 子命令

| 命令 | 输入 | 默认档位 | 默认 Effort | 用途 | |---|---|---|---|---| | general-image | 1-2 张图 | STD | medium | 描述任意图片 | | ui-to-artifact | 1 张图 | PRO | high | UI 截图 → 自包含 HTML | | diagram-analysis | 1 张图 | PRO | high | 提取架构/流程图的节点和边 | | data-viz | 1 张图 | STD | high | 从图表中提取数据 | | error-diagnosis | 1 张图 | LITE | low | 诊断截图中的报错 | | ui-diff | 2 张图 | STD | medium | 对比设计稿与实现截图 | | paper-figure | 1-2 张图 | PRO | high | 撰写学术配图分析段落 | | extract-text | 1 张图 | LITE | low | OCR 式纯文本提取 | | extract-table | 1 张图 | LITE | low | 图片表格 → .xlsx + HTML |

每个子命令均支持：

• --model-tier <auto|pro|std|lite>（默认 auto，使用各 action 预设档位）
• --effort <minimal|low|medium|high>（默认按 action 预设）
• --extra-prompt <文本>（追加到分析提示词末尾）
• --format json（输出结构化 JSON，便于下游程序解析）

使用指南（面向 AI Agent）

如果你是通过 MCP 或 CLI 调用 seed-viz 的 AI agent，请按本节使用。

按用户意图选择 Action

| 用户想…… | Action | 说明 | |---|---|---| | 描述 / 转录任意图片 | general-image | 兜底动作，会先转录文字 | | 把 UI 截图变成可运行的 HTML | ui-to-artifact | 返回自包含 HTML 文档 | | 从架构/流程图提取节点、边、层级结构 | diagram-analysis | 适合时输出 Mermaid | | 从图表读取坐标轴、数据点、趋势 | data-viz | 仅限定量图表 | | 诊断截图中的报错 | error-diagnosis | 分类错误并给出修复建议 | | 逐项对比两张 UI 截图 | ui-diff | 需要 image2 参数 | | 两张相关图片（配图面板、多视角、前后对比） | general-image / paper-figure | 第二张图通过 image2 传入；用 extra_prompt 描述关系。这不是逐像素 diff——ui-diff 仅用于设计稿与实现对比。 | | 撰写学术配图分析段落 | paper-figure | 通过 extra_prompt 传入配图契约和论文背景 |

没有明确匹配的 action 时，用 general-image 并把具体要求写进 extra_prompt。不要在同一张图上反复试不同的 action——选一个，通过 extra_prompt 精调。

参数约定

• image（必填）：本地文件路径或 http(s) URL。
• image2（可选第二张图）：ui-diff 必须提供；general-image 和 paper-figure 在处理相关图组（同一配图的多个面板、同一对象的多个视角等）时可选。用 extra_prompt 说明两张图的关系。
• action：省略时默认为 general-image。
• extra_prompt：附加的自由格式指令，适合"关注误差线""这是某论文关于 X 的配图"等具体要求。
• model / effort：没有特殊理由就别设。每个 action 都有调好的预设。降档可省钱，但密集图片的质量会变差。
• CLI 专用：--format json 输出结构化 {tool, content, model, effort}，便于下游解析。

输出处理

• stdout：分析结果（text 模式）或 JSON 对象（json 模式）。这是该呈现给用户的答案。
• stderr：日志和诊断信息。不要当答案给用户。
• 退出码：0 成功 · 2 配置错误 · 3 输入错误 · 4 API 错误 · 5 超时。非零退出时，先修复根因再重试。

seed-viz 不适合做什么

• 文档解析（PDF/DOCX/PPTX → 文本） → seed-viz 只处理图片。文档提取由 docdistill 负责（uvx docdistill），一个基于 MinerU 的独立 Python MCP。
• 扫描件 / 手写笔记（图片 OCR） → 单张图片用 extract-text（analyze_image 的一个 action）。整篇多页文档请用 docdistill。
• 生成图片（文生图） → 用扩散模型。seed-viz 只做图→文。
• 渲染架构 / 网络图 → diagram-analysis 是"读"图，不会"画"图。
• 交互式 Web 应用 / 仪表盘 → ui-to-artifact 产出的是静态 HTML。

成本意识

部分 action 使用更大的 Pro 模型，成本更高。探索性的"这图里有啥"先用 general-image，确有需要再换更重的 action。

CLI 快速示例

seed-viz general-image screenshot.png
seed-viz ui-to-artifact mockup.png --format json
seed-viz ui-diff design.png impl.png
seed-viz diagram-analysis arch.png
seed-viz general-image chart.png --extra-prompt "关注误差线，忽略图例"
seed-viz paper-figure figs/fig1.png \
  --extra-prompt "配图：5 种方法的 grouped bar chart。论文比较 Proposed Method X 与 baselines 在 3 个指标上的表现，声称 X 在指标 2 上优于所有 baseline。"

真实案例

端到端运行，展示用户给 Claude 的指令 → seed-viz 调用 → 结果。每个案例均附等价 CLI 命令和输出文件。

A. UI 复刻与差异分析

两步工作流：(1) 把 UI 截图复刻成 HTML，(2) 复刻成果与原图做差异分析。

第 1 步——复刻：

用户："复刻这个 UI: /tmp/i/1.png"

→ action=ui-to-artifact，返回自包含 HTML 文档。

| 输入截图 | 浏览器渲染复刻 | |---|---| | | |

seed-viz ui-to-artifact examples/ui-replication/mineru-ui-original.png

输出：mineru-ui-replica.html（32.9KB，无外部依赖）。

第 2 步——差异分析：

用户："分析这两个 UI 之间的区别: /tmp/i/1.png 和 /tmp/i/2.png"

→ action=ui-diff，返回结构化 Markdown 报告，逐条标注文案、结构、视觉差异，附优先级修复清单。

seed-viz ui-diff examples/ui-replication/mineru-ui-original.png examples/ui-replication/mineru-ui-rendered.png

完整报告：ui-diff-analysis.md。

文件清单：mineru-ui-original.png（1718×1047，168.7KB）· mineru-ui-replica.html（32.9KB）· mineru-ui-rendered.png（1659×985，120.2KB）· ui-diff-analysis.md

B. 架构图分析（架构图 → Mermaid）

用户："分析一下这个架构图: /tmp/i/3.png"

→ action=diagram-analysis，返回 Mermaid 流程图加结构化拆解。

| 输入架构图 | Mermaid 渲染 | |---|---| | | |

seed-viz diagram-analysis examples/diagram-analysis/architecture-original.png

输出：architecture.mmd——flowchart LR 还原全部五层架构，节点带中英双语标签，边带类型标注。

文件清单：architecture-original.png（1009×753，428.9KB）· architecture.mmd（1.8KB）· architecture-mermaid-rendered.png（2529×1357，187.8KB）

C. 数据提取（图表 → 结构化数据）

用户："/tmp/i/4.png 分析一下这张图里面的数据"

→ action=data-viz，返回坐标轴、逐点数据、趋势摘要及 KPI 卡片。

seed-viz data-viz examples/data-viz/api-spend-chart.png

输出：api-spend-analysis.md——提取柱状图数据（日期 × USD，$0–$36 范围，9 个每日消费值含 $35 尖峰）外加周边 KPI 卡片（15,631 总请求、$85.29 总消费、$0.0055 平均单价、865M tokens）。

文件清单：api-spend-chart.png（1414×864，70.5KB）· api-spend-analysis.md（1.6KB）

D. 错误诊断（截图 → 分类错误 + 修复建议）

用户："/tmp/i/5.png 这个错误如何解决?"

→ action=error-diagnosis，分类错误、提取错误码和信息、推断原因、给出修复建议。

seed-viz error-diagnosis examples/error-diagnosis/cssh-error.png

输出：cssh-error-diagnosis.md——提取错误码 0x80070002、本地化错误信息（"系统找不到指定的文件"）、完整上下文行，定位原因为 cssh.cmd 不在 PATH 上，并给出三条可执行修复建议。error-diagnosis 是唯一预设 STD+low 的 action——报错截图通常小而自足，这是设计上的"便宜快"档位。

文件清单：cssh-error.png（1217×640，609.6KB）· cssh-error-diagnosis.md（802B）

E. 通用图像（兜底动作）

general-image 处理开放式问题："这是什么？""描述一下""正常吗？"。它先转录图片中的文字，然后凭世界知识自由作答。搭配 extra_prompt 可将自由描述能力定向到结构化分析，覆盖专门 action 未覆盖的场景。

E.1 ——自由识别（无 extra_prompt）

用户："/tmp/i/6.png 这是什么猫啊,感觉好可爱"

→ action=general-image（无 extra_prompt），凭视觉特征 + 世界知识识别品种。

seed-viz general-image examples/general-image/cute-cat.png

输出：cat-identification.md——识别出是橘色异国短毛猫或英短，从扁脸、圆身、吐舌（blep）、四仰八叉露肚皮等特征综合判断。

E.2 ——通过 extra_prompt 定向分析

用户："/tmp/i/7.png 闲鱼上这个mate 80 看上去靠谱吗?"

→ Claude 自行补充 extra_prompt，指定按价格、卖家信用、红旗信号、照片真实性、可信度等维度评估。

seed-viz general-image examples/general-image/xianyu-mate80-listing.png \
  --extra-prompt "闲鱼 Mate 80 列表。分析价格、卖家信用、红旗信号、照片真实性，给出可信度评估。"

输出：xianyu-scam-assessment.md——结论 0/10，确认骗局。推理链串联截图转录（无价格、无卖家信息、无描述）+ 世界知识（Mate 80 截至 2024 年中根本不是合法零售设备）+ 物理照片取证（圆形吸盘痕迹 → 工程样机）。

文件清单：cute-cat.png（912×2016，427.2KB）· cat-identification.md · xianyu-mate80-listing.png（1216×2688，3.6MB）· xianyu-scam-assessment.md

F. 图片表格提取（表格 → Excel）

seed-viz extract-table <image> 把图片中的表格转成可直接使用的 Excel .xlsx （合并单元格、上下标保留），并把 HTML 中间产物保留在磁盘上。

seed-viz extract-table ./sales.png
# xlsx: ./mineru-out/sales.xlsx   （可直接打开、编辑）
# html: ./mineru-out/sales.html    （保留，便于重新转换 / 生成 LaTeX）

需要 LaTeX 输出时，把 HTML 中间产物喂给 LLM（"把这个 HTML 表格转成 LaTeX tabular"）。

通过 MCP 在 analyze_image 下使用 action: "extract-table"；响应中含内联 HTML 及 保存后的 xlsx 路径。如果只想从图片取纯文字（不需要结构），用 extract-text （MCP 下为 action: "extract-text"）。

文档解析

文档提取（PDF/DOCX/PPTX → Markdown/LaTeX/JSON）不在 seed-viz 内。它由 docdistill（uvx docdistill）负责——一个基于 MinerU 的独立 Python MCP。seed-viz 只处理图片。

extract-text（analyze_image 的一个 action）仍可用于单张图片的 OCR（截图、扫描单页）。整篇多页文档请用 docdistill。

阻止模型直接读取图片

可选加固。 模型（尤其是子 agent）有时会绕过 analyze_image 直接调内置文件读取去读图片，把原始字节灌进上下文导致会话崩溃。防御分两层：

1. 软引导——持久指令，告诉模型图片要走视觉工具：

   任何图片文件（png/jpg/jpeg/gif/webp/bmp/tiff/svg/ico/jp2）都调用
   视觉 MCP 工具，绝不调 Read。

   写进 CLAUDE.md、AGENTS.md 或你所用 agent 的等效指令文件。

2. 硬拦截——工具调用前拦截器，在 harness 层直接拒绝图片文件读取，即使子 agent 不读指令也兜得住。

Claude Code

软引导 → ~/.claude/CLAUDE.md（全局）或项目级 CLAUDE.md。

硬拦截 → ~/.claude/settings.json 中的 PreToolUse hook。保存以下脚本为 ~/.claude/hooks/block-image-read.sh：

#!/usr/bin/env bash
set -u
payload="$(cat)"
tool_name="$(printf '%s' "$payload" | jq -r '.tool_name // empty')"
[ "$tool_name" = "Read" ] || exit 0
file_path="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty')"
[ -n "$file_path" ] || exit 0
case "${file_path,,}" in
  *.png|*.jpg|*.jpeg|*.gif|*.webp|*.bmp|*.tiff|*.tif|*.svg|*.ico|*.jp2)
    jq -nc --arg fp "$file_path" '{
      decision: "block",
      reason: ("禁止直接 Read 图片，请改用视觉分析 MCP 工具。被拦截的路径: " + $fp)
    }' ;;
esac
exit 0

在 ~/.claude/settings.json 中注册：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [{ "type": "command", "command": "/block-image-read.sh 的绝对路径" }]
      }
    ]
  }
}

修改后需重启 Claude Code——hook 只在会话启动时加载。

Codex（OpenAI CLI）

配置文件：~/.codex/config.toml（TOML）。

[mcp_servers.seed-viz]
command = "/seed-viz 的绝对路径"
args = ["--mcp"]

软引导 → 项目根 AGENTS.md 或 config.toml 的 instructions 字段。硬拦截 → 使用 [permissions] + filesystem_deny_read_patterns 对图片扩展名加 deny 规则。

OpenCode（opencode.ai）

配置文件：~/.config/opencode/opencode.json（或项目级 .opencode/opencode.json）。

{
  "mcp": {
    "servers": {
      "seed-viz": {
        "type": "local",
        "command": ["/seed-viz 的绝对路径", "--mcp"]
      }
    }
  }
}

软引导 → AGENTS.md（主）或 CLAUDE.md（兼容）。硬拦截 → permissions 数组加 { "action": "read", "resource": "**/*.{png,jpg,jpeg,gif,webp,bmp,tiff,svg,ico,jp2}", "effect": "deny" }。

通用规则

如果不想为每个 agent 单独维护 hook 配置，仅做软引导就能覆盖大部分场景：

任何图片文件都调用 <你的工具名>，绝不调内置文件读取。直接读图片字节会撑爆会话。

硬拦截是给"不读指令的子 agent"兜底用的。

参考

退出码

| 码 | 含义 | |---|---| | 0 | 成功 | | 2 | 配置错误（API key 缺失、环境变量格式错） | | 3 | 输入错误（文件不存在、过大、扩展名不支持） | | 4 | API 错误（端点 HTTP 失败） | | 5 | 超时 | | 1 | 未知错误 |

输出

• stdout：结果内容（text 模式）或 JSON {tool, content, model, effort}（json 模式）
• stderr：日志和诊断信息

开发

git clone <仓库地址> && cd seed-viz
npm install
npm run build        # 编译到 dist/
npm install -g .     # 从源码全局安装

npm test             # 单元测试
npm run typecheck    # 仅类型检查