Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7d4a0c26e3 | ||
|
|
4349c3c608 | ||
|
|
723445d355 | ||
|
|
5b67ed991a |
No files matched your search
@@ -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
@@ -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
|
||||
```
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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 另行验证。
|
||||
}
|
||||
@@ -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 {
|
||||
|
||||
@@ -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
@@ -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"`
|
||||
}
|
||||
@@ -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.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -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))
|
||||
}
|
||||
}
|
||||
@@ -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)时生效。
|
||||
Reference in new issue
Block a user