Files
ssw-ontology/docs/PLAN.md
T

353 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 设计与演进计划 · 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 二进制
- 采用方示例(如尚数网做数据要素、可信数据空间)只作为典型场景之一,不当作唯一目标业务