SpyGlass 版本不兼容：version mismatch 速查
更新时间：2026-10-23。FAQ 速查页，属于 EDA 工具排错系列。SpyGlass 的版本不兼容表现很杂：有时是 sg_shell 起不来，有时是读工程到一半报数据库格式错，更多时候是升级之后 waiver 文件里一大片
unknown rule——本质是「产物（编译缓存、waiver、约束、license）的版本与工具的理解版本错位」。同类思路见 PrimeTime 版本不兼容；waiver 之外的语法类报错见 SpyGlass 语法解析错误，缓存陈旧问题见 SpyGlass 编译缓存陈旧。
本文要回答的问题
- 升级 SpyGlass 后读旧工程报 incompatible database version，缓存还能留吗？
- waiver 文件（.awl）升级后大量报 unknown rule，是文件坏了还是规则没了？
- sgdc 约束文件写法随版本变化，怎么判断是老写法被弃用？
- 团队里有人用新版有人用旧版，产物互相读不了怎么收敛？
- license checkout 报 feature 版本不够，是工具装错了还是 license 没续？
一、报错原文与现象
Error: Incompatible database version: design was compiled by SpyGlass 2023.12, current version is 2025.06. (DB-XXX)
Error: Cannot load pre-compiled library 'work.lib': format version mismatch.
Warning: Unknown rule 'STARC05-2.1.4a' in waiver file 'block.awl'; waiver ignored. (WVR-XXX)
Error: SGDC constraint 'clock -name' is deprecated in this version; use 'clock -tag'. (SGDC-XXX)
Error: License feature 'spyglass_lint' version 2024.03 is older than required 2025.06. (-5,412)五种形态对应五条线：编译缓存/内部数据库版本、waiver 规则名变迁、sgdc 约束语法变迁、团队版本不统一、license feature 版本日期。先把报错里的两个版本号（产物是谁编的、当前工具是谁）抄下来对齐，大多数版本问题在这一步已经定位了一半。
二、可能原因总览
| 报错现象 | 可能原因 | 处置 |
|---|---|---|
| incompatible database version | 新 sg_shell 读旧版编译缓存 | 删缓存目录全量重编 |
| pre-compiled library 拒读 | 预编译库由另一版本生成 | 用当前版本重新 elaborate |
| waiver unknown rule 暴涨 | 新版改名/删除了规则 | 对照 release note 升级 .awl |
| sgdc deprecated 报错 | 约束写法随版本变更 | 按新版手册改写 sgdc |
| 同工程两人结果不同 | PATH/module 指向不同版本 | 统一版本入口脚本 |
| license -5 版本不足 | license feature 日期早于工具 | 续期 license 或回退工具 |
| 升级后 waiver 静默失效 | 规则改名且只给 Warning | 审计 waiver 命中率 |
| 旧版本读新版产物 | 版本只向后兼容不向前 | 全组对齐到同一版本 |
三、逐条排查展开
编译缓存与内部数据库版本是最高频的一条。 SpyGlass 编译设计时会生成内部数据库与缓存（默认在工程目录下的 spyglass_work 或类似工作目录），格式随版本演进，新版工具对旧格式只给有限兼容，经常直接拒读。处置永远是一句话：清掉工作目录与缓存、用当前版本全量重编。不要试图抢救旧缓存——分钟级的编译省时，和缓存错配带来的天级定位相比不值一提。判据细节可对照 SpyGlass 编译缓存陈旧 里的缓存目录清单。
waiver 的 unknown rule 是升级后最吵的一类。 SpyGlass 的规则集（尤其 STARC、GuideWare 系列）在新版本里会改名、合并或删除，旧 .awl 文件里被改名的规则名会逐条报 Warning 并被忽略——注意是 Warning 不是 Error，lint 照样跑完，但原本被 waive 的违规会成批冒出来，看起来像「升级后质量突然变差」。处置：拿新旧两版的 release note 里的 rule rename/deprecate 清单，批量替换 .awl 里的规则名；替换完跑一次「waiver 命中率审计」（看有多少 waiver 实际命中），命中率为零的 waiver 就是没对上的。
sgdc 约束写法随版本变化要查手册，不要猜。 sgdc（SpyGlass Design Constraints）的关键字与参数格式在版本间会调整，老写法先降级为 deprecated warning、再若干版本后变成硬错误。识别特征：同一 sgdc 文件在旧版干净、新版报错或警告，且报错行都是约束关键字而不是设计内容。处置：对照新版 sgdc 手册逐条改写，改完在版本库里注明「本 sgdc 适用工具版本」，避免下一个人拿旧版再踩一遍。约束解析失败的通用排查见 SpyGlass 配置解析失败。
团队版本不统一是「别人能跑我不能」的隐身形态。 多人共用的工程里，A 用新版编译的缓存 B 用旧版读、B 写的 sgdc 用了新语法 A 不认——版本只保证向后兼容（新读旧有限度），从不保证向前兼容（旧读新）。收敛方法不是口头约定，而是统一版本入口：所有人 source 同一个 env 脚本或用 module 系统锁定版本，sg_shell -version 写进每个 run 目录的 log 头，出问题先查这条记录。
版本切换期的「半新半旧」是最危险窗口。 升级不是瞬间完成的：旧版流程还在收尾、新版工程刚起步，这段时间最容易出现「新工具读旧缓存、旧脚本喂新工具」的交叉错配。纪律是切换期内每个 run 目录显式记录所用版本（sg_shell -version 输出写进 log 头），切换期结束的标志是「缓存清零重建 + waiver 迁移审计通过 + 回归基线重建」，三件事不齐就不算切完。
license 版本日期是「全组同时挂」的版本问题。 工具 release 版本号高于 license 文件里 feature 的版本日期时，FlexLM 报 -5 取不到令牌，全员同时失败、回退旧版立刻可用。处置：升级评审 checklist 固定一条「目标工具 release 日期 ≤ license feature 版本日期」，不满足先找管理员续期再升级。详细分支见 SpyGlass license checkout fail。
版本不兼容报错 -> 错位对象分线
错位对象分线 -> 缓存数据库: 清工作目录全量重编
错位对象分线 -> waiver规则: 对照release note替换规则名
错位对象分线 -> sgdc约束: 按新版手册改写语法
错位对象分线 -> 团队版本: 统一入口脚本对齐sg_shell版本
错位对象分线 -> license日期: 核对feature版本日期
缓存数据库 -> 修复: 当前版本重编并验证
waiver规则 -> 修复: awl批量更新并审计命中率
sgdc约束 -> 修复: 改写并标注适用版本
团队版本 -> 修复: 全员锁定同一版本
license日期 -> 修复: 续期license或回退工具
修复: 当前版本重编并验证 -> 版本矩阵建档防复发
修复: awl批量更新并审计命中率 -> 版本矩阵建档防复发
修复: 改写并标注适用版本 -> 版本矩阵建档防复发
修复: 全员锁定同一版本 -> 版本矩阵建档防复发
修复: 续期license或回退工具 -> 版本矩阵建档防复发
版本不兼容报错.style: { fill: "#FDECEC"; stroke: "#D9534F" }
错位对象分线.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
缓存数据库.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
waiver规则.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
sgdc约束.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
团队版本.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
license日期.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
修复: 当前版本重编并验证.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
修复: awl批量更新并审计命中率.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
修复: 改写并标注适用版本.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
修复: 全员锁定同一版本.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
修复: 续期license或回退工具.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
版本矩阵建档防复发.style: { fill: "#F1ECFD"; stroke: "#7A5BD4" }颜色按语义分角色：红是报错入口，蓝是排查动作，橙是修复，紫是收尾防复发。主线是「先按错位对象分五条线：缓存数据库 / waiver 规则 / sgdc 约束 / 团队版本 / license 日期」——缓存一律清掉重编，waiver 对照 release note 批量换名并审计命中率，sgdc 按新版手册改写，团队靠入口脚本锁版本，license 核对日期后找管理员；五条线共用出口：把版本矩阵建成档案。
四、预防与纪律
- 版本矩阵集中建档：SpyGlass 版本、规则集版本、license feature 日期一张表，升级动任何一个先查表。
- 缓存目录带版本号：工作目录按版本隔离（如
spyglass_work/2025.06/），切版本自动隔离，杜绝新旧混读。 - waiver 随版本一起升级：把 .awl 升级写进升级流程，升级后强制跑一次 waiver 命中率审计，命中率为零的逐条对照 rename 清单。
- sgdc 标注适用版本：文件头注释写明「本文件适用 SpyGlass 版本」，换人换版本一眼可查。
- 升级评审双闸门：license 日期够 + waiver/sgdc 迁移清单完成，两条都过才允许切换。
这一篇在知识体系里的位置
本篇是 EDA 排错速查簇中「版本兼容」节点的 SpyGlass FAQ 页，与 PrimeTime 版本不兼容 同族；license 分支细节见 SpyGlass license checkout fail，缓存目录细节见 SpyGlass 编译缓存陈旧，约束解析报错见 SpyGlass 配置解析失败 与 SpyGlass 语法解析错误。
一句话总结
SpyGlass 版本不兼容先按错位对象分五条线：编译缓存与内部数据库报错就清工作目录全量重编，waiver 报 unknown rule 就对照 release note 的 rename 清单批量替换并审计命中率，sgdc 报错就按新版手册改写并标注适用版本，团队产物互读不了就用入口脚本统一 sg_shell -version，license -5 就核对 feature 版本日期后续期或回退；最后靠「版本矩阵建档 + 缓存目录带版本号 + waiver 随版本迁移 + 升级评审双闸门」把版本问题挡在升级之前。