Documentation
¶
Overview ¶
采样聚簇：best-of-N 确定性聚合原语。
同一任务对同一输入跑 N 次（best-of-N），「多份采样相互复现」是确定性的 可信度信号——按调用方提供的签名通道与等价判定把 N 份输出聚簇计数， 不引入任何模型判断（与「裁决不走 LLM」的确定性纪律兼容）。
典型用法：审查/生成类 agent 对高危输入 opt-in N 采样，聚簇后 Count≥2 的 簇升级呈现权重、孤立单现的低权重条目标注降权提示；全部簇保留（漏报防线）。 Fingerprint/NormalizeComment 提供「file+规范化文本」精确指纹通道的 canonical 实现（v0.10.9 自 severity 迁入——指纹是聚簇签名的自然组成部分）。
模式级学习环的确定性数学与键派生（收编自 argus internal/learning，v0.10.32）： BetaConfidence 与 WilsonCI/McNemarExact 同族——评审反馈回路的小样本统计原语； PatternKey/NormalizePatternText 是「同一类问题聚成同一模式」的键语义单源。 纯函数、零依赖、可离线复算；禁止 LLM 摘要参与键派生（不可对账）。
Package reportutil 评审/评测报告后处理原语（沉淀自 heimdallr 报告层与 bianque 评审流水线），一个包覆盖同一条消费链的三段：
- 严重度归一（severity.go）：high/medium/low 词表 + 外部审查专家常用 别名（P0/fatal/nit…）折叠——「严重级别是什么、多严重」；
- 采样聚簇（cluster.go）：best-of-N 输出按签名通道聚簇计数（含 file+规范化文本精确指纹），「哪些发现被独立复现」；
- 对比统计（stats.go）：小样本通过率 Wilson 区间 + 配对 McNemar 精确 检验——「两个版本的差异是否显著」。
三段原为 severity/sampling/stats 三包，消费者画像相同且边界已漂移过一轮 （v0.10.9 severity→sampling 指纹迁移），v0.10.11 合并为单包。零外部依赖。
对比统计：小样本通过率的诚实区间估计与配对二分类差异检验。 显著水平对应的 z 由调用方传入（如 1.96）。实现已下沉 oekit/pkg/mathx （ekit v0.33.0 首下沉、agentkit v0.10.41 起单源在彼；ekit 单体冻结后随 oekit 拆分仓继续单源）；本文件保留公开面薄委托。
Index ¶
- Constants
- func BetaConfidence(posted, regret, suppress, restore int) float64
- func Fingerprint(file, comment string) string
- func Higher(a, b string) string
- func McNemarExact(n01, n10 int) float64
- func Normalize(s string) (string, bool)
- func NormalizeComment(s string) string
- func NormalizePatternText(comment string) string
- func PatternKey(pluginName, comment string) string
- func PatternSample(comment string) string
- func PatternSamples(posted, regret, suppress int) int
- func Rank(s string) int
- func Valid(s string) bool
- func WilsonCI(passed, total int, z float64) (lo, hi float64)
- type Group
Constants ¶
const ( High = "high" Medium = "medium" Low = "low" )
严重级别词表。
const PatternTextMax = 160
PatternTextMax 模式键/人读样本的文本截断上限（rune）。
Variables ¶
This section is empty.
Functions ¶
func BetaConfidence ¶
BetaConfidence 由 posted/regret/suppress/restore 计数推 Beta 后验置信度。 先验 (α=2, β=2) → 0.5；Posted α+1；Regret β+2；Suppress β+3； Restore 只回抬 β（max(β-2,1)），不加 α——此前 Restore α+2 会让 suppress+restore 成对循环净抬置信度（α+2, β+1），API 持有者可循环洗白； 现在 restore 仅撤销部分负证据，成对循环净 β+1（置信度微降），无法洗白。 samples=Posted+Regret+Suppress（PatternSamples），读时计算不落列。
func Fingerprint ¶
Fingerprint 精确指纹：规范化评论文本哈希 + file（SHA256 前 16 字节 hex）。 行号不入指纹；同一指纹跨轮次即「同一问题」。常用作 Aggregate 的签名通道。
func McNemarExact ¶
McNemarExact McNemar 精确检验（双侧）：n01=甲败乙过数，n10=甲过乙败数。
func NormalizeComment ¶
NormalizeComment 规范化：全小写、去所有空白与标点/符号差异。
func NormalizePatternText ¶
NormalizePatternText 规范化评论文本用于模式键： 小写 → 剥路径/十六进制/反引号标识符/纯数字 → 折叠空白 → 截断。 反引号/路径/十六进制/数字先剥，避免 "错误处理不佳 in `handler.go:12`" 与 "错误处理不佳 in `service.go:99`" 落成不同模式。
func PatternKey ¶
PatternKey 派生仓库级模式键：sha256(plugin \x00 normalize(comment)) 前 16 hex。 plugin 为空时用 "unknown"——缺插件归属的键仍可计算，但不应静默混入其他插件历史。 键不含 file/line——同一类问题在不同文件聚成同一模式；含 plugin 分量—— 不同审查来源的信任历史不混用。
func PatternSample ¶
PatternSample 返回入库的人读样本（规范化后截断），便于审计与提示词注入展示。
func PatternSamples ¶
PatternSamples 参与消费判定的样本量（小样本不消费，防抖动）。
Types ¶
type Group ¶
type Group[T any] struct { // Representative 首见条目（稳定性依赖输入有序——按采样序传入）。 Representative T // Items 命中本簇的全部条目（含 Representative，按首见序）。 Items []T // Signature 首见条目的签名通道集（可观测/对账用；归属判定以 eq 为准）。 Signature []string // Count = len(Items)（冗余字段，便于不取 Items 的调用方）。 Count int }
Group 一簇相互等价的采样结果。
Source Files