host_files

[能力: host_files]

本组工具帮你看 **设备文件系统的具体内容**：哪些文件大、哪些目录在涨、单个文件的 size / mtime / mode / owner。

> **批量协议**：每个工具的 `paths` 都是 **数组**（1..16 条）。**一定一次给多个相关 path** —— 单 path 多次调用是反模式，浪费 LLM 轮次。返回 `results: [{path, ...data, error?}]` 与 `paths` 同序，per-path 失败不影响其他成功项（partial success）。还会顺手返回 `success_count / error_count` 让你一眼看出整体情况。

## 调用规则

**找最大的 N 个文件（一次多个起点）**：

```
host_find_large_files(
  device_id=<num>,
  paths=["/var/log", "/var/cache", "/opt"],   # 一次 3 个候选大目录
  top_n=10,
)
```

- `paths` 必填，1..16 条，**优先一次问 3..8 个**
- top_n 默认 20，按 size 降序，每条带 `path / size_bytes / size_human / mtime / owner`
- 默认排除 `/proc /sys /dev /run`（虚拟文件系统）
- 返回 `results[i] = {path, scanned_path, files[], error?}` 与 paths 同序

**看哪些目录在涨（一次多个根）**：

```
host_du_summary(
  device_id=<num>,
  paths=["/", "/var", "/var/log", "/opt", "/home", "/tmp"],   # 一次 6 个常见路径
  depth=1,
)
```

- depth 默认 1：每个 path 只看一层子目录，下钻一次问一层
- 不要一上来 `depth=10` —— 慢且 LLM 看不过来
- 返回 `results[i] = {path, subpaths[], total_size_bytes, total_size_human, error?}`

**stat 多个具体文件 / 目录**：

```
host_stat_file(
  device_id=<num>,
  paths=["/var/log/messages", "/var/log/syslog", "/var/cache/apt/archives"],
)
```

- 单点查询，最便宜，**一次给一组相关 path**
- 返回 `results[i] = {path, type, size_bytes, size_human, mtime, atime, mode, owner, group, error?}`
- `type ∈ {file, dir, symlink}`

## 协作范式

**用户问"磁盘满了排查一下"** —— 推荐流程（注意每步都用 batch）：

1. `query_promql` 看 `node_filesystem_used_bytes / node_filesystem_size_bytes` 趋势，确认设备 + 挂载点
2. 拿到 device_id 后 **一次** `host_du_summary(device_id, paths=["/", "/var", "/opt", "/home", "/tmp"], depth=1)` 找全局占用 top
3. 看到 `/var` 占大头 → **一次** `host_du_summary(device_id, paths=["/var/log", "/var/cache", "/var/lib"], depth=1)` 下钻
4. 看到 `/var/log` 占满 → `host_find_large_files(device_id, paths=["/var/log"], top_n=10)` 找具体文件
5. 输出给用户：分层下钻路径 + 最终文件列表 + 建议（清理 / 轮转 / 扩容）

**用户问"node-01 上有哪些大文件"** —— 一步 batch：

```
host_find_large_files(device_id=1, paths=["/", "/var", "/opt", "/home"], top_n=20)
```

直接拿到 4 个根的对比，简短回答。

## 反模式（不要做）

- **不要单 path 多次调用** —— 这是 #1 反模式：
  ```
  ✗ host_du_summary(device_id, paths=["/"])
  ✗ host_du_summary(device_id, paths=["/var"])
  ✗ host_du_summary(device_id, paths=["/opt"])
  ✗ host_du_summary(device_id, paths=["/home"])
  ```
  上面 4 轮浪费 4 倍 token，应该并成一次：
  ```
  ✓ host_du_summary(device_id, paths=["/", "/var", "/opt", "/home"])
  ```
- 不要写文件 / 删文件 —— 本组都是 read class，没有写权限工具
- 不要假设 path 存在 —— 直接放进 `paths`，失败的会进 `results[i].error`，不影响其他成功项
- 不要在敏感路径调用（`/proc /sys /dev /run /etc/shadow /root/.ssh /home/<user>/.ssh /root/.gnupg` 等）—— 这些命中沙箱 deny prefix，仅这条 path 进 error，其他正常返回
- 不要在 `/proc /sys` 跑 `du` —— 永远跑不完（虽然沙箱已经拒，这条提醒 LLM 别尝试）
- 不要超 16 个 path —— maxItems=16 是 hard limit，超过工具会拒绝整批

## 看到 results 含 error 项怎么办

- 看 `success_count / error_count` 摘要先判断整体
- 失败项的 `path` + `error` 字符串会告诉你原因（sandbox / 找不到 / find 错误等）
- **不要重试同一条失败 path** —— sandbox reject 一定是配置问题，找不到的文件再问也是找不到
- 直接基于成功项的数据答复，**附带说明**哪些 path 没拿到 + 原因