agentool 0.2.0

# 文件系统（`fs`）

中文 | [English](README.md)

[← 返回仓库说明](../../README.zh.md)

> **路径与沙箱**
>
> 所有 `fs` 工具共享同一个 `FsContext`：
>
> | 模式 | 说明 |
> |------|------|
> | `FsContext::new(root, false)`（默认） | **沙箱模式**：相对路径相对于工作区根拼接；解析后的真实路径必须落在该根下（含根本身），否则返回 `INVALID_PATH` |
> | `FsContext::new(root, true)` | **放宽模式**：相对路径同样相对于工作区根拼接，与沙箱一致；**不**校验解析结果是否仍在根内，因此绝对路径或经 `..` 归一化后的路径可以落在根外 |
>
> `root` 为 `None` 时在构造 `FsContext` 的瞬间取进程当前目录并 canonicalize 作为工作区根。路径在解析前会做 `.` / `..` 词法归一化。

---

## `file_read`

读取文本文件内容，支持按行分页。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | `string` | 是 | 文件路径（须为普通文件） |
| `offset` | `integer` | 否 | 起始行号（从 1 开始，须 ≥ 1） |
| `limit` | `integer` | 否 | 读取行数上限（须为非负整数） |

`offset` 和 `limit` 只接受 JSON 整数，不接受浮点数。

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `content` | `string` | 文件内容，保留原始换行符（CRLF 不归一化）及末尾换行 |
| `total_lines` | `number` | 文件逻辑行数 |

---

## `file_write`

写入文件；文件不存在时创建，已存在则覆盖。自动递归创建不存在的父目录。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | `string` | 是 | 文件路径 |
| `content` | `string` | 是 | 写入内容 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `path` | `string` | 文件的绝对路径 |

---

## `file_edit`

精确替换文件中的某段文本。`old_text` 必须在文件中**唯一**出现，且不得为空字符串。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | `string` | 是 | 文件路径 |
| `old_text` | `string` | 是 | 待替换的原始文本（须唯一） |
| `new_text` | `string` | 是 | 替换后的新文本 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `path` | `string` | 文件的绝对路径 |

---

## `directory_create`

创建目录，支持递归创建多级目录。目录已存在时不报错。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | `string` | 是 | 目录路径 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `path` | `string` | 目录的绝对路径 |

---

## `directory_list`

列出目录中的文件和子目录，结果按名称升序排序。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | `string` | 是 | 目录路径 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `entries` | `Entry[]` | 条目列表（按 `name` 升序） |
| `entries[].name` | `string` | 文件或目录名 |
| `entries[].type` | `"file" \| "directory"` | 类型 |
| `entries[].size` | `number` | 文件大小（字节），目录为 0 |

---

## `file_delete`

删除普通文件。若目标是目录，返回 `INVALID_PATH`。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | `string` | 是 | 文件路径 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `path` | `string` | 被删除文件的绝对路径 |

---

## `file_move`

移动或重命名普通文件。目标路径已存在时失败，自动创建目标路径的父目录。

跨卷移动时会自动回退为「复制 + 删除源」；若删除源失败，会尝试清除已创建的目标副本后返回错误，不留无主文件。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `source` | `string` | 是 | 源文件路径 |
| `destination` | `string` | 是 | 目标路径 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `source` | `string` | 源文件的绝对路径 |
| `destination` | `string` | 目标文件的绝对路径 |

---

## `file_copy`

复制普通文件。目标路径已存在时失败，自动创建目标路径的父目录。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `source` | `string` | 是 | 源文件路径 |
| `destination` | `string` | 是 | 目标路径 |

**返回**

| 字段 | 类型 | 说明 |
|------|------|------|
| `source` | `string` | 源文件的绝对路径 |
| `destination` | `string` | 目标文件的绝对路径 |

## 错误码

本模块工具可能返回的 `error.code` 如下（定义见 [`error.rs`](error.rs) 中的 `FsErrorCode`，另有 I/O 映射产生的系统相关码）。

| 错误码 | 说明 |
|--------|------|
| `FILE_NOT_FOUND` | 文件或目录不存在 |
| `PERMISSION_DENIED` | 无读写权限 |
| `FILE_ALREADY_EXISTS` | 目标路径已存在（如 `file_move` / `file_copy`） |
| `DIRECTORY_NOT_EMPTY` | 目录非空等 I/O 语义错误（映射自系统错误） |
| `PATTERN_NOT_FOUND` | `file_edit` 的 `old_text` 未找到 |
| `PATTERN_NOT_UNIQUE` | `file_edit` 的 `old_text` 匹配到多处 |
| `INVALID_PATH` | 路径为空、非法、目标类型不符（如对目录调用 `file_delete`）、超出沙箱，或其它归一化/解析失败 |