Files
ssw-ontology/docs/PLAN.md
T
admin 1e30d4c355 docs+code: 通用化平台叙事,去掉尚数网业务绑定
## 文档重构(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 当前已完成能力)
2026-08-24 14:04:59 +08:00

328 lines
12 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。详细对标见 `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 二进制
- 采用方示例(如尚数网做数据要素、可信数据空间)只作为典型场景之一,不当作唯一目标业务