扩展权限与路径

扩展权限与路径

AI 原文

扩展权限与路径

功能

扩展权限用于把“扩展声明想做什么”和“运行进程允许做什么”分开。manifest.permissions 先声明扩展需要的能力；运行时再结合 BT 进程权限配置判断是否允许加载。

路径 role 用于让 WASM 扩展安全接收项目内路径。宿主会先按 BT 路径规则解析脚本传入的路径，再确认路径没有逃出项目根，最后把它改写为 WASI 预打开目录内的相对路径。

语法

参数

字段说明
fs_read允许读取文件路径 role。
fs_write允许写入文件路径 role。
net预留给 TCP、UDP、WebSocket、DNS 等网络能力。
http预留给 HTTP 客户端能力。
process预留给进程能力。
env预留给环境变量能力。

路径 role

路径 role 写在 bindings.json 的参数上：

role权限要求路径要求
path_readfs_read: true目标必须存在且是文件。
path_writefs_write: true目标存在时不能是目录；目标不存在时父目录必须存在。
path_dirfs_read: true 或 fs_write: true目标必须存在且是目录。

路径 role 的参数类型必须是 string。

返回值

权限声明没有脚本返回值。校验成功时扩展继续加载；权限声明和进程权限不匹配、路径 role 和权限不匹配、路径逃出项目根或路径类型不满足 role 要求时，调用会返回中文错误。

路径转换

脚本可以传入 BT 路径：

宿主处理顺序是：

1. 用 BT 路径规则解析 @ 项目根和普通相对路径。

2. 对已存在路径执行真实路径归一化，防止符号链接逃出项目根。

3. 按 role 校验文件或目录要求。

4. 把宿主路径改写为 WASI 相对路径，例如 in.txt、nested/out.txt 或 .。

5. 把改写后的字符串传给 WASM 模块。

WASM 模块收到的是 guest 相对路径，不应假设会收到宿主绝对路径。

注意事项

  • path_read 和 path_dir 需要目标已经存在。
  • path_write 写入新文件时，父目录必须已经存在。
  • 路径为空字符串会报错。
  • 路径参数不能逃出项目根目录。
  • 文件系统路径能力主要面向 WASM 扩展；纯 BT 扩展通常直接使用 BT 标准库处理项目内逻辑。