docs/architecture/structured-compare-and-evaluation-rewrite.md
本设计解决两个架构问题：
SPO 的前提下支持更强的结构化判断最终目标是形成三层架构：
本文同时描述“已经落地的当前实现”和“目标态架构”。
截至 2026-03-20，当前已落地：
CompareAnalysisHints.modeCompareAnalysisHints.snapshotRolesStructured Compare = pairwise judge + synthesismetadata.compareModemetadata.snapshotRolesmetadata.compareJudgementsmetadata.compareStopSignalsmetadata.compareInsights
pairHighlightsevidenceHighlightslearnableSignalsoverfitWarningsprogressSummary / referenceGapSummary / promptChangeSummary / stabilitySummaryconflictSignalsRewrite From Evaluation 的增强通用能力：
summary / improvements / patchPlan / compareInsights / compareStopSignals / conflictSignalsworkspace 槽位时必须显式选择 targettarget 后自动补全其余角色baseline / reference / referenceBaseline，其余多余候选降级为 auxiliarypromptRef kind/version、modelKey 与 non-workspace 槽位的 prompt 文本签名workspace 槽位的 prompt 文本变化不会直接清空手工角色，而是进入“待复核”状态structured 还是 generictarget / baseline / reference / referenceBaseline 这类会导致 structured compare 歧义的配置当前未落地：
Rewrite From Evaluation 协议与独立模板flowchart TD
A["测试执行层\nrun variants / collect snapshots"] --> B["评估协议层\nsummary / improvements / patchPlan / score"]
B --> C["评估增强能力层\nGeneric Compare\nStructured Compare\nRewrite From Evaluation"]
C --> D["SPO 编排层\nauto preset\none round loop\nmulti-round loop"]
关键原则：
SPO 不能直接发明新的 compare 协议Structured Compare 属于 compare evaluation 的增强模式Rewrite From Evaluation 属于通用重写能力，不应只服务于自动优化现有 compare evaluation 输出协议已经稳定：
summaryimprovementspatchPlanscore因此本期不建议改动最终外部返回结构，而是优先增强 compare 的内部生成方式。
输入特征：
snapshots当前执行方式：
适用：
输入特征：
target执行方式：
适用：
补充说明：
compareMode / snapshotRoles / compareJudgements / compareStopSignals / compareInsights建议在 compare 输入 hints 中扩展出一组中性角色，而不是硬编码 reference 这类业务词：
targetbaselinereferencereferenceBaselinereplicaauxiliary当前 CompareAnalysisHints 已经扩展为：
interface StructuredCompareHints {
mode?: 'generic' | 'structured'
snapshotRoles?: Record<
string,
'target' | 'baseline' | 'reference' | 'referenceBaseline' | 'replica' | 'auxiliary'
>
}
当前实现策略：
mode 或 snapshotRoles 时，走 genericstructuredtarget，并且至少有 baseline / reference / replica 之一workspace 槽位，可自动视为 targetworkspace 槽位，必须由用户显式指定 targettarget 确定后，自动推断只会收敛出单一 baseline / reference / referenceBaselineauxiliary目标态建议仍然是：
这样可以避免 compare evaluation 直接依赖 SPO 配置对象。
Structured Compare 内部应根据角色生成 judge plan，而不是固定写死 A/B/C/D。
target vs baselinetarget vs referencereference vs referenceBaselinetarget vs replicaauxiliary 只进入 synthesis，不进入核心 blind judgereference vs replica 目前仍属于潜在扩展项，当前实现尚未纳入 judge plan新增通用能力：
这个能力应可服务于：
该能力应负责：
该能力不负责：
这些仍属于 SPO 编排层。
为了支持 SPO 等自动化上层，而不把停止判断重新塞回 SPO，建议 compare evaluation 在内部增强中补充一组机器可读的 stop signals。
建议形式：
interface CompareStopSignals {
targetVsBaseline: 'improved' | 'flat' | 'regressed'
targetVsReferenceGap: 'none' | 'minor' | 'major'
improvementHeadroom: 'none' | 'low' | 'medium' | 'high'
overfitRisk: 'low' | 'medium' | 'high'
stopRecommendation: 'continue' | 'stop' | 'review'
stopReasons: string[]
}
这组结构的作用是：
SPO 可以直接消费 compare judgement 与 stop signalsSPO 专属 judge LLM 调用同时当前实现还补充了一组 compareInsights.conflictSignals：
type CompareConflictSignal =
| 'improvementNotSupportedOnReference'
| 'improvementUnstableAcrossReplicas'
| 'regressionOutweighsCosmeticGains'
| 'sampleOverfitRiskVisible'
这组结构的作用是：
职责：
structured 还是 generic输出：
该配置应存放在测试区 session 中，而不是 SPO 专属状态中。
结果面板建议统一支持三类动作：
立即替换迭代优化智能重写其中：
立即替换 对应 patchPlan迭代优化 对应单条 improvement智能重写 对应整份 evaluation resultSPO 只应负责：
SPO 不应负责：
metadata.compareStopSignals状态：已完成
metadata.compareJudgements状态：已完成
Rewrite From Evaluation状态：部分完成
workspace 槽位时必须显式选择 target 已落地target 后自动补全其余角色已落地baseline / reference / referenceBaseline 已落地，剩余候选会降级为 auxiliarypromptRef kind/version + modelKey 变化时，手工角色失效保护已落地non-workspace 槽位的 prompt 文本变化级别失效保护已落地workspace 槽位的 prompt 变化复核机制已落地：
conflictSignals 与结果面板中的 conflict checks 已落地Rewrite From Evaluation 已有最小实现：
compareStopSignals + compareInsights + conflictSignalsSPO 按钮 / 配置弹窗 / 运行卡 / 结果卡 / 抽屉SPO 预置 structured compare架构上最合理的方向是：
Generic + Structured这样可以最大化复用 compare 与 rewrite 能力，同时将自动优化逻辑控制在最薄的一层。