Factum —— 面向 VS Code 的以人为本、AI 原生建模

为事实建模，而非为表建模。

在 VS Code 中进行对象角色建模。画出一份概念模型，把它读回成领域专家能够确认的句子，再把它映射到关系型或属性图 schema。然后把同一个文件交给你的编码智能体 —— 而在那之前，它一直只能靠列名来重建你的领域。

人可读，LLM 也可读　内置 MCP server　可读写 .orm .fbm　免费且 MIT 许可

一份产物，三类读者。

基于事实的建模用句子表达一切，把每条规则都明确陈述出来，拒绝留下任何隐含的东西。这正是领域专家批准一份模型所需要的。这也恰恰是语言模型停止猜测所需要的。

一个基本事实，是领域专家和语言模型都能核对的最小单位 —— 同时对人可读、对机器可校验，两者之间不会出现偏差。

领域专家读句子

“每个 Person 为且仅为一个 Company 工作。”不需要学习任何记号。他们可以说不行，有些外包人员为两家公司工作 —— 这就是在表还不存在之前就抓到的一个 bug。

智能体读事实

LLM 的原生输入就是句子。verbalization 把领域交给它，是几百条声明式陈述、每条规则都写明 —— 而不是让它从表名去推断含义。

构建读约束

同一个文件在 CI 中完成校验、映射到 DDL，并 diff 成一条 pull request 评论。智能体提出的东西，由人用一句话批准。

ORM 事实层，正是 LLM 一直缺失的那一层

把一个编码智能体指向一个代码库，它会用自己唯一能拿到的证据来重建你的领域：列名、外键和几个 migration。一个可空列是按规则可选，还是碰巧可选？那个唯一索引是业务规则，还是早年的一次性能补丁？它会给出答案。但它没有办法答对 —— 因为没有人把答案写下来过。

它只能从这些东西里猜

        CREATE TABLE person (
  id          int,
  company_id  int NULL
);
      

事实层所陈述的内容

        Each Person works for exactly one Company.
It is necessary that each Person has
  exactly one PersonNr.
It is obligatory that each Employee
  has a Salary.
      

检索给模型的是与你领域相似的文本。概念模型给它的则是关于你领域为真的文本。Factum 把这段文本保存在你仓库里的一个文件中，在 CI 中校验它，并通过 MCP 把它提供给智能体。

三种入口

同样的模型，同样的规则，三种界面。没有任何东西被锁在编辑器里 —— 核心对 VS Code 毫无依赖，这正是另外两种入口存在的原因。

编辑器

一个真正的 ORM 2 图形编辑器，作为 VS Code 自定义编辑器，带有实时 verbalization、Problems 面板中的校验，以及侧边面板里的两种映射。

命令行

factum validate、verbalize、diff、drift、ddl、derive。在 CI 里运行它，有人改坏了模型，构建就会失败。

你的编码智能体

factum-mcp 是架在模型之上的 MCP server，所以 Claude Code 或 Copilot 读的是概念模型，而不是从你的表名去猜，另有一组 skills 教会它建模流程本身。八个工具，一行配置。

为什么选择基于事实的建模

ORM 把领域描述为基本事实 —— Person works for Company —— 而不是描述为表或类。因为这些事实不携带属性，所以每条约束都必须明确陈述，而整个模型可以用平实的语言读回来。

由人来验证，而非靠猜

一个你能大声读出来的模型，就是一个领域专家能够批准或否决的模型 —— 而这一切发生在一张表存在之前。

不做过早的属性化

决定什么成为一列是设计步骤，不是建模步骤。ORM 把这两者分开，于是模型的寿命长于 schema。

一份模型，两个目标

Factum – 面向 VS Code 的人类优先、AI 原生建模

同一个概念模式既可以映射到关系表，也可以映射到带标签的属性图。把它们并排比较后再选择。

它做什么

一切都在本地运行，位于 VS Code 的自定义编辑器中，基于一个普通 JSON 文件。

完整 ORM 2 记法

实体类型与值类型及其引用模式、一元至 n 元事实类型、多重读法、子类型、对象化和派生事实类型。

每一种约束

内部与外部唯一性、首选标识符、简单强制与析取强制、频率、全部十种环类型、子集、排除、相等、值与基数——每一种都带有 alethic 或 deontic 模态。

实时语言化

模型的 FORML 呈现会随着你绘制而更新。点击一个句子即可选择它所描述的内容。

随时校验

缺少引用方案、没有唯一性的事实类型、约束过窄而无法让事实类型保持基本、子类型循环——全都会出现在问题面板中。

四种格式，双向支持

NORMA .orm、FBM Exchange MetaModel、Apache Ossie ontologies 和 Unified Modelling Schema——可导入和导出，而不只是读取。

示例总体

真实示例行与模型一起存储。语言化器会将它们代入读法中，校验器会用它们检查你的约束。

导出与布局

为论文和文档提供 SVG 和 PNG 导出，外加确定性的力导向自动布局。

用英语回读你的模型

语言化让概念模式可审查。Factum 直接从约束本身生成语言化内容，因此句子不会偏离图。

        Each Person works for exactly one Company.
In each population of "Person has Skill", each Person, Skill combination occurs at most once.
It is necessary that the possible values of GenderCode are {'M', 'F'}.
Each Manager is a kind of Person.
      

一个强制角色加上一个唯一性约束，读作 exactly one；去掉强制点，同一个事实类型就读作 at most one。措辞跟随模型。

从同一模式得到两种映射

概念模式不是数据库设计。Factum 推导出两者，并解释它所做的每个选择，而不是让你逆向工程输出。

关系型 — Rmap

函数型事实类型被吸收为列，复合唯一事实类型获得自己的表，一元事实类型变成布尔值，强制角色变成 NOT NULL，值约束变成 CHECK 约束。可生成 PostgreSQL、SQL Server、MySQL、SQLite 或 ANSI SQL。

        CREATE TABLE "Person" (
    "personNr" integer NOT NULL,
    "companyName" varchar(255) NOT NULL, -- From "Person works for Company"
    "genderCode" varchar(1) NOT NULL,
    CONSTRAINT "PK_Person" PRIMARY KEY ("personNr"),
    CONSTRAINT "CK_Person_genderCode" CHECK ("genderCode" IN ('M', 'F'))
);
      

属性图 — LadybugDB

ORM 知道的比手绘图模型更多，映射会利用这一点：唯一性约束变成关系多重度，词法值类型变成属性，而任何边都无法承载的 n 元事实类型会被物化为节点。

        CREATE NODE TABLE Person(nr INT64 PRIMARY KEY, genderCode STRING);
CREATE REL TABLE WORKS_FOR(FROM Person TO Company, MANY_ONE);
CREATE REL TABLE HAS_STUDENT(FROM Enrolment TO Student, MANY_ONE);

// Constraints the schema cannot enforce:
//   [mandatory] It is necessary that each Person works for some Company.
      

学习方法，而不只是工具

Factum 附带一本关于 ORM 2 的短书——基本事实、约束族、子类型与对象化，以及从头到尾完整演练的 Halpin 七步设计流程。书中的每张图都由该扩展绘制，每个图都链接到其背后的模型，因此你可以打开任何示例并拆解它。

基本事实

What an elementary fact is, the and-test for splitting compound ones, and the population check that catches invented fact types.

唯一性

最具意义的约束、三种二元模式，以及告诉你何时应拆分 n 元事实类型的元数检查。

设计流程

CSDP 的七个步骤，应用于一个真实的员工目录报告，从第一句话到完成的模式。

基于事实的智能体

上面的小书讲授了表示法。这一本则是完整的论证：为什么编码智能体会从模式和代码中重建你的领域，以及 ORM 2 概念模式能给他们什么——十八章、61 张图和 38 个可工作的模型。

每张图都由 Factum 自己的渲染器从随手稿提供的模型渲染而来，文中引用的每个 FORML 句子、验证器消息和生成的 SQL 行都是真实的工具输出。最后以三个正确建模的真实模式结束：一个六层智能体记忆架构、一个用于多智能体协调的承诺图，以及一个审计日志，其哈希链被表述为约束而非假设。

你不必选择一种格式

基于事实的建模社区没有公认的交换标准，有三个候选方案在角逐。Factum 没有选择支持其中一个，而是读写所有格式——这样模型就可以在不同工具之间迁移，而不是被困在绘制它的那个工具里。

每次转换都会报告它无法携带的内容，而不是悄悄丢弃。将带有对象化事实类型的模型导出到 Ossie 会告诉你 Ossie 没有对象化；导入 UMS 会告诉你返回的是数据的形状，而不是背后的事实。

像代码一样审查

以文本存储的模型可以和你交付的其他所有东西走同一个关卡。捆绑的 GitHub Action 会验证它，并在拉取请求中评论模型现在说的内容——而不是更改的 JSON。

        - Each Person works for at most one Company.
+ Each Person works for exactly one Company.
+ It is necessary that each Employee has a Salary.
      

这就是审查者读一句话就知道是否批准。同样的比较可以在本地用 factum diff 运行，而 --exit-code

建模中最困难的部分是确定第一个fact type。把 Factum 指向一份电子表格导出文件，它就会给出初稿——这正是 Halpin 的设计流程和 FCO-IM 实际开始的步骤。

        $ factum derive employees.csv

note: "employee_nr" is unique and never empty across all 240 rows,
      so it became the reference mode of Employee.
note: "department" takes only 4 distinct values, so a value
      constraint was proposed. Confirm the list is closed.
      

起标识作用的列会成为实体的 reference mode，类型和枚举从值中推断出来，每一行都保留为一条示例 fact。数据不支持的内容一概不会提出，而每一项假设都会以 note 的形式返回，供你确认。

模型就是文件

一个模型就是一个 .orm.json 文件，其中包含 schema、它的布局和它的示例，并由已发布的 JSON Schema 描述，因此任何工具都能校验它。它可以像你的其他源代码一样进行 diff、合并和评审，也可以放心手工编辑——图是文本文档之上的自定义编辑器，所以 VS Code 的脏状态、撤销栈和文件监听都能正常工作。

每个元素都可以携带元数据和按目标区分的生成提示，任何以 x- 为前缀的键都归你使用——会原样保留，这样其他工具就能往返读写我们一无所知的数据。

开始建模

安装扩展并运行 ORM: New ORM Model，或者把 factum derive 指向一个你已有的 CSV。无论哪种方式，你都能在一分钟内得到一个可用的 schema——而且它是一个可以提交的文件。