DeepSeek Harness 插件

hanhan9999999999999999999/dsh-see-world

Star 数 ★ 0 分类 视觉与多模态 收录于 2026-11-16

让模型用摄像头看世界:多帧拼版并自动矫正曝光,可拖动面板里 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 会被顶回来:

  1. 拷源码 → <DSH_HOME>/profiles/desktop/node_modules/dsh-see-world
  2. profile package.json 的 dependencies["dsh-see-world"] = "file:<本仓库路径>"
  3. 同一个 package.json 的 dsh.profile.bundles 里加上 dsh-see-world

装完要重启 DSH。 插件模块是在启动时读进去的,改代码/换 ffmpeg 路径不会热更。


ffmpeg

采集全靠 ffmpeg。查找顺序:

  1. <DSH_HOME>/see-world.json 的 ffmpegPath
  2. 环境变量 DSH_SEE_WORLD_FFMPEG / DSH_FFMPEG_PATH / FFMPEG_PATH
  3. DSH_FFMPEG_DIR
  4. <DSH_HOME>/tools/ffmpeg/bin/ffmpeg.exe ← 推荐,放这儿就完事
  5. <DSH_HOME>/bin/ffmpeg.exe
  6. 裸 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,所以要先有提交,再生成索引:

  1. 改版本号:package.json 与 dsh.plugin.json 两处都要改(verify-meta 会发现两边不一致)。
  2. 写 CHANGELOG 顶部那一节,README 的「当前版本」跟着改。
  3. npm run verify:十二道门全绿。
  4. 提交。
  5. node scripts/make-index.mjs 重新生成 index.json,把这次的提交钉进去。
  6. npm run verify:release:它比 verify 多一条 —— index.json 必须已经钉在当前版本上,没钉住就红。
  7. 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

内容来自项目 README(GitHub)↗

链接

同类插件

查看整个分类 →

社区评论

评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。