# 桌面 API

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

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

## 语法
```text
window.bt.call(name, ...args)
window.bt.window.set_title(title)
window.bt.window.set_size(width, height)
window.bt.window.set_close_mode(mode)
window.bt.window.open_devtools()
window.bt.dialog.open_file(options)
window.bt.tray.enable(options)
window.bt.clipboard.read_text()
window.bt.notify.show(options)
window.bt.drag.on_files(callback)
window.bt.app.version()
window.bt.app.watch_path(path, callback, options)
window.bt.credential.store(credential_id, secret)
window.bt.http.stream(options, callback)
window.bt.workspace.open(root)
window.bt.workspace.list(workspace_id, relative, recursive)
window.bt.workspace.read(workspace_id, relative, max_bytes)
window.bt.workspace.atomic_write(workspace_id, relative, content, expected_sha256)
window.bt.process.start(options)
window.bt.process.status(process_id, task_id, identity)
window.bt.process.stop(process_id, task_id, identity)
window.bt.process.stop_task(task_id)
window.bt.data.store(key, value)
window.bt.data.prepare_cleanup()
window.bt.data.confirm_cleanup(confirm_token)
window.bt.events.on_backend(callback)
```

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

## 参数
### bt.call
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | `main.bt` 中的全局函数名 |
| ...args | any | 否 | 传给 BT 函数的参数，会按 JSON 值转换 |

### bt.window
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| set_title | title:string | void | 设置窗口标题 |
| set_size | width:number, height:number | void | 设置窗口逻辑尺寸 |
| set_resizable | resizable:boolean | void | 设置是否允许调整大小 |
| minimize / maximize / restore / close / hide / show / focus / center | 无 | void | 常用窗口动作 |
| set_fullscreen | fullscreen:boolean | void | 设置全屏 |
| is_fullscreen / is_maximized / is_minimized / is_visible / is_always_on_top | 无 | boolean | 读取窗口状态 |
| set_always_on_top | enabled:boolean | void | 设置窗口置顶 |
| set_decorations | visible:boolean | void | 设置系统标题栏和边框 |
| set_skip_taskbar | enabled:boolean | void | 设置是否跳过任务栏 |
| set_close_mode | mode:string | void | `exit`、`hide` 或 `tray` |
| drag | 无 | void | 自定义标题栏拖动窗口 |
| start_resize | edge:string | void | `top`、`bottom`、`left`、`right`、`top_left`、`top_right`、`bottom_left`、`bottom_right` |
| flash | 无 | void | 请求系统提醒用户关注窗口 |
| open_devtools | 无 | void | 打开 WebView 开发者工具，仅在 `dev.devtools=true` 时可用 |

### bt.dialog
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| open_file | options | string 或 null | 选择单个文件 |
| open_files | options | string[] | 选择多个文件 |
| open_dir | options | string 或 null | 选择目录 |
| save_file | options | string 或 null | 选择保存路径 |
| message | message:string, options | void | 显示消息框 |
| confirm | message:string, options | boolean | 显示确认框 |

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

### bt.tray
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| enable | options | void | 启用托盘图标，重复调用会更新现有托盘 |
| disable | 无 | void | 关闭托盘图标 |
| set_icon | icon:string | void | 设置托盘图标路径 |
| set_tooltip | text:string | void | 设置托盘提示 |
| set_menu | menu:array | void | 设置托盘菜单 |
| on_menu_click | callback | function | 监听菜单点击，返回取消监听函数 |

菜单项格式为 `{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
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| read_text | 无 | string | 读取文本剪贴板 |
| write_text | text:string | void | 写入文本 |
| clear | 无 | void | 清空剪贴板 |

### bt.notify
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| permission_state | 无 | string | `granted`、`denied` 或 `prompt` |
| request_permission | 无 | string | 请求通知权限 |
| show | options | void | 显示通知 |

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

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

### bt.drag
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| on_files | callback | function | 监听拖入文件或目录，回调参数为绝对路径数组 |

### bt.app
| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| version | 无 | string | 当前应用版本 |
| engine_version | 无 | string | bt_app 引擎版本 |
| platform | 无 | string | `windows`、`macos`、`linux` 或其他系统名 |
| open_url | url:string | void | 用系统默认浏览器打开 HTTP/HTTPS 地址 |
| open_path | path:string | void | 用系统默认程序打开文件或目录 |
| reveal_path | path:string | void | 在文件管理器中定位路径 |
| quit | 无 | void | 退出程序 |
| args | 无 | string[] | 启动参数 |
| watch_path | path:string, callback:function, options | function | 监听目录文件变化，返回取消监听函数 |
| unwatch_path | 无 | void | 停止当前文件监听 |

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

### bt.credential

安全凭据使用 Windows 当前用户 DPAPI 加密并保存到当前应用的私有数据目录。接口不会向页面提供读取明文的方法。

| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| store | credential_id:string, secret:string | void | 加密并原子保存凭据；同 ID 会覆盖旧密文 |
| has | credential_id:string | boolean | 只判断凭据是否存在 |
| delete | credential_id:string | boolean | 删除指定凭据；返回是否实际删除 |

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| credential_id | string | 是 | 无 | 1～128 字符，仅字母、数字、`_`、`-`、`.` | 调用方定义的稳定凭据 ID，磁盘文件名使用其 SHA-256，不保存原 ID |
| secret | string | 是 | 无 | 非空 UTF-8 文本 | 只在 `store()` 调用和原生请求构造期间短暂出现的凭据明文 |

### bt.http

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

| `stream options` 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| request_id | string | 否 | 自动生成 UUID | 1～128 字符，仅字母、数字、`_`、`-`、`.` | 调用方需要预先关联事件时可指定的唯一请求 ID |
| url | string | 是 | 无 | `http://` 或 `https://` | 请求地址 |
| method | string | 否 | `POST` | 1～16 个 ASCII 字母 | HTTP 方法 |
| headers | object<string,string> | 否 | `{}` | 最多 32 项；名称不超过 128 字符，值不超过 8192 字符 | 非敏感请求头；禁止 `authorization`、`proxy-authorization` 和 `cookie` |
| body | string | 否 | `""` | UTF-8 字节数不超过 4 MiB | 请求正文 |
| credential_id | string | 否 | `""` | 空值或合法安全凭据 ID | 非空时由原生层解密并注入 `Authorization: Bearer ...`，不会回传页面 |
| timeout_ms | integer | 否 | `120000` | 1000～600000 | 整个请求的超时毫秒数 |
| max_response_bytes | integer | 否 | `4000000` | 1～4000000 | 单个响应允许累计的最大字节数 |

`stream()` 返回控制对象：

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| request_id | string | 是 | 无 | 本次请求 ID | 与事件对应的稳定 ID |
| active_limit | integer | 是 | 无 | 当前固定为 8 | 当前进程允许的并发流式请求上限 |
| max_response_bytes | integer | 是 | 无 | 1～4000000 | 本次请求实际生效的响应上限 |
| off | function | 是 | 无 | 无参数 | 仅取消页面事件监听，不终止请求 |
| cancel | function | 是 | 无 | 无参数，返回 `Promise<boolean>` | 原子关闭事件闸门并取消请求 |

流式回调事件字段：

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| request_id | string | 是 | 无 | 本次请求 ID | 请求关联 ID |
| sequence | integer | 是 | 无 | 从 1 严格递增 | 单请求事件顺序 |
| kind | string | 是 | 无 | `start`、`headers`、`chunk`、`done`、`error`、`cancelled` | 事件类型 |
| status | integer | 是 | `0` | 0 或 HTTP 状态码 | 尚未收到响应头时为 0 |
| data | string | 是 | `""` | 单分块文本或最终完整正文 | `chunk` 与 `done` 的正文数据 |
| message | string | 是 | `""` | 脱敏错误文本 | `error` 等事件的状态说明 |
| received_bytes | integer | 是 | `0` | 0～本次响应上限 | 当前累计响应字节数 |

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

### bt.workspace

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

| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| open | root:string | WorkspaceOpenResult | 登记已存在的真实目录；最多保留 8 个，超限淘汰最早登记项 |
| close | workspace_id:string | boolean | 关闭登记，不删除任何文件 |
| list | workspace_id:string, relative:string, recursive:boolean | WorkspaceEntry[] | 有界列出目录，最多 4096 项 |
| read | workspace_id:string, relative:string, max_bytes:integer | WorkspaceReadResult | 读取 UTF-8 文本，最大 4 MiB |
| atomic_write | workspace_id:string, relative:string, content:string, expected_sha256:string\|null | WorkspaceWriteResult | 同目录临时文件原子替换，并可按旧摘要拒绝并发覆盖 |

| 调用字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| root | string | 是 | 无 | 已存在的绝对目录 | 工作区真实根目录 |
| workspace_id | string | 是 | 无 | `open()` 返回的 ID | 原生工作区登记 |
| relative | string | list 否；read/write 是 | `""` | 工作区内相对路径；禁止绝对路径和 `..` | 目标目录或文件 |
| recursive | boolean | 否 | `false` | `true` 或 `false` | 是否递归列目录 |
| max_bytes | integer | 否 | `1048576` | 1～4194304 | 读取上限，超过即拒绝而不是截断 |
| content | string | write 是 | 无 | UTF-8 文本 | 原子写入的新内容 |
| expected_sha256 | string 或 null | 否 | `null` | 64 位十六进制 SHA-256 | 非空时只允许覆盖摘要相同的旧文件 |

| 返回对象 | 字段 | 类型 | 含义 |
| --- | --- | --- | --- |
| WorkspaceOpenResult | workspace_id | string | 原生生成的短期工作区 ID |
| WorkspaceOpenResult | root | string | 规范化后的真实根目录 |
| WorkspaceEntry | path | string | 使用 `/` 的工作区相对路径 |
| WorkspaceEntry | kind | string | `file`、`directory` 或 `symlink` |
| WorkspaceEntry | bytes | integer | 文件字节数；目录和链接为 0 |
| WorkspaceReadResult | path | string | 规范相对路径 |
| WorkspaceReadResult | content | string | UTF-8 正文 |
| WorkspaceReadResult | bytes | integer | 原始字节数 |
| WorkspaceReadResult | sha256 | string | 内容 SHA-256 |
| WorkspaceWriteResult | path | string | 规范相对路径 |
| WorkspaceWriteResult | bytes | integer | 新内容字节数 |
| WorkspaceWriteResult | sha256 | string | 新内容 SHA-256 |
| WorkspaceWriteResult | previous_sha256 | string 或 null | 旧内容摘要；新文件为 null |

### bt.process

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

| `start options` 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| task_id | string | 是 | 无 | 合法短期 ID | 调用方任务归属 |
| program | string | 是 | 无 | 非空，最长 32768 字符 | 可执行程序路径或程序名 |
| args | string[] | 否 | `[]` | 最多 256 项，单项最长 32768 字符 | 不经过 shell 的参数数组 |
| workspace_id | string | 是 | 无 | 已登记工作区 ID | 进程目录边界 |
| cwd | string | 否 | `""` | 工作区内已存在的相对目录 | 子进程当前目录 |
| environment | object<string,string> | 否 | `{}` | 最多 64 项；名称最长 256，值最长 32768 | 只注入该子进程的环境变量，不写入进程快照 |
| timeout_ms | integer | 否 | `0` | 0～86400000 | 0 表示不自动超时；否则到期清理进程树 |
| output_limit | integer | 否 | `65536` | 1～1048576 | stdout、stderr 各自保留的尾部字节上限 |

| ProcessSnapshot 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| id | string | 是 | 无 | 原生记录 ID | `status()` / `stop()` 的 process_id |
| task_id | string | 是 | 无 | 启动时值 | 调用方任务归属 |
| identity | string | 是 | 无 | 64 位摘要 | 精确停止所需的进程身份值 |
| pid | integer | 是 | 无 | 操作系统 PID | 仅用于观察，不可代替 identity |
| program | string | 是 | 无 | 启动时值 | 程序文本 |
| args | string[] | 是 | `[]` | 启动时值 | 参数数组；不得用参数传递敏感凭据 |
| cwd | string | 是 | 无 | 工作区内真实目录 | 实际当前目录 |
| running | boolean | 是 | 无 | `true` 或 `false` | 是否仍在运行 |
| exit_code | integer 或 null | 是 | `null` | 运行中为 null | 退出码 |
| timed_out | boolean | 是 | `false` | `true` 或 `false` | 是否由超时终止 |
| stdout / stderr | string | 是 | `""` | 各自不超过 output_limit | 有界输出尾部 |
| stdout_dropped / stderr_dropped | integer | 是 | `0` | 大于等于 0 | 因上限被丢弃的字节数 |
| started_at | integer | 是 | 无 | Unix 毫秒时间戳 | 启动时间 |

`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 状态只保存在当前应用私有数据根的 `sessions` 目录。清理采用“预览—用户二次确认—一次性票据执行”三步边界，只清理固定应用自有子目录，不访问已登记工作区。

| 方法 | 参数 | 返回值 | 说明 |
| --- | --- | --- | --- |
| store | key:string, value:any JSON | void | 原子保存一个 JSON 文件 |
| load | key:string | any JSON 或 null | 文件不存在时返回 null |
| prepare_cleanup | 无 | CleanupPreview | 统计固定类别并生成 120 秒有效的一次性确认票据 |
| confirm_cleanup | confirm_token:string | CleanupResult | 消费票据并实际清理；票据错误、过期或重复使用均拒绝 |

| 调用字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| key | string | store/load 是 | 无 | 1～64 字符，仅字母、数字、`_`、`-` | 应用 JSON 文件键 |
| value | JSON | store 是 | 无 | 序列化后不超过 4 MiB | 应用状态值 |
| confirm_token | string | confirm_cleanup 是 | 无 | prepare_cleanup 返回且未消费、未过期 | 二次确认票据 |

| 返回对象 | 字段 | 类型 | 含义 |
| --- | --- | --- | --- |
| CleanupPreview | confirm_token | string | 120 秒有效的一次性票据 |
| CleanupPreview | categories | CleanupCategory[] | 固定清理类别统计 |
| CleanupPreview | total_files | integer | 总文件数 |
| CleanupPreview | total_bytes | integer | 总字节数 |
| CleanupPreview | boundary | string | 本次清理真实目录边界说明 |
| CleanupCategory | name | string | `knowledge_cache`、`sessions`、`logs`、`temp` 或 `credentials` |
| CleanupCategory | files | integer | 类别文件数 |
| CleanupCategory | bytes | integer | 类别总字节数 |
| CleanupResult | cleared | string[] | 已处理的固定类别 |
| CleanupResult | removed_files | integer | 清理前文件数 |
| CleanupResult | removed_bytes | integer | 清理前字节数 |
| CleanupResult | workspace_untouched | boolean | 当前实现成功时恒为 true，表示未触碰用户工作区 |

### bt.events

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

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| --- | --- | --- | --- | --- | --- |
| name | string | 是 | 无 | 被调用的 BT 全局函数名 | 调用来源 |
| ok | boolean | 是 | 无 | `true` 或 `false` | IPC 调用是否成功 |
| at | integer | 是 | 无 | Unix 毫秒时间戳 | 完成时间 |

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

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

## 代码示例
`main.bt`：

```bt
/**
 * 返回前端传入的数据。
 *
 * @param data 前端 JSON 参数。
 * @return 响应对象。
 */
fn inspect(data) {
    {
        ok: true,
        message: 'BT 已收到',
        data: data
    }
}
```

页面调用：

```js
try {
  const result = await window.bt.call('inspect', {name: 'BT'})
  await window.bt.window.set_title(result.message)
} catch (err) {
  console.log('调用失败', String(err))
}
```

托盘菜单：

```js
await window.bt.tray.enable({
  tooltip: 'BT 应用',
  menu: [
    {id: 'show', text: '显示窗口'},
    {type: 'separator'},
    {id: 'quit', text: '退出程序'}
  ]
})

window.bt.tray.on_menu_click(async (id) => {
  if (id == 'show') {
    await window.bt.window.show()
    await window.bt.window.focus()
  }
  if (id == 'quit') {
    await window.bt.app.quit()
  }
})

await window.bt.window.set_close_mode('tray')
await window.bt.window.close()
```

监听目录变化：

```js
const stopWatch = await window.bt.app.watch_path('D:/docs', (event) => {
  console.log(event.kind, event.paths)
})

// 不再需要监听时取消
await stopWatch()
```

流式请求与真实取消：

```js
const controller = await window.bt.http.stream({
  url: 'https://example.com/events',
  method: 'POST',
  headers: {'content-type': 'application/json'},
  body: JSON.stringify({stream: true}),
  credential_id: 'service-primary'
}, (event) => {
  if (event.kind == 'chunk') {
    console.log(event.data)
  }
})

// 用户取消后，原生层不会再派发该请求的事件
await controller.cancel()
controller.off()
```

工作区原子更新：

```js
const workspace = await window.bt.workspace.open('D:/project/demo')
const current = await window.bt.workspace.read(workspace.workspace_id, 'config.json')

await window.bt.workspace.atomic_write(
  workspace.workspace_id,
  'config.json',
  JSON.stringify({enabled: true}),
  current.sha256
)
```

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