嵌入与宿主权限

Rust API

yanxu::embed::Engine是持久执行入口。它保留全局绑定，返回值、值类型、可选原始value_bytes、输出和后端均为结构化字段；前端、类型、编译、运行和 I/O 错误有独立类别。若一次运行失败，运行时会丢弃可能部分改写的状态与类型历史；后续调用从空状态开始。宿主也可显式调用Engine::reset()。

use yanxu::embed::{Backend, Engine, EngineConfig};

let mut engine = Engine::new(EngineConfig::sandboxed(Backend::Bytecode));
let result = engine.run("令 答案：数 为 42；言 答案；")?;
assert_eq!(result.output, ["42"]);
# Ok::<(), yanxu::embed::EngineError>(())

宿主可设置config.arguments，由程序通过环境.参数（）读取。返回值为字节串时，Execution.value仍是无泄露的长度摘要，原始内容仅出现在value_bytes: Option<Vec<u8>>。

默认配置使用字节码 VM、静态检查和无宿主能力沙箱。可信宿主可用PermissionSet逐项开放文件根目录、网络外连主机、TCP 监听地址、UDP 绑定地址或环境变量；allow_process开放子进程能力。EngineConfig::unrestricted必须由宿主显式选择。

运行 YXB 时，归档权限是应用的申请，不是授权。PermissionSet::intersect把申请与宿主配置合并；应用无法超过宿主上限，执行结束后也会恢复原宿主权限。1.1.7 新增的 GUI、剪贴板、文件对话框、通知、托盘、外部地址和全局快捷键也分别相交。沙箱宿主即使载入声明了全权限且重新计算过校验和的 YXB，仍保持沙箱。

每次执行还受ExecutionBudget约束，默认限制一百万执行步、256 层法调用和单集合十万项。宿主可以设置config.budget；越界错误会明确指出max_steps、max_call_depth或max_collection_elements，便于判断是提高预算还是修复无穷循环、无界递归或数据增长。

use yanxu::permissions::PermissionSet;

let mut config = EngineConfig::sandboxed(Backend::Bytecode);
config.permissions = PermissionSet::sandboxed()
    .allow_file("./data")
    .allow_network("api.example.com")
    .allow_tcp_listen("127.0.0.1")
    .allow_udp_bind("127.0.0.1")
    .allow_environment("YANXU_PROFILE");
config.budget = yanxu::budget::ExecutionBudget::new(200_000, 128, 20_000);

包权限与 CLI 策略

包清单使用相对包根目录的文件范围：

[权限]
文件 = ["data", "src"]
网络 = ["api.example.com"]
TCP监听 = ["127.0.0.1"]
UDP绑定 = ["127.0.0.1"]
环境 = ["YANXU_PROFILE"]
进程 = false

yanxu 包 运行 [路径] [-- 参数...]按清单权限执行入口。为兼容 0.7 及更早脚本，直接执行yanxu 文卷.yx仍是显式不受限模式；运行来源不可信的程序时应使用包运行或嵌入沙箱。模块文件、文件标准库、网络与绑定能力、环境变量在树解释器与 VM 中执行相同权限判定。DNS 后的回环、私网和链路本地目标必须额外以真实 IP 精确授权。

C ABI

最小 C ABI 提供yanxu_engine_new、yanxu_engine_new_unrestricted、yanxu_engine_run、yanxu_engine_free和yanxu_string_free。执行结果是 schema 1 的 UTF-8 JSON；1.1.4 对字节返回增加可空value_bytes数列。调用方负责释放返回字符串，默认构造函数始终使用沙箱。

WASI

yanxu::wasm::run_utf8提供无文件、网络、环境或进程权限的字节码入口。可用下列命令检查 WASI 构建：

rustup target add wasm32-wasip1
cargo check --target wasm32-wasip1 --lib

纯计算和标准纯函数可以直接运行；不可用的宿主能力会返回“未获…权限”错误，不会静默跳过。