# 终端与 Agent

> 使用 v42 term、attach、ws enter 和 agents 创建、列出、查看、附着、发送按键或文本、读取屏幕、等待状态、监听变化、重命名、移动和关闭终端。

`term`、`attach`、`ws enter` 和 `agents` 命令让脚本和 coding agent 能够在当前团队的任意在线电脑上创建和控制终端。每个终端都是该电脑上真实持久化运行的窗口，与 Vibe42 App 实时共享。

## 目标标识语法（Target）

操作现有终端的命令接收 `<computer>`（ID 或名称）和 `<target>`：

- `@N`：窗口 ID（例如 `@12`）。针对单个 pane 的命令（`term send`、`term read`、`term wait`）在收到 `@N` 时作用于该窗口当前的活跃 pane。
- `%N`：pane ID（例如 `%5`）。
- `<session>:@N`：`v42 term new` 在 `.data.target` 中返回的完整窗口标识。
- `<session>`：tmux 会话名称（`v42 term attach` 和 `v42 attach` 支持直接附着到整个会话）。

## 列出与查看终端

```sh
v42 term list [<computer>] [--workspace <workspace>] [--idle] [--busy]
v42 term status <computer> <target>
```

- `term list`：列出整个团队所有电脑（或指定 `<computer>`）上的终端。不指定电脑时，离线或连不上的电脑在 `computers` 下报告其状态；指定了电脑（或 Workspace）时，这台电脑离线或连不上会直接报错（如 `computer_offline`），而不是返回空列表。
  - `--workspace <workspace>`：只列出属于该 Workspace（ID 或名称）的终端。
  - `--idle`：只列出空闲（idle）终端。
  - `--busy`：只列出非空闲终端（包括状态为 `unknown` 的终端）。
- `term status <computer> <target>`：查看单个终端窗口、Agent 状态和空闲状态；窗口有多个 pane 时，另在 `panes` 中逐个列出。

### 空闲判定规则（Idle rule）

每个 pane 的 `foreground` 状态为以下三者之一：`idle`（shell 停在提示符处，前台没有程序运行）、`busy`（前台有程序运行）或 `unknown`（电脑是 Windows 或 Vibe42 版本较旧，或终端是在更新前创建的，无法上报前台状态）。

一个终端只有在同时满足以下两个条件时才判定为 **idle（空闲）**：

1. 每个 pane 的 `foreground` 都是 `idle`；且
2. 它的 [Agent 状态](/docs/agents/agent-status)（如果有）为 `idle` 或 `done`（没有处于 `working`、`blocked` 或 `error` 的 Agent）。

当电脑无法判断状态（`unknown`）时，该终端一律按 **busy（忙碌）** 处理。除非显式传入 `--force`，否则 `term close`、`block close` 和 `tab close` 绝不会关闭忙碌或 `unknown` 的终端。

## 创建终端

```sh
v42 term new <computer> [options]
```

在 `<computer>` 上创建终端，可选在其中启动 Agent 或命令，并把它放进所属 Workspace（`--workspace`）或该电脑的布局中。

| 选项 | 说明 |
|---|---|
| `--workspace <workspace>` | 终端归属的 Workspace（ID 或名称）；工作目录取该 Workspace 目录（开启[终端隔离](/docs/workspaces/terminal-isolation)时为新建的隔离副本）。不能与 `--cwd` 同时使用。 |
| `--cwd <cwd>` | 电脑上的起始工作目录（未传 `--workspace` 时使用）。 |
| `--name <name>` | 终端窗口标题。 |
| `--launcher <launcher>` | 启动 `v42 agents list` 中的指定 Agent 启动器 ID；未传 `--name` 时用启动器的显示名称命名终端。传 `terminal` 则打开普通终端。 |
| `--agent <agent>` | 内置 Agent 目录 ID（`claude-code`、`codex`、`omp`、`pi`、`opencode`、`grok-build`、`devin`、`antigravity`、`cursor` 等）；未传 `--command` 时运行该 Agent 的默认命令。 |
| `--command <command>` | 在新终端中启动的单行命令（在交互式登录 shell 中运行）。 |
| `--tab <tab>` | 在指定标签页（ID、从 1 开始的位置或标题）中打开终端；未传 `--beside` 或 `--float` 时排在该标签页最后一个块之后。 |
| `--beside <beside>` | 在指定块旁边打开终端（块 ID、终端 `%N` / `@N` 或 `--tab` 内从 1 开始的位置）。 |
| `--side <side>` | 在 `--beside` 块的哪一侧打开：`left`、`right`、`up`、`down` 或 `auto`（`auto` 默认为 `right`）。 |
| `--float` | 在 `--tab`（或第一个标签页）中作为浮动块打开终端。 |
| `--no-layout` | 不把终端放进任何布局（之后打开该布局的 App 会自动为它单独生成一个标签页）。 |
| `--no-balance` | 放置终端后不自动重新均分所在分屏的比例。 |
| `--attach` | 创建终端后立即附着上去。 |
| `--stdio` | 配合 `--attach` 使用，为程序转发原始字节流而不接管本地终端界面。 |

### `term new`、`term close` 与 `term move` 对布局的影响

- **`term new`**：不传放置选项时，新终端会在所属 Workspace（或电脑）布局的顶部新建一个标签页打开；如果更新布局失败，终端本身仍会保留，`.data.layout` 会报告 `placed: false` 及错误原因。传入 `--tab`、`--beside` 或 `--float` 时，会先校验目标位置，目标无效时不会创建终端。如果某个打开的 App 已经为新终端创建了块，则会把那个块移到指定位置，而不会重复打开两次。
- **`term close`**：等待电脑确认终端已关闭后，将该终端在所属 Workspace 或电脑布局中的所有块一并移除。
- **`term move`**：把窗口移到同一台电脑的另一个 Workspace（或用 `--none` 移出所有 Workspace），从原布局中移除它的块，并在目标布局顶部新建标签页打开它（除非目标布局中已经显示了该终端）。

## 附着到终端

```sh
v42 term attach <computer> <target> [--stdio]
v42 attach <computer> <target> [--stdio]
v42 ws enter <workspace> [--stdio]
```

- `term attach`（及其顶层简写 `attach`）将当前终端连接到 `<computer>` 上的 `<target>`。
- `ws enter <workspace>` 在 `<workspace>` 所在的电脑和目录中新建一个终端并立即附着过去。

在 Windows 电脑上，`term attach` 只能连接整个会话，不能连接单个窗口或 pane。

这三条都是流式命令：stdout 仅包含远端 PTY 原始字节，退出码来自附着客户端。主动断开连接后，远端窗口继续保持运行。

由其他程序或终端复用器驱动 stdin/stdout 时，请加上 `--stdio`：

- stdin 不是 TTY 时，不改动本地终端设置，也不发送窗口尺寸。输入结束时（例如管道输入读完），会向远端终端发送 `Ctrl+D`，远端正在运行的 shell 会因此退出；只是发送一次性输入时请改用 `v42 term send`。
- stdin 是 TTY 时，启用 raw 模式（`Ctrl+C` 作为按键发给远端），但只有在本进程向远端转发第一次输入之后才推送当前窗口尺寸（并在后续尺寸变化时继续同步）。
- 在 macOS 或 Linux 的 Herdr pane 内运行（`HERDR_ENV=1` 且设置了 `HERDR_PANE_ID`）时，`attach` 会给该 Herdr pane 打上 `v42_computer` 和 `v42_pane` 标记，并在附着期间把该 pane 的 [Agent 状态](/docs/agents/agent-status)实时上报给 Herdr（目标为窗口或 pane 时如此；目标为整个 session 时只写 `v42_computer`，不上报状态）。

## 发送输入与读取屏幕

```sh
v42 term send <computer> <target> [<text>] [--stdin] [--enter] [--key <key>]... [--paste] [--raw]
v42 term read <computer> <target> [--history <lines> | --all] [--raw]
```

### `term send`

向 `<target>` 输入文本或按键，且不干扰正在查看该终端的其他连接。同时指定多项时，先输入 `<text>`（或 `--stdin`），再按顺序发送每个 `--key`，最后按 `--enter`。

- `--stdin`：从标准输入读取要发送的文本（最多 8 MiB）。
- `--enter`：在文本和按键之后按下回车（Enter）。
- `--key <key>`：可重复指定。支持的按键名：`enter`、`tab`、`backtab`、`escape`、`backspace`、`insert`、`delete`、`home`、`end`、`pageup`、`pagedown`、`up`、`down`、`left`、`right`、`space`、`f1`–`f35` 或单个字符。修饰键前缀：`ctrl+`、`alt+`、`shift+`、`super+`（如 `ctrl+c`、`alt+x`、`shift+tab`）或 tmux 风格 `C-`、`M-`、`S-`（如 `C-c`、`M-x`、`S-Tab`）。
- `--paste`：用括号粘贴标记（`ESC[200~` … `ESC[201~`）包裹文本，让开启了 bracketed paste 的 shell 或 Agent 把多行文本当作一次粘贴处理。
- `--raw`：原样发送字节（允许非 UTF-8 输入；此时 `--enter` 追加回车符 `\r`，且不能与 `--key` 同用）。

### `term read`

在 `.data.lines` 中输出 `<target>` 当前可见屏幕的纯文本行（自动去掉末尾空行）。

- `--history <lines>`：在可见屏幕之前一并输出最多 `<lines>` 行历史回滚内容（scrollback）。
- `--all`：在可见屏幕之前输出全部历史回滚内容。
- `--raw`：保留 ANSI 转义序列（历史行保留颜色，可见屏幕按换行符切分原始 VT 流）。

## 等待状态与监听事件

```sh
v42 term wait --until <state> [--match <pattern>] [--timeout <seconds>] <computer> <target>
v42 term watch [<computer>] [--workspace <workspace>] [--timeout <seconds>] [--count <count>]
```

### `term wait`

阻塞等待，直到 `<target>` 达到 `--until <state>` 指定的状态，并返回终端状态 JSON。如果 `--timeout <seconds>`（默认 `600` 秒；传 `0` 则无限等待）先到期，命令以错误码 `wait_timeout` 和退出码 `8` 结束。

| `--until` 取值 | 返回时机 |
|---|---|
| `idle` | shell 回到提示符处且没有处于 `working`、`blocked` 或 `error` 的 Agent：在经历一段忙碌期后返回，或屏幕连续 1.5 秒保持未变后返回。需要电脑上运行较新的 Vibe42；Windows 电脑暂不支持（`idle_windows_unsupported`）。 |
| `done` | Agent 完成当前轮次：在等待期间观察到状态变为 `done` 时立即返回，或已持续处于 `done` 满 1.5 秒后返回。 |
| `blocked` | Agent 正在等待用户操作（权限确认、提问或登录）。若已处于该状态则立即返回。 |
| `error` | Agent 报告了错误。若已处于该状态则立即返回。 |
| `working` | Agent 正在工作。若已处于该状态则立即返回。 |
| `gone` | 终端已关闭（传入窗口时为窗口关闭，传入 pane 时为该 pane 关闭）；若开始等待时目标已不存在，则立即返回并标记 `already_gone`。 |
| `output` | 可见屏幕发生变化；配合 `--match <pattern>` 时，等待出现一行开始等待时不存在且匹配正则表达式 `<pattern>` 的新屏幕行。 |

### `term watch`

在 stdout 上以 JSON Lines（NDJSON，每行一个 JSON 对象）流式输出终端变化：

1. 每台被监听的电脑先输出一行 `ready`（无法监听的电脑输出 `unavailable`）
2. 随后实时输出变化事件：`terminal_added`、`terminal_removed`、`renamed`、`workspace_changed`、`agent_status` 和 `foreground`
3. 达到 `--count <count>` 条变化事件（`ready` 和 `unavailable` 不计入）或到达 `--timeout <seconds>` 秒后，输出最后一行 `stopped` 并退出

省略 `<computer>` 时监听当前团队的所有在线电脑；传入 `--workspace <workspace>` 时只输出该 Workspace 下的终端事件。

## 重命名、移动与关闭终端

```sh
v42 term rename <computer> <target> [<name> | --reset]
v42 term move <computer> <window> <--workspace <workspace> | --none>
v42 term close <computer> [<targets>...] [--force] [--idle [--workspace <workspace>] [--dry-run]] [--no-balance]
```

- `term rename`：为窗口 `@N` 或 pane `%N` 设置自定义名称（去除首尾空白后最多 64 个字符），或传 `--reset` 恢复自动名称。
- `term move`：把窗口 `@N` 移到同一台电脑的 `--workspace <workspace>`，或传 `--none` 将其移出所有 Workspace，并同步更新两侧布局。
- `term close`：关闭一个或多个指定的窗口或 pane（`<targets>...`），或用 `--idle` 关闭 `<computer>` 上的所有空闲终端。
  - 指定 `<targets>...` 时，只要其中有任何终端不是空闲状态（或状态为 `unknown`），**所有终端都不会被关闭**，命令返回 `terminal_busy`（退出码 `2`），除非传入 `--force`。
  - 使用 `--idle` 时，只关闭 `<computer>` 本机属于 Vibe42 的空闲终端（可加 `--workspace` 限定范围）；忙碌终端以及从 Herdr 或外部 tmux 会话镜像过来的窗口（原因 `external_source`）绝不会被关闭，并会列在 `.data.skipped` 中。搭配 `--dry-run` 可只列出将被关闭的终端而不实际关闭。
  - 传入 `--no-balance` 可在移除块后保持剩余分屏比例不变。

## 管理 Agent 启动器（`v42 agents`）

App 新建终端流程展示的以及 `v42 term new --launcher <id>` 使用的 Agent 启动器列表在账号下跨设备同步，可通过 CLI 直接管理：

```sh
v42 agents list
v42 agents add --command <command> [--name <name>] [--agent <agent>]
v42 agents edit <id> [--name <name>] [--command <command>]
v42 agents rm <id>
v42 agents move --index <index> <id>
v42 agents reset
```

- `agents list`：列出当前生效的启动器列表（未自定义时为默认列表）以及内置 Agent 目录。
- `agents add --command <command>`：在列表末尾添加自定义启动器（分配 ID `custom-<n>`）。`<command>` 为不超过 1024 字节的单行命令，且不能以 `-` 开头。`--name <name>` 设置显示名称（最多 64 个字符）；`--agent <agent>` 关联内置目录 ID 以便识别状态。
- `agents edit <id>`：修改启动器的 `--name`（传 `--name ""` 恢复默认名称）或 `--command`。
- `agents rm <id>`：移除指定启动器。
- `agents move --index <index> <id>`：将启动器移动到从 1 开始的指定位置。
- `agents reset`：清空所有自定义项，恢复默认 Agent 启动器列表。
