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

341 lines
11 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.
# 尚数网本体管理平台 · 设计与演进计划
> 本文件描述当前实现的真实边界、架构分层和后续演进方向。实现状态以代码、数据库 schema 和运行接口为准;没有实现的能力明确标记为“预留”或“待办”。
---
## 1. 设计目标
尚数网本体管理平台的核心目标是:
1. 用统一本体描述数据要素、可信数据空间、组织、服务、产品及其关系;
2. 用 Action 和 Function 表达业务变化与可复用计算;
3. 用 Interface 对外提供稳定、可发现的 API / MCP 契约;
4. 用 Dynamic Security 控制本体信息的合理、安全使用,而不是把“安全策略”简单灌成业务对象;
5. 让人工编辑、AI 摄取、文件提取和外部连接资源导入共同写入同一个 PostgreSQL 本体真源。
---
## 2. 总体架构
```text
┌───────────────────────────┐
│ 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` 等安全类对象。该方案已撤回,因为它只能“描述存在某个策略”,并不能自动阻止未授权访问。
当前采用治理元能力:
```text
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`。
当前接口:
```text
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`。
当前接口:
```text
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`。
运行时:
```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、耗时。
当前审计接口:
```text
GET /api/v1/access/log
GET /api/v1/access/log/stats
```
---
## 5. 主要请求路径
### 5.1 管理路径
管理路径由 `managerAuth` 保护。默认开发模式下,当两个 API key 都为空时,主体默认为 `manager`;生产环境应设置密钥。
```text
/api/v1/ontology/*
/api/v1/objects*
/api/v1/links*
/api/v1/ai/*
/api/v1/km/*
/api/v1/access/*(whoami 除外)
```
### 5.2 连接器路径
```text
/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 更新路径:
```text
资料 / 文件 / 连接资源
▼
AI 或启发式抽取
▼
Suggestion
┌──────┴──────┐
review auto
仅生成建议 直接应用
▼
objects / links + source 溯源
```
---
## 7. 构建、部署与验证
### 构建链
```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
```
### 本地启动
```bash
./run.sh
```
或:
```bash
HTTP_PORT=8081 ./bin/server
```
### 最小验证
```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 二进制。