# 使用说明 · 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`,首次启动尚未生成 connector api_key 时无需鉴权;一旦 seed 为 connector 主体写入随机密钥,所有请求须在 `X-API-Key` 头(或 `key=` 查询参数)携带该密钥(在 Access Control 页可查看/重置)。 | 方法 | 路径 | 作用 | |------|------|------| | 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` 拿到的取值做过滤,结果确定、可复现。filters 支持操作符(2026-09-05 起): `{"字段":"值"}` 等值、`{"字段":{"ne":"值"}}` 排除、`{"字段":{"in":["a","b"]}}` / `{"nin":[...]}` 枚举、`{"字段":{"contains":"子串"}}`、`{"字段":{"exists":true}}` 非空。另支持顶层 `fields:["a","b"]` 裁剪返回字段: ```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"}' # → 物流数据空间 + 其部署的设备/服务 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 按角色筛选组织 ```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` / `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](INSTANCE_GOVERNANCE.md)。 **接入方式**:在 WorkBuddy 的 MCP 配置里指向 `http://:8081/api/v1/mcp`,之后即可用自然语言问,例如: > "项目里华东区域的数据空间有哪些?分别用了什么设备?" WorkBuddy 会先用 `get_facets` 拿到 `region=华东`,再 `query_related` 过滤并 `expand` 关系,返回确定答案。 --- ## 5. 用 AI 动态维护本体(提交资料自动更新 / 按指令更新) 管理接口前缀 `/api/v1`(需 manager 主体:密码登录后 cookie 鉴权,或 `X-API-Key` 携带 manager 的随机密钥)。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 摄取、图谱可视化、连接器调试(含各端点示例与代码生成)、访问控制(主体/授权/标记/字段策略/审计日志)。