# 在 Side Space 上开发

一个能让 AI agent 和流水线跟团队一起干活的共享盘。Mac 应用、网页版、CLI、MCP、Linux 挂载和 SDK 背后是同一套 API。

Side Space 是一个能让 AI agent 和流水线跟团队一起干活的共享盘：agent 通过 [MCP](/docs/mcp) 接入，流水线在每次上传时运行，渲染节点把空间[挂载](/docs/linux)成文件夹，脚本调用 API，各自的令牌只给需要的权限。每次保存都是一个**版本**，任何改动都能回看、撤回。每个版本可以带若干**附加信息**（sidecar）：生成它的 AI 提示词、转写、标签、媒体信息，或者你自己的数据，都是 JSON。

## 能做什么

| 你想… | 用 |
|---|---|
| 让 Claude 帮你找、整理和分享文件 | [在 Claude 里用](/docs/claude) |
| 让 Cursor 或你自己的 agent 读写、修改、整理文件 | [MCP](/docs/mcp) |
| 看 agent 动手之前文件夹是什么样，再整个退回去 | [看过去和整体回滚](/docs/history) |
| 手动或在每次上传时转写、打标签、转格式 | [AI 处理与流水线](/docs/actions) |
| 加上你自己的处理（质检、在自己显卡上跑的超分） | [插件](/docs/plugins) |
| 文件到了或变了就做点事（转码、通知、同步到别的系统） | [Webhook 和变更日志](/docs/changes) |
| 记录 AI 素材是怎么生成的，附上质检结果或评分 | [附加信息](/docs/sidecars) |
| 让渲染节点和服务器把空间当文件夹读写 | [Linux 挂载](/docs/linux) |
| 用代码上传成片、把样片拉进剪辑、备份一个空间 | [API](/docs/files)、[SDK](/docs/sdks)（TypeScript、Python、Go、Rust），或者用 `aws`、`rclone` 走 [S3 兼容接口](/docs/s3) |
| 在沙盒里试改动，只合并想要的部分 | [分支](/docs/forks) |
| 按团队授权、限制谁能改某个文件夹、用公司的身份提供方登录 | [组织](/docs/organizations) |
| 读取并回复钉在视频某一秒的审阅意见 | [审阅评论](/docs/comments) |

## 基本概念

**空间**（space）装文件，就像一个共享盘。成员按角色加入：查看者、评论者、编辑者、管理员。

**节点**（node）是空间里的文件和文件夹，可以用 id（`nod_…`）或路径（`Ep01/Shots/A001_C003.mov`）找到。

**版本**（`ver_…`）不可修改。再次保存就多一个版本；任何版本都能恢复，也能起名（“给客户的版本”）。两个人同时保存时，后保存的生效，另一个人会收到通知，两次保存都留在历史里。

**附加信息**挂在版本上，每个命名空间一份 JSON：`media`、`transcript`、`ai.tags`、`ai.generation`、`user`，或者你自己的 `x-…`。

**变更日志**（journal）按顺序记录空间里发生的每一次变化。Webhook、流水线、同步客户端和 SDK 的 `changes()` 都读它。

文件内容不经过 API 服务器。**块网关**（block gateway）把内容切块存储（按空间去重并加密），用 HTTP Range 流式读出整个文件，所以读 200 GB 文件的最后一分钟不用先下载前面的部分。API 负责发放访问它的短期票据。

## 地址

- API：`https://<你的服务器>/v1`。OpenAPI 文件在 `/v1/openapi.yaml`，给 AI agent 的简要说明在 `/llms.txt`。
- 块网关：每张票据里的 `blockgw_url`。
- MCP：`https://<你的服务器>/mcp`。
- S3 兼容接口：同一台主机的 `8070` 端口。

Side Space 可以自己部署，所以文档里的服务器统一写成 `https://side.example.com`，换成你的地址即可。

> [!TIP]
> 赶时间的话，看[快速上手](/docs/quickstart)：五分钟内生成令牌，完成一次搜索、一次上传和一次附加信息写入。

## 每一页都有 Markdown 版

每一页都有给 AI 工具读的 Markdown 版本：在地址后面加 `.md`（例如 `/docs/quickstart.md`），或者点页面顶部的“复制本页”。[`/docs/llms.txt`](/docs/llms.txt) 列出了所有页面。