> 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/for-ai-agents.md).

# 面向 AI agent

你是一个 agent（或正在构建一个 agent），而且有一个视频需要回答。这一页把所有决策放在一个地方：该调用哪个入口、拿到 sheet 后如何表现，以及当调用被拒绝时该怎么做。这里的一切都是摘要——每一行都链接到约束它的契约。

**Squish 在 agent 语境里是什么：** 一个镜头，而不是一个回答器。 `squish` 把视频转成带时间戳的 contact sheet——一张可定位时间线的地图——而且 *你* 负责阅读。它从不解释内容：模型 = 含义，Squish = 机制。

## 选择你的入口

一个引擎，四种接入方式。根据视频所在位置和你能运行什么来选择：

| 你的情况                                                                                                       | 使用                                                             | 媒体处理                                              |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------- |
| 有 shell 访问权限，视频是一个 **本地文件**                                                                                | **CLI** — `npx -y @getsquish/squish clip.mov --json`           | 本地机器， **无需上传**，免费，无门槛                             |
| 客户端发起 **MCP**，视频在本地                                                                                        | **MCP 服务器** — `npx -y @getsquish/squish mcp`，工具 `squish_video` | 本地机器， **无需上传**，免费，无门槛                             |
| **官方 AI 应用** （Claude Desktop / claude.ai / ChatGPT），没有本地工具，视频位于 **公开 URL** （或已附加文件，在客户端的 file-param 传递可用时） | **远程 MCP 连接器** — `https://api.getsquish.app/mcp`               | server 端获取它；源文件在任务结束时删除，sheet 存在于约 24 小时有效的 URL 上 |
| 产品/CI 需求 **请求-响应**，可上传                                                                                     | **托管 API** — `POST https://api.getsquish.app/v1/squish`        | 有意上传；任务结束时删除，sheet 存在于约 24 小时有效的 URL 上            |

想零安装手动使用的人工用户去 [getsquish.app](https://getsquish.app) ——在浏览器内处理，不上传任何内容。

在你选择之前，有两个值得了解的不对称点：

* **缩放窗口（`start`/`end`）在 CLI、MCP 服务器和远程 MCP 端点上都存在——但托管 API 还没有** （它每次请求处理整个片段）。如果任务需要 [导航循环](/squish/zh/primitive/the-navigation-loop.md)，优先选 MCP 入口或 CLI。
* **远程端点在 server 端抓取媒体。** 它接受公开的直链文件 URL——或者附件视频，在客户端的 Apps-SDK file-param 传递可用时也可以：工具声明 `openai/fileParams: ["video"]`，平台应把附件上传并在调用到达 Squish 之前重写参数。这个传递是客户端一侧的契约，而且目前并不稳定——ChatGPT **移动端** 目前会在请求发送前就客户端失败（一个已知的上游 bug），所以在移动端请用 URL 这条路径，这一点已在现场验证。私有链接永远无法访问；在不支持 file-param 的 connector 客户端里，聊天附件也不行。如果视频在本地，而且你有 shell 或本地 MCP，优先使用本地工具；拿不准时，公开 URL 路径是各处都已验证的方式。

## 拿到 sheet 之后的行为规则

1. **不要说 Squish“看过”这个视频。** 它只是把视频编译成了带时间戳的视觉产物；阅读它的是你。
2. **单元格按时间顺序运行，从左到右、从上到下。** 两个相邻单元格之间的明显视觉断裂，表示在那个间隙里发生了某个事件——那个间隙就是你的下一次 `start`/`end`.
3. **放大，而不是重新阅读。** 各层级的时间码都是绝对的；把你看到的那些直接作为 `start`/`end` 传回去，然后读取只包含该范围的更密集 sheet。
4. **绝不要引用比单元格间距更精细的时间。** 如果相邻单元格相隔 4 秒，那么它们之间的事件是“在 0:12 和 0:16 之间”，而不是“在 0:14”；先放大到能直接观察到该时刻，再引用。
5. **引用前先确认。** 你答案中的时间戳必须是你确实从某个单元格（或两个单元格之间的括号）里读出来的，而不是估计出来的。
6. **音频取决于嘴巴。** CLI/本地 MCP 0.3+ 包含一条全局归一化的活动包络，位于同一条绝对时间线上。它显示 *何时* 能量发生了变化，而不是说了什么或是什么造成了声音。在单独发布之前，托管路径仍然只显示视觉内容；不要从任何一种产物里猜测音频含义。
7. **多个 sheet 的结果是同一段 clip 的连续窗口。** 按顺序把它们全部读完。
8. **密度 = 时间分辨率。** `3x3` 恢复 *发生了什么*; `4x4`–`6x6` 恢复 *如何*。优先缩小窗口，而不是提高密度——整个片段的更密网格比正确的十秒钟的 3×3 更耗费资源、且解析度更低。

要把这套做法整体安装进去——触发条件、循环、引用纪律——请使用 [`video-navigation` 技能](/squish/zh/shi-pu/agent-skill.md): `npx skills add getsquish/squish`.

## 配额和拒绝

* **本地工具从不设门槛。** 永远不需要 key，也没有 quota。
* **远程 MCP：** 匿名免费通道（按 UTC 日计算的少量任务——如果客户端发送了 Apps-SDK subject id，则按用户计算；否则按 IP 计算），或者 `Authorization: Bearer <API key>` 用于按积分计费的任务。额度用尽会返回 **结构化 JSON 错误** ——把其中的提示（充值链接或每日重置）转告用户，不要盲目重试。细节： [远程 MCP 端点](/squish/zh/can-kao/remote-mcp.md).
* **托管 API：** 按密度（1/2/3/5）为每个 sheet 预付积分；从未付费的账户会自动获得少量每日免费额度。错误语义——哪些会计费、哪些会退款、哪些可以安全重试——见 [托管 API 参考](/squish/zh/can-kao/http-api.md)；唯一需要硬编码的规则是：在 `500` check `refunded` 在正文里—— `true` 表示重试一次， `false` 表示费用保留，改为报告，不要重试。

## 以机器可读方式阅读这些文档

* **供 agent 使用的索引：** [`/llms.txt`](https://getsquish.gitbook.io/squish/llms.txt) · 将整套文档放在一个文件里： [`/llms-full.txt`](https://getsquish.gitbook.io/squish/llms-full.txt)
* **原始 markdown：** 在任何文档页面 URL 后追加 `.md` 。
* **Docs MCP 服务器：** `https://getsquish.gitbook.io/squish/~gitbook/mcp` ——把这些文档当作工具来查询。
* **产品侧运行说明：** [getsquish.app/llms.txt](https://getsquish.app/llms.txt) 涵盖 web app 以及账户/积分界面。
* **机器可读的契约：** 每个响应都会盖上一个冻结的 contract 字符串（`squish-cli-v0` · `squish-mcp-v0` · `squish-mcp-http-v0` · `squish-http-v0`）——见 [稳定性与版本管理](/squish/zh/can-kao/stability.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/ru-men/for-ai-agents.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.