# 文件与端口转发

> 使用 v42 ls、stat、find、mkdir、rm、cp、sync 和 forward 在任意电脑上浏览、查看、搜索、创建、删除、复制和同步文件，或转发本地 TCP 端口。

`v42` 的所有文件命令均同时接受本机路径与 `<computer>:/绝对路径` 形式的远端路径（`<computer>` 为电脑 ID 或名称）。文件操作通过独立的 `file` 通道传输，不会拖慢正在使用的终端。

## 列出、查看与搜索文件

```sh
v42 ls [-a] [-l] <location>
v42 stat [--no-follow] <location>
v42 find <location> <query> [--limit <limit>]
```

- `ls <location>`：列出目录内容。文件夹排在前面，文件排在后面，按自然名称顺序排列；最多返回 10,000 个条目（超出时 `.data.truncated` 为 `true`）。
  - `-a`, `--all`：包含名称以 `.` 开头的隐藏条目。
  - `-l`, `--long`：将每个条目作为对象返回，包含 `name`、`kind`（`file`、`dir`、`symlink`、`other`）、`size` 和 `mtime_ms`。（如需查看权限 `mode`，请使用 `v42 stat --no-follow`。）
- `stat <location>`：查看单个文件或目录的元数据。
  - `--no-follow`：查看符号链接（symlink）本身而非其指向的目标，同时返回权限信息（`mode`）。
- `find <location> <query>`：在 `<location>` 下按文件名进行不区分大小写的子串搜索。自动跳过以 `.` 开头的条目和 `node_modules` 目录；匹配满 `--limit <limit>` 条（`1` 到 `200`，默认 `200`）、访问满 20,000 个条目或耗时满 2 秒时停止搜索，并在提前停止时标记 `truncated: true`。

## 创建与删除目录和文件

```sh
v42 mkdir [-p] <location>
v42 rm [-r] [--yes] <location>
```

- `mkdir <location>`：在本机或 `<computer>` 上创建目录。
  - `-p`, `--parents`：一并创建缺失的父目录，且在目录已存在时不报错。
- `rm <location>`：删除文件、符号链接或目录。删除符号链接时只删除链接本身，绝不删除其指向的目标。
  - `-r`, `--recursive`：递归删除目录及其内部的所有内容（必须配合 `--yes`）。未传 `--yes` 时不会删除任何内容，命令以 `confirmation_required`（退出码 `2`）失败，并在 `error.details` 中报告将删除多少个条目。
  - 文件系统根目录（`/`）、用户主目录（Home）以及主目录的上级父目录**始终被拒绝删除**。

## 复制与同步文件

```sh
v42 cp [-r] [--restart] <source> <destination>
v42 sync [--delete] [--restart] <source> <destination>
```

`<source>` 和 `<destination>` 可以任意组合本机路径与 `<computer>:/绝对路径`（本机到远端、远端到本机，或电脑 A 到电脑 B）。

- `cp`：复制文件或目录。
  - `-r`, `--recursive`：递归复制目录及其内容。如果 `<destination>` 是已存在的目录，则会在其中创建以源目录名命名的子目录。
  - `--restart`：丢弃该操作之前未完成的断点续传状态，从头重新复制。
- `sync`：将 `<source>` 目录的内容单向同步到 `<destination>` 目录。
  - 默认情况下，`<destination>` 中多出的条目会**保留**。
  - `--delete`：删除 `<destination>` 中不在 `<source>` 里的多余条目。只有在所有文件复制成功且复核源目录清单未发生变化后，才会逐项执行删除。
  - `--restart`：丢弃未完成的断点续传状态，从头重新同步。
  - 同一台机器上，目标与源相同、包含源或位于源之内时，`cp` 和 `sync` 会拒绝执行（`invalid_argument`）。路径比较不区分大小写；`v42` 通过某台电脑上的 Vibe42 登录时，本机路径与 `<这台电脑>:/路径` 视为同一台机器。

### 传输完整性与断点续传

文件传输采用分块与整文件双重 SHA-256 校验，先写入 `.part` 临时文件，校验通过后才原子提交为正式文件。如果传输中途中断，再次运行相同的 `cp` 或 `sync` 命令会自动从上次保存的偏移量继续传输。如果期间源文件发生了变化，命令会返回 `resume_source_changed`；此时可加上 `--restart` 从头复制。

## 端口转发（`v42 forward`）

```sh
v42 forward <computer>:<remote-port> [<local-addr>:]<local-port>
```

在本机监听一个 TCP 端口，并通过端到端加密通道将传入连接转发到 `<computer>` 的回环地址 `127.0.0.1:<remote-port>`：

```sh
v42 forward my-mac:3000 3000
v42 forward my-mac:5432 127.0.0.1:15432
v42 forward my-mac:3000 0
```

- 省略 `<local-addr>` 时，默认只绑定本机 `127.0.0.1`。绑定到非回环地址时会在 stderr 打印安全警告。
- 将 `<local-port>` 设为 `0` 时，由操作系统自动分配空闲端口，并在就绪后向 stderr 输出包含实际监听地址和端口的 `forward_listening` JSON。
- 最多同时支持 **64** 条并发 TCP 连接，并保留 TCP 半关闭语义。
- 按 `Ctrl+C`（`SIGINT`）或发送 `SIGTERM` 停止转发。连接经过 AP 中转时，转发流量计入 [Credits 与用量](/docs/account/credits-and-usage)。
