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

146 lines
5.8 KiB
Markdown

# 使用说明 · Ontology Platform
本体把外部业务/数据/知识沉淀成可查询的"对象类型 + 实例 + 关系",通过 REST/MCP 连接器让外部应用精准调取。
下面的示例使用通用占位符(项目、产品、空间、组织...),把业务换成你自己的即可。
---
## 1. 启动
```bash
./build.sh # 构建前端 + 编译后端二进制
./run.sh # 直接运行,监听 http://localhost:8081
# 停止:Ctrl+C 结束进程即可(无后台容器需清理)
```
首次启动(`SEED_ON_START=true`)会自动灌入**极简种子**(1 个对象类型「合作企业」+ 3 条占位实例,见 `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` | **发现维度**:返回各类型可过滤的取值 |
| POST | `/connector/query` | **结构化过滤**:按类型+属性过滤,可 `expand` 展开关系 |
| GET | `/connector/graph` | 全量图谱(节点+边),用于可视化 |
| GET | `/api/v1/mcp/manifest` | MCP 工具清单(WorkBuddy 据此注册工具) |
| POST | `/api/v1/mcp` | MCP JSON-RPC 2.0 Streamable HTTP 端点 |
---
## 3. 精准查询配方
> 原则:**先发现 → 再精确**。不要直接模糊搜。
### 3.1 先发现有哪些可过滤值 → `get_facets`
```bash
curl 'http://localhost:8081/api/v1/connector/facets?type=Project'
# 返回 {"facets":{"region":["华北","华东",...], "status":["active","archived"], "priority":[...]}}
```
拿到真实取值后,再精确过滤,避免瞎猜字段值。
### 3.2 按名称精准查某个实体 → `search_ontology`
```bash
# 默认只匹配名称、按相关度排序
curl 'http://localhost:8081/api/v1/connector/search?q=核心项目A'
# 限定类型,更准
curl 'http://localhost:8081/api/v1/connector/search?q=数据空间&type=DataSpace'
# 全字段(名称+属性)模糊(噪杂,慎用)
curl 'http://localhost:8081/api/v1/connector/search?q=信创&field=all'
```
### 3.3 结构化过滤 → `query_related`
用 `facets` 拿到的取值做过滤,结果确定、可复现:
```bash
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-H 'Content-Type: application/json' \
-d '{"type":"DataSpace","filters":{"region":"华东"}}'
# → 华东的所有数据空间
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"DataSpace","filters":{"industry":"物流"},"expand":"SpaceUsesAppliance"}'
# → 物流数据空间 + 其部署的设备/服务
```
### 3.4 按角色筛选组织
```bash
curl -X POST 'http://localhost:8081/api/v1/connector/query' \
-d '{"type":"MemberOrg","filters":{"role":"合作伙伴"}}'
```
---
## 4. 接入 WorkBuddy / 其他应用(MCP)
连接器同时暴露一份 **MCP 工具清单**(`GET /api/v1/mcp/manifest`),WorkBuddy / Claude Code 可据此把本体注册成可调用的工具:
- `get_object_types` — 有哪些实体类别
- `get_objects_by_type` — 某类别全部实例
- `get_object` — 单个实例详情
- `search_ontology` — 精准检索(支持 type / field / limit)
- `get_facets` — 发现可过滤维度
- `query_related` — 类型+属性精确过滤,并可展开关系
**接入方式**:在 WorkBuddy 的 MCP 配置里指向 `http://<host>:8081/api/v1/mcp`,之后即可用自然语言问,例如:
> "项目里华东区域的数据空间有哪些?分别用了什么设备?"
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:8081/api/v1/ai/ingest' \
-H 'Content-Type: application/json' \
-d '{"raw_text":"合作伙伴「华东数据集团」与「物流行业数据空间」达成合作,并推出数据产品「XX」用于企业估值。","mode":"auto"}'
```
返回会列出抽取到的对象(已自动分类、生成稳定主键并写入),并打 `source='ai-ingest'` 标记。
### 5.2 按指令更新(只抽你想要的部分)
```bash
curl -X POST 'http://localhost:8081/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 兼容),则走真实大模型抽取;否则用内置启发式兜底(识别「」""包裹的实体 + 就近关键词分类)。
### 5.4 大模型支持
- URL 含 `/anthropic` → Anthropic Messages 协议(需 `x-api-key` 头)
- 其他 → OpenAI Chat Completions 兼容协议(DeepSeek / 通义千问 / Ollama 等均可)
---
## 6. 管理平台界面
浏览器打开 `http://localhost:8081` 即前端:概览统计、本体编辑(对象类型/属性/关系/动作/函数/接口/物化/同步源)、实例 CRUD、AI 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)、访问控制(主体/授权/标记/字段策略/审计日志)。