22 KiB
通用本体元数据平台 · Ontology Platform
把业务实体、属性、关系、动作、函数和接口统一纳入本体元数据,并通过访问控制与运行时审计控制信息的安全使用。
设计对标 Palantir Ontology(Semantic + Kinetic + Dynamic Security + Function-backed Action)。 技术栈:Go + Gin + PostgreSQL + Vue3 + Element Plus。前端构建产物复制到
server/webroot后由 Go//go:embed内嵌进二进制。
1. 架构定位
平台采用 Semantic / Kinetic 双层模型(参考 Palantir Ontology 设计):
- Semantic 语义层:描述企业"有什么"以及实体之间如何关联。
- Object Type / Object:对象类型与对象实例
- Property:对象属性
- Link Type / Link:关系类型与关系实例
- Interface Type:对外 REST / MCP 接口契约
- 公理声明:disjointWith / equivalentTo / functionalLinks / inverseOf / dateOrder(
object_types.axioms,2026-09-20,详见 STANDARD_GB48000_3_2026_GAP.md §5.2 #4)
- Kinetic 行为层:描述业务"如何计算、如何执行、如何变化"。
- Action Type:用户主动触发、通常带副作用的动作
- Function Type:可复用、类型化的计算函数
- Function-backed Action:Action 绑定 Function 形成端到端执行链
- Materialization:物化数据集,把多表 join 投影成快读行
- Dynamic Security:运行时执行主体识别、授权、标记过滤、字段脱敏、审计日志
平台本身承担类似 Ontology Metadata Service(OMS)的职责:管理元数据、实例数据、治理规则和对外查询接口。
1.1 当前元数据组件
| 组件 | 数据表 | 当前状态 |
|---|---|---|
| Object | object_types / objects |
✅ 已实现,含 title_property / subtitle_property / color / primary_key;iri 列存全球唯一标识;axioms 公理声明五类 / parent_id SubclassOf 类型继承 / display_name_lang 多语标签(2026-09-20) |
| Property | properties |
✅ 已实现,含 format / default_value / indexable / vector_index / backing_column;data_type 扩展 geoshape / geopoint / media / timeseries / timestamp / uri(绝对 URI 写入校验 + xsd:anyURI 导出);iri 列存全球唯一标识;display_name_lang 多语标签;管理读路径子类型合并祖先属性(标 inherited=true;连接器/MCP get_object_types 视图仍按自身属性,写校验闭包对子实例生效) |
| Link | link_types / links |
✅ 已实现,含 directional;链接本身可带字段(link_properties 子表);iri 列存全球唯一标识;display_name_lang 多语标签;functionalLinks 公理对边写入生效 |
| Schema Version | schema_versions |
✅ 已实现,append-only 全局版本流水(schemaAudit 挂钩点即管理 API 五类 schema 增删改单调 +1;AI 摄取/合并清理等旁路写入暂不进流水,与 ontology_audit_log 同覆盖,PLAN.md 后续项),details 与 ontology_audit_log 同构含 before/after |
| Interface | interface_types |
✅ 已实现,含 shared_properties / parent_interface_id 多态;自动登记 6 个连接器接口 |
| Action | action_types |
✅ 已实现完整契约(submission_criteria / side_effects / impl_function_id / return_type)+ FBA 执行链 |
| Function | function_types + builtin registry |
✅ 已实现 4 个 builtin;含 when_to_suggest + llm_tool_description(AI 提示调度) |
| Materialization | materializations / materialization_rows |
✅ 已实现 CRUD + 60s ticker scheduler + 手动 refresh |
| Backing Source | backing_sources |
✅ 已实现,字段映射到 Materialization |
| Dynamic Security | principals / principal_clearances / object_markings / grants / field_policies / access_log |
✅ 已实现:授权检查、过滤、脱敏、审计 |
公理与 OWL 导出(2026-09-20):
/ontology/export现支持 OWL 公理(disjointWith/equivalentClass/inverseOf/FunctionalProperty);object_types.axioms字段随 schema_versions 写入。
1.2 标准兼容元数据端点(GB/T 48000.3-2026 通用建模方法)
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/ontology/meta |
本体自描述:base_iri(ONTOLOGY_BASE_IRI 配置)+ profile + 服务版本;类型/属性/链接的 iri = base_iri + # + api_name,创建即固化、存量启动回填;默认 ONTOLOGY_BASE_IRI 为 example.org 占位,生产部署应改为自有命名空间 |
| GET | /api/v1/ontology/export?format=turtle |
schema 导出为 W3C Turtle(ObjectType→owl:Class、数据属性→owl:DatatypeProperty、LinkType→owl:ObjectProperty),含 OWL 公理(owl:disjointWith/owl:equivalentClass/owl:inverseOf/owl:FunctionalProperty)、rdfs:subClassOf、多语 rdfs:label "…"@lang、xsd:anyURI;Protégé 等标准工具可加载;单向导出,其余 format 返回 400 |
| GET | /api/v1/ontology/object-types · /api/v1/ontology/object-types/:name |
返回含 axioms 与 parent_api_name(属性含 inherited 标;类型/属性/链接均回显 display_name_lang) |
| POST / PUT | /api/v1/ontology/object-types[/:name] |
接受 axioms(五类公理声明)、parent(SubclassOf,环/自指/父子互斥守卫)、display_name_lang(BCP47 典型形式标签,非法 400) |
| POST / PUT | /api/v1/ontology/object-types/:name/properties · /api/v1/ontology/properties/:id(link-types 同) |
接受 display_name_lang、data_type=uri(写入校验绝对 URI) |
| POST | /api/v1/links · /api/v1/connector/links/batch |
受 functionalLinks 公理边写入校验(同一功能性链接类型:同源指向不同 target 拒绝,无 validate_axioms 后门) |
| GET | /api/v1/ontology/versions?kind=&name=&limit=&offset= |
schema 版本流水(最新在前);GET /api/v1/ontology/versions/:version 按版本读回该次变更完整 details(含 before/after 快照,JSON,不走快照路由) |
2. 种子本体
为方便"docker run 一开箱就能看到东西",极简种子会自动灌入:
- 1 个对象类型:「合作企业」(MemberOrg)
- 3 条示例实例:纯平台 A、合作伙伴 B、合作伙伴 C(占位,可在管理界面一键删干净)
种子是占位演示,不代表任何业务假设。你可以:
- 在管理界面「本体编辑 → 对象类型」一键删除种子类型
- 直接进入「实例管理 → 合作企业」批量清空
- 或把
SEED_ON_START=false设成环境变量,跳过种子只留空库
平台对采用方完全中性。采用方(例如尚数网做数据要素、可信数据空间;某 CRM 团队做客户/合同;个人用户做笔记/人脉)各自按自己的业务建自己的对象类型与实例,互不耦合。
3. 快速开始
3.1 推荐构建与运行
./build.sh
./run.sh
build.sh 会依次完成:
- 构建 Vue 前端
- 将
web/dist同步到server/webroot - 编译 Go 二进制到
bin/server
run.sh 默认连接:
postgres://ssw:[email protected]:5432/ssw-ontology?sslmode=disable
如要连其他 PG 实例,覆盖 .env 里的 DATABASE_URL(格式:postgres://user:pwd@host:port/dbname?sslmode=disable)。
默认监听 8081。如果该端口被本机其他服务占用,可临时切换:
HTTP_PORT=9090 ./bin/server
访问:
http://127.0.0.1:8081
使用 127.0.0.1 可绕过部分本机 HTTP 代理对 localhost 的影响。
3.2 关键环境变量
| 变量 | 说明 | 默认 |
|---|---|---|
DATABASE_URL |
PostgreSQL 连接串 | workspace PostgreSQL |
HTTP_PORT |
HTTP 监听端口 | 8081 |
SEED_ON_START |
本体为空时灌入种子 | true |
ARCHIVE_DIR |
知识文件归档目录 | ../archive |
AI_ENABLED |
是否启用 OpenAI 兼容大模型 | false |
AI_BASE_URL / AI_KEY / AI_MODEL |
大模型服务配置 | 空 / 默认 |
ONTOLOGY_BASE_IRI |
本体全局 IRI 命名空间(类型/属性/链接的 iri = 该值 + # + api_name;改配置不回写存量) |
http://example.org/standard-ontology# |
ALLOW_CORS |
是否允许跨域 | 按配置加载 |
主体(manager/connector/public/ingest)的 API Key 不再通过环境变量配置:首次启动时由 server 自动随机生成并打印到 stdout;后续在管理界面的 Access Control 页查看、重置或清空。生产环境请妥善保存首次启动日志,并在能登录后立即修改默认密码(默认
changeme)。
前端修改后不能只替换磁盘上的静态文件。由于
server/main.go使用//go:embed all:webroot,必须重新执行./build.sh或完成"前端 build → 同步 webroot → go build"。
4. Web UI
当前 Web UI 包含以下入口:
- 概览:对象类型、实例、关系和摄取概览。
- 本体编辑:Object / Property / Link / Action / Function / Interface 元数据 + Materialization / Backing Source Tab。
- 实例管理:按对象类型创建、编辑、删除对象实例;头部嵌入 💡 SuggestionHints(基于
when_to_suggest推 Function / Action)。 - 知识管理:
- 知识文件目录树 + 文件列表
- 上传、建子文件夹、简单预览、单条或批量 AI 提取
- 删除文件时级联清理关联对象、链接和摄取记录
- 数据连接资源定义、导入本体、提取和级联删除
- 关系图谱:可视化对象节点和链接边,按当前主体权限过滤。
- 连接器:只读 REST / MCP 端点查询 + 工具清单 + 测试参数。
- 访问控制:
- Principal 主体
- Grant 授权
- 对象 Marking
- 字段 FieldPolicy
- Dynamic Security 执行日志 + 24 小时统计
5. 提示调度(Palantir "when_to_suggest" 对标)
平台支持按上下文推 Function / Action,模仿 Palantir AIP 的"在正确时机推正确工具"体验:
- Function/Action 元数据带
when_to_suggest(触发条件 JSONB)+llm_tool_description(给 LLM 看的工具描述) GET /api/v1/ontology/suggestions?context=object_view&type=TrustedDataSpace返回当前上下文下建议调用的 Function + Action 列表- 前端用统一组件
SuggestionHints.vue嵌入实例详情头部和 AI 摄取页,根据context自动出现 💡 提示
6. 连接器 REST / MCP API(只读,经 Dynamic Security)
所有查询都会经过当前主体的 Dynamic Security 决策:授权检查 → 对象标记过滤 → 字段策略脱敏 → 审计日志。
6.1 REST 端点
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/connector/object-types |
列出对象类型及属性定义 |
| GET | /api/v1/connector/objects/:type |
按类型列出可见对象 |
| GET | /api/v1/connector/object/:type/:pk |
获取单个可见对象 |
| GET | /api/v1/connector/search?q=&type=&field=&limit= |
关键词检索可见对象 |
| GET | /api/v1/connector/facets?type= |
获取过滤维度取值 |
| POST | /api/v1/connector/query |
按类型+属性过滤,可展开关系邻居 |
| GET | /api/v1/connector/graph?type=&pk= |
查询对象关系图 |
6.2 MCP 端点(Streamable HTTP)
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/mcp/manifest |
人类可读 MCP 自描述(供 WorkBuddy 注册) |
| POST | /api/v1/mcp |
JSON-RPC 2.0 Streamable HTTP(按 Accept 自动 JSON/SSE) |
原生暴露 24 个工具(2026-09-05),按组分类:
| 组 | 工具 |
|---|---|
| 查询(只读) | get_object_types / get_objects_by_type / get_object / search_ontology / get_facets / query_related / whoami |
| 知识管理 | km_list_tree / km_list_files / km_create_folder / km_upload_markdown / km_extract / km_delete |
| 类型管理 | create_object_type / create_link_type / update_enum |
| 实例写入 | create_object / batch_create_objects / batch_create_links / create_link / delete_object / restore_object / get_object_history / find_duplicates |
实例写入的语义约定(merge 默认、软删除、source_ts 乱序丢弃、delete propagate 血统传播、审计回滚)详见 INSTANCE_GOVERNANCE.md。
6.3 一键注册到 WorkBuddy
{
"mcpServers": {
"ontology": {
"url": "http://127.0.0.1:8081/api/v1/mcp"
}
}
}
然后在 WorkBuddy 的自定义连接器入口中信任该 MCP 服务。远程部署时将 127.0.0.1:8081 替换为实际可访问地址;如果启用了连接器密钥,按 WorkBuddy 的 MCP 配置增加请求头。
7. Function / Interface / Action
7.1 Function
Function 是可复用计算单元(对应 Palantir Function 语义):
- 不等于 Action:Action 通常由用户触发并产生副作用;Function 通常是类型化、可复用、偏纯计算的能力
- 当前 4 个 builtin:
mask_field_by_policy:按字段策略对属性脱敏compute_object_link_strength:根据对象关联数量计算关系强度compute_data_asset_value:按对象属性进行启发式资产价值估算derive_object_completeness:计算对象必填属性完整度
- 可调为 MCP 工具(待办)
调用示例:
curl -X POST \
http://127.0.0.1:8081/api/v1/ontology/function-types/derive_object_completeness/invoke \
-H 'Content-Type: application/json' \
-d '{"object_type":"TrustedDataSpace","object_pk":"tds_logistics"}'
7.2 Interface
interface_types 用来描述外部可调用接口的协议、方法、路径、输入输出和 MCP 暴露属性。启动时自动登记 6 个连接器 REST 接口,作为 Interface 元数据,而非另建一套查询逻辑。
新增字段:shared_properties(多态共享字段集)、parent_interface_id(继承父接口)。
7.3 Action(完整契约,P0-1)
Action 在本平台是"用户主动触发的业务动作",带副作用;可关联一个 Function 形成 FBA(Function-backed Action):
- 完整契约字段:
submission_criteria:提交参数校验规则(JSONB)side_effects:副作用声明(JSONB)impl_function_id:绑定的 Function id(FBA 模式)return_type:返回类型when_to_suggest:触发条件 JSONBllm_tool_description:给 LLM 看的工具描述
- 执行端点:
POST /api/v1/objects/:type/:pk/actions/:action,支持dry_run/ FBA / 声明式三种分支
8. Materialization / Backing Source(P2 数据管道层)
为应对"多表 join 频次高、延迟敏感"的场景,平台引入物化层:
- Materialization:定义物化数据集的源对象类型 + projection(JSONB 描述投影哪些字段)+ refresh_strategy(
manual/interval:60s)+ is_active。Server 启动时开启 60s ticker scheduler 自动 refresh。 - Backing Source:描述外部数据源(file / database / api / other),含
field_mapping(字段映射)+materialization_id(可挂到物化上做 ETL)。
CRUD 端点:
GET / POST / DELETE /api/v1/ontology/materializations
POST /api/v1/ontology/materializations/:name/refresh
GET /api/v1/ontology/materializations/:name/rows
GET / POST / DELETE /api/v1/ontology/backing-sources
9. Dynamic Security 访问控制
安全控制不是普通业务对象,而是平级于对象、链接、动作的治理元能力。
9.1 四类治理原语
| 原语 | 作用 |
|---|---|
| Principal | 请求主体,如 manager / connector / public 或自定义主体 |
| Marking | 对象访问标记,默认使用 L0 ~ L4 |
| Grant | (principal, action, scope) → allow/deny 授权规则;deny 优先 |
| FieldPolicy | 字段级 redact / hide / full 策略 |
9.2 运行时处理链
请求
→ 识别 principal
→ 检查 grant
→ 检查 object marking
→ 过滤对象 / 关系
→ 应用字段策略
→ 写入 access_log(allow/deny/filter/redact 四种 decision)
→ 返回结果
覆盖范围:连接器 REST、MCP 工具调用、对象/链接写入、本体 schema 管理、关系图谱、访问控制管理接口。
开发模式下,当 manager 主体的 api_key 尚未配置(全新库、首次启动前)时,匿名请求按 manager 处理以保持本地开发体验;首次启动后 server 会自动随机生成所有内置主体的 api_key 并打印到 stdout,之后真实鉴权默认生效,匿名请求回退为 public(L0 只读)。生产环境应通过 HTTPS 或反向代理保护服务,并妥善保存首次启动日志。
9.3 相关接口
GET /api/v1/access/whoami
GET /api/v1/access/principals
POST /api/v1/access/principals
GET /api/v1/access/principals/:name
PUT /api/v1/access/principals/:name
DELETE /api/v1/access/principals/:name
GET /api/v1/access/principals/:name/clearances
PUT /api/v1/access/principals/:name/clearances
GET /api/v1/access/grants
POST /api/v1/access/grants
DELETE /api/v1/access/grants/:id
GET /api/v1/access/markings
GET /api/v1/access/objects/:type/:pk/markings
PUT /api/v1/access/objects/:type/:pk/markings
GET /api/v1/access/field-policies
POST /api/v1/access/field-policies
DELETE /api/v1/access/field-policies/:id
GET /api/v1/access/preview?principal=
GET /api/v1/access/log
GET /api/v1/access/log/stats
10. AI 与知识管理
AI 摄取支持三类入口(2026-08-24 新增):
- 粘贴文本:在「知识管理」Tab 直接粘贴资料,指定
directive抽取范围 - 知识文件:archive/ 下批量上传,目录树管理,单条/批量提取
- 数据连接资源:外部数据源(db / api / file / other)定义 → 一键导入本体
流程:资料输入 → AI/启发式抽取 → Suggestion(review/auto) → objects + links(source 溯源)。
source 字段精确记录"哪次 import 写的",删除时按 source 级联清理。修复了 ON CONFLICT 漏 source 字段的 4 处 bug(语义:COALESCE(NULLIF(EXCLUDED.source,''), objects.source),必须加表名限定)。
10.1 大模型配置
生产环境可设置 OpenAI 兼容服务:
AI_ENABLED=true \
AI_BASE_URL=https://api.deepseek.com/v1 \
AI_KEY=your-key \
AI_MODEL=deepseek-chat \
./run.sh
或 Anthropic 兼容(URL 含 /anthropic 时自动切换协议):
AI_ENABLED=true \
AI_BASE_URL=https://api.minimaxi.com/anthropic \
AI_KEY=your-key \
AI_MODEL=MiniMax-M3 \
./run.sh
升级到 2026-08-24 后,系统提示词从 65 行扩到 250+ 行,并支持动态上下文注入:每次 Suggest 前查 db 拉已注册类型清单追加到 system prompt,让 LLM 复用而非重复创建。
11. 项目结构
ontology-platform/
├── build.sh
├── run.sh
├── go.mod / go.sum
├── .gitignore
├── server/
│ ├── main.go # 路由注册
│ ├── config.go
│ ├── db.go # 表结构 + 极简种子
│ ├── models.go # 6 元原语 + Materialization + BackingSource 模型
│ ├── access_control.go # Dynamic Security 核心
│ ├── access_log.go # 审计中间件
│ ├── functions.go # builtin Function registry
│ ├── handlers_access.go # 访问控制 CRUD
│ ├── handlers_action.go # applyAction 端点
│ ├── handlers_functions.go
│ ├── handlers_materialization.go
│ ├── handlers_backing_source.go
│ ├── handlers_suggestions.go # /suggestions 提示调度
│ ├── handlers_mcp.go
│ ├── handlers_connector.go
│ ├── handlers_km.go # 知识管理(recursive/excluded/双向溯源)
│ ├── handlers_ai.go
│ ├── handlers_objects.go # 实例 CRUD(merge 默认 + 软删除过滤 + fields 裁剪)
│ ├── object_upsert.go # 统一写入入口:merge/replace 语义 + source_ts 乱序检查
│ ├── instance_governance.go # 级联删除/批量/审计/回滚/去重/血统传播
│ ├── display_name.go # 显示名物化(title_property 回退链 + 缓存)
│ ├── handlers_ontology.go
│ ├── handlers_ontology_cleanup.go
│ ├── ai/ # AI provider 抽象 + prompt
│ │ ├── ai.go # Suggestion struct 22 字段 + ApplySuggestion
│ │ ├── prompt.go # 250+ 行静态 systemPrompt
│ │ ├── anthropic.go
│ │ ├── openai.go
│ │ └── heuristic.go # 启发式兜底(占位)
│ └── webroot/ # 前端构建产物,内嵌进二进制
├── web/
│ └── src/views/ # 7 个主视图
├── docs/
│ ├── README.md # 本文件
│ ├── INSTANCE_GOVERNANCE.md # 实例治理:merge/软删除/批量/审计/血统传播/source_ts
│ ├── PLAN.md # 设计目标 + 演进计划
│ ├── USAGE.md # 启动 + 连接器 + AI 摄取实战
│ ├── IMPORT.md # 外部数据源导入
│ ├── BACKUP.md # 备份与快照路由
│ ├── TESTING.md # 测试约定
│ ├── WORKBUDDY.md # 一键注册到 WorkBuddy
│ ├── GB_T_48000.3-2026.pdf # 国标全文:标准数字化 第3部分 本体建模要求
│ ├── STANDARD_GB48000_3_2026_GAP.md # 与 GB/T 48000.3-2026 的符合性差距矩阵
│ └── product-intro.html
├── archive/ # 知识文件,AI 摄取来源
├── scripts/ # 通用运维/数据迁移脚本(由各采用方按需编写)
└── bin/ # 编译产物
12. 当前状态与注意事项
- ✅ 6 元原语(Object / Property / Link / Interface / Action / Function)+ Materialization / Backing Source / Dynamic Security 全部实现
- ✅ 提示调度(
when_to_suggest+llm_tool_description)+applyAction端点(支持 dry_run / FBA / 声明式) - ✅ AI 系统提示词升级:250+ 行 + 动态上下文注入,LLM 复用而非重复创建
- ✅ 实例治理(2026-09-05,详见 INSTANCE_GOVERNANCE.md):merge 默认写入 / 软删除墓碑 + 墓碑过滤 / 批量事务接口 / object_changes 字段级审计 + history/restore / find_duplicates 去重提示 / same_as 别名跳转 / 显示名物化(修复 45% 实例 name 为空导致检索"隐身") / source_ts 乱序丢弃 / delete propagate 血统传播删除
- ⚠️ 前端改动后必须重新构建并重新编译 Go 二进制,原因是前端静态资源被
//go:embed内嵌 - ⚠️
script/external_apiFunction 类型目前只完成元数据定义,尚未提供通用脚本沙箱或外部 HTTP 执行器 - ⚠️ Interface 元数据已登记,但并未自动注册所有 Function 为 MCP 工具
- ⚠️ ON CONFLICT upsert 路径已统一 source 字段语义(2026-08-24 修复 4 处);写入时
objects.source表名必须限定,否则 PostgreSQL 报 ambiguous