> 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/zi-yuan/changelog.md).

# 更新日志

按已发布版本划分的面向用户的变更： [`@getsquish/squish`](https://www.npmjs.com/package/@getsquish/squish)，按最新在前。日期为 npm 发布日期。发行说明也可见于 [GitHub Releases](https://github.com/getsquish/squish/releases).

## 0.3.1 — 2026-07-18

音频活动在构建其低速率时间线时现在会保留高频能量。

* 修复了 0.3.0 中的一个重采样错误，该错误可能会让 500 Hz 以上的连续音调几乎听不见。Squish 现在会先构建完整频段的活动包络，再把它缩减为供 sheets 和 JSON 使用的紧凑 1 kHz 表示。
* 无协议或命令变更： `audio.samples[]`, `clip_peak`、CLI 和本地 MCP 仍保持 0.3.0 的结构。没有音频的视频和带静音音轨的视频仍保留各自不同的结果。

{% hint style="success" %}
**在你熟悉的视频上试试 0.3.1：**

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

JPEG contact sheet 包含画面、绝对时间码和一个音频活动带。让 AI 找出某一个具体时刻，然后用那个范围再次运行 Squish——例如， `--start 12 --end 18`——来更仔细地查看它。CLI 需要 Node.js 20+ 和 ffmpeg；视频处理会一直留在你的机器上。
{% endhint %}

## 0.3.0 — 2026-07-18

音频活动变成了本地端的导航通道。

* 每个 CLI/本地 MCP 说明页现在都带有一条细小的 **音频活动带** ，位于视觉网格上方，并与同一条绝对源时间线对齐。高能量峰值会被标记出来，这样智能体即使在相邻画面很相似时，也能选择一个范围来检查。
* JSON 新增了一个 `audio` 对象，但没有移除或重命名任何 v0 字段： `存在`, `归一化`，绝对 `窗口`，以及 `samples[]` (`时间`, `级别`）。本地 MCP 会连同 `timecodes[][]`.
* 级别使用 `归一化：clip_peak` ，基于整个源视频，包括窗口化调用。这样，安静的缩放视图相对于总览仍然保持安静，而不会被单独归一化到让每个区间都显得很响。
* 活动包络在总览降采样期间保留短暂瞬变。带静音音轨的视频返回 0 级别；没有音轨的视频仍会生成说明页并报告 `存在：false`.
* 范围边界：activity 回答 *音频能量何时变化*，而不是说了什么或是什么发出的声音。不做转写、说话人分离、音频事件分类或情绪推断。Web 应用、托管 API 和远程 MCP 在单独发布前仍然只提供视觉功能。
* README 和 `video-navigation` 技能现在包含一个五分钟测试流程：带上一个你知道答案的视频，询问某一个具体时刻，按 总览 → 缩放 导航，并将引用的时间与源视频核对。

## 0.2.3 — 2026-07-14

可被发现的发布：智能体现在可以自己找到 Squish。

* 列在官方 **MCP Registry** 中，作为 [`io.github.getsquish/squish`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.getsquish/squish): `package.json` 包含 `mcpName` （该注册表的 npm 所有权标记）， `server.json` 描述了两种接入方式（通过 stdio 的这个 npm 包 + 托管端点），并且一个由标签触发的 OIDC 工作流会在每次发布时更新这条列表。
* **`video-navigation` 智能体技能** 在仓库的 `skills/` 目录中—— `npx skills add getsquish/squish` 教会智能体什么时候该使用 contact sheet、缩放循环和引用规范。已列在 skills.sh 上。
* stdio MCP 真实性： `serverInfo` 现在会报告真实的包版本（此前两个版本里一直硬编码为 `0.2.0` ，持续了两个版本），并且 `squish_video` 带有行为注释——把说明页写到你的磁盘上，任何内容都不会离开机器（封闭世界），重复运行会覆盖相同输出（幂等）。
* 新文档： [面向 AI 智能体](/squish/zh/ru-men/for-ai-agents.md) （可选表面决策表 + 行为规则）以及 [支持](/squish/zh/zi-yuan/support.md).
* 托管端点（同一引擎， **不在此包中**）：Apps SDK 扫描元数据（`outputSchema` + `structuredContent`，attachment `fileParams`）、按 subject 键区分的免费通道，以及面向 ChatGPT 流量的免配额通道——ChatGPT 应用已于 2026-07-12 提交审核。
* 引擎不变： `squish-cli-v0` 和 `squish-mcp-v0` 的契约与 0.2.0 完全相同。

## 0.2.2 — 2026-07-10

lens README，以及远程端增加了认证。

* README 围绕 lens 规范重建—— *AI 通过镜头而不是答案来看：Squish 负责调整镜头；模型负责解读* ——新增了封面（“Random access to video”）和官方应用路径（添加 `https://api.getsquish.app/mcp` 作为连接器，无需安装）。
* `squish_video` 工具描述根据实地证据进行了调整：一调用经济性说明（“一次调用就能替代完整的下载 → ffmpeg → 提取 → montage 流水线”）、密度与窗口的使用建议，以及 `timecodes[][]` 镜像说明——在不改变提示词的情况下，智能体会更好地选择工具并推动循环。
* 托管端点（同一引擎， **不在此包中**): `api.getsquish.app/mcp` 获得了可选的 `Authorization: Bearer` API keys（与托管 API 使用同样的额度，先扣再提取并自动退款），同时还有一个小型匿名免费通道；额度耗尽时会返回结构化错误，智能体可以直接转发。 **此包中的本地 CLI 和 MCP 服务器将永久不设门槛。**
* 引擎不变： `squish-cli-v0` 和 `squish-mcp-v0` 的契约与 0.2.0 完全相同。

## 0.2.1 — 2026-07-08

首次开源发布：背后的引擎 `@getsquish/squish` 正式公开于 [github.com/getsquish/squish](https://github.com/getsquish/squish) （Apache-2.0，创始 monorepo 的精选镜像——历史从那里开始）。

* README 围绕 primitive 重建：把视频视为可寻址表示、导航循环（总览 → 缩放 → 引用），以及元演示——一个 76 秒的讲解视频，与同一个视频并排显示为一张 contact sheet。
* `package.json` `仓库` 现在指向公开仓库，所以 npm 的“Repository”链接可以正常工作。
* 新增了 `SECURITY.md` （通过 GitHub security advisories 提交私密漏洞报告）以及 npm / CI / license 徽章。
* 引擎不变： `squish-cli-v0` 和 `squish-mcp-v0` 的契约与 0.2.0 完全相同。

## 0.2.0 — 2026-07-07

窗口化说明页——把说明页变成可导航地址空间的发布。

* `--start` / `--end` 用于 CLI，以及 `start` / `end` 用于 `squish_video` MCP 工具，会把一次运行限定到一个范围。两者都接受秒数（`90`）或与说明页上标注完全一致的 timecode（`1:30`, `1:07.3`).
* timecode 始终保持 **相对于源视频的绝对时间，在每个缩放深度都一样** ——窗口化运行不会重新设定基准，所以你可以反复深入：总览 → 范围 → 时刻。
* 自适应 timecode 精度：短窗口会标注亚秒级 timecode（`1:07.3`），这样相邻单元格仍然可以区分。
* 可寻址下限：如果窗口小于每个单元格 2 ms，就会返回一个教学性错误（放大或者降低密度），而不是生成难以区分的单元格。
* 窗口化的 `--json` 运行会把解析后的边界回显为 `"window": { "start": …, "end": … }`.

## 0.1.1 — 2026-07-06

为 npm 包页面重写 README。没有引擎或契约变更。

## 0.1.0 — 2026-07-06

首次发布 `@getsquish/squish`：把 CLI 和 MCP 服务器放在一个包里。

* CLI： `squish <video>` → 在输入文件旁生成带时间戳的 contact sheet（`<basename>.sheet-N.jpg`), `--density 3x3|4x4|5x5|6x6`, `--out <dir>`，以及 `--json` 并使用冻结的 `squish-cli-v0` stdout 契约。
* MCP 服务器： `squish mcp` （stdio）暴露一个工具， `squish_video`，返回 CLI 契约以及逐单元格的 `timecodes[][]`，带时间戳 `squish-mcp-v0`.
* ffmpeg/ffprobe 预检，会快速失败并给出按操作系统划分的安装提示，而不是在运行中途报错。
* Apache-2.0 许可证 + NOTICE。


---

# 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/zi-yuan/changelog.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.