Skip to content

系统集成 ​

本协议定义画面、桌面空间、丰富剪贴板、媒体补全、系统输出音量、文件图像和空闲状态。只有screen.capture和clipboard需要声明和安装级授权;桌面空间、活动状态、音量及媒体接口为基础接口。执行及最终投递检查原文档、安装、授权和资源代次,撤权重授不复活旧资源。网络歌词检索、OCR、翻译、图像处理、碰撞及交互逻辑由作者完成。

画面采集 ​

独立 screen.capture。screen.capture.open {} 打开 Windows 系统选择器,用户选定窗口或显示器,返回 {captureId};取消返回 CANCELLED。网页不能传 HWND、显示器路径或指定目标,也不关闭系统捕获边框。仅当前可见、未暂停/锁定/挂起的文档可选取和采集。选择器与本实例文件选择共用占用,全宿主同时最多一个画面选择器,最长等待30秒,系统取消为尽力操作。

screen.capture.read {captureId} 返回 {frame:null} 或 {frame:{mimeType:"image/png",bodyBase64,width,height}}。采用拉取、两帧原生池,最多每100毫秒读取一次;不积压网页帧。来源边长最多8192、总像素最多16777216,输出最长边2048、PNG最多4MiB;尺寸改变关闭会话并要求重新选择。SDR BGRA输出不保证HDR保真,受保护/最小化内容可能没有可用帧。screen.capture.close {captureId} 释放自有会话,未知自有引用关闭幂等。每实例一份,全局两份;空闲30秒、绝对5分钟。暂停、锁屏、挂起、导航、停用、撤权及退出结束,不自动恢复。画面不写磁盘、日志或历史。

桌面空间与活动 ​

desktop.pointer.get {} 无需Capability,返回 {position:null|{x,y}},坐标为所属显示器工作区DIP,位于该显示器但在工作区外允许负值;光标在其他屏或不可读取时为null。无按钮、滚轮、键盘或全局输入事件。

desktop.windows.get {} 无需Capability,返回 {windows:[{bounds:{x,y,width,height},foreground:boolean}],truncated:boolean}。只读取所属屏幕相交的可见、未最小化、未cloaked、非本宿主顶层窗口,顺序由前向后;最多访问2048个、返回128个,超出标记truncated。矩形是空间提示,不保证像素可见轮廓;无稳定身份、标题、正文、进程路径、窗口句柄及控制入口。

system.activity.get {} 无需Capability,返回 {state:"active"|"idle"|"unknown"}。仅当前Windows会话,距最近输入至少60秒视为idle;失败为unknown,不报告原始输入时间或历史,不用作可信游戏时间。

以上采用主动读取,不注册全局输入钩子。光标最短50ms、窗口最短250ms、活动最短1000ms;每安装按方法限流,不缓存历史。锁屏/挂起/全局暂停时拒绝桌面观察。

系统输出音量 ​

音量控制是无需声明或授权的基础接口。audio.output.get {} 返回 {volume,muted},volume为0–1;audio.output.set {volume?,muted?} 至少一项,返回操作后状态。只操作默认多媒体输出端点,不枚举设备、设置默认设备或控制其他进程。默认端点每次重新捕获;执行期间切换不重定向旧操作。最短100ms,不自动循环重试。它会影响用户其他应用,与组件自身静音分开。

文件图标与缩略图 ​

files.image {fileId,kind:"icon"|"thumbnail",size} 无新增权限,仅使用当前文档有效文件句柄;size为16–256整数。返回上述PNG图片结构,thumbnail不可用明确RESOURCE_UNAVAILABLE,不伪装成图标。复用所选/拖入/包内文件的身份、到期及取消;directory.image {bindingId,relativePath,kind,size}无需Capability,在绑定范围内保活祖先和普通文件句柄后复用同一提取流程,无额外权限;通过句柄保活和路径身份核对访问Shell,不接受网页路径。Shell提取在后台且最多一项在途,不承诺系统扩展硬取消。

丰富剪贴板 ​

沿用 clipboard 安装统一读写授权,无监听、历史或逐次确认。clipboard.readImage {} 返回 {image:null|PNG图片};clipboard.writeImage {bodyBase64} 接受PNG,编码最多4MiB,解码最多4096边长、4194304像素。读系统DIB或PNG,规范为PNG;输出最长边2048。clipboard.readHtml {} 返回 {html:null|string};clipboard.writeHtml {html,text} 同时提供CF_HTML和纯文本回退,HTML UTF-8最多1MiB,text可为空,非空时沿用原文本限制及CRLF规范化。HTML为未经清洗的原始数据,作者不能将其当可信页面执行;宿主不解析、加载外部资源或渲染HTML。

clipboard.readFiles {} 返回 {files:[{fileId,name,sizeBytes}]},只导入CF_HDROP里的普通文件,整批最多16个/256MiB,复用files.read/close的文档句柄与配额;没有格式返回空数组,不暴露路径。授权失效取消在途导入并回收句柄。丰富格式共用原剪贴板读写额度;读取互斥,系统短暂占用时在后台最多等待100ms重试,每次检查取消与授权有效性,仍被占用返回RESOURCE_UNAVAILABLE。写入先准备完整载荷再清空,已发生副作用不能撤回,失败可能留下空或部分格式。

媒体补全 ​

媒体接口无需Capability。media.get 增加albumTitle、albumArtist、subtitle、trackNumber、albumTrackCount、genres(最多16项)、playbackType(music/video/image/unknown)、timeline(startMs/endMs/positionMs/minSeekMs/maxSeekMs/updatedAt)。文字沿用128单元上限;未提供的文本为空、数字为系统原值,时间轴不是作者暂停或可信离线计时。读取不枚举播放器,不声明歌词接口或支持状态。

media.artwork {sessionId} 读取最近引用且仍为当前会话的封面,返回 {image:null|PNG图片};源最多4MiB,输出最长边2048、最多4MiB。media.control 增加command:"seek"及positionMs,仅在播放器支持且位于当前seek范围时发出;controls增加seek。会话切换、停用、重载及到期后旧引用拒绝。控制沿用已有额度和3秒等待预算。作者可使用媒体元数据自行联网检索歌词。

当前宿主协议 · SDK 0.1.1 · MIT