> 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/primitive/the-navigation-loop.md).

# 导航循环

导航循环就是智能体实际使用 Squish 的方式：先阅读概览缩略表，找出关键区域，再只针对那个时间窗口以更高密度重新运行 Squish，重复直到答案可见——然后引用绝对时间戳。做检索，而不是回放。

## 五个步骤

1. **概览。** 对整个片段运行 Squish—— `squish clip.mov --json` （CLI）或 `squish_video` 工具（MCP）——并用视觉读取表格。单元格按时间顺序排列：从左到右、从上到下。
2. **导航。** 找出关键区域；每个单元格都带有绝对时间码。相邻单元格看起来相似，说明变化不大；两个单元格之间如果出现明显的视觉断裂，表示某个事件发生在这段间隔中。
3. **缩放。** 再次调用，并将 `开始`/`结束` 设为你看到的时间码——在更窄窗口里生成更密的表格，只保留仍有不确定性的部分。地址始终保持绝对。
4. **重复** 直到答案可直接观察到。只有一个范围重要时，绝不要以高密度重新读取整个片段。
5. **引用。** 用绝对时间戳作答（“在 0:07 时压机落下”）——任何人都可以拿原视频核对。

## 一次真实运行：34 帧，而不是 3,088 帧

在一次真实的智能体会话中，一个场景切换被定位到 **0.2 秒** 通过检索 **34 帧——而不是该片段的 3,088 帧** （概览 → 缩放 → 再缩放）：

1. **概览。** 先对整个片段过一遍。切换表现为两个相邻单元格之间的明显视觉断裂——所以它发生在这两个时间码之间的某处，但单元格之间的间隔仍然有好几秒。
2. **缩放。** 重新运行，并将 `开始`/`结束` 设为前后夹住它的两个时间码。现在，同一事件落在这个窄窗口里更密集表格上两个更接近的地址之间。
3. **再缩小范围。** 现在窗口已经足够短，单元格会标注到亚秒级时间码。切换位于两个相差 0.2 秒的单元格之间——答案已可直接观察。

三次调用，检索到 34 帧，最终答案精确到 0.2 秒，并且可以与原视频核对。若线性观看这个片段，就得为一个只发生在不到一秒内的问题处理全部 3,088 帧。

## 让这个循环安全的不可变条件

**时间码始终是绝对的。** 窗口内的单元格 `1:00–1:30` 标注 `1:07`，而不会 `0:07` ——无论缩放到多深，地址都存在于源视频的坐标系中。相对于窗口的时间码会在下一次缩放时把偏移误差继续叠加；绝对时间码则意味着，在任何深度读到的任何地址，都可以直接用于答案，或直接传入下一次调用。

**精度会随窗口调整。** 相隔一秒或更久的单元格会标注 `m:ss`。更短的窗口会自动标注更细的时间码—— `m:ss.d` 当单元格间隔小于 1 秒时， `m:ss.dd` 当小于 0.1 秒时， `m:ss.ddd` 当小于 0.01 秒时——因此相邻单元格总能解析为不同地址，无论缩放多深都一样。JSON 输出中的时间码始终与表格上标注的像素一致。

**可寻址的下限是每个单元格 2 毫秒。** 窄于 *单元格数 × 2 毫秒* 会被错误拒绝，并提示下一步怎么做（放大范围，或降低密度），而不是假装能精确寻址引擎无法清晰定位的时刻。

{% hint style="info" %}
在 2 毫秒下限与源视频自身的帧间隔之间，不同地址可能显示相同的 *帧*。这就是诚实的最大缩放答案——该视频在那个窗口里没有更多帧了——这不是寻址失败。
{% endhint %}

**表格显示的任何内容都可以作为有效输入。** 这个循环可往返：读取 `1:07.3` 从表格中读出，再把它作为 `开始`。二者都 `开始` 和 `结束` 接受普通秒数（`90`, `67.4`）以及时间码字符串（`1:30`, `01:02:03`, `0:02.5`）。你读到的，就是你引用的，也是你寻址的。

## 在所有界面上都适用的同一个循环

这个循环通过引擎的两个本地入口工作方式完全一致：

* **CLI** — `squish clip.mov --start 1:00 --end 1:15 --density 5x5`。带窗口的运行会回显 `"window": { "start": …, "end": … }` 在其 JSON 中；未指定窗口的运行输出保持不变。参见 [CLI 参考](/squish/zh/can-kao/cli.md).
* **MCP** —— `squish_video` 工具可接受可选的 `开始`/`结束` 参数（秒数或表格时间码），并返回 `timecodes[][]` 与标注的像素相匹配。参见 [MCP 参考](/squish/zh/can-kao/mcp.md).

这个 [托管 API](/squish/zh/can-kao/http-api.md) 每次请求都会处理整个片段，并且不接受 `开始`/`结束` ——请使用本地工具运行这个循环。

若要把这个循环整体教给智能体，请安装 [agent skill](/squish/zh/shi-pu/agent-skill.md)；关于在表格上提问的模式，请参见 [prompt 库](/squish/zh/shi-pu/prompt-library.md).


---

# 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/primitive/the-navigation-loop.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.