j-can-see

j-can-see 视觉工具使用指南

本 MCP server 提供 9 个视觉/像素工具，用于主模型无多模态输入能力时的看图任务。 工具会根据任务自动编排，但理解下面的选择逻辑能让你（AI）用得更准。

触发门控：有眼睛就先用眼睛

工具分两类，触发规则不同：

• 视觉识别类（调上游视觉模型）：see_image / locate / inspect / ocr_long —— 你有原生视觉输入（能直接 Read/查看图片）时，默认不要调用这些工具，直接用自己的眼睛。 只有以下情况才用：
  1. 用户明确要求用 j-can-see；
  2. 原生视觉失效：图片读不了/报错、返回内容降质到不可用、同一问题原生看不出答案；
  3. 任务超出原生视觉的可靠范围：如两屏以上长图的逐字 OCR（原生读会被降采样丢字）、 需要可靠坐标而目测明显不可信的场景。
• 本地像素类（不调视觉模型）：colors / image_diff / crop / trace / extract_fg —— 不受上述门控限制：它们是取像素级真值的仪器（精确 hex、逐像素差异%），任何模型的 眼睛都给不出这些值，需要时直接用。

不确定自己是否有原生视觉？先试一次原生读图：成功 → 按上面规则走；报错/无图像能力 → 你就是本 server 的目标用户，放心使用视觉识别类工具。

工具选择决策树

按你要回答的问题选工具：

问题	工具
这张图是什么 / 说了什么？	see_image
多张图各自是什么？（逐图独立识别）	see_image + each: true
某个东西在哪？（单个目标）	locate
所有同类元素在哪？（每类元素）	inspect
这张超长截图的文字？	ocr_long
把这块裁出来存成文件	crop
这两张图哪里不同？	image_diff
这里到底是什么颜色？	colors
上下/左右颜色是否一致？渐变哪里断了？	colors（profile / 双 region 对比）
这个图形的矢量形状？	trace
把这个图标抠成透明 PNG	extract_fg

核心原则：不信任文字描述的像素级事实

视觉模型对颜色、尺寸、坐标的描述是模糊的（"浅灰"、"大概在右上"）。 凡是要写进代码的像素级事实，用本地工具取真值：

• 颜色 → colors（返回精确 hex + 候选色匹配）
• 差异 → image_diff（逐像素比较）
• 矢量 → trace（从像素拟合 SVG）

这些工具本身也有边界，用之前先知道：

• colors 按 5 位量化分桶聚类，适合 UI 纯色；渐变或照片的主色会被打散成 多个小簇，占比数字只能参考。要精确取某处的色，先用 region 把范围缩到那一块； 比较两处颜色就并行发两次 colors（各带一个 region）比主色 hex； 要看颜色的空间结构（渐变段 / 接缝 / 断层在哪）用 profile: "y" | "x"， 它返回均匀段（纯色/渐变）与跳变点的位置和两侧色值。
• image_diff 返回的是 12×12 网格里差异密度最高的格子，不是精确包围盒 —— 一处跨格线的改动会报成好几块。它用来回答"去哪儿看"，不是"改动的确切边界"。
• trace 只适合扁平高对比图形；照片和复杂渐变出来的 SVG 没有使用价值。
• 放大不增加信息：crop 放大超过原始分辨率的区域时，模型看到的是插值伪影 —— 小尺寸渐变放大后会出现真实的同心圆环带，模型数的"纹理圈数/圆环"可能是在 数伪影，不是原图内容。给模型看的放大 ≤2-3 倍足够；要精确颜色/纹理，用 colors + region 在原图上取（不经过发给模型的 JPEG 编码，色值不受压缩影响）。

核心工作流：粗到细

多步看图任务遵循「先全局，后局部」：

inspect（扫整体布局，拿到所有元素的坐标）
  → locate（锁定你关注的具体目标，拿精确坐标）
    → see_image（用 region 放大看那个目标的细节）

坐标在工具间是通用的（原图像素）：locate/inspect 返回的 x1,y1,x2,y2 直接作为 see_image/crop 的 region 参数传入即可。