> 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/contributing.md).

# 贡献

……的简短版 [`CONTRIBUTING.md`](https://github.com/getsquish/squish/blob/main/CONTRIBUTING.md) 在仓库里——在提 PR 之前先读那个文件；这页就是路线图。

## 开发快速入门

要求：Node ≥ 20 · `ffmpeg` + `ffprobe` 已加入 PATH。

```bash
npm install
npm run squish -- path/to/clip.mov --json   # 从源码运行 CLI
npm run mcp                                  # 从源码运行 MCP 服务器
npm test                                     # node:test 测试套件
npm run check                                # tsc --noEmit
npm run build                                # tsup → dist/
npm run e2e -- path/to/clip.mov              # 使用真实 MCP 客户端连接真实服务器
```

## 三行架构

* `src/engine.ts` 是唯一的流水线：probe → plan → extract → compose → write。
* `src/main.ts` （CLI + `mcp` 子命令）和 `src/mcp.ts` 只是其上的薄包装层——没有逻辑分叉。
* `src/core/` 包含纯规划器（密度、采样、网格布局、时间码格式），并与 Web 应用原样共享。 [getsquish.app](https://getsquish.app) Web 应用。

## 契约已冻结

`squish-cli-v0` （CLI `--json` 输出）和 `squish-mcp-v0` （MCP 工具结果）是稳定性契约： **只能进行追加式更改**；破坏性更改会提升契约字符串版本。使用方会解析 `契约` 字段来检测这一点——PR 必须保持这种做法。在修改采样/时间码路径之前，需要知道两个不变量：

* **在任何缩放层级下，时间码都相对于源视频是绝对的** ——窗口化运行绝不会重新基准化它们。
* 可寻址的最小粒度是 **每个单元 2 毫秒**；低于该阈值的窗口会被返回一个教学式错误，而不是悄悄生成。

参见 [稳定性与版本管理](/squish/zh/can-kao/stability.md) 了解完整策略。

## 更改如何流动（镜像优先）

公开仓库是一个私有 monorepo 的精选镜像，后者仍然是事实来源（Web 应用、托管 API 和内部文档都在那里）。实际上：

* **欢迎在公开仓库提交 Issue 和 PR。** 维护者会在那里审查它们，把被接受的更改移回上游，然后在下一次镜像中同步回来——你会在移植后的 commit 中保留作者署名。
* 镜像由脚本组装；在推送任何内容之前，它会先运行完整测试套件和构建，所以 `main` 应该始终是绿色的。

## 安全

请通过以下方式私下报告漏洞： [GitHub 安全公告](https://github.com/getsquish/squish/security/advisories/new) ——不要作为公开 Issue 提交。范围：CLI/MCP 会通过 shell 调用你系统上的 `ffmpeg`/`ffprobe`，所以 ffmpeg 本身的 bug 应该向上游报告；但“Squish 不安全地把恶意输入传给 ffmpeg”属于范围内问题。关于托管 API 的报告也欢迎通过同一渠道提交。完整政策： [`SECURITY.md`](https://github.com/getsquish/squish/blob/main/SECURITY.md).

## 许可证

Apache-2.0，并附带一个 `NOTICE` 文件。通过贡献，你同意你的贡献将按该许可证授权。Squish 的名称、标志、吉祥物和品牌素材均保留，不包含在该许可证内。


---

# 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/contributing.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.