objectstack

# 对象栈 [](./LICENSE)   > ## 16k 代码量级下的完整业务系统 > > 对象栈将整个应用 — 数据模型、UI、工作流、权限 — 压缩成 AI 代理可以理解和重构的元数据（typed metadata）。该元数据是您的**业务本体** — 开放、版本化的对象、权限和流程定义，您完全拥有它，而不是散布在框架中的代码。严格的 TypeScript、Zod schema 和验证门户在作者阶段捕获代理的错误；运行时派生数据库、REST API、UI 和 MCP 服务器，并在每个调用上强制执行权限和审计。 `适应于代理的上下文` · `类型化、验证、管控` · `可在任何地方自行部署` · Apache-2.0 **此仓库中的所有内容都是开放栈** — 协议、微内核、SDK、CLI 和生产运行时，均采用 Apache-2.0 许可证，没有开放核心限制。工作流程是 **构建并使用 Claude Code（或其他编码代理）提问**：代理在您的仓库中编写元数据，并在 MCP 上操作正在运行的应用。 而不是 **在线构建并提问** — 在浏览器中，无需安装任何东西？ 那是 **[ObjectOS](https://github.com/objectstack-ai/objectos)**，一个建立在此栈上的商业运行时环境。 <p align="center"> <img src="docs/screenshots/architecture.png" width="940" alt="对象栈架构：作者编写类型化的 Zod 元数据（对象、流程、视图、策略）；微内核编译成版本化的 JSON 工件，并加载插件、驱动程序和服务；它生成 REST API、客户端 SDK、控制台和 Studio UI，以及开发人员和 AI 代理使用的 MCP 工具，由 Auth、RBAC、RLS、FLS 和审计管控，支持 PostgreSQL、MySQL、SQLite 或 MongoDB 数据库"> <br>_{一个类型定义 → 数据库 · REST API · 客户端 SDK · UI · MCP 工具。} </p> ## 循环 **1 · 创建项目。** 脚手架安装 AI 技能包并编写 `AGENTS.md`，因此您的代理从加载协议规则开始 — 而不是从通用的“编写一些 TypeScript 代码”开始。 ```bash npm create objectstack@latest my-app && cd my-app ``` **2 · 描述需求。** 在 Claude Code（或 Cursor、Copilot 等）中打开项目并说明业务需求： > 构建一个支持台。添加一个 `ticket` 对象，包含主题、描述、优先级选择和状态选择。添加一个 **Resolve** 操作，仅在未解决的工单上显示。添加“打开的工单”列表视图和支持导航组。完成后运行 `npm run validate`。 代理编写类型化的元数据 — 而不是代码库。门户拒绝那些在运行时会默默失败的内容，代理在您看到它之前修复它。 **3 · 在浏览器中预览。** ```bash npx os dev --ui # → http://localhost:3000/_console/ ``` 控制台渲染真实的应用 — 记录、看板、仪表盘。如果有问题？ 说出要更改的内容。 **需求变更运行相同的循环**，在一个您可以实际阅读的差异上。 <p align="center"> <img src="docs/screenshots/modeling.png" width="49%" alt="Studio 对象设计器显示 Opportunity 对象的类型字段、查找和布局部分"> <img src="docs/screenshots/automation.png" width="49%" alt="Studio 流程设计器显示一个视觉 DAG，使线索进入活动"> </p> <p align="center">_{更喜欢点击？ Studio 以可视化方式编写相同的元数据 — 相同的工件，相同的门户。}</p> ## 它能实际构建什么？ 指向一个空仓库的代理会得到一个一次性代码库：每个屏幕都是手工制作的，每个错误都是您在运行时要查找的。 对象栈为代理提供了一个**词汇** — 企业软件实际由哪些类型化的、验证的基本元素组成。 代理编写定义；运行时已经知道如何运行它。 | | 功能 | | :--- | :--- | | **对象和字段** | 类型化的 schema，包含关系、验证、公式、文件 | | **权限** | RBAC 加上行级和字段级安全，由运行时强制执行 | | **自动化** | DAG 流程、记录触发器、计划作业、Webhook | | **审批** | 多步骤链条，带有队列和完整审计追踪 | | **视图** | 列表、看板、日历、甘特图、画廊 — 声明式，而不是编码 | | **仪表盘和报告** | 图表、聚合、KPI 绑定到实时数据 | | **操作** | 权限检查的按钮和服务器操作 | | **API 和 SDK** | 生成的 REST + 实时端点，类型化的客户端 SDK | | **AI 工具** | 每个对象和暴露的操作都是一个受管控的 MCP 工具 | | **翻译** | 标签和 UI 文本作为元数据，每个本地化 | | **种子数据** | 夹具和演示数据集随应用发布 | | **数据源** | PostgreSQL、MySQL、SQLite、MongoDB 或内存 | 以下是它的形状 — 一个对象，数据库表、REST API、UI 视图和 MCP 工具都遵循： ```ts import { ObjectSchema, Field } from '@objectstack/spec/data'; export const Ticket = ObjectSchema.create({ name: 'support_desk_ticket', label: '工单', sharingModel: 'private', // 组织范围的默认值 — 安全门户需要它 fields: { subject: Field.text({ label: '主题', required: true, searchable: true }), status: Field.select({ label: '状态', required: true, options: [ { label: '打开', value: 'open', color: '#3B82F6', default: true }, { label: '已解决', value: 'resolved', color: '#10B981' }, ], }), due_date: Field.date({ label: '截止日期' }), }, }); ``` ## 为什么错误不会发布 “AI 编写它”只有在 AI 的错误不会到达生产环境时才有用。 四个门户在代理和您的用户之间： | 门户 | 捕获 | | :--- | :--- | | **类型化** | 严格的 TypeScript + Zod — 形状错误在编辑器中立即被捕获 | | **验证** | `os validate` 拒绝类型检查但会在运行时默默失败的元数据：悬空绑定、错误的 CEL 谓词、缺少安全姿势 | | **审查** | 您批准一个小的可读差异在控制台中 — 而不是五万行胶水代码 | | **管控** | 运行时在每个调用上强制执行权限和审计，因此即使错误的应用程序也停留在围栏内 | 它的工作原理与 TypeScript 相同：**代理的错误成为位于的文本，它可以在几秒钟内读取并自行修复**，而不是一个沉默的运行时故障，没人追溯。 另一半是大小。 此仓库中的 CRM 示例 — [`examples/app-crm`](./examples/app-crm)：六个对象、视图、仪表盘、潜在客户转换流程、权限集、操作、翻译 — 是 **31 个文件，1792 行，大约 16k 代码量级**。 这是整个业务系统，大约是 200k 代码量级的 8%。 自己数一下： ```bash find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l ``` 因为它 **适应于代理的上下文窗口**，所以代理可以加载它端到端，推理每个依赖关系，并在一次更改中重构数据、API、UI 和权限 — 它可以回答 *“如果我更改此内容会发生什么？”* 而不是 grep 和希望。 这就是 AI 从自动补全到 AI 协作者的区别。 > 您的对象、权限和流程是您的业务本体 — 以及 AI 时代的定义层应该是一个开放的协议，您拥有它。 [阅读原因](https://www.objectos.ai/en/blog/ai-ontology-open-protocol/)。 ## 您的应用是 AI 可操作的，免费 因为应用是类型化的元数据，所以运行时将其作为 **MCP 服务器** 在 `/api/v1/mcp` 提供 — 默认开启。 将任何 MCP 客户端指向它，代理可以在相同的权限和 RLS 下检查和**操作**您刚刚构建的应用： ```bash claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp ``` 对象自动暴露；操作通过 `ai: { exposed: true }` 启用。 请参阅 [连接 MCP 客户端](https://objectstack.ai/docs/ai/connect-mcp)。 ## 此仓库 **框架**：协议（`@objectstack/spec`）、内核、SDK、CLI 和生产运行时。 `os start` 或官方 Docker 镜像 [`ghcr.io/objectstack-ai/objectstack`](./docker) 将您的编译应用连同控制台和治理功能一起发布 — 完全开源。 在 ~30 秒内尝试 [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) 上的实时应用（无需安装）。 三层位于微内核上： **ObjectQL** （数据）、**内核** （控制）、**ObjectUI** （视图）。 所有内容从 Zod schema 开始 — 1600+ 个 — TypeScript 类型、JSON Schemas、REST 路由、UI 元数据和代理工具均由此导出。 请参阅 [ARCHITECTURE.md](./ARCHITECTURE.md)。 **想要它被管控和托管，并内置 Build & Ask AI？** [ObjectOS](https://www.objectos.ai) 是这些定义的商业运行时环境 — [objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) 是其公共主页（文档、问题跟踪器、商标政策）。 ## 发布 脚手架项目已准备好容器化： ```bash docker build -t my-app . && docker compose up -d # 应用程序 + Postgres 在官方运行时镜像上 ``` 有关裸 Node、Kubernetes 和您必须固定的秘密，请参阅 [自托管部署](https://objectstack.ai/docs/deployment/self-hosting) — 以及 [使用 Claude Code 构建](https://objectstack.ai/docs/getting-started/build-with-claude-code) 以运行整个循环。 ## 在框架本身上工作 ```bash git clone https://github.com/objectstack-ai/objectstack.git cd objectstack pnpm install # Node 18+，pnpm 8+（核心包启用） pnpm build # 构建所有包（不包括文档） pnpm dev # 运行展示示例（REST + 控制台位于：3000） ``` ## 监视脚本 | 脚本 | 描述 | | :--- | :--- | | `pnpm build` | 构建所有包（不包括文档） | | `pnpm dev` | 运行展示示例（`@objectstack/example-showcase`）— REST + Studio；锻炼每个元数据类型、视图、自动化、AI 和安全链 | | `pnpm dev:showcase` | 与 `pnpm dev` 相同（显式别名） | | `pnpm dev:crm` | 运行最小的 CRM 示例（`@objectstack/example-crm`） | | `pnpm dev:todo` | 运行 Todo 示例（`@objectstack/example-todo`） | | `pnpm objectui:refresh` | 将 sibling `../objectui` 构建到 `packages/console/` | | `pnpm test` | 运行所有测试（Turborepo） | | `pnpm setup` | 安装依赖并构建 spec 包 | | `pnpm docs:dev` | 在本地启动文档站点 | | `pnpm docs:build` | 为生产环境构建文档 | ## CLI 命令 CLI 二进制文件作为 `os` 和 `objectstack` 提供。 ```bash os init [name] # 脚手架新项目 os create # 交互式项目 / 对象脚手架 os dev # 使用热重载启动开发服务器（REST + 控制台） os start # 启动生产服务器 os serve # 提供编译后的工件 os compile # 构建可部署的 JSON 环境工件 os validate # 验证元数据是否符合协议 os lint # 校验元数据最佳实践违规 os info # 显示项目元数据摘要 os generate # 脚手架对象、视图、流程、代理、迁移 os doctor # 检查环境健康状况 os explain # 在命令行上解释协议概念 ``` 云、软件包注册表和环境管理子命令（`os package publish`, `os package install`, `os login`, `os whoami`, `os environments`, `os cloud …`）在目标 ObjectStack 云控制面板时可用。 ## 使用生成的 API 每个对象自动提供 REST API — 无需编写控制器： ```bash # 您上面定义的 `todo_task` 对象的 CRUD 端点 curl http://localhost:3000/api/v1/data/todo_task ``` 对于浏览器，类型化的客户端 SDK 和 React 钩子（`useQuery` / `useMutation` / `usePagination`）位于 [`@objectstack/client-react`](packages/client-react)。 需要新功能？ 编写插件、驱动程序或服务以对抗相同的内核 API — 每个内置功能都是一个（请参见下文）。 ## 软件包目录 <details> <summary><b>72 个已发布的软件包</b>，涵盖核心、引擎、驱动程序、客户端、插件、服务、适配器、工具和示例 — 点击展开。</summary> ### 核心 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/spec`](packages/spec) | 协议定义 — Zod schema、TypeScript 类型、JSON Schemas、常量 | | [`@objectstack/core`](packages/core) | 微内核运行时 — 插件系统、DI 容器、EventBus、Logger | | [`@objectstack/types`](packages/types) | 共享 TypeScript 类型实用程序 | | [`@objectstack/formula`](packages/formula) | 规范表达式引擎 — CEL（cel-js）+ 对象栈标准库，用于公式字段、谓词、条件、动态默认值 | | [`@objectstack/platform-objects`](packages/platform-objects) | 内置平台对象模式 — 身份、安全、审计、通知、包和环境 | ### 引擎 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/objectql`](packages/objectql) | 对象QL查询引擎和模式注册表 | | [`@objectstack/runtime`](packages/runtime) | 运行时启动 — 驱动程序插件、应用程序插件 | | [`@objectstack/metadata`](packages/metadata) | 元数据加载和持久化 | | [`@objectstack/rest`](packages/rest) | 自动生成的 REST API 层 | ### 驱动程序 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/driver-memory`](packages/plugins/driver-memory) | 内存驱动程序（开发和测试） | | [`@objectstack/driver-sql`](packages/plugins/driver-sql) | SQL 驱动程序 — PostgreSQL、MySQL、SQLite（生产） | | [`@objectstack/driver-mongodb`](packages/plugins/driver-mongodb) | MongoDB 驱动程序（原生文档数据库） | > Turso / libSQL 驱动程序（`@objectstack/driver-turso`）和 libSQL 支持的向量知识插件（`@objectstack/knowledge-turso`）从此版本开始位于 [ObjectStack Cloud](https://github.com/objectstack-ai/cloud) 仓库中。 ### 客户端 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/client`](packages/client) | 客户端 SDK — CRUD、批处理 API、错误处理 | | [`@objectstack/client-react`](packages/client-react) | React 钩子 — `useQuery`、`useMutation`、`usePagination` | ### 插件 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/plugin-hono-server`](packages/plugins/plugin-hono-server) | 基于 Hono 的 HTTP 服务器插件 | | [`@objectstack/mcp`](packages/mcp) | 模型上下文协议服务器 — 将 ObjectStack 暴露给 AI 代理 | | [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | 身份验证插件（better-auth） | | [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC、行级安全、字段级安全 | | [`@objectstack/plugin-sharing`](packages/plugins/plugin-sharing) | 记录级共享 — `sys_record_share` + 执行中间件 | | [`@objectstack/plugin-approvals`](packages/plugins/plugin-approvals) | 审批作为流程节点 — 审批人解析、记录锁定 & 状态镜像 `sys_approval_request` + `sys_approval_action` | | [`@objectstack/plugin-audit`](packages/plugins/plugin-audit) | 审计日志插件 | | [`@objectstack/plugin-email`](packages/plugins/plugin-email) | 可插拔的外部电子邮件传输 | | [`@objectstack/plugin-webhooks`](packages/plugins/plugin-webhooks) | 外部 Webhook 交付 — fan-out `data.record.*` 事件 | | [`@objectstack/plugin-reports`](packages/plugins/plugin-reports) | 保存的报告 + 计划电子邮件摘要 | | [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | 开发者模式 — 内存中所有服务的 stub | ### 服务 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/service-analytics`](packages/services/service-analytics) | 分析 — 聚合、时间序列、漏斗、仪表盘 | | [`@objectstack/service-automation`](packages/services/service-automation) | 自动化引擎 — `flows、triggers 和工作流状态机 | | [`@objectstack/service-cache`](packages/services/service-cache) | 缓存 — 内存、Redis、多层 | | [`@objectstack/service-feed`](packages/services/service-feed) | 活动信息流 / 聊天 | | [`@objectstack/service-i18n`](packages/services/service-i18n) | 国际化服务 | | [`@objectstack/service-job`](packages/services/service-job) | Cron 和间隔作业调度器 | | [`@objectstack/service-package`](packages/services/service-package) | 包注册表 — 发布、版本、检索元数据包 | | [`@objectstack/service-queue`](packages/services/service-queue) | 后台作业队列（内存、BullMQ） | | [`@objectstack/service-realtime`](packages/services/service-realtime) | 实时事件和订阅 | | [`@objectstack/service-settings`](packages/services/service-settings) | 设置 — 清单注册 + K/V 解析器（环境 > 租户 > 用户） | | [`@objectstack/service-storage`](packages/services/service-storage) | 文件存储（本地、S3、R2、GCS） | ### 框架适配器 | 软件包 | 描述 | | :--- | :--- | | [`@objectstack/hono`](packages/adapters/hono) | Hono 适配器（Node.js、Bun、Deno、Cloudflare Workers） — 受支持的 HTTP 适配器 | </details> ### 工具与应用 | 软件包 / 应用 | 描述 | | :--- | :--- | | [`@objectstack/cli`](packages/cli) | 命令行工具 (`os` / `objectstack`) — `init`, `dev`, `start`, `serve`, `compile`, `publish`, `validate`, `generate`, `lint`, `doctor` | | [`create-objectstack`](packages/create-objectstack) | 项目脚手架 (`npx create-objectstack`) | | [`objectstack-vscode`](packages/vscode-objectstack) | VS Code 扩展 — 自动补全，验证，诊断 | | [`@object-ui/console`](https://github.com/objectstack-ai/objectui/tree/main/apps/console) | 可分叉运行的运行时控制台单页应用（位于 objectstack-ai/objectui，通过 `@object-ui/console` 在 npm 上提供服务） | | [`@objectstack/account`](apps/account) | 账户与身份门户 — 登录，组织，已连接的应用 | | [`@objectstack/docs`](apps/docs) | 文档站点（Fumadocs + Next.js） | ### 示例 | 示例 | 描述 | 级别 | | :--- | :--- | :--- | | [`@objectstack/example-todo`](examples/app-todo) | 任务管理应用 — 对象，视图，仪表盘，流程 | 初学者 | | [`@objectstack/example-crm`](examples/app-crm) | 最简 CRM 烟雾测试工作区 — 验证元数据加载管道 | 中级 | | [HotCRM](https://github.com/objectstack-ai/hotcrm) | 功能齐全的企业 CRM 参考应用（独立仓库） | 高级 | </details> ## 架构 ObjectStack 使用 **微内核架构**，内核仅提供基本基础设施（依赖注入，事件总线，生命周期），所有功能均作为插件提供。三个层级位于微内核之上： <p align="center"> <img src="docs/screenshots/layers.png" width="900" alt="ObjectStack 分层架构：ObjectQL 数据层，内核控制层，ObjectUI 视图层位于微内核（插件生命周期，服务注册表 / 依赖注入，事件总线）；每个功能 — 驱动，服务器，认证，安全，自动化，AI — 都是插件"> </p> 参见 [ARCHITECTURE.md](./ARCHITECTURE.md) 以获取完整的设计文档，包括插件生命周期状态机，依赖图和设计决策。 ## 路线图 参见 [ROADMAP.md](./ROADMAP.md) 以获取当前的文档和架构清理优先级。 ## 贡献 我们欢迎贡献。请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 以获取开发工作流，编码标准，测试要求和文档指南。 关键标准： - **Zod-first** — 所有模式从 Zod 开始；TypeScript 类型通过 `z.infer<>` 派生 - **camelCase** 用于配置键（例如，`maxLength`，`defaultValue`） - **snake_case** 用于机器名称 / 数据值（例如，`project_task`，`first_name`） ## 文档 完整文档：**[https://objectstack.ai/docs](https://objectstack.ai/docs)** **从 10.x 升级？** 参见 [升级到 ObjectStack 11](./docs/upgrading-to-11.md)。 本地运行：`pnpm docs:dev` ## 社区 - ⭐ **如果 ObjectStack 对您有帮助，请给此仓库点赞 — 这有助于其他人发现它。** - 🐛 问题，错误或功能请求 → [打开一个问题](https://github.com/objectstack-ai/objectstack/issues)。 - 🤝 想要贡献？ 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 许可证 Apache-2.0。