Files
ssw-ontology/docs/USAGE.md
T
admin cf9e8a74a4 feat(instances): 实例治理 — 显示名物化/merge 语义/软删除/审计/批量/血统传播/source_ts
对标《本体改进需求》14 项按本库实情取舍落地 + Palantir 两机制:

- 显示名物化: title_property → name/title/real_name/display_name 回退链,
  启动回填存量 1235 个空 name(修复 45% 实例检索隐身)— server/display_name.go
- 写入语义: create/update 默认 merge(只改传入字段),replace=true 才全量替换,
  响应回显 added/changed/removed — server/object_upsert.go
- 软删除: objects.deleted/same_as 真实列,连接器默认排除墓碑,
  connObject 别名自动跳转 canonical,restore_object 恢复
- 删除闭环: delete_object 级联删边+幂等+快照进 object_changes;
  propagate=true 沿 source 血统清理该来源全部抽取产物+摄取记录
- 变更审计: object_changes 字段级 diff + get_object_history + restore
- 批量: POST /objects/batch /links/batch 单事务逐条 ok/fail
- 检索: search 多字段 + query filters ne/in/nin/contains/exists + fields 裁剪
- KM: km_list_files recursive + 文件级 excluded 标记 + 双向溯源
- source_ts 乱序丢弃: 旧于已有值直接 409 stale_write(批量 stale_skipped)
- MCP: 新增 batch_create_objects/batch_create_links/delete_object/
  restore_object/get_object_history/find_duplicates 等,共 24 工具
- 前端: api 封装 + InstanceView 删除/保存对话框治理提示
- 文档: docs/INSTANCE_GOVERNANCE.md 权威语义 + 6 份关键文档同步
2026-09-05 14:31:00 +08:00

7.4 KiB
Raw Blame History

使用说明 · Ontology Platform

本体把外部业务/数据/知识沉淀成可查询的"对象类型 + 实例 + 关系",通过 REST/MCP 连接器让外部应用精准调取。

下面的示例使用通用占位符(项目、产品、空间、组织...),把业务换成你自己的即可。


1. 启动

./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

curl 'http://localhost:8081/api/v1/connector/facets?type=Project'
# 返回 {"facets":{"region":["华北","华东",...], "status":["active","archived"], "priority":[...]}}

拿到真实取值后,再精确过滤,避免瞎猜字段值。

3.2 按名称精准查某个实体 → search_ontology

# 默认只匹配名称、按相关度排序
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'

用 facets 拿到的取值做过滤,结果确定、可复现。filters 支持操作符(2026-09-05 起): {"字段":"值"} 等值、{"字段":{"ne":"值"}} 排除、{"字段":{"in":["a","b"]}} / {"nin":[...]} 枚举、{"字段":{"contains":"子串"}}、{"字段":{"exists":true}} 非空。另支持顶层 fields:["a","b"] 裁剪返回字段:

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"}'
# → 物流数据空间 + 其部署的设备/服务

curl -X POST 'http://localhost:8081/api/v1/connector/query' \
  -d '{"type":"DataSpace","filters":{"region":{"ne":"华东"}},"fields":["name","region"]}'
# → 非华东的数据空间,只返回 name/region 两个字段

软删除约定(2026-09-05):被删除的实例是「墓碑」,连接器/检索默认排除;管理端可用 ?include_deleted=true 或 ?only_deleted=true 查看。search_ontology 命中别名时自动跳转到 canonical 实例。

3.4 按角色筛选组织

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 / get_facets / query_related / whoami
  • 知识管理:km_list_tree / km_list_files / km_create_folder / km_upload_markdown / km_extract / km_delete
  • 类型管理:create_object_type / create_link_type / update_enum
  • 实例写入:create_object(默认 merge,只更新传入字段)/ batch_create_objects / batch_create_links / create_link / delete_object(可 propagate 血统传播)/ restore_object / get_object_history / find_duplicates

写入语义要点:

  • create_object 默认 merge:只更新传入字段,其余保留;传 null 删除字段;replace=true 才全量替换(响应回显被清掉的字段)
  • 可传 source_ts(业务源时间戳毫秒):比已有值更旧的写入会被拒绝(stale_write),旧信息不覆盖新信息
  • delete_object 响应回显 source_ref(实例来源文档);propagate=true 时沿溯源把来源文档全部抽取产物一并清理
  • 新建时响应携带 possible_duplicates 高度相似实体提示,建议改用已有 pk 或 same_as 归并

完整约定见 INSTANCE_GOVERNANCE.md。

接入方式:在 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 直接入库)

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 按指令更新(只抽你想要的部分)

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 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)、访问控制(主体/授权/标记/字段策略/审计日志)。