> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/zh/ru-men/quickstart-cli.md).

# 快速开始：CLI

**让 AI 能随机访问视频。** Squish CLI 会把视频在你的机器上完整转换成带时间戳的 contact sheet——也就是一个帧网格，每个单元格都标有其绝对时间码。绝不会上传任何内容，而且所有密度都免费。

## 需求

* **Node ≥ 20**
* **`ffmpeg` + `ffprobe` 已在 PATH 中**
  * macOS： `brew install ffmpeg`
  * Ubuntu： `sudo apt-get install ffmpeg`

## 第一张表

无需安装步骤——直接从 npm 运行：

```bash
npx -y @getsquish/squish clip.mov
```

或者全局安装：

```bash
npm install -g @getsquish/squish
squish clip.mov
```

## 会落到磁盘上的内容

表会保存在输入文件旁边，文件名为 `clip.sheet-1.jpg` （模式： `<basename>.sheet-N.jpg`）——一个带时间码的帧网格。默认密度 3×3 可以还原 *发生了什么；* 发生； `4x4`–`6x6` 还原 *如何* 完成的。 `--out <dir>` 用于选择输出目录。

把这张表交给任何视觉模型：单元格按时间顺序排列，从左到右、从上到下，而且每个单元格都带着它所显示帧的绝对时间码。

## 机器可读输出： `--json`

使用 `--json`时，stdout 只会输出一个对象（固定契约——解析 `契约` 以检测破坏性变更）：

```json
{
  "input": "/abs/path/clip.mov",
  "duration": 20.275,
  "frames": 9,
  "sheets": 1,
  "files": ["/abs/path/clip.sheet-1.jpg"],
  "warnings": [],
  "contract": "squish-cli-v0"
}
```

退出 `0` 成功 · `1` 失败（消息会输出到 stderr）。临时帧始终会被清理。

## 放大到某个范围

`--start` / `--end` 接受秒数（`90`）或表上标注的完全相同时间码（`1:30`, `1:07.3`），并将运行范围限制到该区间：

```bash
squish clip.mov --start 1:00 --end 1:30 --density 5x5
```

**时间码始终相对于源视频是绝对的**，所以你可以反复放大：先看总览 → 发现一个范围 → 用 `--start`/`--end` 重跑 → 得到更细的时间码 → 再继续深入。较短的窗口会标注亚秒级时间码（`1:07.3`），这样相邻单元格就能区分开。窗口运行还会额外回显 `"window": { "start": …, "end": … }` （解析后的边界，单位秒）到 `--json` 输出中——如果没有请求窗口，则不会出现这个键。

## 下一步

* [导航循环](/squish/zh/primitive/the-navigation-loop.md) ——代理如何把“总览 → 放大 → 再放大”串联起来，用证据回答问题，而不是反复播放视频。
* [CLI 参考](/squish/zh/can-kao/cli.md) ——每个标志、退出代码，以及完整的 JSON 契约。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/zh/ru-men/quickstart-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.