苏苏原则:本体对外分发不应假设用户能访问 git 仓库,资产一律内置。 原 reviewer skill 的 6 个脚本资产(scan.py 扫描器/manifest schema/AI 精修 提示词/代理脚本/两份示例输出)从 git 历史提取至 server/reviewkit/, 经 //go:embed 随二进制发布: - GET /api/v1/review-kit:索引(文件名/大小/用途) - GET /api/v1/review-kit/<name>:单文件下载,按扩展名给 content-type - GET /api/v1/review-kit/archive:tar.gz 打包(一次拿全套) - 路径穿越防护(../、绝对路径、子目录、白名单外文件名一律 404) get_usage_guide 的 review 场景与 WORKBUDDY.md 路径 C.2 同步改写: 「git show 取回」→「curl 从本体服务下载」,host 取实际部署地址。 验证:3 个新测试用例(内嵌完整性含孤儿文件检查/路径穿越/HTTP 三端点 含 gzip+tar 解包校验);本地 8081 端到端 smoke——下载的 scan.py 实连 MCP --list-types 拉出真实类型清单,key 文件用完即删。
12 KiB
WorkBuddy 接入与本体信息更新
文档定位:给所有用 WorkBuddy 接 ssw-ontology 本体的同事/AI 看。 读完能做:把 ssw-ontology 装进 WorkBuddy → 通过 WorkBuddy 日常更新本体 → 验证 → 排错。 通用化原则:全部 host/port/key 变量化,不写死测试环境。
0. 名词速查
| 名词 | 含义 |
|---|---|
| ssw-ontology | 本体平台(部署在某个 host:port) |
| MCP / 连接器 | 模型上下文协议,AI 通过这个查询和更新本体 |
| 导入核对页 | 浏览器里的 <本体host>:<本体port>/import-review.html,人类 review/apply 的地方 |
| get_usage_guide | MCP 内置「场景作业指南」工具:传 scenario 拿某场景完整 SOP(本文 §4 路径 C 用它) |
| review-kit | GET /api/v1/review-kit:本体差距扫描工具包(扫描器/schema/提示词/示例),内嵌二进制随服务分发,零 git 依赖 |
| manifest | GET /api/v1/mcp/manifest,MCP 自描述文件 |
| 主体 / Principal | 谁在操作(manager / connector / ingest / analyst / public …) |
| API Key | 主体身份凭证,决定「能做什么」 |
1. 前置条件
- 一台 ssw-ontology 实例在跑且 HTTP 可达(找运维要地址)。
- 一个能用的 API Key(向运维索取,不要用同事的私人 key)。
- WorkBuddy 已安装并登录。
💡 默认端口 8081;非默认端口会写在运维给你的地址里。
2. 变量清单(先把这个表填了再动手)
| 变量 | 含义 | 示例 |
|---|---|---|
<本体host> |
本体服务的主机/IP | 192.168.1.100 |
<本体port> |
端口 | 8081 |
<MCP-NAME> |
WorkBuddy mcp.json 中的显示名 | shangshu-ontology |
<API-KEY> |
连接器 API Key | ingest-key-001 |
示例里的
192.168.1.100/ingest-key-001仅为示意,实际值以运维提供为准。
3. 安装连接器
3.1 先用 curl 探通
curl --noproxy '*' http://<本体host>:<本体port>/api/v1/mcp/manifest
期望返回 JSON(工具清单),含 server_name / tools[] 等字段。
如果返回 502 / timeout:
| 现象 | 原因 | 解决 |
|---|---|---|
Connection refused |
本体没起 / 端口错 | 找运维确认地址 |
502 Bad Gateway |
走系统代理被劫持 | curl 加 --noproxy '*',或浏览器直连 |
404 Not Found |
host 通了但路径错 | 检查是不是 /api/v1/mcp/manifest(有 /api/v1 前缀) |
3.2 写入 WorkBuddy MCP 配置
打开 ~/.workbuddy/mcp.json,在 mcpServers 下加一项(合并,别覆盖):
{
"mcpServers": {
"<MCP-NAME>": {
"url": "http://<本体host>:<本体port>/api/v1/mcp",
"headers": {
"X-API-Key": "<API-KEY>"
}
}
}
}
已存在
mcpServers就合并进去。已有其它连接器别动。
3.3 信任连接器
- 重启 WorkBuddy。
- WorkBuddy → 设置 → 自定义连接器(或 MCP 管理入口)。
- 找到
<MCP-NAME>,点 信任。
跳过这一步,WorkBuddy 不会自动加载新 MCP。
3.4 验证装好
在 WorkBuddy 对话里说:
用 <MCP-NAME> 工具查一下,有哪些对象类型
或直接看可用工具列表(应包含 search_ontology / get_object_types / get_objects_by_type / get_object / query_related / get_facets 等)。
4. 本体信息更新 · 三条路径
不同场景选不同路径:
| 场景 | 路径 |
|---|---|
| 有一段文字 / 需求要直接落到本体 | A. 粘贴文本 |
| 有 PDF / Word / Excel / Markdown 文件 | B. 上传文件 → 核对页 |
| 有大量文档要扫描整理 | C. 自动扫描(get_usage_guide review 场景) |
路径 A · 粘贴文本(最快)
WorkBuddy 直接说:
更新本体:<更新要求 + 粘贴的资料文本>
AI 内部走 runIngest:
- 解析文本 → 产出 Suggestion(
create_object_type/create_link_type/create_object/create_link)。 - 自动应用 → 写到数据库。
路径 A 默认
source="",不溯源(找不到是哪段文字写的)。如要溯源用路径 B 或 C。
⚠️ 写入语义注意(2026-09-05 起):
create_object默认 merge:只更新传入的字段,其余字段保留;要全量替换必须显式replace=true(响应会回显被清掉的字段)。- 可传
source_ts(业务源时间戳毫秒):比实例已有时间戳更旧的写入会被拒(stale_write),防止旧资料覆盖新资料。delete_object默认只删当前实例并回显source_ref;propagate=true才会沿溯源把来源文档的全部抽取产物一并清理——先看回显再决定。- 新建返回
possible_duplicates时,优先改用已有 pk 或same_as归并,避免重复实体。完整约定见 INSTANCE_GOVERNANCE.md。
路径 B · 上传文件 → 核对页 Apply
适用:PDF / Word / Excel / Markdown 等结构化资料。 优势:每条抽取都带
source=<文件名>,可在核对页追溯/回滚。
B.1 打开核对页
http://<本体host>:<本体port>/import-review.html
必须带
.html后缀!本体服务是 Go + Vue SPA,独立入口必须带后缀,否则会 fallback 到主站首页。
B.2 填 Key + 上传文件
- 顶部填
<API-KEY>(密码输入框,不会明文存)。 - 左侧目录树新建文件夹 / 上传文件。
- 文件列表选中 → 点 提取。
B.3 AI 自动抽取
后端走 runIngest:
- 解析文档(支持 PDF / Word / Excel / 图片 OCR 等)。
- 产出 Suggestion 清单。
- 每条带
source=<文件名>写库。
B.4 核对页 review / apply
回到 导入核对 tab:
- 每条建议展示:类型、目标、属性值、关联。
- 三种操作:
| 操作 | 含义 |
|---|---|
| ✅ Apply | 立刻写库(生成对象/链接 type、实例、关系) |
| 🕓 待审 | 标"等待人工二次审核",管理员视图会聚到这里 |
| ❌ 拒绝 | 不写库,留下记录便于回溯 AI 判断 |
非管理员填 key 后只能 review / 改状态 / 导出 JSON,无法 Apply(按钮灰)。 管理员(
ingest-key-001或具备 manage 权限的 key)才能一键 Apply。
路径 C · 自动扫描(推荐大批量)
适用:整个产品体系的术语盘点、跨多文档实体清单、定期体检、连接器/MCP 对接自检。 工具:MCP 内置
get_usage_guide工具的review场景(v1.5.2 起,无需安装任何 skill)。
C.1 拿 SOP
WorkBuddy 里直接说:
调 get_usage_guide({scenario:"review"}),按指南扫描 <资料目录> vs 现有本体
AI 会拿到完整流程(扫描器用法 → findings 精修 → 两类型清单 → 核对页)。
C.2 触发扫描
扫描器脚本内嵌于本体二进制(v1.5.2 起)——对外部署零 git 依赖,从本体服务直接下载:
# 打包拿全套(扫描器 + 清单 schema + AI 精修提示词 + 示例输出)
curl -O http://<本体host>:<本体port>/api/v1/review-kit/archive && tar xzf archive
# 或只拿单个文件,如 curl -O http://<本体host>:<本体port>/api/v1/review-kit/scan.py
# 文件清单与用途:GET http://<本体host>:<本体port>/api/v1/review-kit
python3 scan.py --mcp-url http://<本体host>:<本体port>/api/v1/mcp --mcp-key <API Key> \
--docs <资料目录> --output review-manifest.json
host 取实际部署地址,不写死;本机已有 ~/.workbuddy/mcp.json 时可用 --mcp-config 自动拼 URL;加 --extract-only 可先看候选抽得准不准。
C.3 工作流
-
AI 精修 scan 产出的 findings(去重复、补元数据、分级)→ 输出两类型清单:
operation:{method, params}直连 MCP 写入工具(create_object_type/create_link_type/update_enum/create_object/create_link)。document:{filename, markdown}走km_upload_markdown+km_extract。
-
提示你:
已生成 review-manifest.json(X 项 findings,Y 项 items)。请打开核对页面处理:<推导出的 URL>
URL 从 mcp.json 推导,绝不会硬编码。
C.4 落库
打开提示里的核对页(路径 C 也用 /import-review.html),导入 JSON → review → apply。
5. 导入核对页速查
| 维度 | 说明 |
|---|---|
| URL | http://<本体host>:<本体port>/import-review.html |
| 必带后缀 | .html(否则 fallback 到主站首页) |
| 身份分流 | 见下表 |
| 数据持久化 | localStorage + 导出/导入 JSON 流转 |
5.1 身份分流
| 填的 Key 类型 | 能做什么 |
|---|---|
ingest-key-001(具备 manage) |
Apply / 拒绝 / 待审 / 全部操作 |
analyst-key-001(只读) |
review / 改状态 / 导出 JSON,不能 Apply |
| 无 Key | 只能浏览公开内容 |
Key 不存盘(密码输入框,不进 storage),刷新页面需重填。
5.2 三种操作含义
- ✅ Apply:立刻写库(自动生成对象/链接 type、实例、关系)。
- 🕓 待审:标"等待人工二次审核",管理员视图会聚到这里。
- ❌ 拒绝:不写库,留下记录便于回溯 AI 判断。
5.3 导出 / 导入 JSON
- 顶部 导出 → 把当前 review 状态落 JSON(便于跨人协同)。
- 顶部 导入 → 把别人导出的 JSON 加载进来接着 review。
6. get_usage_guide · 场景作业指南(MCP 内置)
get_usage_guide 是本体 MCP 的第 40 号工具(v1.5.2 起),把全部常用场景的作业流程
内置在服务端——任何接入 MCP 的客户端都能用,不需要安装 skill、不需要 clone 仓库。
调用方式:
| 调用 | 返回 |
|---|---|
get_usage_guide() |
总览:8 条铁律 + 三步启动 + 场景路由表 |
get_usage_guide({scenario:"query"}) |
该场景完整 SOP |
场景键:query(查数)/ ingest(批量入库)/ modeling(建模)/ classification(分级)/
access(权限)/ knowledge(知识库入库)/ backup(备份回滚去重)/ review(差距扫描)/
training(员工培训)/ gotchas(坑位速查)。
WorkBuddy 里不确定怎么用时,直接说「调 get_usage_guide 看 XX 场景怎么做」。 历史 skill(
ssw-ontology-ops/ssw-ontology-reviewer/ssw-ontology-trainer) 已于 2026-10-15 全部并入本工具并删除;扫描器等脚本资产内嵌本体二进制 (GET /api/v1/review-kit取用),对外使用不依赖任何 git 仓库。
7. 排错清单
| 现象 | 可能原因 | 解决 |
|---|---|---|
curl manifest 返回 502 |
本体没起 / 网络不通 / 代理劫持 | curl 加 --noproxy '*';检查 host/port |
curl manifest 返回 404 |
路径错(漏 /api/v1 前缀) |
改用 /api/v1/mcp/manifest |
WorkBuddy 工具列表里没 <MCP-NAME> |
没点「信任」/ mcp.json 写错 | 重启 WorkBuddy → 设置 → 信任 |
MCP call 401 / 403 |
Key 无效 / Key 没 manage 权限 | 向运维换 key |
| Apply 按钮是灰的 | 当前 Key 只读 | 用 ingest-key-001 或具备 manage 的 key |
| 浏览器看到主站首页而非核对页 | 路径没带 .html 后缀 |
必须访问 …/import-review.html |
工具列表里没有 get_usage_guide |
服务端版本旧(v1.5.2 之前无此工具) | 看 /api/v1/version,升级服务端 |
上传文件后 提取 报 500 |
文件太大 / 格式不支持 | 检查后端日志(./bin/server 输出) |
| 抽取后本体里没出现新数据 | Key 没 manage / Apply 没点 | 核对 key 权限 + 核对页状态 |
8. 相关文档
| 文档 | 定位 |
|---|---|
docs/README.md |
平台总览(功能 + 架构 + API 一览) |
docs/USAGE.md |
使用说明(含完整 REST/MCP 接口清单) |
docs/IMPORT.md |
外部数据源导入(API / 文件 / DB) |
docs/PLAN.md |
设计演进 + 当前边界 + 待办 |
docs/README.md §6.3 |
MCP 一键注册精简版(管理员视角) |
server/mcp_guide.go |
场景指南工具的内容源(新增/改场景 SOP 改这里) |
附录 A · 完整示例(仅作模板,实际值由运维提供)
// ~/.workbuddy/mcp.json
{
"mcpServers": {
"shangshu-ontology": {
"url": "http://192.168.1.100:8081/api/v1/mcp",
"headers": {
"X-API-Key": "ingest-key-001"
}
}
}
}
# 探通
curl --noproxy '*' http://192.168.1.100:8081/api/v1/mcp/manifest
# 打开核对页
open http://192.168.1.100:8081/import-review.html