Files
adminandClaude Code aef8b83e24 docs(release): v1.8.0 发布说明 + 本体导入设计约束落地记录 + 对标分析
- 新增 docs/ONTOLOGY_IMPORT.md:本体 schema 导入的硬约束(fail-fast 闸门、整事务、
  幂等键、IRI 双空间映射、不做范围对账删除),并记录实现落点与逐条偏差
- 新增 docs/auto-ontology-benchmark-20261106.md:NVIDIA auto-ontology 对标分析与
  Top-8 路线图,本版已落地项逐条标注
- docs/README.md 同步 API 清单与 MCP 工具表(54 个:只读 27 / 写入 27)
- 项目 CLAUDE.md 补「本体 schema 导入」小节:闸门顺序、事务与串行理由、幂等表、
  RDF Schema 命名空间年份坑
- README.md 镜像标签更新到 1.8.0,本地构建镜像补上 Linux 静态二进制交叉编译步骤,
  健康检查端点改回 /api/v1/version
- scripts/ 收拢本体 v2 迁移与分级校正脚本(一次性运维工具,不参与构建)

Co-Authored-By: Claude Code <[email protected]>
2026-11-06 13:53:25 +08:00
..

通用本体元数据平台 · Ontology Platform

把业务实体、属性、关系、动作、函数和接口统一纳入本体元数据,并通过访问控制与运行时审计控制信息的安全使用。

设计对标 Palantir Ontology(Semantic + Kinetic + Dynamic Security + Function-backed Action)。 技术栈:Go + Gin + PostgreSQL + Vue3 + Element Plus。前端构建产物复制到 server/webroot 后由 Go //go:embed 内嵌进二进制。


1. 架构定位

平台采用 Semantic / Kinetic 双层模型(参考 Palantir Ontology 设计):

  • Semantic 语义层:描述企业"有什么"以及实体之间如何关联。
    • Object Type / Object:对象类型与对象实例
    • Property:对象属性
    • Link Type / Link:关系类型与关系实例
    • Interface Type:对外 REST / MCP 接口契约
    • 公理声明:disjointWith / equivalentTo / functionalLinks / inverseOf / dateOrder(object_types.axioms,2026-09-20,详见 STANDARD_GB48000_3_2026_GAP.md §5.2 #4)
  • Kinetic 行为层:描述业务"如何计算、如何执行、如何变化"。
    • Action Type:用户主动触发、通常带副作用的动作
    • Function Type:可复用、类型化的计算函数
    • Function-backed Action:Action 绑定 Function 形成端到端执行链
    • Materialization:物化数据集,把多表 join 投影成快读行
  • Dynamic Security:运行时执行主体识别、授权、标记过滤、字段脱敏、审计日志

平台本身承担类似 Ontology Metadata Service(OMS)的职责:管理元数据、实例数据、治理规则和对外查询接口。

1.1 当前元数据组件

组件 数据表 当前状态
Object object_types / objects ✅ 已实现,含 title_property / subtitle_property / color / primary_key;iri 列存全球唯一标识;axioms 公理声明五类 / parent_id SubclassOf 类型继承 / display_name_lang 多语标签(2026-09-20)
Property properties ✅ 已实现,含 format / default_value / indexable / vector_index / backing_column;data_type 扩展 geoshape / geopoint / media / timeseries / timestamp / uri(绝对 URI 写入校验 + xsd:anyURI 导出);iri 列存全球唯一标识;display_name_lang 多语标签;管理读路径子类型合并祖先属性(标 inherited=true;连接器/MCP get_object_types 视图仍按自身属性,写校验闭包对子实例生效)
Link link_types / links ✅ 已实现,含 directional;链接本身可带字段(link_properties 子表);iri 列存全球唯一标识;display_name_lang 多语标签;functionalLinks 公理对边写入生效
Schema Version schema_versions ✅ 已实现,append-only 全局版本流水(schemaAudit 挂钩点即管理 API 五类 schema 增删改单调 +1;AI 摄取/合并清理等旁路写入暂不进流水,与 ontology_audit_log 同覆盖,PLAN.md 后续项),details 与 ontology_audit_log 同构含 before/after
Interface interface_types ✅ 已实现,含 shared_properties / parent_interface_id 多态;自动登记 6 个连接器接口
Action action_types ✅ 已实现完整契约(submission_criteria / side_effects / impl_function_id / return_type)+ FBA 执行链
Function function_types + builtin registry ✅ 已实现 4 个 builtin;含 when_to_suggest + llm_tool_description(AI 提示调度)
Materialization materializations / materialization_rows ✅ 已实现 CRUD + 60s ticker scheduler + 手动 refresh
Backing Source backing_sources ✅ 已实现,字段映射到 Materialization
Dynamic Security principals / principal_clearances / object_markings / grants / field_policies / access_log ✅ 已实现:授权检查、过滤、脱敏、审计

公理与 OWL 导出(2026-09-20):/ontology/export 现支持 OWL 公理(disjointWith/equivalentClass/inverseOf/FunctionalProperty);object_types.axioms 字段随 schema_versions 写入。

1.2 标准兼容元数据端点(GB/T 48000.3-2026 通用建模方法)

方法 路径 用途
GET /api/v1/ontology/meta 本体自描述:base_iri(ONTOLOGY_BASE_IRI 配置)+ profile + 服务版本;类型/属性/链接的 iri = base_iri + # + api_name,创建即固化、存量启动回填;默认 ONTOLOGY_BASE_IRI 为 example.org 占位,生产部署应改为自有命名空间
GET /api/v1/ontology/export?format=turtle schema 导出为 W3C Turtle(ObjectType→owl:Class、数据属性→owl:DatatypeProperty、LinkType→owl:ObjectProperty),含 OWL 公理(owl:disjointWith/owl:equivalentClass/owl:inverseOf/owl:FunctionalProperty)、rdfs:subClassOf、多语 rdfs:label "…"@lang、xsd:anyURI;Protégé 等标准工具可加载;其余 format 返回 400
POST /api/v1/ontology/import schema 导入(Turtle,与导出对称):四道 fail-fast 闸门(根键 G1 / 空文档 G2 / 作用域内无实体 G3 / 逐实体校验 G4)→ 整事务写入 → 幂等(source+external_id 映射落 import_identities,重复导入 0 新建、0 更新、不产新版本);只支持 mode=merge(replace 明确拒绝),dry_run=true 出逐条计划不落库;写闸门走 grants 的 manage 级授权;对应 MCP 工具 ontology_import。约束与偏差见 docs/ONTOLOGY_IMPORT.md
GET /api/v1/ontology/object-types · /api/v1/ontology/object-types/:name 返回含 axioms 与 parent_api_name(属性含 inherited 标;类型/属性/链接均回显 display_name_lang)
POST / PUT /api/v1/ontology/object-types[/:name] 接受 axioms(五类公理声明)、parent(SubclassOf,环/自指/父子互斥守卫)、display_name_lang(BCP47 典型形式标签,非法 400)
POST / PUT /api/v1/ontology/object-types/:name/properties · /api/v1/ontology/properties/:id(link-types 同) 接受 display_name_lang、data_type=uri(写入校验绝对 URI)
POST /api/v1/links · /api/v1/connector/links/batch 受 functionalLinks 公理边写入校验(同一功能性链接类型:同源指向不同 target 拒绝,无 validate_axioms 后门)
GET /api/v1/ontology/versions?kind=&name=&limit=&offset= schema 版本流水(最新在前);GET /api/v1/ontology/versions/:version 按版本读回该次变更完整 details(含 before/after 快照,JSON,不走快照路由)
GET /api/v1/ontology/schema/diff?from=&to= 跨版本结构 diff(见 §1.3);GET /api/v1/ontology/schema/snapshots 列出可比较的快照版本;POST /api/v1/ontology/schema/snapshot 手动标记锚点

1.3 跨版本结构 diff(2026-11-06)

「改了什么」的对照面:任意两个 schema 版本之间,机器事实与人工策展分开列。

GET  /api/v1/ontology/schema/diff?from=<版本|baseline>&to=<版本|live>
GET  /api/v1/ontology/schema/snapshots
POST /api/v1/ontology/schema/snapshot          # 手动标记当前结构为锚点
概念 说明
快照 每次 schema 变更后落一份全量结构(schema_snapshots 表);version 对应 schema_versions.version
基线 version=0,快照机制启用那一刻的实时结构(来源写在 label 里,不是历史某刻的真值)
from / to 整数版本号 / baseline(默认基线)/ live(默认当前实时结构);只能比较有快照的版本

比对口径:每条结构事实(对象类型 / 对象属性 / 链接类型 / 链接属性 / 动作类型)拆成两组字段——

  • machine_fact:结构与配置(IRI、父子继承、约束、公理、分级、显示名绑定…);
  • curated:人工内容(显示名、描述、多语标签、certification 认证记录)——正是重摄取不许覆盖的那部分。

带 certification 认证位的条目在 diff 里额外标 certified=true:改动这类条目前值得人工确认。响应 summary 分别给出 machine_fact_fields 与 curated_fields 计数。

为什么用全量快照而不是回放 schema_versions 流水:流水一次变更一行,且更新走部分更新语义(流水里的 after 不是完整状态),回放重建的历史状态会掺假。

MCP 工具:diff_schema_versions / list_schema_snapshots / capture_schema_snapshot。


2. 种子本体

为方便"docker run 一开箱就能看到东西",极简种子会自动灌入:

  • 1 个对象类型:「合作企业」(MemberOrg)
  • 3 条示例实例:纯平台 A、合作伙伴 B、合作伙伴 C(占位,可在管理界面一键删干净)

种子是占位演示,不代表任何业务假设。你可以:

  • 在管理界面「本体编辑 → 对象类型」一键删除种子类型
  • 直接进入「实例管理 → 合作企业」批量清空
  • 或把 SEED_ON_START=false 设成环境变量,跳过种子只留空库

平台对采用方完全中性。采用方(例如尚数网做数据要素、可信数据空间;某 CRM 团队做客户/合同;个人用户做笔记/人脉)各自按自己的业务建自己的对象类型与实例,互不耦合。


3. 快速开始

3.1 推荐构建与运行

./build.sh
./run.sh

build.sh 会依次完成:

  1. 构建 Vue 前端
  2. 将 web/dist 同步到 server/webroot
  3. 编译 Go 二进制到 bin/server

run.sh 默认连接:

postgres://ssw:[email protected]:5432/ssw-ontology?sslmode=disable

如要连其他 PG 实例,覆盖 .env 里的 DATABASE_URL(格式:postgres://user:pwd@host:port/dbname?sslmode=disable)。

默认监听 8081。如果该端口被本机其他服务占用,可临时切换:

HTTP_PORT=9090 ./bin/server

访问:

http://127.0.0.1:8081

使用 127.0.0.1 可绕过部分本机 HTTP 代理对 localhost 的影响。

3.2 关键环境变量

变量 说明 默认
DATABASE_URL PostgreSQL 连接串 workspace PostgreSQL
HTTP_PORT HTTP 监听端口 8081
SEED_ON_START 本体为空时灌入种子 true
ARCHIVE_DIR 知识文件归档目录 ../archive
AI_ENABLED 是否启用 OpenAI 兼容大模型 false
AI_BASE_URL / AI_KEY / AI_MODEL 大模型服务配置 空 / 默认
ONTOLOGY_BASE_IRI 本体全局 IRI 命名空间(类型/属性/链接的 iri = 该值 + # + api_name;改配置不回写存量) http://example.org/standard-ontology#
ALLOW_CORS 是否允许跨域 按配置加载

主体(manager/connector/public/ingest)的 API Key 不再通过环境变量配置:首次启动时由 server 自动随机生成并打印到 stdout;后续在管理界面的 Access Control 页查看、重置或清空。生产环境请妥善保存首次启动日志,并在能登录后立即修改默认密码(默认 changeme)。

前端修改后不能只替换磁盘上的静态文件。由于 server/main.go 使用 //go:embed all:webroot,必须重新执行 ./build.sh 或完成"前端 build → 同步 webroot → go build"。


4. Web UI

当前 Web UI 包含以下入口:

  1. 概览:对象类型、实例、关系和摄取概览。
  2. 本体编辑:Object / Property / Link / Action / Function / Interface 元数据 + Materialization / Backing Source Tab。
  3. 实例管理:按对象类型创建、编辑、删除对象实例;头部嵌入 💡 SuggestionHints(基于 when_to_suggest 推 Function / Action)。
  4. 知识管理:
    • 知识文件目录树 + 文件列表
    • 上传、建子文件夹、简单预览、单条或批量 AI 提取
    • 删除文件时级联清理关联对象、链接和摄取记录
    • 数据连接资源定义、导入本体、提取和级联删除
  5. 关系图谱:可视化对象节点和链接边,按当前主体权限过滤。
  6. 连接器:只读 REST / MCP 端点查询 + 工具清单 + 测试参数。
  7. 访问控制:
    • Principal 主体
    • Grant 授权
    • 对象 Marking
    • 字段 FieldPolicy
    • Dynamic Security 执行日志 + 24 小时统计

5. 提示调度(Palantir "when_to_suggest" 对标)

平台支持按上下文推 Function / Action,模仿 Palantir AIP 的"在正确时机推正确工具"体验:

  • Function/Action 元数据带 when_to_suggest(触发条件 JSONB)+ llm_tool_description(给 LLM 看的工具描述)
  • GET /api/v1/ontology/suggestions?context=object_view&type=TrustedDataSpace 返回当前上下文下建议调用的 Function + Action 列表
  • 前端用统一组件 SuggestionHints.vue 嵌入实例详情头部和 AI 摄取页,根据 context 自动出现 💡 提示

6. 连接器 REST / MCP API(只读,经 Dynamic Security)

所有查询都会经过当前主体的 Dynamic Security 决策:授权检查 → 对象标记过滤 → 字段策略脱敏 → 审计日志。

6.1 REST 端点

方法 路径 用途
GET /api/v1/connector/object-types 列出对象类型及属性定义
GET /api/v1/connector/objects/:type 按类型列出可见对象
GET /api/v1/connector/object/:type/:pk 获取单个可见对象
GET /api/v1/connector/search?q=&type=&field=&limit=&offset= 关键词检索可见对象
GET /api/v1/connector/facets?type= 获取过滤维度取值
POST /api/v1/connector/query 按类型+属性过滤,可展开关系邻居(body 支持 limit / offset)
GET /api/v1/connector/graph?type=&pk= 查询对象关系图
GET /api/v1/connector/readiness 自检探针:本体现在能不能用(ready + blockers/unverified/warnings 分档)
POST /api/v1/connector/answerable 可答性评估:{"question":"..."} → coverage/answerable/uncovered/candidates

6.2 MCP 端点(Streamable HTTP)

方法 路径 用途
GET /api/v1/mcp/manifest 人类可读 MCP 自描述(供 WorkBuddy 注册)
POST /api/v1/mcp JSON-RPC 2.0 Streamable HTTP(按 Accept 自动 JSON/SSE)

原生暴露 54 个工具(只读 27 / 写入 27),按组分类:

组 工具
自检探针(只读) check_readiness / check_answerable
查询(只读) get_object_types / get_objects_by_type / get_object / search_ontology / get_facets / query_related / whoami / get_server_info / get_usage_guide
治理(只读) get_object_history / find_duplicates / get_classification_config / list_principals / get_principal
知识库(只读) km_list_tree / km_list_files
备份(只读) backup_list / backup_inspect / backup_switch
结构版本(只读) diff_schema_versions / list_schema_snapshots
行级归属(只读) get_object_owners / list_groups
分区(只读) list_zones
存在性(只读,manager 专属) probe_existence
知识管理 km_create_folder / km_upload_markdown / km_extract / km_delete / set_km_classification
类型管理 create_object_type / update_object_type / add_object_type_property / create_link_type / update_enum / set_object_type_classification
实例写入 create_object / batch_create_objects / batch_create_links / create_link / delete_object / restore_object
分级与权限 recompute_classification / set_principal_clearance
行级归属(写入) set_object_owners / set_group
结构版本(写入) capture_schema_snapshot
本体导入(写入,manage 级) ontology_import
分区(写入) set_zone / delete_zone
备份 backup_create / backup_delete

实例写入的语义约定(merge 默认、软删除、source_ts 乱序丢弃、delete propagate 血统传播、审计回滚)详见 INSTANCE_GOVERNANCE.md。

工具清单单一事实来源:54 个工具的元数据(title / description / inputSchema / read_only / destructive / idempotent)全部登记在 server/mcp_registry.go 一份注册表里,tools/list 的 wire 清单、annotations、按名查询均由此派生,分发前按注册表准入。三条测试守住一致性:① 注册表不得重名、不得缺字段;② 注册表与 mcpDispatchTool 的 case 双向一致(AST 解析,防「声明了却调不通」与「能调却不声明」两种漂移);③ 只读工具全量调用前后比对平台状态指纹,只读性由测试保证而非注释。

读路径的可见范围(server/scope.go):过滤结果用显式类型 Scope 承载,分三档——ScopeUnscoped 不施加任何过滤、ScopeDenyAll 过滤生效且拒绝全部、ScopeAllow 只放行可见取值(取值集合为空 = 一个都不放行)。「不施加过滤」与「过滤后为空」在类型层面分开,不再靠 len(x)==0 的疏忽区分。配套语义:实例分级为空继承类型默认级(不是「无限制」);主体无任何 clearance 记录则看不到任何实例;列表路径与详情路径共用同一套判定,列表看不到的实例详情一律 404。

三条正交的可见性轴(叠加生效,不是互斥):

轴 粒度 判定
标记 / clearance 实例级 实例带标记,主体 clearance 覆盖该标记才可见
分级 实例级(可继承类型默认级) 生效级别 ≤ 主体最高 clearance 才可见
分区(zone) 类型级 类型入区后,主体持有该分区才可见

分区是目录分区 + 授权边界,不是相关度过滤:越区即完全不可见(列表与详情口径一致,看不到就是 404)。类型未入任何分区 = 公共区,全体可见;主体一个分区都不持有 → 所有被分区的类型都不可见(fail-closed);类型同时属于多个分区时命中任一即可见。分区只收窄可见性,不改可改性——写权限仍由 grants 与行级归属决定。

空结果与存在性(server/empty_reason.go / server/existence.go):空结果必须带原因,「不可见」与「不存在」严格分开。读路径回包新增 empty_reason:

code 含义 该做什么
no_data 该类型在当前快照下真的没实例 去摄取 / 建模
not_visible 有实例,但当前主体被标记 / 分级 / 分区挡住 调权限,不要回答「不存在」
no_type 对象类型未注册 先建模
not_materialized 数据来自物化,物化还没跑 先 refresh 物化
no_match 检索无匹配(跨类型,无法归因) 换关键词,或按类型定位

原因只说「被哪一维挡住」,不报条数——条数本身就是存在性泄漏。三态存在性探针 GET /api/v1/access/existence?type=&pk=&principal=(仅 manager)返回 exists / invisible(附 blocked_by:grant / marking / classification / zone)/ not_exists;读路径对越权实例仍一律 404,三态只走这条管理面探针。

统一分页信封(server/pagination.go):所有列表读路径(管理面 /api/v1/objects、连接器实例列表 / 检索 / 图式查询)回包带同一套分页字段:

字段 含义
count 本次实际返回的条数
total 过滤后的真实总数(与 items 同一 WHERE:授权 / 分级 / 分区过滤都在内)
limit / offset 本页上限与起始偏移
has_more 是否还有下一页
truncated 结果是否被 limit 截断(与 has_more 同值,语义更直白)

total 必须与 items 同源——先过滤再截断;反过来会让 total 偏小,调用方以为翻完了其实后面还有。total 与 count 由 total 推导 has_more(总数正好是 limit 整数倍时不会误报「还有下一页」)。检索(search_ontology / GET /connector/search)与图式查询(query_related / POST /connector/query)均支持 offset 翻页;offset 翻过头时空页返回 count=0 但 total 仍是真实总数——空页 ≠ 没有数据。各端点的 limit 上限仍不统一(检索 200 / 查询 500 / 列表 1000),是既有 API 行为。

长任务进度回报(server/mcp_progress.go):MCP 客户端在自己的超时里会把「没动静」当成卡死,然后重试——重试又叠加负载。长任务因此主动汇报进度,但客户端显式要才给:在 tools/call 的 _meta 里带 progressToken、且 Accept 里有 text/event-stream 时,服务端才进 SSE 进度模式。

带了就以 SSE 帧流式吐 notifications/progress(规范格式:event: message + data: {"jsonrpc":"2.0","method":"notifications/progress","params":{progressToken,progress,total,message}}),progressToken 原样回带,最后照常补一条 message 帧承载最终结果——进度不能顶掉结果。不带 → 走的还是原来那份单响应,行为与从前完全一致。

覆盖四类长任务:km_extract(逐份文档)、backup_create(逐张表)、recompute_classification(逐实例,试算与落库两轮都报)、batch_create_objects(逐条)。进度回调挂在请求 context 上,MCP 层的进程内子请求继承同一个 context;REST 直连路径没有回调时为空操作。进度帧做了节流(最小间隔 200ms),全库重算上万实例不会把 SSE 刷爆;被节流压下的最后一条一定补发,保证客户端看到终态。

6.3 一键注册到 WorkBuddy

{
  "mcpServers": {
    "ontology": {
      "url": "http://127.0.0.1:8081/api/v1/mcp"
    }
  }
}

然后在 WorkBuddy 的自定义连接器入口中信任该 MCP 服务。远程部署时将 127.0.0.1:8081 替换为实际可访问地址;如果启用了连接器密钥,按 WorkBuddy 的 MCP 配置增加请求头。


7. Function / Interface / Action

7.1 Function

Function 是可复用计算单元(对应 Palantir Function 语义):

  • 不等于 Action:Action 通常由用户触发并产生副作用;Function 通常是类型化、可复用、偏纯计算的能力
  • 当前 4 个 builtin:
    • mask_field_by_policy:按字段策略对属性脱敏
    • compute_object_link_strength:根据对象关联数量计算关系强度
    • compute_data_asset_value:按对象属性进行启发式资产价值估算
    • derive_object_completeness:计算对象必填属性完整度
  • 可调为 MCP 工具(待办)

调用示例:

curl -X POST \
  http://127.0.0.1:8081/api/v1/ontology/function-types/derive_object_completeness/invoke \
  -H 'Content-Type: application/json' \
  -d '{"object_type":"TrustedDataSpace","object_pk":"tds_logistics"}'

7.2 Interface

interface_types 用来描述外部可调用接口的协议、方法、路径、输入输出和 MCP 暴露属性。启动时自动登记 6 个连接器 REST 接口,作为 Interface 元数据,而非另建一套查询逻辑。

新增字段:shared_properties(多态共享字段集)、parent_interface_id(继承父接口)。

7.3 Action(完整契约,P0-1)

Action 在本平台是"用户主动触发的业务动作",带副作用;可关联一个 Function 形成 FBA(Function-backed Action):

  • 完整契约字段:
    • submission_criteria:提交参数校验规则(JSONB)
    • side_effects:副作用声明(JSONB)
    • impl_function_id:绑定的 Function id(FBA 模式)
    • return_type:返回类型
    • when_to_suggest:触发条件 JSONB
    • llm_tool_description:给 LLM 看的工具描述
  • 执行端点:POST /api/v1/objects/:type/:pk/actions/:action,支持 dry_run / FBA / 声明式三种分支

8. Materialization / Backing Source(P2 数据管道层)

为应对"多表 join 频次高、延迟敏感"的场景,平台引入物化层:

  • Materialization:定义物化数据集的源对象类型 + projection(JSONB 描述投影哪些字段)+ refresh_strategy(manual / interval:60s)+ is_active。Server 启动时开启 60s ticker scheduler 自动 refresh。
  • Backing Source:描述外部数据源(file / database / api / other),含 field_mapping(字段映射)+ materialization_id(可挂到物化上做 ETL)。

CRUD 端点:

GET / POST / DELETE  /api/v1/ontology/materializations
POST                 /api/v1/ontology/materializations/:name/refresh
GET                  /api/v1/ontology/materializations/:name/rows
GET / POST / DELETE  /api/v1/ontology/backing-sources

9. Dynamic Security 访问控制

安全控制不是普通业务对象,而是平级于对象、链接、动作的治理元能力。

9.1 四类治理原语

原语 作用
Principal 请求主体,如 manager / connector / public 或自定义主体
Marking 对象访问标记,默认使用 L0 ~ L4
Grant (principal, action, scope) → allow/deny 授权规则;deny 优先
FieldPolicy 字段级 redact / hide / full 策略

另有两条与上面正交的轴:

  • 分级(Classification):objects.classification + object_markings,决定「这一行的敏感度」,与主体 clearance 求交得到「看不看得到」。
  • 行级归属(ObjectOwner):object_owners,决定「谁能改这一行」。

9.2 运行时处理链

请求
  → 识别 principal
  → 检查 grant
  → 检查 object marking
  → 检查类型分区(zone)
  → 过滤对象 / 关系
  → 应用字段策略
  → 写入 access_log(allow/deny/filter/redact 四种 decision)
  → 返回结果

覆盖范围:连接器 REST、MCP 工具调用、对象/链接写入、本体 schema 管理、关系图谱、访问控制管理接口。

开发模式下,当 manager 主体的 api_key 尚未配置(全新库、首次启动前)时,匿名请求按 manager 处理以保持本地开发体验;首次启动后 server 会自动随机生成所有内置主体的 api_key 并打印到 stdout,之后真实鉴权默认生效,匿名请求回退为 public(L0 只读)。生产环境应通过 HTTPS 或反向代理保护服务,并妥善保存首次启动日志。

9.3 相关接口

GET    /api/v1/access/whoami
GET    /api/v1/access/principals
POST   /api/v1/access/principals
GET    /api/v1/access/principals/:name
PUT    /api/v1/access/principals/:name
DELETE /api/v1/access/principals/:name
GET    /api/v1/access/principals/:name/clearances
PUT    /api/v1/access/principals/:name/clearances
GET    /api/v1/access/grants
POST   /api/v1/access/grants
DELETE /api/v1/access/grants/:id
GET    /api/v1/access/markings
GET    /api/v1/access/objects/:type/:pk/markings
PUT    /api/v1/access/objects/:type/:pk/markings
GET    /api/v1/access/field-policies
POST   /api/v1/access/field-policies
DELETE /api/v1/access/field-policies/:id
GET    /api/v1/access/preview?principal=
GET    /api/v1/access/existence?type=&pk=&principal=
GET    /api/v1/access/log
GET    /api/v1/access/log/stats
GET    /api/v1/access/groups
PUT    /api/v1/access/groups/:name
DELETE /api/v1/access/groups/:name
GET    /api/v1/access/zones
POST   /api/v1/access/zones
DELETE /api/v1/access/zones/:name

9.4 行级可改性轴(object_owners)

clearance 决定「看不看得到」,owner 决定「能不能改」——两条轴互不影响。

概念 载体 语义
归属 object_owners(object_type, object_pk, owner_kind, owner_name) owner_kind = principal(账号)或 group(组)
组 principal_groups(principal, group_name) 组只是归属的载体,本身不带任何全局权限

判定口径(server/object_owner.go::canWriteObject,所有对象写路径统一走它):

  • grants 表仍是「能做什么动作」的唯一真源;归属只在 grant 之上收窄——对象设有归属时,非归属方即便持有该类型的写授权也不能改这一行;
  • 对象未设归属 → 不限制,历史行为一字不变(存量库零影响);
  • manager 豁免;归属查询失败 → 拒绝(fail-closed);
  • 组的成员获得该行的可改性,且仅限该行,不扩大任何全局权限;
  • 归属方可转交行(加协作者、换归属方);解除归属仅 manager;
  • 删组会连带解除引用该组的归属行——否则那些行会变成「谁都改不了」的静默死锁。

接口(/ownership 组只要求登录,归属方本人也能查/转交;组管理在 /access 组,仅 manager):

GET    /api/v1/ownership/objects/:type/:pk/owners
PUT    /api/v1/ownership/objects/:type/:pk/owners
DELETE /api/v1/ownership/objects/:type/:pk/owners

MCP 工具:get_object_owners / set_object_owners / list_groups / set_group。


10. AI 与知识管理

AI 摄取支持三类入口(2026-08-24 新增):

  1. 粘贴文本:在「知识管理」Tab 直接粘贴资料,指定 directive 抽取范围
  2. 知识文件:archive/ 下批量上传,目录树管理,单条/批量提取
  3. 数据连接资源:外部数据源(db / api / file / other)定义 → 一键导入本体

流程:资料输入 → AI/启发式抽取 → Suggestion(review/auto) → objects + links(source 溯源)。

source 字段精确记录"哪次 import 写的",删除时按 source 级联清理。修复了 ON CONFLICT 漏 source 字段的 4 处 bug(语义:COALESCE(NULLIF(EXCLUDED.source,''), objects.source),必须加表名限定)。

10.1 大模型配置

生产环境可设置 OpenAI 兼容服务:

AI_ENABLED=true \
AI_BASE_URL=https://api.deepseek.com/v1 \
AI_KEY=your-key \
AI_MODEL=deepseek-chat \
./run.sh

或 Anthropic 兼容(URL 含 /anthropic 时自动切换协议):

AI_ENABLED=true \
AI_BASE_URL=https://api.minimaxi.com/anthropic \
AI_KEY=your-key \
AI_MODEL=MiniMax-M3 \
./run.sh

升级到 2026-08-24 后,系统提示词从 65 行扩到 250+ 行,并支持动态上下文注入:每次 Suggest 前查 db 拉已注册类型清单追加到 system prompt,让 LLM 复用而非重复创建。


11. 项目结构

ontology-platform/
├── build.sh
├── run.sh
├── go.mod / go.sum
├── .gitignore
├── server/
│   ├── main.go                # 路由注册
│   ├── config.go
│   ├── db.go                  # 表结构 + 极简种子
│   ├── models.go              # 6 元原语 + Materialization + BackingSource 模型
│   ├── access_control.go      # Dynamic Security 核心
│   ├── access_log.go          # 审计中间件
│   ├── functions.go           # builtin Function registry
│   ├── handlers_access.go     # 访问控制 CRUD
│   ├── handlers_action.go     # applyAction 端点
│   ├── handlers_functions.go
│   ├── handlers_materialization.go
│   ├── handlers_backing_source.go
│   ├── handlers_suggestions.go # /suggestions 提示调度
│   ├── handlers_mcp.go
│   ├── handlers_connector.go
│   ├── handlers_km.go         # 知识管理(recursive/excluded/双向溯源)
│   ├── handlers_ai.go
│   ├── handlers_objects.go    # 实例 CRUD(merge 默认 + 软删除过滤 + fields 裁剪)
│   ├── object_upsert.go       # 统一写入入口:merge/replace 语义 + source_ts 乱序检查
│   ├── instance_governance.go # 级联删除/批量/审计/回滚/去重/血统传播
│   ├── display_name.go        # 显示名物化(title_property 回退链 + 缓存)
│   ├── handlers_ontology.go
│   ├── handlers_ontology_cleanup.go
│   ├── ai/                    # AI provider 抽象 + prompt
│   │   ├── ai.go              # Suggestion struct 22 字段 + ApplySuggestion
│   │   ├── prompt.go          # 250+ 行静态 systemPrompt
│   │   ├── anthropic.go
│   │   ├── openai.go
│   │   └── heuristic.go       # 启发式兜底(占位)
│   └── webroot/               # 前端构建产物,内嵌进二进制
├── web/
│   └── src/views/             # 7 个主视图
├── docs/
│   ├── README.md              # 本文件
│   ├── INSTANCE_GOVERNANCE.md # 实例治理:merge/软删除/批量/审计/血统传播/source_ts
│   ├── PLAN.md                # 设计目标 + 演进计划
│   ├── USAGE.md               # 启动 + 连接器 + AI 摄取实战
│   ├── IMPORT.md              # 外部数据源导入
│   ├── BACKUP.md              # 备份与快照路由
│   ├── TESTING.md             # 测试约定
│   ├── WORKBUDDY.md           # 一键注册到 WorkBuddy
│   ├── GB_T_48000.3-2026.pdf           # 国标全文:标准数字化 第3部分 本体建模要求
│   ├── STANDARD_GB48000_3_2026_GAP.md  # 与 GB/T 48000.3-2026 的符合性差距矩阵
│   └── product-intro.html
├── archive/                   # 知识文件,AI 摄取来源
├── scripts/                   # 通用运维/数据迁移脚本(由各采用方按需编写)
└── bin/                       # 编译产物

12. 当前状态与注意事项

  • ✅ 6 元原语(Object / Property / Link / Interface / Action / Function)+ Materialization / Backing Source / Dynamic Security 全部实现
  • ✅ 提示调度(when_to_suggest + llm_tool_description)+ applyAction 端点(支持 dry_run / FBA / 声明式)
  • ✅ AI 系统提示词升级:250+ 行 + 动态上下文注入,LLM 复用而非重复创建
  • ✅ 实例治理(2026-09-05,详见 INSTANCE_GOVERNANCE.md):merge 默认写入 / 软删除墓碑 + 墓碑过滤 / 批量事务接口 / object_changes 字段级审计 + history/restore / find_duplicates 去重提示 / same_as 别名跳转 / 显示名物化(修复 45% 实例 name 为空导致检索"隐身") / source_ts 乱序丢弃 / delete propagate 血统传播删除
  • ⚠️ 前端改动后必须重新构建并重新编译 Go 二进制,原因是前端静态资源被 //go:embed 内嵌
  • ⚠️ script / external_api Function 类型目前只完成元数据定义,尚未提供通用脚本沙箱或外部 HTTP 执行器
  • ⚠️ Interface 元数据已登记,但并未自动注册所有 Function 为 MCP 工具
  • ⚠️ ON CONFLICT upsert 路径已统一 source 字段语义(2026-08-24 修复 4 处);写入时 objects.source 表名必须限定,否则 PostgreSQL 报 ambiguous