Files
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

157 lines
6.6 KiB
Go
Raw Permalink 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
// ---------- 空结果的确定性预检查(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,则是权限问题而非数据缺失",
}
}