Clef 决策结果时好时坏，第一反应去调参数往往会把问题掩盖掉。决策链路通常可以拆成输入特征与约束、特征处理、候选评分排序、阈值过滤几段；任意一段的中间输出失真，最终选择都可能看起来像参数不灵。更稳妥的做法是先用同一批请求逐段打印中间输出，确认偏差发生在哪一段，再决定是否动参数。

适用场景：Clef 决策结果波动，但配置没有大改。操作动作：按输入、特征处理、评分、阈值四段打印中间输出，并和预期值对照。验证方式：固定同一批请求重放，比较每段实际输出与预期输出。风险边界：中间输出可能含敏感字段，日志需要脱敏并控制留存；若无法复现，先固定输入版本和随机种子。

在调用 Clef 前打印输入特征和约束条件

输入层是整条链路的起点。先确认传入 Clef 的特征向量没有缺失、类型错误或默认值误填，同时把约束字段一并记录下来。约束字段包括硬性限制、可选范围、业务规则开关等；这些字段一旦被静默覆盖，后面的评分再合理也可能选错。建议在调用 Clef 之前执行下面的通用骨架，把请求标识、特征名、输入向量和约束一起写入调试日志。

def log_clef_input(request_id, feature_names, input_vector, constraints):
    record = {
        'request_id': request_id,
        'feature_names': feature_names,
        'input_vector': list(input_vector),
        'constraints': dict(constraints),
    }
    # 替换为项目实际使用的日志组件或调试输出
    print('[clef-input]', record)
    return record

放置位置：在特征组装完成之后、调用 Clef 之前。替换项：feature_names 换成实际字段名，constraints 换成实际约束结构。验证方式：用一条已知应选 A 的样例运行，检查日志里特征数量、顺序、约束字段是否与预期一致；如果出现 None、空字符串或类型不一致，先修输入源，不要继续调决策参数。

在特征处理层检查归一化和分桶结果

特征尺度不一致是决策波动的常见来源。归一化、标准化或分桶之后，特征的分布和排序可能已经改变；如果只看原始输入，很容易误判。可以先打印处理前后的统计量，再打印分桶边界和每个桶的计数。下面是一段通用检查代码，按需替换统计函数。

def log_feature_stats(raw_values, processed_values, bucket_labels):
    def stats(values):
        n = len(values)
        if n == 0:
            return {'n': 0}
        mean = sum(values) / n
        var = sum((x - mean) ** 2 for x in values) / n
        return {
            'n': n,
            'min': min(values),
            'max': max(values),
            'mean': mean,
            'std': var ** 0.5,
        }
    print('[feature-raw]', stats(raw_values))
    print('[feature-processed]', stats(processed_values))
    print('[feature-buckets]', bucket_labels)

验证方式：如果使用 z-score，处理后的均值通常应接近 0、标准差接近 1；如果使用 min-max，处理后的范围通常应落在 0 到 1 之间。分桶结果要检查每个桶的样本数是否极端倾斜，以及桶边界是否硬编码后适配了旧数据。需要结合环境确认阈值；一旦发现某个特征处理前后排序变化很大，优先检查该特征的原始尺度、缺失值填充方式和分桶规则，而不是先去调决策阈值。

在决策层输出每个候选的评分和排序

最终只返回一个选择时，很难判断是评分本身有问题，还是排序或后处理有问题。建议在决策层把每个候选的评分、排序和关键特征打印出来。下面的伪代码展示如何记录评分列表，实际评分函数替换为 Clef 的评分调用或本地封装。

def log_candidate_scores(candidates, scorer):
    scored = []
    for item in candidates:
        score = scorer(item)
        scored.append({
            'id': item.get('id'),
            'score': score,
            'features': item.get('features'),
        })
    scored.sort(key=lambda x: x['score'], reverse=True)
    print('[clef-scores]', scored)
    return scored

对比预期的方式：取一批人工已知正确选择的样例，观察正确候选的评分是否稳定靠前；如果正确候选评分偏低，问题更可能在上游特征或评分权重；如果正确候选评分靠前但最终没被选中，继续看阈值过滤和后处理。不要只看 Top1，要把 TopN 和分数差距一起记录，分数差距过小往往说明特征区分度不足或归一化有问题。

在阈值应用后记录被过滤的选项和原因

阈值过滤是漏选的常见位置。只记录最终保留的选项不够，还要记录被过滤掉的是谁、分数是多少、因为哪条规则被过滤。下面的日志片段把保留项和丢弃项分开输出，便于回溯。

def apply_threshold(scored, min_score, max_candidates):
    kept = []
    dropped = []
    for item in scored:
        if item['score'] < min_score:
            dropped.append({
                'id': item['id'],
                'score': item['score'],
                'reason': 'below_min_score',
            })
        else:
            kept.append(item)
    kept = kept[:max_candidates]
    print('[threshold]', {
        'min_score': min_score,
        'max_candidates': max_candidates,
        'kept': kept,
        'dropped': dropped,
    })
    return kept

调整阈值的验证步骤：第一步，固定同一批输入和同一份特征处理结果；第二步，只把 min_score 下调一档，观察原先被过滤的候选是否进入 kept；第三步，检查进入后是否出现明显不合理的结果，比如违反硬约束或分数远低于其他候选；第四步，如果下调后结果改善，再判断是阈值过紧，还是上游评分尺度变了。注意不要只看最终输出，要同时对比 kept 和 dropped 两个列表，必要时回放日志确认过滤原因。

对照中间输出定位偏差来源，再决定是否调参

逐段检查之后，把每段输出、预期值、实际值和偏差原因填进同一张表，能避免在参数上反复试错。表格模板如下，实际使用时按 Clef 接入方式替换字段。

如果表格里只有最终输出异常，而输入、特征处理、评分和过滤都符合预期，才需要把注意力放到参数本身。调整参数时建议一次只动一个，并用同一批请求重放验证。若某一段中间输出本身无法解释，先不要调参，优先补充该段的日志和输入校验；否则调参只是在掩盖链路问题。