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

11 KiB
Raw Blame History

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 探通

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 信任连接器

  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。

路径 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

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 · 完整示例(仅作模板,实际值由运维提供)

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

# 装 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