苏苏原则:本体对外分发不应假设用户能访问 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 文件用完即删。
229 lines
16 KiB
Go
229 lines
16 KiB
Go
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
|
||
}
|