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

139 lines
4.8 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 的三态存在性探针):
//
// 生成式回答引用了一条**真实存在、但当前主体无权看到**的实例。
// 如果把它当成「不存在」,用户会被告知一条真实数据不存在——
// 这是生成式问答里最常见、也最有害的一类错误。
// 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
}