内容
# Coda
**编写剧本并将其转化为结构化的分解内容——在您可控的基础设施上。**
Coda 是一个自我托管、桌面优先的剧本编写工作空间。编写或导入可移植的 Fountain 文档，然后使用现有的分解工作空间将源材料组织成具有类型字段和页面引用的可配置层次结构。
[文档](https://kinetik-gg.github.io/coda-docs/) · [安全](SECURITY.md) · [更新日志](CHANGELOG.md) · [MIT 许可证](LICENSE)
Coda 专注于剧本创作和源分解。它不是任务管理器、端到端生产跟踪器或媒体审查套件。
## Coda 的功能
- 原生 Fountain 剧本创建、上下文语法高亮、自动保存、导入和无损 `.fountain` 导出。
- 可配置的一到三级分解层次结构，带有自定义名称和显示前缀。
- 空白分解和电影、连续剧和顺序艺术的启动模板。
- 类似表格的表格，支持搜索、类型过滤器、排序、内联编辑、列大小调整和保存的手动排序。
- 用于文本、长文本、数字、布尔值、日期、枚举和存储媒体的已排序自定义字段。
- 带有页面范围引用的集成 PDF 工作空间，附在分解项上。
- 分解范围的角色、细粒度权限、邀请、评论和活动历史。
- 具有所有者发布的分解默认设置的个人分屏布局。
- 可恢复的回收站、CSV 和 JSON 导出、REST API 密钥和分解范围的 MCP 服务器。
- 一个自我托管的应用程序，支持 PostgreSQL 和兼容 S3 的对象存储。
## 安装
最快捷的方式是使用**一键 Coolify 服务模板**：粘贴一个文件，分配您的域名，然后部署。Coolify 生成每个机密，因此无需手动生成任何内容，也无需阅读容器日志。选择 `coda`，当您已经运行 PostgreSQL 和 S3 时，或者选择 `coda-complete`，适用于一体式堆栈。请参阅 [使用 Coolify 部署](docs/coolify.md)。
Coda 是一个无状态应用程序：它不保留本地状态，而是将所有内容存储在 PostgreSQL 和兼容 S3 的对象存储中。运行后，实例从管理员设置中自行操作——应用内备份（下载、带有保留的调度、从设置中恢复以及自动预升级快照）、具有验证的对象迁移的存储向导、更新检查器和可选的升级仪式、诊断医生页面和令牌保护的 `/metrics` 端点。
## 使用 Docker Compose 安装
Coda 是一个无状态应用程序。PostgreSQL 和兼容 S3 的对象存储是外部服务，您需要自己管理——托管服务或具有独立生命周期自行托管的堆栈。因此，规范安装是 **仅应用拓扑**（`compose.app.yaml`）：Coda 独自运行，指向您拥有的存储。捆绑的完整堆栈（`compose.yaml`) 仍然支持作为**一体式快速入门**用于评估，而 `deploy/minio/` 提供了一个独立的对象存储栈，当您希望自行托管存储时，其生命周期与应用程序独立。
要求：Docker Engine 26+，带有 Compose 插件。发布存档中依赖项免费的操作员实用程序需要 Node.js 22+。
从 GitHub 发布中下载版本部署存档和匹配的校验和，验证校验和和 GitHub 工件证明，然后解压。捆绑包包括规范拓扑、独立对象存储栈、本机覆盖层、环境模板以及带有已注入的发布确切证明的图像摘要的操作文档。
```bash
gh attestation verify coda-deployment-v0.0.4.tar.gz --repo kinetik-gg/coda
gh attestation verify coda-deployment-v0.0.4.sha256 --repo kinetik-gg/coda
sha256sum --check coda-deployment-v0.0.4.sha256
```
要直接从源代码检出安装：
```bash
git clone --branch v0.0.4 --depth 1 https://github.com/kinetik-gg/coda.git
cd coda
cp .env.example .env
```
将成功的发布工作流的 **已发布容器** 摘要中的 `name@sha256:...` 镜像引用复制到 `CODA_IMAGE`。用唯一随机值替换 `.env` 中的每个剩余的 `replace-with-...` 值。
### 规范部署（外部 PostgreSQL 和对象存储）
在 PostgreSQL 和 S3 兼容存储由其他地方管理时使用仅应用拓扑。在 `.env` 中设置 `DATABASE_URL`、`S3_ENDPOINT`、`S3_PUBLIC_ENDPOINT`、凭证、存储桶、区域和 `S3_FORCE_PATH_STYLE`，然后运行：
```bash
docker compose -f compose.app.yaml -f compose.app.local.yaml up -d
docker compose -f compose.app.yaml -f compose.app.local.yaml ps
```
打开 `http://localhost:3000` 并使用 `.env` 中的 `SETUP_TOKEN` 完成一次性所有者设置。生产堆栈不会创建默认帐户。
托管 PostgreSQL 部署应在 `DATABASE_URL` 中需要 TLS。虚拟托管的 S3 提供商通常需要 `S3_FORCE_PATH_STYLE=false`。在启动 Coda 之前预配存储桶及其 CORS 策略。请参阅 [部署和操作](docs/operations.md) 以获取仅应用的 `docker run` 等效项和反向代理拓扑。
### 自托管对象存储
如果您自行托管 S3 兼容存储而不是使用托管提供商，`deploy/minio/` 是一个强化、独立的 MinIO 堆栈，您可以将其部署为自己的资源，以便存储保持与应用程序独立的生命周期——它在应用程序重新部署时存活，并且可以稍后由 R2、S3 或 Spaces 替换。复制 `deploy/minio/minio.env.example` 到 `deploy/minio/minio.env`，替换每个占位符，然后运行：
```bash
docker compose -f deploy/minio/compose.yaml -f deploy/minio/compose.local.yaml up -d
```
堆栈配置了私有存储桶和存储桶范围的服务帐户；将应用程序的 `S3_*` 变量指向它，并在 Coda 之外备份。
### 一体式快速入门（捆绑完整堆栈）
对于评估，捆绑的完整堆栈在单个项目中运行 Coda、PostgreSQL 和 MinIO。保持 `DATABASE_URL` 中的 PostgreSQL 密码与 `POSTGRES_PASSWORD` 同步；如果密码包含保留字符，请 URL 编码。然后运行：
```bash
docker compose -f compose.yaml -f compose.local.yaml up -d
docker compose -f compose.yaml -f compose.local.yaml ps
```
打开 `http://localhost:3000` 并使用 `.env` 中的 `SETUP_TOKEN` 完成一次性所有者设置。生产堆栈不会创建默认帐户。
此参考部署启动：
- 在 `CODA_IMAGE` 中选择的已证明 `ghcr.io/kinetik-gg/coda@sha256:...` 清单
- PostgreSQL，用于持久的应用数据
- MinIO，带有存储桶范围的 Coda 服务帐户
`compose.yaml` 是平台中立的完整堆栈，不发布任何主机端口。显式的 `compose.local.yaml` 重写仅将 Coda 和 MinIO S3 API 绑定到 localhost；它绝不会公开 PostgreSQL 或 MinIO 管理控制台。
### 本地镜像构建
使用开发覆盖文件从检出构建应用程序镜像：
```bash
docker compose -f compose.yaml -f compose.dev.yaml up -d --build
```
## 本地开发
要求：Node.js 24、pnpm 11 和 Docker。
```bash
pnpm install --frozen-lockfile
copy .env.example .env
copy .env.local.example .env.local
# 在启动服务之前替换两个文件中的每个占位符机密。
docker compose -f compose.yaml -f compose.dev.yaml up -d postgres minio minio-init
pnpm db:deploy
pnpm dev
```
在 macOS 或 Linux 上，使用 `cp` 代替 `copy`。用 `.env` 中使用的相同本地服务凭证填充 `.env.local`，然后打开 `http://localhost:5173`。开发 Web 和 API 服务器绑定到 `0.0.0.0`；对于 LAN 上的另一个设备，在启动 Coda 之前在 `.env.local` 中添加 `DEV_ALLOWED_ORIGINS=http://<development-host-ip>:5173`，然后从该设备打开该地址。生产环境拒绝此仅限开发的允许列表。
有用检查：
```bash
pnpm format:check
pnpm quality
pnpm typecheck
pnpm test:unit
pnpm openapi:check
pnpm build
```
拉取请求还针对可丢弃的 PostgreSQL 和 MinIO 服务运行集成测试、生产容器烟雾测试和 Playwright 产品循环。
## 分解模板
新的分解可以从空白开始或使用原子服务器端模板：
| 模板 | 默认层次结构 |
| --- | --- |
| 电影 | 序列 → 场景 → 镜头 |
| 电视系列 | 集 → 场景 → 镜头 |
| 漫画 | 问题 → 页面 → 面板 |
模板添加了一组可编辑的类型字段，可以在不上传 PDF 的情况下创建。稍后可以添加源文档。
## API 和 MCP
帐户设置可以创建单独的、分解范围的 REST API 密钥和 MCP 令牌。令牌仅显示一次，存储为哈希，限制为选定的权限，可以独立过期或撤销。
MCP 服务器是一个 REST 客户端，而不是数据库绕过。它公开了有界的分解、模式、项目、源和活动工具，同时省略了管理性和破坏性操作。
- [文档](https://kinetik-gg.github.io/coda-docs/)
- [外部 OpenAPI 规范](docs/openapi.json)
- [MCP 包](apps/mcp)
## 数据和操作
Coda 从管理员设置中运行，无需 shell 访问：
- **备份。** 按需下载签名 `.codabk` 存档，安排具有滚动保留的定期备份，从首次运行屏幕恢复新实例，并在应用迁移之前捕获自动预升级快照。每个存档都包含数据库和存储对象。在另一个实例上恢复需要该实例携带源的 `CONFIG_ENCRYPTION_KEY`。
- **存储。** 存储向导验证、热交换并（通过验证的对象迁移）在运行时移动对象存储后端。
- **更新。** 更新检查器显示新版本，可选的升级仪式在进行重新部署之前需要进行新的备份，具有通用重新部署 webhook 层和可选的 Coolify 适配器。
- **诊断。** 医生页面呈现一份净化的实例报告，令牌保护的 Prometheus `/metrics` 端点公开请求、存储和更新信号。
[部署和操作指南](docs/operations.md) 记载了这些、完整环境合同和操作员侧备份/恢复程序。[数据兼容性](docs/data-compatibility.md) 是备份格式版本、数据库迁移和配置 blob 的立政策。不应在数据库已由更新的不兼容版本迁移后运行旧版应用程序。
## 当前范围
Coda 是一个早期、桌面优先的自我托管产品：
- 剧本使用 Fountain 作为其规范源，并支持无损 Fountain 导入/导出。
- 剧本保存使用乐观版本检查；尚未包含实时协同编辑和存在功能。
- 分解源文档仅限 PDF，每个分解只有一个活动源 PDF。
- 分解项是手动创建的；尚未包含 OCR 和自动提取。
- 层次结构限制为一、两或三个级别。
- 协作使用授权更新通知和权威重新获取，而不是实时单元格协同编辑或存在。
- 评论是扁平的而不是线程化的。
- JSON 导出包含存储元数据但不包含上传的二进制文件。
- TLS 和公共路由仍然是操作员的责任；应用内提供备份和恢复。
## 仓库信息
- [安全政策](SECURITY.md)
- [更新日志](CHANGELOG.md)
- [许可证](LICENSE)
Coda 在 MIT 许可证下发布。名称和徽标标识此项目，不由软件许可证授予商标。
