Files
ssw-ontology/server/mcp_guide.go
T
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

229 lines
16 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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
}