oh-my-knowledge 0.30.0 → 0.32.0

package/dist/server/skill-insights.js

@@ -0,0 +1,788 @@
+import { isActiveDiagnosisLifecycle } from '../diagnosis/types.js';
+/** Resolve which variant in `report` 是这个 entry / insight 关注的。
+ *  优先用调用方传的 `preferred`(entry.eval?.variantName);找不到再 fallback 到第一个非 baseline。
+ *  这避免 multi-treatment 报告里所有 detector 都默认拿第一个 treatment 的数据,导致
+ *  /skills/<treatment-2> 的详情页加载的是 treatment-1 的 failureModes / coverage / illustrations。 */
+function resolveVariant(report, preferred) {
+    const all = report.meta.variants ?? [];
+    if (preferred && all.includes(preferred))
+        return preferred;
+    return all.find((v) => v !== 'baseline') ?? null;
+}
+function summarizeToolCall(tc) {
+    const tool = tc.tool;
+    const inp = tc.input;
+    let arg = '';
+    if (inp) {
+        if (typeof inp.command === 'string')
+            arg = inp.command.slice(0, 60);
+        else if (typeof inp.file_path === 'string')
+            arg = inp.file_path;
+        else if (typeof inp.url === 'string')
+            arg = inp.url;
+        else if (typeof inp.query === 'string')
+            arg = inp.query.slice(0, 50);
+    }
+    const status = tc.success ? '' : ' [失败]';
+    return arg ? `${tool}: ${arg}${status}` : `${tool}${status}`;
+}
+function getFailedSamples(report, variant) {
+    const out = [];
+    for (const r of report.results) {
+        const v = r.variants?.[variant];
+        if (!v)
+            continue;
+        const passed = (v.assertions?.details ?? []).every((d) => d.passed);
+        if (passed)
+            continue;
+        const isTripwire = (v.diagnostic?.rootCause || []).includes('tripwire_intentional')
+            || report.sampleSnapshots?.[r.sample_id]?.tripwire === true;
+        if (isTripwire)
+            continue;
+        const firstFail = v.assertions?.details?.find((d) => !d.passed);
+        out.push({
+            sampleId: r.sample_id,
+            rootCause: (v.diagnostic?.rootCause ?? []),
+            failureModes: (v.diagnostic?.failureModes ?? []),
+            diagnosticSummary: v.diagnostic?.summary ?? '',
+            prompt: report.sampleSnapshots?.[r.sample_id]?.prompt,
+            llmOutput: v.outputPreview ?? undefined,
+            toolCalls: v.toolCalls?.slice(0, 6).map(summarizeToolCall),
+            firstFailedAssertion: firstFail
+                ? `${firstFail.type}: ${typeof firstFail.value === 'object' ? JSON.stringify(firstFail.value) : String(firstFail.value)}`
+                : undefined,
+        });
+    }
+    return out;
+}
+/**
+ * 阈值依据:
+ *   >= 3:high — 同 failure mode 重复 3 次以上,可以排除偶发,定为强信号;
+ *   >= 2:medium — 重复出现意味着不是单条 sample 抽风,但 2 次还不算稳定模式;
+ *   1:low — 单条命中,可能是 sample 设计问题或 LLM 一次性失误,不阻塞但记录。
+ *
+ * 各 detector 内部一般也用 `>= 2` 作为 cluster 阈值(详情参考各 detector 注释)。
+ *
+ * 采样不足提醒:单 skill < 2 个非诱错 sample 时不会触发任何 cluster-based insight,
+ * 这是设计行为(没数据不下结论),用户层面应该看到"用例数 < 5,建议补样本"提示
+ * (在 detail page 空态有,list 页面 todo)。
+ */
+function severityOfCount(n) {
+    if (n >= 3)
+        return 'high';
+    if (n >= 2)
+        return 'medium';
+    return 'low';
+}
+function pickIllustrations(samples, n = 2) {
+    return samples.slice(0, n).map((s) => ({
+        sampleId: s.sampleId,
+        samplePrompt: s.prompt?.slice(0, 200),
+        llmOutput: s.llmOutput?.slice(0, 200),
+        toolCalls: s.toolCalls,
+        failedAssertion: s.firstFailedAssertion,
+    }));
+}
+// ────────── 7 类 detection ──────────
+/** failureMode `环境拦截` cluster — 实际是 sample 设计问题,不是 skill 问题。 */
+function detectEnvironmentBlocked(evalReport, variantName) {
+    if (!evalReport)
+        return null;
+    const variant = resolveVariant(evalReport, variantName);
+    if (!variant)
+        return null;
+    const failed = getFailedSamples(evalReport, variant);
+    const blocked = failed.filter((f) => f.failureModes.includes('环境拦截'));
+    if (blocked.length < 2)
+        return null;
+    const sampleIds = blocked.map((s) => s.sampleId).join(', ');
+    return {
+        id: 'environment-blocked-mocks',
+        category: 'environment-blocked-mocks',
+        audience: 'sample-author',
+        title: `${blocked.length} 条评测样本因 mock 没盖到 LLM 想调的工具而 fail`,
+        description: 'LLM 行为正确但工具调用被 mock-strict 拦截 — 这是 sample 设计问题,不是 skill 问题。要么 mock 列表漏写,要么 command_glob/file_path 写得太严没匹配到 LLM 真实调用。',
+        severity: severityOfCount(blocked.length),
+        affectedCount: blocked.length,
+        stageRefs: { evalSampleIds: blocked.map((s) => s.sampleId) },
+        evidence: [
+            {
+                perspective: 'eval-functional', status: 'flagged',
+                message: `sample ${sampleIds} 失败模式都是「环境拦截」(LLM 调用被 mocks-strict deny)`,
+                ref: blocked[0].sampleId,
+                illustrations: pickIllustrations(blocked, 2),
+            },
+            {
+                perspective: 'doctor', status: 'silent',
+                message: 'doctor 不检查 mock 设计完备性(超出静态体检范围)',
+            },
+        ],
+        recommendations: [
+            {
+                action: `复查 sample ${blocked[0].sampleId} 的 mocks 列表,确认 LLM 实际调用形态被覆盖`,
+                priority: severityOfCount(blocked.length),
+                patch: {
+                    target: 'sample-mocks',
+                    location: `sample ${blocked[0].sampleId} 的 mocks 数组`,
+                    snippet: `// 看 LLM 实际调了什么(toolCalls 里),把缺的工具加进去
+{
+  "tool": "Bash",  // 或 Read/WebFetch 等,跟 illustration 里的 toolCalls 对上
+  "match": { "command_glob": "*<LLM 实际调的命令片段>*" },
+  "return": { "stdout": "<模拟成功输出>", "exit": 0 }
+}`,
+                },
+            },
+            {
+                action: 'file_path 严格匹配挂的话,改用 file_path_endswith 后缀匹配',
+                priority: 'medium',
+                patch: {
+                    target: 'sample-mocks',
+                    location: '所有 file_path 严格相等的 mock',
+                    snippet: `// before: { "match": { "file_path": "tasks/state.json" } }
+// after:
+{ "match": { "file_path_endswith": "tasks/state.json" } }`,
+                },
+            },
+        ],
+    };
+}
+/** sample.environment.files_available 缺声明 + skill 文档没强调依赖。 */
+function detectSkillDocGap(doctor, evalReport, observe, variantName) {
+    const depRule = doctor?.results.find((r) => r.ruleId === 'dependencies_present'
+        && (r.status === 'warn' || r.status === 'fail'));
+    let failedDocSamples = [];
+    if (evalReport) {
+        const variant = resolveVariant(evalReport, variantName);
+        if (variant) {
+            failedDocSamples = getFailedSamples(evalReport, variant).filter((f) => f.rootCause.includes('skill_doc_missing') || f.rootCause.includes('skill_doc_unclear'));
+        }
+    }
+    if (!depRule && failedDocSamples.length === 0)
+        return null;
+    const missingFiles = depRule?.detail?.missing_files ?? [];
+    const exampleFile = missingFiles[0] ?? 'XXX.md';
+    const evidence = [];
+    evidence.push(depRule
+        ? {
+            perspective: 'doctor', status: 'flagged',
+            message: `doctor 静态检查:skill 引用了 ${missingFiles.length || 1} 个文件但 sample 没声明已就绪${missingFiles.length > 0 ? ` (${missingFiles.join(', ')})` : ''}`,
+            ref: depRule.ruleId,
+        }
+        : {
+            perspective: 'doctor', status: 'blind',
+            message: 'eval 失败 sample 标 skill 文档缺漏,但 doctor 没卡 — 文档可能写得不规范但 doctor 规则识别不出',
+        });
+    if (failedDocSamples.length > 0) {
+        evidence.push({
+            perspective: 'eval-functional', status: 'flagged',
+            message: `${failedDocSamples.length} 条评测样本失败,LLM 没找到该读哪段文档(${failedDocSamples.map((f) => f.sampleId).join(', ')})`,
+            ref: failedDocSamples[0].sampleId,
+            illustrations: pickIllustrations(failedDocSamples, 2),
+        });
+    }
+    else {
+        evidence.push({
+            perspective: 'eval-functional', status: 'silent',
+            message: '本批 evaluation 没命中文档缺漏类失败',
+        });
+    }
+    evidence.push(observe
+        ? observe.gapRate >= 0.2
+            ? {
+                perspective: 'observe', status: 'flagged',
+                message: `生产里 ${(observe.gapRate * 100).toFixed(0)}% 段也命中知识库 gap(LLM 找不到该读哪段) — 跟评测信号印证`,
+            }
+            : {
+                perspective: 'observe', status: 'silent',
+                message: `生产 gap 率 ${(observe.gapRate * 100).toFixed(0)}%,真实使用中此问题触发不多`,
+            }
+        : { perspective: 'observe', status: 'na', message: '没跑 observe,无法看真实生产是否也踩' });
+    const severity = (depRule && failedDocSamples.length >= 2) ? 'high'
+        : failedDocSamples.length >= 2 || depRule ? 'medium' : 'low';
+    const recs = [];
+    if (depRule) {
+        recs.push({
+            action: `在 sample.environment.files_available 加上文件路径,告诉 LLM "这些文件已就绪,无需探测"`,
+            priority: severity,
+            patch: {
+                target: 'sample-environment',
+                location: 'samples.json 各 sample 的 environment 块',
+                snippet: `"environment": {
+  "files_available": [
+    "${exampleFile}"${missingFiles.length > 1 ? `,
+    "${missingFiles[1]}"` : ''}
+  ],
+  "notes": "所有依赖文件已就绪,LLM 跳过探测直接进工作流"
+}`,
+            },
+        });
+    }
+    if (failedDocSamples.length > 0) {
+        recs.push({
+            action: `在 SKILL.md 引用这些文件的章节加显眼提示,LLM 容易漏读`,
+            priority: severity,
+            patch: {
+                target: 'skill',
+                location: 'SKILL.md 中引用 ' + (missingFiles[0] ?? '相关文件') + ' 的章节',
+                snippet: `## <相关章节>
+
+⚠️ **必读前置**:本步骤依赖 \`${exampleFile}\` 中的内容,务必先 Read 该文件再继续。
+
+<原步骤说明>...`,
+            },
+        });
+    }
+    return {
+        id: 'skill-doc-gap',
+        category: 'skill-doc-gap',
+        audience: failedDocSamples.length > 0 ? 'skill-author' : 'sample-author',
+        title: failedDocSamples.length > 0
+            ? `LLM 漏读 skill 引用的文件,导致 ${failedDocSamples.length} 条样本失败`
+            : 'skill 引用了文件但没声明在 sample.environment 里',
+        description: 'skill 文档提到某些前置文件,但 sample 没标"已就绪"。LLM 看 prompt 时会试图先探测/Read 这些文件,在 mocks-strict 环境下被拦,流程在第一步就停。',
+        severity,
+        affectedCount: failedDocSamples.length || 1,
+        stageRefs: {
+            ...(depRule ? { doctorRuleIds: ['dependencies_present'] } : {}),
+            ...(failedDocSamples.length > 0 ? { evalSampleIds: failedDocSamples.map((f) => f.sampleId) } : {}),
+            ...((observe?.gapRate ?? 0) >= 0.2 ? { observeRefs: ['gap'] } : {}),
+        },
+        evidence,
+        recommendations: recs,
+    };
+}
+/** failureMode 是 skill 写法层反模式(硬编码/幻觉/跳步/误读) — 真要改 skill。 */
+function detectFailureModeSkillIssue(evalReport, variantName) {
+    if (!evalReport)
+        return null;
+    const variant = resolveVariant(evalReport, variantName);
+    if (!variant)
+        return null;
+    const failed = getFailedSamples(evalReport, variant);
+    if (failed.length === 0)
+        return null;
+    const SKILL_MODES = new Set(['硬编码值', '幻觉输出', '工作流跳步', '误读约束', '工具误用']);
+    // 排除已被 skill-doc-gap 覆盖的(rootCause skill_doc_missing/unclear)
+    const candidates = failed.filter((f) => {
+        const docIssue = f.rootCause.includes('skill_doc_missing') || f.rootCause.includes('skill_doc_unclear');
+        if (docIssue)
+            return false;
+        return f.failureModes.some((m) => SKILL_MODES.has(m));
+    });
+    // 找最大簇 — 同 failureMode 在 ≥ 2 sample
+    const modeCount = {};
+    for (const f of candidates) {
+        for (const m of f.failureModes) {
+            if (!SKILL_MODES.has(m))
+                continue;
+            if (!modeCount[m])
+                modeCount[m] = [];
+            modeCount[m].push(f);
+        }
+    }
+    const top = Object.entries(modeCount).filter(([, fs]) => fs.length >= 2)
+        .sort((a, b) => b[1].length - a[1].length);
+    if (top.length === 0)
+        return null;
+    const [topMode, topSamples] = top[0];
+    const MODE_USERFACING_DESC = {
+        '硬编码值': 'LLM 把本来该用变量传的值写死(如 namespace 直接写成 "testuser001")',
+        '幻觉输出': 'LLM 声称完成了某动作但实际没调对应工具,输出虚构 id / commit hash / 文件路径',
+        '工作流跳步': 'LLM 没按 skill 教的步骤顺序走,跳过了关键中间步骤',
+        '误读约束': 'skill 文档里写清楚的约束(如"必须用 X 不能用 Y")LLM 没遵守',
+        '工具误用': 'LLM 选错工具或传错参数,反复尝试同一失败动作',
+    };
+    const MODE_PATCH_HINT = {
+        '硬编码值': {
+            location: 'SKILL.md 涉及具体值传递的章节(如「参数获取」「身份注入」节)',
+            snippet: `# Before(LLM 容易硬编码):
+直接把 namespace 设成 "testuser001"。
+
+# After(强制变量化):
+**严禁**直接写死 namespace。先调 \`<your-cli> auth status -o json\` 拿到 username,赋给变量后再传:
+\`\`\`bash
+NAMESPACE=$(<your-cli> auth status -o json | jq -r '.username')
+<your-cli> project create --namespace "$NAMESPACE"
+\`\`\``,
+        },
+        '幻觉输出': {
+            location: 'SKILL.md 涉及工具调用结果回传的章节',
+            snippet: `# 加显眼"诚实输出"约束:
+**严禁**编造 commit hash / id / 文件路径等关键标识符。这些值**必须**从前一步工具调用的真实返回里提取,不能凭印象写。
+若工具调用失败,如实告知用户失败原因,**不要**伪装成功。`,
+        },
+        '工作流跳步': {
+            location: 'SKILL.md 工作流章节(如「步骤 1...步骤 N」)',
+            snippet: `# 用编号 + 必做标记强化顺序:
+## 工作流(必须按序执行)
+1. **第 1 步必做**: <动作 A>
+2. **第 2 步必做**: <动作 B,依赖第 1 步的输出>
+3. **第 3 步可选**: <分支 C>
+
+每完成一步,在响应中明确说"已完成第 N 步: ..."`,
+        },
+        '误读约束': {
+            location: 'SKILL.md 中相关约束的位置',
+            snippet: `# 把约束抬到段落开头 + 加 ⚠️/❌:
+⚠️ **硬规则**: 必须用 \`<工具 A>\`,**严禁**用 \`<工具 B>\` 绕过。
+原因: <为什么>。
+<原步骤说明>`,
+        },
+        '工具误用': {
+            location: 'SKILL.md 工具选择章节',
+            snippet: `# 加工具选择对照表:
+| 场景 | 用 | 不用 |
+|------|----|------|
+| 查询 X | tool-A | tool-B(参数语义不一样) |
+...`,
+        },
+    };
+    return {
+        id: `failure-mode-skill:${topMode}`,
+        category: 'failure-mode-skill',
+        audience: 'skill-author',
+        title: `${topSamples.length} 条样本踩同一个写法坑:${topMode}`,
+        description: MODE_USERFACING_DESC[topMode] ?? `多 sample 共享 failureMode 「${topMode}」,skill 文档对此没抑制`,
+        severity: severityOfCount(topSamples.length),
+        affectedCount: topSamples.length,
+        stageRefs: { evalSampleIds: topSamples.map((s) => s.sampleId) },
+        evidence: [
+            {
+                perspective: 'eval-functional', status: 'flagged',
+                message: `sample ${topSamples.map((s) => s.sampleId).join(', ')} 都因「${topMode}」失败 — 单一原因反复踩,说明 skill 没抑制这种写法`,
+                ref: topSamples[0].sampleId,
+                illustrations: pickIllustrations(topSamples, 2),
+            },
+        ],
+        recommendations: [
+            {
+                action: `在 SKILL.md 中针对「${topMode}」加专门提示`,
+                priority: severityOfCount(topSamples.length),
+                ...(MODE_PATCH_HINT[topMode] ? {
+                    patch: {
+                        target: 'skill',
+                        location: MODE_PATCH_HINT[topMode].location,
+                        snippet: MODE_PATCH_HINT[topMode].snippet,
+                    },
+                } : {}),
+            },
+            {
+                action: '加针对该模式的诱错样本(tripwire),防止 skill 改进后再退化',
+                priority: 'low',
+            },
+        ],
+    };
+}
+/** observe 高失败率 — 真实环境 skill 跑不稳。 */
+function detectProductionInstability(doctor, observe) {
+    if (!observe || observe.failureRate < 0.4)
+        return null;
+    const depRule = doctor?.results.find((r) => r.ruleId === 'dependencies_present'
+        && (r.status === 'warn' || r.status === 'fail'));
+    return {
+        id: 'production-instability',
+        category: 'production-instability',
+        audience: 'skill-author',
+        title: `生产环境跑这个 skill 时,工具失败率 ${(observe.failureRate * 100).toFixed(0)}%`,
+        description: '真实用户用这个 skill,LLM 调出去的工具经常报错。可能是凭证/网络/上游 SLA 问题,也可能是 skill 教错了用什么工具/参数。',
+        severity: 'high',
+        affectedCount: Math.round(observe.segmentCount * observe.failureRate),
+        stageRefs: {
+            observeRefs: ['high-failure-rate'],
+            ...(depRule ? { doctorRuleIds: ['dependencies_present'] } : {}),
+        },
+        evidence: [
+            {
+                perspective: 'observe', status: 'flagged',
+                message: `${observe.segmentCount} 段产线轨迹,工具调用失败率 ${(observe.failureRate * 100).toFixed(0)}%`,
+            },
+            depRule
+                ? {
+                    perspective: 'doctor', status: 'flagged',
+                    message: `doctor 也警告依赖问题:${depRule.message}`,
+                    ref: depRule.ruleId,
+                }
+                : {
+                    perspective: 'doctor', status: doctor ? 'silent' : 'na',
+                    message: doctor
+                        ? 'doctor 没警告依赖,失败可能在 CLI/凭证/上游 API 层(skill 自身可能没错)'
+                        : '没跑 doctor,无法对照',
+                },
+        ],
+        recommendations: [
+            {
+                action: '排查产线工具失败原因:CLI 安装 / 凭证有效期 / 网络 / 上游 API SLA',
+                priority: 'high',
+            },
+            ...(depRule ? [{
+                    action: '依据 doctor 警告补依赖声明 / 改 skill 引用',
+                    priority: 'high',
+                }] : []),
+            {
+                action: '如果不是 skill 写错而是环境问题,在 skill 加重试 / 容错指南',
+                priority: 'medium',
+                patch: {
+                    target: 'skill',
+                    location: 'SKILL.md 工具调用章节',
+                    snippet: `# 容错指南:
+若 \`<工具>\` 调用失败:
+1. 检查环境(凭证 / 网络 / 工具版本)
+2. 重试 1-2 次
+3. 仍失败:**如实告知用户**,不要继续假装完成`,
+                },
+            },
+        ],
+    };
+}
+/** observe gap + eval coverage 漏 — sample 没盖到生产真实使用的文件。 */
+function detectCoverageGap(evalReport, observe, variantName) {
+    if (!observe || observe.gapRate === 0)
+        return null;
+    let evalUncovered = [];
+    if (evalReport?.analysis?.coverage) {
+        const variant = resolveVariant(evalReport, variantName);
+        if (variant && evalReport.analysis.coverage[variant]) {
+            evalUncovered = evalReport.analysis.coverage[variant].uncoveredFiles || [];
+        }
+    }
+    const evidence = [
+        {
+            perspective: 'observe', status: 'flagged',
+            message: `生产里 ${(observe.gapRate * 100).toFixed(0)}% 段命中知识库 gap — LLM 在真实使用中找不到该读哪段`,
+        },
+    ];
+    if (evalUncovered.length > 0) {
+        evidence.push({
+            perspective: 'eval-functional', status: 'flagged',
+            message: `评测样本也漏覆盖 ${evalUncovered.length} 个文件:${evalUncovered.slice(0, 3).join(', ')}${evalUncovered.length > 3 ? '...' : ''}`,
+        });
+    }
+    else {
+        evidence.push({
+            perspective: 'eval-functional', status: 'silent',
+            message: '评测覆盖率 OK,gap 主要来自生产用法跟 sample 设计有差距',
+        });
+    }
+    const severity = observe.gapRate >= 0.4 ? 'high'
+        : observe.gapRate >= 0.2 ? 'medium' : 'low';
+    return {
+        id: 'coverage-gap',
+        category: 'coverage-gap',
+        audience: 'sample-author',
+        title: '生产 + 评测都没覆盖到部分知识库文件',
+        description: '观测到生产用户访问了 skill 引用的某些文件,但你的评测 sample 没测到这些路径 — sample 设计跟真实使用脱节。',
+        severity,
+        affectedCount: Math.max(evalUncovered.length, Math.round(observe.segmentCount * observe.gapRate)),
+        stageRefs: { observeRefs: ['gap', 'uncovered-files'] },
+        evidence,
+        recommendations: [
+            ...(evalUncovered.length > 0
+                ? [{
+                        action: `补 1-2 条 sample 专门测覆盖这些文件:${evalUncovered.slice(0, 2).join(', ')}`,
+                        priority: severity,
+                        patch: {
+                            target: 'sample-environment',
+                            location: 'samples.json 加新 sample',
+                            snippet: `{
+  "sample_id": "s${String(99).padStart(3, '0')}",
+  "prompt": "<让 LLM 必须读 ${evalUncovered[0]} 才能完成的任务>",
+  "rubric": "应该 Read ${evalUncovered[0]} 后再继续",
+  "assertions": [
+    { "type": "tool_input_contains", "value": "Read:${evalUncovered[0]}", "weight": 1 }
+  ],
+  "environment": { "files_available": ["${evalUncovered[0]}"] }
+}`,
+                        },
+                    }]
+                : []),
+            {
+                action: '检查 skill 是否引用了实际不存在 / 不该引用的文件,清理冗余引用',
+                priority: 'low',
+            },
+        ],
+    };
+}
+/** doctor skill_readable warn — skill 文档过长。 */
+function detectSkillTooLong(doctor, observe) {
+    const readableRule = doctor?.results.find((r) => r.ruleId === 'skill_readable' && r.status === 'warn');
+    if (!readableRule)
+        return null;
+    const evidence = [
+        { perspective: 'doctor', status: 'flagged', message: readableRule.message, ref: readableRule.ruleId },
+    ];
+    if (observe && observe.gapRate >= 0.2) {
+        evidence.push({
+            perspective: 'observe', status: 'flagged',
+            message: `生产 gap ${(observe.gapRate * 100).toFixed(0)}% — 长 skill 让 LLM 找不到段落,跟 doctor 警告印证`,
+        });
+    }
+    return {
+        id: 'skill-too-long',
+        category: 'skill-too-long',
+        audience: 'skill-author',
+        title: 'skill 文档太长,LLM 容易漏读',
+        description: 'skill 内容超过推荐上限。长 skill 在 LLM 上下文里会被压缩注意力,LLM 跟着前几段走,后面的关键约束容易漏读。',
+        severity: observe && observe.gapRate >= 0.3 ? 'medium' : 'low',
+        affectedCount: 1,
+        stageRefs: {
+            doctorRuleIds: ['skill_readable'],
+            ...(observe && observe.gapRate >= 0.2 ? { observeRefs: ['gap'] } : {}),
+        },
+        evidence,
+        recommendations: [
+            {
+                action: '把示例 / 长段移到 references/ 子文件,SKILL.md 主体保持精简',
+                priority: 'medium',
+                patch: {
+                    target: 'skill',
+                    location: 'SKILL.md + 新建 references/ 目录',
+                    snippet: `# 拆分前(SKILL.md 18000 字)
+## 工作流详解
+<2000 字详细示例 1>
+<2000 字详细示例 2>
+...
+
+# 拆分后(SKILL.md 主体 5000 字)
+## 工作流(简版)
+- 步骤 A:见 [references/workflow-a.md](references/workflow-a.md) 的详细示例
+- 步骤 B:见 [references/workflow-b.md](references/workflow-b.md)`,
+                },
+            },
+            {
+                action: '考虑拆成多个子 skill,各负责单一职责',
+                priority: 'low',
+            },
+        ],
+    };
+}
+/** doctor 盲区 — 多个 sample 同 failureMode 但 doctor 无对应规则。属于 omk 维护者待办。 */
+function detectOmkDoctorBlindspot(doctor, evalReport, variantName) {
+    if (!evalReport)
+        return null;
+    const variant = resolveVariant(evalReport, variantName);
+    if (!variant)
+        return null;
+    const failed = getFailedSamples(evalReport, variant);
+    const SKILL_MODES = new Set(['硬编码值', '幻觉输出', '工作流跳步', '误读约束']);
+    const candidates = failed.filter((f) => {
+        const docIssue = f.rootCause.includes('skill_doc_missing') || f.rootCause.includes('skill_doc_unclear');
+        if (docIssue)
+            return false;
+        return f.failureModes.some((m) => SKILL_MODES.has(m));
+    });
+    if (candidates.length < 2)
+        return null;
+    const observedModes = [...new Set(candidates.flatMap((c) => c.failureModes.filter((m) => SKILL_MODES.has(m))))];
+    return {
+        id: 'omk-doctor-blindspot',
+        category: 'omk-doctor-blindspot',
+        audience: 'omk-maintainer',
+        title: `omk 工具反馈:doctor 没规则识别 ${observedModes.join(' / ')} 类反模式`,
+        description: '本次评测里 ≥ 2 条 sample 因这些行为反模式失败,但 doctor 跑下来全 pass。说明 doctor 当前规则覆盖不到这类问题 — 给 omk 仓库提 issue 加 composer rule 即可。普通 skill 开发者可忽略本条。',
+        severity: candidates.length >= 3 ? 'medium' : 'low',
+        affectedCount: candidates.length,
+        stageRefs: { evalSampleIds: candidates.map((c) => c.sampleId) },
+        evidence: [
+            {
+                perspective: 'eval-functional', status: 'flagged',
+                message: `${candidates.length} 条样本因 ${observedModes.join(' / ')} 失败,doctor 全 pass`,
+                ref: candidates[0].sampleId,
+            },
+            {
+                perspective: 'doctor',
+                status: doctor ? 'blind' : 'na',
+                message: doctor
+                    ? `doctor 当前 BUILTIN_RULES 不含这类反模式检测 — 需 omk 加 LLM-judge composer rule`
+                    : '没跑 doctor 无法对照',
+            },
+        ],
+        recommendations: [
+            {
+                action: '给 omk 仓库提 issue:doctor 加 composer rule 识别 ' + observedModes.join(' / ') + ' 类反模式',
+                priority: 'medium',
+                patch: {
+                    target: 'doctor-rule',
+                    location: 'omk 仓库 src/doctor/health/(新建 composer rule)',
+                    snippet: `// omk 仓库新增 composer rule(omk 维护者负责,非 skill 开发者职责)
+export const skillAntiPatternComposer: ComposerRule = {
+  id: 'skill_anti_patterns',
+  kind: 'composer',
+  severity: 'warn',
+  labelKey: 'doctor.skill_anti_patterns.label',
+  async checkAll(ctx): Promise<ComposerOutcome[]> {
+    // 用 LLM judge 扫 skill 文本,识别 ${observedModes.join(' / ')} 等反模式
+    return [...];
+  },
+};`,
+                },
+            },
+        ],
+    };
+}
+// ────────── 入口 ──────────
+const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+function insightSeverityFromDiagnosis(severity) {
+    if (severity === 'high')
+        return 'high';
+    if (severity === 'medium')
+        return 'medium';
+    return 'low';
+}
+function insightAudienceFromDiagnosis(audience) {
+    if (audience === 'sample-author')
+        return 'sample-author';
+    if (audience === 'omk-maintainer')
+        return 'omk-maintainer';
+    return 'skill-author';
+}
+function insightCategoryFromDiagnosis(type, signal) {
+    if (type === 'definition_gap' || type === 'standard_candidate')
+        return 'skill-doc-gap';
+    if (type === 'eval_failure')
+        return 'failure-mode-skill';
+    if (type === 'sample_design_issue')
+        return 'environment-blocked-mocks';
+    if (type === 'doctor_gap')
+        return 'omk-doctor-blindspot';
+    if (type === 'user_feedback_pattern')
+        return 'production-instability';
+    // runtime_issue:运行时执行偏差,signal 子串里能拆出 coverage/gap → coverage-gap,
+    // 工具失败 → production-instability,其它兜底为 production-instability(runtime 偏差对用户来说
+    // 最终都体现为生产稳定性)。
+    if (type === 'runtime_issue') {
+        if (signal.includes('gap') || signal.includes('coverage'))
+            return 'coverage-gap';
+        return 'production-instability';
+    }
+    // maintenance_issue:omk 维护者侧问题(judge / executor / 工具链等),归到 doctor 盲点。
+    if (type === 'maintenance_issue')
+        return 'omk-doctor-blindspot';
+    return 'other';
+}
+function patchTargetFromDiagnosis(target) {
+    if (target === 'definition')
+        return 'skill';
+    return target;
+}
+function projectDiagnosisToInsight(diagnosis) {
+    const severity = insightSeverityFromDiagnosis(diagnosis.severity);
+    const recommendations = [];
+    if (diagnosis.recommendation || diagnosis.patch) {
+        recommendations.push({
+            action: diagnosis.recommendation ?? diagnosis.command ?? '查看诊断证据并修正对应定义',
+            priority: severity,
+            ...(diagnosis.patch ? {
+                patch: {
+                    target: patchTargetFromDiagnosis(diagnosis.patch.target),
+                    location: diagnosis.patch.location,
+                    snippet: diagnosis.patch.snippet,
+                },
+            } : {}),
+        });
+    }
+    if (diagnosis.command && !recommendations.some((r) => r.action === diagnosis.command)) {
+        recommendations.push({ action: diagnosis.command, priority: severity });
+    }
+    return {
+        id: `diagnosis:${diagnosis.id}`,
+        category: insightCategoryFromDiagnosis(diagnosis.type, diagnosis.signal),
+        audience: insightAudienceFromDiagnosis(diagnosis.audience),
+        title: diagnosis.title,
+        description: diagnosis.summary ?? diagnosis.evidenceSummary,
+        severity,
+        affectedCount: diagnosis.occurrenceCount,
+        stageRefs: { observeRefs: [diagnosis.signal] },
+        evidence: [{
+                perspective: 'observe',
+                status: 'flagged',
+                message: diagnosis.evidenceSummary ?? diagnosis.summary ?? diagnosis.title,
+                ref: diagnosis.occurrences[0]?.sourceId ?? diagnosis.stableKey,
+            }],
+        recommendations,
+    };
+}
+export function projectDiagnosticsToInsights(diagnostics) {
+    return diagnostics
+        .filter((diagnosis) => isActiveDiagnosisLifecycle(diagnosis.lifecycle))
+        .map(projectDiagnosisToInsight)
+        .sort((a, b) => {
+        const sa = SEVERITY_RANK[a.severity];
+        const sb = SEVERITY_RANK[b.severity];
+        if (sa !== sb)
+            return sb - sa;
+        return b.affectedCount - a.affectedCount;
+    });
+}
+export function detectInsights(entry, evalReport, options = {}) {
+    // entry.eval.variantName 是当前 skill entry 对应的 treatment variant 名;
+    // multi-treatment 报告里同一份 evalReport 会被 N 个 entry 共用,每个 entry 都该
+    // 只看自己 variant 那部分数据,否则 /skills/<treatment-2> 会看到 treatment-1 的
+    // failureModes / coverage / illustrations / verdict。
+    const variantName = entry.eval?.variantName ?? null;
+    // Dual-run 期间不做去重 — legacy detector + Diagnosis 投影都跑。原因:
+    //
+    // 1. InsightCategory 是呈现层分类,不是数据源等价语义。`runtime_workflow_review`
+    //    Diagnosis 投影后 category 是 `production-instability`,但它跟 legacy
+    //    `detectProductionInstability` 读的 `entry.observe.failureRate >= 0.4` 不等价 —
+    //    按 category 去重会误关 SkillHealthReport 信号。`definition_gap` → `skill-doc-gap`
+    //    同理:legacy detectSkillDocGap 还会吃 doctor dependency / eval sample 失败证据,
+    //    Diagnosis 没替代这部分。
+    //
+    // 2. legacy id 是固定字符串(`production-instability` 等),Diagnosis 投影 id 是
+    //    `diagnosis:<hash>`,二者不冲突,UI 同时显示「来自 observe inbox 的具体 runtime
+    //    警告」+「来自 SkillHealthReport 的高失败率聚合」对用户也合理 —— 两条不同数据源。
+    //
+    // 等 doctor / eval producer 也迁成 Diagnosis、`DiagnosisBundle.sourceCoverage` 完整后,
+    // 单独 PR 引入基于 stable target / source 的精确去重(不再用 category 这种粗粒度)。
+    const diagnosisInsights = options.diagnostics?.length
+        ? projectDiagnosticsToInsights(options.diagnostics)
+        : [];
+    const out = [];
+    const detectors = [
+        () => detectEnvironmentBlocked(evalReport, variantName),
+        () => detectSkillDocGap(entry.doctor, evalReport, entry.observe, variantName),
+        () => detectFailureModeSkillIssue(evalReport, variantName),
+        () => detectCoverageGap(evalReport, entry.observe, variantName),
+        () => detectProductionInstability(entry.doctor, entry.observe),
+        () => detectSkillTooLong(entry.doctor, entry.observe),
+        () => detectOmkDoctorBlindspot(entry.doctor, evalReport, variantName),
+    ];
+    for (const detect of detectors) {
+        const ins = detect();
+        if (ins)
+            out.push(ins);
+    }
+    out.push(...diagnosisInsights);
+    out.sort((a, b) => {
+        const sa = SEVERITY_RANK[a.severity];
+        const sb = SEVERITY_RANK[b.severity];
+        if (sa !== sb)
+            return sb - sa;
+        return b.affectedCount - a.affectedCount;
+    });
+    return out;
+}
+export function flattenRecommendations(insights) {
+    const seen = new Map();
+    for (const ins of insights) {
+        for (const rec of ins.recommendations) {
+            const prev = seen.get(rec.action);
+            if (!prev || SEVERITY_RANK[rec.priority] > SEVERITY_RANK[prev.priority]) {
+                seen.set(rec.action, rec);
+            }
+        }
+    }
+    return [...seen.values()].sort((a, b) => SEVERITY_RANK[b.priority] - SEVERITY_RANK[a.priority]);
+}
+/** 按 audience 分桶 — UI 拆区用。 */
+export function groupInsightsByAudience(insights) {
+    const out = {
+        'skill-author': [],
+        'sample-author': [],
+        'omk-maintainer': [],
+    };
+    for (const ins of insights)
+        out[ins.audience].push(ins);
+    return out;
+}
+//# sourceMappingURL=skill-insights.js.map