v0.8.0¶

本次 minor release 引入低占比特殊值治理（SV Bin Governance）：两组正交开关，用于治理特殊值（special value，下称 SV）箱的 WOE 估计。0.7.2 及之前，两个 WOE 引擎对每个 SV 无条件赋予经验 WOE 并计入总 IV，而 min_bin_size / small_bin_policy 只治理普通区间箱，对 SV 箱完全不生效——占比 0.05% 的 -1 与占比 8% 的 NULL 得到同等信任，导致方差极大、IV 虚高、上线后 PSI 漂移。

四个新参数的默认值组合严格等于旧行为，与 0.7.2 逐位一致；没有移除公开 API，也没有翻转任何默认值。

新增参数¶

参数	类型 / 默认	取值	语义
`sv_min_bin_size`	`float = 0.0`	`[0.0, 1.0)`	SV 箱占全量样本的占比阈值；`0.0` 关闭
`sv_small_policy`	`str = "keep"`	`keep` / `neutral` / `merge_missing`	亚阈值 SV 箱的兜底策略
`sv_woe_smoothing`	`str = "none"`	`none` / `laplace`	是否把 SV 箱 WOE 向全局 base rate 收缩
`sv_smoothing_alpha`	`float = 0.0`	`>= 0.0`	平滑强度 α；`0.0` 关闭

四个参数在两个引擎上同名同义、口径一致：MonotoneWOEBinner.__init__() 是构造器参数，WOE_Master.fit() / update_woe() 是方法参数。非法取值在入口即抛 ValueError，风格与 G08 small_bin_policy 一致。

方式1 —— 低占比兜底¶

占比按 prop = n_bin / N_total 计算（分母不加 eps），判定用严格小于；占比恰好等于阈值不触发。

keep（默认）取经验 WOE，零行为变更。
neutral 把亚阈值 SV 箱的 woe 与 iv 置 0.0。
merge_missing 把亚阈值 SV 箱的 bad / good 计数并入 [Missing] 箱，[Missing] 随后按经验公式重算；被合并行存表的 woe 改写为 [Missing] 重算后的 WOE，iv 置 0 避免重复计入总 IV。特征没有 [Missing] 箱时降级为 neutral 并 warnings.warn(UserWarning)。

采用 rewrite-stored-WOE 方案，因此两个引擎的 transform 路径都没有任何改动：apply_woe() / mapping_woe() 照常按 bin_label → WOE 查表即命中正确值，fit→transform 往返自动一致。实际处置写入结果表的 sv_policy_applied 列（keep / neutral / neutral(fallback) / merged_into_missing / merge_target）。

方式2 —— SV WOE 平滑¶

sv_woe_smoothing="laplace" 采用坏率收缩（bad-rate shrinkage），仅作用于 SV 箱，普通区间箱不动：

p = N_bad / (N_bad + N_good)
n_bin = n_bad + n_good

r = (n_bad + alpha * p) / (n_bin + alpha)

pct_bad_smoothed  = n_bin * r       / N_bad
pct_good_smoothed = n_bin * (1 - r) / N_good

woe = ln(pct_bad_smoothed / pct_good_smoothed)

alpha = 0 逐位还原旧经验 WOE（回归护栏）。
alpha → ∞ 时 r → p，WOE 单调收缩到 0。
α 与 n_bin 竞争，样本越少的箱收缩越强。

采用该形式而非"人口分母伪计数"（(n_bad + alpha*p) / (N_bad + alpha)）的原因是：后者 alpha → ∞ 时收敛到 logit(p) ≠ 0 且不单调，加大平滑强度反而可能推高 |WOE|。

正交组合语义¶

方式1 优先：亚阈值箱走兜底后不再平滑；方式2 只作用于占比达标、保留经验 WOE 的 SV 箱。两个开关可独立启用也可叠加。

merge_missing + laplace 同开时，合并目标 [Missing] 箱按经验公式重算（不平滑），使合并后的桶反映真实 post-merge 坏率；其他占比达标的 SV 箱仍照常平滑。

[Missing]（NaN）箱在两个引擎里都是正常的受治理 SV 箱——达标就平滑、亚阈值就置零；唯一特殊之处是在 merge_missing 下只能当合并目标、不能当合并来源。该能力与 missing_bin_strategy 正交：后者只治理 NaN 缺失箱语义，前者治理所有 SV 箱（含 -1 这类非 NaN 哨兵）。

Pipeline 层暴露¶

CreditModelPipelineConfig 与 FeatureValidationPipelineConfig 的 woe_params、monotone_woe_params 两个默认字典都显式带上了四个 sv_* 键（值 = 旧行为），使其成为可发现、可文档化、可快照的一等参数，而不是"碰巧能塞进去的 dict key"。
四个 sv_* 已加入 FeatureValidationPipeline._MONOTONE_INIT_KEYS 与 Feature_Screen._MONOTONE_INIT_KEYS 白名单。这两处不在白名单里的 key 会被静默丢弃（不报错、不告警），漏改会让 FVP 与筛选期的 SV 治理静默失效、并造成筛选 IV 与建模 WOE 口径分裂。今后给 MonotoneWOEBinner.__init__ 新增参数必须同步这两份名单。
sv_* 属于构造器参数，未加入 _MONOTONE_FIT_KEYS（{chi2_binning, chi2_p, chi2_init_size, n_jobs}）；CM 侧 monotone 的 fit-only pop 名单同样保持不含 sv_*，否则会被当成 fit() kwarg 传下去而抛 TypeError。
FVP config_snapshot 原样 dump 两个字典，sv_* 自动进快照，便于复现"某个模型用了什么 SV 治理口径"。

向后兼容¶

全默认参数下，两个引擎的 WOE / IV 与 0.7.2 基线逐位一致。
laplace + alpha=0 数值上等价旧经验 WOE。
transform 侧无任何改动，既有 mapping table / Format-A 分箱产物继续可用。