16 KiB
设计与演进计划 · Ontology Platform
本文件描述当前实现的真实边界、架构分层和后续演进方向。实现状态以代码、数据库 schema 和运行接口为准;没有实现的能力明确标记为"预留"或"待办"。
1. 设计目标
通用本体元数据平台的核心目标是:
- 用统一本体描述业务实体(数据资源/产品/空间/组织/人/项目/知识/...)、属性、关系;
- 用 Action 和 Function 表达业务变化与可复用计算;
- 用 Interface 对外提供稳定、可发现的 API / MCP 契约;
- 用 Dynamic Security 控制本体信息的合理、安全使用,而非把"安全策略"简单灌成业务对象;
- 让人工编辑、AI 摄取、文件提取、外部数据源导入共同写入同一个 PostgreSQL 本体真源;
- 让任何采用方(企业部门、垂直业务、个人知识库)都能用同一套平台管理自己的本体,而非绑定到某一类业务。
设计对标 Palantir Ontology——6 元原语(Semantic + Kinetic) + Dynamic Security + Function-backed Action + Materialization。
2. 总体架构
┌───────────────────────────┐
│ Ontology Metadata Core │
│ 本平台承担 OMS 职责 │
└──────────────┬────────────┘
│
┌──────────────────────────┴──────────────────────────┐
│ │
┌─────────┴─────────┐ ┌───────────┴──────────┐
│ Semantic 语义层 │ │ Kinetic 行为层 │
│ 描述"有什么/什么状态" │ │ 描述"如何计算/如何变化" │
├────────────────────┤ ├──────────────────────┤
│ Object │ │ Action │
│ Property │ │ Function │
│ Link │ │ FBA (Function-backed │
│ Interface │ │ Action) │
│ │ │ Materialization │
└─────────┬──────────┘ └───────────┬──────────┘
└──────────────────────────┬──────────────────────────┘
▼
PostgreSQL 单一真源 + Go API/MCP
2.1 核心组件与当前实现
| 组件 | 语义 | 当前实现 | 状态 |
|---|---|---|---|
| Object | 对象类型和对象实例 | object_types / objects |
✅ 已实现,含 title_property / subtitle_property / color / primary_key |
| Property | 对象字段定义 | properties |
✅ 已实现,含 format / default_value / indexable / vector_index / backing_column |
| Link | 对象之间的有向关系 | link_types / links / link_properties |
✅ 已实现,含 directional;链接本身可带字段 |
| Action | 用户主动触发的业务动作 | action_types + applyAction 端点 |
✅ 已实现完整契约 + FBA 执行链 |
| Function | 可复用计算单元 | function_types + Go builtin registry |
✅ 已实现 4 个 builtin invoke + when_to_suggest |
2.2 扩展组件
| 组件 | 语义 | 当前实现 | 状态 |
|---|---|---|---|
| Interface | REST / MCP 接口契约 | interface_types |
✅ 已实现,含 shared_properties + parent_interface_id |
| Materialization | 物化数据集 | materializations / materialization_rows |
✅ 已实现 + 60s ticker scheduler |
| Backing Source | 同步源 | backing_sources + 字段映射 |
✅ 已实现 |
| Dynamic Security | 请求级授权与安全执行 | principals / principal_clearances / object_markings / grants / field_policies / access_log |
✅ 已实现 |
3. 数据层与治理层边界
3.1 业务本体层
业务本体继续使用对象、属性和链接表达:
- 企业数据资产盘点:数据资源 / 数据产品 / 数据需求 / 数据空间
- CRM/销售:客户 / 合同 / 订单 / 产品
- 知识管理:文档 / 概念 / 人 / 项目
- 可信数据空间:空间 / 会员 / 设备 / 政策
- 个人/小团队:项目 / 任务 / 笔记 / 人脉
业务类型与平台耦合为零。
3.2 访问控制不是业务对象类型
早期曾尝试增加一组 DataClassification、AccessControlPolicy 等安全类对象。该方案已撤回,因为它只能"描述存在某个策略",并不能自动阻止未授权访问。
当前采用治理元能力:
Principal + Grant + Marking + FieldPolicy
│
▼
Dynamic Security Runtime
│
▼
过滤对象、关系、字段并记录审计
因此,安全控制与 object_types、link_types、action_types 处于同一元模型层面,但不污染业务对象模型——无论业务是数据要素、CRM 还是个人笔记,治理都按同一套原语执行。
4. 当前已完成能力(按 Palantir Ontology 对标)
P0:Function / Action 元原语 + 提示调度
数据库:function_types、action_types
字段重点:
api_name/display_name/descriptioninputs/outputs类型化 JSON 契约when_to_suggestJSONB(Palantir "when to suggest" 语义触发条件)llm_tool_descriptionTEXT(给 LLM 看的工具描述)submission_criteria/side_effectsJSONB(Action 完整契约)impl_function_idBIGINT FK function_types(FBA)return_typeTEXTimpl_kind:当前支持builtin元数据;script/external_api仅预留
已注册 4 个 builtin Function:
mask_field_by_policycompute_object_link_strengthcompute_data_asset_valuederive_object_completeness
P1:Interface 元原语 + 多态
数据库:interface_types
记录接口协议、HTTP 方法、路径、输入输出、鉴权要求、是否暴露到 MCP、后端绑定引用等。
启动时自动登记 6 个连接器接口:
list_object_typeslist_objectsget_objectsearch_ontologyget_facetsquery_related
新增字段:shared_properties(多态共享字段集)、parent_interface_id(继承父接口)。
P2:Materialization 物化层 + Backing Source 同步源
为应对"多表 join 频次高、延迟敏感"的场景:
- Materialization:定义源对象类型 + projection(JSONB 描述投影哪些字段)+ refresh_strategy + is_active。Server 启动时开启 60s ticker scheduler 自动 refresh,也可手动触发。
- Backing Source:描述外部数据源(file / database / api / other),含
field_mapping(字段映射)+materialization_id(可挂到物化上做 ETL)。
P3:Dynamic Security 审计
静态规则:
principals:主体principal_clearances:主体可读取的 marking 集合object_markings:对象访问标记grants:主体、动作、范围和 allow/denyfield_policies:字段级redact/hide/full
运行时:
principalFromRequest
→ authzOf
→ CanRead / CanWrite / CanExecute
→ marking 过滤
→ field policy 脱敏
→ access_log
access_log 记录:
- principal、HTTP method、path
- target object 和 action
- decision:
allow/deny/filter/redact - matched grants、matched markings、耗时
P4:实例治理与血统治理(2026-09-05,对标 Palantir)
来源:本体外部应用实操反馈 + 全库扫描复核,完整需求与验证清单见 INSTANCE_GOVERNANCE.md。
- 写入安全:
create_object默认 merge(不丢字段),replace=true才全量替换且回显 removed;source_ts乱序写入丢弃(Palantir source timestamp 语义) - 软删除:
objects.deleted真实列;消费方默认不见墓碑;restore_object 从 object_changes 快照回滚 - 审计:
object_changes字段级 diff(create/update/delete/restore,含 actor/via/source);get_object_history查历史 - 批量:objects/links 单事务批量接口(上限 500),逐条明细,乱序条目
stale_skipped - 去重:新建时返回
possible_duplicates(归一化名 + Levenshtein);same_as别名跳转 canonical - 血统传播:delete 默认回显
source_ref,propagate=true沿 source 清理来源文档全部抽取产物(Palantir Lineage-Aware Deletion 语义) - 显示名物化:title_property → name → title → real_name → display_name 回退链,修复存量 45% 实例 name 为空导致默认检索"隐身"
明确不做:时间衰减/降权重(本体是事实库,遗忘要有据可查)、StaleObject 全量乐观并发(写入方少,收益低)。
5. 主要请求路径
5.1 管理路径
管理路径由 managerAuth 保护。默认开发模式下,当两个 API key 都为空时,主体默认为 manager;生产环境应设置密钥。
/api/v1/auth/* # 账号密码登录 + session cookie
/api/v1/ontology/* # 对象/属性/链接/动作/函数/接口/物化/同步源/suggestions
/api/v1/objects* # 实例 CRUD + applyAction
/api/v1/links* # 链接 CRUD
/api/v1/ai/* # AI 摄取
/api/v1/km/* # 知识管理(文件/连接资源)
/api/v1/access/* # 访问控制元原语 + log
5.2 连接器路径
/api/v1/connector/* # 只读 REST
/api/v1/mcp # MCP JSON-RPC 2.0 Streamable HTTP
连接器使用 connectorAuth 进行入口鉴权,并在 handler 内执行主体授权、对象标记过滤和字段策略。MCP 通过进程内复用连接器 handler,避免 REST 与 MCP 出现两套授权逻辑。
5.3 MCP 当前边界
MCP 端点支持 JSON-RPC 2.0 的:
initializepingtools/listtools/call- 通知消息
当前原生工具为 6 个只读查询工具。Function 的 HTTP invoke 已完成,但尚未自动注册为 MCP 工具(待办)。
6. 知识管理与本体更新
知识管理是"双 tab"结构:
Tab 1:知识文件
archive/默认归档目录- 目录树、文件列表、上传、建子文件夹
- 文本类文件简单预览
- 单条或批量 AI 提取
- 文件记录保存提取信息
- 删除文件级联删除关联对象、关系和摄取记录
Tab 2:数据连接资源
- 定义外部数据库、API、文件或其他资源
- 导入本体生成 DataResource 等实例
- 支持提取、删除和关联记录级联清理
AI 更新路径:
资料 / 文件 / 连接资源
▼
AI 或启发式抽取
▼
Suggestion
┌──────┴──────┐
review auto
仅生成建议 直接应用
▼
objects / links + source 溯源
关键修复(2026-08-24):所有
ON CONFLICT ... DO UPDATE SET路径必须带source=COALESCE(NULLIF(EXCLUDED.source,''), objects.source)语义,且必须加表名限定objects.source,否则 PostgreSQL 报column reference 'source' is ambiguous。
7. 构建、部署与验证
7.1 构建链
./build.sh
等价核心步骤:
cd web
npm install
npm run build
cd ..
rm -rf server/webroot
cp -r web/dist server/webroot
go build -o bin/server ./server
7.2 本地启动
./run.sh
或:
HTTP_PORT=8081 ./bin/server
7.3 最小验证
curl --noproxy '*' http://127.0.0.1:8081/health
curl --noproxy '*' http://127.0.0.1:8081/api/v1/ontology/function-types
curl --noproxy '*' http://127.0.0.1:8081/api/v1/ontology/interface-types
curl --noproxy '*' http://127.0.0.1:8081/api/v1/access/whoami
curl --noproxy '*' -X POST http://127.0.0.1:8081/api/v1/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
8. 后续计划
优先级 P1:治理能力完善
- 将 Interface 元数据与 grant / marking 直接关联,实现接口级授权
- 将 MCP 工具清单改为数据库驱动,同时保持 builtin 工具的安全白名单
- 增加对象、链接、schema 变更历史(schema 版本快照 + 按版本读回,与 GB/T 48000.3-2026 差距分析 P1 #3 合并推进,见 STANDARD_GB48000_3_2026_GAP.md §5.4)
- 版本流补钩——merge 清理与 AI 摄取等旁路 schema 写入接入 schemaAudit,使
schema_versions覆盖全部写入路径 - 让审计日志记录更细粒度的命中规则和结果摘要
- IRI + 命名空间机制(GB/T 48000.3-2026 差距分析 P1 #1):
base_iri配置 + 类型/属性/链接生成全球唯一 IRI,增量列不破坏现有api_name唯一约束 - OWL/Turtle 导出(GB/T 48000.3-2026 差距分析 P1 #2):
GET /api/v1/ontology/export?format=turtle单向导出(当前仅 turtle,其余 format 400;JSON-LD 列为后续项),让本体可在 Protégé 等 W3C 工具链中查看;依赖 IRI 机制
优先级 P2:行为层深化
- Action 调用 Function 的编排定义
- 公理/约束声明机制(差距分析 P2 #4)——已落地(2026-09-20),见 CHANGELOG 1.6.0:
object_types.axioms JSONB声明 disjointWith / functionalLinks / inverseOf / equivalentTo / 跨属性日期序(dateOrder),三层校验(形状 / schema 良构 / 写入),统一入口applyObjectUpsert+createLink/batchCreateLinks,随 Turtle 导出为 OWL 公理;Function 输入输出 schema 校验仍为待办(本项合流部分已完成) - Function 结果写回对象的受控流程
script和external_api执行器的隔离、超时、网络和权限控制- 类型继承(SubclassOf,差距分析 P2 #5)、多语标签(#6)、
uri数据类型(#7)——已落地(2026-09-20,M5),见 CHANGELOG 1.6.0:parent_id+ 属性继承(子类型读路径合并祖先属性 + 校验走typeClosure闭包)/ 三表display_name_lang(Turtle@lang)/data_type='uri'(写入校验 +xsd:anyURI)
优先级 P3:平台化
- 外部数据源增量同步和失败重试
- 连接器限流、缓存和分页
- 多租户主体、组织和项目域
- HTTPS、密钥轮换、JWT / OIDC 等生产身份集成
明确不做(本体工程边界)
参照 GB/T 48000.3-2026 差距分析(STANDARD_GB48000_3_2026_GAP.md §5.3):
- 不实现 SHACL 引擎与 OWL2 推理(声明式 axioms 约束 + 导出即可,推理是 SaaS 卖点非本平台职责)
- 不内置任何特定领域的业务类与专有属性(例:标准数字化领域的"标准实体/制定程序/ICS 分类"等)——领域模板最多以独立种子包交付,平台核心保持通用
- 不实现等价类合并查询(只存声明)
9. 文档与实现一致性原则
- 文档只把已验证的能力标为"已实现"
- 预留能力必须明确写"预留"或"待办"
- API 路径以
server/main.go注册路由为准 - 前端能力以
web/src当前视图为准 - 数据表以
server/db.go及运行时迁移为准 - 修改前端后必须重新构建并编译 Go 二进制
- 采用方示例(如尚数网做数据要素、可信数据空间)只作为典型场景之一,不当作唯一目标业务