# Workspace、便签与隔离副本

> 使用 v42 ws、memo 和 copy 创建与管理 Workspace、读写并发送 Workspace 便签，以及在本机或跨网络查看和应用终端隔离副本。

`ws`、`memo` 和 `copy` 三个命令组用于管理 [Workspace](/docs/workspaces/workspaces)、[Workspace 便签](/docs/workspaces/extras)以及[终端隔离副本](/docs/workspaces/terminal-isolation)。三者均支持从任何已登录机器跨网络调用；当在电脑本机的隔离终端内部运行时，`v42 copy` 还可以免登录直接在本地运行。

## Workspace（`v42 ws`）

```sh
v42 ws list [--all] [--discovered]
v42 ws show <workspace>
v42 ws create <computer> <path> [--name <name>] [--isolation]
v42 ws update <workspace> [--name <name>] [--path <path>] [--isolation] [--mirror-herdr <on|off>]
v42 ws archive <workspace> --yes
v42 ws move --index <index> <workspace>
v42 ws adopt <workspace> [--name <name>]
v42 ws storage <workspace> [--enable --yes]
v42 ws enter <workspace> [--stdio]
```

- `ws list`：列出当前团队已保存的活动 Workspace。
  - `--all`：包含已归档的 Workspace。
  - `--discovered`：包含在电脑上发现但尚未保存到团队的 Workspace（例如 Herdr workspace）。
- `ws show <workspace>`：按 ID 或名称查看单个 Workspace（按已保存、已发现、已归档的优先级匹配名称）。
- `ws create <computer> <path>`：将在线 `<computer>` 上的绝对目录 `<path>` 保存为新 Workspace。
  - `--name <name>`：Workspace 名称（最多 200 字节；默认取目录路径的最后一段）。
  - `--isolation`：开启[终端隔离](/docs/workspaces/terminal-isolation)，使每个新终端都在 `<path>` 的写时复制独立副本中启动。创建前会先检查目录是否支持；开启后不可关闭。Windows 电脑暂不支持（`isolation_windows_unsupported`）。
  - 如果相同名称和目录的 Workspace 已存在，命令以 `workspace_exists` 失败，并在 `error.details` 中返回现有 Workspace 的 `id`。
- `ws update <workspace>`：修改已保存 Workspace 的 `--name`、`--path`（同一台电脑上已存在的新绝对目录）、`--isolation`（开启终端隔离，不可再关闭）或 `--mirror-herdr <on|off>`（绑定 Herdr 的 Workspace，即 `source_kind: "herdr"`，是否将其标签页镜像到 Herdr）。目录正在转换为去重存储期间不可修改。
- `ws archive <workspace> --yes`：归档已保存的 Workspace（必须传 `--yes`，否则返回 `confirmation_required`）。其中正在运行的终端继续运行，磁盘上的文件不受影响；归档后无法通过 CLI 恢复。
- `ws move --index <index> <workspace>`：将已保存的 Workspace 移到 `v42 ws list` 排序中从 1 开始的指定位置。
- `ws adopt <workspace> [--name <name>]`：把 `v42 ws list --discovered` 列出的已发现 Workspace 保存到当前团队。
- `ws storage <workspace> [--enable --yes]`：查看在线 macOS 或 Linux 电脑（Windows 电脑返回 `storage_windows_unsupported`）上某个 Workspace 目录的[压缩与去重](/docs/workspaces/storage-dedup)状态，或传 `--enable --yes` 开始转换该目录（开启后不可关闭）。
- `ws enter <workspace> [--stdio]`：在 `<workspace>` 中新建一个终端并立即附着上去（见[终端与 Agent](/docs/cli/terminals)）。

## Workspace 便签（`v42 memo`）

每个 Workspace 最多可保存 **15 条未完成便签**（以及已完成的 `--done` 便签）：

```sh
v42 memo list <workspace> [--done]
v42 memo add <workspace> <text> [--visibility <private|team_read|team_write>]
v42 memo edit <workspace> <memo> [--text <text>] [--visibility <private|team_read|team_write>]
v42 memo done <workspace> <memo>
v42 memo undone <workspace> <memo>
v42 memo rm <workspace> <memo> --yes
v42 memo move --index <index> <workspace> <memo>
v42 memo send <workspace> <memo> <computer> <target> [--enter]
```

`<memo>` 可以是便签 ID，也可以是 `v42 memo list`（`undone` 则对应 `v42 memo list --done`）输出的从 1 开始的 `index`。

- `memo list <workspace>`：按顺序返回未完成便签（带从 1 开始的 `index`）；加上 `--done` 则按最近完成顺序列出已完成便签。其他成员的 `private` 便签不会显示。
- `memo add <workspace> <text>`：在未完成列表顶部添加一条便签（`<text>` 去除首尾空白后最多 8192 字节，允许以 `-` 开头）。`--visibility` 设置可见与编辑权限：
  - `private`（默认）：仅你自己可见可改。
  - `team_read`：团队所有成员可读，仅你自己可改。
  - `team_write`：团队所有成员可读可改。
- `memo edit <workspace> <memo>`：修改便签的 `--text` 或 `--visibility`（仅创建者本人可修改可见性）。
- `memo done` / `memo undone`：将便签标为已完成，或将已完成便签恢复为未完成。
- `memo rm <workspace> <memo> --yes`：永久删除一条便签（仅创建者本人可删；必须传 `--yes`）。
- `memo move --index <index> <workspace> <memo>`：将未完成便签移动到从 1 开始的指定位置。
- `memo send <workspace> <memo> <computer> <target> [--enter]`：把便签内容原样输入到 `<computer>` 的终端 `<target>` 中（加上 `--enter` 会在末尾按下回车）。

## 终端隔离副本（`v42 copy`）

`v42 copy` 支持两种运行方式：

1. **本机模式（在电脑上的隔离终端内部运行）**：在 `<父目录>/.<目录名>.v42-copies/<n>/work` 内运行（或设置了环境变量 `V42_COPY`）时，`v42 copy` 直接连接本机 Vibe42 后台服务，无需登录，也不经过网络。如果在副本外部执行目录级命令，可传 `--root <path>`（或在 Workspace 目录下运行）。
2. **远程模式（在任意已登录机器上跨网络运行）**：传入 `--workspace <workspace>`（或 `--computer <computer> --root <绝对路径>`）指定在线电脑上的 Workspace 目录。对于操作单个副本的命令（`save`、`versions`、`changes`、`diff`、`apply`、`push`、`delete` 或查看单副本的 `status`），还需传入 `--copy <copy>`（填 `v42 copy list` 给出的副本编号，或 `.v42-copies/<n>` 目录路径）。

### 查看副本列表与支持状态

```sh
v42 copy list [--workspace <ws> | --computer <c> --root <path>]
v42 copy status [--workspace <ws> | --computer <c> --root <path>] [--copy <copy>]
v42 copy stats [--workspace <ws> | --computer <c> --root <path>]
v42 copy support [--workspace <ws> | --computer <c> --root <path>]
```

- `copy list`：列出某个 Workspace 目录下的全部副本及其状态（`in_use`、`detached`、`preparing` 等）。
- `copy status`：查看单个副本的详情（在副本内部或传入 `--copy <copy>` 时），或列出该 Workspace 目录下的全部副本。
- `copy stats`：查看该 Workspace 目录下所有副本占用的磁盘空间。
- `copy support`：检查某个 Workspace 目录是否支持终端隔离（不支持时 `.data.reason` 会说明具体原因）。

### 版本、改动列表与差异对比

```sh
v42 copy save [-m <message>] [--workspace <ws>] [--copy <copy>]
v42 copy versions [--workspace <ws>] [--copy <copy>]
v42 copy changes [--from <id>] [--to <id>] [--workspace <ws>] [--copy <copy>]
v42 copy diff <path> [--from <ref>] [--to <ref>] [--workspace <ws>] [--copy <copy>]
```

- `copy save`：将副本当前文件保存为一个新版本（`-m` / `--message` 添加版本备注）。
- `copy versions`：列出该副本已保存的历史版本。
- `copy changes`：列出相对于初始基线发生改动的所有文件路径及其应用状态（`pending`、`applied` 或 `conflict`），或用 `--from` 和 `--to` 比较两个版本 ID。
- `copy diff <path>`：输出单个路径（相对副本根目录，与 `changes` 输出一致）的 unified diff。`--from` 默认为 `baseline`，`--to` 默认为 `latest`；两者均可传 `baseline`、`latest`、`source`（原 Workspace 目录中的当前文件）或某个版本 ID。

### 写回改动、推送分支、删除副本与重建索引

```sh
v42 copy apply [<paths>...] [--all] [--workspace <ws>] [--copy <copy>]
v42 copy push --branch <branch> [--workspace <ws>] [--copy <copy>]
v42 copy delete [--force] [--workspace <ws>] [--copy <copy>]
v42 copy rebuild-index [--workspace <ws> | --computer <c> --root <path>] --yes
v42 copy skill
```

- `copy apply`：将 `<paths>...`（或 `--all`）中处于 `pending` 状态的改动写回原 Workspace 目录。`copy apply` 会在本次调用开头自己列一次改动，每个路径写入前再与这份列表核对，若期间又发生了变化则标记为 `changed_since_listing`，且绝不会覆盖冲突（`conflict`）文件。它不以你之前运行的 `changes` 为准，所以请在应用前用 `copy diff` 确认。
- `copy push --branch <branch>`：将副本当前的 Git `HEAD` 推送到原 Workspace 仓库的 `<branch>` 分支。
- `copy delete`：删除副本及其工作文件。当仍有终端窗口在该副本中运行时会以 `copy_in_use` 拒绝；当副本还有未写回的改动或没有版本历史时会以 `copy_not_clean` 拒绝，除非传入 `--force`。
- `copy rebuild-index --yes`：清空并重建某个 Workspace 目录的版本索引（所有副本的历史版本记录都会丢失，必须传 `--yes`）。跨网络执行时，如果耗时超过 15 秒响应上限（`copy_timeout`），请先运行 `v42 copy list` 检查状态后再决定是否重试。
- `copy skill`：输出供隔离副本内部运行的 coding agent 使用的 `SKILL.md` 说明文档（见 [v42 CLI Agent Skill](/docs/cli/skill)）。
