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

330 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。
> ⚠️ 写入语义注意(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](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 + 上传文件
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
```