cloudcell/om-core 源码：https://github.com/cloudcell/om-core

OM Core

OM Core 是一个用于结构化金融、运营和分析模型的多维建模引擎的开放源码参考实现。它不是将电子表格网格视为模型，而是使用维度、多维数据集、分组和规则来表示模型。网格和视图是该模型的投影，而非真相来源。

阿尔法软件：OM Core 正在积极开发中。API、命令名称、文件格式、GUI 行为以及模块边界可能在 v1.0 之前发生变化。

文档

主文档站点位于：https://cloudcell.github.io/om-docs/

从以下内容开始：

• 什么是 OM Core：https://cloudcell.github.io/om-docs/start/what-is-om-core/
• 为什么不使用电子表格：https://cloudcell.github.io/om-docs/start/why-not-spreadsheets/
• 安装：https://cloudcell.github.io/om-docs/start/installation/
• 快速入门：https://cloudcell.github.io/om-docs/start/quickstart/

核心思想

大多数电子表格模型将多种事物混在一起：

• 模型结构
• 业务逻辑
• 布局
• 呈现
• 计算流程
• 用户交互

OM Core 将这些关注点分离。模型由以下部分构成：

• 维度 —— 业务轴，如时间、账户、地区、产品、场景或行项目。
• 多维数据集 —— 存储在一个或多个维度上的数据。
• 分组与层次结构 —— 结构化集合与汇总。
• 规则 —— 基于语义模型地址而非电子表格坐标表达的计算。
• 视图 —— 用于检查模型并与之交互的网格和界面。

规则应描述业务关系，而非单元格位置。例如，模型应能表达诸如毛利润源自收入和成本这样的关系，而不必让这种关系依赖于特定的行、列或复制的公式。

仓库范围

该仓库目前包含运行 OM Core 所需的完整阿尔法应用栈。其中包括建模引擎以及支持的命令、REPL、GUI/TUI、运行时、时间线、脚本、插件、存储适配器、示例和测试层。

某些模块是内部实现层。由于当前阿尔法应用依赖它们，因此将其包含在内。它们不应被视为稳定的公共扩展 API。

仓库配置

.om/ 目录是有意提交的。它包含 OM Core 应用的默认配置，包括当前阿尔法应用所需的工具栏设置。它不是一个临时缓存目录或私有本地状态。除非应用配置系统已更改为从其他文档化位置加载这些默认值，否则请勿删除 .om/。

安装

OM Core 当前从源码运行。

Linux / macOS

git clone https://github.com/cloudcell/om-core.git
cd om-core
./start.sh

Windows

使用 PowerShell：

git clone https://github.com/cloudcell/om-core.git
cd om-core
.\start.ps1

./start.sh 或 .\start.ps1 启动 GUI 并询问是否在单独的终端中打开 TUI。

OM Core 使用 uv (https://docs.astral.sh/uv) 管理其 Python 环境。安装 uv，然后在项目根目录中运行 uv sync 以创建 .venv 并安装依赖。之后，启动脚本和测试脚本会自动使用 uv run。

您也可以启动特定的运行时模式：

# Linux / macOS
./start.sh --gui          # 仅图形界面
./start.sh --tui          # 当前终端中的终端界面
./start.sh --runtime      # 仅无头运行时
./start.sh --repl         # 当前终端中的 REPL 命令 shell

# Windows
.\start.ps1 --gui         # 仅图形界面
.\start.ps1 --tui         # 当前终端中的终端界面
.\start.ps1 --runtime     # 仅无头运行时
.\start.ps1 --repl        # 当前终端中的 REPL 命令 shell

更多详情请参阅安装指南：https://cloudcell.github.io/om-docs/start/installation/

快速入门

运行 ./start.sh（Linux / macOS）或 .\start.ps1（Windows）即可启动 GUI。系统会提示您在一个单独的终端中打开 TUI；接受默认值（Y）将在 GUI 旁边提供一个命令 shell，如下所示。

注意： 首次运行 ./start.sh 或 .\start.ps1 时，uv 会在项目文件夹中创建 Python 虚拟环境（.venv）并从 uv.lock 安装依赖。

OM Core GUI 和 TUI 同时运行

启动 OM Core 后，尝试内置的帮助命令：

om> help

您可以针对特定主题寻求帮助：

om> help rule
om> help calc

一个最小的 OM Core 脚本如下所示：

# Dimensions
dim Month Jan Feb Mar

# Cube
cube Sales Month

# View
view SalesView = Sales::Month

# Rules
rule Sales::Month.Jan = 100
rule Sales::Month.Feb = Sales::Month.Jan * 1.1
rule Sales::Month.Mar = Sales::Month.Feb * 1.1

# Calculate
calc

将其保存为 hello.openm，然后从 REPL 或 TUI 中引用它：

om> source hello.openm

完整指南请参见：https://cloudcell.github.io/om-docs/start/quickstart/

测试

使用平台特定脚本运行测试套件：

# Linux / macOS
./test.sh

# Windows
.\test.ps1

架构

OM Core 分为会话范围的运行时层、命令/查询服务层以及多个客户端。引擎拥有规范的工作空间状态；GUI、TUI、REPL 和 CLI 是通过消息总线进行通信的客户端。

目标架构概览

为什么不直接用电子表格？

电子表格快速且灵活，但大型模型往往变得脆弱，因为业务逻辑被编码在单元格地址、复制的公式、链接的工作表和隐式的布局约定中。OM Core 使用了不同层次的抽象。它使模型显式化：维度描述轴，多维数据集保存值，分组组织结构，规则定义计算，视图显示结果。这种取舍是有意为之的：您事先定义更多结构，以换取模型在成长过程中更易于审计、扩展、测试和维护。

更详细的说明请参见：https://cloudcell.github.io/om-docs/start/why-not-spreadsheets/

项目状态

OM Core 目前是阿尔法软件。v1.0 之前尚不承诺提供以下内容：

• 稳定的公共 API
• 稳定的插件 API
• 稳定的脚本 API
• 稳定的文件格式
• 打包的桌面安装程序
• 未经独立验证即可用于关键业务用途的生产就绪状态

另请参见：

• KNOWN_ISSUES.md
• CHANGELOG.md
• SECURITY.md

法律信息

除非另有说明，OM Core 根据 GNU Affero General Public License v3.0 分发。

请参见：

• LICENSE
• NOTICE
• legal/THIRD-PARTY-NOTICES.md
• legal/CONTRIBUTOR-CLA.md
• legal/CONTRIBUTOR-SIGNOFFS.md

OM Core 名称受与软件许可证不同的条件约束。请参见：

• legal/TRADEMARKS.md

贡献

欢迎贡献，尤其是对示例、文档和范围明确的引擎行为的小而集中的改进。请阅读：

• CONTRIBUTING.md
• legal/CODE_OF_CONDUCT.md
• SECURITY.md

安全问题不应通过公开的 GitHub 问题报告。请参见 SECURITY.md。

反馈

• 错误： 提交 GitHub issue (https://github.com/cloudcell/om-core/issues)。
• 讨论： 加入 Discord (https://discord.gg/GfU5ypAbaD)。