Files
ssw-ontology/server/CHANGELOG.md
T

15 KiB
Raw Blame History

更新说明(CHANGELOG)

本文件随二进制一起编译打包(//go:embed),运行时通过 GET /api/v1/version/changelog、MCP 工具 get_server_info 或前端页脚可见。

格式遵循 Keep a Changelog,版本号采用语义化版本。

问题反馈(Issue 机制)

AI 客户端在使用本平台过程中发现 bug 或有改进建议,请提交 Issue,不要只在会话里提及(会话结束即丢失):

  • 自动提交(推荐):POST /api/v1/feedback(公开,无需任何 token)
    {"title":"xxx 失败","body":"复现步骤/期望/实际","kind":"bug"}
    
    kind 取 bug 或 suggestion(标题前缀 [bug]/[建议] 缺失时自动补,正文自动附服务端版本与时间)。响应返回 issue_number 与 issue_url。每 IP 每小时限 10 条。
  • Web 手工入口:https://oadfec13300ad18dm.mayishangshu.cn:82/ssw/ssw-ontology/issues (需登录)
  • 约定:正文带版本号(get_server_info)与复现步骤,能定位到的接口/工具名写进正文;同一问题先检索已有 issue 避免重复提交

版本历史

[1.4.1] - 2026-09-14 导入核对 tab 与全局风格统一

改动:ReviewWorkbench(导入核对)去掉内嵌 dark-theme SPA 外壳(sidebar/brand/进度环),改为与其它 tab 一致的 page-title + card 浅色风格;筛选折叠为顶部单行 filter-bar,状态 select/操作按钮替换为 el-select/el-button。7 项分类筛选、6 项状态筛选、连接/Key 配置、统计卡、详情展开、日志、清单导入、MD/JSON 导出、Apply 等功能全部保留。

[1.4.0] - 2026-09-11 使用分析 + schema 层审计

影响:本体定义(类型/属性/链接类型等)的增删改此前只有 access_log 的 method+path 间接痕迹,无 before/after;使用/浏览情况无法按本体分项统计(:name 参数路由的 target 长期为空)。

改动:

  • schema 审计:对象类型/属性/链接类型/链接属性/动作类型/分级配置的增删改写入 ontology_audit_log(target_pk 落库,update/delete 带 before 快照);存量库幂等补 target_pk 列。
  • access_log 中间件:按路由模板映射 target(修复 :name/:id 参数名导致 target 为空);4xx 响应兜底记 deny;action 归一为 read/write/delete/manage。
  • 保留策略:access_log 默认保留 90 天(ACCESS_LOG_RETENTION_DAYS 覆盖,0 关闭),启动时 + 每 24h 清理。
  • 使用分析 API(仅 manager):GET /api/v1/analytics/overview|types|users|sharing —— 总体读写比/活跃主体/来源分布/按天趋势、分项热度、用户活跃、共享授权使用量,全部现算不建新表。
  • 前端:新增「使用分析」tab(指标卡 + 按天趋势柱图 + 分项热度/用户活跃/共享明细表,7/30/90 天切换)。

[1.3.6] - 2026-09-07 MCP 读路径按真实调用者解析主体(issue #8)

影响:MCP 读工具(get_objects_by_type / get_object / query_related / search_ontology / get_object_types / get_facets)此前一律以 connector 主体执行,manager 走 MCP 只能看 connector clearance (L0-L2) 下的数据;现已按调用者真实 api_key 解析主体。

改动:

  • callConn 改为透传调用方 X-API-Key / session cookie,让 principalFromRequest 自然解析主体;不再注入 connector key + 手动 X-Principal(之前是「模拟身份」)。
  • connectorAuth 放宽:接受任何主体的 api_key(不再只接 connector key)。连接器入口 = 任何已认证主体;可见性仍由读路径 classification filter 按各自 clearance 控制。

顺带:PUT /access/principals/:name 只传 description 时响应 has_api_key 误报 false 已修复(读取 DB 真实状态回显)。

[1.3.3] - 2026-09-07 访问控制:principal clearance 可配置(issue #7)

影响:之前管理员无法通过 PUT /principals/:name 配置 clearance(字段被静默忽略),主体 clearance 列表接口也不回显;现已补齐。

改动:

  • PUT /access/principals/:name 新增 clearances []string(nil=不动;非空=全量替换)。
  • GET /principals/:name 与列表回显 clearances(保证非 nil)。
  • MCP 新增 list_principals / get_principal / set_principal_clearance 三个工具。

[1.3.2] - 2026-09-07 本体:补 update_object_type / add_object_type_property(issue #6)

影响:本体管理工具集缺「向已存在类型追加属性」入口,导致 587 个 data_level 实例无法被分级引擎接管;现已补齐。

改动:

  • PUT /object-types/:api_name 静默忽略 properties 字段已修复,与 createObjectType 共用 upsertObjectTypeProperties(同名更新元数据,新名新增)。
  • MCP 新增 update_object_type / add_object_type_property 工具。

设计:拒绝方案 C(让 set_object_type_classification 自动注入未注册属性)——属性注册应是显式动作,不应藏在分类配置里失去审计。

[1.3.1] - 2026-09-07 访问控制:内置主体可设置自己的 API Key;密钥完全由 DB 管理

修复管理员在「访问控制 → 主体」里编辑 manager(或 connector)并填入 API Key 时保存失败的问题;同步移除 .env 显式密钥,所有主体密钥由 DB(seed 随机值 + UI 管理)唯一管理。

修复

  • PUT /api/v1/access/principals/:name 此前对内置主体(manager/connector/public)一律拒绝任何 api_key 变更,导致 UI 编辑保存无反应。现改为仅禁止匿名主体 public 设置 key,manager/connector 可通过 UI 或 REST 设置/重置/清空自己的 key。
  • principalFromRequest 不再读取 .env 的 MANAGER_API_KEY/CONNECTOR_API_KEY,仅查 principals 表的 api_key;loginRequired / connectorAuth 同步切换为基于「DB 是否已有密钥」判断。

移除

  • Config.ManagerAPIKey / Config.ConnectorAPIKey / Config.IngestAPIKey 字段及对应 loadConfig 环境变量读取;seedAccessControlDefaults 不再接收 ingestKey 参数。
  • README.md、docs/README.md、docs/USAGE.md、docs/IMPORT.md、skills/ssw-ontology-reviewer/SKILL.md、web/src/views/ConnectorView.vue 中的 .env 密钥说明。

加固

  • 首次启动时 seedAccessControlDefaults 为 4 个内置主体(manager/connector/public/ingest)随机生成 API Key 并打印到 stdout,避免空 key / 固定值被暴力破解;重复启动幂等。

前端

  • 主体编辑 / 重置 Key 的失败现以 ElMessage.error 显式提示,不再静默吞错。

容器

  • HEALTHCHECK 端点由 /api/v1/connector/object-types 改为免鉴权的 /api/v1/version(v1.3.1 密钥收紧后 connector 接口无头请求返回 401,原探活恒失败会误报 unhealthy)。

[1.3.0] - 2026-09-07 数据备份(按 schema 镜像 + 请求级切库)

「M"做了「备份 → 可读快照库 → 不破坏业务 SQL」的能力,让 AI 客户端敢操作。详细语义见 docs/BACKUP.md。

新增

  • 备份按 schema 镜像:每次备份 = 一个独立 schema backups_<id>,包含 23 张 业务表的同结构副本 + 一致的 INSERT...SELECT 数据。查询性能与活库一致(真表,不是 JSONB)。
  • 请求级 search_path 切库:snapshotRouter 中间件读 X-Snapshot-Id / X-Snapshot-Ts 头 → BeginTx + SET LOCAL search_path TO <schema>, public → 把 a.pool 临时换为事务视图,业务代码一行不改即可命中快照库。
  • 快照只读护栏:写方法(POST/PUT/PATCH/DELETE)带快照头 → 403 拒绝(mistake-safety,不会误写活库)。
  • 两种切换入口:X-Snapshot-Id: 42(run id 直接定位)或 X-Snapshot-Ts: 1700000000(秒级时间戳 → 最近一次 ≤ ts 的快照)。
  • 接口:POST /api/v1/backups 创建、GET /api/v1/backups 列表、GET /api/v1/backups/:id 元信息、GET /api/v1/backups/:id/switch 切库提示、DELETE /api/v1/backups/:id 级联删 schema。
  • MCP 工具 + 4(清单共 32 个):backup_create / backup_list / backup_inspect / backup_switch / backup_delete。
  • 接口扩展:把 a.pool 字段类型从 *pgxpool.Pool 升级为 dbRunner interface(中间件可换 *txPool 注入),11 个 helper 函数签名同步改为 dbExec,业务 SQL 调用方式无任何变化。

测试

  • 22 个测试用例全绿(go test -tags=integration -timeout 120s ./server/ 5.5s):
    • 11 个纯函数单((之前已存在)
    • 4 个新快照路由集成:SnapshotRouter(改前建快照 → 改后读快照只见改前)/ SnapshotSearchPathPersist(不污染下一个请求)/ SnapshotByTimestamp(ts 头也能切库)/ SnapshotDeleteCleansSchema(delete 真 DROP schema)
    • 7 个备份 / 实例治理集成(已存在,已适配新接口)

[1.2.0] - 2026-09-07 关系边恢复 + 数据分级

采纳 Gitea issue #4、#5(其余项明确不采纳,原因见对应 issue 回帖)。详细语义见 docs/INSTANCE_GOVERNANCE.md §15–§16。

新增

  • restore_object 恢复关系边(issue #4):删除实例改为级联存边快照(object_changes.links_snapshot),回滚默认连同边一起重建(两端都在才建,悬空引用跳过);分级一并从快照物化,回滚不再绕过分级
  • 数据分级通用能力(issue #5,平台不硬编码字段名/级别名,详见 §16):
    • 类型级配置 classification_property / classification_levels / classification_default,objects.classification 物化列 + 索引供 SQL 直接过滤
    • 读路径(列表/详情/检索/查询/图谱邻居)按主体 principal_clearances 下推过滤,越级记录默认屏蔽且不泄漏存在性(fail-closed);manager 不受影响
    • 字段级敏感度 properties.sensitivity:越级字段对当前主体脱敏为 ***
    • 枚举写入校验:声明了 enum_values 的属性,越界值写入被拒(400 enum_violation,带友好提示);修复原校验变量遮蔽导致的"永不拦截" bug
    • 批量重算 POST /ontology/classification/recompute:生效分级 = max(属性分级, 来源文件分级),默认 dry_run,apply=true 才落库
    • KM 源文件级分级 POST /km/classification:整份文档打级,传导给已抽取实例(文件越敏→产物越敏)
  • MCP 工具 +3:get_classification_config、recompute_classification、set_km_classification(清单共 28 个)

变更

  • 分级路由由 /objects/classification/* 改为 /ontology/classification/*,避免与 /objects/:type/:pk 参数路由冲突被抢占匹配

文档

  • docs/INSTANCE_GOVERNANCE.md 新增 §15 恢复关系边、§16 数据分级
  • docs/TESTING.md 新增:测试分层(纯函数单测 / 集成测试)、跑测命令、编写新测试的约定

测试

  • 16 个测试用例全绿:
    • go test -short ./server/:11 个纯函数单测(levelIndex / maxLevel / materializeClassification / principalMaxIndex / deniedLevelsFor / resolveDisplayName / propString / diffProps / mergeProps / parseStringArray / similarity),约 0.7s
    • go test -tags=integration -timeout 90s ./server/:5 个集成测试(枚举校验 / 分级过滤 / 字段脱敏 / 删→恢复边 / recompute 落库),约 1.2s,需真实 PG
  • 集成测试的恢复边用例同时锁住了 issue #4 行为;分级过滤用例同时锁住了 issue #5-③④ 的 fail-closed 语义

[1.1.1] - 2026-09-05 问题反馈通道

新增

  • 公开反馈代理:POST /api/v1/feedback(公开、调用方零凭据)→ 服务端持专用 token 自动生成 Gitea issue。标题自动补 [bug]/[建议] 前缀,正文自动附版本号/commit/时间;每 IP 每小时限 10 条
  • Issue 反馈机制:CHANGELOG 头部说明 + Web 手工入口 + 提交约定;MCP manifest 新增 feedback 段(issues/api/convention/changelog_url)

变更

  • 反馈配置内嵌二进制:Gitea 地址/仓库/token 编译进 version.go(含外网地址),移除 .env 依赖与 GITEA_* 环境变量,部署零配置

[1.1.0] - 2026-09-05 实例治理

对标《本体改进需求》14 项按本库实情取舍落地,另落地 Palantir 两个机制。详细语义见 docs/INSTANCE_GOVERNANCE.md。

新增

  • 显示名物化:objects.name 按 object_types.title_property → name → title → real_name → display_name 回退链物化,启动时自动回填存量空 name(首次上线补 1235 个,修复 45% 实例默认检索隐身)
  • 批量写入:POST /api/v1/objects/batch、POST /api/v1/links/batch,单事务执行,逐条 ok/fail 明细
  • 变更审计:object_changes 表记录 create/update/delete 字段级 diff;GET /objects/:type/:pk/history 查历史,POST /objects/:type/:pk/restore 回滚
  • 去重提示:create_object 响应返回 possible_duplicates;GET /objects/duplicates?type=X 全类型相似度扫描
  • source_ts 乱序丢弃(Palantir Source Timestamp 语义):写入携带 source_ts 早于已有值时拒绝(单条 409 stale_write,批量该条 stale_skipped 不阻断整批);不传则不检查,完全向后兼容
  • 血统传播删除(Palantir Lineage-Aware Deletion 语义):DELETE /objects/:type/:pk 默认只删实例+边并回显 source_ref 与来源剩余实例数;?propagate=true 沿 source 清理该文档/连接抽取的全部实例、边、摄取记录
  • 查询过滤操作符:query filters 支持 ne / in / nin / contains / exists;支持 fields 裁剪返回字段
  • KM:km_list_files 支持 recursive=true 一次返回子树;文件级 excluded 标记;文件 ↔ 实体双向溯源(extracted_objects / objects.source)
  • MCP 工具扩至 25 个:新增 batch_create_objects / batch_create_links / delete_object / restore_object / get_object_history / find_duplicates / get_server_info
  • 版本自描述:GET /api/v1/version、GET /api/v1/version/changelog、MCP get_server_info、前端页脚版本号(本机制)

变更

  • create_object / update_object 默认 merge 语义:只更新传入字段,replace=true 才全量替换且响应回显被清掉的字段(removed)。此前全量覆盖一次不完整 upsert 会静默清空其余属性
  • 软删除走真实列:objects.deleted / objects.same_as;连接器侧默认排除墓碑(include_deleted=true 才包含),别名实例读取时自动跳转 canonical
  • search 多字段:默认按 name 列 + 属性全文检索
  • 边属性:create_link 支持 properties(如任职起止时间)与 source 溯源

[1.0.0] - 2026-08 初始发布

  • 6 元原语(Object / Property / Link / Action / Function / Interface)+ Principal / Marking / Grant / FieldPolicy 动态安全
  • 连接器 REST 只读查询 + MCP(/api/v1/mcp)6 个查询工具
  • 知识管理(目录/上传/Markdown 抽取入库)、AI 抽取(MiniMax 路由 + 启发式兜底)
  • Materialization 物化 + Backing Source 同步源 + Access Log 执行审计
  • Docker 单镜像(PostgreSQL 16 + ontology),EXTERNAL_PG 外部库模式