Files
ssw-ontology/docs/USAGE.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

125 lines
5.9 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.
# 尚数网本体管理平台 · 使用说明
本体把尚数网的真实业务(数据资源 / 数据产品 / 可信数据空间 / 会员单位·数据集团 / 数据交易所 / 应用场景 / 分支机构 / 密算一体机 / 五大服务 / 知识产权)沉淀成可查询的「对象类型 + 实例 + 关系」。连接器让 WorkBuddy 等外部应用随时**精准**调取这些信息。
---
## 1. 启动
> 后端以 Go 二进制直接运行(`./run.sh`),数据库复用 workspace 内已部署的 PostgreSQL(`jnpf-postgres`,宿主机映射 `15432`),无需 docker。
```bash
./build.sh # 构建前端 + 编译后端二进制
./run.sh # 直接运行,连 workspace pg,监听 http://localhost:8080
# 停止:Ctrl+C 结束进程即可(无后台容器需清理)
```
首次启动(`SEED_ON_START=true`)会自动灌入尚数网种子本体(见 `server/db.go` 的 `seedIfEmpty`)。
---
## 2. 连接器 API(只读,供外部消费)
所有连接器接口前缀 `/api/v1/connector`,默认无需鉴权;可在 `.env` 设置 `CONNECTOR_API_KEY` 开启(`X-API-Key` 头)。
| 方法 | 路径 | 作用 |
|------|------|------|
| GET | `/connector/object-types` | 列出全部对象类型及属性定义(先了解有哪些实体类别) |
| GET | `/connector/objects/:type` | 列出某类型的全部实例(`?limit=`) |
| GET | `/connector/object/:type/:pk` | 取单个实例详情 |
| GET | `/connector/search?q=` | **精准检索**:按名称优先排序,支持 `type`/`field`/`limit` |
| GET | `/connector/facets` | **发现维度**:返回各类型可过滤的取值(region/industry/type…) |
| POST| `/connector/query` | 图式查询:按类型+属性过滤,可 `expand` 展开关系 |
| GET | `/connector/graph` | 全量图谱(节点+边),用于可视化 |
| GET | `/api/v1/mcp/manifest` | MCP 工具清单(WorkBuddy 据此注册工具) |
---
## 3. 精准查询配方(不要再「莫名其妙」地全模糊搜)
### 3.1 先发现有哪些可过滤值 → `get_facets`
```bash
curl 'http://localhost:8080/api/v1/connector/facets?type=TrustedDataSpace'
# 返回 {"facets":{"region":["深圳","北京","江西",...],"industry":["物流","茶业",...],"deploy_mode":[...]}}
```
拿到真实取值后,再精确过滤,避免瞎猜字段值。
### 3.2 按名称精准查某个实体 → `search_ontology`
```bash
# 默认只匹配名称、按相关度排序
curl 'http://localhost:8080/api/v1/connector/search?q=广州数据集团'
# 限定类型,更准
curl 'http://localhost:8080/api/v1/connector/search?q=数据空间&type=TrustedDataSpace'
# 全字段(名称+属性)模糊(噪杂,慎用)
curl 'http://localhost:8080/api/v1/connector/search?q=信创&field=all'
```
### 3.3 结构化过滤 → `query_related`
用 `facets` 拿到的取值做过滤,结果确定、可复现:
```bash
curl -X POST 'http://localhost:8080/api/v1/connector/query' \
-H 'Content-Type: application/json' \
-d '{"type":"TrustedDataSpace","filters":{"region":"深圳"}}'
# → 深圳的所有可信数据空间
curl -X POST 'http://localhost:8080/api/v1/connector/query' \
-d '{"type":"TrustedDataSpace","filters":{"industry":"物流"},"expand":"SpaceUsesAppliance"}'
# → 物流数据空间 + 其部署的密算一体机
```
### 3.4 查会员单位里的地方数据集团
```bash
curl -X POST 'http://localhost:8080/api/v1/connector/query' \
-d '{"type":"MemberOrg","filters":{"type":"数据集团"}}'
```
---
## 4. 接入 WorkBuddy / 其他应用(MCP)
连接器同时暴露一份 **MCP 工具清单**(`GET /api/v1/mcp/manifest`),WorkBuddy 可据此把本体注册成可调用的工具:
- `get_object_types` — 有哪些实体类别
- `get_objects_by_type` — 某类别全部实例
- `get_object` — 单个实例详情
- `search_ontology` — 精准检索(支持 type / field / limit)
- `get_facets` — 发现可过滤维度
- `query_related` — 类型+属性精确过滤,并可展开关系
接入方式:在 WorkBuddy 的 MCP 配置里指向 `http://<host>:8080/api/v1/mcp/manifest`(或将其包成 MCP server)。之后即可用自然语言问,例如:
> “尚数网在深圳部署了哪些可信数据空间?分别用了哪款密算一体机?”
WorkBuddy 会先用 `get_facets` 拿到 `region=深圳`,再 `query_related` 过滤并 `expand` 关系,返回确定答案。
---
## 5. 用 AI 动态维护本体(提交资料自动更新 / 按指令更新)
管理接口前缀 `/api/v1`(可设 `MANAGER_API_KEY` 鉴权)。AI 摄取把一段资料自动抽取成本体增量并入库。
### 5.1 提交资料,自动更新(mode=auto 直接入库)
```bash
curl -X POST 'http://localhost:8080/api/v1/ai/ingest' \
-H 'Content-Type: application/json' \
-d '{"raw_text":"会员单位「广州数据集团」与「物流行业可信数据空间」达成合作,并推出数据产品「数小美」用于企业估值。","mode":"auto"}'
```
返回会列出抽取到的对象(已自动分类、生成稳定主键并写入)。
### 5.2 按指令更新(只抽你想要的部分)
```bash
curl -X POST 'http://localhost:8080/api/v1/ai/ingest' \
-d '{"raw_text":"...同上资料...","directive":"只提取其中的数据产品","mode":"auto"}'
```
`directive` 会约束抽取范围(如「只提取数据产品」「提取所有数据集团并标注区域」)。
### 5.3 先审后入(mode=review)
把 `mode` 设为 `review`,接口只返回 `suggestion` 不写库,由人工确认后再调用管理接口写入。
> 若配置了 `AI_BASE_URL` + `AI_KEY` + `AI_MODEL`(OpenAI 兼容),则走真实大模型抽取;否则用内置启发式兜底(识别「」""()包裹的实体 + 就近关键词分类)。
---
## 6. 管理平台界面
浏览器打开 `http://localhost:8080` 即前端:概览统计、本体编辑(对象类型/属性/关系/动作)、实例 CRUD、AI 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)。