# 标签页、块与布局

> 通过 v42 layout、v42 tab 和 v42 block 在命令行查看与编排 Workspace 或电脑的标签页与块布局。

每个 Workspace 和每台电脑都有一份按用户独立保存的标签页（tab）与块（block）布局，与 Vibe42 桌面、Web 和手机 App 显示的布局完全一致（见[标签页、功能块与终端列表](/docs/terminal/windows-and-panes)）。通过 `v42 layout`、`v42 tab` 和 `v42 block` 所做的任何调整都会实时同步到已打开的 App 中。

## 选择所属容器（`--workspace` 或 `--computer`）

每条 `layout`、`tab` 和 `block` 命令都作用于一个容器布局：

- 传入 `--workspace <workspace>`（ID 或名称）操作某个 Workspace 的布局。
- 传入 `--computer <computer>`（ID 或名称）操作某台电脑的布局（承载不属于任何 Workspace 的终端）。

## 标签页与块的选择器

- **`<tab>`**：标签页 ID、从 1 开始的标签页位置编号（与 `v42 layout show` 和 `v42 tab list` 输出一致），或标签页标题。
- **`<block>`**：块 ID、`--tab` 内从 1 开始的块位置编号，或该块所显示的终端标识（`%N` 或 `@N`）。

## 查看布局（`v42 layout show`）

```sh
v42 layout show --workspace <workspace>
v42 layout show --computer <computer>
```

输出该布局下的全部标签页和块，并附带各个终端块的实时状态。标签页从 `1` 开始编号：你自己的标签页排在前面，随后是来自 Herdr 的标签页（`source: "herdr"`）。

返回的 `.data.state` 有三种状态：

- `ready`：服务端已有保存的布局。
- `uninitialized`：该 Workspace 或电脑从未在 App 中打开或保存过布局。第一次执行不依赖现有标签页或块 ID 的 CLI 改动（例如 `tab new`、`term new` 或 `block new --new-tab`）时，CLI 会像 App 首次打开它一样，根据容器内正在运行的终端初始化默认布局。
- `read_only`：已保存的布局数据未通过校验；命令会展示校验错误，且不会修改该布局。

### Herdr 标签页

当 Workspace 绑定了 Herdr（`source: "herdr"`）时，其中的 Herdr 标签页来自电脑上的 Herdr。Herdr 支持的布局改动（如关闭标签页、在其所属 Herdr workspace 内移动标签页顺序、切分或关闭终端 pane）会转发给 Herdr 执行；Herdr 不支持的操作（如将块设为浮动或添加非终端类型的块）会以错误码 `source_tab_unsupported` 失败。

### 自动均分与 `--no-balance`

默认情况下，当账号设置中的自动均分（**自动均分大小**）处于开启状态时，新增、移动、浮动、停靠或关闭块会自动重新均分所在分屏的尺寸比例。在 `term new`、`term close`、`block new`、`block close`、`block close-others`、`block move`、`block float` 或 `block dock` 中加上 `--no-balance`，即可在本次操作中保持原有分屏比例不变。

## 管理标签页（`v42 tab`）

```sh
v42 tab list <--workspace <ws> | --computer <c>>
v42 tab new <--workspace <ws> | --computer <c>> [--title <title>] [--index <index>]
v42 tab close <--workspace <ws> | --computer <c>> <tab> [--force]
v42 tab rename <--workspace <ws> | --computer <c>> <tab> [<title> | --reset]
v42 tab move <--workspace <ws> | --computer <c>> --index <index> <tab>
v42 tab arrange <--workspace <ws> | --computer <c>> <tab> <preset>
```

- `tab list`：列出布局中的所有标签页及其从 1 开始的位置、标题、来源和块数量。
- `tab new`：创建一个空标签页。`--title <title>` 设置自定义标题；`--index <index>` 指定从 1 开始的插入位置（省略时追加在末尾）。
- `tab close <tab>`：关闭标签页**以及它所显示的终端**（会先关闭电脑上的终端）。如果标签页内有任何非空闲（或状态为 `unknown`）的终端，必须传入 `--force`（否则返回 `terminal_busy`，退出码 `2`）。关闭 Herdr 标签页会关掉其中的 Herdr pane，总是需要 `--force`（否则返回 `confirmation_required`，退出码 `2`）；挂在其中的 Vibe42 终端与 App 中一样继续运行。
- `tab rename <tab> [<title>]`：重命名标签页，或传 `--reset` 恢复自动标题（取自第一个块的标题）。
- `tab move --index <index> <tab>`：将标签页移到从 1 开始的新位置（普通标签页为在整体布局中的位置；Herdr 标签页为在其所属 Herdr workspace 标签页中的位置）。
- `tab arrange <tab> <preset>`：用五种预设之一重新排列 `<tab>` 内的所有停靠块：
  - `columns`：左右并排的竖列
  - `rows`：上下堆叠的横行
  - `grid`：均匀二维网格
  - `main-side`：左侧大主块，右侧上下堆叠其余块
  - `main-stack`：顶部大主块，底部左右并排其余块

## 放置与管理块（`v42 block`）

### 打开新块（`v42 block new`）

```sh
v42 block new <kind> [<values>...] <--workspace <ws> | --computer <c>> [options]
```

在指定标签页（`--tab <tab>`，或用 `--new-tab` 在顶部新建标签页）中打开一个块。如果要打开的资源已经存在于目标标签页中（使用 `--new-tab` 时为已存在于整个布局中），`block new` 会返回 `existing: true`，而不会重复打开第二个块。

| `<kind>` | `<values>...` | 打开的内容 |
|---|---|---|
| `terminal` | `[<%N\|@N>]` | 显示容器所属电脑上的一个已有终端；省略时在该电脑（Workspace 布局下为 Workspace 目录）中新建一个终端并放置 |
| `agent` | `[<launcher-id>]` | 使用 `v42 agents list` 中的 `<launcher-id>`（默认取第一个）启动新 Agent 终端并放置 |
| `folder` | `<path>` | 以电脑上 `<path>` 为根的目录树块 |
| `file` | `<path>` | 电脑上 `<path>` 文件的预览块 |
| `memo` | `[<memo-id>]` | Workspace 便签块（仅限 `--workspace` 布局） |
| `port` | `<port>` | 电脑上 `<port>` 端口的内置预览块 |
| `desktop` | *（无）* | 电脑的远程桌面块（可选传 `v42 desktop windows` 中的 `--window <window-id>` 或 `--display <display-id>`） |
| `folder-follow` | *（无）* | 跟随当前焦点终端工作目录的目录树块 |

`block new` 的放置选项：

- `--tab <tab>`：要在其中打开块的标签页（ID、从 1 开始的位置或标题）。
- `--new-tab`：在布局顶部新建一个标签页并在其中打开该块。
- `--beside <beside>`：在该标签页的指定块旁边打开。
- `--side <left|right|up|down|auto>`：在 `--beside` 块的哪一侧打开（`auto` 默认为 `right`）。
- `--end`：放在标签页最后一个块之后（未传 `--beside` 和 `--float` 时的默认行为）。
- `--float <x,y,width,height>`：以占标签页区域的百分比小数（`0` 到 `1`）作为浮动块打开。
- `--no-balance`：不重新均分所在分屏的比例。

### 移动、交换与调整停靠块大小

```sh
v42 block move <--workspace <ws> | --computer <c>> <block> [--tab <tab>] [--to-tab <tab> | --new-tab] [--beside <block>] [--side <side>] [--end] [--no-balance]
v42 block swap <--workspace <ws> | --computer <c>> [--tab <tab>] <a> <b>
v42 block resize <--workspace <ws> | --computer <c>> [--tab <tab>] --side <left|right|up|down> --delta <delta> <block>
v42 block equalize <--workspace <ws> | --computer <c>> [--tab <tab>] <block>
v42 block rename <--workspace <ws> | --computer <c>> [--tab <tab>] <block> [<title> | --reset]
```

- `block move`：将 `<block>` 移到同一标签页的另一位置、移入 `--to-tab <tab>`，或用 `--new-tab` 移到紧跟当前标签页之后的新标签页。
- `block swap`：交换块 `<a>` 和块 `<b>` 的位置。
- `block resize`：将 `<block>` 在 `--side <left|right|up|down>` 方向上的分隔边框移动 `--delta <delta>`（占最近一层包含该方向邻块的分屏比例，正数扩大如 `0.1`，负数缩小如 `-0.1`）。
- `block equalize`：让 `<block>` 所在分屏内的所有块均分尺寸。
- `block rename`：为 `<block>` 设置自定义标题，或传 `--reset` 恢复自动标题。

### 浮动与停靠块

```sh
v42 block float <--workspace <ws> | --computer <c>> [--tab <tab>] [--rect <x,y,w,h>] [--no-balance] <block>
v42 block dock <--workspace <ws> | --computer <c>> [--tab <tab>] [--beside <block>] [--side <side>] [--end] [--no-balance] <block>
v42 block minimize <--workspace <ws> | --computer <c>> [--tab <tab>] [--restore] <block>
v42 block rect <--workspace <ws> | --computer <c>> [--tab <tab>] <block> <x,y,w,h>
```

- `block float`：将 `<block>` 转为浮动块（默认位置与尺寸 `0.2,0.15,0.6,0.7`）。
- `block dock`：将浮动块停靠回标签页的分屏树中（默认 `--end`，或指定 `--beside <block> --side <side>`）。
- `block minimize`：将浮动块最小化收起，或传 `--restore` 恢复展开。
- `block rect`：将浮动块移动并缩放到 `<x,y,width,height>`（`0` 到 `1` 的标签页区域比例）。

### 关闭块

```sh
v42 block close <--workspace <ws> | --computer <c>> [--tab <tab>] [--force] [--no-balance] <block>
v42 block close-others <--workspace <ws> | --computer <c>> [--tab <tab>] [--force] [--no-balance] <block>
```

- `block close`：关闭 `<block>`。对于非终端块（`file`、`folder`、`memo`、`port`、`desktop`、`folder-follow`），仅将其从标签页移除。对于**终端块**，会像 `v42 term close` 一样先关闭电脑上的终端，再移除该布局中所有显示该终端的块；如果终端正忙或状态为 `unknown`，未传 `--force` 时命令会以 `terminal_busy`（退出码 `2`）失败。
- `block close-others`：关闭 `<block>` 所在标签页内的所有其他块（其中的终端也会一并关闭；若有忙碌终端同样需要 `--force`）。在 Herdr 标签页中只关掉其他 Herdr pane，挂在其中的 Vibe42 终端与 App 中一样继续运行；原生 Herdr pane 视为 `unknown`，因此需要 `--force`。
