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

12 KiB
Raw Blame History

设计与演进计划 · 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. 总体架构

                         ┌───────────────────────────┐
                         │   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 等安全类对象。该方案已撤回,因为它只能"描述存在某个策略",并不能自动阻止未授权访问。

当前采用治理元能力:

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

运行时:

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;生产环境应设置密钥。

/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 连接器路径

/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 更新路径:

资料 / 文件 / 连接资源
          ▼
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 构建链

./build.sh

等价核心步骤:

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 本地启动

./run.sh

或:

HTTP_PORT=8081 ./bin/server

7.3 最小验证

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