Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
27d0e28703 | ||
|
|
25bbd15fd6 | ||
|
|
1e0807ea7a | ||
|
|
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
|
||||
```
|
||||
@@ -0,0 +1,270 @@
|
||||
# 多本体 / 多租户设计
|
||||
|
||||
> 目标:一套部署跑若干个彼此隔离的本体,每个租户一套完整 schema。
|
||||
> 生成时间:2026-10-17。上游讨论:2026-09-08 会话提出的「动态切 schema 的第二个用法:多本体」。
|
||||
> 状态:**仅规划,不执行**(2026-10-17 用户确认)。本文档只作为设计存档,不进入实施计划、不排期、不写代码。
|
||||
> 重启条件:用户明确说「开始做多租户」时,先复核 §8 风险表(尤其 `X-Principal` 越权洞)是否仍成立,再进 writing-plans。
|
||||
|
||||
## TL;DR
|
||||
|
||||
选**多本体(每租户一整套 schema)**,不是行级 `tenant_id`,也不只是分级/域。
|
||||
|
||||
- 隔离层:PostgreSQL schema,请求级 `SET LOCAL search_path` 切换,复用现有 `snapshot_router.go` 的 `dbRunner`/`txPool` 机制
|
||||
- 控制面:租户注册表 + 管理页留在**默认租户 `public`**;租户 schema 只装业务本体
|
||||
- 路由:主体与租户 **1:1**,请求不带 `ontology_id` 时隐式落到主体的「家租户」
|
||||
- 结构同步:`migrate()` 拆成带版本号的迁移段,启动时按 `schema_version` 给落后的租户自动补跑
|
||||
- 备份:每租户各备各的,快照层与租户层在同一条 `search_path` 上叠加
|
||||
- 前端:只做「租户生死」管理页,不做切换器,不做跨租户检索
|
||||
|
||||
**历史数据零迁移**:现有 3000+ 实例原地留在 `public`,`public` 就是默认租户。
|
||||
|
||||
## 1. 数据模型
|
||||
|
||||
### 1.1 ontologies(控制面表,只存在于默认租户)
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS ontologies (
|
||||
id TEXT PRIMARY KEY, -- 'alpha',同时是 schema 名后缀
|
||||
schema_name TEXT NOT NULL, -- 'ontology_alpha';默认租户为 'public'
|
||||
display_name TEXT NOT NULL,
|
||||
home_principal TEXT NOT NULL, -- 家主体(1:1),指向 principals.name
|
||||
schema_version INT NOT NULL DEFAULT 0, -- 该租户已应用到的迁移版本
|
||||
status TEXT NOT NULL DEFAULT 'active', -- active | dropped
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
created_by TEXT NOT NULL DEFAULT '',
|
||||
dropped_at TIMESTAMPTZ
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_ontologies_home ON ontologies(home_principal);
|
||||
CREATE INDEX IF NOT EXISTS idx_ontologies_status ON ontologies(status);
|
||||
```
|
||||
|
||||
约束:
|
||||
|
||||
- `id` 只允许 `[a-z0-9_-]{1,32}`,全小写——它会拼进 schema 名,必须挡住注入
|
||||
- `schema_name` 由 `id` 派生(`public` 除外),不单独自由输入
|
||||
- **`public` 自己建成一条记录**(`id='public'`、`schema_name='public'`、`home_principal='manager'`),保证「家租户指向 public」和「家租户指向 alpha」走同一套逻辑,不留双分支
|
||||
- 默认租户记录**不允许删除或改家主体**
|
||||
|
||||
### 1.2 principals 加一列
|
||||
|
||||
```sql
|
||||
ALTER TABLE principals ADD COLUMN IF NOT EXISTS home_ontology TEXT NOT NULL DEFAULT 'public';
|
||||
```
|
||||
|
||||
1:1 之后不再需要 ACL 名单表——「谁能进这个租户」就是这一列。上次讨论里的 `principals_allowed JSONB` 方案作废。
|
||||
|
||||
### 1.3 每个租户 schema 内的 schema_meta
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS schema_meta (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL
|
||||
);
|
||||
-- key='schema_version'
|
||||
```
|
||||
|
||||
与 `public` 里那张 append-only 的 `schema_versions`(审计流水,与 `ontology_audit_log` 同点挂钩)**不是一回事**,后者不动。前者是「这个租户的结构到第几段了」,后者是「变更历史」,跨租户共享一份全局流水。
|
||||
|
||||
## 2. 请求路由
|
||||
|
||||
### 2.1 入口
|
||||
|
||||
```
|
||||
HTTP: X-Ontology-Id: alpha (REST / 管理页 / MCP 透传)
|
||||
MCP: arguments.ontology_id: "alpha" (可选;不传 = 主体家租户)
|
||||
```
|
||||
|
||||
两条都支持,MCP 参数在 `callConn`/`mcpCall` 里翻译成内层请求的 `X-Ontology-Id` 头——和现有 `X-Snapshot-Id` 透传是同一处、同一写法。
|
||||
|
||||
### 2.2 ontologyMiddleware
|
||||
|
||||
挂在 `/api/v1` 组最前,与 `snapshotMiddleware` 并列:
|
||||
|
||||
```go
|
||||
api.Use(a.snapshotMiddleware(), a.ontologyMiddleware())
|
||||
```
|
||||
|
||||
五步:
|
||||
|
||||
1. **定租户**:无 `X-Ontology-Id` 头 → 取主体的 `home_ontology`(默认 `public`);有头 → 用头里的值
|
||||
2. **定主体**:调 `a.principalFromRequest(c)`(既有单一入口,复用不违背设计)
|
||||
3. **校验**:查 `ontologies`(**用真池查,不能被切 schema 影响**)
|
||||
- 无记录 / `status='dropped'` → 404
|
||||
- `home_principal != 调用主体` 且调用主体不是 `manager` → 403
|
||||
- `manager` 可进任意 active 租户(运维/评审需要)
|
||||
4. **切**:`BeginTx` → `SET LOCAL search_path TO <tenant>, public` → tx 挂进请求 context(见 §3)
|
||||
5. **收尾**:`defer` 里 `c.IsAborted()` → rollback,否则 commit
|
||||
|
||||
### 2.3 中间件顺序的坑
|
||||
|
||||
`principalFromRequest` 现在由 `loginRequired`/`managerAuth` 调用,而 `ontologyMiddleware` 必须挂在它们**之前**(否则 managerAuth 查库就已经切到错租户了)。解法:`ontologyMiddleware` 自己调一次 `principalFromRequest`。
|
||||
|
||||
这之所以安全:它内部用 `a.pool` 解析 api_key,而此时请求 context 里**还没有 tx**(第 4 步才挂),`ctxPool` 会落到真池 → 查的是 `public.principals` → 正确。
|
||||
|
||||
### 2.4 MCP 侧
|
||||
|
||||
`callConn`(`handlers_mcp.go:1265`)已透传 `X-API-Key` 和 session cookie,加两行:
|
||||
|
||||
```go
|
||||
if v := c.GetHeader("X-Ontology-Id"); v != "" {
|
||||
req.Header.Set("X-Ontology-Id", v)
|
||||
}
|
||||
```
|
||||
|
||||
工具参数表给所有工具加可选 `ontology_id`;不传即主体家租户——**现有 MCP 客户端一行配置都不用改**。
|
||||
|
||||
新增 4 个管理工具(manager 限定):`list_ontologies` / `create_ontology` / `set_home_ontology` / `delete_ontology`。
|
||||
|
||||
## 3. 并发安全(前置项,必须先做)
|
||||
|
||||
### 3.1 现状缺陷
|
||||
|
||||
`snapshot_router.go` 的 `snapshotMiddleware` 这样切库:
|
||||
|
||||
```go
|
||||
origDB := a.pool
|
||||
a.pool = &txPool{tx: tx} // 改 app 结构体上的共享字段,全程无锁
|
||||
defer func() { a.pool = origDB }()
|
||||
```
|
||||
|
||||
两个并发请求:A 换成 `txPoolA`,B 又换成 `txPoolB`,A 的 handler 随后读 `a.pool` 拿到的是 **B 的事务**——跨请求串味。快照模式因为用得少、且全只读,撞上了不易发现;**多租户是每个请求都走这条路,必然踩**。
|
||||
|
||||
### 3.2 修法:ctxPool(零 handler 改动)
|
||||
|
||||
启动时**一次性**把 `a.pool` 设成永久的 `ctxPool`,此后永不改动:
|
||||
|
||||
```go
|
||||
type ctxPool struct{ base *pgxpool.Pool }
|
||||
|
||||
func (p *ctxPool) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) {
|
||||
if tx, ok := ctx.Value(txKey{}).(pgx.Tx); ok { return tx.Query(ctx, sql, args...) }
|
||||
return p.base.Query(ctx, sql, args...)
|
||||
}
|
||||
// QueryRow / Exec / Begin / BeginTx / Close 同构
|
||||
```
|
||||
|
||||
中间件把 tx 塞进请求 context:
|
||||
|
||||
```go
|
||||
c.Request = c.Request.WithContext(context.WithValue(c.Request.Context(), txKey{}, tx))
|
||||
```
|
||||
|
||||
业务代码仍写 `a.pool.Query(c, sql, ...)`——`c` 是 `gin.Context`,实现 `context.Context`,其 `Value()` 会代理到请求 context → 自动命中事务。**几百个 handler 一个都不用改**,且天然并发安全。
|
||||
|
||||
`dbRunner` 接口保留(`txPool` 降级为内部类型或直接删除,由 §3.3 决定)。
|
||||
|
||||
### 3.3 snapshotMiddleware 一并改造
|
||||
|
||||
改造后快照中间件不再替换 `a.pool`,同样走 context 挂载。两个中间件叠加时:
|
||||
|
||||
```go
|
||||
SET LOCAL search_path TO backups_<id>, <tenant>, public
|
||||
```
|
||||
|
||||
一条语句搞定,顺序即优先级。
|
||||
|
||||
## 4. 迁移分段
|
||||
|
||||
### 4.1 现状
|
||||
|
||||
`migrate(ctx, p dbExec)`(`db.go:37`)是一整段 DDL 字符串 + 若干后置修复(`backfillMissingIRI`、seed),硬编码跑在 `public` 上。
|
||||
|
||||
### 4.2 目标
|
||||
|
||||
```go
|
||||
type migration struct {
|
||||
Version int
|
||||
Name string
|
||||
SQL string // 或 func(ctx context.Context, p dbExec) error
|
||||
}
|
||||
|
||||
var migrations = []migration{
|
||||
{Version: 1, Name: "schema_meta", SQL: `CREATE TABLE IF NOT EXISTS schema_meta(...)`},
|
||||
{Version: 2, Name: "core_objects", SQL: `...object_types/properties/objects/links...`},
|
||||
// …按现有 DDL 的自然边界切分,每段内部保持幂等
|
||||
}
|
||||
|
||||
func (a *app) migrateSchema(ctx context.Context, db dbExec, upTo int) error
|
||||
```
|
||||
|
||||
`migrate(ctx, p)` 保留为「跑全部段到 public」的薄封装,调用点不变。
|
||||
|
||||
### 4.3 只对默认租户执行的部分
|
||||
|
||||
`backfillMissingIRI` 和 `seedIfEmpty` 是**存量修复/演示种子**,不能对每个新租户跑:
|
||||
|
||||
- `backfillMissingIRI` → 迁移段的一种,只对已有数据的 schema 有意义
|
||||
- `seedIfEmpty`(「合作企业」示例)→ 迁到 `initDB` 里对 `public` 单独调用
|
||||
|
||||
### 4.4 启动时自动补跑
|
||||
|
||||
```go
|
||||
func (a *app) syncTenantSchemas(ctx context.Context) error {
|
||||
// 1. 从 public.ontologies 列出所有 active 租户
|
||||
// 2. 对每个租户读 schema_meta 的 schema_version
|
||||
// 3. version < len(migrations) 的,补跑缺失段(逐租户独立事务)
|
||||
// 4. 单个租户失败 → 记日志 + 该租户标记 degraded,继续处理其他
|
||||
}
|
||||
```
|
||||
|
||||
在 `initDB` 之后、`seedIfEmpty` 之后调用。失败**不阻断启动**——一个坏租户不该拖垮整台服务。
|
||||
|
||||
### 4.5 建租户
|
||||
|
||||
```
|
||||
create_ontology(id, display_name, home_principal)
|
||||
1. 校验 id 词法 + 未重名
|
||||
2. CREATE SCHEMA ontology_<id>
|
||||
3. 开事务 SET LOCAL search_path TO ontology_<id>, public → migrateSchema(upTo=len)
|
||||
4. 事务提交后写 ontologies 记录
|
||||
```
|
||||
|
||||
任一步失败 → `DROP SCHEMA` 回滚,不留半成品。
|
||||
|
||||
## 5. 备份 / 快照
|
||||
|
||||
### 5.1 语义
|
||||
|
||||
`backup_create` 作用于**当前租户**:只把该租户 schema 的全部表复制到 `backups_<id>`。默认租户(public)行为不变。
|
||||
|
||||
### 5.2 硬约束(会静默出错,必须防)
|
||||
|
||||
快照 schema 必须**完整包含源租户的全部表**。否则 `search_path TO backups_x, tenant_y, public` 在缺表时会**漏到下一级**,读出「一部分快照 + 一部分活库」的混合数据,且不报错。
|
||||
|
||||
在建快照时断言:源租户表数 == 快照表数,不等则拒绝创建并报错。
|
||||
|
||||
### 5.3 快照元数据
|
||||
|
||||
`backup_inspect` / `backup_list` 增加 `source_ontology` 字段(从 `backups.snapshot_runs` 读)。`switch_via` 提示文案补充 `X-Ontology-Id`。
|
||||
|
||||
### 5.4 reviewkit 工具链
|
||||
|
||||
`server/reviewkit/` 内嵌二进制 + reviewkit.go 要能接受并透传 `ontology_id`,否则对接核对会在默认租户上跑,结论失真。
|
||||
|
||||
## 6. 管理页(前端)
|
||||
|
||||
新增「多租户」tab,**只管生死**:
|
||||
|
||||
- 列表:名称 / 家主体 / 实例数 / 创建时间 / 结构版本 / 状态
|
||||
- 操作:新建、改家主体、删除
|
||||
- 实例数:管理 handler 里对每个 active 租户 schema 单独 `count`(租户数量级小,可接受;不做跨租户联合查询)
|
||||
|
||||
删除租户:`status='dropped'` 软标记 + 二次确认;`DROP SCHEMA` 单独一步(可保留 dropped 状态的 schema 数据,人工确认后再物理清)。参考现有 `objects.deleted` 的软删除做法。
|
||||
|
||||
## 7. 明确不做
|
||||
|
||||
- 跨租户联合查询 / 全景检索(跨 N 个 schema 联合分页,成本高且易错)
|
||||
- 前端全局租户切换器(管理页之外,前端所有请求不带 `ontology_id`,各管各的)
|
||||
- 行级 `tenant_id`(选了 schema-per-tenant 就没有这条路)
|
||||
- 租户级对象类型模板/市场
|
||||
- 跨租户物化、跨租户 AI 摄取
|
||||
|
||||
## 8. 风险与未决
|
||||
|
||||
| 项 | 说明 | 处置 |
|
||||
|---|---|---|
|
||||
| 迁移分段回归 | 现有 DDL 切段时切错边界,老租户结构不完整 | 切完在默认租户上验证表/列与切段前逐一对齐 |
|
||||
| 串味 | §3.2 的 `ctxPool` 是所有后续工作的前置 | 单独一个 commit,先跑并发集成测试验证 |
|
||||
| 快照表数断言 | §5.2 | 建快照时硬校验,不等即失败 |
|
||||
| **`X-Principal` 头越权(现存洞,多租户会放大)** | `principalFromRequest`(`access_control.go:83`)把 `X-Principal` 头作为最高优先级且**完全无鉴权**地决定主体。任何请求 `X-Principal: manager` 即取得 manager 身份。多租户下再配一个 `X-Ontology-Id`,即可无凭据进入任意租户 | **多租户上线前必须先封**:外部入口一律不接受 `X-Principal` 头,该头只允许来自进程内自调用(`callHandler`/`mcpCall`,`handlers_mcp.go:1219/1246`)。建议同时清理进程内自调用改为在 context 里带主体 |
|
||||
| 租户数量 | 每租户一整套 schema,25 张表 | 暂不设上限;上千租户时应评估「行级」或混合方案 |
|
||||
@@ -18,6 +18,31 @@ AI 客户端在使用本平台过程中发现 bug 或有改进建议,**请提
|
||||
|
||||
## 版本历史
|
||||
|
||||
## [1.5.3] - 2026-10-17 X-Principal 头越权洞修复
|
||||
|
||||
**影响**:修复前,任何能发 HTTP 请求的一方带一个 `X-Principal: manager` 头即可取得平台最高权限——管理接口、知识库写接口、MCP 端点、连接器读路径的身份过滤全部沦陷,且该头排在真实凭据之前,合法低权限 key 配该头即提权。修复后主体只来自真实凭据(api_key / 会话 cookie),裸头一律按匿名处理。
|
||||
|
||||
**改动**:
|
||||
- `principalFromRequest` 不再读取 `X-Principal` 请求头;最高优先级改为进程内注入的 request context,其后仍是会话 cookie → `principals.api_key` → dev 兜底,优先级链其余部分不变
|
||||
- 新增 `withInjectedPrincipal` / `injectedPrincipal`(`server/principal_ctx.go`):MCP 的 `callHandler` / `mcpCall` 两处进程内自调用改在 `*http.Request` 的 context 上带主体。context 由代码构造、网络请求无法携带,故外部伪造不命中
|
||||
- review-kit 代理 `mcp-review-proxy.js` 的 CORS 允许头去掉 `X-Principal`(此前为 `*` origin + 显式放行该头,任意网页 JS 可借该代理伪造身份)
|
||||
- 新增 `server/xprincipal_authz_test.go`:覆盖匿名伪造(managerAuth 401 / ingestOrManagerAuth 403 / mcpAuth 401)、该头不覆盖已解析的真实主体、真实 manager key 仍放行三条链路
|
||||
- 集成测试 60 处 `X-Principal: manager` 测试捷径改为查库取真实 api_key(`principalKey` / `authHeaderFor` helper)
|
||||
|
||||
**设计**:不采用「降优先级」「回环 IP 白名单」「内部签名头」——三者都保留了一条外部可构造的提权路径。多租户(每租户一套 schema)会把该洞放大成跨租户洞,故在多租户立项前先行封堵;多租户本身仍为「仅规划,不执行」。
|
||||
|
||||
## [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 不一致的问题。
|
||||
|
||||
@@ -73,14 +73,19 @@ func (a *Authz) AllowedMarking(marking string) bool {
|
||||
// principalFromRequest 从请求头推断主体。
|
||||
// 鉴权唯一来源是 principals 表的 api_key(首次启动由 seed 注入随机值,之后由 Access Control 页管理);
|
||||
// 不再读取任何 .env 显式密钥。
|
||||
// 优先级:X-Principal > cookie session > principals 表的 api_key(X-API-Key 头或 key 查询参数)。
|
||||
// 优先级:进程内注入的 request context > cookie session > principals 表的 api_key(X-API-Key 头或 key 查询参数)。
|
||||
//
|
||||
// 未携带任何有效 key 时:
|
||||
// - 若 manager 主体尚未配置 api_key(全新库、seed 未运行)→ 开放为 manager,便于首次引导;
|
||||
// - 否则匿名回退 public(L0 只读)。
|
||||
// 生产环境首次启动后 manager 必然已有随机 key,故真实鉴权默认生效。
|
||||
//
|
||||
// 2026-10-17 修复越权洞:原实现把 `X-Principal` 请求头列为最高优先级且完全不校验,
|
||||
// 而该头客户端可任意设置 → 任何请求 `X-Principal: manager` 即取得平台最高权限。
|
||||
// 该头已彻底移除;进程内自调用改走 request context(见 principal_ctx.go)。
|
||||
func (a *app) principalFromRequest(c *gin.Context) string {
|
||||
if p := strings.TrimSpace(c.GetHeader("X-Principal")); p != "" {
|
||||
// 进程内自调用注入的主体(外部不可伪造)。
|
||||
if p := injectedPrincipal(c.Request.Context()); p != "" {
|
||||
return p
|
||||
}
|
||||
// cookie session(账号密码登录后写入)
|
||||
|
||||
@@ -16,8 +16,8 @@ import (
|
||||
// - 前端编辑「对象类型分级」保存按钮看似无反应(POST 到不存在的路由 → 404)
|
||||
// - 后果:587 个打了 data_level 标签的实例是「裸属性」无法被分级引擎接管
|
||||
func TestIntegration_SetObjectTypeClassification(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 用一个已有「真属性行」的类型,避免 setupTestEnv 新建的测试类型 properties 行为不同
|
||||
// DataDemand 在本工作区有 64 个属性行(详见 docs/db/0910 schema)。
|
||||
@@ -129,8 +129,8 @@ func TestIntegration_SetObjectTypeClassification(t *testing.T) {
|
||||
// TestIntegration_SetClassificationThroughMCP 验证 MCP 工具 set_object_type_classification
|
||||
// 是否正确代理到刚补的 REST PUT。需要 manager 主体。
|
||||
func TestIntegration_SetClassificationThroughMCP(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
const fixedType = "DataDemand"
|
||||
t.Cleanup(func() {
|
||||
|
||||
@@ -14,8 +14,8 @@ import (
|
||||
|
||||
// GET /ontology/meta:自描述 IRI 命名空间与依据标准。
|
||||
func TestIntegration_OntologyMeta(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
code, body := env.httpDo(t, "GET", "/api/v1/ontology/meta", nil, h)
|
||||
if code != 200 {
|
||||
t.Fatalf("meta 应 200, got %d", code)
|
||||
@@ -30,8 +30,8 @@ func TestIntegration_OntologyMeta(t *testing.T) {
|
||||
|
||||
// 创建类型后 GET 详情应带 iri = base_iri + "#" + api_name。
|
||||
func TestIntegration_CreateObjectType_HasIRI(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h)
|
||||
@@ -53,7 +53,7 @@ func TestIntegration_CreateObjectType_HasIRI(t *testing.T) {
|
||||
// listObjectTypes 返回裸 JSON 数组(httpDo 解码进 map 会丢),须裸 http 读 body。
|
||||
func TestIntegration_ListAndConnector_HasIRI(t *testing.T) {
|
||||
env, a := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
const propName = "echo_prop"
|
||||
wantOT := "http://example.org/standard-ontology#" + key
|
||||
@@ -76,7 +76,7 @@ func TestIntegration_ListAndConnector_HasIRI(t *testing.T) {
|
||||
if err != nil {
|
||||
t.Fatalf("req: %v", err)
|
||||
}
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, err := env.srv.Client().Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("do: %v", err)
|
||||
@@ -119,7 +119,7 @@ func TestIntegration_ListAndConnector_HasIRI(t *testing.T) {
|
||||
}
|
||||
|
||||
// 3) 连接器视图应带 iri(测试库主体已配置 api_key 时 connectorAuth 要求 X-API-Key)
|
||||
connH := map[string]string{"X-Principal": "manager"}
|
||||
connH := authHeaderFor(t, a, "manager")
|
||||
var apiKey string
|
||||
_ = a.pool.QueryRow(context.Background(),
|
||||
`SELECT api_key FROM principals WHERE name='manager' AND COALESCE(api_key,'')<>''`).Scan(&apiKey)
|
||||
@@ -148,15 +148,15 @@ func TestIntegration_ListAndConnector_HasIRI(t *testing.T) {
|
||||
|
||||
// 导出端点:建类型+链接 → turtle 文本含两类三元组。
|
||||
func TestIntegration_ExportTurtle(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types",
|
||||
map[string]any{"api_name": key, "display_name": "导出体"}, h)
|
||||
t.Cleanup(func() { env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h) })
|
||||
|
||||
req, _ := http.NewRequest("GET", env.srv.URL+"/api/v1/ontology/export?format=turtle", nil)
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
@@ -186,8 +186,8 @@ func TestIntegration_ExportTurtle(t *testing.T) {
|
||||
// 类型编辑(经 schemaAudit)应同步产生版本行,且 before/after 完整可查。
|
||||
// 走只读端点 GET /ontology/versions(列表) + GET /ontology/versions/:version(详情)。
|
||||
func TestIntegration_SchemaVersions(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types",
|
||||
map[string]any{"api_name": key, "display_name": "版本前"}, h)
|
||||
@@ -237,14 +237,14 @@ func TestIntegration_SchemaVersions(t *testing.T) {
|
||||
|
||||
// 建版本端点前先验写入:schemaAudit 挂钩是否落 schema_versions。
|
||||
func TestIntegration_SchemaVersionsWritten(t *testing.T) {
|
||||
env, app := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types",
|
||||
map[string]any{"api_name": key, "display_name": "写入验证"}, h)
|
||||
t.Cleanup(func() { env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h) })
|
||||
var n int
|
||||
err := app.pool.QueryRow(context.Background(),
|
||||
err := a.pool.QueryRow(context.Background(),
|
||||
`SELECT count(*) FROM schema_versions WHERE target_name=$1`, key).Scan(&n)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
@@ -256,8 +256,8 @@ func TestIntegration_SchemaVersionsWritten(t *testing.T) {
|
||||
|
||||
// 非法字符 api_name 在创建类型时被守卫拦截。
|
||||
func TestIntegration_InvalidIRIName_Rejected(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
bad := "含 空格"
|
||||
code, body := env.httpDo(t, "POST", "/api/v1/ontology/object-types",
|
||||
map[string]any{"api_name": bad, "display_name": "x"}, h)
|
||||
@@ -268,8 +268,8 @@ func TestIntegration_InvalidIRIName_Rejected(t *testing.T) {
|
||||
|
||||
// 新 escaper 不再产出 \a/\v(上轮遗留:导出会被 rapper 拒绝)。
|
||||
func TestIntegration_TurtleExportEscapesControlChars(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
if code, _ := env.httpDo(t, "POST", "/api/v1/ontology/object-types",
|
||||
map[string]any{"api_name": key, "display_name": "控制"}, h); code != 201 {
|
||||
@@ -277,7 +277,7 @@ func TestIntegration_TurtleExportEscapesControlChars(t *testing.T) {
|
||||
}
|
||||
t.Cleanup(func() { env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h) })
|
||||
req, _ := http.NewRequest("GET", env.srv.URL+"/api/v1/ontology/export?format=turtle", nil)
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, _ := http.DefaultClient.Do(req)
|
||||
defer resp.Body.Close()
|
||||
data, _ := io.ReadAll(resp.Body)
|
||||
@@ -289,8 +289,8 @@ func TestIntegration_TurtleExportEscapesControlChars(t *testing.T) {
|
||||
// 公理随 Turtle 导出为 OWL 公理(disjointWith / equivalentClass / inverseOf / FunctionalProperty)。
|
||||
// dateOrder 是跨属性时序规则,OWL2 不可表达——不导出,运行期由 validateDateOrder 统一守约。
|
||||
func TestIntegration_ExportIncludesAxioms(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key, other := env.typeKey, env.typeKey+"_o"
|
||||
ltName := env.typeKey + "_lnk"
|
||||
t.Cleanup(func() {
|
||||
@@ -314,7 +314,7 @@ func TestIntegration_ExportIncludesAxioms(t *testing.T) {
|
||||
}}, h)
|
||||
|
||||
req, _ := http.NewRequest("GET", env.srv.URL+"/api/v1/ontology/export?format=turtle", nil)
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
@@ -339,8 +339,8 @@ func TestIntegration_ExportIncludesAxioms(t *testing.T) {
|
||||
|
||||
// 创建/读取公理回显(本任务只覆盖创建路径的写入回显;update 在任务 3 联调)。
|
||||
func TestIntegration_AxiomsRoundTrip(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
// 任务 3 接入 schema 良构校验后,disjointWith/equivalentTo 引用的类型必须存在。
|
||||
// 提前创建 Other / Alias 两个被引用类型。
|
||||
@@ -388,8 +388,8 @@ func TestIntegration_AxiomsRoundTrip(t *testing.T) {
|
||||
|
||||
// 各项良构校验的可达性都靠此测试覆盖(任务 3 前 schema 校验尚未接通,全部应 400/合法)。
|
||||
func TestIntegration_AxiomsWellFormed(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
keyA, keyB := env.typeKey, env.typeKey+"_b"
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+keyA, nil, h)
|
||||
@@ -454,11 +454,11 @@ func TestIntegration_AxiomsWellFormed(t *testing.T) {
|
||||
// functionalLinks 边写入校验:同 source 第二次不同 target → 400;同 target 重设 → 201。
|
||||
func TestIntegration_FunctionalLinkEnforced(t *testing.T) {
|
||||
env, a := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
keyA, keyB, keyC := env.typeKey, env.typeKey+"_b", env.typeKey+"_c"
|
||||
// 连接器接口(批量)在全库任意主体已配 api_key 时强制要求 X-API-Key。
|
||||
// 测试库常处于 manager 已配 key 状态,带上以保通用。
|
||||
connH := map[string]string{"X-Principal": "manager"}
|
||||
connH := authHeaderFor(t, a, "manager")
|
||||
var apiKey string
|
||||
_ = a.pool.QueryRow(context.Background(),
|
||||
`SELECT api_key FROM principals WHERE name='manager' AND COALESCE(api_key,'')<>''`).Scan(&apiKey)
|
||||
@@ -515,8 +515,8 @@ func TestIntegration_FunctionalLinkEnforced(t *testing.T) {
|
||||
|
||||
// parent_id SubclassOf:基本读写、环校验、父子互斥、rdfs:subClassOf 导出。
|
||||
func TestIntegration_ParentSubclassOf(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
root, child := env.typeKey, env.typeKey+"_c"
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+root, nil, h)
|
||||
@@ -570,7 +570,7 @@ func TestIntegration_ParentSubclassOf(t *testing.T) {
|
||||
}
|
||||
// 导出 rdfs:subClassOf
|
||||
req, _ := http.NewRequest("GET", env.srv.URL+"/api/v1/ontology/export?format=turtle", nil)
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, _ := http.DefaultClient.Do(req)
|
||||
defer resp.Body.Close()
|
||||
data, _ := io.ReadAll(resp.Body)
|
||||
@@ -584,8 +584,8 @@ func TestIntegration_ParentSubclassOf(t *testing.T) {
|
||||
// 修复前 bug:C 已 disjointWith:[B],PUT C {"parent":"B"} → 守卫只看空新公理 → 放行,
|
||||
// 落库父子互斥矛盾(导出同对既发 rdfs:subClassOf 又发 owl:disjointWith)。
|
||||
func TestIntegration_SetParentChecksExistingDisjoint(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
child, parent := env.typeKey, env.typeKey+"_b"
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+child, nil, h)
|
||||
@@ -623,8 +623,8 @@ func TestIntegration_SetParentChecksExistingDisjoint(t *testing.T) {
|
||||
|
||||
// dateOrder 在 applyObjectUpsert 路径上生效;validate_axioms=false 豁免。
|
||||
func TestIntegration_DateOrderWriteCheck(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
t.Cleanup(func() { env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h) })
|
||||
// 先建类型,后加属性,最后挂公理(公理形状校验要求属性先存在)。
|
||||
@@ -672,8 +672,8 @@ func TestIntegration_DateOrderWriteCheck(t *testing.T) {
|
||||
// parent_id 三态契约回归:PUT 不带 parent 字段不应清空既有 parent。
|
||||
// 修复前 bug:updateObjectType 无条件写 parent_id=$17 (nil → NULL),每次更新即清空。
|
||||
func TestIntegration_ParentTriState_PreserveOnMissing(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
root, child := env.typeKey, env.typeKey+"_c"
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+child, nil, h)
|
||||
@@ -719,8 +719,8 @@ func TestIntegration_ParentTriState_PreserveOnMissing(t *testing.T) {
|
||||
// COALESCE($16::jsonb, axioms) 永不落回 → 任何 PUT(如仅改名)静默洗掉公理。
|
||||
// 规约:不带/null → 保持;显式 {} → 清空。与 parent 三态同款问题。
|
||||
func TestIntegration_AxiomsTriState_PreserveOnMissing(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key, other := env.typeKey, env.typeKey+"_o"
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h)
|
||||
@@ -776,8 +776,8 @@ func TestIntegration_AxiomsTriState_PreserveOnMissing(t *testing.T) {
|
||||
|
||||
// 父声明属性 + 枚举;子继承(读路径合并)+ enum 校验闭包生效。
|
||||
func TestIntegration_PropertyInheritance(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
root, child := env.typeKey, env.typeKey+"_c"
|
||||
t.Cleanup(func() {
|
||||
env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+child, nil, h)
|
||||
@@ -864,7 +864,7 @@ func TestIntegration_PropertyInheritance(t *testing.T) {
|
||||
// 步骤顺序利用 60s TTL 窗口,无需 sleep 即确定性覆盖"建子类型后闭包未即时生效"回归。
|
||||
func TestIntegration_ParentEnumFreshCacheAfterCreate(t *testing.T) {
|
||||
env, a := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
root, child := env.typeKey, env.typeKey+"_fc"
|
||||
t.Cleanup(func() {
|
||||
_, _ = a.pool.Exec(context.Background(), `DELETE FROM objects WHERE type_api_name=$1`, child)
|
||||
@@ -899,8 +899,8 @@ func TestIntegration_ParentEnumFreshCacheAfterCreate(t *testing.T) {
|
||||
|
||||
// 多语标签:入参校验、读写回显、Turtle @tag 输出。
|
||||
func TestIntegration_DisplayNameLang(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
t.Cleanup(func() { env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h) })
|
||||
// 非法 lang → 400
|
||||
@@ -920,7 +920,7 @@ func TestIntegration_DisplayNameLang(t *testing.T) {
|
||||
}
|
||||
// Turtle 含 @tag
|
||||
req, _ := http.NewRequest("GET", env.srv.URL+"/api/v1/ontology/export?format=turtle", nil)
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, _ := http.DefaultClient.Do(req)
|
||||
defer resp.Body.Close()
|
||||
data, _ := io.ReadAll(resp.Body)
|
||||
@@ -932,8 +932,8 @@ func TestIntegration_DisplayNameLang(t *testing.T) {
|
||||
// uri data_type:写入校验 + xsd:anyURI 导出。
|
||||
// 注:创建实例统一走 POST /api/v1/objects(type 在 body),无 /objects/{type} 创建路由。
|
||||
func TestIntegration_URIDataType(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
key := env.typeKey
|
||||
t.Cleanup(func() { env.httpDo(t, "DELETE", "/api/v1/ontology/object-types/"+key, nil, h) })
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types",
|
||||
@@ -952,7 +952,7 @@ func TestIntegration_URIDataType(t *testing.T) {
|
||||
}
|
||||
// 导出 xsd:anyURI
|
||||
req, _ := http.NewRequest("GET", env.srv.URL+"/api/v1/ontology/export?format=turtle", nil)
|
||||
req.Header.Set("X-Principal", "manager")
|
||||
req.Header.Set("X-API-Key", principalKey(t, a, "manager"))
|
||||
resp, _ := http.DefaultClient.Do(req)
|
||||
defer resp.Body.Close()
|
||||
data, _ := io.ReadAll(resp.Body)
|
||||
|
||||
+135
-5
@@ -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
|
||||
|
||||
@@ -1082,11 +1212,11 @@ func (a *app) mcpDispatchTool(c *gin.Context, name string, args map[string]inter
|
||||
}
|
||||
|
||||
// callHandler 进程内直接调用本体管理 handler,绕过 HTTP 中间件(managerAuth 仅放行 manager),
|
||||
// 由调用方 mcpDispatchTool 的 canWrite 统一放行 manager/ingest。X-Principal 透传以走正常鉴权链路。
|
||||
// 由调用方 mcpDispatchTool 的 canWrite 统一放行 manager/ingest。主体经 request context 透传以走正常鉴权链路。
|
||||
func (a *app) callHandler(h gin.HandlerFunc, params gin.Params, body []byte, principal string) (string, int) {
|
||||
req := httptest.NewRequest(http.MethodPost, "/x", bytes.NewReader(body))
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
req.Header.Set("X-Principal", principal)
|
||||
req = withInjectedPrincipal(req, principal)
|
||||
w := httptest.NewRecorder()
|
||||
c, _ := gin.CreateTestContext(w)
|
||||
c.Request = req
|
||||
@@ -1104,7 +1234,7 @@ func optStr(m map[string]interface{}, k string) string {
|
||||
return ""
|
||||
}
|
||||
|
||||
// mcpCall 进程内把请求路由到 KM/管理 handler,并携带当前 MCP 主体身份(X-Principal),
|
||||
// mcpCall 进程内把请求路由到 KM/管理 handler,并携带当前 MCP 主体身份(request context),
|
||||
// 使 ingestOrManagerAuth 中间件能正确放行(manager/ingest),复用现有逻辑、零漂移。
|
||||
func (a *app) mcpCall(method, path string, body []byte, principal string) (string, int) {
|
||||
var reader io.Reader
|
||||
@@ -1113,7 +1243,7 @@ func (a *app) mcpCall(method, path string, body []byte, principal string) (strin
|
||||
}
|
||||
req := httptest.NewRequest(method, path, reader)
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
req.Header.Set("X-Principal", principal)
|
||||
req = withInjectedPrincipal(req, principal)
|
||||
w := httptest.NewRecorder()
|
||||
a.engine.ServeHTTP(w, req)
|
||||
return w.Body.String(), w.Code
|
||||
|
||||
@@ -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 另行验证。
|
||||
}
|
||||
+19
-19
@@ -139,9 +139,9 @@ func (e *testEnv) httpDo(t *testing.T, method, path string, body any, headers ma
|
||||
// ---------- 1. 枚举写入校验(issue #5-①,含修复后的变量遮蔽 bug)----------
|
||||
|
||||
func TestIntegration_EnumValidation(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
key := env.typeKey
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 建类型 + 枚举属性
|
||||
if code, body := env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
@@ -191,11 +191,11 @@ func TestIntegration_EnumValidation(t *testing.T) {
|
||||
// ---------- 2. 分级过滤(issue #5-③④)----------
|
||||
|
||||
func TestIntegration_ClassificationFilter(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
key := env.typeKey
|
||||
|
||||
// 建类型(带分级)+ 枚举属性 + 插入 analyst clearance(L0,L1)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
if code, _ := env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
"api_name": key, "display_name": "回归-分级过滤",
|
||||
"classification_property": "level",
|
||||
@@ -209,7 +209,7 @@ func TestIntegration_ClassificationFilter(t *testing.T) {
|
||||
"enum_values": []string{"L0", "L1", "L2", "L3"},
|
||||
}, h)
|
||||
|
||||
// 注入 analyst clearance:L0+L1(principal 名与 GET 时 X-Principal 一致)
|
||||
// 注入 analyst clearance:L0+L1(principal 名与 GET 时带的 analyst api_key 对应主体一致)
|
||||
pool, _ := initDB(context.Background(), testDSN())
|
||||
defer pool.Close()
|
||||
_, _ = pool.Exec(context.Background(),
|
||||
@@ -236,7 +236,7 @@ func TestIntegration_ClassificationFilter(t *testing.T) {
|
||||
|
||||
// analyst(L0,L1) → 只见到 L0/L1
|
||||
_, body = env.httpDo(t, "GET", "/api/v1/connector/objects/"+key+"?limit=50", nil,
|
||||
map[string]string{"X-Principal": "analyst"})
|
||||
authHeaderFor(t, a, "analyst"))
|
||||
total := int(body["total"].(float64))
|
||||
if total != 2 {
|
||||
t.Errorf("analyst 应见 2 个, got %d, items=%v", total, body["items"])
|
||||
@@ -251,7 +251,7 @@ func TestIntegration_ClassificationFilter(t *testing.T) {
|
||||
|
||||
// analyst 直取 L2 实例 → 404(fail-closed:不泄漏存在性)
|
||||
code, _ := env.httpDo(t, "GET", "/api/v1/connector/object/"+key+"/a_l2", nil,
|
||||
map[string]string{"X-Principal": "analyst"})
|
||||
authHeaderFor(t, a, "analyst"))
|
||||
if code != 404 {
|
||||
t.Errorf("analyst 直取 L2 应 404, got %d", code)
|
||||
}
|
||||
@@ -260,9 +260,9 @@ func TestIntegration_ClassificationFilter(t *testing.T) {
|
||||
// ---------- 3. 字段级分级脱敏(issue #5-②)----------
|
||||
|
||||
func TestIntegration_FieldSensitivity(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
key := env.typeKey
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
"api_name": key, "display_name": "回归-字段脱敏",
|
||||
@@ -305,7 +305,7 @@ func TestIntegration_FieldSensitivity(t *testing.T) {
|
||||
|
||||
// analyst(L0,L1) → secret_id 应被 redact 为 ***
|
||||
_, body = env.httpDo(t, "GET", "/api/v1/connector/object/"+key+"/u1", nil,
|
||||
map[string]string{"X-Principal": "analyst"})
|
||||
authHeaderFor(t, a, "analyst"))
|
||||
props = body["properties"].(map[string]any)
|
||||
if props["secret_id"] != "***" {
|
||||
t.Errorf("analyst 应见 secret_id='***', got %v", props["secret_id"])
|
||||
@@ -318,9 +318,9 @@ func TestIntegration_FieldSensitivity(t *testing.T) {
|
||||
// ---------- 4. 删除 → 恢复关系边(issue #4)----------
|
||||
|
||||
func TestIntegration_RestoreEdges(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
key := env.typeKey
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
pool, _ := initDB(context.Background(), testDSN())
|
||||
defer pool.Close()
|
||||
|
||||
@@ -385,9 +385,9 @@ func TestIntegration_RestoreEdges(t *testing.T) {
|
||||
// ---------- 5. recompute 落库(issue #5-⑩)----------
|
||||
|
||||
func TestIntegration_RecomputeApply(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
key := env.typeKey
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
"api_name": key, "display_name": "回归-recompute",
|
||||
@@ -445,8 +445,8 @@ func TestIntegration_RecomputeApply(t *testing.T) {
|
||||
// ---------- 6. 数据备份 (v1.3.0) 端到端:create → list → inspect → diff → download → delete ----------
|
||||
|
||||
func TestIntegration_BackupLifecycle(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 当前 public 的 objects 表应有内容(>0 行),diff 才有意义
|
||||
pool, _ := initDB(context.Background(), testDSN())
|
||||
@@ -562,7 +562,7 @@ func TestIntegration_BackupLifecycle(t *testing.T) {
|
||||
|
||||
// 7) connector 主体应被拒(managerAuth 中间件 → 401)
|
||||
code, body = env.httpDo(t, "GET", "/api/v1/backups", nil,
|
||||
map[string]string{"X-Principal": "connector"})
|
||||
authHeaderFor(t, a, "connector"))
|
||||
if code != 401 {
|
||||
t.Errorf("非 manager 应被拒 401, got %d, body=%v", code, body)
|
||||
}
|
||||
@@ -581,8 +581,8 @@ func TestIntegration_BackupLifecycle(t *testing.T) {
|
||||
// TestIntegration_BackupDiffAfterMutation 验证「改动前/后各打一份 → diff 可见」
|
||||
// 这正是「敢操作」的工作流核心。
|
||||
func TestIntegration_BackupDiffAfterMutation(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 创建测试类型 + 一个实例
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
|
||||
@@ -11,8 +11,8 @@ import (
|
||||
// 之前 PUT /object-types/:name 静默忽略 properties 字段,导致「已有类型补注册属性」无入口。
|
||||
// 验证:properties 数组非空时被 upsert(同名属性更新元数据,新名属性新增)。
|
||||
func TestIntegration_UpdateObjectType_MergesProperties(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 用 setupTestEnv 已建的类型(test_UpdateMergeProp),保证隔离
|
||||
key := "test_UpdateMergeProp"
|
||||
@@ -96,8 +96,8 @@ func TestIntegration_UpdateObjectType_MergesProperties(t *testing.T) {
|
||||
// MCP 工具集暴露 add_object_type_property(包装 POST /properties)。
|
||||
// 验证 MCP 调用真的注册了属性,而不是空跑。
|
||||
func TestIntegration_AddObjectTypeProperty_MCP(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
key := "test_AddPropertyMCP"
|
||||
t.Cleanup(func() {
|
||||
@@ -174,8 +174,8 @@ func TestIntegration_AddObjectTypeProperty_MCP(t *testing.T) {
|
||||
// TestIntegration_UpdateObjectType_MCP 验证 issue #6 方案 A 的另一半:
|
||||
// MCP update_object_type 工具可一并 upsert properties。
|
||||
func TestIntegration_UpdateObjectType_MCP(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
key := "test_UpdateOTMCP"
|
||||
t.Cleanup(func() {
|
||||
|
||||
@@ -13,8 +13,8 @@ import (
|
||||
// 验证:clearances 数组在 PUT 时一并落库(DELETE + INSERT 全量替换),
|
||||
// GET /principals/:name 和 listPrincipals 都能回显。
|
||||
func TestIntegration_UpdatePrincipal_Clearances(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 用一个非内置主体(避免污染 manager seed)
|
||||
key := "test_principal_clearance"
|
||||
@@ -102,8 +102,8 @@ func TestIntegration_UpdatePrincipal_Clearances(t *testing.T) {
|
||||
// TestIntegration_SetPrincipalClearance_MCP 修复 issue #7 方案 A:
|
||||
// MCP set_principal_clearance 工具能写入;list_principals / get_principal 能读取。
|
||||
func TestIntegration_SetPrincipalClearance_MCP(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
key := "test_mcp_clearance"
|
||||
t.Cleanup(func() {
|
||||
@@ -197,8 +197,8 @@ func TestIntegration_SetPrincipalClearance_MCP(t *testing.T) {
|
||||
// `PUT /principals/:name/clearances` 端点仍然有效(用户不知道有这个端点)。
|
||||
// 这是 issue #7 的关键发现:端点一直都在,只是用户认知里没有。
|
||||
func TestIntegration_PutClearances_Rest(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
key := "test_legacy_clearance_path"
|
||||
t.Cleanup(func() {
|
||||
|
||||
@@ -135,14 +135,14 @@ func seedConnectorForTest(t *testing.T) string {
|
||||
// get_object_types / get_facets)一律以 connector 主体执行——manager 走
|
||||
// MCP 也只能看到 connector clearance(L0-L2)下的数据,违反 v1.2.0 「manager 不受影响」。
|
||||
//
|
||||
// 新行为:callConn 接受 principal 参数,内层请求同时注入
|
||||
// X-API-Key=<connector>(让 connectorAuth 放行)+ X-Principal=<实际 caller>
|
||||
// 让 principalFromRequest 走 X-Principal 分支,读 filter 按真实身份工作。
|
||||
// 新行为:callConn 透传调用方真实 X-API-Key / session cookie,内层 principalFromRequest
|
||||
// 自然解析到调用方主体,读 filter 按真实身份工作。
|
||||
// (2026-10-17 变更:此前内层注入 `X-Principal` 头,该头可被外部伪造,已改为透传真实 key。)
|
||||
func TestIntegration_MCPRead_RespectsPrincipal(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
seedConnectorForTest(t)
|
||||
|
||||
hMgr := map[string]string{"X-Principal": "manager"}
|
||||
hMgr := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 建一个含 L0/L1/L3 三档的测试类型 + 3 个实例
|
||||
key := "test_mcp_read_principal"
|
||||
@@ -222,10 +222,10 @@ func TestIntegration_MCPRead_RespectsPrincipal(t *testing.T) {
|
||||
// TestIntegration_MCPRead_QueryRelatedPrincipal 通过 MCP /api/v1/mcp 端点
|
||||
// 验证 callConn 修复:manager 走 query_related 应能见 L3,connector 只能见 L0。
|
||||
func TestIntegration_MCPRead_QueryRelatedPrincipal(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
env, a := setupTestEnv(t)
|
||||
seedConnectorForTest(t)
|
||||
|
||||
hMgr := map[string]string{"X-Principal": "manager"}
|
||||
hMgr := authHeaderFor(t, a, "manager")
|
||||
|
||||
key := "test_mcp_query_related"
|
||||
t.Cleanup(func() {
|
||||
@@ -297,8 +297,8 @@ func TestIntegration_MCPRead_QueryRelatedPrincipal(t *testing.T) {
|
||||
// PUT /access/principals/:name 只传 description 不传 api_key 时,响应 has_api_key
|
||||
// 应反映 DB 真实状态,而非误报 false。
|
||||
func TestIntegration_UpdatePrincipal_NotTouchKeyHasAPIEchoTrue(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
key := "test_not_touch_key"
|
||||
t.Cleanup(func() {
|
||||
|
||||
@@ -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,40 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/http"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// 进程内主体传递:修复 X-Principal 头越权洞(2026-10-17)。
|
||||
//
|
||||
// 背景:principalFromRequest 曾把客户端可任意设置的 `X-Principal` 请求头作为最高优先级、
|
||||
// 完全无鉴权地决定主体。任何 HTTP 客户端带 `X-Principal: manager` 即取得平台最高权限。
|
||||
//
|
||||
// 本文件提供进程内自调用(callHandler / mcpCall)传递当前主体的唯一通道:
|
||||
// 主体挂在 *http.Request 的 context 上,而非 HTTP 头。context 由代码构造、
|
||||
// 网络请求无法携带,故外部伪造不可能命中。
|
||||
//
|
||||
// 严禁改回「设 X-Principal 头」——那正是被封掉的洞。
|
||||
|
||||
// principalCtxKey 私有类型,避免与外部包/未来 context key 撞名。
|
||||
type principalCtxKey struct{}
|
||||
|
||||
// withInjectedPrincipal 返回一个携带指定主体的 request 副本(原 request 不变)。
|
||||
// 主体为空时原样返回,调用方可无条件套用。
|
||||
func withInjectedPrincipal(req *http.Request, principal string) *http.Request {
|
||||
p := strings.TrimSpace(principal)
|
||||
if req == nil || p == "" {
|
||||
return req
|
||||
}
|
||||
return req.WithContext(context.WithValue(req.Context(), principalCtxKey{}, p))
|
||||
}
|
||||
|
||||
// injectedPrincipal 读出进程内注入的主体;外部请求恒为空串。
|
||||
func injectedPrincipal(ctx context.Context) string {
|
||||
if ctx == nil {
|
||||
return ""
|
||||
}
|
||||
p, _ := ctx.Value(principalCtxKey{}).(string)
|
||||
return strings.TrimSpace(p)
|
||||
}
|
||||
@@ -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.
+2
-2
@@ -46,7 +46,7 @@ function sendCors(res, status, body, type = 'application/json') {
|
||||
'Content-Type': type,
|
||||
'Access-Control-Allow-Origin': '*',
|
||||
'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
|
||||
'Access-Control-Allow-Headers': 'Content-Type, X-API-Key, X-Principal, Accept',
|
||||
'Access-Control-Allow-Headers': 'Content-Type, X-API-Key, Accept',
|
||||
'Access-Control-Max-Age': '86400',
|
||||
});
|
||||
res.end(body);
|
||||
@@ -71,7 +71,7 @@ function proxyToTarget(req, res) {
|
||||
const headers = { ...proxyRes.headers };
|
||||
headers['access-control-allow-origin'] = '*';
|
||||
headers['access-control-allow-methods'] = 'GET, POST, OPTIONS';
|
||||
headers['access-control-allow-headers'] = 'Content-Type, X-API-Key, X-Principal, Accept';
|
||||
headers['access-control-allow-headers'] = 'Content-Type, X-API-Key, Accept';
|
||||
res.writeHead(proxyRes.statusCode, headers);
|
||||
proxyRes.pipe(res); // 流式透传,SSE 也能正常转发
|
||||
});
|
||||
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))
|
||||
}
|
||||
}
|
||||
@@ -15,8 +15,8 @@ import (
|
||||
// 3) 写路径带快照头:直接 403(不改活库、不污染事务)
|
||||
// 4) 同事务内 search_path 不影响 information_schema(catalog 表独立)
|
||||
func TestIntegration_SnapshotRouter(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
// 1) 建一个测试类型 + 一个实例(作为「快照前」状态)
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
@@ -64,7 +64,7 @@ func TestIntegration_SnapshotRouter(t *testing.T) {
|
||||
// 5) 快照头读:应见 before=v=1、无 after(快照取的是改前那一刻)
|
||||
_, snapBody := env.httpDo(t, "GET", "/api/v1/connector/objects/"+env.typeKey+"?limit=50",
|
||||
nil, h,
|
||||
map[string]string{"X-Principal": "manager", "X-Snapshot-Id": strconv.FormatInt(snapID, 10)})
|
||||
map[string]string{"X-Snapshot-Id": strconv.FormatInt(snapID, 10)})
|
||||
snapItems, _ := snapBody["items"].([]any)
|
||||
snapSet := map[string]string{}
|
||||
for _, it := range snapItems {
|
||||
@@ -97,8 +97,8 @@ func TestIntegration_SnapshotRouter(t *testing.T) {
|
||||
// TestIntegration_SnapshotSearchPathPersist 验证 search_path 不污染下一个请求:
|
||||
// - 跑完一个 snapshot 请求后,下一个活库请求仍走 public
|
||||
func TestIntegration_SnapshotSearchPathPersist(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
env.httpDo(t, "POST", "/api/v1/ontology/object-types", map[string]any{
|
||||
"api_name": env.typeKey, "display_name": "persist-test",
|
||||
@@ -127,8 +127,8 @@ func TestIntegration_SnapshotSearchPathPersist(t *testing.T) {
|
||||
|
||||
// TestIntegration_SnapshotByTimestamp 验证 X-Snapshot-Ts 也能切库
|
||||
func TestIntegration_SnapshotByTimestamp(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
_, body := env.httpDo(t, "POST", "/api/v1/backups",
|
||||
map[string]any{"name": uniqSnapshotName(t)}, h)
|
||||
@@ -156,8 +156,8 @@ func TestIntegration_SnapshotByTimestamp(t *testing.T) {
|
||||
|
||||
// TestIntegration_SnapshotDeleteCleansSchema 验证 delete 真清掉对应 schema
|
||||
func TestIntegration_SnapshotDeleteCleansSchema(t *testing.T) {
|
||||
env, _ := setupTestEnv(t)
|
||||
h := map[string]string{"X-Principal": "manager"}
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
|
||||
_, body := env.httpDo(t, "POST", "/api/v1/backups",
|
||||
map[string]any{"name": uniqSnapshotName(t)}, h)
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
//go:build integration
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// principalKey 返回某主体在共享测试库里的真实 api_key。
|
||||
// 历史测试用 `X-Principal: manager` 头当捷径,该头已于 2026-10-17 封禁(外部可伪造 → 越权),
|
||||
// 统一改走真实凭据。
|
||||
func principalKey(t *testing.T, a *app, principal string) string {
|
||||
t.Helper()
|
||||
var key string
|
||||
err := a.pool.QueryRow(context.Background(),
|
||||
`SELECT api_key FROM principals WHERE name=$1 AND COALESCE(api_key,'')<>''`, principal).Scan(&key)
|
||||
if err != nil || key == "" {
|
||||
t.Fatalf("测试库缺少主体 %s 的 api_key(err=%v);请先跑 seedAccessControlDefaults 或 issue8 的 seed", principal, err)
|
||||
}
|
||||
return key
|
||||
}
|
||||
|
||||
// authHeaderFor 同 principalKey,但返回 env.httpDo 用的 header map。
|
||||
func authHeaderFor(t *testing.T, a *app, principal string) map[string]string {
|
||||
t.Helper()
|
||||
return map[string]string{"X-API-Key": principalKey(t, a, principal)}
|
||||
}
|
||||
|
||||
// doRaw 发一条不带 JSON 解码的请求(部分端点返回非 JSON)。
|
||||
func (e *testEnv) doRaw(t *testing.T, method, path string, headers map[string]string) (int, []byte) {
|
||||
t.Helper()
|
||||
req, err := http.NewRequest(method, e.srv.URL+path, nil)
|
||||
if err != nil {
|
||||
t.Fatalf("req: %v", err)
|
||||
}
|
||||
for k, v := range headers {
|
||||
req.Header.Set(k, v)
|
||||
}
|
||||
resp, err := e.srv.Client().Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("do: %v", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
b, _ := io.ReadAll(resp.Body)
|
||||
return resp.StatusCode, b
|
||||
}
|
||||
|
||||
func postMCP(t *testing.T, e *testEnv, headers map[string]string) (int, map[string]any) {
|
||||
t.Helper()
|
||||
body, _ := json.Marshal(map[string]any{
|
||||
"jsonrpc": "2.0", "id": 1, "method": "initialize",
|
||||
"params": map[string]any{"protocolVersion": "2024-11-05", "capabilities": map[string]any{}, "clientInfo": map[string]any{"name": "t", "version": "1"}},
|
||||
})
|
||||
req, err := http.NewRequest("POST", e.srv.URL+"/api/v1/mcp", bytes.NewReader(body))
|
||||
if err != nil {
|
||||
t.Fatalf("req: %v", err)
|
||||
}
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
req.Header.Set("Accept", "application/json, text/event-stream")
|
||||
for k, v := range headers {
|
||||
req.Header.Set(k, v)
|
||||
}
|
||||
resp, err := e.srv.Client().Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("do: %v", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
raw, _ := io.ReadAll(resp.Body)
|
||||
var out map[string]any
|
||||
_ = json.Unmarshal(raw, &out)
|
||||
return resp.StatusCode, out
|
||||
}
|
||||
|
||||
// TestXPrincipal_AnonymousForgeRejected 断言:匿名请求伪造 X-Principal: manager 不得取得 manager 身份。
|
||||
// 覆盖 managerAuth(401) / ingestOrManagerAuth(403) / mcpAuth(401) 三条鉴权链路。
|
||||
func TestXPrincipal_AnonymousForgeRejected(t *testing.T) {
|
||||
env, a := setupTestEnv(t)
|
||||
if !a.managerKeySet() {
|
||||
t.Skip("共享测试库 manager 尚未配置 api_key(dev 开放模式),无法验证真实鉴权")
|
||||
}
|
||||
forged := map[string]string{"X-Principal": "manager"}
|
||||
|
||||
if code, _ := env.httpDo(t, "GET", "/api/v1/ontology/object-types", nil, forged); code != 401 {
|
||||
t.Errorf("managerAuth: 匿名伪造 X-Principal 应 401, got %d", code)
|
||||
}
|
||||
if code, _ := env.httpDo(t, "GET", "/api/v1/km/tree", nil, forged); code != 403 {
|
||||
t.Errorf("ingestOrManagerAuth: 匿名伪造 X-Principal 应 403, got %d", code)
|
||||
}
|
||||
if code, _ := postMCP(t, env, forged); code != 401 {
|
||||
t.Errorf("mcpAuth: 匿名伪造 X-Principal 应 401, got %d", code)
|
||||
}
|
||||
}
|
||||
|
||||
// TestXPrincipal_DoesNotOverrideRealCredential 断言:X-Principal 不得覆盖已解析出的真实主体。
|
||||
// 低权限主体的合法 key + X-Principal: manager 仍应被 managerAuth 拒。
|
||||
func TestXPrincipal_DoesNotOverrideRealCredential(t *testing.T) {
|
||||
env, a := setupTestEnv(t)
|
||||
analyst := authHeaderFor(t, a, "analyst")
|
||||
analyst["X-Principal"] = "manager"
|
||||
|
||||
if code, _ := env.httpDo(t, "GET", "/api/v1/ontology/object-types", nil, analyst); code != 401 {
|
||||
t.Errorf("analyst key + X-Principal: manager 应仍被 managerAuth 拒(401), got %d", code)
|
||||
}
|
||||
if code, _ := env.httpDo(t, "GET", "/api/v1/km/tree", nil, analyst); code != 403 {
|
||||
t.Errorf("analyst key + X-Principal: manager 应仍被 ingestOrManagerAuth 拒(403), got %d", code)
|
||||
}
|
||||
}
|
||||
|
||||
// TestXPrincipal_RealCredentialStillWorks 反向断言:换成真实 manager key 后同一端点放行,
|
||||
// 确保上一条不是「因为端点坏了才通过」。
|
||||
func TestXPrincipal_RealCredentialStillWorks(t *testing.T) {
|
||||
env, a := setupTestEnv(t)
|
||||
h := authHeaderFor(t, a, "manager")
|
||||
if code, _ := env.httpDo(t, "GET", "/api/v1/ontology/object-types", nil, h); code != 200 {
|
||||
t.Errorf("manager 真实 key 应放行 managerAuth, got %d", code)
|
||||
}
|
||||
if code, _ := env.httpDo(t, "GET", "/api/v1/km/tree", nil, h); code != 200 {
|
||||
t.Errorf("manager 真实 key 应放行 ingestOrManagerAuth, got %d", code)
|
||||
}
|
||||
}
|
||||
@@ -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