# context.native

当 Node.js 代码需要调用原生工具时，把可执行文件放进插件包，再使用 `execute()` 运行。清单需要声明 `native.execute`，并在 `hostPlatforms` 中指定工具支持的平台。

## execute()

运行工具并读取输出。路径相对插件目录，指向一个有执行权限的文件。

```ts
context.native.execute(path: string, args?: string[]): Promise<{ stdout: string; stderr: string }>
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `path` | `string` | 插件包内的可执行文件路径，例如 `bin/tool`。 |
| `args` | `string[]` | 命令行参数，默认 `[]`。每个数组项都是一个参数，不需要 shell 引号。 |

### 返回值

Promise 解析为 `{ stdout, stderr }`，两个属性都是字符串。工具运行时间最多 6 秒，stdout 和 stderr 每路输出最多 16 KiB。非零退出码会使 Promise 拒绝。最多传入 32 个参数，单项最多 4096 个字符，总长度最多 16384 个字符。

Windows 程序使用 `.exe` 包内相对路径，以隐藏窗口启动。宿主仅传递 `SystemRoot`、`WINDIR`、`TEMP`/`TMP`、用户配置目录及系统目录 `PATH` 等运行必需变量；不会继承宿主的任意环境变量。插件仍须自行提供对应平台的工具与依赖，宿主不根据插件 ID 查找、构建或安装工具。

### 示例

```js
const { stdout } = await context.native.execute("bin/tool", ["--name", args.name]);
return { result: stdout.trim() };
```