桌面 API

桌面 API

功能

bt_app 会向 static、server 和 remote 页面注入 window.bt。桌面 API 提供 BT 后端调用、窗口控制、系统对话框、托盘、剪贴板、通知、文件拖入、目录文件监听、应用信息，以及有界流式 HTTP、应用凭据、工作区、原生进程和应用自有数据能力。

页面只应使用 window.bt。运行器不会公开全局 window.__TAURI__，也不会把本地 fs、net、process 能力直接暴露给前端。

语法

所有异步方法返回 Promise。成功时直接返回数据；失败时 Promise 会 reject，错误值是字符串或可转为字符串的错误对象。

参数

bt.call

bt.window

bt.dialog

options.title 为对话框标题，options.default_path 为默认路径，options.filters 为文件过滤器数组。消息框 options.kind 支持 info、warning、error。

bt.tray

菜单项格式为 {id:'show', text:'显示窗口', enabled:true}；分隔线格式为 {type:'separator'}。同一应用默认只保留一个托盘图标，重复调用 window.bt.tray.enable() 会更新图标、提示文本和菜单，不会新增多个托盘入口。

window.bt.window.set_close_mode('tray') 只设置窗口关闭按钮的行为：之后用户点击窗口关闭按钮或代码调用 window.bt.window.close() 时，窗口会隐藏到托盘，程序继续常驻运行。如果需要按钮点击后立刻关闭到托盘，应先设置 tray 模式，再调用 window.bt.window.close()。

bt.clipboard

bt.notify

options.title 为空时使用应用标题，options.body 为通知正文。

request_permission() 返回的是系统通知权限状态；show() 才是真正发送系统通知。Windows 便携 exe 会使用兼容的 toast 发送路径，不依赖安装器创建的应用通知注册。通知是否弹出桌面横幅仍由操作系统通知设置、勿扰模式和应用通知策略决定，未弹出时通常仍可在系统通知中心查看。

bt.drag

bt.app

watch_path() 使用系统文件事件监听目录变化，不会按固定周期扫描目录。options.recursive 默认为 true，表示递归监听子目录。回调参数为 {root, kind, paths}，kind 可能是 create、modify、remove、rename 或 other。

bt.credential

应用凭据以明文 JSON 保存到当前用户目录 %USERPROFILE%\.<app.name>\credentials\；例如 app.name="bt_ai" 时为 %USERPROFILE%\.bt_ai\credentials\。这是便于迁移和人工维护的明文格式，不使用 Windows DPAPI。接口不会向页面提供读取明文的方法，但能访问该用户目录的本机程序可以读取文件，因此调用方必须在界面中明确提示并保护操作系统账户权限。

bt.http

stream() 发起真实异步 HTTP 请求，通过回调依次返回响应头、SSE 或普通分块以及最终完整正文。启动前会先安装事件监听；cancel() 会先关闭原生事件闸门，再通知网络任务终止，因此取消成功后不会再派发该请求的状态或正文事件。

stream() 返回控制对象：

原生层会在构造第一个 HTTP client 前幂等初始化 Rustls ring crypto provider。因此，即使应用冷启动后直接调用 window.bt.http.stream()，也不依赖 BT 标准库或 Web 服务提前执行网络初始化。

流式回调事件字段：

单个响应最多派发 16384 个分块事件；超过字节数或分块数上限会以 error 结束并释放请求登记。

bt.workspace

工作区 API 先登记一个真实目录，再用短期 workspace_id 操作相对路径。所有路径都经过规范化和真实路径边界检查，递归列表不跟随符号链接或 junction。

bt.process

原生进程使用程序名和参数数组直接启动，不经过 shell。进程必须属于一个调用方任务和已登记工作区；查询、停止时必须同时匹配 process_id、task_id 与不可伪造的 identity。停止会清理该句柄对应的进程树，不按名称批量结束外部进程。

on_event() 回调字段为 process_id:string、task_id:string、kind:string、data:string、pid:integer；kind 可为 start、stdout、stderr、exit、timeout 或 stopped。同时最多登记 32 个进程，结束记录会按启动时间淘汰。

bt.data

应用 JSON 状态默认保存在当前用户 %USERPROFILE%\.<app.name>\sessions 目录。自动化验收可设置 BT_APP_DATA_HOME，把隐藏应用目录临时放到指定父目录；正常桌面运行应保持该变量未设置。清理采用“预览—用户二次确认—一次性票据执行”三步边界，只清理该应用数据根的固定子目录，不访问已登记工作区。

bt.events

on_backend(callback) 监听 bt.call() 完成事件，返回取消监听函数。回调字段如下；事件不包含 BT 函数返回正文。

返回值

bt.call() 直接返回 BT 函数的返回值。BT 函数返回对象时，前端收到普通 JSON 对象；返回字符串、数字、布尔或数组时，前端收到对应 JSON 值。

如果 BT 函数不存在、执行报错、VM 调用队列已满或桌面 API 参数无效，Promise 会 reject，不会返回 {error,message,data} 包装对象。

代码示例

main.bt：

页面调用：

托盘菜单：

监听目录变化：

流式请求与真实取消：

工作区原子更新：

注意事项

• bt.call() 是长期 VM 业务通道；窗口、托盘、剪贴板、通知等桌面能力走独立 command，不占用 BT VM。
• VM 调用队列有上限。前端高频调用时应节流，避免无控增长。
• remote 页面同样拥有完整 window.bt 能力，只应加载可信地址。
• 同一个窗口当前只保留一个 watch_path() 监听；再次监听新目录会替换旧目录监听。
• 设置 BT_PERMISSION_DENY=desktop 后，窗口、对话框、托盘、剪贴板、通知、拖入文件事件、文件监听事件和应用级桌面命令会被拒绝；bt.call() 本身不受 desktop 限制，被调用 BT 函数内部使用的标准库能力仍按各自权限检查。
• 通用生产 API 只提供受边界约束的客户端 HTTP、已登记工作区和句柄化子进程；不会暴露任意文件系统、网络监听、shell 字符串或按名称结束进程能力。
• 凭据是当前用户目录中的明文 JSON，不得再放入 URL、普通请求头、请求体、进程参数、日志或页面存储；应使用 credential_id 让原生层注入，并限制用户目录访问权限。
• 应用关闭、任务取消或清理数据前，应先取消仍在运行的流式请求并精确停止所属任务的子进程。
• 完整示例位于 examples/desktop-api。