> 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/can-kao/stability.md).

# 稳定性与版本管理

Squish 的机器可读接口层通过显式的 **契约字符串**，并作为一个 `契约` 字段写入每个 payload。消费者会解析这个字符串——完全匹配表示该形状就是这里所文档化的那一种；陌生字符串表示发生了破坏性变更，消费者不应再假定旧的形状。

## 这三个契约

| 契约字符串            | 它所覆盖的接口层                                                         | 文档见                                                |
| ---------------- | ---------------------------------------------------------------- | -------------------------------------------------- |
| `squish-cli-v0`  | CLI 的 `--json` stdout 对象                                         | [CLI 参考](/squish/zh/can-kao/cli.md#--json-output)  |
| `squish-mcp-v0`  | MCP 工具返回的 JSON payload `squish_video` （CLI 字段加上 `timecodes[][]`) | [MCP 参考](/squish/zh/can-kao/mcp.md#result-payload) |
| `squish-http-v0` | 托管 API 的 JSON 响应，以及它的 `/healthz` 正文                              | [托管 API 参考](/squish/zh/can-kao/http-api.md)        |

MCP payload 使用自己的字符串——而不是 CLI 的——因为它的形状不同（`timecode` 只存在于那里）。每个接口层都独立版本化。

## 仅增不改规则

在同一个契约版本内，变更是 **仅限新增**:

* 新字段可以被 **添加**.
* 现有字段绝不会被 **重命名**, **删除**，或 **更改类型**.
* 任何违反上述规则的变更都是破坏性变更，并且 **会提升契约字符串版本** （例如 `squish-cli-v0` → `squish-cli-v1`).

对于消费者来说，这意味着：忽略你不认识的字段，并把解析逻辑建立在 `契约` 这个值上——这种组合与所有非破坏性发布都向前兼容。不要通过“嗅探”形状来判断；请直接解析 `契约`.

## 哪些内容是冻结的

除这三个契约的 JSON 键集合之外，这些接口层也已冻结，并按相同的仅增不改原则处理：

* **MCP 工具名称 `squish_video`** ——客户端和 agent skill 都通过名称绑定到它。
* **JSON 键** ，包括 CLI/MCP payload 中的键顺序，以及以下内容的条件存在规则： `window` （仅在请求了 window 时才出现）。
* **文件名格式** `<basename>.sheet-N.jpg` ——请参见 [文件名契约](/squish/zh/can-kao/sheet-format.md#filename-contract).
* **timecode 语法** ——输出格式 `m:ss` / `m:ss.d` / `m:ss.dd` / `m:ss.ddd`、无限分钟、向下取整；以及被接受输入的语法及其 [往返属性](/squish/zh/can-kao/sheet-format.md#round-trip-property) （工作表显示的任何内容都属于有效 `start`/`end` 输入）。
* **绝对 timecode 语义** ——无论缩放到什么层级，timecode 都指向源视频的时钟；带 window 的运行不会重新设定其基准。
* **2 毫秒/单元的可寻址下限** ——低于该下限的 window 会被以教学错误拒绝，绝不会悄悄生成重复地址（见 [自适应精度](/squish/zh/can-kao/sheet-format.md#adaptive-precision)).

## 不涵盖哪些内容

以下内容不作稳定性承诺：

* **工作表的视觉样式** ——颜色、字体、timecode-pill 形状、页脚品牌、页眉/边距、像素尺寸、JPEG 编码器设置。工作表的 *地址* 属于契约内容；其 *外观* 不属于。
* **CLI 的人类可读输出** （在没有 `--json`）
* **错误消息措辞** ——错误 *条件* 及其类别已记录在 [CLI](/squish/zh/can-kao/cli.md#usage-errors) 和 [MCP](/squish/zh/can-kao/mcp.md#error-behavior) 参考资料中，但确切措辞可能会随着时间改进。
* **内部实现** ——引擎内部、渲染代码、ffmpeg 调用细节、临时文件布局。任何未标注契约字符串或未在上文列出的内容都属于实现，而不是接口。

## 破坏性变更将如何公告

1. 受影响的接口层会获得一个 **新的契约字符串** (`……-v1`）；旧字符串绝不会被重复用于不同的形状。
2. 该变更记录在 [变更日志](/squish/zh/zi-yuan/changelog.md).

运行中的 payload 不会悄无声息地改变：如果你的解析器检查 `契约` 并且它仍然读取 `squish-cli-v0` / `squish-mcp-v0` / `squish-http-v0`，那么本页以及以下内容中的每一项保证： [sheet-format 规范](/squish/zh/can-kao/sheet-format.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/can-kao/stability.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.