让模型用摄像头看世界:多帧拼版并自动矫正曝光,可拖动面板里 30fps 的实时预览,以及可选定时把带帧的消息投进绑定的会话。
安装
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:hanhan9999999999999999999/dsh-see-world
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
让 DSH 通过摄像头看世界。
不是「截一张图」,是看着:画面按变化程度挑帧,安静的屋子只给一张,有动静的屋子给你动作; 真的出现了值得看的变化时,它会主动叫醒这个会话。每次给的是一张拼版(多帧 + 钟点 + 序号), 一张图的 token,看得见时间。
工具名:see_world。当前版本 0.3.5(更新记录)。
一眼看懂它能干什么
see_world({action:"look"}) 采样几秒,马上给一张拼版 —— 正常问"现在镜头前是什么"
see_world({action:"watch"}) 阻塞:先给开场画面,然后等到真的变了再回来
see_world({action:"peek"}) 拿插件已经攒下的一张,不用等(被叫醒时用这个)
see_world({action:"snapshot"}) 一张全分辨率静帧(流会停 ~2 秒,只在小字要看清楚时用)
see_world({action:"devices"}) 列摄像头
see_world({action:"status"}) 采集状态、曝光、叫醒次数
see_world({action:"stop"}) 放开摄像头
see_world({action:"help"}) 把内部机制、实测数字、调参说明一次讲清楚(不碰摄像头)
三个界面(都在 DSH 里):
| 位置 | 作用 |
|---|---|
| 设置 → 看世界 | 选摄像头、分辨率、输入帧率、拼图帧数、画质、预览宽度、自动监控、打开即抓一张 |
| 会话输入框上方 看世界 小按钮 | 一键打开实时画面面板 |
| 浮层面板 | 当前摄像头的实时画面 + 亮度/变动/帧数 + 「开始」「停止」「抓一张发到会话」;按住标题栏可以拖到别处,右下角把手可以改宽,位置记在 localStorage,不挡 DSH 的其它操作。键盘和读屏也能用:Esc 关闭,Tab 在面板里循环(不会漏到背后的页面),焦点跟着进出(关掉会还回原来的位置),标题、状态变化和出错都会被念出来 |
装
从市场装(推荐):DSH 里打开 插件 → 发现 → 索引源,加一条
https://raw.githubusercontent.com/hanhan9999999999999999999/dsh-see-world/main/index.json
然后搜「看世界」。索引就放在本仓库里(index.json),钉的是发布那次提交。
从源码装:
node scripts/install-dev.mjs # 装进 desktop profile(会先备份 package.json)
node scripts/install-dev.mjs --check # 只对账
node scripts/install-dev.mjs --remove # 卸载(同样先备份)
桌面版走的是 dsh-see-now 那套开发装法,因为 desktop profile 被 Electron 独占,命令行
dsh plugin install 会被顶回来:
- 拷源码 →
<DSH_HOME>/profiles/desktop/node_modules/dsh-see-world - profile
package.json的dependencies["dsh-see-world"] = "file:<本仓库路径>" - 同一个
package.json的dsh.profile.bundles里加上dsh-see-world
装完要重启 DSH。 插件模块是在启动时读进去的,改代码/换 ffmpeg 路径不会热更。
ffmpeg
采集全靠 ffmpeg。查找顺序:
<DSH_HOME>/see-world.json的ffmpegPath- 环境变量
DSH_SEE_WORLD_FFMPEG/DSH_FFMPEG_PATH/FFMPEG_PATH DSH_FFMPEG_DIR<DSH_HOME>/tools/ffmpeg/bin/ffmpeg.exe← 推荐,放这儿就完事<DSH_HOME>/bin/ffmpeg.exe- 裸
ffmpeg(靠 PATH)
插件每次真要开流前都会再解析一遍,所以「插件先起、ffmpeg 后装」也会自己恢复,不必重启。
Windows 上从 gyan.dev 下 essentials 版解压,把
bin\ffmpeg.exe 放进 <DSH_HOME>/tools/ffmpeg/bin/ 即可。
设置
<DSH_HOME>/see-world.json(设置页写的就是它):
{
"device": "4K AutoFocus Webcam",
"width": 1280, "height": 720,
"fps": 10,
"frames": 4,
"stillSpanSec": 5,
"quality": 1,
"previewWidth": 640,
"monitor": true,
"sendOnOpen": true,
"autoReply": true,
"replyIntervalSec": 25,
"replyAttach": true,
"replyBudget": 20,
"ffmpegPath": null
}
| 键 | 含义 | 范围 |
|---|---|---|
device |
摄像头名字,null = 第一个视频设备 |
see_world({action:"devices"}) 列出来的名字 |
width/height |
采集分辨率 | 160–3840 / 120–2160 |
fps |
采集帧率 | 1–30 |
frames |
一张拼版里放几帧 | 1–9 |
stillSpanSec |
静止识别跨度:至少采这么久才判"画面动没动",判出静止就只给一张大图 | 1–20(默认 5) |
quality |
拼版缩放档次 | 0 省 token / 1 标准 / 2 清晰 / 3 最清晰 |
previewWidth |
面板里小图宽度(不影响发给模型的图) | 240–1280 |
monitor |
画面有动静时主动叫醒会话 | 布尔 |
sendOnOpen |
打开面板就自动抓一张发进会话 | 布尔 |
autoReply |
面板开着时,画面有变化就自动回报(不用你喊它看) | 布尔 |
replyIntervalSec |
两次自动回报之间至少隔多久 | 3–600 |
replyAttach |
回报时把当次变化的那张图一起送过去 | 布尔 |
replyBudget |
一次开流最多自动回报几次(防刷屏) | 1–200 |
ffmpegPath |
指定 ffmpeg | 路径或 null |
越界会被夹到边界并在回包里给中文提示(校验只在宿主做一次,前端不重复实现)。
自动回报:哪个会话开着面板,哪个会话就负责说话
面板一开,「开始」按下之后,插件不只是显示画面——它在宿主侧盯着变化,值得看就往一个会话里投一条消息(可带图)。几条硬规则:
- 投给谁:工具的调用者(
see_world是谁调的)优先;没有就用最近活动的会话;面板上还有「回报到」下拉可以手动改绑(POST /control {action:"bind"})。换绑会让规矩重新说一遍。 - 规矩只说一次:第一句话里带一段「自动回报已开始」的规则块(不用调工具、只说一两句、没变化就说没变化),之后都是短消息。宿主记着"哪些会话已经听过",所以关掉面板再开、绑走再绑回来都不会重讲;只有换到一个没听过的会话才会讲。
- 有间隔、有上限:
replyIntervalSec(默认 25 秒)是最小间隔,replyBudget(默认 20 次)是这一段开流的总次数;面板上随时能关自动回报。 - 自动回报靠"预攒画面"转起来:监控负责在有变化时把拼版塞进队列,回报循环才有东西发。所以面板点「开始」会先把监控挂上(
autoReply打开时这一项自动生效,不用另外勾)。 - 前端没有会话 id:
conversation.composer.dock传进来的 props 是空对象,客户端插件拿不到"当前会话"。真正的来源是 shell 自己 persist 的localStorage['dsh.sessions.current']({"sessionId":"…"})——点按钮、开面板、按开始那一刻读它,把回报目标绑过去;读不到才交回宿主兜底。 - 收起面板不等于停摄像头:自动回报开着,收起面板它继续值班(它是"值班的眼睛");自动回报关着,收起面板顺手放开设备,把摄像头还给开会的人。设置页顶部那一行会显示当前绑在哪个会话、开没开、间隔多少、在不在跑。
它为什么省 token
一张拼版 = 一张图的 token,但里面有 1–9 帧和它们的时间点。
- 挑帧看变化,不按时间均匀抽:把每帧降到 64×36 网格算差异,只看「和参考帧比变了多少」 「和上一帧比动了多少」;安静时第一帧和最后一帧就够了,动起来才补中间帧。
- 真的没动就只给一张:窗口里最后 3 帧粗缩到 80×45(面积平均,噪点被吃掉)、亮度对齐后
比平均差,< 3 就判「基本没动」,只留最后一帧放大 —— 四张一模一样的格子白付 token。
跨度由
stillSpanSec控制(默认 5 秒);短于 3 秒的窗口不判静止,因为这台摄像头开流后 还要两三秒自对焦,那段时间的"变化"是镜头自己在动。 - 亮度自动归一:摄像头对着窗户会整片死白,插件按帧均值算增益(
gainFor),把画面拉到 中间灰附近,并在文字里说明「发生过校正」——所以别把白画面当成白房间。 - 常驻不重启:设备源开着就不停(关掉再开要等硬件唤醒 ~2 秒),成本约 0.14 核; 90 秒没人用它自己放流。
- 开着监控时它自己看:变化持续 0.7 秒以上、过了 6 秒冷却,才攒一张并叫醒你,不是每帧都叫。
面板里的画面为什么是"视频"而不是"一张张刷新"
面板的实时预览走一条长连接,不是轮询:
- 浏览器请求一次
GET /api/see-world/stream?w=640&fps=30,服务端就一直往里写multipart/x-mixed-replace,每节是一张image/jpeg;<img>自己就地换画面,不用 JS 参与。 - 一个摄像头只开一次:UVC 相机是独占的,第二个 ffmpeg 会拿到
Could not run graph … already in use(实测)。所以"给人看的流"和"给模型看的帧" 从同一个 ffmpeg 进程里分两路出(dualOutputArgs):pipe:1出 MJPEG、pipe:3出缩小降帧的 rawvideo(pipe:3在 Windows 上可用,前提是 spawn 时给第 4 个管道)。 - 输入侧请求
-vcodec mjpeg:同一台相机,yuyv422在 1280×720 只给 10fps,mjpeg给 30fps。 - 实测(真摄像头):预览 30.3 fps / 21 KB 每帧,分析 10 fps,一条流喂两个消费者。
- 推帧是"帧到即推",不是定时轮询:
session.watchJpeg(fn)在 ffmpeg 吐出 JPEG 的那一刻 通知预览器,够间隔立刻写、不够就定一个补齐定时器,赶不上的旧帧直接丢。 这条不是优化癖——原来每 16ms 轮询 + 每帧至少隔 33ms,16+16=32ms 差 1ms 不够, 每帧都要等第三次节拍(48ms),30fps 就被自己的节拍砍成 20fps(实测 18.2fps)。 改完实测 29.7fps / p90 42ms。 - 浏览器那边一条 read 里可能躺着好几帧,只解最新那一帧:逐帧解会让解码落后于到达, 缓冲区越积越长,画面看着流畅其实比现实晚好几秒。
- 预览这一路不做亮度归一(ffmpeg 直出 JPEG,改不了像素),面板用
filter: brightness(gain)把分析那一路算出来的增益补回去——所以画面亮度和模型看到的那张是一致的。 - 只有在设备不支持双路时,才退回"取原始帧 + 自己压 JPEG"的老路(
src/jpeg.js, 纯 JS PNG 对摄像头噪声既压不小又压不快,所以那条路只在兜底时用)。
架构
src/
index.js 插件入口:注册 see_world、配置、网页接口;ensureEye/ensureWatcher/captureSheet
tool-spec.js 工具契约(description / parameters / output.schema / render)
define-tool.js @deepseek-ai/dsh-tools 拿不到时的兜底 defineTool(打进 asar 了,插件侧常常解析不到)
capture.js ffmpeg 开流/抓静帧/枚举设备;错误分类(找不到/没权限/设备被占/没有 ffmpeg)
binaries.js 找 ffmpeg:设置里的 ffmpegPath → 环境变量 → $DSH_HOME/tools → PATH
session.js "眼睛":常驻流、环形帧缓冲、变化判定、监控叫醒、拼版、空闲放流
pick.js 从采样里挑「最值得看」的几帧(首张/末张必留,中间按运动量加权)
analyze.js 64×36 网格差异、曝光统计、增益、参考帧混合
sheet.js 拼版排版(1/2/3/4/5-6/7-9 帧的布局)、每格钟点与序号、单帧整图
png.js 纯 JS PNG 编码(zlib deflate + Paeth 滤波 + CRC32),不引依赖
jpeg.js 兜底用的常驻 ffmpeg 编码器(设备不支持"一条流两路输出"时,rgb24 → JPEG)
live.js 实时预览分发:一条长连接、按帧推、慢客户端丢帧
font.js 5×7 点阵字,把时间和序号烧在图上
loop.js 叫醒链路:sessionController.resolveAgent → agent.followup → sessions.flush
settings.js see-world.json 的读/规范化/落盘
trust.js 网页接口的信任栅栏(loopback / 同源 / sec-fetch-site)
log.js 错误日志的位置与轮转(超 2MB 归档成 .1,只留一代)
routes.js /api/see-world 的 /status /frame /stream /devices /config /control /send
client.js 浏览器侧:设置页 + 输入框按钮 + 实时画面浮层(ModuleLoader 包,只 require('react'))
types/
index.d.ts 给从源码调用插件的人:createEye / createWatcher / still / buildSheet 的签名
capture.d.ts 采集子路径(dsh-see-world/capture):inputArgs / outputArgs / parseDevices / spawnFrames
scripts/
verify-meta.mjs verify-docs.mjs logtest.mjs unitest.mjs looptest.mjs sessiontest.mjs
eyetest.mjs watchtest.mjs types-smoke.ts binarytest.mjs hosttest.mjs clienttest.mjs
paneltest.mjs selftest.mjs install-dev.mjs make-index.mjs bench-preview-jitter.mjs bench-sheet.mjs
叫醒链路用的是 Harness 自己的会话服务,不是往控制台打印,也不是塞系统消息:
resolveAgent(sessionId).agent.followup({role:'user', content:[图, 文字], source:{kind:'see-world'}})。
所以模型看到的是「用户贴了一张摄像头照片 + 一句话」,不是一条来路不明的指令。
自检
node scripts/selftest.mjs # 真摄像头:设备枚举 → 开流 → look → snapshot → status,图落 .out/
node scripts/hosttest.mjs # 假宿主:注册、契约、返回值、叫醒投递、7 组网页接口(含信任栅栏)
node scripts/clienttest.mjs # 客户端:ModuleLoader 形态、三个槽位、组件能否出树、CSS 前缀
node scripts/paneltest.mjs # 面板交互:打开/开始/换流地址/拖动/停止/关面板(会真 re-render)
paneltest 里用的是自己写的一套迷你 React(能 re-render、能推进定时器),所以"点一下会怎样"不是靠肉眼:打开面板会不会绑会话、点「开始」带不带 sessionId、跑起来之后 <img> 是不是换成 /stream、拖动跟不跟手、松手落不落盘、关面板要不要停摄像头——都有断言。
hosttest 会把 DSH_HOME 指到临时目录,不会碰真实的 see-world.json。
--no-cam 可以跳过需要摄像头的段(DSH 正开着面板时设备被独占,也必须加这个):
node scripts/hosttest.mjs --no-cam
一条命令跑完全部离线门(元数据对账、文档对账、日志轮转、六个纯函数套件、看护时钟、眼睛状态机、性能基准、类型、三套件):
npm install # 只有类型门需要它(typescript + @types/node)
npm run verify
verify 里十四道门各自也能单跑,红了哪道就单独看:
node scripts/verify-meta.mjs # 版本号/仓库地址/entry.inject/索引钉版 是否互相对得上
node scripts/verify-docs.mjs # README 的设置项、action、脚本引用 是否与代码一致
node scripts/logtest.mjs # 错误日志超过 2MB 会不会归档成 .1
node scripts/unitest.mjs # 纯函数:像素统计、PNG 往返、拼版版式、点阵字、信任栅栏、配置归一(173 条)
node scripts/looptest.mjs # 叫醒层:取服务、投递失败分支、起钟不并发、自动回报文案(77 条)
node scripts/sessiontest.mjs # 眼睛的状态机:没流时的 status、peek/latest、close 幂等、起不来立刻报错(39 条)
node scripts/eyetest.mjs # 眼睛的真路径:ring 留帧与上限、监控攒图与冷却、peek 取走即清、错误分级、重开(42 条,假采集层)
node scripts/watchtest.mjs # 自动回报的决策:什么时候叫、去重、预算、失败上限、没人理就停(57 条,时钟是假的)
node scripts/binarytest.mjs # 找 ffmpeg 的六层优先级、ffmpeg 参数、设备清单解析、stderr 分类(84 条,不需要摄像头)
node scripts/bench-sheet.mjs # 拼一张图多快(4 帧 960×540,中位数预算 300ms;CI 上自动跳过)。会连分解一起打印:缩图 / 行拷贝 / PNG 编码 lv1·lv3·lv6
npm run verify:types # tsc 检查 types/*.d.ts + scripts/types-smoke.ts
(上面的条数是写这段时的快照,以实际运行输出为准 —— 加测试比改文档容易得多。)
想看覆盖率就 npm run coverage:它用 c8 包住整条 verify,统计 src/ 的行覆盖(当前 75%,门槛 70%,掉下去会红)。插桩会把拼版基准拖慢三四倍,所以 bench 在覆盖率模式下自动跳过 —— 那不是代码变慢。
只想确认语法没坏(不跑全部套件)用 npm run check。
Windows 上 npm 可能被执行策略挡住,那就用 npm.cmd,或者直接 node 跑前三个:
node scripts/clienttest.mjs && node scripts/paneltest.mjs && node scripts/hosttest.mjs --no-cam
types/index.d.ts 是给从源码调用插件的 TypeScript 使用者准备的(createEye / createWatcher 那一层),采集子路径另有一份 types/capture.d.ts(dsh-see-world/capture 的 inputArgs / outputArgs / parseDevices / spawnFrames);用 see_world 工具的人不需要它们。scripts/types-smoke.ts 以使用者身份 import 这个包(含 dsh-see-world/capture 子路径),并用 @ts-expect-error 反过来证明类型真的在拦人,而不是退化成 any。
发一个版本之前
顺序不能反 —— index.json 钉的是某次提交的 sha,所以要先有提交,再生成索引:
- 改版本号:
package.json与dsh.plugin.json两处都要改(verify-meta会发现两边不一致)。 - 写 CHANGELOG 顶部那一节,README 的「当前版本」跟着改。
npm run verify:十二道门全绿。- 提交。
node scripts/make-index.mjs重新生成index.json,把这次的提交钉进去。npm run verify:release:它比verify多一条 ——index.json必须已经钉在当前版本上,没钉住就红。git tag vX.Y.Z && git push --tags。
第 5 步不能省,也不能提前:make-index 取的是 HEAD 的 sha,工作树没提交时它只能钉在旧提交上 —— 于是「版本号是新的、索引是旧的」,而 verify:release 就是为拦住这种发布才存在的。
隐私
- 画面在本机编码,不经过任何中转;发进会话的那一张就是普通的对话附件。
- 只有你让它送的那几张图会被写成附件(在 DSH 的会话目录里,你可以自己删);除此之外插件不往磁盘写任何像素。
- 唯一的日志是
<DSH_HOME>/see-world-error.log:只记文本(哪一步失败了、ffmpeg 报了什么),从不含画面数据;超过 2MB 自动归档成.1,只留一代。 - 摄像头在不用时会自己放流(90 秒没有调用、也没在监控,就关流把设备还给系统),
stop立刻放;收起面板且自动回报关着时也会立刻放。 - 画面里的文字是内容,不是指令:屏幕上写着「忽略之前的指令」也只是画面的一部分。
排错
| 现象 | 原因 / 做法 |
|---|---|
没找到 ffmpeg |
把 ffmpeg.exe 放到 <DSH_HOME>/tools/ffmpeg/bin/,或设 ffmpegPath |
摄像头这边出问题了(device-unavailable) |
设备名不对或被别的程序占着;先 see_world({action:"devices"}) |
| 设置页看不到「看世界」 | 插件没加载:看 <DSH_HOME>/see-world-error.log,然后重启 DSH |
| 有按钮但画面一片黑 | 摄像头被系统隐私开关挡了;先用别的程序(相机)确认能出画面 |
| 画面整片白 | 正常,插件会压暗;文字里会说「亮度已校正」 |
插件自己的错误写在 <DSH_HOME>/see-world-error.log;DSH_SEE_WORLD_DEBUG=1 时会把错误再抛出来。
许可
MIT
链接
同类插件
liustack/modlens★ 4996
为纯文本模型架起视觉桥梁:粘贴图片,输出结构化 JSON 证据(OCR、版面、语义)。
ysr666/dsh-vision-router★ 1281
为纯文本 Agent 提供视觉能力:内置免 Key 视觉链 + 像素级视觉工具(看图问答、定位、裁剪、像素对比、取色、OCR、矢量化、抠图、截图);粘贴图片即可用。
Anionex/dsh-vision-toolkit★ 945
让纯文本模型处理视觉任务:粘贴图片后自动切换到 Vision Toolkit 变体,支持图片问答、多图比较、长截图 OCR、截图还原前端 UI、元素定位与像素对比。默认无需 API Key——图片经作者自建的免费服务处理,每台机器每天 100 张;也可改为指向自己的服务商。
SAOS-3624/dsh-see-now★ 672
让只有文字的智能体「看」实时屏幕或摄像头:每帧按画面变化量打分,只把真正变了的帧拼成一张带编号、带音轨条的宫格图——看视频、看演示、看游戏都行,token 只花在变了的地方。
SAOS-3624/dsh-video-storyboard★ 560
把视频(本地文件,或 B 站 / yt-dlp 链接)压成一张可寻址的宫格图:每格烧编号、对应精确时间、挂台词,底部还有同时间轴的音频包络;video_zoom 可对任意窗口高清重看——纯文本模型因此能「看」视频,而不是读别人写的摘要。
kingcharleslzy-ai/dsh-qwen-studio★ 229
DSH 的 Qwen Image 2.1 创作工作区:本机 MLX 或自己的 NVIDIA 服务器,支持原生参考编辑、LoRA、结构控制、蒙版、整套预设、图库与对话实时进度,提供校验更新和 Agent 安装指南。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。