Lets the model look through a webcam: multi-frame sheets with automatic exposure correction, a 30 fps MJPEG preview in a draggable panel, and optional timed replies with a frame attached into the bound conversation.
Install
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:hanhan9999999999999999999/dsh-see-world
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
This plugin publishes its README in Chinese only.
让 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
Links
More in this category
liustack/modlens★ 4996
Vision bridge for text-only models: paste an image, get structured JSON evidence (OCR, layout, semantics).
ysr666/dsh-vision-router★ 1281
Free vision for text-only agents: built-in keyless vision chain plus pixel tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots); paste an image to use it.
Anionex/dsh-vision-toolkit★ 945
Vision for text-only models: paste an image and the model switches to a Vision Toolkit variant for image Q&A, multi-image comparison, long-screenshot OCR, screenshot-to-UI reproduction, element grounding, and pixel diff. No API key by default — images are processed by the author-hosted free service, 100 per machine per day; configurable to your own provider.
SAOS-3624/dsh-see-now★ 672
Lets a text-only agent watch a live screen or camera feed: every frame is scored by how much the picture changed, only the ones that matter are packed into one numbered sheet with an audio envelope, so the model looks at what actually changed instead of a screenshot every few seconds.
SAOS-3624/dsh-video-storyboard★ 560
Turns a video (a local file, or a Bilibili/yt-dlp link) into one addressable storyboard grid — numbered cells with exact timestamps, per-cell transcript and an audio envelope on the same timeline — and video_zoom re-reads any window at higher resolution, so a text-only model can look at the video instead of reading a summary.
kingcharleslzy-ai/dsh-qwen-studio★ 229
Qwen Image 2.1 workspace for DSH: Apple Silicon MLX or your own NVIDIA server, native reference editing, LoRA, ControlNet, inpainting, shared presets, gallery and live agent progress. Includes verified updates and an agent setup guide.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.