一次收口 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]>
157 lines
6.6 KiB
Go
157 lines
6.6 KiB
Go
package main
|
||
|
||
// ---------- 空结果的确定性预检查(2026-11-06) ----------
|
||
//
|
||
// 动机(对标 NVIDIA/auto-ontology 的 empty-result 处置):
|
||
//
|
||
// auto-ontology 遇到空结果时的做法是「让 LLM 重新推导一次」(one-shot retry)——
|
||
// 因为在它那边,空结果的原因本来就是概率性的(检索没召回 / 表达式写错 / 过滤器太窄)。
|
||
//
|
||
// 本仓的空结果原因**大部分是确定性可判定的**,不该退化成一次 LLM 猜谜:
|
||
//
|
||
// no_data 该类型在当前快照下真的一个实例都没有 → 去摄取 / 建模
|
||
// not_visible 该类型有实例,但当前主体被标记/分级/分区挡住 → 去调权限
|
||
// not_materialized 该类型的数据来自物化,物化还没跑 → 去 refresh
|
||
//
|
||
// 这三件事的处置完全不同。若一律回一句「查不到」,调用方(尤其是读它的 LLM)
|
||
// 会把它当成「不存在」——把「不可见」误报成「不存在」是生成式问答里最常见、
|
||
// 也最有害的一类错误:用户被告知一条真实存在的数据不存在。
|
||
//
|
||
// 因此本仓的口径是:**空结果必须带原因**,且「不可见」与「不存在」严格分开。
|
||
//
|
||
// 两条红线:
|
||
// 1. 确定性:无 LLM、无随机、无外部调用,同输入同输出。
|
||
// 2. 不泄漏:not_visible 只说「被哪一维挡住」,**不给条数**——
|
||
// 连「有多少条」都不该告诉无权主体,那是另一种存在性泄漏。
|
||
|
||
import (
|
||
"context"
|
||
"fmt"
|
||
)
|
||
|
||
// 空结果原因码。
|
||
const (
|
||
// emptyCodeNoType 对象类型未注册(建模问题)。
|
||
emptyCodeNoType = "no_type"
|
||
// emptyCodeNoData 类型已注册,但当前快照下没有任何实例。
|
||
emptyCodeNoData = "no_data"
|
||
// emptyCodeNotVisible 有实例,但当前主体一条都看不到(权限问题)。
|
||
emptyCodeNotVisible = "not_visible"
|
||
// emptyCodeNotMaterialized 类型的数据来自物化,物化尚未产出任何行。
|
||
emptyCodeNotMaterialized = "not_materialized"
|
||
// emptyCodeNoMatch 检索无匹配(跨类型,不归因到具体类型)。
|
||
emptyCodeNoMatch = "no_match"
|
||
// emptyCodeUnknown 判定不了(查询失败)。
|
||
emptyCodeUnknown = "unknown"
|
||
)
|
||
|
||
// emptyReason 空结果的原因与处置建议。
|
||
type emptyReason struct {
|
||
Code string `json:"code"`
|
||
Detail string `json:"detail"`
|
||
Remedy string `json:"remedy"`
|
||
}
|
||
|
||
// emptyReasonOf 判定「该类型当前一条都看不到」的原因。
|
||
//
|
||
// 返回 nil 表示「不是空结果」(该类型当前有可见实例),调用方据此决定要不要带这个字段。
|
||
//
|
||
// 判定顺序刻意是「先看有没有,再看看不看得到,最后看是不是还没物化」:
|
||
// 数据是否存在是事实,可见性是权限,可见性判定要先于「是不是还没物化」,
|
||
// 因为「有实例但被挡住」比「还没物化」更常见,也更容易被误诊成后者。
|
||
func (a *app) emptyReasonOf(ctx context.Context, authz *Authz, objType string) *emptyReason {
|
||
if authz == nil {
|
||
authz = &Authz{Principal: "public", Clearances: map[string]bool{}}
|
||
}
|
||
|
||
// ---- 类型是否注册 ----
|
||
var typeCount int
|
||
if err := a.pool.QueryRow(ctx, `SELECT count(*) FROM object_types WHERE api_name=$1`, objType).Scan(&typeCount); err != nil {
|
||
return &emptyReason{
|
||
Code: emptyCodeUnknown,
|
||
Detail: "无法判定空结果原因(对象类型查询失败)",
|
||
Remedy: "重试;持续失败查服务端日志",
|
||
}
|
||
}
|
||
if typeCount == 0 {
|
||
return &emptyReason{
|
||
Code: emptyCodeNoType,
|
||
Detail: fmt.Sprintf("对象类型 %s 未注册", objType),
|
||
Remedy: "先建模(create_object_type)再问数",
|
||
}
|
||
}
|
||
|
||
// ---- 该类型实例数:总量 / 标记可见量 / 全维度可见量 ----
|
||
// 三个计数放在一条 SQL 里:过滤条件与占位符只构造一次,参数顺序与 $n 一致。
|
||
args := []interface{}{objType}
|
||
visCond, visArgs := visibilityCond(authz, "o", args)
|
||
classCond, classArgs := a.classificationCond(ctx, authz, "o", visArgs)
|
||
zoneCond, allArgs := a.zoneCond(ctx, authz, "o", "type_api_name", classArgs)
|
||
|
||
var total, markedVisible, visible int64
|
||
if err := a.pool.QueryRow(ctx,
|
||
`SELECT count(*),
|
||
count(*) FILTER (WHERE `+visCond+`),
|
||
count(*) FILTER (WHERE `+visCond+` AND `+classCond+` AND `+zoneCond+`)
|
||
FROM objects o WHERE o.type_api_name=$1 AND NOT COALESCE(o.deleted,false)`,
|
||
allArgs...).Scan(&total, &markedVisible, &visible); err != nil {
|
||
return &emptyReason{
|
||
Code: emptyCodeUnknown,
|
||
Detail: "无法判定空结果原因(实例计数失败)",
|
||
Remedy: "重试;持续失败查服务端日志",
|
||
}
|
||
}
|
||
if visible > 0 {
|
||
return nil // 不是空结果
|
||
}
|
||
|
||
// ---- 一条都没有:看是不是「物化还没跑」 ----
|
||
if total == 0 {
|
||
var pending int
|
||
_ = a.pool.QueryRow(ctx,
|
||
`SELECT count(*) FROM materializations
|
||
WHERE source_object_type=$1 AND is_active
|
||
AND (last_refresh_at IS NULL OR last_refresh_rows=0)`, objType).Scan(&pending)
|
||
if pending > 0 {
|
||
return &emptyReason{
|
||
Code: emptyCodeNotMaterialized,
|
||
Detail: fmt.Sprintf("类型 %s 的数据来自物化,物化尚未产出任何行", objType),
|
||
Remedy: "先刷新物化(POST /api/v1/materializations/:name/refresh)再查",
|
||
}
|
||
}
|
||
return &emptyReason{
|
||
Code: emptyCodeNoData,
|
||
Detail: fmt.Sprintf("类型 %s 在当前快照下没有任何实例(已排除软删除)", objType),
|
||
Remedy: "去摄取数据(batch_create_objects)或换一个问题",
|
||
}
|
||
}
|
||
|
||
// ---- 有实例但当前主体看不到:不泄漏条数,只说被哪一维挡住 ----
|
||
axis := "实例标记"
|
||
if markedVisible > 0 {
|
||
axis = "分级或分区"
|
||
}
|
||
return &emptyReason{
|
||
Code: emptyCodeNotVisible,
|
||
Detail: fmt.Sprintf("类型 %s 存在实例,但当前主体一条都看不到(被%s挡住)——这是权限问题,不是数据缺失",
|
||
objType, axis),
|
||
Remedy: "调权限:降低类型默认级 / 给主体补 clearance / 给主体补分区;不要据此回答「不存在」",
|
||
}
|
||
}
|
||
|
||
// emptyReasonNoMatch 检索无匹配时的原因(跨类型,不归因到具体类型)。
|
||
//
|
||
// 检索是跨类型的,无法断定「哪一类原因」,所以只给一句保守说明 + 下一步,
|
||
// 不像按类型查那样能给出确定的 code 归因。
|
||
func emptyReasonNoMatch(query string) *emptyReason {
|
||
detail := "检索无匹配结果"
|
||
if query != "" {
|
||
detail = fmt.Sprintf("检索 %q 无匹配结果", query)
|
||
}
|
||
return &emptyReason{
|
||
Code: emptyCodeNoMatch,
|
||
Detail: detail,
|
||
Remedy: "换关键词;或按类型用 get_objects_by_type 定位——若该类型返回 not_visible,则是权限问题而非数据缺失",
|
||
}
|
||
}
|