企业官网建设流程全解析

Helix Foundry 是一款本地优先的数据工作区，它能把公司散落在多个系统中的数据自动对齐，一键生成业务本体（Ontology）：核心是跨源数据对齐与键匹配算法——同一批客户在 Stripe、数据库、CSV 里的不同 ID 如何被认成"同一个人"，本文完整揭秘。

为什么需要"自动生成业务本体"？

先理解一个痛点：同一家公司的客户数据，往往散落在至少 5 个系统里——

每张表的主键都不同，字段命名也五花八门。传统做法是人工写一堆 JOIN、维护一堆映射表——Helix Foundry 用一段确定性的算法代码代替了这些手工活：数据导入完成后，它自动扫描所有数据集的"键候选列"，比对各列的取值重叠，把描述同一事物的表合并成一个业务实体（Entity），并生成实体之间的链接（Link）。

这套逻辑集中在一个文件里：discovery.ts，文件开头就写明了它的设计目标——

Datasets that describe the same real-world thing in different systems are merged into one entity, and value overlap between key columns becomes links. Deterministic; one executor call.

（描述同一真实事物的不同系统的数据集合并为一个实体；键列之间的取值重叠变成链接。确定性；一次执行器调用。）

下面按算法的实际执行顺序，拆解四个步骤。🔍

第一步：给每张表找到它的"身份证"（键候选识别）

算法的第一步是回答：每张表的哪一列最能代表一行数据？这就是ownKey函数做的事（discovery.ts）。

它的判断优先级非常讲究：

1. 优先找"和表名呼应的主键"：support_tickets表里，ticket_id比匿名的id更可信，因为ticket_id这个词根（stem）和表名一致；
2. 再看普通 ID 列：id、uuid、guid这类名字直接命中；
3. 然后是自然键：sku、order_number、handle、username这类业务编号也算键；
4. 邮箱列（email）被刻意降级：因为不同系统的邮箱大小写、前后缀经常不一致，只作为"备选键"（代码里叫alt键）参与后续匹配。

同时，算法会把所有看起来像键的列（类型是整数/VARCHAR/UUID、名字含 key 词根、区分度 ≥ 2）都登记进一个全局候选列表——这些列才进入第二步的取值比对。

💡 小技巧：如果一张表没有任何唯一列，它会被放进unplaced（未安置）清单，界面上会明确提示"该表没有能标识行的唯一列，因此不显示为实体"，而不是硬凑一个错误实体。

第二步：键匹配算法——一次 SQL 算出所有列对的重叠

这是整个算法最精妙的部分：函数overlap（discovery.ts）只向 DuckDB 执行器发起一次调用，就拿到了任意两列之间"有多少取值是共享的"。

它的思路像一次"指纹比对"：

1. 把所有键候选列的值收集成一个值索引（UNION ALL各列的非空值）；
2. 自连接这个索引，统计每一对列（A, B）中完全相同的取值数量m_exact，以及忽略大小写后相同的m_ci；
3. 用一条WHERE子句提前剪枝：重叠值少于较小列一半区分度（或不足 20 个）的列对直接丢弃，避免组合爆炸。

拿到重叠统计后，算法用两道阈值判断两列是否"指向同一批记录"：

• 精确匹配占比 ≥ 80%（匹配值数 ÷ A 列区分度），或者A 列 90% 以上的行都能找到对方；
• 如果只有忽略大小写才能匹配（典型场景：Stripe 邮箱Alice@X.comvs Postgresalice@x.com），则按大小写不敏感口径计算，并在建议里生成一条case类型的备注，告诉你"有 N 条邮箱只在忽略大小写时才匹配"。

针对自增整数主键还有一个防误判规则（discovery.ts）：两张表各自的id从 1 开始自增，值域天然高度重叠，纯属巧合。所以"两个整型id列互为身份键"必须再被一条数据库声明的外键、或一条非整数列匹配佐证，否则直接剔除。

第三步：把表合并成业务实体（union-find 分组）

通过阈值检验的列对，会被分类成两种边：

• identity 边（同一性）：A 列在系统 X 中唯一，B 列是系统 Y 表的主键，且精确匹配过关——说明这两张表是同一批业务对象，应当合并；
• reference 边（引用）：普通的"外键指向"关系，比如invoices.customer_id → customers。

然后算法用**并查集（union-find）**把所有 identity 边连成组（discovery.ts），每一组就是一个候选实体。这里有两个保护性设计：

• 同一系统最多合并一张表：accounts和users都在应用数据库里，即使邮箱碰巧对得上也不会被并成一个实体，防止"账号被吞进用户"；
• 锚点（anchor）选举：每个实体的"主表"优先选来自应用数据库（PlanetScale/Postgres/MySQL）、连接度最高、行数最多的那张，实体名也从它推导——support_tickets自动变成人类可读的 "Support Ticket"（内置了一套英文单复数转换规则，discovery.ts）。

于是你得到了一个自动生成的实体摘要，例如示例数据 Loopwell 中：

7 entities and 1 activity stream from 11 datasets across 5 sources. Accounts combine PlanetScale, WorkOS and Stripe.

（11 个数据集、5 个数据源，被归并为 7 个实体 + 1 条活动流；其中 Account 实体合并了 PlanetScale、WorkOS、Stripe 三个来源。）

第四步：生成链接，并剪掉"废话"

reference 边会被整理成实体间的链接，每条链接携带三类证据标签（evidence）：

剪枝规则同样值得学习（discovery.ts 的withoutImplied）：如果"发票 → 订阅 → 客户"这条两跳路径已经能让同一行数据到达客户，那么"发票 → 客户"这条直连边就是可推导的冗余，算法会实际跑 SQL 验证两条路径是否 95% 以上行行一致，一致就删掉直连边——保持本体图干净，遍历时不迷路。

此外，PostHog 事件流这类"行数巨大、只进不出"的表会被识别为activity stream（活动流），只保留"指向"实体的方向，而不被当成普通记录存储。

确定性是核心：AI 只负责"润色"

一个容易误解的点：Helix Foundry 的业务本体建议不是大模型生成的。整个匹配过程是纯代码、确定性的——同样的输入数据，永远得到同样的本体（结果还会算一个 hash 用于缓存与一致性校验，见 onboarding.ts）。

AI（本地qwen3:4b、Claude 或 OpenAI）只在后台改写实体摘要、描述文案和链接的展示名，不改变合并与链接本身。这带来两个好处：🛡️

• 可复现：数据没变，建议就不会变；输入签名（selected sources + 数据集版本）变化时才会重新计算；
• 零幻觉：每个实体的合并都附"证据备注"——Accounts combines PlanetScale with Stripe (1,204 of 1,204 match)，哪条没匹配上、为什么，一目了然。

确认之后，构建阶段同样不经过模型调用：你确认的实体和链接直接落成 HelixDB 里的记录和关系，只有仪表盘设计才用到模型。

3 步体验：让 Helix Foundry 为你的数据生成本体

1. 选 AI：安装后打开应用（默认http://localhost:3001），引导设置第一步选 Local / Claude / OpenAI。没有 AI 也能走完流程，只是少了描述文案；
2. 接数据：在 Data 步骤连接数据库、Stripe、WorkOS、PostHog、S3 或上传 CSV/Parquet 文件；不想折腾可点Continue with sample data，体验 11 个数据集的 Loopwell 示例（含"计费邮箱 ≠ 登录名""工单没有账号"等真实脏数据场景）；
3. 确认本体：Ontology 步骤会自动算出建议本体，你可以重命名或排除实体，然后点Looks right — build my workspace，工作区即发布，Home 页自动展示核心指标。

进度保存在服务端，中途关浏览器，后台工作不会中断。🔄

想深入源码？看这几个文件

总结：Helix Foundry 的跨源对齐算法可以浓缩成一句话——先给每张表发"身份证"，再用一次 SQL 比对所有身份证的指纹，最后用并查集把指向同一事物的表合并成实体。全程确定性、带证据、可解释，AI 只锦上添花。下次面对"五个系统五套 ID"的窘境时，这种"值重叠 + 阈值剪枝 + 冗余边裁剪"的组合拳，值得直接抄作业。