oh-my-knowledge 0.45.0 → 0.46.0

package/dist/doctor/health/composer.js

@@ -18,6 +18,8 @@ import { createExecutor } from '../../executors/index.js';
 import { getRegisteredHealthDimensions } from './dimension-registry.js';
 import { buildHealthPrompt } from './prompt-builder.js';
 import { deriveOverallHealth, extractJson, parseHealthOutput } from './parser.js';
+import { enumerateFindingsForMerge, mergeHealthSamples, mergeHealthSamplesLlm, parseMergeClusters, } from './consensus.js';
+import { buildHealthMergePrompt } from '../../shared/llm-prompts/skill-health-merge.js';
 export const SKILL_HEALTH_COMPOSER_ID = 'skill_health';
 const defaultExecutorFactory = createExecutor;
 // ---------------------------------------------------------------------------
@@ -125,6 +127,24 @@ function listSiblingSkills(skillRoot) {
         .sort();
 }
 // ---------------------------------------------------------------------------
+// 有界并发 map
+// ---------------------------------------------------------------------------
+/** 最多 limit 个任务并发,返回与 items 同序的结果(worker-pool,对齐 eval-core 口径)。 */
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next;
+            next += 1;
+            results[i] = await fn(items[i], i);
+        }
+    };
+    const workers = Math.max(1, Math.min(Number.isFinite(limit) ? limit : 1, items.length));
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    return results;
+}
+// ---------------------------------------------------------------------------
 // Composer factory
 // ---------------------------------------------------------------------------
 export function makeSkillHealthComposer(execFactory = defaultExecutorFactory) {
@@ -139,7 +159,7 @@ export function makeSkillHealthComposer(execFactory = defaultExecutorFactory) {
 async function composerCheckAll(ctx, execFactory) {
     const dims = getRegisteredHealthDimensions();
     // Programmatic opt-out: runHealthCheck=false → 给 summary 一条 skipped,
-    // 各维度不展开避免污染报告。CLI 的 --static-only 会直接过滤掉 composer rule。
+    // 各维度不展开避免污染报告。eval preflight 走这条(只跑静态 rule,不触发 LLM)。
     if (!ctx.runHealthCheck) {
         return [{
                 subId: '_summary',
@@ -176,44 +196,124 @@ async function composerCheckAll(ctx, execFactory) {
     const siblingSkills = listSiblingSkills(skillRoot);
     const prompt = buildHealthPrompt({ skillName, skillContent: content, skillRoot, subFiles, siblingSkills }, dims);
     const executor = execFactory(ctx.executorName);
-    let res;
-    try {
-        res = await executor({
-            model: ctx.model,
-            prompt,
-            cwd: skillRoot ?? ctx.cwd,
-            skillDir: skillRoot ?? null,
-            timeoutMs: ctx.timeoutMs,
-            effort: ctx.effort ?? 'medium',
-            lean: true,
-        });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return [errorSummaryOutcome(ctx, 'executor', msg)];
-    }
-    if (!res.ok) {
-        return [errorSummaryOutcome(ctx, 'executor', res.error ?? 'unknown')];
-    }
-    if (!res.output || res.output.trim().length === 0) {
-        return [errorSummaryOutcome(ctx, 'empty_output', '')];
+    // 采样次数(self-consistency):默认 1;非有限值(NaN/Infinity)兜底 1;上限 10 防 fat-finger
+    // / 资源耗尽(并发默认=采样数,会一起放大)。
+    const MAX_HEALTH_SAMPLES = 10;
+    const rawSamples = ctx.healthSamples;
+    const requested = Math.min(MAX_HEALTH_SAMPLES, Math.max(1, Math.floor(Number.isFinite(rawSamples) ? rawSamples : 1)));
+    // 跨采样累计的执行指标(token / cost / 时长 / 轮次都求和,反映真实总开销)。
+    const agg = {
+        durationMs: 0, durationApiMs: 0,
+        inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0,
+        costUSD: 0, numTurns: 0, fullNumTurns: 0,
+    };
+    const accumulate = (r) => {
+        agg.durationMs += r.durationMs ?? 0;
+        agg.durationApiMs += r.durationApiMs ?? 0;
+        agg.inputTokens += r.inputTokens ?? 0;
+        agg.outputTokens += r.outputTokens ?? 0;
+        agg.cacheReadTokens += r.cacheReadTokens ?? 0;
+        agg.cacheCreationTokens += r.cacheCreationTokens ?? 0;
+        agg.costUSD += r.costUSD ?? 0;
+        agg.numTurns += r.numTurns ?? 0;
+        agg.fullNumTurns += r.fullNumTurns ?? 0;
+    };
+    // 采样并发:默认全并行(并发=采样数,样本间相互独立),`--concurrency 1` 退回串行。
+    // 非有限值兜底为 requested。
+    const rawConc = ctx.healthConcurrency;
+    const concurrency = Math.max(1, Math.min(requested, Math.floor(Number.isFinite(rawConc) ? rawConc : requested)));
+    const runSample = async () => {
+        let res;
+        try {
+            res = await executor({
+                model: ctx.model,
+                prompt,
+                cwd: skillRoot ?? ctx.cwd,
+                skillDir: skillRoot ?? null,
+                timeoutMs: ctx.timeoutMs,
+                effort: ctx.effort ?? 'low',
+                lean: true,
+            });
+        }
+        catch (err) {
+            return { error: { phase: 'executor', msg: err instanceof Error ? err.message : String(err) } };
+        }
+        if (!res.ok)
+            return { res, error: { phase: 'executor', msg: res.error ?? 'unknown' } };
+        if (!res.output || res.output.trim().length === 0)
+            return { res, error: { phase: 'empty_output', msg: '' } };
+        const cleaned = extractJson(res.output);
+        if (cleaned === null)
+            return { res, error: { phase: 'extract', msg: '', extra: { rawOutput: res.output.slice(0, 4000) } } };
+        const pr = parseHealthOutput(cleaned, dims);
+        // 全维度 _missing → 该样本的 JSON 里 dim_id 缺失或写错,丢弃(不当作"全部通过")。
+        if ([...pr.byDimId.values()].every((r) => r._missing)) {
+            return { res, error: { phase: 'extract', msg: 'LLM output missing all dimension IDs', extra: { rawSample: cleaned.slice(0, 3000) } } };
+        }
+        return { res, parsed: pr };
+    };
+    // 跑 N 次(并发受 concurrency 限),收集成功解析的样本。单样本报错 / 空输出 / JSON 抽不出 /
+    // 全维度漏报都跳过(记最后一次错误);只要 ≥1 成功就走并集合并,全失败才报 fail。
+    const sampleResults = await mapWithConcurrency(Array.from({ length: requested }, (_, i) => i), concurrency, () => runSample());
+    const parsed = [];
+    let lastError = null;
+    for (const sr of sampleResults) {
+        if (sr.res)
+            accumulate(sr.res);
+        if (sr.parsed)
+            parsed.push(sr.parsed);
+        else if (sr.error)
+            lastError = sr.error;
     }
-    const cleaned = extractJson(res.output);
-    if (cleaned === null) {
-        return [errorSummaryOutcome(ctx, 'extract', '', { rawOutput: res.output.slice(0, 4000) })];
+    if (parsed.length === 0) {
+        return [errorSummaryOutcome(ctx, lastError?.phase ?? 'extract', lastError?.msg ?? '', lastError?.extra ?? {})];
     }
-    const parseResult = parseHealthOutput(cleaned, dims);
-    const overall = parseResult.overall ?? deriveOverallHealth(parseResult.byDimId);
-    // 诊断:如果所有维度都被标 _missing,说明 LLM 输出 JSON 里 dim_id 字段缺失或写错。
-    // 此时应报 fail(解析失败),不能当作"全部通过"。
-    const allMissing = [...parseResult.byDimId.values()].every((r) => r._missing);
-    if (allMissing) {
-        return [errorSummaryOutcome(ctx, 'extract', 'LLM output missing all dimension IDs', { rawSample: cleaned.slice(0, 3000) })];
+    // 归并:healthMerge='string' 走字符串键;='llm'(CLI 默认)且确有可并 finding 时,多跑一次
+    // LLM 聚类(跨措辞同根因归并),失败回退 string。单样本时两者都等价于直通 + support={1,1}。
+    const mergeStrategy = ctx.healthMerge ?? 'string';
+    let merged = null;
+    let mergeMode = 'string';
+    if (mergeStrategy === 'llm' && parsed.length > 1) {
+        const tagged = enumerateFindingsForMerge(parsed, dims);
+        // 仅当某维度内 ≥2 条 finding 才值得跑 LLM 聚类(否则没东西可并,白花一次调用)。
+        const mergeable = dims.some((d) => tagged.filter((t) => t.dimId === d.id).length >= 2);
+        if (mergeable) {
+            let mres = null;
+            try {
+                mres = await executor({
+                    model: ctx.model,
+                    prompt: buildHealthMergePrompt(dims, tagged),
+                    cwd: skillRoot ?? ctx.cwd,
+                    skillDir: skillRoot ?? null,
+                    timeoutMs: ctx.timeoutMs,
+                    effort: ctx.effort ?? 'low',
+                    lean: true,
+                });
+            }
+            catch {
+                mres = null;
+            }
+            if (mres)
+                accumulate(mres);
+            const cleaned = mres?.ok && mres.output ? extractJson(mres.output) : null;
+            const clusters = cleaned ? parseMergeClusters(cleaned) : null;
+            if (clusters) {
+                merged = mergeHealthSamplesLlm(parsed, dims, tagged, clusters);
+                mergeMode = 'llm';
+            }
+            else {
+                mergeMode = 'string(llm-fallback)'; // LLM 合并失败 → 用字符串键兜底
+            }
+        }
     }
+    if (!merged)
+        merged = mergeHealthSamples(parsed, dims);
+    const overall = merged.overall ?? deriveOverallHealth(merged.byDimId);
+    const succeeded = parsed.length;
     // 汇总 finding 计数(框架算,不信 LLM 算术)
     const finding = { '错误': 0, '警告': 0, '建议': 0 };
     const dimCount = { '健康': 0, '亚健康': 0, '不健康': 0, '不适用': 0 };
-    for (const r of parseResult.byDimId.values()) {
+    for (const r of merged.byDimId.values()) {
         if (r._missing)
             continue;
         dimCount[r.level] += 1;
@@ -222,7 +322,7 @@ async function composerCheckAll(ctx, execFactory) {
     }
     // N 条维度 outcome
     const dimOutcomes = dims.map((dim) => {
-        const r = parseResult.byDimId.get(dim.id);
+        const r = merged.byDimId.get(dim.id);
         return {
             subId: dim.id,
             labelKey: dim.labelKey,
@@ -240,35 +340,47 @@ async function composerCheckAll(ctx, execFactory) {
             },
         };
     });
+    // summary message:多采样时(requested>1)追加采样次数说明,让终端看到"并集来自几次采样"。
+    let summaryMessage = tDoctorMessage('cli.doctor.health.summary.message', ctx.lang, {
+        overall,
+        h: dimCount['健康'], sh: dimCount['亚健康'], bad: dimCount['不健康'], na: dimCount['不适用'],
+        err: finding['错误'], warn: finding['警告'], sug: finding['建议'],
+    });
+    if (requested > 1) {
+        summaryMessage += tDoctorMessage(succeeded < requested
+            ? 'cli.doctor.health.summary.samples_degraded'
+            : 'cli.doctor.health.summary.samples', ctx.lang, { requested, succeeded });
+    }
+    const sampleDegraded = requested > 1 && succeeded < requested;
     // 1 条 summary outcome
     const summaryOutcome = {
         subId: '_summary',
         severity: 'info',
         labelKey: 'cli.doctor.health.summary.label',
-        status: 'pass', // summary 永远 pass(信息性,不影响 outcome)
-        message: tDoctorMessage('cli.doctor.health.summary.message', ctx.lang, {
-            overall,
-            h: dimCount['健康'], sh: dimCount['亚健康'], bad: dimCount['不健康'], na: dimCount['不适用'],
-            err: finding['错误'], warn: finding['警告'], sug: finding['建议'],
-        }),
-        hint: parseResult.topSuggestions.slice(0, 3).join(' | ')
+        status: sampleDegraded ? 'warn' : 'pass',
+        message: summaryMessage,
+        hint: merged.topSuggestions.slice(0, 3).join(' | ')
             || tDoctorMessage('cli.doctor.health.summary.no_top', ctx.lang),
         detail: {
             overall,
+            // 采样次数:requested=请求几次,succeeded=成功解析几次。finding 的 support=k/n
+            // 即"被评估的 n 次里有 k 次报了这条"。mergeMode=归并实现(string / llm / 回退)。
+            samples: { requested, succeeded, concurrency, degraded: sampleDegraded },
+            mergeMode,
             dimensionLevelCount: dimCount,
             findingCountByLevel: finding,
-            topSuggestions: parseResult.topSuggestions,
-            featurePoints: parseResult.featurePoints,
-            durationMs: res.durationMs,
-            durationApiMs: res.durationApiMs,
-            // turns:claude-cli 在内部跑的 LLM 轮次(每轮 = 1 次 messages.create)
+            topSuggestions: merged.topSuggestions,
+            featurePoints: merged.featurePoints,
+            durationMs: agg.durationMs,
+            durationApiMs: agg.durationApiMs,
+            // turns:claude-cli 在内部跑的 LLM 轮次(每轮 = 1 次 messages.create),多采样累加。
             // numTurns:assistant turn 数 / fullNumTurns:含 tool turn 的总数
-            llmTurns: { numTurns: res.numTurns, fullNumTurns: res.fullNumTurns },
+            llmTurns: { numTurns: agg.numTurns, fullNumTurns: agg.fullNumTurns },
             tokens: {
-                input: res.inputTokens, output: res.outputTokens,
-                cacheRead: res.cacheReadTokens, cacheCreation: res.cacheCreationTokens,
+                input: agg.inputTokens, output: agg.outputTokens,
+                cacheRead: agg.cacheReadTokens, cacheCreation: agg.cacheCreationTokens,
             },
-            costUSD: res.costUSD,
+            costUSD: agg.costUSD,
             executor: { name: ctx.executorName, model: ctx.model },
         },
     };

package/dist/doctor/health/consensus.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 多采样共识合并 —— self-consistency 抹平单次采样方差。
+ *
+ * composer 串行跑 N 次 LLM,各次产出独立的 HealthParseResult。本模块把这 N 份
+ * 结果**按维度取并集**:同根因 finding 跨采样合并成一条,标注支持度 `k/n`
+ * (该维度被评估的 n 次里,有 k 次报了这条)。**默认不过滤** —— 召回优先,
+ * 低支持度的也保留并如实标注,让重复体检看到的是"并集",而不是每次抖动的子集。
+ *
+ * 两种归并实现,共用 assembleDimResult 出维度结果:
+ *   - mergeHealthSamples(string,默认):按 findingKey(反引号锚点 / 归一化描述前缀)
+ *     聚类。便宜、无额外 LLM 调用;缺点是同根因不同措辞可能漏并(拆成多条低支持度)。
+ *   - mergeHealthSamplesLlm(option C):用一次 LLM 聚类(skill-health-merge prompt)的
+ *     结果分组,跨措辞归并最准;composer 在 healthMerge='llm' 时调用,失败回退 string。
+ */
+import type { HealthDimensionSpec, HealthFinding, HealthFindingLevel } from './dimension-spec.js';
+import type { HealthParseResult } from './parser.js';
+/**
+ * 同根因合并键。锚点优先(跨采样最稳),退回归一化描述前缀。
+ * 不含 level:同一问题不同采样 level 可能不同,合并时单独取最严重。
+ */
+export declare function findingKey(f: HealthFinding): string;
+export declare function mergeHealthSamples(samples: HealthParseResult[], dims: HealthDimensionSpec[]): HealthParseResult;
+/** 带稳定 id 的采样 finding(喂给 merge prompt + 回填分组)。 */
+export interface TaggedFinding {
+    id: string;
+    sampleIdx: number;
+    dimId: string;
+    finding: HealthFinding;
+}
+/** 枚举所有采样里所有维度的 finding,赋稳定 id(f0, f1, …),供 LLM 聚类引用。 */
+export declare function enumerateFindingsForMerge(samples: HealthParseResult[], dims: HealthDimensionSpec[]): TaggedFinding[];
+/** merge LLM 输出的一个聚类。 */
+export interface MergeCluster {
+    dimId: string;
+    findingIds: string[];
+    level?: HealthFindingLevel;
+    description?: string;
+    suggestion?: string;
+}
+/** 解析 merge LLM 的 clusters JSON(已 extractJson)。非法返回 null → composer 回退 string。 */
+export declare function parseMergeClusters(jsonText: string): MergeCluster[] | null;
+/** 按 LLM 聚类结果合并。未被任何 cluster 覆盖的 finding 兜底自成一组(绝不丢)。 */
+export declare function mergeHealthSamplesLlm(samples: HealthParseResult[], dims: HealthDimensionSpec[], tagged: TaggedFinding[], clusters: MergeCluster[]): HealthParseResult;

package/dist/doctor/health/consensus.js

@@ -0,0 +1,224 @@
+/**
+ * 多采样共识合并 —— self-consistency 抹平单次采样方差。
+ *
+ * composer 串行跑 N 次 LLM,各次产出独立的 HealthParseResult。本模块把这 N 份
+ * 结果**按维度取并集**:同根因 finding 跨采样合并成一条,标注支持度 `k/n`
+ * (该维度被评估的 n 次里,有 k 次报了这条)。**默认不过滤** —— 召回优先,
+ * 低支持度的也保留并如实标注,让重复体检看到的是"并集",而不是每次抖动的子集。
+ *
+ * 两种归并实现,共用 assembleDimResult 出维度结果:
+ *   - mergeHealthSamples(string,默认):按 findingKey(反引号锚点 / 归一化描述前缀)
+ *     聚类。便宜、无额外 LLM 调用;缺点是同根因不同措辞可能漏并(拆成多条低支持度)。
+ *   - mergeHealthSamplesLlm(option C):用一次 LLM 聚类(skill-health-merge prompt)的
+ *     结果分组,跨措辞归并最准;composer 在 healthMerge='llm' 时调用,失败回退 string。
+ */
+import { deriveOverallHealth } from './parser.js';
+const FINDING_SEVERITY = { 错误: 3, 警告: 2, 建议: 1 };
+function isFindingLevel(s) {
+    return s === '错误' || s === '警告' || s === '建议';
+}
+function deriveDimLevel(findings) {
+    if (findings.some((f) => f.level === '错误'))
+        return '不健康';
+    if (findings.length > 0)
+        return '亚健康';
+    return '健康';
+}
+/**
+ * 同根因合并键。锚点优先(跨采样最稳),退回归一化描述前缀。
+ * 不含 level:同一问题不同采样 level 可能不同,合并时单独取最严重。
+ */
+export function findingKey(f) {
+    const text = `${f.description ?? ''} ${f.suggestion ?? ''}`;
+    const anchors = [...text.matchAll(/`([^`]+)`/g)]
+        .map((m) => m[1].trim().toLowerCase())
+        .filter((s) => s.length > 0);
+    if (anchors.length > 0) {
+        return `a:${[...new Set(anchors)].sort().join(',')}`;
+    }
+    // 去掉空白 / 标点 / 符号后取前缀(中文字符保留)
+    const norm = (f.description ?? '').toLowerCase().replace(/[\s\p{P}\p{S}]+/gu, '');
+    return `d:${norm.slice(0, 48)}`;
+}
+/** 由分组好的 FindingGroup 组装一个维度结果(support、排序、维度 level 派生)。 */
+function assembleDimResult(presentLevels, n, groups, suggestions) {
+    const findings = groups.map((g) => {
+        // representative 取描述更详尽的一条;level 取组内最严重(除非 LLM 显式给了)。
+        const rep = [...g.members].sort((a, b) => (b.description?.length ?? 0) - (a.description?.length ?? 0))[0];
+        const worst = g.members.reduce((acc, f) => (FINDING_SEVERITY[f.level] > FINDING_SEVERITY[acc] ? f.level : acc), '建议');
+        return {
+            ...rep,
+            // override.level 只能"升"不能"降":worst(组内最严重)是下限,LLM 聚类觉得更严重才采纳。
+            // 否则一次归并能把真 错误 降成 警告(维度 不健康→亚健康),把真问题藏掉。
+            level: g.override?.level && FINDING_SEVERITY[g.override.level] > FINDING_SEVERITY[worst]
+                ? g.override.level
+                : worst,
+            description: g.override?.description ?? rep.description,
+            suggestion: g.override?.suggestion ?? rep.suggestion,
+            support: { k: g.sampleIdxs.size, n },
+        };
+    });
+    // 排序:支持度高在前,其次错误优先 —— 最可信、最严重的排最前。
+    findings.sort((x, y) => {
+        const sk = (y.support?.k ?? 0) - (x.support?.k ?? 0);
+        if (sk !== 0)
+            return sk;
+        return FINDING_SEVERITY[y.level] - FINDING_SEVERITY[x.level];
+    });
+    // 零 finding 时:只有所有采样都判不适用才算不适用(任一判健康 = 适用且健康)。
+    const level = findings.length > 0
+        ? deriveDimLevel(findings)
+        : presentLevels.every((l) => l === '不适用') ? '不适用' : '健康';
+    return { level, findings, suggestions };
+}
+/** 该维度被"实际评估"过的采样(present 且非 _missing;健康=0 finding 也算评估过)。 */
+function presentSamplesFor(samples, dimId) {
+    const out = [];
+    samples.forEach((s, idx) => {
+        const r = s.byDimId.get(dimId);
+        if (r != null && !r._missing)
+            out.push({ idx, r });
+    });
+    return out;
+}
+function finalize(byDimId, samples) {
+    const topSet = new Set();
+    for (const s of samples)
+        for (const t of s.topSuggestions)
+            topSet.add(t);
+    const featurePoints = samples.find((s) => s.featurePoints.length > 0)?.featurePoints ?? [];
+    return { byDimId, overall: deriveOverallHealth(byDimId), topSuggestions: [...topSet], featurePoints };
+}
+// ---------------------------------------------------------------------------
+// string 归并(默认,findingKey 聚类)
+// ---------------------------------------------------------------------------
+export function mergeHealthSamples(samples, dims) {
+    const byDimId = new Map();
+    for (const dim of dims) {
+        const present = presentSamplesFor(samples, dim.id);
+        if (present.length === 0) {
+            byDimId.set(dim.id, { level: '不适用', findings: [], suggestions: [], _missing: true });
+            continue;
+        }
+        const suggestionsSet = new Set();
+        const groupMap = new Map();
+        for (const { idx, r } of present) {
+            for (const sug of r.suggestions)
+                suggestionsSet.add(sug);
+            for (const f of r.findings) {
+                const key = findingKey(f);
+                let g = groupMap.get(key);
+                if (!g) {
+                    g = { members: [], sampleIdxs: new Set() };
+                    groupMap.set(key, g);
+                }
+                g.members.push(f);
+                g.sampleIdxs.add(idx);
+            }
+        }
+        // n(支持度分母)= 已评估且适用的采样数;不适用采样不算"评估过这条 finding"。
+        const assessedN = present.filter((p) => p.r.level !== '不适用').length;
+        byDimId.set(dim.id, assembleDimResult(present.map((p) => p.r.level), assessedN, [...groupMap.values()], [...suggestionsSet]));
+    }
+    return finalize(byDimId, samples);
+}
+/** 枚举所有采样里所有维度的 finding,赋稳定 id(f0, f1, …),供 LLM 聚类引用。 */
+export function enumerateFindingsForMerge(samples, dims) {
+    const out = [];
+    let counter = 0;
+    samples.forEach((s, sampleIdx) => {
+        for (const dim of dims) {
+            const r = s.byDimId.get(dim.id);
+            if (!r || r._missing)
+                continue;
+            for (const f of r.findings) {
+                out.push({ id: `f${counter}`, sampleIdx, dimId: dim.id, finding: f });
+                counter += 1;
+            }
+        }
+    });
+    return out;
+}
+/** 解析 merge LLM 的 clusters JSON(已 extractJson)。非法返回 null → composer 回退 string。 */
+export function parseMergeClusters(jsonText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const raw = parsed.clusters;
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const c = item;
+        if (typeof c.dim_id !== 'string')
+            continue;
+        if (!Array.isArray(c.finding_ids))
+            continue;
+        const ids = c.finding_ids.filter((x) => typeof x === 'string');
+        if (ids.length === 0)
+            continue;
+        out.push({
+            dimId: c.dim_id,
+            findingIds: ids,
+            level: isFindingLevel(c.level) ? c.level : undefined,
+            description: typeof c.description === 'string' && c.description.trim() ? c.description : undefined,
+            suggestion: typeof c.suggestion === 'string' && c.suggestion.trim() ? c.suggestion : undefined,
+        });
+    }
+    return out.length > 0 ? out : null;
+}
+/** 按 LLM 聚类结果合并。未被任何 cluster 覆盖的 finding 兜底自成一组(绝不丢)。 */
+export function mergeHealthSamplesLlm(samples, dims, tagged, clusters) {
+    const byId = new Map(tagged.map((t) => [t.id, t]));
+    const covered = new Set();
+    const groupsByDim = new Map();
+    const addGroup = (dimId, g) => {
+        if (!groupsByDim.has(dimId))
+            groupsByDim.set(dimId, []);
+        groupsByDim.get(dimId).push(g);
+    };
+    for (const c of clusters) {
+        const members = c.findingIds
+            .map((id) => byId.get(id))
+            .filter((t) => t != null && t.dimId === c.dimId && !covered.has(t.id));
+        if (members.length === 0)
+            continue;
+        for (const m of members)
+            covered.add(m.id);
+        addGroup(c.dimId, {
+            members: members.map((m) => m.finding),
+            sampleIdxs: new Set(members.map((m) => m.sampleIdx)),
+            override: { description: c.description, suggestion: c.suggestion, level: c.level },
+        });
+    }
+    // 兜底:LLM 漏分配的 finding 自成一组,绝不丢。
+    for (const t of tagged) {
+        if (covered.has(t.id))
+            continue;
+        covered.add(t.id);
+        addGroup(t.dimId, { members: [t.finding], sampleIdxs: new Set([t.sampleIdx]) });
+    }
+    const byDimId = new Map();
+    for (const dim of dims) {
+        const present = presentSamplesFor(samples, dim.id);
+        if (present.length === 0) {
+            byDimId.set(dim.id, { level: '不适用', findings: [], suggestions: [], _missing: true });
+            continue;
+        }
+        const suggestionsSet = new Set();
+        for (const { r } of present)
+            for (const sug of r.suggestions)
+                suggestionsSet.add(sug);
+        const assessedN = present.filter((p) => p.r.level !== '不适用').length;
+        byDimId.set(dim.id, assembleDimResult(present.map((p) => p.r.level), assessedN, groupsByDim.get(dim.id) ?? [], [...suggestionsSet]));
+    }
+    return finalize(byDimId, samples);
+}

package/dist/doctor/health/dimension-spec.d.ts

@@ -19,6 +19,12 @@ export interface HealthFinding {
     evidence: string;
     description: string;
     suggestion?: string;
+    /** 多采样共识的支持度:N 次采样里有 k 次报了这条(同根因)finding。
+     *  单次采样(healthSamples=1)时不设或为 {k:1,n:1};renderer 仅在 n>1 时展示。 */
+    support?: {
+        k: number;
+        n: number;
+    };
 }
 export interface HealthDimensionResult {
     level: HealthDimensionLevel;

package/dist/doctor/health/register.d.ts

@@ -3,7 +3,6 @@
  * 注册到 doctor customRules。
  *
  * CLI doctor.ts 默认动态 import 本文件 → 副作用一次性完成。
- * `--static-only` 会在 CLI 层过滤掉 composer rule,不触发 LLM 审计。
  * 测试 import 各 module 的具名 export 不会触发本文件,保持 registry 干净。
  *
  * 用户自定义维度:在自己的代码里 `registerHealthDimension(spec)`,只要在

package/dist/doctor/health/register.js

@@ -3,7 +3,6 @@
  * 注册到 doctor customRules。
  *
  * CLI doctor.ts 默认动态 import 本文件 → 副作用一次性完成。
- * `--static-only` 会在 CLI 层过滤掉 composer rule,不触发 LLM 审计。
  * 测试 import 各 module 的具名 export 不会触发本文件,保持 registry 干净。
  *
  * 用户自定义维度:在自己的代码里 `registerHealthDimension(spec)`,只要在

package/dist/doctor/index.js

@@ -220,6 +220,9 @@ export async function runDoctor(opts) {
         timeoutMs: opts.timeoutMs,
         effort: opts.effort,
         runHealthCheck: opts.runHealthCheck ?? false,
+        healthSamples: opts.healthSamples,
+        healthMerge: opts.healthMerge,
+        healthConcurrency: opts.healthConcurrency,
     };
     const skillReports = [];
     const totals = { pass: 0, warn: 0, fail: 0 };

package/dist/doctor/messages.d.ts

@@ -14,7 +14,7 @@ interface MessageEntry {
     zh: string;
     en: string;
 }
-export type DoctorMessageKey = 'cli.doctor.rule.skill_readable' | 'cli.doctor.rule.skill_metadata' | 'cli.doctor.rule.dependencies' | 'cli.doctor.rule.samples_contract' | 'cli.doctor.rule.skill_health_check' | 'cli.doctor.health.skipped' | 'cli.doctor.health.no_dimensions' | 'cli.doctor.health.fail.executor' | 'cli.doctor.health.fail.parse' | 'cli.doctor.health.fail.empty_output' | 'cli.doctor.health.hint.executor' | 'cli.doctor.health.hint.parse' | 'cli.doctor.health.dim.message' | 'cli.doctor.health.dim.missing' | 'cli.doctor.health.summary.label' | 'cli.doctor.health.summary.message' | 'cli.doctor.health.summary.no_top' | 'cli.doctor.health.dim.trigger-boundary' | 'cli.doctor.health.dim.doc-clarity' | 'cli.doctor.health.dim.instr-precision' | 'cli.doctor.health.dim.dependency' | 'cli.doctor.health.dim.tool-conventions' | 'cli.doctor.health.dim.security' | 'cli.doctor.health.dim.examples' | 'cli.doctor.skill_readable.pass' | 'cli.doctor.skill_metadata.pass' | 'cli.doctor.dependencies.pass' | 'cli.doctor.samples_contract.pass' | 'cli.doctor.skill_readable.fail.missing' | 'cli.doctor.skill_readable.fail.empty' | 'cli.doctor.skill_readable.fail.too_short' | 'cli.doctor.skill_readable.hint.missing' | 'cli.doctor.skill_readable.hint.too_short' | 'cli.doctor.skill_metadata.fail.frontmatter_invalid' | 'cli.doctor.skill_metadata.fail.hardrules_invalid' | 'cli.doctor.skill_metadata.fail.workflows_invalid' | 'cli.doctor.skill_metadata.fail.missing_skillmd' | 'cli.doctor.skill_metadata.hint.frontmatter' | 'cli.doctor.skill_metadata.hint.hardrules' | 'cli.doctor.skill_metadata.hint.workflows' | 'cli.doctor.skill_metadata.hint.missing_skillmd' | 'cli.doctor.dependencies.fail' | 'cli.doctor.dependencies.hint.tool' | 'cli.doctor.dependencies.hint.file' | 'cli.doctor.dependencies.hint.env' | 'cli.doctor.dependencies.hint.preflight' | 'cli.doctor.dependencies.issue.tool_not_found' | 'cli.doctor.dependencies.issue.file_not_found' | 'cli.doctor.dependencies.issue.env_not_set' | 'cli.doctor.dependencies.issue.preflight_failed' | 'cli.doctor.samples_contract.skipped' | 'cli.doctor.samples_contract.warn.empty' | 'cli.doctor.samples_contract.warn.missing_prompt' | 'cli.doctor.samples_contract.hint';
+export type DoctorMessageKey = 'cli.doctor.rule.skill_readable' | 'cli.doctor.rule.skill_metadata' | 'cli.doctor.rule.dependencies' | 'cli.doctor.rule.samples_contract' | 'cli.doctor.rule.skill_health_check' | 'cli.doctor.health.skipped' | 'cli.doctor.health.no_dimensions' | 'cli.doctor.health.fail.executor' | 'cli.doctor.health.fail.parse' | 'cli.doctor.health.fail.empty_output' | 'cli.doctor.health.hint.executor' | 'cli.doctor.health.hint.parse' | 'cli.doctor.health.dim.message' | 'cli.doctor.health.dim.missing' | 'cli.doctor.health.summary.label' | 'cli.doctor.health.summary.message' | 'cli.doctor.health.summary.samples' | 'cli.doctor.health.summary.samples_degraded' | 'cli.doctor.health.summary.no_top' | 'cli.doctor.health.dim.trigger-boundary' | 'cli.doctor.health.dim.doc-clarity' | 'cli.doctor.health.dim.instr-precision' | 'cli.doctor.health.dim.dependency' | 'cli.doctor.health.dim.tool-conventions' | 'cli.doctor.health.dim.security' | 'cli.doctor.health.dim.examples' | 'cli.doctor.skill_readable.pass' | 'cli.doctor.skill_metadata.pass' | 'cli.doctor.dependencies.pass' | 'cli.doctor.samples_contract.pass' | 'cli.doctor.skill_readable.fail.missing' | 'cli.doctor.skill_readable.fail.empty' | 'cli.doctor.skill_readable.fail.too_short' | 'cli.doctor.skill_readable.hint.missing' | 'cli.doctor.skill_readable.hint.too_short' | 'cli.doctor.skill_metadata.fail.frontmatter_invalid' | 'cli.doctor.skill_metadata.fail.hardrules_invalid' | 'cli.doctor.skill_metadata.fail.workflows_invalid' | 'cli.doctor.skill_metadata.fail.missing_skillmd' | 'cli.doctor.skill_metadata.hint.frontmatter' | 'cli.doctor.skill_metadata.hint.hardrules' | 'cli.doctor.skill_metadata.hint.workflows' | 'cli.doctor.skill_metadata.hint.missing_skillmd' | 'cli.doctor.dependencies.fail' | 'cli.doctor.dependencies.hint.tool' | 'cli.doctor.dependencies.hint.file' | 'cli.doctor.dependencies.hint.env' | 'cli.doctor.dependencies.hint.preflight' | 'cli.doctor.dependencies.issue.tool_not_found' | 'cli.doctor.dependencies.issue.file_not_found' | 'cli.doctor.dependencies.issue.env_not_set' | 'cli.doctor.dependencies.issue.preflight_failed' | 'cli.doctor.samples_contract.skipped' | 'cli.doctor.samples_contract.warn.empty' | 'cli.doctor.samples_contract.warn.missing_prompt' | 'cli.doctor.samples_contract.hint';
 export declare const DOCTOR_MESSAGES: Record<DoctorMessageKey, MessageEntry>;
 export declare function tDoctorMessage(key: DoctorMessageKey, lang?: Lang, params?: Record<string, string | number>): string;
 export {};

package/dist/doctor/messages.js

@@ -65,6 +65,14 @@ export const DOCTOR_MESSAGES = {
         zh: '{overall} | 维度: 健康 {h}/亚健康 {sh}/不健康 {bad}/不适用 {na} | finding: 错误 {err}/警告 {warn}/建议 {sug}',
         en: '{overall} | dims: healthy {h}/sub {sh}/unhealthy {bad}/n-a {na} | findings: err {err}/warn {warn}/sug {sug}',
     },
+    'cli.doctor.health.summary.samples': {
+        zh: ' | 采样 {succeeded}/{requested} 次（并集去重，finding 标注 k/n 支持度）',
+        en: ' | sampled {succeeded}/{requested} (unioned & deduped; findings tagged k/n support)',
+    },
+    'cli.doctor.health.summary.samples_degraded': {
+        zh: ' | 采样仅成功解析 {succeeded}/{requested} 次（已降级，finding 的 k/n 只基于成功样本）',
+        en: ' | parsed only {succeeded}/{requested} samples (degraded; k/n support uses successful samples only)',
+    },
     'cli.doctor.health.summary.no_top': {
         zh: '完整详情见 --json 输出或 --html 报告',
         en: 'Full detail in --json output or --html report',

package/dist/doctor/rules.d.ts

@@ -2,8 +2,10 @@
  * omk doctor 内置规则注册表。
  *
  * BUILTIN_RULES 是**纯静态/低成本检查**, 不碰 LLM 连通性 — executor / judge
- * 连通性由 evaluation preflight 负责。用户入口 `omk doctor` 默认还会跑
- * skill_health composer 做 LLM 审计;`--static-only` 只暴露这里的静态规则。
+ * 连通性由 evaluation preflight 负责。用户入口 `omk doctor` 默认会跑这些静态
+ * 规则,再跑 skill_health composer 做 LLM 审计;`--static-only` 只跑静态规则。
+ * samples_contract_aligned 需要 samples,仍只归 eval preflight
+ * (run-evaluation.ts 经 runDoctor 调,dependencies_present 守依赖完整性)。
  *
  * 每条 rule 回答一个独立的「skill 能不能被有意义评测」子问题:
  *   - skill_readable: 文件能读、内容非空且有最小长度

package/dist/doctor/rules.js

@@ -2,8 +2,10 @@
  * omk doctor 内置规则注册表。
  *
  * BUILTIN_RULES 是**纯静态/低成本检查**, 不碰 LLM 连通性 — executor / judge
- * 连通性由 evaluation preflight 负责。用户入口 `omk doctor` 默认还会跑
- * skill_health composer 做 LLM 审计;`--static-only` 只暴露这里的静态规则。
+ * 连通性由 evaluation preflight 负责。用户入口 `omk doctor` 默认会跑这些静态
+ * 规则,再跑 skill_health composer 做 LLM 审计;`--static-only` 只跑静态规则。
+ * samples_contract_aligned 需要 samples,仍只归 eval preflight
+ * (run-evaluation.ts 经 runDoctor 调,dependencies_present 守依赖完整性)。
  *
  * 每条 rule 回答一个独立的「skill 能不能被有意义评测」子问题:
  *   - skill_readable: 文件能读、内容非空且有最小长度