# os 工具参考

## 模板（工具）

### 阅读方式

- 工具函数定义是参数/返回的权威来源；本手册只补充使用指导。

### 单工具字段顺序

1. 用途
2. 调用签名
3. 参数（仅在需要补充用法指导时摘要说明）
4. 前置条件
5. 成功信号
6. 失败/错误
7. 可直接执行示例
8. 常见误用

## 工具列表

### 1. shell_cmd

执行 Shell 命令。

**参数：**

- `command`（必需）：要执行的命令
- `shell`（可选）：执行时使用的 shell（默认：Linux/macOS 为 `bash`，Windows 为 `cmd.exe`）
- `scrollbackLines`（可选）：滚动回看里保留的最近输出行数
- `timeoutSeconds`（可选）：超时秒数；超时后转为守护进程追踪

**Windows 提示：**

- 使用 `shell` 选择外层执行环境：`cmd.exe`、`powershell.exe` 或 `pwsh`
- `command` 必须是所选 shell 的原生命令；不要在另一个 shell 命令里嵌套 `cmd /c` 或 `powershell -Command`
- 默认 `cmd.exe` 路径下，优先使用不带空格的正斜杠路径，如 `D:/path/to/file`
- 只有非常明显的混套模式可能触发警告；工具不会替你改写混合 shell 语法

**返回：**

```yaml
status: ok|error
command: <执行的命令>
exit_code: <退出码>
stdout: <标准输出>
stderr: <标准错误>
executed_at: <执行时间戳>
```

### 2. stop_daemon

停止守护进程。

**参数：**

- `pid`（必需）：守护进程 PID（数字）
- `entire_pg`（可选）：是否停止整个进程组/进程树（默认：`true`；Windows 上会停止被追踪的 shell 进程及其子进程）

**返回：**

```yaml
status: ok|error
pid: <守护进程 PID>
stopped_at: <停止时间戳>
```

**错误：**

- `DAEMON_NOT_FOUND`：守护进程不存在
- `DAEMON_NOT_RUNNING`：守护进程未运行

### 3. get_daemon_output

获取守护进程输出。

**参数：**

- `pid`（必需）：守护进程 PID（数字）
- `stdout`（可选）：是否包含 stdout 输出（默认 `true`）
- `stderr`（可选）：是否包含 stderr 输出（默认 `true`）

**返回：**

```yaml
stdout: <请求时返回 stdout 输出>
stderr: <请求时返回 stderr 输出>
```

### 4. env_get

获取环境变量。

**参数：**

- `key`（必需）：环境变量名称

**返回：**

- 已设置：直接返回环境变量值
- 未设置：返回 `(unset)`

### 5. env_set

设置环境变量。

**参数：**

- `key`（必需）：环境变量名称
- `value`（必需）：环境变量值

**返回：**

```yaml
ok: <环境变量名称>
prev: <之前的值或 (unset)>
next: <新的值>
```

### 6. env_unset

删除环境变量。

**参数：**

- `key`（必需）：环境变量名称

**返回：**

```yaml
ok: <环境变量名称>
prev: <之前的值或 (unset)>
next: (unset)
```

## 使用示例

### 执行 Shell 命令

```typescript
shell_cmd({
  command: 'ls -la /home/user',
  timeoutSeconds: 10,
});
```

### 停止守护进程

```typescript
stop_daemon({
  pid: 12345,
});

// 显式要求停止整个进程组/进程树
stop_daemon({
  pid: 12345,
  entire_pg: true,
});
```

### 获取守护进程输出

```typescript
get_daemon_output({
  pid: 12345,
});

get_daemon_output({
  pid: 12345,
  stdout: true,
  stderr: false,
});
```

### 获取环境变量

```typescript
env_get({
  key: 'PATH',
});
```

### 设置环境变量

```typescript
env_set({
  key: 'MY_VAR',
  value: 'hello',
});
```

### 删除环境变量

```typescript
env_unset({
  key: 'MY_VAR',
});
```

## YAML 输出契约

所有工具的输出都使用 YAML 格式，便于程序化处理：

- `status`：操作状态，`ok` 表示成功，`error` 表示失败
- 其他字段：具体操作的附加信息

错误时返回：

```yaml
status: error
error_code: <错误代码>
message: <错误消息>
```
