# 设计与演进计划 · Ontology Platform > 本文件描述当前实现的真实边界、架构分层和后续演进方向。实现状态以代码、数据库 schema 和运行接口为准;没有实现的能力明确标记为"预留"或"待办"。 --- ## 1. 设计目标 通用本体元数据平台的核心目标是: 1. 用统一本体描述业务实体(数据资源/产品/空间/组织/人/项目/知识/...)、属性、关系; 2. 用 Action 和 Function 表达业务变化与可复用计算; 3. 用 Interface 对外提供稳定、可发现的 API / MCP 契约; 4. 用 Dynamic Security 控制本体信息的合理、安全使用,而非把"安全策略"简单灌成业务对象; 5. 让人工编辑、AI 摄取、文件提取、外部数据源导入共同写入同一个 PostgreSQL 本体真源; 6. 让任何采用方(企业部门、垂直业务、个人知识库)都能用同一套平台管理自己的本体,而非绑定到某一类业务。 > **设计对标 Palantir Ontology**——6 元原语(Semantic + Kinetic) + Dynamic Security + Function-backed Action + Materialization。 --- ## 2. 总体架构 ```text ┌───────────────────────────┐ │ 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` 等安全类对象。该方案已撤回,因为它只能"描述存在某个策略",并不能自动阻止未授权访问。 当前采用治理元能力: ```text 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` / `description` - `inputs` / `outputs` 类型化 JSON 契约 - `when_to_suggest` JSONB(Palantir "when to suggest" 语义触发条件) - `llm_tool_description` TEXT(给 LLM 看的工具描述) - `submission_criteria` / `side_effects` JSONB(Action 完整契约) - `impl_function_id` BIGINT FK function_types(FBA) - `return_type` TEXT - `impl_kind`:当前支持 `builtin` 元数据;`script` / `external_api` 仅预留 已注册 4 个 builtin Function: 1. `mask_field_by_policy` 2. `compute_object_link_strength` 3. `compute_data_asset_value` 4. `derive_object_completeness` ### P1:Interface 元原语 + 多态 数据库:`interface_types` 记录接口协议、HTTP 方法、路径、输入输出、鉴权要求、是否暴露到 MCP、后端绑定引用等。 启动时自动登记 6 个连接器接口: - `list_object_types` - `list_objects` - `get_object` - `search_ontology` - `get_facets` - `query_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/deny - `field_policies`:字段级 `redact` / `hide` / `full` 运行时: ```text 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](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`;生产环境应设置密钥。 ```text /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 连接器路径 ```text /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 的: - `initialize` - `ping` - `tools/list` - `tools/call` - 通知消息 当前原生工具为 6 个只读查询工具。Function 的 HTTP invoke 已完成,但尚未自动注册为 MCP 工具(待办)。 --- ## 6. 知识管理与本体更新 知识管理是"双 tab"结构: ### Tab 1:知识文件 - `archive/` 默认归档目录 - 目录树、文件列表、上传、建子文件夹 - 文本类文件简单预览 - 单条或批量 AI 提取 - 文件记录保存提取信息 - 删除文件级联删除关联对象、关系和摄取记录 ### Tab 2:数据连接资源 - 定义外部数据库、API、文件或其他资源 - 导入本体生成 DataResource 等实例 - 支持提取、删除和关联记录级联清理 AI 更新路径: ```text 资料 / 文件 / 连接资源 ▼ 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 构建链 ```bash ./build.sh ``` 等价核心步骤: ```bash 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 本地启动 ```bash ./run.sh ``` 或: ```bash HTTP_PORT=8081 ./bin/server ``` ### 7.3 最小验证 ```bash 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](STANDARD_GB48000_3_2026_GAP.md) §5.4) - 让审计日志记录更细粒度的命中规则和结果摘要 - **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|jsonld` 单向导出,让本体可在 Protégé 等 W3C 工具链中查看;依赖 IRI 机制 ### 优先级 P2:行为层深化 - Action 调用 Function 的编排定义 - Function 输入输出 schema 校验(与 GB/T 48000.3-2026 差距分析 P2 #4 公理/约束声明机制合流:`axioms JSONB` 声明 disjointWith / functional / inverseOf / 跨属性日期序,写入路径统一校验) - Function 结果写回对象的受控流程 - `script` 和 `external_api` 执行器的隔离、超时、网络和权限控制 - 视需要推进:类型继承(SubclassOf,差距分析 P2 #5)、多语标签(#6)、`uri` 数据类型(#7)——不阻塞 P1 ### 优先级 P3:平台化 - 外部数据源增量同步和失败重试 - 连接器限流、缓存和分页 - 多租户主体、组织和项目域 - HTTPS、密钥轮换、JWT / OIDC 等生产身份集成 ### 明确不做(本体工程边界) 参照 GB/T 48000.3-2026 差距分析([STANDARD_GB48000_3_2026_GAP.md](STANDARD_GB48000_3_2026_GAP.md) §5.3): - 不实现 SHACL 引擎与 OWL2 推理(声明式 axioms 约束 + 导出即可,推理是 SaaS 卖点非本平台职责) - 不内置任何特定领域的业务类与专有属性(例:标准数字化领域的"标准实体/制定程序/ICS 分类"等)——领域模板最多以独立种子包交付,平台核心保持通用 - 不实现等价类合并查询(只存声明) --- ## 9. 文档与实现一致性原则 - 文档只把已验证的能力标为"已实现" - 预留能力必须明确写"预留"或"待办" - API 路径以 `server/main.go` 注册路由为准 - 前端能力以 `web/src` 当前视图为准 - 数据表以 `server/db.go` 及运行时迁移为准 - 修改前端后必须重新构建并编译 Go 二进制 - 采用方示例(如尚数网做数据要素、可信数据空间)只作为典型场景之一,不当作唯一目标业务