4 Commits
Author SHA1 Message Date
admin 7d4a0c26e3 chore(release): v1.5.2 CHANGELOG 定稿(摘除未发布标记) 2026-10-15 10:20:09 +08:00
admin 4349c3c608 feat(server): 扫描工具包内嵌二进制,对外零 git 依赖(review-kit 端点)
苏苏原则:本体对外分发不应假设用户能访问 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 文件用完即删。
2026-10-15 09:21:32 +08:00
admin 723445d355 feat(mcp): get_usage_guide 并入 review/training 场景,删除三个 ontology skill
苏苏决策:skill 需要用户安装、跨客户端不可移植,场景说明全部前移为
服务端工具能力。本次将原 ssw-ontology-reviewer(差距扫描核对)与
ssw-ontology-trainer(员工培训闭环)的核心 SOP 并入 get_usage_guide,
随后删除全部三个 skill:

- get_usage_guide 场景键 8 → 10:新增 review(扫描器用法/findings 精修/
  两类型清单/核对页 Apply/策展决策)与 training(业务全景六域+个体按需/
  三阶段闭环/只读安全边界)。reviewer 的脚本资产留在 git 历史,
  工具内给出取回命令
- instructions 场景列表同步补评审/培训(1659→~1680 字节,仍 <2KB)
- 删除 skills/ssw-ontology-ops、skills/ssw-ontology-reviewer(git rm),
  .workbuddy/skills/ssw-ontology-trainer(进访达回收站),用户级两个
  软链一并清除;git 历史均保留可恢复
- 文档同步:WORKBUDDY.md 路径 C/§6/排错/附录改为 get_usage_guide 用法,
  CLAUDE.md 目录表改指 server/mcp_guide.go

验证:go test ./server 全绿(10 场景键穷举+容错用例同步扩充);
全仓无 skill 残留引用(CHANGELOG 历史条目除外)。
2026-10-15 08:52:31 +08:00
admin 5b67ed991a feat(mcp): 内置提示词席位 + 工具语义标注 + get_usage_guide 场景指南工具
把「怎么用这套本体」从用户侧 skill 前移为服务端能力,任何接入 MCP 的
客户端开箱即用,无需安装 skill:

- initialize 下发 instructions(1.6KB,起步速查:开工三步/查询/写入/
  建模/分级/权限/知识库/铁律;控制在 2KB 内防客户端截断)
- tools/list 每个工具带 title + ToolAnnotations(readOnly/destructive/
  idempotent/openWorld),指针字段确保显式 false 不被 omitempty 吞掉;
  39→40 个工具全覆盖,4 个破坏性工具可被客户端识别
- tools/list 补 ttlMs/cacheScope,清单可缓存 5 分钟
- 新增 get_usage_guide:不传参返回铁律+场景路由总览,传 scenario 返回
  该场景完整 SOP(query/ingest/modeling/classification/access/
  knowledge/backup/gotchas)。静态内容不触库,与 ssw-ontology-ops
  skill 同源——skill 定位转为深度参考

回归测试 4 个用例守护:标注覆盖率、instructions 长度上限、清单顺序
稳定性、指南场景键全覆盖与容错。实测确认 WorkBuddy 不消费协议层
instructions/annotations(asar 逆向证据),故指南必须走工具通道——
本工具为普通 tool call,全客户端有效。
2026-10-15 08:31:30 +08:00
17 changed files with 902 additions and 394 deletions

No files matched your search

+1 -1
View File
@@ -125,6 +125,6 @@ Semantic 层:Object / Property / Link / Interface(描述"有什么/什么状
| docs/WORKBUDDY.md | 一键注册到 WorkBuddy |
| docs/BACKUP.md | 备份与快照路由 |
| docs/STANDARD_GB48000_3_2026_GAP.md | GB/T 48000.3-2026《标准数字化 本体建模要求》差距分析:借鉴其通用建模方法(IRI/OWL 导出/schema 版本 + 公理声明/类型继承/多语标签/URI 数据类型,**已落地 2026-09-20**,见"标准兼容层"),标准领域实体类型(18 类业务类)由采用方建模、**不内置**(PLAN.md §8"明确不做") |
| skills/ssw-ontology-reviewer/ | 本体差距自动扫描技能(独立 SKILL) |
| server/mcp_guide.go | 场景作业指南内容源(`get_usage_guide` 工具,MCP 第 40 号;2026-10-15 起三个 ontology skill 已全部并入) |
代码状态以代码、schema 和运行接口为准。README/PLAN 里写"已实现"以代码为准;写"预留/待办"的就是还没做。
+47 -43
View File
@@ -13,7 +13,8 @@
| ssw-ontology | 本体平台(部署在某个 `host:port`) |
| MCP / 连接器 | 模型上下文协议,AI 通过这个查询和更新本体 |
| 导入核对页 | 浏览器里的 `<本体host>:<本体port>/import-review.html`,人类 review/apply 的地方 |
| ssw-ontology-reviewer | 通用扫描 skill(本文 §6 详细介绍) |
| 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 | 主体身份凭证,决定「能做什么」 |
@@ -108,7 +109,7 @@ curl --noproxy '*' http://<本体host>:<本体port>/api/v1/mcp/manifest
|---|---|
| 有一段文字 / 需求要直接落到本体 | A. 粘贴文本 |
| 有 PDF / Word / Excel / Markdown 文件 | B. 上传文件 → 核对页 |
| 有大量文档要扫描整理 | C. 自动扫描 skill |
| 有大量文档要扫描整理 | C. 自动扫描(`get_usage_guide` review 场景) |
### 路径 A · 粘贴文本(最快)
@@ -176,48 +177,47 @@ http://<本体host>:<本体port>/import-review.html
> 非管理员填 key 后只能 review / 改状态 / 导出 JSON,**无法 Apply**(按钮灰)。
> 管理员(`ingest-key-001` 或具备 manage 权限的 key)才能一键 Apply。
### 路径 C · 自动扫描 skill(推荐大批量)
### 路径 C · 自动扫描(推荐大批量)
> **适用**:整个产品体系的术语盘点、跨多文档实体清单、定期体检、连接器/MCP 对接自检。
> **工具**:`ssw-ontology-reviewer` skill(每个同事 clone 项目仓库后启用)。
> **工具**:MCP 内置 `get_usage_guide` 工具的 `review` 场景(v1.5.2 起,无需安装任何 skill)。
#### C.1 装 skill
#### C.1 拿 SOP
WorkBuddy 里直接说:
```bash
git clone <你的 ssw-ontology 仓库地址>
cd <仓库根>
ln -s "$(pwd)/skills/ssw-ontology-reviewer" ~/.workbuddy/skills/ssw-ontology-reviewer
# 重启 WorkBuddy → 自动加载
```
调 get_usage_guide({scenario:"review"}),按指南扫描 <资料目录> vs 现有本体
```
AI 会拿到完整流程(扫描器用法 → findings 精修 → 两类型清单 → 核对页)。
#### C.2 触发扫描
WorkBuddy 里说:
扫描器脚本**内嵌于本体二进制**(v1.5.2 起)——对外部署零 git 依赖,从本体服务直接下载:
```
帮我用 ssw-ontology-reviewer 扫描《<某篇文章 URL>》vs 现有本体
```bash
# 打包拿全套(扫描器 + 清单 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 工作流
#### C.3 skill 工作流
1. **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`。
2. **提示你**:
skill 内部自动跑:
> 已生成 review-manifest.json(X 项 findings,Y 项 items)。请打开核对页面处理:**<推导出的 URL>**
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 推导的,**绝不会硬编码**。
URL 从 mcp.json 推导,**绝不会硬编码**。
#### C.4 落库
@@ -257,17 +257,26 @@ skill 内部自动跑:
---
## 6. ssw-ontology-reviewer skill(自动扫描)
## 6. get_usage_guide · 场景作业指南(MCP 内置)
skill 仓库地址:`<你的 ssw-ontology 仓库地址>`(`skills/ssw-ontology-reviewer/` 目录)。
`get_usage_guide` 是本体 MCP 的第 40 号工具(v1.5.2 起),把全部常用场景的作业流程
内置在服务端——**任何接入 MCP 的客户端都能用,不需要安装 skill、不需要 clone 仓库**。
定位:
调用方式:
1. **驱动 AI 对照 MCP 看本体可优化**(扫描 + 精修)。
2. **导出两类型 JSON 结果**(`operation` / `document`,无需 AI 再解析)。
3. **提示用户到核对页处理**(URL 从 MCP 配置推导,**绝不写死**)。
| 调用 | 返回 |
|---|---|
| `get_usage_guide()` | 总览:8 条铁律 + 三步启动 + 场景路由表 |
| `get_usage_guide({scenario:"query"})` | 该场景完整 SOP |
详细用法见 `skills/ssw-ontology-reviewer/SKILL.md`,特别是 §七「同事上手」。
场景键:`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 仓库**。
---
@@ -281,7 +290,7 @@ skill 仓库地址:`<你的 ssw-ontology 仓库地址>`(`skills/ssw-ontology
| `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/` 检查 |
| 工具列表里没有 `get_usage_guide` | 服务端版本旧(v1.5.2 之前无此工具) | 看 `/api/v1/version`,升级服务端 |
| 上传文件后 `提取` 报 500 | 文件太大 / 格式不支持 | 检查后端日志(`./bin/server` 输出) |
| 抽取后本体里没出现新数据 | Key 没 manage / Apply 没点 | 核对 key 权限 + 核对页状态 |
@@ -296,7 +305,7 @@ skill 仓库地址:`<你的 ssw-ontology 仓库地址>`(`skills/ssw-ontology
| `docs/IMPORT.md` | 外部数据源导入(API / 文件 / DB) |
| `docs/PLAN.md` | 设计演进 + 当前边界 + 待办 |
| `docs/README.md` §6.3 | MCP 一键注册精简版(管理员视角) |
| `skills/ssw-ontology-reviewer/SKILL.md` | 自动扫描 skill 详细用法 |
| `server/mcp_guide.go` | 场景指南工具的内容源(新增/改场景 SOP 改这里) |
---
@@ -320,11 +329,6 @@ skill 仓库地址:`<你的 ssw-ontology 仓库地址>`(`skills/ssw-ontology
# 探通
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
```
+12
View File
@@ -18,6 +18,18 @@ AI 客户端在使用本平台过程中发现 bug 或有改进建议,**请提
## 版本历史
## [1.5.2] - 2026-10-15 场景指南内置 + 扫描工具包内嵌
**影响**:AI 客户端接入本体后「怎么用」不再依赖外部资源——场景 SOP 由服务端工具直接下发,差距扫描器随二进制分发,对外部署零 git 依赖、零 skill 安装。
**改动**:
- 新增 MCP 工具 `get_usage_guide`:无参返回铁律+场景路由总览,传 `scenario` 返回该场景完整 SOP(query/ingest/modeling/classification/access/knowledge/backup/review/training/gotchas 十个场景),静态内容不触库
- 新增 `GET /api/v1/review-kit` 系列端点:本体差距扫描工具包(scan.py 零依赖扫描器、manifest schema、AI 精修提示词、两份示例输出)经 `//go:embed` 内嵌二进制,支持索引查询、单文件下载、`archive` tar.gz 打包下载,防路径穿越
- `initialize` 结果下发 `instructions`(~1.7KB 起步指南,控制在 2KB 内防客户端截断);`tools/list` 每个工具带 `title` + ToolAnnotations(readOnly/destructive/idempotent/openWorld),并补 `ttlMs`/`cacheScope` 缓存提示
- 删除 `ssw-ontology-ops` / `ssw-ontology-reviewer` / `ssw-ontology-trainer` 三个 skill(内容并入上述工具;reviewer 脚本资产即本版内嵌的 review-kit)
**设计**:WorkBuddy 实测不消费 MCP 协议层 instructions/annotations(asar 逆向确认),故场景指南必须走「普通工具调用」通道才能全客户端生效;工具数量不收敛为 facade——该补的是语义标注而非减少工具数。
## [1.5.1] - 2026-09-21 发布整合:GB/T 48000.3 建模能力 + MCP 写闸门修复
首个整合此前 [1.6.0] 与 [1.5.0] 规划能力的正式发布版本;并修复 MCP 写权限闸门与 REST 不一致的问题。
+131 -1
View File
@@ -37,6 +37,113 @@ type jsonrpcError struct {
Message string `json:"message"`
}
// ---------- MCP 服务器端「内置提示词」与工具语义标注 ----------
// 参考 spec 2026-07-28 server/tools。三项均为纯增量字段,不改变任何请求语义。
// 1. instructions:legacy 挂在 InitializeResult,v2 挂在 DiscoverResult(服务端必须实现该方法)。
// 语义是「服务器给 LLM 的自然语言使用指南」,由客户端注入模型——这样任何接入方
// 都能自带起步能力,不必各自维护一份 skill 才知道怎么用。
// 2) ToolAnnotations:让模型/客户端不读文档即可判断只读、破坏性、幂等。
// 3) ttlMs/cacheScope:工具清单随发版才变化,允许客户端缓存,减少重复拉取。
//
// 长度自律:instructions 需控制在 ~2KB 字节内(部分客户端如 Claude Code 会截断更长内容),
// 因此这里只放「路由 + 铁律」,深度 SOP 交给上层 skill(ssw-ontology-ops)按需加载。
const mcpInstructions = `尚数网本体(SSW Ontology)MCP。
开工三步:whoami(确认主体与写权限)→ get_server_info({include_changelog:false}) → get_object_types。
查询:search_ontology 找候选 → get_object(type,pk) 核对详情;结构过滤先 get_facets 取真实取值再 query_related(expand 展开邻居);取全量须用 offset 翻到 total。
写入:单条 create_object,≥20 条 batch_create_objects;默认 merge,**禁用 replace:true(会丢字段)**;每条带 source 溯源;写完 find_duplicates 自检,重复用 same_as 归并勿硬删。
建模:先确认非重复建设,再 create_object_type / add_object_type_property / create_link_type / update_enum。
分级:两层互不影响——objects.classification 列=类型默认级,object_markings=实例覆盖层。设 classification_property 前须先 add_object_type_property 注册该属性,否则报 400;recompute_classification 先 dry_run 再 apply。员工主体锁 L0–L2;要让员工看到某数据,正解是降低该数据类型默认级,而非抬高员工。
权限:set_principal_clearance 是全量替换(传空=清空),改前必须 get_principal 备份。
知识库:只收 Markdown,原档须客户端先转 .md;km_upload_markdown → km_extract(先 review 后 auto);敏感文件 set_km_classification。
铁律:批量写/删除/改 schema/重算分级前必先 backup_create;结论须标注 type:pk 出处;查不到就答「本体暂无」,禁止编造。
需要某场景完整步骤(查数/入库/建模/分级/权限/知识库/备份/评审/培训)调 get_usage_guide({scenario}),不传参数返回总览。`
// mcpToolSpec 单个工具的中文名与行为提示。
type mcpToolSpec struct {
title string
readOnly bool
destructive bool
idempotent bool
}
// mcpToolSpecs 按工具名检索的唯一事实来源(当前 40 个工具全覆盖)。
// 集中在此而非散落进下方数百行定义里:标注表是单点可审,改工具不影响其 schema 定义。
//
// destructive 取值口径:以「默认调用路径」为准。
// create_object / batch_create_objects 默认是 merge 增量,只有显式 replace:true 才可能丢字段,
// 故记 false——否则日常批量入库会被不必要的二次确认卡死;replace 风险改由 instructions 约束。
// 真正具备删除/清空语义的才记 true(delete_object / km_delete / backup_delete / set_principal_clearance)。
var mcpToolSpecs = map[string]mcpToolSpec{
// ---- 只读(19) ----
"whoami": {"查看当前主体", true, false, true},
"get_server_info": {"服务端版本信息", true, false, true},
"get_usage_guide": {"场景作业指南", true, false, true},
"get_object_types": {"全部对象类型", true, false, true},
"get_objects_by_type": {"按类型列实例", true, false, true},
"get_object": {"单个对象详情", true, false, true},
"search_ontology": {"检索本体实例", true, false, true},
"get_facets": {"可过滤维度取值", true, false, true},
"query_related": {"图式精确查询", true, false, true},
"get_object_history": {"字段级变更审计", true, false, true},
"find_duplicates": {"相似重复分组", true, false, true},
"get_classification_config": {"分级配置现状", true, false, true},
"list_principals": {"全部主体与可见级", true, false, true},
"get_principal": {"单个主体详情", true, false, true},
"km_list_tree": {"知识库目录树", true, false, true},
"km_list_files": {"文件夹文件列表", true, false, true},
"backup_list": {"快照清单", true, false, true},
"backup_inspect": {"快照包含的表", true, false, true},
"backup_switch": {"命中快照所需信息", true, false, true},
// ---- 写入(21) ----
"create_object": {"新建/更新实例", false, false, true},
"batch_create_objects": {"批量写入实例", false, false, true},
"create_link": {"新建关系边", false, false, true},
"batch_create_links": {"批量新建关系边", false, false, true},
"create_object_type": {"新建对象类型", false, false, false},
"update_object_type": {"更新类型元数据", false, false, true},
"add_object_type_property": {"注册类型属性", false, false, true},
"create_link_type": {"新建链接类型", false, false, false},
"update_enum": {"枚举追加取值", false, false, true},
"delete_object": {"删除实例并清边", false, true, true},
"restore_object": {"从快照恢复实例", false, false, true},
"km_create_folder": {"新建知识库文件夹", false, false, true},
"km_upload_markdown": {"上传 Markdown", false, false, true},
"km_extract": {"抽取导入本体", false, false, false},
"km_delete": {"删文件并级联回滚", false, true, true},
"recompute_classification": {"重算实例分级", false, false, true},
"set_object_type_classification": {"配置类型分级引擎", false, false, true},
"set_km_classification": {"给知识库文件打级", false, false, true},
"set_principal_clearance": {"全量替换主体可见级", false, true, true},
"backup_create": {"创建全库快照", false, false, false},
"backup_delete": {"删除快照", false, true, true},
}
// boolPtr 取 bool 字面量地址,使 omitempty 能输出显式 true/false 而非省略。
func boolPtr(b bool) *bool { return &b }
// mcpAnnotatedToolList 在工具清单上叠加 title 与 annotations。
// 未命中标注表的工具保持原样:无提示优于错提示(错误 hint 会误导客户端决策)。
// 顺序天然确定——mcpToolList 返回硬编码切片,同版本跨请求顺序不变,
// 符合 spec 对确定性排序的要求,利于客户端缓存与 LLM prompt cache 命中。
func mcpAnnotatedToolList() []MCPTool {
tools := mcpToolList()
for i := range tools {
spec, ok := mcpToolSpecs[tools[i].Name]
if !ok {
continue
}
tools[i].Title = spec.title
tools[i].Annotations = &MCPToolAnnotations{
ReadOnlyHint: boolPtr(spec.readOnly),
DestructiveHint: boolPtr(spec.destructive),
IdempotentHint: boolPtr(spec.idempotent),
// 本体工具一律操作本平台数据,属封闭世界;显式 false 而非省略。
OpenWorldHint: boolPtr(false),
}
}
return tools
}
// mcpToolList 与 /api/v1/mcp/manifest 共用同一份工具清单。
func mcpToolList() []MCPTool {
return []MCPTool{
@@ -50,6 +157,16 @@ func mcpToolList() []MCPTool {
},
},
},
{
Name: "get_usage_guide",
Description: "获取本体平台常用场景的作业指南(SOP)。首次使用本平台、或不确定该用哪些工具/什么顺序时调用。不传参数返回总览(铁律+场景路由表);传 scenario 返回该场景完整步骤,可选值:query(查数问答) ingest(批量入库) modeling(建模) classification(分级治理) access(权限调整) knowledge(知识库入库) backup(备份回滚去重) review(差距扫描核对) training(员工培训) gotchas(坑位速查)。静态内容,不触库。",
InputSchema: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"scenario": map[string]interface{}{"type": "string", "description": "场景键:query/ingest/modeling/classification/access/knowledge/backup/review/training/gotchas;省略返回总览", "enum": []string{"query", "ingest", "modeling", "classification", "access", "knowledge", "backup", "review", "training", "gotchas"}},
},
},
},
{
Name: "get_object_types",
Description: "获取本体平台的全部对象类型(含属性定义),了解有哪些实体类别。",
@@ -609,12 +726,21 @@ func (a *app) mcpDispatch(c *gin.Context, req jsonrpcRequest) jsonrpcResponse {
"protocolVersion": pv,
"capabilities": gin.H{"tools": gin.H{}},
"serverInfo": gin.H{"name": "ontology-platform", "version": Version},
// instructions = 服务端「内置提示词」席位:客户端会把这段自然语言指南注入模型上下文,
// 使任何接入方开箱即用,不必先配 skill 才知道怎么用这套本体。
"instructions": mcpInstructions,
},
}
case "ping":
return jsonrpcResponse{JSONRPC: "2.0", ID: req.ID, Result: gin.H{}}
case "tools/list":
return jsonrpcResponse{JSONRPC: "2.0", ID: req.ID, Result: gin.H{"tools": mcpToolList()}}
// 叠加 title + ToolAnnotations;返回顺序天然确定(硬编码切片),符合 spec 的确定性排序要求。
// ttlMs/cacheScope:清单随版本发布才变动,允许客户端缓存 5 分钟,避免每次会话重复拉取。
return jsonrpcResponse{JSONRPC: "2.0", ID: req.ID, Result: gin.H{
"tools": mcpAnnotatedToolList(),
"ttlMs": 300000,
"cacheScope": "public",
}}
case "tools/call":
name, _ := req.Params["name"].(string)
args, _ := req.Params["arguments"].(map[string]interface{})
@@ -668,6 +794,10 @@ func (a *app) mcpDispatchTool(c *gin.Context, name string, args map[string]inter
b, _ := json.MarshalIndent(info, "", " ")
return string(b), false, false
case "get_usage_guide":
// 静态指南,不触库、不需鉴权(与 get_server_info 同):内容在 mcp_guide.go。
return mcpUsageGuide(args)
case "get_object_types":
return a.callConn(c, "GET", "/api/v1/connector/object-types", nil), false, false
+175
View File
@@ -0,0 +1,175 @@
package main
import (
"encoding/json"
"strings"
"testing"
"github.com/gin-gonic/gin"
)
// 这些测试守护「工具清单 ↔ 标注表」的一致性:
// 新增工具若忘记在 mcpToolSpecs 标注,或 annotations 语义填矛盾,这里会立刻失败。
func TestMCPToolAnnotationCoverage(t *testing.T) {
tools := mcpAnnotatedToolList()
if len(tools) == 0 {
t.Fatal("工具清单为空")
}
var readOnly, destructive int
for _, tl := range tools {
if tl.Title == "" {
t.Errorf("工具 %s 缺少 title", tl.Name)
}
if tl.Annotations == nil {
t.Errorf("工具 %s 缺少 annotations:mcpToolSpecs 未覆盖,请补标注", tl.Name)
continue
}
an := tl.Annotations
if an.ReadOnlyHint == nil || an.DestructiveHint == nil ||
an.IdempotentHint == nil || an.OpenWorldHint == nil {
t.Errorf("工具 %s 的 annotations 字段不完整", tl.Name)
continue
}
if *an.OpenWorldHint {
t.Errorf("工具 %s 操作本平台数据,不应标 openWorld", tl.Name)
}
if *an.ReadOnlyHint {
readOnly++
if *an.DestructiveHint {
t.Errorf("工具 %s 同时为只读与破坏性,语义矛盾", tl.Name)
}
}
if *an.DestructiveHint {
destructive++
}
}
if readOnly == 0 || destructive == 0 {
t.Errorf("标注分布异常:只读=%d 破坏性=%d,检查 mcpToolSpecs", readOnly, destructive)
}
t.Logf("工具总数=%d 只读=%d 破坏性=%d", len(tools), readOnly, destructive)
// 抽样确认序列化后字段真实落地(omitempty 会不会把显式 false 吃掉)。
b, err := json.Marshal(tools[0])
if err != nil {
t.Fatalf("序列化失败: %v", err)
}
t.Logf("样例工具 JSON: %s", string(b))
}
func TestMCPInstructionsServedInInitialize(t *testing.T) {
if len(mcpInstructions) == 0 {
t.Fatal("instructions 为空")
}
// 部分客户端(如 Claude Code)在 ~2KB 处截断服务端指令,超长等于白写。
if n := len([]byte(mcpInstructions)); n > 2048 {
t.Errorf("instructions %d 字节,超过 2KB 会被客户端截断,请精简", n)
} else {
t.Logf("instructions 长度=%d 字节", n)
}
a := &app{}
resp := a.mcpDispatch(nil, jsonrpcRequest{
JSONRPC: "2.0", ID: json.RawMessage(`1`),
Method: "initialize", Params: map[string]interface{}{},
})
if resp.Error != nil {
t.Fatalf("initialize 返回错误: %+v", resp.Error)
}
m, ok := resp.Result.(gin.H)
if !ok {
t.Fatalf("initialize 结果类型异常: %T", resp.Result)
}
v, ok := m["instructions"]
if !ok {
t.Fatal("initialize 结果缺少 instructions 字段")
}
if v.(string) != mcpInstructions {
t.Error("initialize 返回的 instructions 与常量不一致")
}
}
func TestMCPToolsListCacheAndOrdering(t *testing.T) {
a := &app{}
call := func() gin.H {
resp := a.mcpDispatch(nil, jsonrpcRequest{
JSONRPC: "2.0", ID: json.RawMessage(`1`),
Method: "tools/list", Params: map[string]interface{}{},
})
m, ok := resp.Result.(gin.H)
if !ok {
t.Fatalf("tools/list 结果类型异常: %T", resp.Result)
}
return m
}
m := call()
if _, ok := m["ttlMs"]; !ok {
t.Error("tools/list 缺少 ttlMs")
}
if _, ok := m["cacheScope"]; !ok {
t.Error("tools/list 缺少 cacheScope")
}
// 确定性排序:同版本跨请求顺序必须一致(利于客户端缓存与 LLM prompt cache 命中)。
names := func(m gin.H) []string {
var out []string
for _, tl := range m["tools"].([]MCPTool) {
out = append(out, tl.Name)
}
return out
}
first := names(m)
second := names(call())
if len(first) != len(second) {
t.Fatalf("两次调用工具数不一致: %d vs %d", len(first), len(second))
}
for i := range first {
if first[i] != second[i] {
t.Fatalf("第 %d 位顺序不稳定: %s vs %s", i, first[i], second[i])
}
}
t.Logf("工具顺序稳定,共 %d 个", len(first))
}
// TestMCPUsageGuide 守护「场景作业指南」工具:
// 场景键与 mcpToolList 里 enum 声明的一致性靠本测试的场景清单穷举,
// 新增场景若只改 enum 不改 mcpGuideBodies(或反之),这里立刻失败。
func TestMCPUsageGuide(t *testing.T) {
text, unknown, isErr := mcpUsageGuide(map[string]interface{}{})
if unknown || isErr {
t.Fatalf("总览应正常返回: unknown=%v isErr=%v", unknown, isErr)
}
for _, want := range []string{"铁律", "场景路由", "whoami"} {
if !strings.Contains(text, want) {
t.Errorf("总览缺少关键内容: %s", want)
}
}
for _, key := range []string{"query", "ingest", "modeling", "classification", "access", "knowledge", "backup", "review", "training", "gotchas"} {
body, _, isErr := mcpUsageGuide(map[string]interface{}{"scenario": key})
if isErr {
t.Errorf("场景 %s 应正常返回却报错", key)
continue
}
if len(body) < 100 {
t.Errorf("场景 %s 内容过短(%d 字节),疑似遗漏", key, len(body))
}
}
_, _, isErr = mcpUsageGuide(map[string]interface{}{"scenario": "不存在的场景"})
if !isErr {
t.Error("未知场景应返回 isErr 并列出可选值")
}
// 容错:大小写与首尾空格
if _, _, isErr := mcpUsageGuide(map[string]interface{}{"scenario": " Query "}); isErr {
t.Error("scenario 应容忍大小写与首尾空格")
}
// 注:tools/call 全链路(分发 → content 文本)依赖 DB 鉴权链路,
// 按项目约定归 integration 标签;此处不重复造 DB 基建。
// 分发接线(case "get_usage_guide")由编译期保证,线上 smoke 另行验证。
}
+4
View File
@@ -373,6 +373,10 @@ func registerRoutes(r *gin.Engine, a *app) {
api.Any("/mcp", a.mcpAuth(), a.mcpHandle)
// MCP 工具清单(人类可读的自描述,供参考/调试)
api.GET("/mcp/manifest", a.mcpManifest)
// 本体差距扫描工具包(内嵌二进制,对外零 git 依赖)
api.GET("/review-kit", a.reviewKitIndex)
api.GET("/review-kit/archive", a.reviewKitArchive)
api.GET("/review-kit/:name", a.reviewKitFile)
}
func (a *app) managerAuth() gin.HandlerFunc {
+228
View File
@@ -0,0 +1,228 @@
package main
import (
"sort"
"strings"
)
// 本文件是「场景作业指南」的服务端实现:把原 ssw-ontology-ops skill 的场景路由、
// 铁律与 SOP 固化为 MCP 工具 get_usage_guide,任何接入方开箱即用,无需安装 skill。
//
// 与 instructions 的分工:
// - instructions(~1.5KB,客户端可能截断)= 起步速查,随 initialize 下发;
// - 本工具 = 完整 SOP,按需调用、按场景取,不占初始上下文。
// 内容变更只需改本文件;工具 schema 定义在 handlers_mcp.go 的 mcpToolList。
// mcpGuideOverview 不带参数时返回:铁律 + 三步启动 + 场景路由 + 破坏性工具警示。
const mcpGuideOverview = `尚数网本体 MCP · 场景作业指南
【铁律】每次执行前过一遍
1. 先 whoami 确认主体与 can_write;写不了就停下来说明,别硬试
2. 查库为空 ≠ 数据不存在——绝大多数是主体 clearance 不够,先查权限再补数据
3. 任何批量写/删除/改 schema/重算分级前,先 backup_create 留回滚点
4. 默认 merge 语义,禁用 replace:true(会丢字段);删字段传 null
5. recompute_classification 先 dry_run 看影响面,确认后才 apply:true
6. 知识库只收 Markdown,docx/pdf/xlsx 须客户端先转 .md
7. 永不写死 host;密钥/明文 API Key 不进提示词
8. 结论必须溯源:每条标注 type:pk,查不到就答「本体暂无」,禁止编造
【三步启动】会话首次必做
whoami → get_server_info({include_changelog:false}) → get_object_types
类型数量以 get_object_types 实时返回为准,不要写死(历史上 59→47→42 变过多次)。
【场景路由】把 scenario 参数传给 get_usage_guide,拿对应场景的完整 SOP:
- query 查数问答:找实体/问业务/拉全景/看邻居
- ingest 批量入库:表格/结构数据 → 实例
- modeling 建模:建类型/加属性/建关系/改枚举
- classification 分级治理:类型默认级/实例覆盖层/重算
- access 权限调整:主体能看到哪几层
- knowledge 知识库入库:文档 → md → KM → 抽取成实例
- backup 备份回滚与去重:快照/回滚/相似合并
- review 差距扫描核对:资料 vs 本体体检,产出两类型执行清单
- training 员工培训:业务全景+按需学习+考核闭环
- gotchas 坑位速查:十条血泪清单
【破坏性工具】delete_object / km_delete / backup_delete / set_principal_clearance
调这四个前务必确认范围。set_principal_clearance 是全量替换,传空数组 = 清空该主体全部权限。`
// mcpGuideBodies 各场景的完整 SOP。内容与 ssw-ontology-ops skill 的 scenarios/ 同源,
// 此处为精简可执行版(skill 保留更长的背景与复现命令)。
var mcpGuideBodies = map[string]string{
"query": `场景 S1 · 查数问答
工具序列:search_ontology → get_object → query_related(过滤值先用 get_facets 取)
① 先 whoami 确认主体;权限不足就停下来说明,不要硬编数据
② search_ontology({q, field:"all"}) 找候选;限定类型加 type 参数
③ get_object({type, pk}) 取完整属性核对,不得只凭搜索摘要下结论
④ 属性过滤先用 get_facets 拿到真实取值(不要猜),再 query_related({type, filters, expand})
⑤ 看上下游关系用 expand:"<链接类型>" 展开邻居
⑥ 取全量看 total/has_more,用 offset 翻页(limit 上限 1000)
⑦ 每条结论标注「本体出处 type:pk」;查不到就明确回答本体暂无
可直接复制的提示词:
用 shangshu-ontology MCP 回答:<你的问题>。先 whoami 确认主体;search_ontology 找候选后必须 get_object 核对详情;过滤值先用 get_facets 取真实取值再 query_related;每条结论标注 type:pk 出处,查不到就答本体暂无,禁止凭记忆编造。`,
"ingest": `场景 S2 · 批量入库
工具序列:create_object → batch_create_objects → create_link / batch_create_links
① whoami 确认 can_write,否则中止
② 写入前 backup_create({notes}) 留回滚点
③ 主键 pk 命名规范:稳定小写+业务标识,避免歧义重复
④ 单条用 create_object;≥20 条用 batch_create_objects({items, stop_on_error:false})
⑤ 默认 merge 语义,禁止 replace:true;要删字段传 null
⑥ 每条带 source 溯源标签
⑦ 关系边用 create_link / batch_create_links
⑧ 完成后 find_duplicates({type}) 自检,重复项用 same_as 归并,不要硬删
可直接复制的提示词:
用 shangshu-ontology MCP 把 <数据来源描述> 导入本体,目标类型 <Type>。先 whoami + backup_create;单条 create_object、≥20 条 batch_create_objects;默认 merge 禁 replace;每条带 source;关系边用 create_link;完成后 find_duplicates 自检,重复用 same_as 归并勿硬删。`,
"modeling": `场景 S3 · 建模(新建元原语)
工具序列:create_object_type / add_object_type_property / create_link_type / update_enum
① whoami + backup_create 先行
② 先确认不是重复建设:get_object_types 找是否已有等价类型,有则复用不要新建
③ 建类型 create_object_type({api_name, display_name, properties}) 一次性内联关键属性
④ 已有类型加属性 add_object_type_property({api_name, property_api_name, display_name, data_type, enum_values})
⑤ 两类之间有关系就 create_link_type({api_name, source_type, target_type, cardinality})
⑥ 枚举扩充 update_enum({type, property, add_values}),不要改 schema 也不要动 SQL
⑦ 建完 get_object_types 复核一次
可直接复制的提示词:
用 shangshu-ontology MCP 补建本体元原语:<缺失的类型/属性/关系/枚举>。先 whoami + backup_create;先 get_object_types 确认无等价类型再新建;建类型内联关键属性;关系用 create_link_type;枚举用 update_enum 追加;建完 get_object_types 复核。`,
"classification": `场景 S4 · 分级治理
工具序列:get_classification_config → add_object_type_property(如缺)→ set_object_type_classification → recompute_classification
① whoami + backup_create 先行
② get_classification_config 看现状(当前 property / levels / default / 分布)
③ 顺序铁律:类型上没有承载分级的属性时,先 add_object_type_property 注册(enum=[L0..L4],如 classification),
再 set_object_type_classification({api_name, classification_property, classification_levels, classification_default});
直接设未注册的属性会 400「类型没有属性 X」
④ set 完必须 recompute_classification({type, dry_run:true}) 看影响面,确认无误才 apply:true
⑤ 两层模型:objects.classification 列 = 类型默认级(recompute 只写这里);
object_markings = 实例覆盖层(recompute 不碰,需单实例接口整替换)
⑥ 五层词汇:L0公众/L1客户/L2员工/L3经理以上/L4公司管理层;classification_default 必须 ∈ levels
可直接复制的提示词:
用 shangshu-ontology MCP 调整分级:<类型/实例> 的可见级别。先 get_classification_config 看现状;类型缺承载属性先 add_object_type_property 注册再 set_object_type_classification;改完 recompute_classification 先 dry_run 后 apply;员工主体锁 L0–L2,要让员工看到某数据就降该数据类型默认级。`,
"access": `场景 S5 · 权限调整
工具序列:get_principal → set_principal_clearance → list_principals 复核
① whoami 确认自己有权改
② 改前必须 get_principal({name}) 备份当前 clearances——这是全量替换接口,没有增量
③ set_principal_clearance({name, clearances:[...]});传空数组 = 清空全部权限,
传漏层级会让该主体一个实例都看不到
④ 员工类主体保持在 L0–L2,不要提到 L3/L4;要让员工看到某数据,正解是
把该数据的类型默认级降到 L2,而不是抬高员工
⑤ 改完 list_principals() 复核
⑥ manager 主体硬编码读全量,不受 clearance 影响
可直接复制的提示词:
用 shangshu-ontology MCP 调整主体 <name> 的可见范围到 [L0,L1,L2]。先 get_principal 备份当前 clearances 再 set_principal_clearance 全量替换;传空=清空、传漏层级=全不可见;员工锁 L0–L2;改完 list_principals 复核。`,
"knowledge": `场景 S6 · 知识库入库
工具序列:km_list_tree → km_create_folder(如需)→ km_upload_markdown → km_extract → set_km_classification
① whoami 确认 can_write
② 平台只收 Markdown:docx/pdf/xlsx 必须先在客户端转成 .md
③ km_list_tree 看现有归类,决定放哪个文件夹;必要时 km_create_folder
④ km_upload_markdown({filename, content, folder})——filename 必须 .md 结尾
⑤ km_extract({rel_paths, mode:"review"}) 先看建议,确认后 mode:"auto" 正式抽取
⑥ 高敏文件 set_km_classification({rel_paths, classification}) 抬产物下界
⑦ 误入库用 km_delete 级联回滚(会连带删抽取实例,务必确认范围)
可直接复制的提示词:
用 shangshu-ontology MCP 把 <文档路径> 沉淀进知识库并抽取成本体实例。平台只收 Markdown,原档先转 .md;km_list_tree 定文件夹;km_upload_markdown 上传;km_extract 先 review 后 auto;高敏文件 set_km_classification;误删用 km_delete 级联回滚。`,
"backup": `场景 S7 · 备份 / 回滚 / 去重
A 写前保险:backup_create({notes}) → 记住返回的 id
B 比对历史:backup_list → backup_switch({id}) → 后续 GET 带 X-Snapshot-Id: <id> 命中快照。
快照只读,写方法带快照头会被 403 拒绝;用完不必切换回去
C 去重:find_duplicates({type, threshold}) 拿相似分组,人工确认后用
create_object({pk, same_as:"<canonical_pk>"}) 归并;
确需删除才 delete_object(物理删+级联清边),或 create_object({deleted:true}) 软删;
误删 restore_object({type, pk}) 恢复属性(不恢复关系边)
D 回收归档:backup_inspect({id}) 确认表清单 → backup_delete({id}) 级联清除`,
"review": `场景 S8 · 差距扫描与核对(本体体检)
用途:资料更新后想知道「本体漏了什么」;周期性体检;新同事建立差距视图。
流程:
① 定范围:资料目录聚焦核心内容(实例量大时避免噪音)
② 拿扫描器(内嵌于本体二进制,对外零 git 依赖,无需 clone 任何仓库):
curl -O <本体host>/api/v1/review-kit/archive # tar.gz 打包(推荐,含扫描器+schema+提示词+示例)
# 或单文件:curl -O <本体host>/api/v1/review-kit/scan.py
# 索引与用途说明:GET <本体host>/api/v1/review-kit
python3 scan.py --mcp-url <本体host>/api/v1/mcp --mcp-key <API Key> \
--docs <资料目录> --output review-manifest.json
本机已有 ~/.workbuddy/mcp.json 时也可 --mcp-config 自动拼 URL;加 --extract-only 先看候选准不准;
host 取实际部署地址,不写死
③ AI 精修 findings → items[]:过滤误报(普通名词/章节标题)、合并同类、分级。
每条 item 只能是两种 kind 之一:
- operation:{method, params} 直连 MCP 写入工具(create_object_type / create_link_type /
update_enum / create_object / create_link)
- document:{filename, markdown} 走 km_upload_markdown + km_extract
严禁出现「需 schema 迁移 / 需管理员 SQL / 需手工」——这些已被 MCP 写入工具覆盖
④ 引导用户到平台内置核对页:<mcp-host>/import-review.html(host 从 MCP 配置推导,
只截掉 /api/v1/mcp 后缀,绝不硬编码 127.0.0.1)。页面自动载入 /builtin-review-manifest.json
示例清单,也可「导入 JSON」载入 scan 产物;可写主体直接 Apply,只读主体导出 JSON/MD 交管理员
⑤ 本流程只读本体 + 产出清单,写回由人在核对页执行
策展决策(快速参考):
- 文章描述 N 类相似业务(≥4 类)→ 1 元原语 + 1 document,别建 N 个对象类型(schema 碎片化)
- 文档缺核心 schema → operation create_object_type;资料描述两对象间关系 → create_link_type
- 整篇作为知识沉淀 → document;scan 0 候选 → 补正则词表或直接策展,别反复扫判 0`,
"training": `场景 S9 · 员工培训闭环(用本体当知识源)
核心原则:先按尚数网整体业务铺全景 → 个体再按需单独提问、单独学习。
取数只走 MCP,禁止凭记忆编造定义(内容新鲜度 = 本体新鲜度)。
模式 A · 业务全景(默认,必先做):
① get_object_types 取全量类型(数量动态,禁写死)→ 归入业务域。参考框架六域:
定位 / 生态 / 流程 / 技术底座 / 合规与安全 / 知识内容——域归属以 get_object_types 实时返回为准
② 每域 search_ontology({type, field:"all"}) 拉真实实例
③ 每域配一张 SVG 关系图:节点必须对应本体真实类型,图下标注「本体出处 type:pk」
模式 B · 个体按需:
学员任意提问 → search_ontology({q, field:"all"}) 跨类型检索 → 聚焦讲解 + 关系图 +
延伸阅读(相关实例 pk)+ 可选追加出题。岗位聚焦 = 模式 A 的下钻。
三阶段闭环(两种模式共用):
1 培训:要点式讲解 + 每域 SVG 关系图
2 自习:知识点对应本体实例整理成「勾选已读 → 解锁考核」清单
3 考核:基于真实数据出单选,每题附解析 + 出处 + 关联知识点;答错汇总知识缺口清单
可选写回:ingest/manager 主体把培训记录/缺口写回本体,source=training:<session_id>
边界:
- 本体是知识源,不是培训平台;课程进度/学员档案/成绩在调用方侧
- 默认只读主体(connector/analyst)即可培训出题,不越权;写回才需 ingest
- 讲解/出题前务必实时 search_ontology`,
"gotchas": `坑位速查(血泪清单)
1. 写入全 401 / 说没权限 → 主体不含 manager,can_write=false。正解:whoami 确认;用 MCP 通道(本地桥),别直连 REST
2. 直连 REST 401 但 key 对 → Bash 沙箱注入代理剥掉 X-API-Key 头。正解:优先走 MCP;必须直连时沙箱外执行 + env -u 清代理变量
3. 查什么都为空 → clearance 不够,非数据缺失。正解:list_principals / get_principal 核对星级,别盲目补数据
4. 改 clearance 后主体瞎了 → set_principal_clearance 是全量替换,传空=清空。正解:改前先 get_principal 备份原值
5. 设分级报 400「类型没有属性 X」→ classification_property 指向未注册属性。正解:先 add_object_type_property 注册,再设配置
6. 写入后字段莫名少了 → 用了 replace:true。正解:默认 merge;删字段传 null
7. 写入被拒 stale_write 409 → source_ts 比已有值旧。正解:旧信息不覆盖新信息,确认时间戳或不用该字段
8. 列表只拿到一部分 → get_objects_by_type 有分页。正解:看 total/has_more,用 offset 翻页,limit 上限 1000
9. 上传 KM 被拒 → 传了二进制/非 .md。正解:客户端先转 Markdown;filename 必须 .md 结尾
10. 实例名称没按预期显示 → objects.name 按回退链物化:title_property → name → title → real_name → display_name → label`,
}
// mcpUsageGuide get_usage_guide 的工具体:静态内容,不触库、不需鉴权(与 get_server_info 同)。
// 返回 (text, unknown, isErr)。
func mcpUsageGuide(args map[string]interface{}) (string, bool, bool) {
key, _ := args["scenario"].(string)
key = strings.ToLower(strings.TrimSpace(key))
if key == "" {
return mcpGuideOverview, false, false
}
body, ok := mcpGuideBodies[key]
if !ok {
keys := make([]string, 0, len(mcpGuideBodies))
for k := range mcpGuideBodies {
keys = append(keys, k)
}
sort.Strings(keys)
return "未知场景: " + key + "。可选值: " + strings.Join(keys, " / ") +
";不传 scenario 则返回总览(铁律+场景路由)。", false, true
}
return body, false, false
}
+20 -2
View File
@@ -214,7 +214,25 @@ type ConnectorObjectType struct {
// MCPTool MCP 工具清单中的单个工具描述(供 WorkBuddy 等接入)。
type MCPTool struct {
Name string `json:"name"`
Description string `json:"description"`
Name string `json:"name"`
Title string `json:"title,omitempty"`
Description string `json:"description"`
InputSchema map[string]interface{} `json:"inputSchema"`
Annotations *MCPToolAnnotations `json:"annotations,omitempty"`
}
// MCPToolAnnotations 工具行为提示(spec ToolAnnotations,含 legacy 同名 hints)。
// 指针字段让 omitempty 能区分"未标注"与"显式 false",避免语义丢失。
//
// 注意:规范明确规定这些仅为 hints,客户端 MAY 据此自动放行只读 / 对破坏性操作二次确认,
// 但 MUST 视其为不可信输入,不得单独作为安全判据(服务端自身的鉴权才是边界)。
type MCPToolAnnotations struct {
// ReadOnlyHint true = 不修改环境
ReadOnlyHint *bool `json:"readOnlyHint,omitempty"`
// DestructiveHint true = 可能执行破坏性更新;false = 仅增量更新
DestructiveHint *bool `json:"destructiveHint,omitempty"`
// IdempotentHint true = 同参数重复调用无额外副作用
IdempotentHint *bool `json:"idempotentHint,omitempty"`
// OpenWorldHint true = 与外部开放实体交互;false = 封闭世界
OpenWorldHint *bool `json:"openWorldHint,omitempty"`
}
+136
View File
@@ -0,0 +1,136 @@
package main
import (
"archive/tar"
"compress/gzip"
"embed"
"net/http"
"path"
"sort"
"strings"
"github.com/gin-gonic/gin"
)
// reviewKitFS 内嵌「本体差距扫描工具包」——对外分发的本体实例不依赖任何外部
// git 仓库:扫描器、清单 schema、AI 精修提示词、示例输出全部随二进制发布,
// 通过 /api/v1/review-kit 端点本地获取。
//
// 目录内容来源:原 ssw-ontology-reviewer skill(2026-10-15 并入
// get_usage_guide 的 review 场景,脚本资产收进此处)。
//
//go:embed reviewkit
var reviewKitFS embed.FS
// reviewKitRead 从内嵌文件系统读取工具包文件;拒绝路径穿越(.. / 绝对路径 /
// 子目录前缀),只允许 reviewKitFiles 表内的顶层文件名。
func reviewKitRead(name string) ([]byte, bool) {
if name == "" || strings.Contains(name, "..") || strings.Contains(name, "/") || strings.Contains(name, "\\") {
return nil, false
}
if _, ok := reviewKitFiles[name]; !ok {
return nil, false
}
data, err := reviewKitFS.ReadFile("reviewkit/" + name)
if err != nil {
return nil, false
}
return data, true
}
// reviewKitFiles 工具包文件清单(名称 → 用途说明),用于索引端点与
// tar 包内注释。新增文件必须同步此表,测试会校验一致性。
var reviewKitFiles = map[string]string{
"scan.py": "零依赖 Python 扫描器(仅标准库):比对资料文档与本体当前状态,产出 review-manifest.json。不消耗 LLM token",
"review-manifest-schema.json": "review-manifest.json 的 JSON Schema,供校验/精修阶段参照",
"analysis-prompt.md": "AI 精修提示词:把 findings 精修成 operation/document 两类型执行清单",
"mcp-review-proxy.js": "Node 代理脚本:AI 经 MCP 操作本体时的 JSON-RPC 中转(SSE 兼容)",
"example-output.json": "示例输出:接口/数据类资料的 manifest 长什么样",
"example-output-business-article.json": "示例输出:业务文章类资料的 manifest 长什么样",
}
// reviewKitContentType 按扩展名给内容类型(扫描器要能直接跑/直接引)。
func reviewKitContentType(name string) string {
switch strings.ToLower(path.Ext(name)) {
case ".py":
return "text/x-python; charset=utf-8"
case ".json":
return "application/json; charset=utf-8"
case ".js":
return "text/javascript; charset=utf-8"
case ".md":
return "text/markdown; charset=utf-8"
default:
return "application/octet-stream"
}
}
// reviewKitIndex GET /api/v1/review-kit —— 工具包索引(有哪些文件、干什么用)。
func (a *app) reviewKitIndex(c *gin.Context) {
files := reviewKitList()
c.JSON(http.StatusOK, gin.H{
"kit": "ssw-ontology-review-kit",
"note": "本体差距扫描工具包,内嵌于本体二进制,无需外部 git 仓库。单文件下载:GET /api/v1/review-kit/<文件名>;打包下载:GET /api/v1/review-kit/archive",
"usage": "python3 scan.py --mcp-url <本体MCP地址> --mcp-key <API Key> --docs <资料目录> --output review-manifest.json;完整步骤调 get_usage_guide({scenario:\"review\"})",
"files": files,
})
}
// reviewKitFile GET /api/v1/review-kit/:name —— 下载单个文件。
func (a *app) reviewKitFile(c *gin.Context) {
name := c.Param("name")
if name == "archive" {
a.reviewKitArchive(c)
return
}
data, ok := reviewKitRead(name)
if !ok {
c.JSON(http.StatusNotFound, gin.H{"error": "工具包无此文件: " + name, "available": reviewKitNames()})
return
}
c.Data(http.StatusOK, reviewKitContentType(name), data)
}
// reviewKitArchive GET /api/v1/review-kit/archive —— tar.gz 打包下载(一次拿全套)。
func (a *app) reviewKitArchive(c *gin.Context) {
c.Header("Content-Type", "application/gzip")
c.Header("Content-Disposition", "attachment; filename=review-kit.tar.gz")
gz := gzip.NewWriter(c.Writer)
defer gz.Close()
tw := tar.NewWriter(gz)
defer tw.Close()
for _, name := range reviewKitNames() {
data, _ := reviewKitRead(name)
hdr := &tar.Header{
Name: name,
Mode: 0o644,
Size: int64(len(data)),
}
if err := tw.WriteHeader(hdr); err != nil {
return
}
if _, err := tw.Write(data); err != nil {
return
}
}
}
// reviewKitNames 排序后的文件名列表(确定性输出)。
func reviewKitNames() []string {
names := make([]string, 0, len(reviewKitFiles))
for n := range reviewKitFiles {
names = append(names, n)
}
sort.Strings(names)
return names
}
// reviewKitList 索引条目(名称/大小/用途)。
func reviewKitList() []gin.H {
list := make([]gin.H, 0, len(reviewKitFiles))
for _, n := range reviewKitNames() {
data, _ := reviewKitRead(n)
list = append(list, gin.H{"name": n, "bytes": len(data), "purpose": reviewKitFiles[n]})
}
return list
}
File renamed without changes.
+148
View File
@@ -0,0 +1,148 @@
package main
import (
"archive/tar"
"bytes"
"compress/gzip"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"github.com/gin-gonic/gin"
)
// TestReviewKitEmbedded 工具包必须完整内嵌于二进制:表内每个文件都能读出且非空,
// 且内嵌目录里不能有表外的孤儿文件(新增资产忘登记会失败)。
func TestReviewKitEmbedded(t *testing.T) {
entries, err := reviewKitFS.ReadDir("reviewkit")
if err != nil {
t.Fatalf("读取内嵌目录失败: %v", err)
}
embedded := map[string]bool{}
for _, e := range entries {
if e.IsDir() {
t.Errorf("工具包不应含子目录: %s", e.Name())
continue
}
embedded[e.Name()] = true
}
for name := range reviewKitFiles {
if !embedded[name] {
t.Errorf("登记表内的文件未内嵌: %s", name)
}
data, ok := reviewKitRead(name)
if !ok || len(data) == 0 {
t.Errorf("文件读不出或为空: %s", name)
}
}
for name := range embedded {
if _, ok := reviewKitFiles[name]; !ok {
t.Errorf("内嵌文件未登记用途: %s(请补进 reviewKitFiles)", name)
}
}
t.Logf("工具包 %d 个文件全部内嵌且非空", len(embedded))
}
// TestReviewKitPathTraversal 路径穿越必须被拒。
func TestReviewKitPathTraversal(t *testing.T) {
for _, bad := range []string{
"../main.go", "..", "/etc/passwd", "reviewkit/scan.py", "sub/dir/scan.py", `..\main.go`, "",
} {
if _, ok := reviewKitRead(bad); ok {
t.Errorf("路径穿越未被拒绝: %q", bad)
}
}
}
// TestReviewKitHTTPEndpoints 三个端点的行为:索引 JSON / 单文件 / tar.gz / 404。
func TestReviewKitHTTPEndpoints(t *testing.T) {
gin.SetMode(gin.TestMode)
a := &app{}
// ① 索引
w := httptest.NewRecorder()
c, _ := gin.CreateTestContext(w)
c.Request = httptest.NewRequest("GET", "/api/v1/review-kit", nil)
a.reviewKitIndex(c)
if w.Code != http.StatusOK {
t.Fatalf("索引应 200,实际 %d", w.Code)
}
var idx struct {
Kit string `json:"kit"`
Files []gin.H `json:"files"`
}
if err := json.Unmarshal(w.Body.Bytes(), &idx); err != nil {
t.Fatalf("索引不是合法 JSON: %v", err)
}
if idx.Kit != "ssw-ontology-review-kit" || len(idx.Files) != len(reviewKitFiles) {
t.Fatalf("索引内容异常: kit=%s files=%d", idx.Kit, len(idx.Files))
}
// ② 单文件(content-type + 内容非空 + 与内嵌一致)
for name, wantType := range map[string]string{
"scan.py": "text/x-python; charset=utf-8",
"review-manifest-schema.json": "application/json; charset=utf-8",
"mcp-review-proxy.js": "text/javascript; charset=utf-8",
"analysis-prompt.md": "text/markdown; charset=utf-8",
} {
w = httptest.NewRecorder()
c, _ = gin.CreateTestContext(w)
c.Request = httptest.NewRequest("GET", "/api/v1/review-kit/"+name, nil)
c.Params = gin.Params{{Key: "name", Value: name}}
a.reviewKitFile(c)
if w.Code != http.StatusOK {
t.Fatalf("%s 应 200,实际 %d", name, w.Code)
}
if got := w.Header().Get("Content-Type"); got != wantType {
t.Errorf("%s content-type = %q, 期望 %q", name, got, wantType)
}
want, _ := reviewKitRead(name)
if !bytes.Equal(w.Body.Bytes(), want) {
t.Errorf("%s 响应体与内嵌内容不一致", name)
}
}
// ③ 不存在的文件 → 404
w = httptest.NewRecorder()
c, _ = gin.CreateTestContext(w)
c.Request = httptest.NewRequest("GET", "/api/v1/review-kit/nope.py", nil)
c.Params = gin.Params{{Key: "name", Value: "nope.py"}}
a.reviewKitFile(c)
if w.Code != http.StatusNotFound {
t.Errorf("不存在文件应 404,实际 %d", w.Code)
}
// ④ archive:合法 gzip,解 tar 后文件数与清单一致、无未登记文件、无空文件
w = httptest.NewRecorder()
c, _ = gin.CreateTestContext(w)
c.Request = httptest.NewRequest("GET", "/api/v1/review-kit/archive", nil)
c.Params = gin.Params{{Key: "name", Value: "archive"}}
a.reviewKitArchive(c)
if w.Code != http.StatusOK {
t.Fatalf("archive 应 200,实际 %d", w.Code)
}
gzr2, err := gzip.NewReader(bytes.NewReader(w.Body.Bytes()))
if err != nil {
t.Fatalf("archive 不是合法 gzip: %v", err)
}
defer gzr2.Close()
tr := tar.NewReader(gzr2)
count := 0
for {
hdr, err := tr.Next()
if err != nil {
break
}
if hdr.Size == 0 {
t.Errorf("tar 内文件为空: %s", hdr.Name)
}
if _, ok := reviewKitFiles[hdr.Name]; !ok {
t.Errorf("tar 内含未登记文件: %s", hdr.Name)
}
count++
}
if count != len(reviewKitFiles) {
t.Errorf("tar 内文件数 = %d, 期望 %d", count, len(reviewKitFiles))
}
}
-347
View File
@@ -1,347 +0,0 @@
---
name: ssw-ontology-reviewer
description: 尚数网本体差距自动扫描与核对技能。驱动 AI 对照本体 MCP 自动审计:扫描资料 vs 本体现状 → 产出"应掌握但未掌握/过期"的核对清单 → 导出 JSON 执行清单(含 operation/document 两类型,无需 AI 再解析) → 提示用户到 `<mcp-host>/import-review.html` 处理(**不写死 127.0.0.1**,根据 MCP 配置拼接)。用于:本体体检、资料与本体一致性审计、版本更新后差异核对、技能体系/产品体系盘点、连接器/MCP 对接自检。触发词:核对本体、扫描本体、本体差距、资料对照本体、本体缺失什么、ontology review、gap scan。
layer: L1
maturity: beta
version: 1.2.0
owner: 尚数网平台组
requires: []
sources:
- scripts/scan.py(零依赖自动扫描器,含 PRODUCT_RE/CHINESE_PRODUCT_RE/BUSINESS_DOMAIN_RE 三类正则)
- references/review-manifest-schema.json(输出 JSON schema)
- references/mcp-review-proxy.js(远程访问 MCP 的本地反向代理,与本平台解耦)
- references/example-output.json(基础输出样例:技术架构类)
- references/example-output-business-article.json(实战案例:业务类文章 → 1 元原语 + 1 document)
- templates/analysis-prompt.md(Agent 精修提示词 + 典型策展决策)
verified: 2026-08-21
---
# 尚数网本体差距自动扫描与核对
> **本技能 = "驱动 AI 对照 MCP 做本体审计 + 导出可执行 JSON + 引导用户到核对页面"**。
> 任何同事只要有自己的本体 MCP 端点(来自 `~/.workbuddy/mcp.json` 或扫描器自动探测),AI 就能:
> 1. **AI 驱动审计**:扫描器直连 MCP 拉本体现状 + 解析资料目录 → 产出 37 项级别 findings → AI 精修为可执行 items
> 2. **导出两类型 JSON**:operation(method+params 直连 MCP 写入工具应用)/ document(filename+markdown 走 km_upload_markdown+km_extract)—— **管理员拿到后无需再解析、无需 SQL**
> 3. **引导到核对页面**:根据 MCP 配置中的 host 拼接出 `<mcp-host>/import-review.html`(**不写死 127.0.0.1**),管理员/同事在该页面点「导入 JSON」载入清单 → 逐项核对 / Apply
## 什么时候用
- 资料(技术架构/产品白皮书/需求文档)更新后,想知道"本体漏了什么"
- 周期性本体体检:本体应掌握但没掌握 / 已过期
- 资料与"尚数网技能体系"等内部资产做一致性审计
- 新同事接手本体,先扫一遍建立差距视图
- **业务类文章**(供需撮合/政策文件/招标公告)→ 自动建立 `DataDemand`/`DataProvider` 等业务元原语 + 抽取嵌入实例
## 典型策展决策(快速参考)
| 场景 | 正解 | 反模式 |
|---|---|---|
| 文章描述 N 类相似业务(≥4 类) | **1 元原语 + 1 document**(AI 抽 N 个实例)| N 个对象类型(schema 碎片化)|
| 1 篇文章涵盖多章节知识 | **1 个 document 涵盖全文** | 拆 N 个 doc 重复摘要 |
| 文档缺核心 schema | operation `create_object_type`(red/orange)| 占位 doc |
| 资料描述两对象间关系 | operation `create_link_type`(amber)| 占位 doc |
| 整篇作为知识库沉淀 | document(blue)| 占位 item |
| scan 0 候选 | 加 `BUSINESS_DOMAIN_RE` 或直接策展 | 反复扫判 0 |
完整决策依据见 `templates/analysis-prompt.md` 末尾"典型策展决策"段。实战案例见 `references/example-output-business-article.json`(供需撮合·第三十二期)。
## 设计铁律(对齐"本机能力优先 → LLM 兜底")
- **扫描零 LLM 消耗**:`scan.py` 纯 HTTP + 正则 + 结构化比对,不调任何大模型。
- **LLM 只在精修阶段介入**:把机械 findings 过滤误报、合并、分级、写抽取描述 → 生成两类型 `items[]`。
- **不改本体**:本技能只"读 + 产出 JSON"。写回本体由管理员在主站「导入核对」tab 或独立页 `/import-review.html` 通过 MCP 写入工具(`create_object_type` / `create_link_type` / `update_enum` / `create_object` / `create_link` / `km_extract` 等)执行。
- **密钥不下落**:`review-manifest.json` 的 `meta.mcp_host` 只记主机名/端口,**绝不存 key**。导出 JSON 的 `meta.auth` 字段永远是 `X-API-Key: ***(已隐藏,避免泄漏)`。
- **不写死 URL**:引导用户到 `<mcp-host>/import-review.html` 时,`<mcp-host>` 从 MCP 配置(`~/.workbuddy/mcp.json` 或扫描时的 `--mcp-url`)拼接,绝不假设 `127.0.0.1`。
---
## 一、扫描方法(四种用法)
`scan.py` 零依赖(仅 Python 标准库),直连本体 MCP(Streamable HTTP / JSON-RPC 2.0,兼容 SSE 响应),做确定性比对。
```bash
# ① 仅列出本体对象类型(探活 / 调试 / 确认端点可达)
python3 scripts/scan.py \
--mcp-url http://<你的本体host>:<port>/api/v1/mcp \
--mcp-key <你的 API Key> \
--list-types
# ② 仅抽取候选术语(不调本体,纯文档解析,用于先看抽得准不准)
python3 scripts/scan.py --docs /path/to/资料目录 --extract-only
# ③ 全量扫描:抽候选 + 逐条 search 本体 → 产出 review-manifest.json(findings)
python3 scripts/scan.py \
--mcp-url http://<你的本体host>:<port>/api/v1/mcp \
--mcp-key <你的 API Key> \
--docs /path/to/资料目录 \
--output review-manifest.json
# ④ 自动从 WorkBuddy MCP 配置读 URL(推荐,**不写死 host**)
python3 scripts/scan.py \
--mcp-config ~/.workbuddy/mcp.json \
--server-name shangshu-ontology \
--mcp-key <你的 API Key, 可省略则取配置文件 headers.X-API-Key> \
--docs /path/to/资料目录 \
--output review-manifest.json
# ⑤ 配合 Agent 精修:把 findings 交给运行本技能的 Agent → 得到 curated items
```
**通用化要点(避免写死 host)**:
- **不假设 `127.0.0.1` / `localhost` / `8081`**——同事的本机、内网、staging、prod 任意地址都能用。
- 推荐用 `④ 自动从 MCP 配置读` 方式:URL、key 都不用手动填,脚本从 `~/.workbuddy/mcp.json` 里的 `mcpServers.<server>.url` + `headers.X-API-Key` 抓出来。
- 输出 manifest 的 `meta.mcp_host` 与 `meta.reviewer_url` 字段是扫描时实际使用的值,**不是**写死的占位符——下游 Agent 直接用它们告诉用户"打开哪个 URL"。
**精度机制**(避免噪声):
- 候选词形:`PRODUCT_RE`(数小*/ssw-*/SSW*/SAOP/Nax/Vue Flow/Flowable/OPA/MCP Router/DAG)+ `CHINESE_PRODUCT_RE`(数据应用超市/密算一体机/海光 CSV/DCU/Zynq-7015/联盟链…)+ 「」引用 + 标题。
- **信号门禁**:候选必须含英文/数字或命中产品词表,纯中文通用标题(概述/架构总览)一律丢弃。
- `SKIP_DIRS` 跳过 `.workbuddy` / `.git` / `node_modules` / `__pycache__`,不扫自身产物与依赖。
**产出**:`review-manifest.json` 的 `meta`(扫描时间、对象类型数、全部类型名、候选数)+ `findings[]`(每个候选的 `ontology_hits` / `matched_names` / `is_object_type` / `severity` / `action`)。
> `findings` 是机械结果,含误报与未分级项;**必须经 Agent 精修**为 `items[]`(自包含 `description` + 4 类 × 3 严重度分级)后才交给工作台/管理员。
---
## 二、如何接本体 MCP
### 端点
```
http://<本体host>:8081/api/v1/mcp
```
Streamable HTTP / JSON-RPC 2.0;响应为 SSE 流(`event: message\ndata: {...}`)。CORS 已开(Allow-Headers 含 `X-API-Key`)。
### WorkBuddy 注册
`~/.workbuddy/mcp.json`:
```json
{
"mcpServers": {
"shangshu-ontology": {
"url": "http://<本体host>:8081/api/v1/mcp",
"headers": { "X-API-Key": "ingest-key-001" }
}
}
}
```
改完在连接器页「自定义连接器」点「信任」。
### ⚠️ 身份陷阱(必读)
- 主体:dev 模式无 key(manager 尚未配置 api_key 的全新库)→ 默认 `manager`;`X-Principal` 可直接指定;`X-API-Key` 命中 principals 表 → 该主体。所有内置主体密钥均由首次启动时随机 seed 生成,不再读取 .env。
- **写权限**仅 `manager` / `ingest`;只读用 `analyst-key-001`。
- **WorkBuddy MCP client 会自动注入 analyst 身份**,删掉 X-API-Key 或换 server name 都无效——要用 `ingest-key-001`(具备 manage 覆盖的 ingest 主体)才能跑 KM 写路径。
### 浏览器直连注意
- 浏览器直连**远程**本体 MCP 常被系统/企业 HTTP 代理拦截(返回 502);本地同源(开 `<host>:8081/` 后切到「导入核对」tab)不受限。
- 远程场景用下方「代理方法」绕开。
---
## 三、MCP 内置核对模板(界面核对 + 权限分流 + 两类型执行)
本体服务**自带**核对工作台、内置清单与代理脚本,任何连上该 MCP 的人都能直接用,无需另装:
| 资源 | 路径 | 说明 |
|---|---|---|
| 主站 SPA | `http://<本体host>:8081/` | 登录后管理员可见 8 个 tab,其中**「导入核对」= 核对工作台**(仅管理员) |
| 内置清单 | `/builtin-review-manifest.json` | 管理员切到「导入核对」自动 fetch 载入的示例核对清单(两类型) |
| 代理脚本 | `references/mcp-review-proxy.js`(本 skill 内部) | 绕开企业代理 502 的本地反向代理,**与本体平台解耦** |
| 自描述 | `GET /api/v1/mcp/manifest` 的 `ui_template` 字段 | 广告上述资源 + 用法(agent 可读 manifest 自我发现) |
### 管理员体验(内置即开即用)
1. 浏览器开 `http://<本体host>:8081/`
2. 登录页用 `manager / changeme`(首次默认密码,立即改)
3. 顶部切到「**导入核对**」tab,自动 fetch `/builtin-review-manifest.json` 载入示例清单——和"原来硬编码 29 项"的体验一致,无需先导入。
4. 同事用 `scan.py` 生成的清单也可点「导入 JSON」载入。
> 本页**不再需要手动填 MCP URL / Key**——身份走 cookie session(管理员登录即等于 manager),URL 走同源(location.origin)。代理脚本也只在远程被拦截时才需要。
### 执行清单只有两种 kind(核心约定)
每条 `items[]` 必为且仅为以下一种,管理员端**无需 AI 再次解析、无需任何 SQL / 人工 schema 迁移**:
| kind | 字段 | 工作台"应用"按钮做什么 |
|---|---|---|
| `operation`(操作项) | `method` + `params` | 直接调对应 MCP 写入工具:`create_object_type` / `create_link_type` / `create_object` / `create_link` / `update_enum` |
| `document`(文档项) | `filename` + `markdown` | 调 `km_upload_markdown` 上传 + `km_extract` 抽取导入 |
> 旧版"需 schema 迁移 / 管理员 SQL / 需手工"的 dead-end 已不存在——`update_enum`(往枚举追加取值)、`create_*` 等新 MCP 工具让所有 schema 类操作都能直接 Apply。
### 用法
1. **直接打开**(推荐,同源无 CORS):`http://<本体host>:8081/` → 登录 → 切到「导入核对」tab(自动载入内置清单)。
2. **经代理打开**(远程被企业代理拦截时):见下方「代理方法」,开 `http://127.0.0.1:9333/`(代理会反向代理整站 SPA)。
3. 导入外部清单:点「导入 JSON」选 `review-manifest.json`(**支持 `items` 或 `findings` 两种结构**);或用 URL `?manifest=<json地址>` 自动加载。
4. ~~填 MCP URL / Key~~(已移除——身份走 cookie session,URL 走同源)。
### 权限分流(核心)
管理员登录后,工作台自动以 cookie session 身份调 `whoami` 探测:
- **可写(manager)** → 横幅「可执行模式」。操作项点「直接应用(MCP)」调对应写入工具;文档项点「导入文档」走 `km_upload_markdown`+`km_extract`。勾选后可「直连 Apply 选中」批量执行。
- **导入核对 tab 本身仅 `is_manager` 可见**——非管理员连入口都看不到;即使用某种方式进入页面,工作台也会自动检测到当前主体无写权限而禁用 Apply 按钮。
### 导出(仅两类型)
- **执行清单 JSON**:`meta.schema` 注明每条 `kind ∈ {operation, document}`;`operation` 带 `method`+`params`、`document` 带 `filename`+`markdown`。管理员拿到后**无需再解析**,直接逐项应用。
- **核对报告 MD**:表格化汇总(名称/分类/执行方式/方法或文件/状态/备注)。
### 代理方法(远程被拦截时)
代理脚本随本技能发布(`references/mcp-review-proxy.js`),与本体平台解耦——任何宿主都能用:
```bash
# 从 skill 拿代理文件
cp ~/.workbuddy/skills/ssw-ontology-reviewer/references/mcp-review-proxy.js ./
PROXY_TARGET=http://<本体host>:8081 node mcp-review-proxy.js
open http://127.0.0.1:9333/
```
代理同源转发整站(SPA + `/api/v1/mcp` + `/builtin-review-manifest.json`),绕开企业代理 502 与 CORS/SSE 解析问题。
---
## 四、Agent 精修(读 templates/analysis-prompt.md)→ 产出两类型 items
把 `findings` 交给运行本技能的 Agent 精修:过滤误报(普通名词/章节标题)、合并同类、按 4 类 × 3 严重度分级,并把每条落为 **`operation` 或 `document` 两种 kind 之一**(详见 `template/analysis-prompt.md` 与 `references/example-output.json`)。结果写回 `review-manifest.json` 的 `items[]`。
映射要点:
- 新建对象类型 / 补属性 → `operation` · `method=create_object_type`(可内联 `properties`)
- 新增关系类型 → `operation` · `method=create_link_type`
- 修订枚举(往属性追加取值)→ `operation` · `method=update_enum`(`params={type,property,add_values}`)
- 补大量实例 / 结构重组 → `document`(写 `markdown` 让 `km_extract` 抽)
- 已知具体两端 PK 的关系实例 → `operation` · `method=create_link`
**严禁**在 item 里出现"需 schema 迁移 / 需管理员 SQL / 需手工"——这些已被 MCP 写入工具覆盖。
**精修完成后 AI 必做(见 §六)**:
1. 把精修后的 `review-manifest.json` 路径告诉用户
2. **从 `--mcp-url` 或 `~/.workbuddy/mcp.json` 推导 `<mcp-host>/import-review.html`**,**绝不**硬编码 `127.0.0.1`
3. 提示用户去该页面点「导入 JSON」载入清单逐项处理(Apply 权限由用户自己的 Key 决定)
---
## 五、输出物清单
| 文件 | 生产者 | 用途 |
|---|---|---|
| `review-manifest.json` | scan.py + Agent | 核对主产物(findings + items) |
| `完善意见.md` | Agent | 给技术负责人的系统性偏差总结 |
| 执行清单 JSON | items[](工作台导出) | 管理员 Apply 输入 |
## 已知边界
- 扫描是**术语级**比对,无法理解语义;深度差距(属性过期、关系缺失)依赖 Agent 精修与人工 review。
- 候选术语抽取是启发式正则,可能漏抽罕见词形;可在 `scan.py` 的 `PRODUCT_RE` / `CHINESE_PRODUCT_RE` / `BUSINESS_DOMAIN_RE` 增补。
- 本体实例量级大时(千级),`--docs` 建议聚焦核心资料,避免噪音。
## 七、同事上手(共创尚数网本体)
> 本技能是**通用工具**:任何人 + 任何本体 MCP 部署(dev/staging/prod)都能跑,不是 127.0.0.1 专属。
### 0. 安装(两种方式)
**方式 A:从 WorkBuddy BuiltinMarket 安装(推荐)**
```text
对 WorkBuddy 说:「安装 ssw-ontology-reviewer 技能」
```
**方式 B:手动 clone(已 git push 之后)**
```bash
mkdir -p ~/.workbuddy/skills
cd ~/.workbuddy/skills
git clone <ssw-ontology-reviewer 仓库> ssw-ontology-reviewer
```
### 1. 配置 MCP(一次性)
把要扫描的本体服务加到 `~/.workbuddy/mcp.json`(没有就建):
```json
{
"mcpServers": {
"shangshu-ontology": {
"url": "http://<你的本体host>:<port>/api/v1/mcp",
"headers": { "X-API-Key": "<你的 API Key>" }
}
}
}
```
- URL 支持内网/外网任意地址(如 `http://192.168.1.20:8081/api/v1/mcp` 或 `https://ontology.shangshuwang.cn/api/v1/mcp`),**不写死任何 host**。
- API Key 向管理员要(dev 默认 `ingest-key-001`)。
- 可以同时配多个 server(如 `shangshu-ontology-dev` / `shangshu-ontology-prod`),跑扫描时 `--server-name` 切。
### 2. 跑扫描(三种姿势)
```bash
# 方式 1:从 MCP 配置读(最简洁)
python3 ~/.workbuddy/skills/ssw-ontology-reviewer/scripts/scan.py \
--mcp-config ~/.workbuddy/mcp.json \
--server-name shangshu-ontology \
--docs ~/Downloads/资料目录 \
--output ~/Downloads/review-manifest.json
# 方式 2:直接传 URL(CI / 临时服务器)
python3 ~/.workbuddy/skills/ssw-ontology-reviewer/scripts/scan.py \
--mcp-url http://<本体host>:<port>/api/v1/mcp \
--mcp-key <key> \
--docs ~/Downloads/资料目录 \
--output ~/Downloads/review-manifest.json
# 方式 3:先看抽取准不准
python3 ~/.workbuddy/skills/ssw-ontology-reviewer/scripts/scan.py \
--mcp-config ~/.workbuddy/mcp.json --server-name shangshu-ontology \
--docs ~/Downloads/资料目录 --extract-only
```
输出 manifest 的 `meta.reviewer_url` 会**自动**给出该部署下的核对页 URL(如 `https://ontology.shangshuwang.cn/import-review.html`),不需自己拼。
### 3. Agent 精修 → 上传 → Apply
把 `review-manifest.json` 交给本技能 Agent 精修(参考 `templates/analysis-prompt.md`),得到两类型 `items[]` 的最终清单。然后:
- **本机浏览** `meta.reviewer_url`(如 `https://ontology.shangshuwang.cn/import-review.html`)→「导入 JSON」→ 选最终清单 → 勾选 → Apply。
### 4. 谁来用
| 角色 | 典型场景 |
|---|---|
| 产品经理 | 把白皮书/需求文档丢进 `--docs`,看本体漏了什么元原语 |
| 架构师 | 把架构 v1.x 资料丢进去,看是否所有平台/组件都被建模 |
| AI 工程师 | 评估某领域术语覆盖率,业务类文章→ 元原语+实例两件套 |
| 运营 | 政策/招标/供需撮合类文档→ 自动建立 DataDemand/DataProvider 等业务元原语 |
| 跨团队协作 | 把 manifest 当"差别账本"互相对齐:你们队的本体和我们队的差在哪 |
---
## 六、引导用户到核对页面(URL 拼接)
**核心约定**:本技能绝不假设 MCP 是 `127.0.0.1:8081`。`<mcp-host>` 必须从实际配置中推导。
### 拼接规则
| 来源 | 推导 |
|---|---|
| `--mcp-url http://10.0.0.5:18081/api/v1/mcp` | host = `http://10.0.0.5:18081`,核对页 = `http://10.0.0.5:18081/import-review.html` |
| `~/.workbuddy/mcp.json` 里 `mcpServers.shangshu-ontology.url` | 同上,去掉尾部 `/api/v1/mcp` 后拼接 `/import-review.html` |
| `meta.mcp_host` 字段(scan.py 写入) | 用作 fallback |
### AI 工作流(精修完成后必做)
1. **不要**给用户 `http://127.0.0.1:8081/import-review.html` 这种硬编码。
2. **必须**从 scan 时的 `--mcp-url` 或 `~/.workbuddy/mcp.json` 取实际 host,**只截掉 `/api/v1/mcp` 后缀**,再拼接 `/import-review.html`。
3. 提示用户:
> "已生成 review-manifest.json(X 项 findings,Y 项 items)。
> 请打开核对页面处理:**<推导出的 URL>**
> 在该页面:
> - 顶部填 MCP URL + Key(任意主体的 API Key;填你自己的 Key 才能 Apply)
> - 点「导入 JSON」选 `review-manifest.json` 载入
> - 逐项核对 / 改状态 / Apply(写权限才生效);无写权限则导出 JSON/MD 交管理员"
### 用户身份分流(页面侧自动处理)
| 用户身份 | 在核对页能做什么 |
|---|---|
| **可写(manager/ingest)** | Apply 按钮可用;操作项直调 MCP 写入工具;文档项走 `km_upload_markdown`+`km_extract` |
| **只读(connector/analyst 等)** | Apply 自动禁用;可勾选、改状态、导出 JSON/MD 交管理员统一执行 |
### 远程被企业代理拦截时的备选
如果用户报告"打开核对页 MCP 连接 502",提示其:
```bash
# 从本 skill 取代理文件 + 启动本地反向代理
cp ~/.workbuddy/skills/ssw-ontology-reviewer/references/mcp-review-proxy.js ./
PROXY_TARGET=<mcp-host> node mcp-review-proxy.js
# 浏览器改用 http://127.0.0.1:9333/import-review.html
```
代理同源转发整站(SPA + `/api/v1/mcp` + `/builtin-review-manifest.json`),绕开企业代理 502 与 CORS/SSE 问题。
- 本地 dev 模式(未设 API Key)下所有 key 回退为 `manager`,故本地看不到"只读导出"分支;该分支在配置了真实只读主体(如生产 analyst-key-001)时生效。