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(<Name, &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, ¶msRaw, &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 }