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

6.6 KiB
Raw Blame History

外部数据源导入 · Ontology Platform

把外部数据源(API、文件、数据库、其他平台)导入到平台,让本体从"人工编辑"变成"实时镜像"。

平台提供两条导入路径,各有所长:

路径 适用 入口
平台内 AI 摄取 文本/少量文件/外部资源定义 POST /api/v1/ai/ingest / POST /api/v1/km/extract
外部脚本(自定义 importer) 大批量、异构、定时同步 自己写 Node/Python 脚本,upsert 到 /api/v1/objects

下面重点说第二种:平台本身只提供管理 API,导入逻辑由采用方按需编写。下面以"尚数网线上网站 → 本体"为例演示通用模式,可替换成任何外部数据源。


通用模式(三步)

任何外部数据源都可以按下面三步走:

外部 API/数据库/文件
   ↓ ① 抓取 + normalize(字段映射 + 中文翻译 + 字段类型归一)
   ↓ ② 映射为本体对象(加前缀避免 pk 与种子冲突 + 决定 object_type)
POST /api/v1/objects  (upsert by (object_type, pk))
   ↓ ③ 尽力匹配 → POST /api/v1/links  (建关系)

要点:

  • 抓取与翻译用采用方已有的代码(没有就 fetch + JSON.parse),平台不强制抓取实现
  • upsert 靠平台主键策略 + source 字段做溯源,撞 pk 时是覆盖
  • 链接按采用方业务规则建,匹配不上保留原始字段

示例:尚数网 shangshuwang.cn → 本体

这是其中一个采用方(尚数网)的导入实现,展示完整模式。复用他们的 xeo 抓取器(/Users/xs/Desktop/xeo):

  • xeo/lib/api-client.js:调用尚数网后端 /m/*(mobileApi 反编译得到),分页拉取并 normalize
  • xeo/lib/dict.js:把 enCode / 状态码 / 行政区域 / 场景类型 翻译为中文

零新增爬虫代码——直接 require xeo 的库即可。

导入脚本

importer/import-from-xeo.js(Node,依赖 Node 18+ 全局 fetch)。

数据流:

尚数网 API (/m/*)
  → xeo api-client 抓取 + normalize + 中文翻译
  → importer 映射为本体对象(加前缀 pk,避免与种子冲突)
  → 本体平台管理 API  POST /api/v1/objects  (upsert)
  → 尽力匹配 data_space 关键字 → POST /api/v1/links  (建空间链接)

运行

# 前置:本体平台已运行(默认 http://localhost:8081), xeo 在 /Users/xs/Desktop/xeo
# 已在仓库根目录执行,无需再 cd 子目录

# 全量导入 5 类
node importer/import-from-xeo.js --base http://localhost:8081

# 只导某一类
node importer/import-from-xeo.js --type product

# 小批量预览
node importer/import-from-xeo.js --limit 20

# 只打印不写入
node importer/import-from-xeo.js --dry-run

# 带管理鉴权(生产环境设了 MANAGER_API_KEY 时)
node importer/import-from-xeo.js --key <MANAGER_API_KEY>

字段映射示例

外部类型 本体类型 pk 前缀 主要字段映射 关系链接
product DataProduct mkt_ name, owner←supplier, desc, price_model←charge_mode 翻译, status←status 翻译, source=平台挂牌 SpaceContainsProduct
sample DataResource res_ name, category←sample_type 翻译, owner←supplier, scale←datasetSize SpaceContainsResource
demand DataDemand dem_ name, desc, scene←翻译, deadline, org←demand_orgname, status←翻译 SpaceHasDemand
partner MemberOrg part_ name←org_name, role=合作伙伴 —
news NewsArticle news_ name←title, content, date←datePublished —

DataDemand、NewsArticle 等对象类型与 source / role 等属性在本次会话的 schema 演进中已逐步沉淀(详见 docs/update/2026-08-24.md)。你的导入不依赖这些具体类型——可以自己建。

链接策略与限制

外部源数据里的 data_space_id(UUID 数组)与本体的行业空间是两套命名,UUID 无法直接翻译,因此采用关键字包含匹配:

  • 仅当实体的空间翻译名/描述里出现行业关键字(物流 / 茶 / 司法 / ...)且能对应到本体某个空间名时,才建立 → 可信数据空间 链接
  • 匹配不上则保留原始 data_space 文本作为属性,绝不硬连错

通用模式:你自己接入任意数据源

把 importer/import-from-xeo.js 换成自己的 import-from-xxx.js,三步不变:

  1. 抓取 + normalize:用你最熟悉的方式(fetcher / ORM / parser)
  2. 字段映射:在脚本里维护一个 externalType → ontologyType + props 的转换表
  3. upsert + 链接:调 POST /api/v1/objects(撞 pk 自动更新)+ POST /api/v1/links

关键约定:

  • pk 加前缀避免冲突(如 mkt_ / part_ / crm_)
  • source 字段填本次导入的标识(如 crm-monday-sync / wiki-export-2026-08),删除时按 source 级联
  • 稳定映射:每次重跑都生成相同 pk,这样 upsert 是覆盖而非重复写入

平台内导入(更简单,无脚本)

POST /api/v1/ai/ingest

粘一段文本 → AI 抽取 → 自动落库(mode=auto)或仅生成建议(mode=review)。

curl -X POST 'http://localhost:8081/api/v1/ai/ingest' \
  -H 'Content-Type: application/json' \
  -d '{"raw_text":"合作伙伴「XX」与「XX 行业空间」达成合作,推出数据产品「X」...","mode":"auto"}'

POST /api/v1/km/extract

知识管理 Tab 上传文件后,批量调 AI 抽取。

详见 docs/USAGE.md 第 5 节。

POST /api/v1/km/connections/:id/import

数据连接资源:定义外部数据库/API/文件 → 一键导入本体,source=conn:<id>。


增量与定时同步

  • 每类按外部 id 生成稳定 pk(如 mkt_{id}),POST /objects 是 upsert(按 (object_type, pk) 冲突更新),重跑覆盖、不重复
  • 可做成定时任务(如每日一次)调用本脚本,外部新增的数据自动同步进本体,连接器与 MCP 实时可读
  • 删除时按 source 级联:DELETE /api/v1/km/files?source=mkt_* 会一并清掉 objects + links + 关联记录

常见问题

Q:导入撞 pk 时 source 字段不更新? A:升级到 2026-08-24 后已修复。ON CONFLICT ... DO UPDATE SET source=COALESCE(NULLIF(EXCLUDED.source,''), objects.source) 是统一语义(必须加表名限定 objects.source)。

Q:导入后 AI 摄取为啥查不到? A:检查 source 字段是否正确写入,管理接口 /api/v1/objects?type=xxx&source=xxx 可按 source 过滤。

Q:链接建不上? A:先确认目标对象存在(get_objects_by_type 或 search_ontology);链接是两端具体对象的关系,任意一端缺失都建不上去。