桌面

桌面型 Workspace 在 guest 里运行图形桌面。你可以在本机浏览器里查看和操作它，也可以用 kibo workspace desktop 截图、发送键鼠输入，把桌面操作写进脚本。

前提条件复制标题链接

• 一个 kibotos-desktop Workspace。
• 在浏览器中查看时：工作机上准备好 noVNC 客户端，见准备 noVNC。
• 截图与键鼠输入：服务端具备 workspace.desktop 能力，见能力名。

在浏览器中查看桌面复制标题链接

kibo workspace desktop view 在本机启动一个网页，用于查看和操作桌面，并输出网页的地址：

kibo workspace desktop view "$workspace_id"
# Page  http://127.0.0.1:41735/

在浏览器里打开这个地址。页面可以在工作期间一直开着：断开后点「重新连接」即可，不需要重跑命令。

准备 noVNC复制标题链接

网页中的 VNC 客户端是上游 noVNC。kibo 不自带它，需要在工作机上准备一次。当前版本要的是 noVNC v1.6.0。

命令按下面的顺序查找 noVNC，用第一个包含所需文件的目录：

1. --novnc-dir
2. KIBO_NOVNC_DIR
3. /usr/share/kibotos/novnc
4. 工作目录下的 .cache/novnc/<release>

都找不到时命令失败，错误信息给出它要的 noVNC 版本。

下面的命令下载上游归档、核对校验和，把需要的部分解压到用户目录，再让 kibo 从那里读取：

curl -fsSLo novnc.tar.gz https://github.com/novnc/noVNC/archive/refs/tags/v1.6.0.tar.gz
echo '5066103959ef4e9b10f37e5a148627360dd8414e4cf8a7db92bdbd022e728aaa  novnc.tar.gz' | shasum -a 256 -c -
mkdir -p "$HOME/.local/share/kibotos/novnc"
tar -xzf novnc.tar.gz -C "$HOME/.local/share/kibotos/novnc" --strip-components=1 \
  noVNC-1.6.0/core noVNC-1.6.0/vendor noVNC-1.6.0/LICENSE.txt noVNC-1.6.0/AUTHORS
export KIBO_NOVNC_DIR="$HOME/.local/share/kibotos/novnc"

连接复制标题链接

查看命令为桌面的 VNC socket（/run/kibotos/services/desktop/vnc.sock）申请数据面凭证，把 RFB 流量转成本机的 WebSocket 给浏览器。

启动：

• Workspace 开机时桌面不运行，第一次连接会启动它。
• 命令先连一次，在拨号期限（5 秒）内等桌面就绪。来不及时命令失败，重跑即可。

保持连接：

• 凭证在到期前自动换新，Workspace 重新启动后也会重新申请。
• 连接没有时长、空闲或累计流量上限。凭证过期不会断开已建立的连接。
• 一个查看命令最多同时保持 16 条连接，例如 16 个标签页，超出时新连接被拒绝。

下列情况下连接结束：

• Workspace 停止或删除，或所在 node 重启。页面会提示并允许重新连接。
• 浏览器停止读取，要发给它的数据 5 秒内没有被接收。

截图与键鼠输入复制标题链接

kibo workspace desktop 的其他子命令直接对桌面截图或发送键鼠输入。它们与浏览器中的查看页面共享同一个桌面，互不抢占。

桌面还没运行时，第一次调用会启动它，并在调用期限内等它就绪。

截图复制标题链接

screenshot <workspace-id> <local-path|-> 把当前画面保存到本地文件：

kibo workspace desktop screenshot "$workspace_id" screen.png

• 先写到目标旁边的临时文件，写完后再替换目标。
• 目标不能是符号链接或特殊文件；新建文件权限为 0600。
• 输出包含 path、format、width、height、size_bytes 和 sha256。
• 刚就绪的桌面可能还没画完，第一张截图里不一定有完整的桌面。

路径为 - 时图片写到标准输出，这时不能用 --json，上述信息改写到标准错误：

kibo workspace desktop screenshot "$workspace_id" - > screen.png

指针输入复制标题链接

每个输入子命令执行一次输入动作，成功后输出指针位置 pointer（x、y），人读格式为 x,y。

下面的命令移动指针、点击、拖动和滚动：

kibo workspace desktop move "$workspace_id" 640 360
kibo workspace desktop click "$workspace_id"
kibo workspace desktop click "$workspace_id" 640 360 --button right --count 2
kibo workspace desktop drag "$workspace_id" 100 100 400 300 --button left
kibo workspace desktop scroll "$workspace_id" --direction down --amount 3

键盘与文本输入复制标题链接

下面的命令按下组合键、输入文本和粘贴文本：

kibo workspace desktop key "$workspace_id" ctrl+l
kibo workspace desktop type "$workspace_id" '在搜索框里输入中文 😀'
kibo workspace desktop paste "$workspace_id" "$(cat notes.md)"
kibo workspace desktop paste "$workspace_id" 'ls -la' --keys ctrl+shift+v

• key 接受的键名：单个字符，或 shift ctrl alt super enter tab escape backspace delete insert space home end pageup pagedown up down left right f1..f12。
• type 输入键盘布局中没有的字符（中文、emoji 等）时，会临时占用布局中空闲的键位，调用结束后恢复。每批字符都要等桌面应用重新读取布局，长文本或字符种类多的文本用 paste 更快。
• paste 把写入剪贴板和按快捷键放在一次调用里，因为桌面上任何应用复制内容都会覆盖剪贴板。
• 桌面进程重建后剪贴板为空。
• 终端应用通常需要 --keys ctrl+shift+v。

用 API复制标题链接

程序通过数据面 DesktopService 的 Screenshot 与 PerformActions 截图和发送输入。kibo workspace desktop 除 view 以外的每个子命令各发起一次这样的调用。

• 服务端须具备 workspace.desktop 能力，见先查询能力。
• 每次调用需要 DESKTOP 范围的数据面凭证，见申请会话凭证。
• 全部方法与消息见 DesktopService。

一个 PerformActions 请求带一组动作。服务端先检查整组，再投递其中的动作。每个动作遵守上文表格里的限制，整个请求另有这些限制：

超出任一限制的请求以 invalid_argument 失败，不投递任何动作。

注意复制标题链接

• 坐标是否在屏幕内、取值是否在上述限制以内、键名是否可用由服务端判断。kibo 只检查参数格式：非数字坐标、未知按钮和方向在发请求前就被拒绝。
• Template 的默认账号在 guest 里不可用时，桌面也不可用，见默认账号不可用。

下一步复制标题链接

• 服务与端口：打开 guest 里的其他 Web 服务。
• 命令与终端：在桌面之外执行命令。
• API 概览：自己的程序需要的凭证与约定。