OpenCode Senses：将「视觉灵魂」注入终端代码助手

你正在用终端里的 OpenCode 写代码，忽然发现一个报错截图发给了 AI——但 OpenCode 是纯文字模型，它看不到这张图。这时候你只能手打错误信息，或者截图给 AI 看后让它"猜"发生了什么。OpenCode Senses 解决的就是这个痛点：给纯文字的 OpenCode 装上一双真正的「眼睛」。

背景：为什么代码助手需要视觉能力

当前 AI 代码助手（OpenCode、Claude Code 等）大多基于纯文本语言模型，能读代码、写代码，但碰到截图、设计稿、错误页面时就「失明」了。传统的解决方案是调用云端多模态 API（如 GPT-4V），但这意味着截图要上传到第三方服务器——对很多涉及内部代码或敏感数据的开发者来说，这是隐私红线。

OpenCode Senses 的作者 Adarsh Gourab Mahalik 决定自己解决这个问题。他用 Moondream 2（一个可以在 6GB 显存本地运行的小型视觉语言模型）为 OpenCode 构建了一套本地视觉插件，所有图像分析都在本机 GPU 完成，截图永远不出本地机器。

这个项目在 Hacker News 上发布后，很快获得了社区关注——不是因为它做了什么超级复杂的黑科技，而是因为它解决了一个开发者每天都会遇到的具体问题，而且做得足够优雅。

核心功能：13 个「感知工具」让 AI 看图说话

OpenCode Senses 提供 13 个结构化视觉工具（都以 senses_ 开头），覆盖了开发者最常见的使用场景：

信息提取类：

• senses_inspect：通用图像分析，返回结构化场景描述（类型、布局、元素、状态）+ 图像说明 + 精确 OCR，无需指定问题即给出完整报告
• senses_ocr：提取图像中的精确文字，支持 kind=all（全部）、kind=code（仅代码）、kind=error（仅错误信息）
• senses_metadata：读取图像元数据（尺寸、格式、模式、字节大小、DPI、EXIF），无需调用 AI 模型

定位检测类：

• senses_detect：在图像中定位指定物体/UI 元素，返回归一化 [0,1] 边界框
• senses_point：返回目标对象的归一化中心点坐标（可用于"点击这里"类操作）
• senses_segment：裁剪出指定物体（需 Moondream 3.x 模型）

增强分析类：

• senses_zoom：对图像区域进行 LANCZOS 放大（1-8倍），再对放大结果执行 OCR 或问答，用于恢复全图尺度下 AI 漏读的小字
• senses_colors：像素级颜色分析——主色调及占比、明度分层（暗/中/亮）、平均 RGB，是 AI 模型无法可靠输出的确定性真值

对比与标注类：

• senses_diff：像素级图像差异对比，返回变化百分比 + 差异区域边界框 + 可选 AI 描述，适合渲染迭代 QA
• senses_annotate：在图像上绘制边界框和点（使用 detect/point 的输出格式），用于直观验证 AI 的定位结果

搜索与状态类：

• senses_reverse：无 API Key 的反向图像搜索，支持本地感知哈希扫描和 Yandex 上传搜索
• senses_status：查询视觉运行时的模型状态、设备信息、显存占用和推理计数

工作原理：TypeScript 插件 + Python 推理服务

OpenCode Senses 的架构分为三层：

第一层：OpenCode 插件（TypeScript）

位于 src/plugin.ts，是 OpenCode 会话内的插件入口，负责：

• 管理插件生命周期
• 注册 13 个 senses_* 工具
• 监听用户附加图片的事件，触发自动分析并注入 <SENSES> 证据块到消息中
• 通过 stdio JSON-RPC 与 Python 运行时通信

第二层：Python 运行时（python/runtime.py）

是一个行分隔的 JSON-RPC 服务器（stdio），管理：

• Moondream 视觉模型的懒加载、热缓存和显式卸载
• 各种图像分析处理器（OCR、检测、颜色、放大等）
• 模型生命周期和显存管理

第三层：视觉模型（Moondream）

默认使用 Moondream 2（约 2B 参数），在 6GB 显存环境下峰值占用约 4.5GB。若拥有大显存 GPU，可切换到 Moondream 3.1-9B 以获得更强的分析能力。

项目源码目录结构清晰：

src/plugin.ts            插件入口：选项、生命周期、自动注入
src/opencode/tools.ts    13个 senses_* 工具注册
src/providers/photon.ts  URL下载/缓存 + JSON-RPC桥接到Python
src/providers/types.ts   请求/结果契约（统一使用归一化bbox）
src/core/context-builder.ts 防护守卫 + 证据渲染（<SENSES>块）
python/runtime.py        视觉运行时：Moondream + 所有分析处理器

两个关键设计决策值得注意：

1. 自动注入机制（Auto-inject）：用户附加图片时，插件自动分析并追加 <SENSES> 证据块，模型无需主动调用工具即可「看到」图像——降低了交互摩擦，适合作为默认行为。

2. 提示注入防护：所有模型从图像中读取的文字都包裹在 <SENSES> 证据块中，且显式标注为「untrusted data」（不可信数据）。这意味着截图里即便有人试图注入 prompt（"ignore previous instructions"），也会被模型当作数据而非指令处理——这个设计是开源项目中相对少见的隐私安全考量。

上手体验：5 分钟安装，无任何 API Key

安装过程极度简洁：

# 1. 安装 npm 包（全局或项目内均可）
npm install -g opencode-senses

# 2. 在 opencode.jsonc 中启用插件
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-senses"]
}

# 3. 重启 OpenCode，首次使用时自动完成以下步骤：
#    - 创建 ~/.cache/opencode-senses/venv 虚拟环境
#    - 安装 moondream 及依赖（若系统有 uv 则比 pip 快 10-100x）
#    - 从 Hugging Face 下载 Moondream 2 权重（约 3.9GB，一次性）
#    - 后续使用全部离线运行

首次推理会稍慢（加载模型权重），之后由于 KV Cache 热缓存，推理通常在亚秒级完成。作者在 HN 上分享：在 RTX 3050 笔记本上，单张图像分析仅需 300ms。

对于 Web 图像，所有工具都支持直接传入 https:// URL，图片会被原样下载（保留原始类型、字节和尺寸）并缓存在 ~/.cache/opencode-senses/fetched/，无需手动下载再引用。

典型使用场景

场景一：截图还原设计稿

> "Build this mockup from ui.png"
  senses_detect(ui.png, "search input")  → bbox=[0.12, 0.08, 0.53, 0.13]
  senses_detect(ui.png, "submit button") → bbox=[0.73, 0.28, 0.88, 0.35]
  → AI 基于精确坐标实现设计稿

场景二：渲染质量像素级验证

> "Did the new render change the top-right icon?"
  senses_diff(path="render-v1.png", otherPath="render-v2.png", describe=true)
  senses_zoom(path="render-v2.png", region="0.6,0.1,0.9,0.3", scale=4, analyze="ocr")

场景三：错误日志精确提取

> "What does this error say?"
  senses_ocr(path="error.png", kind="error")
  → 精确返回：Login failed / 账户暂时锁定 / 15分钟后再试

局限与争议

1. 依赖本地 GPU：没有 NVIDIA 或 Apple Silicon，就只能用 Moondream 的云端 API——但这违背了项目「本地优先」的初衷
2. Apple Silicon 性能：Windows/NVIDIA 平台优化更成熟，Apple Silicon 虽然支持但实测性能数据较少
3. Moondream 模型能力边界：Moondream 2 是轻量级视觉模型，在复杂场景理解、长文本 OCR 精度上与 GPT-4V 等大型多模态模型存在差距
4. segment 工具依赖特定模型：默认 Moondream 2 不支持分割功能，需要切换到 Moondream 3.x 才能使用
5. Yandex 反向搜索的可用性：Yandex 有反爬机制，脚本化上传可能被拦截，只返回搜索链接（作者也在文档中坦诚这一点）

行业意义

OpenCode Senses 代表着 AI 开发者工具链中一个明确的趋势：本地化多模态推理。当 GPT-4V 等云端视觉 API 成为主流时，这个项目证明：在一个 6GB 显存的消费级 GPU 上，完全可以完成大多数开发者日常需要的视觉任务——OCR、UI 定位、截图分析。

更重要的是，它的插件化设计让视觉能力可以热插拔到 OpenCode 中——不需要 fork 整个项目，不需要改 OpenCode 核心，一行配置即可启用。这种「扩展而非修改」的理念，对 AI 工具的生态建设有很好的示范意义。

随着开源视觉模型的能力持续提升（Moondream 3 已在预览中），这类本地多模态工具的实用性只会越来越好。隐私敏感且有本地 GPU 的开发者，OpenCode Senses 是一个值得现在就装上的工具。