opencode-senses
itsmeadarsh2008/opencode-senses加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你正在用终端里的 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 上发布后，很快获得了社区关注——不是因为它做了什么超级复杂的黑科技，而是因为它解决了一个开发者每天都会遇到的具体问题，而且做得足够优雅。
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 描述，适合渲染迭代 QAsenses_annotate：在图像上绘制边界框和点（使用 detect/point 的输出格式），用于直观验证 AI 的定位结果搜索与状态类：
senses_reverse：无 API Key 的反向图像搜索，支持本地感知哈希扫描和 Yandex 上传搜索senses_status：查询视觉运行时的模型状态、设备信息、显存占用和推理计数OpenCode Senses 的架构分为三层：
第一层：OpenCode 插件（TypeScript）
位于 src/plugin.ts，是 OpenCode 会话内的插件入口，负责：
senses_* 工具<SENSES> 证据块到消息中第二层：Python 运行时（python/runtime.py）
是一个行分隔的 JSON-RPC 服务器（stdio），管理：
第三层：视觉模型（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"），也会被模型当作数据而非指令处理——这个设计是开源项目中相对少见的隐私安全考量。
安装过程极度简洁：
# 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分钟后再试
OpenCode Senses 代表着 AI 开发者工具链中一个明确的趋势：本地化多模态推理。当 GPT-4V 等云端视觉 API 成为主流时，这个项目证明：在一个 6GB 显存的消费级 GPU 上，完全可以完成大多数开发者日常需要的视觉任务——OCR、UI 定位、截图分析。
更重要的是，它的插件化设计让视觉能力可以热插拔到 OpenCode 中——不需要 fork 整个项目，不需要改 OpenCode 核心，一行配置即可启用。这种「扩展而非修改」的理念，对 AI 工具的生态建设有很好的示范意义。
随着开源视觉模型的能力持续提升（Moondream 3 已在预览中），这类本地多模态工具的实用性只会越来越好。隐私敏感且有本地 GPU 的开发者，OpenCode Senses 是一个值得现在就装上的工具。