docs(WORKBUDDY): WorkBuddy 接入 + 本体信息更新说明(连接器安装 / 三条更新路径 / 排错)
This commit is contained in:
1 parent
e5fc024217
commit
240dd2c31f
1 file changed
+322
@@ -0,0 +1,322 @@
|
||||
# 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 的地方 |
|
||||
| ssw-ontology-reviewer | 通用扫描 skill(本文 §6 详细介绍) |
|
||||
| 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 探通
|
||||
|
||||
```bash
|
||||
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` 下加一项(**合并,别覆盖**):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"<MCP-NAME>": {
|
||||
"url": "http://<本体host>:<本体port>/api/v1/mcp",
|
||||
"headers": {
|
||||
"X-API-Key": "<API-KEY>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 已存在 `mcpServers` 就合并进去。已有其它连接器别动。
|
||||
|
||||
### 3.3 信任连接器
|
||||
|
||||
1. 重启 WorkBuddy。
|
||||
2. WorkBuddy → **设置** → **自定义连接器**(或 MCP 管理入口)。
|
||||
3. 找到 `<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. 自动扫描 skill |
|
||||
|
||||
### 路径 A · 粘贴文本(最快)
|
||||
|
||||
WorkBuddy 直接说:
|
||||
|
||||
```
|
||||
更新本体:<更新要求 + 粘贴的资料文本>
|
||||
```
|
||||
|
||||
AI 内部走 `runIngest`:
|
||||
|
||||
- 解析文本 → 产出 Suggestion(`create_object_type` / `create_link_type` / `create_object` / `create_link`)。
|
||||
- 自动应用 → 写到数据库。
|
||||
|
||||
> 路径 A 默认 `source=""`,**不溯源**(找不到是哪段文字写的)。如要溯源用路径 B 或 C。
|
||||
|
||||
### 路径 B · 上传文件 → 核对页 Apply
|
||||
|
||||
> **适用**:PDF / Word / Excel / Markdown 等结构化资料。
|
||||
> **优势**:每条抽取都带 `source=<文件名>`,可在核对页追溯/回滚。
|
||||
|
||||
#### B.1 打开核对页
|
||||
|
||||
```
|
||||
http://<本体host>:<本体port>/import-review.html
|
||||
```
|
||||
|
||||
> **必须带 `.html` 后缀**!本体服务是 Go + Vue SPA,独立入口必须带后缀,否则会 fallback 到主站首页。
|
||||
|
||||
#### B.2 填 Key + 上传文件
|
||||
|
||||
1. 顶部填 `<API-KEY>`(密码输入框,不会明文存)。
|
||||
2. 左侧目录树新建文件夹 / 上传文件。
|
||||
3. 文件列表选中 → 点 **提取**。
|
||||
|
||||
#### 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 · 自动扫描 skill(推荐大批量)
|
||||
|
||||
> **适用**:整个产品体系的术语盘点、跨多文档实体清单、定期体检、连接器/MCP 对接自检。
|
||||
> **工具**:`ssw-ontology-reviewer` skill(每个同事 clone 项目仓库后启用)。
|
||||
|
||||
#### C.1 装 skill
|
||||
|
||||
```bash
|
||||
git clone <你的 ssw-ontology 仓库地址>
|
||||
cd <仓库根>
|
||||
ln -s "$(pwd)/skills/ssw-ontology-reviewer" ~/.workbuddy/skills/ssw-ontology-reviewer
|
||||
# 重启 WorkBuddy → 自动加载
|
||||
```
|
||||
|
||||
#### C.2 触发扫描
|
||||
|
||||
WorkBuddy 里说:
|
||||
|
||||
```
|
||||
帮我用 ssw-ontology-reviewer 扫描《<某篇文章 URL>》vs 现有本体
|
||||
```
|
||||
|
||||
或:
|
||||
|
||||
```
|
||||
跑一次本体体检
|
||||
```
|
||||
|
||||
#### C.3 skill 工作流
|
||||
|
||||
skill 内部自动跑:
|
||||
|
||||
1. **WebFetch 拉资料** → 落档。
|
||||
2. **跑 `scripts/scan.py`**(内置正则 + 业务术语识别)→ 候选清单。
|
||||
3. **AI 精修**(去重复、补元数据)→ 输出两份 JSON:
|
||||
- `review-manifest.json`:汇总元数据 + `meta`(含 `mcp_url` / `mcp_host` / `reviewer_url`,**全部从你的 mcp.json 推导**)。
|
||||
- `manifest.items[]`:每项 `kind ∈ {operation, document}`。
|
||||
4. **提示你**:
|
||||
|
||||
> 已生成 review-manifest.json(X 项 findings,Y 项 items)。请打开核对页面处理:**<推导出的 reviewer_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. ssw-ontology-reviewer skill(自动扫描)
|
||||
|
||||
skill 仓库地址:`<你的 ssw-ontology 仓库地址>`(`skills/ssw-ontology-reviewer/` 目录)。
|
||||
|
||||
定位:
|
||||
|
||||
1. **驱动 AI 对照 MCP 看本体可优化**(扫描 + 精修)。
|
||||
2. **导出两类型 JSON 结果**(`operation` / `document`,无需 AI 再解析)。
|
||||
3. **提示用户到核对页处理**(URL 从 MCP 配置推导,**绝不写死**)。
|
||||
|
||||
详细用法见 `skills/ssw-ontology-reviewer/SKILL.md`,特别是 §七「同事上手」。
|
||||
|
||||
---
|
||||
|
||||
## 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` |
|
||||
| skill 没加载 | 软链断 / SKILL.md 缺 frontmatter | `ls -la ~/.workbuddy/skills/ssw-ontology-reviewer/` 检查 |
|
||||
| 上传文件后 `提取` 报 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 一键注册精简版(管理员视角) |
|
||||
| `skills/ssw-ontology-reviewer/SKILL.md` | 自动扫描 skill 详细用法 |
|
||||
|
||||
---
|
||||
|
||||
## 附录 A · 完整示例(**仅作模板**,实际值由运维提供)
|
||||
|
||||
```json
|
||||
// ~/.workbuddy/mcp.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"shangshu-ontology": {
|
||||
"url": "http://192.168.1.100:8081/api/v1/mcp",
|
||||
"headers": {
|
||||
"X-API-Key": "ingest-key-001"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
# 探通
|
||||
curl --noproxy '*' http://192.168.1.100:8081/api/v1/mcp/manifest
|
||||
|
||||
# 装 skill
|
||||
git clone http://<gitea>/ssw/ssw-ontology.git ~/Desktop/know/ssw-ontology
|
||||
cd ~/Desktop/know/ssw-ontology
|
||||
ln -s "$(pwd)/skills/ssw-ontology-reviewer" ~/.workbuddy/skills/ssw-ontology-reviewer
|
||||
|
||||
# 打开核对页
|
||||
open http://192.168.1.100:8081/import-review.html
|
||||
```
|
||||
Reference in new issue
Block a user