本体

为什么要有对象层

表名的世界和业务的世界之间隔着三处具体的落差。每一处都不是「叫法不好听」， 而是缺了它，链路某一段就只能说物理的词——或者更糟，自己发明一个。

本体的做法是把这三样声明进语义模型，然后在整个链路上按同一个词说话： 检索时当别名用、生成时写进提示、答案卡上做表头、拒绝文案里说人话、 分析时定下钻次序、判定与行动里带出对象身份。 一次声明，全链消费——所以它不会有第二份定义，也不会跟语义层漂移。

三块声明

全部写在语义模型里，位置是固定的一种（放错层会被拦，见下）。 下面用金融演示库的词汇写一份示例：

semantic_model:
- name: financial
  datasets:
  - name: loan
    primary_key: [loan_id]
    fields: [...]
    entity:                       # ① 对象声明：这个数据集是什么业务对象
      display_name: 贷款
      natural_keys: [loan_id]
      aliases: [借款, 贷款单]
  - name: customer
    primary_key: [customer_id]
    fields: [...]
    entity:
      display_name: 客户
      aliases: [用户]
  relationships:
  - name: loan_to_customer        # ② 关系声明：这条边在业务里叫什么
    from: loan
    to: customer
    from_columns: [customer_id]
    to_columns: [customer_id]
    cardinality: N:1
    display_name: 属于
  hierarchies:                    # ③ 层级声明：维度链，粗 → 细
  - name: region_chain
    display_name: 地区层级
    dataset: district
    levels: [region, province, city]

models.py:165 SemanticEntity models.py:190 SemanticRelationship models.py:332 Hierarchy models.py:354 SemanticModel

① 对象声明 datasets[].entity

三个键全空（写了个 entity: {}）与整个块缺席同义， 都归一成「未声明」——空声明不会在投影里变成一个空壳对象。

② 关系声明 relationships[].display_name

关系本身（from / to / 列对 / 基数）是语义层本来就有的， join 路径与 fan-out 保护都靠它。本体给关系补的是业务名： display_name: 属于。

models.py:226 display_name models.py:221 cardinality

③ 层级声明 hierarchies[]

ossie.py:151 _entity_declaration lint.py:826 _lint_hierarchies

一次声明，全链消费

三块声明各自喂给不同的消费面。这张表是「声明一次」这句话的兑现清单—— 每一行都能在源码里指到具体的读点。

flowchart LR
    E["① datasets[].entity
对象名 · 别名 · 自然键"]:::gen
    R["② relationships[]
业务名（基数另管编译）"]:::gen
    H["③ hierarchies[]
字段链：粗 → 细"]:::gen
    P["对象图投影
纯函数 · 零 I/O"]:::entry
    C1["表锚定与生成提示
别名 · 对象摘要行"]:::exec
    C2["答案卡表头
列名 · 实体"]:::exec
    C3["拒绝文案与一键起草"]:::gate
    C4["分析次序 · 判定标签 · 行动身份"]:::ext
    E --> P
    R --> P
    H --> P
    E --> C1
    E --> C2
    R --> C3
    H --> C4
    classDef entry fill:#71717a14,stroke:#71717a59,stroke-width:1px;
    classDef gen fill:#6366f114,stroke:#6366f199,stroke-width:1.5px;
    classDef exec fill:#14b8a614,stroke:#14b8a699,stroke-width:1.5px;
    classDef gate fill:#f59e0b14,stroke:#f59e0b99,stroke-width:1.5px;
    classDef ext fill:transparent,stroke:#71717a80,stroke-width:1.5px,stroke-dasharray:4 4;

这些消费面共用的还有同一份读侧回退：显示名缺省回退数据集名这件事只写在 一个函数里（ object_graph.py:43 entity_display_name）， 对象图页与答案卡表头调的是同一个它——同一份声明在任何地方给出的是同一个名字。 纪律是：声明层保持缺失即缺失，回退只发生在读侧。

对象图：投影 ≡ 声明

对象图是把语义模型映射成「对象 + 链接 + 层级」的一份只读投影， 由 object_graph.py:85 build_object_graph 产出：纯函数、零 I/O、零 LLM、同输入逐字节同输出，并且绝不抛异常。 它有三条由测试钉住的往返不变量：

列表顺序 = 声明顺序（不排序、不去重——声明即输出，顺序是文档的一部分）； 空模型给的是三键恒在的空图，「投影为空」与「读不到」由调用方用错误形状区分， 投影自己不替调用方判 404。

管理台：只读，但三态诚实

/admin/ontology 是这份投影的图形界面。 它不建模、不编辑——页面上唯一的动作是深链回语义台去声明。 只读不是省事，是为了让「这里看到的」永远等于「模型里声明的」。

页面顶部四块 KPI：对象数 / 链接数 / 层级数 / 声明覆盖率（声明了实体的对象占比）。 图本身是确定性的：位置由关系流向决定，同一份语义模型在任何一次渲染里都是同一张图； 只放大缩小（1×–3×）、不平移，节点键盘可达，指向未声明数据集的悬空链接明确提示而不是静默丢掉。 对象数超过 60 时给一条规模提示。

1 2 3 4

1. 1四块 KPI——对象 / 链接 / 层级 / 声明覆盖率（声明了实体的对象占比，图里这个源是 100%）。覆盖率不是打分，是缺口提示：没声明的数据集照样出现在图上（灰色「表」节点），缺口一眼可见而不是被藏起来。
2. 2对象图——节点用实体显示名，边用关系声明的业务名 + 基数（贷款「发放至」银行账户 1:N）。位置由关系流向决定（左 → 右），同一份语义模型每次渲染都是同一张图；灰色虚线节点是尚未声明实体的数据集。
3. 3详情栏——选中对象后是它的声明原文：自然键 account_id、别名「账户 / 账号」（这两个别名就是表锚定里会被认的词）、业务度量与出入链接。页面唯一的动作是「编辑（回语义台）」深链——本体页不建模、不编辑。
4. 4层级卡——第三块声明：地区层级 A3 · A2（粗 → 细，级别按声明序）。分析引擎的下钻读的就是这条链：候选维度按层级序重排、钻下一级取同链的细一级；没声明链的维度不会被硬凑成上下级。

OntologyView.vue:54 coverageText OntologyGraph.vue:58 ZOOM_MAX semantic.py:196 semantic_object_graph

声明从哪来

三条路，出口全在同一个门槛上：改动一律先落 pending 草稿，确认才写入。

init_pipeline.py:368 _draft_entity_naming candidates.py:215 _entity_spec manage.py:1129 create_draft

确认时的写路径与语义层其他改动完全同一条：先跑一次「应用后的文档」lint， 有阻断级问题就拒绝写盘（ issues.py:280 blocking_issues）， 通过才写入并留一次 git 提交。本体声明的 lint 是分级的：

issues.py:253 _ADVISORY_CODES lint.py:723 _lint_entities

还有一类草稿值得单独说：撞上已声明实体或重名关系的改动。 它照常落到待审队列（覆盖是正当的修正路径），但不能直接确认—— 确认按钮前置禁用，管理端以它为蓝本预填「新建」。 草稿是用来审的材料，不是用来一键覆盖现有声明的开关。

声明怎么被验证

写盘前的 lint 证的是声明自洽——自然键引用的字段在这份模型里存在、层级不重名； 证不了声明为真——自然键在库里到底重不重复、标着 1:N 的边「一」侧到底唯不唯一， 这两件事只有连上库才知道。而它们恰恰是准确性杠杆的承重墙：键锚定与骨架保真保的是 「自然键唯一」这个前提，fan-out 拦截读的正是基数声明。声明一旦不成立，守卫不会报错—— 它只会安静地朝反方向使劲：该拦行倍增的地方，自己变成行倍增。

所以 trove validate --live 带了第三族检查：对库探测—— 每条声明翻成一条只读 COUNT，零 LLM、纯确定性。裁决是四态闭集，没有一态叫「静默通过」：

三类探测各自证什么：

• 键唯一——实体自然键（未声明实体则退回主键）：非空键行去重后变少就是违例。这是键锚定与骨架保真的前提被对库核实；
• 关系基数——many→one 的全部含义就是「to 侧唯一」；1:1 加验 from 侧；M:N 不主张唯一（编译器本就不许直接连），它唯一可证伪的面是豁免；
• fan_out 前提——dedup 豁免只在「重复是整行精确重复」时成立：DISTINCT * 折叠后每键仍多于一行即违例（同键不同行，去重去不掉，豁免看着放行、行倍增照旧）；库上根本没有重复行只是 advisory——豁免没在做事。

两个细节是承重的。其一，NULL 语义：SQL 唯一语义对 NULL 不去重， 混口径的计数（COUNT(*) 含 NULL、COUNT(DISTINCT …) 排除 NULL） 会把两行 NULL 键读成「重复键违例」——探测在非空行上判唯一，NULL 单列成 advisory，不制造假警报。 其二，只探测声明过的东西：未声明的键与边没有可证伪的声明，它们进同一份报告的 覆盖率节——哪些数据集没实体、哪些对象没键、哪几个数据集之间一条边都没有—— advisory、零查询；覆盖率是进度指标，不是可用性开关。

这一族只在 --live 下存在：不带 --live 既不连库、输出也逐字节不变。 方言不支持反引号引用标识符时（如 Postgres）给一条诚实的「跳过」，而不是逐条报 SQL 错刷屏—— 与 kb.columns 的 MySQL-only 闸同款。

verify.py:91 verify_declarations verify.py:239 _probe_dedup verify.py:282 _coverage service.py:336 _live_semantic_checks

诚实边界

继续读