## 文档重构(5 个 md + 1 个 html) - README.md: '尚数网本体管理平台' → '本体元数据平台 · Ontology Platform' - docs/README.md: 通用化定位,补全 P0/P1/P2 (Palantir Ontology 对标) + Materialization/BackingSource/Suggestions 全清单 - docs/PLAN.md: 通用化设计目标,改为 'Palantir Ontology 对标' 路线图 - docs/USAGE.md: 用通用占位符(项目/空间/组织)替换尚数网具体业务举例 - docs/IMPORT.md: 把 shangshu 当成 '一个采用方示例' 展示通用模式 - docs/product-intro.html: title/brand/hero/场景/footer 全改通用,沙数只作典型场景之一 ## 代码字符串同步去 shangshu - server/main.go: '[boot] 尚数网本体管理平台监听' → '[boot] 本体平台监听' - server/handlers_connector.go: manifest 'server' 字段 → 'ontology-platform' - server/handlers_mcp.go: tool description + serverInfo → 通用 - server/handlers_functions.go: builtin interface description → 通用 - server/handlers_backing_source.go: 注释去 shangshuwang.cn 具体网址 - server/config.go + server/db.go: 注释/seed 数据改占位 (demo_self / demo_partner_a/b) - server/ai/anthropic.go: fallback systemPrompt → '通用本体平台工程师' - server/ai/heuristic.go: 未识别 summary → '本体概念' - server/ai/prompt.go: 静态 systemPrompt 头部 + JSON 示例去 shangshu ## 前端文案同步 - web/src/App.vue: title 改 '本体元数据平台' - web/src/views/LoginView.vue: 登录页 h1 改通用 - web/src/views/OntologyView.vue: backing source placeholder 改 example.com - web/src/components/ReviewWorkbench.vue + useReviewWorkbench.js: '尚数网' → '本体平台' ## 验证 - go build ./server OK - 剩余 '尚数网' / 'shangshu-ontology' 引用: - 文档 README/README/USAGE/PLAN/IMPORT 仅在 '采用方示例' 上下文出现 - 代码注释 sswOntologySystemPrompt 等 identifier 保持不变(避免改动 API 表面) - skill 名 'ssw-ontology-reviewer' 保持不变(已发布技能) Refs: docs/README.md (1.1 元数据组件表)、docs/PLAN.md (4 当前已完成能力)
328 lines
12 KiB
Markdown
328 lines
12 KiB
Markdown
# 设计与演进计划 · 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。详细对标见 `docs/update/2026-08-24.md` 第 9 节。
|
||
|
||
---
|
||
|
||
## 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、耗时
|
||
|
||
---
|
||
|
||
## 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 变更历史
|
||
- 让审计日志记录更细粒度的命中规则和结果摘要
|
||
|
||
### 优先级 P2:行为层深化
|
||
|
||
- Action 调用 Function 的编排定义
|
||
- Function 输入输出 schema 校验
|
||
- Function 结果写回对象的受控流程
|
||
- `script` 和 `external_api` 执行器的隔离、超时、网络和权限控制
|
||
|
||
### 优先级 P3:平台化
|
||
|
||
- 外部数据源增量同步和失败重试
|
||
- 连接器限流、缓存和分页
|
||
- 多租户主体、组织和项目域
|
||
- HTTPS、密钥轮换、JWT / OIDC 等生产身份集成
|
||
|
||
---
|
||
|
||
## 9. 文档与实现一致性原则
|
||
|
||
- 文档只把已验证的能力标为"已实现"
|
||
- 预留能力必须明确写"预留"或"待办"
|
||
- API 路径以 `server/main.go` 注册路由为准
|
||
- 前端能力以 `web/src` 当前视图为准
|
||
- 数据表以 `server/db.go` 及运行时迁移为准
|
||
- 修改前端后必须重新构建并编译 Go 二进制
|
||
- 采用方示例(如尚数网做数据要素、可信数据空间)只作为典型场景之一,不当作唯一目标业务 |