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

277 lines
9.2 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
// 分区维度(zone):目录分区 + 授权边界。
//
// 借鉴 NVIDIA auto-ontology 的 zone(`dal/schema.py:729-790`、`dal/terms.py:82-104`):
// zone 不是「相关度过滤」(相关度过滤是排序问题),而是**授权边界**——
// 「落在 zone 之外的实体被完全隐藏,而不是排在后面」。
//
// 与本仓另两个维度的关系(三个维度叠加,AND,不是互斥):
//
// marking / clearance —— 「这一行有多敏」 (实例级,object_markings + principal_clearances)
// classification —— 「这一行有多级」 (实例级 + 类型默认值)
// zone —— 「这一类属于哪个目录」 (类型级,object_zones + principal_zones)
//
// 三个维度各管一件事,任何一个拒绝即不可见。zone 与 marking 不互斥:
// 一个实例可以既在「财务」分区里、又被标了 L2 敏级——要看到它,
// 主体既得持有该分区、也得有 L2 的 clearance。
//
// **分区绑定在对象类型上**(不是实例上),这是本仓的取舍:
// - 本仓的「数据资产层」就是对象类型(承载业务实体/资产的类);
// 分区到类型 ⇒ 一次查询即可判定该请求内全部实例的可见性;
// - 实例级分区需要给每一行单独打标,且极易在新增读路径时漏掉 ⇒
// NVIDIA 的 zone 之所以「半成品」,正是全局关闭后没人再管它
// (benchmark 文档 §3.4)。类型级分区能保证**每个读路径都带得上一条条件**。
//
// 判定口径(命中任一即可见,与「目录分区」的直觉一致):
//
// - 类型不属于任何分区 → 公共区,所有主体可见;
// - 类型属于分区集合 Z → 主体持有 Z 中**至少一个**分区即可见;
// - 主体一个分区都没有 → 所有被分区的类型都不可见(fail-closed)。
//
// 「命中任一」而不是「必须全中」:类型同时属于两个目录(财务 + 集团共享)时,
// 持有任一目录的主体都应看得到——若要求「全中」,往类型上加第二个分区会
// 静默夺走已有主体的可见性(这类静默失权比泄露更难排查)。
import (
"context"
"errors"
"log"
"sort"
"strconv"
"strings"
)
// 分区名校验错误。
var (
errZoneNameEmpty = errors.New("分区名必填")
errZoneNameTooLong = errors.New("分区名最长 64 字符")
)
// Zone 分区配置(对外形状)。
type Zone struct {
Name string `json:"name"`
Description string `json:"description"`
Types []string `json:"types"` // 落在本分区的对象类型
Principals []string `json:"principals"` // 持有本分区的主体
}
// zoneFilter 一次请求内的分区判定结果。
//
// 分区绑在类型上 ⇒ 判定一次即可覆盖该请求里的全部实例,无需逐对象查库。
type zoneFilter struct {
denied map[string]bool // 主体无权访问的对象类型
// failClosed 为真表示分区配置读取失败:此时一律拒绝(读不到配置 ≠ 可以看)。
failClosed bool
}
// allows 该对象类型对主体是否可见。
func (f *zoneFilter) allows(objType string) bool {
if f == nil {
return true
}
if f.failClosed {
return false
}
return !f.denied[objType]
}
// deniedTypes 无权访问的类型(有序)。
func (f *zoneFilter) deniedTypes() []string {
if f == nil || len(f.denied) == 0 {
return nil
}
out := make([]string, 0, len(f.denied))
for t := range f.denied {
out = append(out, t)
}
sort.Strings(out)
return out
}
// zoneDeniedTypes 算出主体无权访问的对象类型集合(纯函数,便于单测)。
//
// principalZones:主体持有的分区;typeZones:对象类型 → 其所属分区列表。
// 见文件头「判定口径」:类型无分区 → 公共区;否则命中任一即可见。
func zoneDeniedTypes(principalZones map[string]bool, typeZones map[string][]string) map[string]bool {
denied := map[string]bool{}
for typ, zs := range typeZones {
if len(zs) == 0 {
continue // 公共区
}
hit := false
for _, z := range zs {
if principalZones[z] {
hit = true
break
}
}
if !hit {
denied[typ] = true
}
}
return denied
}
// zoneCondSQL 生成分区维度的 SQL 条件(与 visibilityCond / classificationCond 同构)。
//
// alias:表别名;typeCol:该表中承载「对象类型」的列名
// (objects 表为 type_api_name,links 表为 source_type / target_type)。
// 无权访问的类型集合为空 → 返回 "TRUE"(不过滤,保证「不配置分区 = 零影响」)。
func zoneCondSQL(alias, typeCol string, denied []string, args []interface{}) (string, []interface{}) {
if len(denied) == 0 {
return "TRUE", args
}
args = append(args, denied)
ph := "$" + strconv.Itoa(len(args))
return `NOT (` + alias + `.` + typeCol + ` = ANY(` + ph + `::text[]))`, args
}
// loadZoneTypeMap 取「对象类型 → 所属分区列表」。
func (a *app) loadZoneTypeMap(ctx context.Context) (map[string][]string, error) {
out := map[string][]string{}
rows, err := a.pool.Query(ctx,
`SELECT object_type, zone_name FROM object_zones ORDER BY object_type, zone_name`)
if err != nil {
return nil, err
}
defer rows.Close()
for rows.Next() {
var typ, zone string
if err := rows.Scan(&typ, &zone); err != nil {
continue
}
out[typ] = append(out[typ], zone)
}
return out, rows.Err()
}
// zoneFilterOf 计算当前主体在分区维度上的可见范围。
//
// 每次请求现查分区配置(object_zones 体量小、且要求「改了立刻生效」,
// 不吃缓存);主体持有的分区取自 Authz(principal_zones,变更时清缓存)。
//
// fail-closed:分区配置读不出来 → 一律拒绝。读不到配置不等于可以看。
func (a *app) zoneFilterOf(ctx context.Context, authz *Authz) *zoneFilter {
if authz == nil || authz.Principal == "manager" {
return &zoneFilter{}
}
typeZones, err := a.loadZoneTypeMap(ctx)
if err != nil {
log.Printf("[zone] 读取分区配置失败,按 fail-closed 处理: %v", err)
return &zoneFilter{failClosed: true}
}
return &zoneFilter{denied: zoneDeniedTypes(authz.Zones, typeZones)}
}
// zoneCond 把分区过滤下推成 SQL 条件(列表 / 检索 / 图谱邻居共用)。
func (a *app) zoneCond(ctx context.Context, authz *Authz, alias, typeCol string, args []interface{}) (string, []interface{}) {
zf := a.zoneFilterOf(ctx, authz)
if zf.failClosed {
// 配置读不出来:条件恒假 = 什么都看不到(与 fail-closed 一致)。
return "FALSE", args
}
return zoneCondSQL(alias, typeCol, zf.deniedTypes(), args)
}
// zoneAllowed 单个对象类型是否对主体可见(详情路径用)。
//
// 与 zoneCond 同口径:列表看不到的类型,详情也必须 404(不泄漏存在性)。
func (a *app) zoneAllowed(ctx context.Context, authz *Authz, objType string) bool {
return a.zoneFilterOf(ctx, authz).allows(objType)
}
// ---------- 分区配置的读写 ----------
// normalizeZoneName 规整分区名(去空白;不允许空)。
func normalizeZoneName(s string) (string, error) {
name := strings.TrimSpace(s)
if name == "" {
return "", errZoneNameEmpty
}
if len(name) > 64 {
return "", errZoneNameTooLong
}
return name, nil
}
// normalizeNameList 规整字符串清单:去空白、去重、保序。
func normalizeNameList(in []string) []string {
out := []string{}
seen := map[string]bool{}
for _, s := range in {
s = strings.TrimSpace(s)
if s == "" || seen[s] {
continue
}
seen[s] = true
out = append(out, s)
}
return out
}
// loadZones 取全部分区配置(含类型与主体清单)。
func (a *app) loadZones(ctx context.Context) ([]Zone, error) {
zones := map[string]*Zone{}
rows, err := a.pool.Query(ctx, `SELECT zone_name, description FROM zones ORDER BY zone_name`)
if err != nil {
return nil, err
}
for rows.Next() {
var name, desc string
if err := rows.Scan(&name, &desc); err != nil {
continue
}
zones[name] = &Zone{Name: name, Description: desc, Types: []string{}, Principals: []string{}}
}
rows.Close()
if err := rows.Err(); err != nil {
return nil, err
}
trows, err := a.pool.Query(ctx, `SELECT zone_name, object_type FROM object_zones ORDER BY zone_name, object_type`)
if err != nil {
return nil, err
}
for trows.Next() {
var z, t string
if err := trows.Scan(&z, &t); err != nil {
continue
}
if zones[z] == nil {
zones[z] = &Zone{Name: z, Types: []string{}, Principals: []string{}}
}
zones[z].Types = append(zones[z].Types, t)
}
trows.Close()
if err := trows.Err(); err != nil {
return nil, err
}
prows, err := a.pool.Query(ctx, `SELECT zone_name, principal FROM principal_zones ORDER BY zone_name, principal`)
if err != nil {
return nil, err
}
for prows.Next() {
var z, p string
if err := prows.Scan(&z, &p); err != nil {
continue
}
if zones[z] == nil {
zones[z] = &Zone{Name: z, Types: []string{}, Principals: []string{}}
}
zones[z].Principals = append(zones[z].Principals, p)
}
prows.Close()
if err := prows.Err(); err != nil {
return nil, err
}
out := make([]Zone, 0, len(zones))
for _, z := range zones {
out = append(out, *z)
}
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
return out, nil
}