Files
ssw-ontology/docs/PLAN.md
T
ssw f1b687c2d2 目录扁平化:子目录内容提升至仓库根,文档归入 docs/
- 将 shangshu-ontology/ 子目录内容移至仓库根一级
- 修复 run.sh 的 REPO_ROOT 计算(扁平化后不再需要 cd ..),ARCHIVE_DIR 正确指向仓库根/archive
- 文档(README/PLAN/USAGE/IMPORT/product-intro)移至 docs/,同步更新结构树与导入命令中的旧路径
- 新增根 README.md 索引指向 docs/
- 新增 .gitignore:忽略 bin/、web/node_modules/、web/dist/、server/webroot/、.env、.workbuddy/ 等噪音
- main.go 的 ARCHIVE_DIR fallback 基于可执行文件相邻上级,扁平化后仍正确,无需改动
2026-08-07 14:21:34 +08:00

11 KiB
Raw Blame History

尚数网本体管理平台 · 设计与演进计划

本文件描述当前实现的真实边界、架构分层和后续演进方向。实现状态以代码、数据库 schema 和运行接口为准;没有实现的能力明确标记为“预留”或“待办”。


1. 设计目标

尚数网本体管理平台的核心目标是:

  1. 用统一本体描述数据要素、可信数据空间、组织、服务、产品及其关系;
  2. 用 Action 和 Function 表达业务变化与可复用计算;
  3. 用 Interface 对外提供稳定、可发现的 API / MCP 契约;
  4. 用 Dynamic Security 控制本体信息的合理、安全使用,而不是把“安全策略”简单灌成业务对象;
  5. 让人工编辑、AI 摄取、文件提取和外部连接资源导入共同写入同一个 PostgreSQL 本体真源。

2. 总体架构

                         ┌───────────────────────────┐
                         │   Ontology Metadata Core   │
                         │      本平台承担 OMS 职责     │
                         └──────────────┬────────────┘
                                        │
             ┌──────────────────────────┴──────────────────────────┐
             │                                                     │
   ┌─────────┴─────────┐                               ┌───────────┴──────────┐
   │ Semantic 语义层     │                               │ Kinetic 行为层        │
   │ 描述“有什么/什么状态” │                               │ 描述“如何计算/如何变化”  │
   ├────────────────────┤                               ├──────────────────────┤
   │ Object              │                               │ Action               │
   │ Property            │                               │ Function             │
   │ Link                │                               │ Dynamic Security     │
   │ Interface           │                               │ (运行时授权执行)       │
   └─────────┬──────────┘                               └───────────┬──────────┘
             └──────────────────────────┬──────────────────────────┘
                                        ▼
                         PostgreSQL 单一真源 + Go API/MCP

2.1 核心组件与当前实现

组件 语义 当前实现 状态
Object 对象类型和对象实例 object_types / objects 已实现
Property 对象字段定义 properties 已实现
Link 对象之间的有向关系 link_types / links 已实现
Action 用户主动触发的业务动作 action_types、AI 摄取和管理写接口 已实现元数据,真实业务编排持续扩展
Function 可复用计算单元 function_types + Go builtin registry 已实现 builtin invoke

2.2 扩展组件

组件 语义 当前实现 状态
Interface REST / MCP 接口契约 interface_types 已实现元数据,自动登记 6 个连接器接口
Dynamic Security 请求级授权与安全执行 principals、principal_clearances、object_markings、grants、field_policies、access_log 已实现

3. 数据层与治理层边界

3.1 业务本体层

业务本体继续使用对象、属性和链接表达:

  • 数据资源、数据产品、数据需求;
  • 可信数据空间、数据交易所、会员单位;
  • 核心服务、应用场景、分支机构、密算一体机;
  • 知识产权、新闻文章等扩展实体。

3.2 访问控制不是业务对象类型

早期曾尝试增加一组 DataClassification、AccessControlPolicy 等安全类对象。该方案已撤回,因为它只能“描述存在某个策略”,并不能自动阻止未授权访问。

当前采用治理元能力:

Principal + Grant + Marking + FieldPolicy
                         │
                         ▼
                 Dynamic Security Runtime
                         │
                         ▼
              过滤对象、关系、字段并记录审计

因此,安全控制与 object_types、link_types、action_types 处于同一元模型层面,但不污染尚数网业务对象模型。


4. 当前已完成能力

P0:Function 元原语

数据库:function_types

字段重点:

  • api_name、display_name、description;
  • inputs、outputs 类型化 JSON 契约;
  • impl_kind:当前支持 builtin 元数据;script / external_api 仅预留;
  • impl_ref、is_pure、builtin_fn。

已注册 4 个 builtin:

  1. mask_field_by_policy;
  2. compute_object_link_strength;
  3. compute_data_asset_value;
  4. derive_object_completeness。

当前接口:

GET    /api/v1/ontology/function-types
GET    /api/v1/ontology/function-types/:name
POST   /api/v1/ontology/function-types
DELETE /api/v1/ontology/function-types/:name
POST   /api/v1/ontology/function-types/:name/invoke

说明:Function 当前可以被 HTTP 调用;尚未实现通用的 Action 编排 DSL,也没有把 Function 自动加入 MCP 工具列表。

P1:Interface 元原语

数据库:interface_types

记录接口协议、HTTP 方法、路径、输入输出、鉴权要求、是否暴露到 MCP、后端绑定引用等信息。

启动时自动登记 6 个连接器接口:

  • list_object_types;
  • list_objects;
  • get_object;
  • search_ontology;
  • get_facets;
  • query_related。

当前接口:

GET    /api/v1/ontology/interface-types
GET    /api/v1/ontology/interface-types/:name
POST   /api/v1/ontology/interface-types
DELETE /api/v1/ontology/interface-types/:name

说明:Interface 元数据用于发现和管理契约;MCP 的实际工具清单仍由 mcpToolList() 维护,尚未完全改为数据库驱动。

P2: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、耗时。

当前审计接口:

GET /api/v1/access/log
GET /api/v1/access/log/stats

5. 主要请求路径

5.1 管理路径

管理路径由 managerAuth 保护。默认开发模式下,当两个 API key 都为空时,主体默认为 manager;生产环境应设置密钥。

/api/v1/ontology/*
/api/v1/objects*
/api/v1/links*
/api/v1/ai/*
/api/v1/km/*
/api/v1/access/*(whoami 除外)

5.2 连接器路径

/api/v1/connector/*
/api/v1/mcp

连接器使用 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 溯源

7. 构建、部署与验证

构建链

./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

本地启动

./run.sh

或:

HTTP_PORT=8081 ./bin/server

最小验证

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 二进制。