沙数网 shangshuwang.cn mobileApi 专用 importer 不属于通用本体平台的一部分, 按业务专用代码剥离。 - 删除 importer/import-from-xeo.js(200 行, Node 脚本) - 删除空目录 importer/ 文档同步: - docs/README.md 项目结构去掉 importer/ 行 - docs/IMPORT.md 删除"尚数网示例"整节,改为通用 Node 骨架 历史信息归档在 .workbuddy/memory/2026-08-24.md (字段映射表 / 抓取器路径 / 重新启用方式)
406 lines
17 KiB
Markdown
406 lines
17 KiB
Markdown
# 通用本体元数据平台 · 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 接口契约
|
||
- **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 |
|
||
| Property | `properties` | ✅ 已实现,含 format / default_value / indexable / vector_index / backing_column;data_type 扩展 geoshape / geopoint / media / timeseries / timestamp |
|
||
| Link | `link_types` / `links` | ✅ 已实现,含 directional;链接本身可带字段(link_properties 子表) |
|
||
| 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` | ✅ 已实现:授权检查、过滤、脱敏、审计 |
|
||
|
||
---
|
||
|
||
## 2. 种子本体
|
||
|
||
为方便"docker run 一开箱就能看到东西",**极简种子**会自动灌入:
|
||
|
||
- 1 个对象类型:「合作企业」(MemberOrg)
|
||
- 3 条示例实例:纯平台 A、合作伙伴 B、合作伙伴 C(占位,可在管理界面一键删干净)
|
||
|
||
**种子是占位演示,不代表任何业务假设**。你可以:
|
||
|
||
- 在管理界面「本体编辑 → 对象类型」一键删除种子类型
|
||
- 直接进入「实例管理 → 合作企业」批量清空
|
||
- 或把 `SEED_ON_START=false` 设成环境变量,跳过种子只留空库
|
||
|
||
> 平台对采用方完全中性。采用方(例如尚数网做数据要素、可信数据空间;某 CRM 团队做客户/合同;个人用户做笔记/人脉)各自按自己的业务建自己的对象类型与实例,互不耦合。
|
||
|
||
---
|
||
|
||
## 3. 快速开始
|
||
|
||
### 3.1 推荐构建与运行
|
||
|
||
```bash
|
||
./build.sh
|
||
./run.sh
|
||
```
|
||
|
||
`build.sh` 会依次完成:
|
||
1. 构建 Vue 前端
|
||
2. 将 `web/dist` 同步到 `server/webroot`
|
||
3. 编译 Go 二进制到 `bin/server`
|
||
|
||
`run.sh` 默认连接:
|
||
|
||
```text
|
||
postgres://ssw:[email protected]:5432/ssw-ontology?sslmode=disable
|
||
```
|
||
|
||
如要连其他 PG 实例,覆盖 `.env` 里的 `DATABASE_URL`(格式:`postgres://user:pwd@host:port/dbname?sslmode=disable`)。
|
||
|
||
默认监听 `8081`。如果该端口被本机其他服务占用,可临时切换:
|
||
|
||
```bash
|
||
HTTP_PORT=9090 ./bin/server
|
||
```
|
||
|
||
访问:
|
||
|
||
```text
|
||
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` | 大模型服务配置 | 空 / 默认 |
|
||
| `MANAGER_API_KEY` | 生产环境管理主体密钥 | 空 |
|
||
| `CONNECTOR_API_KEY` | 连接器入口密钥 | 空 |
|
||
| `ALLOW_CORS` | 是否允许跨域 | 按配置加载 |
|
||
|
||
> 前端修改后不能只替换磁盘上的静态文件。由于 `server/main.go` 使用 `//go:embed all:webroot`,必须重新执行 `./build.sh` 或完成"前端 build → 同步 webroot → go build"。
|
||
|
||
---
|
||
|
||
## 4. Web UI
|
||
|
||
当前 Web UI 包含以下入口:
|
||
|
||
1. **概览**:对象类型、实例、关系和摄取概览。
|
||
2. **本体编辑**:Object / Property / Link / Action / Function / Interface 元数据 + Materialization / Backing Source Tab。
|
||
3. **实例管理**:按对象类型创建、编辑、删除对象实例;头部嵌入 💡 SuggestionHints(基于 `when_to_suggest` 推 Function / Action)。
|
||
4. **知识管理**:
|
||
- 知识文件目录树 + 文件列表
|
||
- 上传、建子文件夹、简单预览、单条或批量 AI 提取
|
||
- 删除文件时级联清理关联对象、链接和摄取记录
|
||
- 数据连接资源定义、导入本体、提取和级联删除
|
||
5. **关系图谱**:可视化对象节点和链接边,按当前主体权限过滤。
|
||
6. **连接器**:只读 REST / MCP 端点查询 + 工具清单 + 测试参数。
|
||
7. **访问控制**:
|
||
- 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) |
|
||
|
||
原生暴露 6 个查询工具:`get_object_types` / `get_objects_by_type` / `get_object` / `search_ontology` / `get_facets` / `query_related`。
|
||
|
||
### 6.3 一键注册到 WorkBuddy
|
||
|
||
```json
|
||
{
|
||
"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 工具**(待办)
|
||
|
||
调用示例:
|
||
```bash
|
||
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`:触发条件 JSONB
|
||
- `llm_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 运行时处理链
|
||
|
||
```text
|
||
请求
|
||
→ 识别 principal
|
||
→ 检查 grant
|
||
→ 检查 object marking
|
||
→ 过滤对象 / 关系
|
||
→ 应用字段策略
|
||
→ 写入 access_log(allow/deny/filter/redact 四种 decision)
|
||
→ 返回结果
|
||
```
|
||
|
||
覆盖范围:连接器 REST、MCP 工具调用、对象/链接写入、本体 schema 管理、关系图谱、访问控制管理接口。
|
||
|
||
开发模式下,当 `MANAGER_API_KEY` 与 `CONNECTOR_API_KEY` 都为空时,匿名请求按 `manager` 处理以保持本地开发体验。生产环境应设置密钥并通过 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 新增):
|
||
|
||
1. **粘贴文本**:在「知识管理」Tab 直接粘贴资料,指定 `directive` 抽取范围
|
||
2. **知识文件**:archive/ 下批量上传,目录树管理,单条/批量提取
|
||
3. **数据连接资源**:外部数据源(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 兼容服务:
|
||
|
||
```bash
|
||
AI_ENABLED=true \
|
||
AI_BASE_URL=https://api.deepseek.com/v1 \
|
||
AI_KEY=your-key \
|
||
AI_MODEL=deepseek-chat \
|
||
./run.sh
|
||
```
|
||
|
||
或 Anthropic 兼容(URL 含 `/anthropic` 时自动切换协议):
|
||
|
||
```bash
|
||
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. 项目结构
|
||
|
||
```text
|
||
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 # 知识管理
|
||
│ ├── handlers_ai.go
|
||
│ ├── handlers_objects.go # 注意 source 字段语义
|
||
│ ├── 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 # 本文件
|
||
│ ├── PLAN.md # 设计目标 + 演进计划
|
||
│ ├── USAGE.md # 启动 + 连接器 + AI 摄取实战
|
||
│ ├── IMPORT.md # 外部数据源导入
|
||
│ ├── update/ # 升级说明(按日期)
|
||
│ └── 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 复用而非重复创建
|
||
- ⚠️ 前端改动后必须重新构建并重新编译 Go 二进制,原因是前端静态资源被 `//go:embed` 内嵌
|
||
- ⚠️ `script` / `external_api` Function 类型目前只完成元数据定义,尚未提供通用脚本沙箱或外部 HTTP 执行器
|
||
- ⚠️ 当前 MCP 原生暴露 6 个查询工具;Interface 元数据已登记,但并未自动注册所有 Function 为 MCP 工具
|
||
- ⚠️ ON CONFLICT upsert 路径已统一 source 字段语义(2026-08-24 修复 4 处);写入时 `objects.source` 表名必须限定,否则 PostgreSQL 报 ambiguous
|
||
|
||
详细升级步骤与迁移指南:[docs/update/2026-08-24.md](update/2026-08-24.md)。 |