一次收口 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]>
139 lines
4.8 KiB
Go
139 lines
4.8 KiB
Go
package main
|
||
|
||
// ---------- 三态存在性探针(2026-11-06) ----------
|
||
//
|
||
// 动机(对标 NVIDIA/auto-ontology 的三态存在性探针):
|
||
//
|
||
// 生成式回答引用了一条**真实存在、但当前主体无权看到**的实例。
|
||
// 如果把它当成「不存在」,用户会被告知一条真实数据不存在——
|
||
// 这是生成式问答里最常见、也最有害的一类错误。
|
||
// NVIDIA 的做法是探针返回 Exists / NotExists / Invisible 三态,
|
||
// 并强调 Invisible 只能作为**溯源标记**,不能当成「查不到」的结论喂给用户。
|
||
//
|
||
// 本仓的读路径对越权实例一律 404(不泄漏存在性)——这是对的,
|
||
// 不能为了三态就把 404 改成 403/200,那等于把存在性泄漏出去。
|
||
// 所以三态需要一条**独立的管理面探针**:只有 manager 能问
|
||
// 「某主体看不看得见这条实例」,答案用于平台内部的解释与溯源
|
||
// (生成式链路据此说「当前主体无可见数据」,而不是「不存在」)。
|
||
|
||
import (
|
||
"context"
|
||
"errors"
|
||
"strings"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
"github.com/jackc/pgx/v5"
|
||
)
|
||
|
||
// 存在性三态。
|
||
const (
|
||
// existenceExists 存在且该主体可见。
|
||
existenceExists = "exists"
|
||
// existenceInvisible 真实存在,但该主体看不到(权限/分区挡住)。
|
||
existenceInvisible = "invisible"
|
||
// existenceNotExists 本体里确实没有这条实例(含已软删除)。
|
||
existenceNotExists = "not_exists"
|
||
)
|
||
|
||
// existenceProbe 存在性探针结果。
|
||
type existenceProbe struct {
|
||
Type string `json:"type"`
|
||
PK string `json:"pk"`
|
||
Principal string `json:"principal"`
|
||
State string `json:"state"`
|
||
Visible bool `json:"visible"`
|
||
BlockedBy []string `json:"blocked_by"`
|
||
Detail string `json:"detail"`
|
||
Note string `json:"note,omitempty"`
|
||
}
|
||
|
||
// probeExistence REST 入口(管理面,仅 manager;路由挂在 /api/v1/access 组)。
|
||
//
|
||
// 参数:type、pk 必填;principal 可选——不给则按**调用主体**判定。
|
||
func (a *app) probeExistence(c *gin.Context) {
|
||
typ := c.Query("type")
|
||
pk := c.Query("pk")
|
||
if typ == "" || pk == "" {
|
||
c.JSON(400, gin.H{"error": "type 与 pk 必填"})
|
||
return
|
||
}
|
||
principal := c.Query("principal")
|
||
if principal == "" {
|
||
_, principal = a.authzOf(c)
|
||
}
|
||
rep, err := a.probeExistenceOf(c, principal, typ, pk)
|
||
if err != nil {
|
||
c.JSON(500, gin.H{"error": err.Error()})
|
||
return
|
||
}
|
||
c.JSON(200, rep)
|
||
}
|
||
|
||
// probeExistenceOf 判定「某主体看不看得见这条实例」。
|
||
//
|
||
// 判定与真实读路径同口径(connObject 的三道关):
|
||
// 1. 读授权(grant) + 实例标记(marking)→ authz.CanRead
|
||
// 2. 分级(classification)→ classAllowed
|
||
// 3. 分区(zone)→ zoneFilter.allows
|
||
//
|
||
// 授权用的是**实时加载**的 Authz(不吃鉴权缓存):探针是诊断工具,
|
||
// 必须看到当下配置,不能因为缓存还没失效就给出过期结论。
|
||
func (a *app) probeExistenceOf(ctx context.Context, principal, typ, pk string) (*existenceProbe, error) {
|
||
rep := &existenceProbe{
|
||
Type: typ, PK: pk, Principal: principal,
|
||
State: existenceNotExists, BlockedBy: []string{},
|
||
}
|
||
|
||
var deleted bool
|
||
var cls string
|
||
err := a.pool.QueryRow(ctx,
|
||
`SELECT COALESCE(deleted,false), COALESCE(classification,'') FROM objects
|
||
WHERE type_api_name=$1 AND pk=$2`, typ, pk).Scan(&deleted, &cls)
|
||
if err != nil {
|
||
if errors.Is(err, pgx.ErrNoRows) {
|
||
rep.Detail = "本体中不存在该实例"
|
||
rep.Note = "确实不存在:回答里可以直接说「本体暂无」"
|
||
return rep, nil
|
||
}
|
||
return nil, err
|
||
}
|
||
if deleted {
|
||
rep.Detail = "实例已软删除(消费者默认不可见)"
|
||
rep.Note = "已软删除:视同不存在,但与「从未存在」不同(血统与审计记录仍在)"
|
||
return rep, nil
|
||
}
|
||
|
||
// 实时加载授权(不吃缓存)
|
||
authz, err := a.loadAuthz(ctx, principal, false)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
mks := a.loadObjectMarkings(ctx, typ, pk)
|
||
if !authz.CanRead(typ, pk, mks) {
|
||
if !authz.Allowed("read", typ, pk) {
|
||
rep.BlockedBy = append(rep.BlockedBy, "grant")
|
||
} else {
|
||
rep.BlockedBy = append(rep.BlockedBy, "marking")
|
||
}
|
||
}
|
||
if !a.classAllowed(ctx, authz, typ, cls) {
|
||
rep.BlockedBy = append(rep.BlockedBy, "classification")
|
||
}
|
||
if zf := a.zoneFilterOf(ctx, authz); !zf.allows(typ) {
|
||
rep.BlockedBy = append(rep.BlockedBy, "zone")
|
||
}
|
||
|
||
if len(rep.BlockedBy) == 0 {
|
||
rep.State = existenceExists
|
||
rep.Visible = true
|
||
rep.Detail = "存在且该主体可见"
|
||
return rep, nil
|
||
}
|
||
rep.State = existenceInvisible
|
||
rep.Visible = false
|
||
rep.Detail = "实例真实存在,但该主体看不到(被 " + strings.Join(rep.BlockedBy, "、") + " 挡住)"
|
||
rep.Note = "invisible 是溯源标记:回答时应说「当前主体无可见数据」,不要据此说「不存在」"
|
||
return rep, nil
|
||
}
|