Files
ssw-ontology/server/schema_diff.go
T
adminandClaude Code d14440a3ed feat(server): v1.8.0 本体导入 + 分区 + 行级归属 + 认证位 + 结构 diff + 分页 + 进度回报
一次收口 2026-11-06 的九项能力(CHANGELOG 1.5.4 → 1.8.0):

- 自检探针(readiness.go):check_readiness / check_answerable 两个只读探针,把
  「本体里没有」「我没权限看」「模型没抽全」三种空结果原因拆开
- 读路径语义钉死(scope.go):标记与分级的可见范围统一由 Scope 产出,实例分级
  为空时继承类型默认级(fail-closed),列表与详情口径一致
- 行级可改性轴(object_owner.go):归属只收窄不宽于 grants,所有对象写路径统一
  走 canWriteObject,归属查询失败即拒绝
- 公理第 6 类 certification:认证位保护人工策展内容,AI 重摄取不再覆盖已认证条目
- 跨版本结构 diff(schema_diff.go):schema_snapshots 全量快照 + diff 端点,机器
  事实与人工策展分组呈现
- 分区维度 zone:分区绑类型、命中任一即可见,读路径一律带 zone 条件
- 统一分页信封(pagination.go):列表回包统一 count/total/limit/offset/has_more/
  truncated,total 与 items 同源
- MCP 长任务进度(mcp_progress.go):客户端带 progressToken 才走 SSE 进度帧
- 本体 schema 导入(ontology_import.go):Turtle 导入 + 四道 fail-fast 闸门 +
  整事务 + (source, external_id) 幂等 + IRI 往返不变式

MCP 工具清单并入单一注册表(mcp_registry.go),对外声明与实际可调不再各说各话;
工具数 42 → 54(只读 27 / 写入 27),注册表与分发 case 的双向漂移由 AST 单测拦截。

CHANGELOG 编号整理:新「认证位 + 行级归属」条目由 1.6.0 改为 1.5.6(1.6.x 留给
分区与结构 diff),2026-09-20 的 GB/T 规划稿改标「规划稿·未发布」——该能力已并入
v1.5.1,避免与正式发布的版本号重复。

Co-Authored-By: Claude Code <[email protected]>
2026-11-06 13:51:48 +08:00

659 lines
22 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package main
// 跨版本结构 diff(2026-11-06 · S4.4)
//
// 借鉴 NVIDIA auto-ontology catalog/diff.py 的 diff 原则:
// 增量 diff **只比源拥有的事实**,明确排除人工撰写的内容
// ("it is curated in the UI and must survive a re-ingest")。
//
// 本仓的对应实现:
// - 事实底座 = schema_snapshots(每次 schema 变更后落一份全量结构快照)
// - 比对口径 = 每条结构事实拆成【机器事实】与【人工策展】两组字段,
// diff 结果逐字段标出 class,汇总里分别计数
// - 认证位(axioms.certification,2026-11-06 落地)标记「这条已被人工确认」,
// 其策展字段在 AI 重摄取中被保护(见 ai/ai.go),diff 里单独标出
//
// 为什么用全量快照而不是回放 schema_versions 流水:
// schema_versions 是增量流水(一次变更一行),而 update 语义是 COALESCE 部分更新
// (见 handlers_ontology.go::updateObjectType),流水里的 after **不是完整状态**
// ——靠回放重建历史状态必然失真。全量快照让「任意两版本」退化成两次读文件的比较。
import (
"context"
"encoding/json"
"fmt"
"sort"
"strings"
)
// 结构事实的种类(与 ontology 六元原语对齐)。
const (
factKindObjectType = "object_type" // 对象类型
factKindObjectProp = "object_property" // 对象属性
factKindLinkType = "link_type" // 链接类型
factKindLinkProp = "link_property" // 链接属性
factKindActionType = "action_type" // 动作类型
)
// 字段归属分类:机器事实 vs 人工策展。
const (
classMachine = "machine_fact" // 机器事实:结构与配置,重摄取可覆盖
classCurated = "curated" // 人工策展:人写的文本与认证记录,重摄取须保留
)
// schemaFact 一条结构事实(一个类型 / 属性 / 链接类型 / 链接属性 / 动作类型)。
//
// Machine 与 Curated 两组字段互不重叠:前者是「结构与配置」,后者是「人写的内容」。
type schemaFact struct {
Kind string `json:"kind"`
Name string `json:"name"`
Machine map[string]any `json:"machine"`
Curated map[string]any `json:"curated"`
Certified bool `json:"certified"`
}
// schemaFieldChange 一个字段级变更。
type schemaFieldChange struct {
Field string `json:"field"`
Class string `json:"class"` // machine_fact | curated
Old any `json:"old"`
New any `json:"new"`
}
// schemaDiffEntry 一条结构事实的差异。
type schemaDiffEntry struct {
Kind string `json:"kind"`
Name string `json:"name"`
Change string `json:"change"` // added | removed | changed
Certified bool `json:"certified"`
Fields []schemaFieldChange `json:"fields,omitempty"`
}
// schemaDiffSummary 差异汇总:机器事实与人工策展分开计数。
type schemaDiffSummary struct {
Added int `json:"added"`
Removed int `json:"removed"`
Changed int `json:"changed"`
MachineFactFields int `json:"machine_fact_fields"`
CuratedFields int `json:"curated_fields"`
// CertifiedTouched 落在「已认证条目」上的差异条数——这类条目的策展内容
// 已被声明为受保护(重摄取不覆盖),改动它们需要人工确认。
CertifiedTouched int `json:"certified_entries_touched"`
}
// schemaDiffReport 跨版本结构 diff 报告。
type schemaDiffReport struct {
FromVersion any `json:"from_version"` // int64;0 = 基线
ToVersion any `json:"to_version"` // int64;"live" = 当前实时结构
FromLabel string `json:"from_label"`
ToLabel string `json:"to_label"`
Summary schemaDiffSummary `json:"summary"`
Entries []schemaDiffEntry `json:"entries"`
}
// ---------- 采集 ----------
// jsonbValue JSONB → 通用 Go 值(读路径统一走它,避免各处分类型不一致)。
func jsonbValue(raw []byte) any {
if len(raw) == 0 {
return nil
}
var v any
if err := json.Unmarshal(raw, &v); err != nil {
return nil
}
return v
}
// splitAxioms 把公理拆成「结构部分」(机器事实)与「认证部分」(人工策展)。
//
// 返回:结构部分(map,键与 typeAxioms 的 JSON 键同名)、是否带认证位。
func splitAxioms(ax *typeAxioms) (map[string]any, bool) {
structural := map[string]any{}
if ax == nil {
return structural, false
}
if len(ax.DisjointWith) > 0 {
structural["disjointWith"] = ax.DisjointWith
}
if len(ax.EquivalentTo) > 0 {
structural["equivalentTo"] = ax.EquivalentTo
}
if len(ax.FunctionalLinks) > 0 {
structural["functionalLinks"] = ax.FunctionalLinks
}
if len(ax.InverseOf) > 0 {
structural["inverseOf"] = ax.InverseOf
}
if len(ax.DateOrder) > 0 {
structural["dateOrder"] = ax.DateOrder
}
return structural, ax.Certification != nil
}
// certificationValue 认证位内容(人工策展:无认证位时为 nil)。
func certificationValue(ax *typeAxioms) any {
if ax == nil || ax.Certification == nil {
return nil
}
return ax.Certification
}
// captureSchemaFacts 采集当前实时结构(快照与 diff 共用同一份口径)。
func (a *app) captureSchemaFacts(ctx context.Context) ([]schemaFact, error) {
facts := []schemaFact{}
// ---- 对象类型 ----
rows, err := a.pool.Query(ctx, `
SELECT ot.api_name, ot.display_name, COALESCE(ot.description,''), COALESCE(ot.icon,''),
COALESCE(ot.group_name,''), COALESCE(ot.title_property,''), COALESCE(ot.subtitle_property,''),
COALESCE(ot.color,''), COALESCE(ot.primary_key,''),
COALESCE(ot.classification_property,''), COALESCE(ot.classification_levels,'[]'::jsonb),
COALESCE(ot.classification_default,''), COALESCE(ot.iri,''),
COALESCE(ot.axioms,'{}'::jsonb), COALESCE(ot.display_name_lang,'{}'::jsonb),
COALESCE(parent.api_name,'')
FROM object_types ot LEFT JOIN object_types parent ON ot.parent_id = parent.id`)
if err != nil {
return nil, err
}
for rows.Next() {
var (
apiName, dispName, desc, icon, groupName string
titleProp, subTitleProp, color, primaryKey string
clsProp, clsDefault, iri, parentName string
clsLevels, axiomsRaw, langRaw []byte
)
if err := rows.Scan(&apiName, &dispName, &desc, &icon, &groupName, &titleProp,
&subTitleProp, &color, &primaryKey, &clsProp, &clsLevels, &clsDefault, &iri,
&axiomsRaw, &langRaw, &parentName); err != nil {
rows.Close()
return nil, err
}
ax := parseAxiomsLenient(axiomsRaw)
structural, certified := splitAxioms(ax)
facts = append(facts, schemaFact{
Kind: factKindObjectType, Name: apiName, Certified: certified,
Machine: map[string]any{
"parent_api_name": parentName,
"iri": iri,
"title_property": titleProp,
"subtitle_property": subTitleProp,
"primary_key": primaryKey,
"icon": icon,
"color": color,
"group": groupName,
"classification_property": clsProp,
"classification_levels": jsonbValue(clsLevels),
"classification_default": clsDefault,
"axioms": structural,
},
Curated: map[string]any{
"display_name": dispName,
"description": desc,
"display_name_lang": jsonbValue(langRaw),
"certification": certificationValue(ax),
},
})
}
rows.Close()
// ---- 对象属性 ----
rows, err = a.pool.Query(ctx, `
SELECT ot.api_name, p.api_name, p.display_name, p.data_type, p.required,
COALESCE(p.enum_values,'[]'::jsonb), COALESCE(p.description,''),
COALESCE(p.format,''), p.default_value, p.indexable, p.vector_index,
COALESCE(p.backing_column,''), COALESCE(p.sensitivity,''), COALESCE(p.iri,''),
COALESCE(p.display_name_lang,'{}'::jsonb)
FROM properties p JOIN object_types ot ON ot.id = p.object_type_id`)
if err != nil {
return nil, err
}
for rows.Next() {
var (
typeName, apiName, dispName, dataType string
required bool
enumRaw, defRaw, langRaw []byte
desc, format, backing, sensitivity, iri string
indexable, vectorIndex bool
)
if err := rows.Scan(&typeName, &apiName, &dispName, &dataType, &required,
&enumRaw, &desc, &format, &defRaw, &indexable, &vectorIndex,
&backing, &sensitivity, &iri, &langRaw); err != nil {
rows.Close()
return nil, err
}
facts = append(facts, schemaFact{
Kind: factKindObjectProp, Name: typeName + "." + apiName,
Machine: map[string]any{
"data_type": dataType,
"required": required,
"enum_values": jsonbValue(enumRaw),
"format": format,
"default_value": jsonbValue(defRaw),
"indexable": indexable,
"vector_index": vectorIndex,
"backing_column": backing,
"sensitivity": sensitivity,
"iri": iri,
},
Curated: map[string]any{
"display_name": dispName,
"description": desc,
"display_name_lang": jsonbValue(langRaw),
},
})
}
rows.Close()
// ---- 链接类型 ----
rows, err = a.pool.Query(ctx, `
SELECT api_name, display_name, source_type, target_type, cardinality,
COALESCE(description,''), directional, COALESCE(source_property,''),
COALESCE(target_property,''), COALESCE(iri,''), COALESCE(display_name_lang,'{}'::jsonb)
FROM link_types`)
if err != nil {
return nil, err
}
for rows.Next() {
var (
apiName, dispName, srcType, tgtType, cardinality string
desc, srcProp, tgtProp, iri string
directional bool
langRaw []byte
)
if err := rows.Scan(&apiName, &dispName, &srcType, &tgtType, &cardinality,
&desc, &directional, &srcProp, &tgtProp, &iri, &langRaw); err != nil {
rows.Close()
return nil, err
}
facts = append(facts, schemaFact{
Kind: factKindLinkType, Name: apiName,
Machine: map[string]any{
"source_type": srcType,
"target_type": tgtType,
"cardinality": cardinality,
"directional": directional,
"source_property": srcProp,
"target_property": tgtProp,
"iri": iri,
},
Curated: map[string]any{
"display_name": dispName,
"description": desc,
"display_name_lang": jsonbValue(langRaw),
},
})
}
rows.Close()
// ---- 链接属性 ----
rows, err = a.pool.Query(ctx, `
SELECT lt.api_name, p.api_name, p.display_name, p.data_type, p.required,
COALESCE(p.enum_values,'[]'::jsonb), COALESCE(p.description,'')
FROM link_properties p JOIN link_types lt ON lt.id = p.link_type_id`)
if err != nil {
return nil, err
}
for rows.Next() {
var (
ltName, apiName, dispName, dataType string
required bool
enumRaw []byte
desc string
)
if err := rows.Scan(&ltName, &apiName, &dispName, &dataType, &required, &enumRaw, &desc); err != nil {
rows.Close()
return nil, err
}
facts = append(facts, schemaFact{
Kind: factKindLinkProp, Name: ltName + "." + apiName,
Machine: map[string]any{
"data_type": dataType,
"required": required,
"enum_values": jsonbValue(enumRaw),
},
Curated: map[string]any{
"display_name": dispName,
"description": desc,
},
})
}
rows.Close()
// ---- 动作类型 ----
rows, err = a.pool.Query(ctx, `
SELECT api_name, display_name, COALESCE(description,''), COALESCE(params,'[]'::jsonb),
COALESCE(submission_criteria,'{}'::jsonb), COALESCE(side_effects,'{}'::jsonb),
COALESCE(impl_function_id,0), COALESCE(return_type,''),
COALESCE(when_to_suggest,'[]'::jsonb), COALESCE(llm_tool_description,'')
FROM action_types`)
if err != nil {
return nil, err
}
for rows.Next() {
var (
apiName, dispName, desc, retType, llmDesc string
paramsRaw, criteriaRaw, effectsRaw []byte
whenRaw []byte
implFn int64
)
if err := rows.Scan(&apiName, &dispName, &desc, &paramsRaw, &criteriaRaw, &effectsRaw,
&implFn, &retType, &whenRaw, &llmDesc); err != nil {
rows.Close()
return nil, err
}
facts = append(facts, schemaFact{
Kind: factKindActionType, Name: apiName,
Machine: map[string]any{
"params": jsonbValue(paramsRaw),
"submission_criteria": jsonbValue(criteriaRaw),
"side_effects": jsonbValue(effectsRaw),
"impl_function_id": implFn,
"return_type": retType,
"when_to_suggest": jsonbValue(whenRaw),
},
Curated: map[string]any{
"display_name": dispName,
"description": desc,
"llm_tool_description": llmDesc,
},
})
}
rows.Close()
sortSchemaFacts(facts)
return facts, nil
}
// sortSchemaFacts 稳定排序(kind → name),保证快照与 diff 结果确定性。
func sortSchemaFacts(facts []schemaFact) {
sort.Slice(facts, func(i, j int) bool {
if facts[i].Kind != facts[j].Kind {
return facts[i].Kind < facts[j].Kind
}
return facts[i].Name < facts[j].Name
})
}
// ---------- 比对 ----------
// canonicalJSON 归一化取值(用于比较):JSON 编码后字节一致即视为相等。
//
// 必要性:实时采集的值是 Go 强类型([]string / int64),快照读回的是通用 JSON 类型
// ([]any / float64)——按值直接比较会误判为「变了」。
func canonicalJSON(v any) string {
if v == nil {
return "null"
}
b, err := json.Marshal(v)
if err != nil {
return fmt.Sprintf("%v", v)
}
return string(b)
}
// diffSchemaFacts 比对两组结构事实(纯函数,可单测)。
func diffSchemaFacts(oldFacts, newFacts []schemaFact) []schemaDiffEntry {
oldIdx := indexSchemaFacts(oldFacts)
newIdx := indexSchemaFacts(newFacts)
keys := make([]string, 0, len(oldIdx)+len(newIdx))
seen := map[string]bool{}
for k := range oldIdx {
if !seen[k] {
seen[k] = true
keys = append(keys, k)
}
}
for k := range newIdx {
if !seen[k] {
seen[k] = true
keys = append(keys, k)
}
}
sort.Strings(keys)
entries := []schemaDiffEntry{}
for _, k := range keys {
of, okO := oldIdx[k]
nf, okN := newIdx[k]
switch {
case okO && okN:
fields := diffFactFields(of, nf)
if len(fields) == 0 {
continue
}
entries = append(entries, schemaDiffEntry{
Kind: nf.Kind, Name: nf.Name, Change: "changed",
Certified: nf.Certified || of.Certified,
Fields: fields,
})
case okN:
entries = append(entries, schemaDiffEntry{
Kind: nf.Kind, Name: nf.Name, Change: "added", Certified: nf.Certified,
Fields: factFields(nf, classMachine, classCurated, true),
})
case okO:
entries = append(entries, schemaDiffEntry{
Kind: of.Kind, Name: of.Name, Change: "removed", Certified: of.Certified,
Fields: factFields(of, classMachine, classCurated, false),
})
}
}
return entries
}
// indexSchemaFacts 按 kind/name 建索引。
func indexSchemaFacts(facts []schemaFact) map[string]schemaFact {
idx := make(map[string]schemaFact, len(facts))
for _, f := range facts {
idx[f.Kind+"/"+f.Name] = f
}
return idx
}
// diffFactFields 逐字段比对一条事实(机器事实组 + 人工策展组)。
func diffFactFields(oldF, newF schemaFact) []schemaFieldChange {
changes := []schemaFieldChange{}
changes = append(changes, diffFieldGroup(oldF.Machine, newF.Machine, classMachine)...)
changes = append(changes, diffFieldGroup(oldF.Curated, newF.Curated, classCurated)...)
sort.Slice(changes, func(i, j int) bool { return changes[i].Field < changes[j].Field })
return changes
}
// diffFieldGroup 比对同一组字段(机器事实组或人工策展组)。
func diffFieldGroup(oldM, newM map[string]any, class string) []schemaFieldChange {
changes := []schemaFieldChange{}
for field, ov := range oldM {
nv, ok := newM[field]
if !ok {
changes = append(changes, schemaFieldChange{Field: field, Class: class, Old: ov, New: nil})
continue
}
if canonicalJSON(ov) != canonicalJSON(nv) {
changes = append(changes, schemaFieldChange{Field: field, Class: class, Old: ov, New: nv})
}
}
for field, nv := range newM {
if _, ok := oldM[field]; !ok {
changes = append(changes, schemaFieldChange{Field: field, Class: class, Old: nil, New: nv})
}
}
return changes
}
// factFields 展开一条事实的全部字段(新增/删除条目用;added=true 时新值在 New 侧)。
func factFields(f schemaFact, machineClass, curatedClass string, added bool) []schemaFieldChange {
changes := []schemaFieldChange{}
for field, v := range f.Machine {
if added {
changes = append(changes, schemaFieldChange{Field: field, Class: machineClass, Old: nil, New: v})
} else {
changes = append(changes, schemaFieldChange{Field: field, Class: machineClass, Old: v, New: nil})
}
}
for field, v := range f.Curated {
if added {
changes = append(changes, schemaFieldChange{Field: field, Class: curatedClass, Old: nil, New: v})
} else {
changes = append(changes, schemaFieldChange{Field: field, Class: curatedClass, Old: v, New: nil})
}
}
sort.Slice(changes, func(i, j int) bool { return changes[i].Field < changes[j].Field })
return changes
}
// summarizeSchemaDiff 汇总差异(机器事实与人工策展分开计数)。
func summarizeSchemaDiff(entries []schemaDiffEntry) schemaDiffSummary {
var s schemaDiffSummary
for _, e := range entries {
switch e.Change {
case "added":
s.Added++
case "removed":
s.Removed++
case "changed":
s.Changed++
}
if e.Certified {
s.CertifiedTouched++
}
for _, f := range e.Fields {
if f.Class == classCurated {
s.CuratedFields++
} else {
s.MachineFactFields++
}
}
}
return s
}
// ---------- 快照存储 ----------
// storeSchemaSnapshot 落一份全量结构快照(按版本唯一;重复落覆盖)。
func (a *app) storeSchemaSnapshot(ctx context.Context, version int64, label string, facts []schemaFact) error {
b, err := json.Marshal(facts)
if err != nil {
return err
}
_, err = a.pool.Exec(ctx,
`INSERT INTO schema_snapshots(version, label, snapshot) VALUES($1,$2,$3::jsonb)
ON CONFLICT (version) DO UPDATE SET snapshot=EXCLUDED.snapshot, label=EXCLUDED.label, created_at=now()`,
version, label, string(b))
return err
}
// loadSchemaSnapshot 读回某版本的结构快照。
func (a *app) loadSchemaFactsSnapshot(ctx context.Context, version int64) ([]schemaFact, string, error) {
var (
raw []byte
label string
)
err := a.pool.QueryRow(ctx,
`SELECT snapshot, COALESCE(label,'') FROM schema_snapshots WHERE version=$1`, version).
Scan(&raw, &label)
if err != nil {
return nil, "", err
}
facts := []schemaFact{}
if err := json.Unmarshal(raw, &facts); err != nil {
return nil, "", err
}
return facts, label, nil
}
// captureAndStoreSchemaSnapshot 采集实时结构并按版本落快照(跨版本 diff 的底座)。
func (a *app) captureAndStoreSchemaSnapshot(ctx context.Context, version int64, label string) error {
facts, err := a.captureSchemaFacts(ctx)
if err != nil {
return err
}
return a.storeSchemaSnapshot(ctx, version, label, facts)
}
// ensureSchemaBaseline 首次启用结构快照时落一份基线(version=0)。
//
// 基线 = 「快照机制启用那一刻的实时结构」——它不是历史某个时刻的真值,
// 因此标签写明来源,避免被误读成「版本 0 时刻的结构」。
func (a *app) ensureSchemaBaseline(ctx context.Context) {
var n int
if err := a.pool.QueryRow(ctx, `SELECT count(*) FROM schema_snapshots WHERE version=0`).Scan(&n); err != nil {
return
}
if n > 0 {
return
}
facts, err := a.captureSchemaFacts(ctx)
if err != nil {
return
}
_ = a.storeSchemaSnapshot(ctx, 0, "基线(结构快照机制启用时的实时结构)", facts)
}
// ---------- diff 组装 ----------
// parseSchemaVersionParam 解析版本参数:"" / "baseline" → 0(基线),"live" → 实时,其余为整数。
func parseSchemaVersionParam(s string, allowLive bool) (int64, bool, error) {
s = strings.TrimSpace(s)
switch strings.ToLower(s) {
case "", "baseline", "基线":
return 0, false, nil
case "live", "current", "实时":
if !allowLive {
return 0, false, fmt.Errorf("该参数不支持 live")
}
return 0, true, nil
}
var v int64
if _, err := fmt.Sscanf(s, "%d", &v); err != nil {
return 0, false, fmt.Errorf("版本参数非法: %q(应为整数、baseline 或 live)", s)
}
return v, false, nil
}
// buildSchemaDiffReport 组装 diff 报告。to == nil 表示与当前实时结构比。
func (a *app) buildSchemaDiffReport(ctx context.Context, from int64, to *int64) (*schemaDiffReport, error) {
oldFacts, fromLabel, err := a.loadSchemaFactsSnapshot(ctx, from)
if err != nil {
return nil, fmt.Errorf("版本 %d 无结构快照(可用的快照版本见 GET /api/v1/ontology/schema/snapshots): %w", from, err)
}
if fromLabel == "" {
fromLabel = fmt.Sprintf("版本 %d 变更后的结构", from)
}
var (
newFacts []schemaFact
toLabel string
)
if to == nil {
newFacts, err = a.captureSchemaFacts(ctx)
if err != nil {
return nil, err
}
toLabel = "当前实时结构"
} else {
newFacts, toLabel, err = a.loadSchemaFactsSnapshot(ctx, *to)
if err != nil {
return nil, fmt.Errorf("版本 %d 无结构快照(可用的快照版本见 GET /api/v1/ontology/schema/snapshots): %w", *to, err)
}
if toLabel == "" {
toLabel = fmt.Sprintf("版本 %d 变更后的结构", *to)
}
}
entries := diffSchemaFacts(oldFacts, newFacts)
report := &schemaDiffReport{
FromVersion: from,
ToVersion: "live",
FromLabel: fromLabel,
ToLabel: toLabel,
Summary: summarizeSchemaDiff(entries),
Entries: entries,
}
if to != nil {
report.ToVersion = *to
}
return report, nil
}