FAQ

安装 / Installation

Q: 为什么 pip 安装时不需要编译器？
C 扩展只是可选的加速器。当 C 扩展不可用或编译失败时，cfgdrift 自动降级到纯 Python 解析器，功能完全一致。Dual-wheel model：CPython 3.13 用户拿到加速 wheel，其他版本拿到纯 wheel。

Q: CFGDRIFT_BACKEND=pure 和默认 auto 有什么区别？
auto 有 C 用 C、无 C 静默降级；pure 强制纯模式；c 强制 C，无 C 时 import 抛 RuntimeError。

告警 / Alerting

Q: 为什么没有收到告警？
先 cfgdrift alert list 确认规则存在；再检查 daemon 是否在跑（cfgdrift daemon status）；最后看防抖冷却（600s）与告警阈值。失败重试是规则级配置的（--retry-count / --retry-delay）。

插件 / Plugins

Q: --format mydsl 报未注册错误怎么办？
错误消息会附带注册指引。两种方式：pip 安装带 [project.entry-points."cfgdrift.parsers"] 的包（方式 B），或在进程内 import 触发 register_plugin（方式 A）。同名冲突时 entry point 优先于装饰器。

无 git 降级 / No-git degradation

Q: 配置目录没有 .git，hint 的「溯源」会怎样？
修复建议的溯源（provenance）会自动静默降级为基线信息（baseline 名 + 版本 + created_at），不影响 diff / scan / 告警流程。

零噪音契约 / Zero-noise contract

Q: 升级版本后输出变了怎么办？
设计上所有新增输出（约束违反、hint 等）默认关闭或只对真实漂移出现。需要严格回退时用 --no-hint 可得到与 v0.12.0 逐字节一致的输出。

数据与目录 / Data & directories

Q: 数据存在哪里？如何隔离演示环境？
默认 ~/.cfgdrift/（SQLite + 策略文件）。演示或 CI 用 CFGDRIFT_HOME=/tmp/xxx 或全局 --store PATH 完全隔离。

FAQ