# v42 CLI Agent Skill

> 按需安装可选的 v42-cli SKILL.md，让你的 coding agent 掌握通过 v42 CLI 操作终端、布局、Workspace、文件与隔离副本的工作流。

Vibe42 提供了一份现成的 Agent Skill（`v42-cli`），用于教 coding agent 如何在 shell 中通过 `v42` CLI 操控 Vibe42。遵循 Vibe42 的[不注入原则](/docs/agents/zero-injection)，Vibe42 绝不会自己往你的 Agent 目录写入任何 skill、hook 或插件——是否安装这份 Skill 完全可选，由你自己决定。

## 这份 Skill 包含什么

`v42-cli` Skill（`SKILL.md`）向 coding agent 说明了：

- **按需查阅 `--help`**：要求 Agent 在调用未用过的命令前先运行 `v42 --help`、`v42 <group> --help` 和 `v42 <group> <command> --help`，并以 `--help` 为参数和选项的唯一权威参考。
- **通用约定**：`{"ok":true,"data":...}` JSON 输出结构与 `jq` 解析、退出码含义（包括代表 `confirmation_required` / `terminal_busy` 的退出码 `2` 和代表 `wait_timeout` 的退出码 `8`）、`V42_AGENT_NAME` 审计标识，以及 `<computer>`、`<workspace>` 与终端 `<target>`（`@N`、`%N`、`session:@N`）选择器。
- **分步工作流**：
  - 查找并安全关闭空闲终端（`term list --idle`、`term close --idle --dry-run`）
  - 在 Workspace 中启动 Coding Agent 并等待结果（`agents list`、`term new --launcher`、`term wait --until`、`term read`）
  - 发送文本、按键与多行括号粘贴并读取屏幕（`term send`、`term read --history`）
  - 流式监听终端变化事件（`term watch`）
  - 查看与编排标签页和块布局（`layout show`、`tab`、`block`）
  - 操作电脑上的文件（`ls`、`stat`、`find`、`mkdir`、`rm`、`cp`、`sync`）
  - 在终端外部跨网络管理隔离副本（`copy ... --workspace ... --copy ...`）
  - 管理 Workspace 与便签（`ws`、`memo`）
  - 查看并操作电脑桌面（`desktop screenshot`、`click`、`type`、`key`、`control`、`clipboard copy`）
- **安全规则**：未经用户明确授权绝不传 `--force` 或 `--yes`、优先运行 `--dry-run`、不擅自关闭或改动非自己创建的终端、遵守忙碌/未知状态终端保护、用 `term wait` 代替轮询循环，以及在桌面上绝不输入密钥或密码、未经用户要求不解锁屏幕。

## 如何安装 `v42-cli`

同一份 `SKILL.md` 文件既可以通过 `v42` 命令直接打印（`v42 skill`），也可以通过 HTTPS 从 [`https://vibe42.ai/skills/v42-cli/SKILL.md`](https://vibe42.ai/skills/v42-cli/SKILL.md) 获取（同时收录在 [`https://vibe42.ai/llms.txt`](https://vibe42.ai/llms.txt) 中）。

### 方式一：通过已安装的 `v42` CLI 生成

```sh
mkdir -p ~/.claude/skills/v42-cli
v42 skill > ~/.claude/skills/v42-cli/SKILL.md
```

### 方式二：通过 `curl` 下载

```sh
mkdir -p ~/.claude/skills/v42-cli
curl -fsSL https://vibe42.ai/skills/v42-cli/SKILL.md -o ~/.claude/skills/v42-cli/SKILL.md
```

如果使用其他 coding agent（例如 Codex CLI、OMP、Pi、OpenCode 或 Cursor Agent），把文件保存到该 Agent 加载 `SKILL.md` 的用户目录或项目目录即可（例如单个代码仓库内的 `.claude/skills/v42-cli/SKILL.md`）。

## 面向隔离终端内部的独立 Skill：`v42 copy skill`

除了用于操控整个 Vibe42 的 `v42 skill` 之外，`v42` 还提供了另一份专门面向在[终端隔离](/docs/workspaces/terminal-isolation)副本内部运行的 Agent（已设置环境变量 `V42_COPY`）的 Skill（`v42-copy`）：

```sh
mkdir -p ~/.claude/skills/v42-copy
v42 copy skill > ~/.claude/skills/v42-copy/SKILL.md
```

`v42 copy skill` 专门讲解写时复制副本的目录结构、如何用 `v42 copy status`、`v42 copy changes` 和 `v42 copy diff` 检查状态与差异、如何用 `v42 copy save -m "..."` 保存版本快照或用 `v42 copy push --branch ...` 推送审阅分支，并明确规定将改动写回原 Workspace 目录（`v42 copy apply`）必须由用户本人决定。
