Files
ssw-ontology/docs/README.md
T

422 lines
19 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
> 把业务实体、属性、关系、动作、函数和接口统一纳入本体元数据,并通过访问控制与运行时审计控制信息的安全使用。
>
> **设计对标 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` | 大模型服务配置 | 空 / 默认 |
| `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 包含以下入口:
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) |
原生暴露 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](INSTANCE_GOVERNANCE.md)。
### 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 尚未配置(全新库、首次启动前)时,匿名请求按 `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 新增):
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 # 知识管理(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](INSTANCE_GOVERNANCE.md)):merge 默认写入 / 软删除墓碑 + 墓碑过滤 / 批量事务接口 / object_changes 字段级审计 + history/restore / find_duplicates 去重提示 / same_as 别名跳转 / 显示名物化(修复 45% 实例 name 为空导致检索"隐身") / source_ts 乱序丢弃 / delete propagate 血统传播删除
- ⚠️ 前端改动后必须重新构建并重新编译 Go 二进制,原因是前端静态资源被 `//go:embed` 内嵌
- ⚠️ `script` / `external_api` Function 类型目前只完成元数据定义,尚未提供通用脚本沙箱或外部 HTTP 执行器
- ⚠️ Interface 元数据已登记,但并未自动注册所有 Function 为 MCP 工具
- ⚠️ ON CONFLICT upsert 路径已统一 source 字段语义(2026-08-24 修复 4 处);写入时 `objects.source` 表名必须限定,否则 PostgreSQL 报 ambiguous