15 KiB
更新说明(CHANGELOG)
本文件随二进制一起编译打包(//go:embed),运行时通过 GET /api/v1/version/changelog、MCP 工具 get_server_info 或前端页脚可见。
格式遵循 Keep a Changelog,版本号采用语义化版本。
问题反馈(Issue 机制)
AI 客户端在使用本平台过程中发现 bug 或有改进建议,请提交 Issue,不要只在会话里提及(会话结束即丢失):
- 自动提交(推荐):
POST /api/v1/feedback(公开,无需任何 token)kind 取{"title":"xxx 失败","body":"复现步骤/期望/实际","kind":"bug"}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升级为dbRunnerinterface(中间件可换*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的属性,越界值写入被拒(400enum_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.7sgo 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 清理该文档/连接抽取的全部实例、边、摄取记录 - 查询过滤操作符:
queryfilters 支持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、MCPget_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 外部库模式