# 尚数网本体管理平台 · 设计与演进计划 > 本文件描述当前实现的真实边界、架构分层和后续演进方向。实现状态以代码、数据库 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 二进制。