# process 进程库

## 功能

process(program) 创建命令构建器，支持参数、环境变量、工作目录、stdio 配置、同步执行和子进程句柄操作。

## API 列表

| API | 说明 |
| ------ | ------ |
| [process.arg](/zh-hans/docs/process/arg) | 追加一个命令行参数。 |
| [process.args](/zh-hans/docs/process/args) | 批量追加命令行参数。 |
| [process.env](/zh-hans/docs/process/env) | 设置一个子进程环境变量。 |
| [process.envs](/zh-hans/docs/process/envs) | 批量设置子进程环境变量。 |
| [process.current_dir](/zh-hans/docs/process/current_dir) | 设置子进程工作目录。 |
| [process.stdin](/zh-hans/docs/process/stdin) | 设置要写入子进程标准输入的文本。 |
| [process.inherit_stdio](/zh-hans/docs/process/inherit_stdio) | 让子进程继承当前进程 stdio。 |
| [process.null_stdio](/zh-hans/docs/process/null_stdio) | 丢弃子进程 stdio。 |
| [process.window_hidden](/zh-hans/docs/process/window_hidden) | Windows 下隐藏 console 子进程窗口。 |
| [process.pipe_limit](/zh-hans/docs/process/pipe_limit) | 设置当前 Process 对象的 stdout/stderr 未读缓冲上限。 |
| [process.env_clear](/zh-hans/docs/process/env_clear) | 启动子进程前清空继承环境变量。 |
| [process.env_remove](/zh-hans/docs/process/env_remove) | 从已配置环境变量中删除一个键。 |
| [process.get_args](/zh-hans/docs/process/get_args) | 读取当前构建器已配置的参数数组。 |
| [process.get_current_dir](/zh-hans/docs/process/get_current_dir) | 读取当前构建器工作目录配置。 |
| [process.get_envs](/zh-hans/docs/process/get_envs) | 读取当前构建器环境变量配置。 |
| [process.get_program](/zh-hans/docs/process/get_program) | 读取当前构建器程序路径。 |
| [process.status](/zh-hans/docs/process/status) | 同步执行命令并返回退出码。 |
| [process.output](/zh-hans/docs/process/output) | 同步执行命令并返回输出对象。 |
| [process.child](/zh-hans/docs/process/child) | 启动子进程并把句柄保存在当前 Process 对象中。 |
| [process.pid](/zh-hans/docs/process/pid) | 读取已启动子进程 PID。 |
| [process.kill](/zh-hans/docs/process/kill) | 终止已启动子进程。 |
| [process.suspend](/zh-hans/docs/process/suspend) | Windows 下暂停已启动子进程及其子进程树。 |
| [process.resume](/zh-hans/docs/process/resume) | Windows 下恢复已暂停子进程及其子进程树。 |
| [process.wait](/zh-hans/docs/process/wait) | 等待已启动子进程退出。 |
| [process.try_wait](/zh-hans/docs/process/try_wait) | 非阻塞检查已启动子进程是否退出。 |
| [process.stdout](/zh-hans/docs/process/stdout) | 读取已启动子进程 stdout 管道状态。 |
| [process.stdout_read](/zh-hans/docs/process/stdout_read) | 读取已启动子进程 stdout 当前可用文本。 |
| [process.stdout_read_lines](/zh-hans/docs/process/stdout_read_lines) | 按行读取已启动子进程 stdout 当前可用文本。 |
| [process.stderr_read](/zh-hans/docs/process/stderr_read) | 读取已启动子进程 stderr 当前可用文本。 |
| [process.stderr_read_lines](/zh-hans/docs/process/stderr_read_lines) | 按行读取已启动子进程 stderr 当前可用文本。 |
| [process.child_running](/zh-hans/docs/process/child_running) | 判断当前 Process 对象是否保存子进程句柄。 |

## 示例

```bt
ret = process('cmd').args(['/C', 'echo BT']).output()
result = ret.stdout.trim()

// 输出：BT
print result
```

## 注意事项

- 示例以 Windows cmd 为例；Linux/macOS 可使用 sh -c。
- status、output、wait 会阻塞当前流程，常驻服务中应谨慎使用。
- Web 请求上下文中拒绝 status、output、child、wait，避免同步等待外部进程或派生长期子进程；完整规则见：[Web 阻塞 API 策略](/zh-hans/docs/web/io-policy)。
- 子进程会继承 BT 运行期环境变量 overlay；如果当前 Process 对象通过 env/envs 设置了同名变量，则以 Process 对象的显式配置为准。
- 默认非 inherit_stdio() 场景不会继承父进程 stdin；未调用 stdin(text) 时子进程会收到关闭的 stdin。
- Windows 下默认非 inherit_stdio() 场景会隐藏 console 子进程窗口；需要显式交互控制台时调用 inherit_stdio()。
- child() 默认打开 stdout/stderr 管道；inherit_stdio() 或 null_stdio() 会关闭脚本侧管道读取能力。
- 管道读取采用后台线程和有界未读缓冲，默认 BT_PROCESS_PIPE_LIMIT 为 1048576 字节，BT_PROCESS_PIPE_READ_CHUNK 为 8192 字节，BT_PROCESS_PIPE_TIMEOUT_MS 为 100 毫秒；单个 Process 可用 pipe_limit(bytes) 覆盖。
- 超过 BT_PROCESS_PIPE_LIMIT 或 pipe_limit(bytes) 会返回运行时错误；未启动子进程、无对应管道、超时内无数据或管道已读完时返回 empty。
- Process 对象最后释放时会终止仍在运行的托管子进程；Windows 下 kill() 和释放清理会尽量递归终止子进程树。
- suspend()/resume() 面向 Windows 桌面批处理场景，通过线程级暂停和恢复控制子进程树；Linux/macOS 暂不支持。