前言¶
在 DeepSeek Harness（DSH）里跑桌面型 Agent 时，常见情况是：模型在真机上点窗口、输验证码、扫二维码，你在聊天里只能看到文字描述，无法确认界面真实状态，也很难在关键时刻代劳一两步。传统做法往往是另开端口做远程桌面，或把凭证暴露给浏览器，安全和运维成本都偏高。
下面介绍社区插件 dsh-desktop-view（维护者 soffits，分类：客户端）。它把 cua-spacesd 生成的桌面流与 Cua 的 Web 查看器，经 DSH 既有登录与 Web 服务中继到界面右侧；默认只观看，需要时再「接管 / 归还」，且不额外开端口或子域。
这是什么¶
dsh-desktop-view 在 DSH Web UI 中提供 Agent 运行机器的实时画面与声音：你能看到、听到桌面上的操作；在验证码、二维码登录、意外弹窗等场景下可临时接管，归还后 Agent 继续。流与票据留在服务端，浏览器只持有短时中继票据，并与你的 DSH 登录绑定。
- 仓库：soffits/dsh-desktop-view
- 目录页：SkillHub 插件条目
- 插件包版本（package.json）：0.2.0；许可证 MIT
核心功能¶
界面入口¶
- 右侧边栏 Desktop 标签：可从边栏指引进入，或从会话头部的 monitor 按钮进入。
- 全屏页
/desktop-view/，由你的 DSH 同源提供；适配手机、支持触摸、可直链打开。 - URL 参数
?control=1：直达接管模式。Agent 需要协助时可发送
/desktop-view/?control=1&help=1&session=<其 session id>，归还控制后可将其唤醒以继续任务。
观看与接管¶
- 默认是观看模式：可见可听，点击、按键、剪贴板与文件会被拒绝。
- 选择 Take control 进入接管；Give back 回到观看。长时间无输入、或关闭视图后，接管会自动结束。
- 仅隐藏 Desktop 标签（切到其他边栏、折叠边栏、换会话）时，接管状态仍保留；流会暂停，再次打开继续看。
接管模式下可用能力¶
在持有控制权期间，可使用桌面查看器的完整能力：鼠标、键盘与触摸、屏幕键盘、剪贴板同步、拖拽上传、文件浏览与下载、显示器选择、缩放；在桌面支持时还可使用麦克风。
与 Agent 的协作¶
插件会向 stateFile 写入小型 JSON，Agent 在操作桌面前应读取；每次控制权变化会通知打开该视图的会话。聊天中会以简短的 Desktop control 行展示相关提示（取决于 notifyAgent 配置）。
stateFile 示例：
{
"controller": "user",
"since": "2026-11-08T12:00:00.000Z",
"sessionId": "01H…",
"updatedAt": "2026-11-08T12:00:04.120Z"
}
当用户持有控制权时，controller 为 "user"；否则为 null，并可能记录 lastReason（released、idle、disconnected、replaced、stopped）。驱动桌面的脚本或 Skill 应在 controller 非 null 时让出操作。
安全要点（README 摘要）¶
- 插件路径上的请求经 DSH 准入：Host/Origin 围栏、签名 Cookie，仅 owner 可访问。
- cua-spacesd 的 env token 与插件签发的 viewer 票据不离开 Host 进程；浏览器仅持有短时 relay 票据。
- 观看模式使用只读 viewer 票据，daemon 侧拒绝输入、剪贴板与文件；同一时刻只有一个视图持有控制权。
- 插件页面使用
no-store、无 referrer、严格的同源 CSP。
显示的桌面查看器由运行时的 cua-spacesd 提供（Cua FSL-1.1-MIT）；本插件独立于 Cua，不包含或再分发该查看器。
环境与依赖¶
安装前请确认：
| 项 | 要求 |
|---|---|
| DSH | 0.2.2-rc.1 或更高（engines 写明 dsh >=0.2.2-rc.1 <0.3.0-0） |
| cua-spacesd | 0.12 或更高，与 DSH 同机；DSH 进程能访问 env token（Cua 桌面镜像上通常为 127.0.0.1:3211，token 在 /run/cua/env-token） |
| Node | >= 22（package.json engines） |
| 浏览器 | Chrome、Edge、Firefox 或 Safari 17+；移动端支持 iOS Safari 与 Android Chrome |
安装与启用¶
官方推荐从 GitHub 直接添加（web profile）：
dsh plugin --profile web add github:soffits/dsh-desktop-view
也可在 DSH Web UI 的插件管理器中添加对应 bundle。添加后需重启 DSH。
DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系，本文安装步骤以仓库 README 为准。
配置项¶
各选项出现在 Web UI 中 desktop-view 插件行的字段里：
| 配置 | 默认值 | 说明 |
|---|---|---|
endpoint |
http://127.0.0.1:3211 |
cua-spacesd 监听地址；宜保持 loopback，因该地址会接收 env token |
tokenFile |
/run/cua/env-token |
env token 文件路径，始终留在服务端 |
maxFps |
30 |
查看器请求帧率；降低可减 CPU 与带宽 |
clipboard |
true |
接管时是否同步剪贴板 |
filesRoot |
~ |
接管时可浏览、上传、下载的桌面目录；留空则禁用文件传输 |
microphone |
true |
接管且在桌面支持时是否允许向桌面发送麦克风 |
idleSeconds |
120 |
无输入多少秒后自动从接管回到观看 |
stateFile |
/tmp/dsh-desktop-view/control.json |
插件写入控制状态供 Agent 读取的路径 |
notifyAgent |
wake |
控制权变化时如何通知会话：wake / quiet / off（见 README 对唤醒行为的说明） |
典型用法¶
- 安装插件并重启 DSH，确认本机 cua-spacesd 已运行且 token 路径可达。
- 在 Web UI 打开正在使用桌面的会话，从右侧 Desktop 或会话头 monitor 进入，先以观看模式确认 Agent 操作。
- 遇到需人工介入的界面时，点击 Take control，完成验证码、登录或对话框处理；需要剪贴板或文件时，在接管模式下使用同步与上传/下载（受
clipboard、filesRoot约束）。 - 完成后点击 Give back，或依赖空闲超时自动归还；若 Agent 曾发送带
help=1的链接，归还后按notifyAgent策略可能被唤醒继续。 - 移动端可直接打开
/desktop-view/或带?control=1的链接，在触摸环境下完成同样流程。
适用场景与注意¶
适合谁：在 DSH 上跑依赖真实桌面环境的 Agent（Cua 等），需要在不额外暴露端口的前提下，从浏览器观看、旁听并在关键时刻接管的开发与运维场景。
安装前建议：
- 插件以当前 DSH 进程权限运行；接管模式下文件与剪贴板能力受配置限制，但仍应对照 源码与 MIT 许可证 自行评估。
- 仅在与 README 一致的环境中使用：cua-spacesd、DSH 版本与 loopback token 假设不匹配会导致无法拉流或无法签发票据。
- 自定义 Skill 若会驱动同一桌面，务必周期性读取
stateFile，在用户接管期间停止自动化点击/输入，避免与用户争抢控制权。
结尾¶
dsh-desktop-view 把 Agent 所在机器的视听流收进 DSH 同源 Web UI：平时观看，遇事接管，归还后继续，并借 DSH 登录与中继控制暴露面。若你正在 SkillHub 或 GitHub 检索客户端类插件，可用目录页 soffits/dsh-desktop-view 跳转，完整说明与问题反馈见 GitHub 仓库。
