# WASI 扩展的原生后台进程

## 功能

Rust SDK 的可选 `host-process` feature 向扩展实现提供
`bt_extension_sdk::host_process::request(json)`。它使用参数数组启动原生程序并立即
返回，轮询返回有界输出和状态，不等待进程完成。此能力要求本次更新后的 BT 宿主；
旧版 1.1.4 二进制不提供该导入。

这是 WASI 沙箱之外的原生进程权限，只应交给可信扩展和可执行程序。路径声明校验
列出的文件，但不能约束原生程序的任意行为。FFmpeg 由视频扩展选择，宿主不包含
媒体专用逻辑。

## 语法

manifest 声明 `"permissions": ["process", "fs_read", "fs_write"]`。
SDK 导入 `bts_host.process_request(i32, i32, i32, i32) -> i32`，请求为 UTF-8 JSON，
响应信封为 `{ok: value}` 或 `{error: message}`。SDK 解包为
`Result<String, String>`。这是扩展作者接口；BT 应用通常使用
[视频任务](/zh-hans/docs/extensions/video)。

## 请求字段

| 字段 | 类型 | 必填 | 默认值 | 范围 / 含义 |
|---|---|---|---|---|
| `op` | String | 是 | 无 | `spawn`、`poll`、`cancel`、`close`。 |
| `program` | String | spawn 时 | 无 | 非空可执行文件路径或 PATH 名称，不隐式调用 shell。 |
| `args` | Array[String] | spawn 时 | 无 | 最多 256 个参数；整个请求 JSON 最多 64 KiB。 |
| `timeout_ms` | Int | 否 | 60000 | 1–300000；包含启动时间，由 worker 自动执行超时。 |
| `read_paths` | Array[String] | 否 | [] | 已存在的项目相对路径，要求 `fs_read`。 |
| `write_paths` | Array[String] | 否 | [] | 项目相对输出，父目录已存在，要求 `fs_write`。 |
| `cleanup_paths` | Array[String] | 否 | [] | 调用者以 create-new 方式预留的自有空普通文件；失败、取消或超时且进程回收后删除，要求 `fs_write`。 |
| `id` | Int | 非 spawn 时 | 无 | 当前扩展实例中存在的正整数任务 ID。 |
| `discard_output` | Bool | 否 | false | 仅 close：原子安排删除自有 `cleanup_paths`，包括 worker 刚刚成功的情况；普通 close 保留成功输出。 |

所列路径拒绝父目录跳转和规范化后超出项目根的路径。可执行程序的工作目录是项目根。
原生执行保留操作系统账号权限；BT 进程本身也必须允许进程能力及请求的文件系统能力。

## 返回值

`spawn` 返回 `{id: Int}`。`close` 立即移除句柄并返回 `{closed: true}`；取消和进程
回收继续在 worker 内完成。poll 和 cancel 返回以下字段：

| 字段 | 类型 | 必有 | 默认值 | 含义 / 范围 |
|---|---|---|---|---|
| `state` | String | 是 | 无 | `queued`、`running`、`succeeded`、`failed`、`cancelled`、`timed_out`。 |
| `stdout`、`stderr` | String | 是 | 空串 | 每个流最后 1 MiB；非法 UTF-8 使用替换字符。 |
| `stdout_truncated`、`stderr_truncated` | Bool | 是 | false | 先前字节超出保留尾部容量。 |
| `exit_code` | Int 或 JSON null | 是 | null | 可用时为进程退出码；运行中或无数字退出码时为 null。 |
| `elapsed_ms` | Int | 是 | 0 | 提交后经过的毫秒数，终态冻结。 |

## BT 示例

```bt
source = video('@/clip.mp4', {})
job = source.frame('@/frame.png', 0.5)
state = job.status()
// 输出：排队、探测、运行或终态的任务状态
print state
job.cancel()
job.close()
source.close()
```

## 资源与平台注意事项

每实例最多四个活动进程和 32 个保留句柄；整个宿主进程跨实例最多 32 个活动进程。
容量满时立即拒绝新任务。关闭运行中的句柄后，直到 worker 回收进程才释放活动额度，
不存在无界等待队列。每个输出流最多保留 1 MiB；WASM SDK 复用 16 MiB 响应缓冲，
以容纳 JSON 转义。关闭所有句柄后释放对应输出存储。

Windows 使用隐藏子进程及关闭即终止的独立 Job Object；Unix 在正常取消时使用独立
进程组。原生程序不得故意逃离其进程组或 Job。Unix 宿主异常终止时不保证后代清理。
本地验收覆盖 Windows x64；Unix 代码需要目标平台验证。销毁 Store 会请求取消其
子进程。成功输出在 close 后保留。

Web 请求脚本已有 BT 有界 blocking pool 隔离。媒体命令运行在专用有界 worker 内；
应用每个请求只轮询一次，不在请求内 sleep 等待。无关 VM 指令不增加工作。