内容
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="apps/web/public/brand/logo-dark.svg" />
<img src="apps/web/public/brand/logo.svg" alt="StoryOS" width="220" />
</picture>
</p>
<p align="center">
<strong>开源工作操作系统：用户定义的关联数据库，可以运行整个公司。</strong><br/>
客户、任务、内容流程、CRM、冲刺 — 一个引擎，您的模式，您的服务器。
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="许可证：AGPL-3.0"/></a>
<img src="https://img.shields.io/badge/self--hosted-docker%20compose%20up-success" alt="自托管"/>
<img src="https://img.shields.io/badge/API-first%2C%20OpenAPI%203.1-orange" alt="API优先"/>
</p>
---
StoryOS 是一个连接数据库的工作操作系统，开源且 API 优先。您可以定义数据库，通过真正的关联连接它们，并通过表格、看板、日历、画廊、列表、动态信息流和时间线查看相同的记录。没有任何功能被付费墙限制。网页界面只是公共 REST API 的第一个客户端 — 它可以做的所有事情，脚本（或通过 MCP 的 AI 代理）也可以做到。
## 功能
**引擎**
- **数据库和字段** — 文本、富文本、数字、复选框、日期、选择、多选、URL、电子邮件、人员、关联、查找、汇总、公式、按钮。模式更改是运行时 API 调用，而不是迁移。
- **关联** — 双向关联，双方都有（一个项目看到其任务，一个任务看到其项目），一对多或多对多，跨空间。
- **查找和汇总** — 显示关联记录的字段，或聚合关联记录（计数/求和/平均值/最小值/最大值）。
- **公式** — `{Allocation} - {Days Used}`，`days_between(today(), {Due})`，19 个函数，5 级链。 [文档 →](docs/product/formulas.md)
- **视图** — 表格（虚拟化、内联编辑、多选批量编辑），带有拖拽功能的看板，日历带有拖拽重排。每个视图保存过滤器和排序。
- **实体页面** — 每个记录都是一个页面：字段、富文本描述、附件、带有 @ 提及的评论，以及完整的活动记录。
**工作流程**
- **模板** — 19 个可安装的软件包（客户工作、销售 CRM、内容流程、社交日历、会议、组织图、时间休假、开发项目...），每个都有示例数据和内置指南。 [库 →](docs/product/template-library.md)
- **自动化和按钮** — 在记录更改或计划上触发；按钮通过单击运行操作。 [文档 →](docs/product/automations.md)
- **Cmd+K** — 带有搜索、导航和最近记录的调色板。通知和任务视图的收件箱和我的工作。
- **访客和粒度访问** — 邀请客户端进入确切的一个空间，授予查看者 → 评论者 → 编辑者 → 创建者权限。其他一切对他们都是不可见的。
- **CSV 导入** — 具有类型推断、标题匹配的关联关系和试运行。 [迁移您的数据 →](docs/product/migrate-data.md)
**集成**
- **GitHub** — 导入和刷新问题和 PR；PR 自动链接到问题，问题编号在标题中以 `#N` 或分支名称中的问题编号引用。您的令牌保留在您的服务器上。
- **Linear** — 一次性迁移：每个团队成为一个具有问题、冲刺和项目的空间；状态、优先级、子问题和链接保留；幂等重新导入。 [映射表 →](docs/product/migrate-from-linear.md)
**API 优先**
- `/api/v1` 下的版本化 REST API，OpenAPI 3.1 规范从代码生成，交互式文档位于实例上的 `/api/docs`。
- 个人访问令牌、速率限制、带有过滤器 AST 的查询端点 — 所有这些都可用于构建 MCP 服务器或任何其他客户端。 [指南 →](docs/api/)
## 安装（自托管）
一个 Postgres，两个容器，一条命令：
```bash
git clone https://github.com/StoryFunnels/storyOS.git storyos && cd storyos
echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)" > .env
docker compose up -d
```
打开 **http://localhost** 并注册 — 第一个帐户创建自己的工作空间，迁移自动运行。1 GB RAM 足以应对一个小型团队。
完整的指南 — 环境矩阵、SMTP、Google OAuth、S3/MinIO 附件、备份、升级 — 在 **[docs/self-hosting.md](docs/self-hosting.md)** 中。
## 开发
```bash
pnpm install
docker compose -f docker-compose.dev.yml up -d # Postgres + Mailpit（仅限开发基础设施）
cp apps/api/.env.example apps/api/.env
pnpm dev # api 在 :3001，web 在 :3000
```
`pnpm test` 运行 API 集成套件（Testcontainers），`pnpm lint` / `pnpm typecheck` 是门控，`pnpm sdk:generate` 从 OpenAPI 规范重新生成类型化的 SDK。
## 原则
1. **关联是核心原始数据类型。** 没有关联的数据库是电子表格。
2. **API 优先，无例外。** 用户界面使用与其他人相同的公共 API。
3. **能力永远不会被付费墙限制。** 自托管的核心功能齐全，永久免费。未来的商业化是托管和管理 AI — 永远不会削弱引擎。
4. **结构优于文档。** 工作单元是数据库中的记录，而不是树中的页面。
5. **模式即数据。** 数据库、字段、关联和视图是具有稳定 ID 的 API 资源。
6. **枯燥、可预测、可自托管。** 在 10 美元的 VPS 上运行一个 10 人团队。
## 仓库映射
| 路径 | 内容 |
|---|---|
| [apps/api](apps/api/) | NestJS（Fastify）REST API — 产品的大脑 |
| [apps/web](apps/web/) | Next.js 网页应用 — API 的客户端 #1 |
| [packages/schemas](packages/schemas/) | 共享 zod 模式 + 公式引擎 |
| [packages/sdk](packages/sdk/) | 从 OpenAPI 规范生成的类型化客户端 |
| [packages/mcp](packages/mcp/) | **MCP 服务器** — 从 Claude / 任何 MCP 客户端使用 StoryOS（[设置](packages/mcp/README.md)） |
| [docs/self-hosting.md](docs/self-hosting.md) | 安装、配置、备份、升级 |
| [docs/product/](docs/product/) | 愿景、公式、自动化、模板、迁移指南 |
| [docs/architecture/](docs/architecture/) | 元模型、记录存储、API 约定、身份验证 |
| [docs/decisions/](docs/decisions/) | ADRs — 我们不会重新审议的决定 |
| [docs/api/](docs/api/) | API 指南：身份验证、查询、构建 MCP 服务器 |
| [tickets/](tickets/) | 完整的开发积压，MN-001 及以后 — 如何构建此项目 |
## 技术栈
TypeScript 多仓库（pnpm + Turborepo）· NestJS 11 on Fastify · Next.js 16 · PostgreSQL 16（唯一的数据存储）· Drizzle ORM · better-auth · BlockNote · zod · 从代码生成的 OpenAPI 3.1。 [ADR-0001](docs/decisions/ADR-0001-stack.md) 中的理由。
## 许可证
**双重许可。** [AGPL-3.0-or-later](LICENSE) 适用于所有人 — 永久免费；如果您将其作为服务托管，请分享您的更改。 为无法接受 AGPL 的组织提供单独的**商业许可证** — 相同的代码，不同的法律条款。 见 [docs/licensing.md](docs/licensing.md)。
贡献需要同意 [贡献者许可协议](CLA.md) — 见 [CONTRIBUTING.md](CONTRIBUTING.md)。
