oh-my-knowledge 0.33.0 → 0.34.0

package/README.md

@@ -11,6 +11,8 @@
 **Did your prompt actually get better?**
 A/B test your prompts and skills with statistical rigor — bootstrap CI and length-debias on by default, Krippendorff α the moment you add a gold set.
 
+📖 **Full documentation: [oh-my-knowledge.pages.dev](https://oh-my-knowledge.pages.dev)** (searchable, English / 简体中文)
+
 ![omk report — verdict pill "v2 is clearly better than v1 — ready to ship"](./assets/screenshots/report-overview.png)
 
 ## Quick start
@@ -27,10 +29,18 @@ That's it — no editing required. `omk init` scaffolds two skill variants and t
 
 Walkthrough: [5-minute quickstart guide](docs/quickstart-skill-eval.md) (recommended for first-time users).
 
-Deeper: [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors & artifact layout](docs/reference/executors.md)
+Deeper: [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors](docs/reference/executors.md) · [artifact layout](docs/reference/artifact-layout.md)
 
 ## Use inside AI Coding Agents
 
+Install the official omk Agent Skill to let your coding agent run omk workflows from natural language:
+
+```bash
+omk install omk-agent-skill
+```
+
+By default, omk installs only into detected local targets it explicitly supports: Codex/AGENTS when `~/.codex` or `~/.agents` exists, and Claude Code when `~/.claude` exists. Use `--to all` to force every target omk currently knows, or `--dest` for a custom skill root.
+
 ### Use inside Claude Code
 
 When the `omk` skill is available in Claude Code, you can invoke it directly:
@@ -69,7 +79,7 @@ Teams doing knowledge engineering produce lots of knowledge artifacts (skills to
 | Saturation curve | ✓ | ✗ | ✗ | ✗ |
 | Three-layer scoring isolation | ✓ | ✗ | partial | ✗ |
 | Per-variant skill isolation (construct validity) | ✓ default | ✗ | ✗ | ✗ |
-| Native Claude Code skill | ✓ | ✗ | ✗ | ✗ |
+| Native Agent Skill | ✓ | ✗ | ✗ | ✗ |
 | Hosted SaaS dashboard | ✗ | ✗ | ✓ | ✓ |
 
 omk's moat is **default-on safety net** — Bootstrap CI and length-debias aren't advanced flags; they're the default, and judge ↔ human α comes free the moment you add a gold set. Other tools let you opt into confidence intervals; omk makes them unavoidable. Need a hosted SaaS dashboard? Choose LangSmith. Want quick local prompt iteration without statistics? Choose promptfoo. **Shipping to production and someone will ask "why should I trust this number?" Choose omk.**
@@ -101,14 +111,17 @@ RAG-specific evals: see RAGAS (separate niche, complementary to omk). Full compa
 
 ## Documentation
 
+The full docs are published at **[oh-my-knowledge.pages.dev](https://oh-my-knowledge.pages.dev)** — searchable, with an English / 简体中文 switcher. Key pages:
+
 - **[How it works](docs/explanation/architecture.md)** — interleaved scheduling, variant resolution, dual-channel scoring, six-dim report
 - **[Eval sample format](docs/reference/eval-sample-format.md)** — sample schema, scoring formulas, 30+ assertion types, custom JS assertions
-- **[CLI reference](docs/reference/cli.md)** — all seven commands with bash examples and flag tables
-- **[Executors & artifact layout](docs/reference/executors.md)** — built-in / custom executors, agent evaluation, common model configs (Claude / OpenAI / GLM / Qwen / DeepSeek / Moonshot / Ollama)
+- **[CLI reference](docs/reference/cli.md)** — all top-level commands with bash examples and flag tables
+- **[Executors](docs/reference/executors.md)** & **[artifact layout](docs/reference/artifact-layout.md)** — built-in / custom executors; how `variant` resolves to an artifact + runtime context
+- **[How-to guides](docs/guides/agent-eval.md)** — [evaluate an agent](docs/guides/agent-eval.md) (project runtime context) and [use non-Claude models](docs/guides/non-claude-models.md) (GLM / Qwen / DeepSeek / Moonshot / Ollama)
 - **[Quickstart](docs/quickstart-skill-eval.md)** — first-time five-minute walkthrough
 - **[Sample design spec](docs/specs/sample-design-spec.md)** — capability / construct / provenance metadata; industry-gap mapping
 - **[Statistical rigor](docs/explanation/statistical-rigor.md)** — why bootstrap CI / α / length-debias / saturation matter
-- **[Comparison with 7 tools](docs/reference/comparison.md)** — 25+ dimensions across promptfoo / DeepEval / LangSmith / Langfuse / Braintrust etc.
+- **[Comparison with 7 tools](docs/reference/comparison.md)** — 25+ dimensions across promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai
 
 ## Environment variables
 

package/README.zh.md

@@ -11,6 +11,8 @@
 **你改完 prompt，真的变好了吗？**
 用统计严谨性 A/B 测试你的 prompt 和 skill —— Bootstrap 置信区间、长度去偏默认开，配一份人工 gold 就自动算 Krippendorff α。
 
+📖 **完整文档：[oh-my-knowledge.pages.dev/zh](https://oh-my-knowledge.pages.dev/zh/)**（可搜索，可切换英文）
+
 ![omk 报告 — verdict pill「v2 明显优于 v1，可以发布」](./assets/screenshots/report-overview-zh.png)
 
 ## 快速开始
@@ -27,10 +29,18 @@ omk eval --control code-review-v1 --treatment code-review-v2
 
 手把手教程：[5 分钟快速上手](docs/zh/quickstart-skill-eval.md)（推荐第一次跑评测的用户）。
 
-深入：[CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测样本格式](docs/zh/reference/eval-sample-format.md) · [执行器与 artifact 布局](docs/zh/reference/executors.md)
+深入：[CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [artifact 布局](docs/zh/reference/artifact-layout.md)
 
 ## 在 AI Coding Agent 中使用
 
+安装 omk 官方 Agent Skill 后，可以直接用自然语言让 coding agent 跑 omk 工作流：
+
+```bash
+omk install omk-agent-skill
+```
+
+默认只会安装到本机已检测到、且 omk 明确支持的目标：检测到 `~/.codex` 或 `~/.agents` 时写入 Codex/AGENTS，检测到 `~/.claude` 时写入 Claude Code。要强制写入当前 omk 已知的全部目标，用 `--to all`；要指定自定义 skill 根目录，用 `--dest`。
+
 ### 在 Claude Code 中使用
 
 当 `omk` skill 已在 Claude Code 中可用时，可以直接这样调用：
@@ -69,7 +79,7 @@ omk sample skills/my-skill.md
 | 饱和曲线 | ✓ | ✗ | ✗ | ✗ |
 | 三层独立评分 | ✓ | ✗ | 部分 | ✗ |
 | 用例隔离(construct validity) | ✓ 默认 | ✗ | ✗ | ✗ |
-| 原生 Claude Code skill | ✓ | ✗ | ✗ | ✗ |
+| 原生 Agent Skill | ✓ | ✗ | ✗ | ✗ |
 | 托管 SaaS 看板 | ✗ | ✗ | ✓ | ✓ |
 
 omk 的护城河是 **default-on 安全网** —— Bootstrap CI / 长度去偏不是 advanced flag，是默认行为；评委 ↔ 人工 α 只要给一份 gold 集就自动算。其他工具让你**手动**接置信区间；omk 让你**默认无法忽略**它。需要 SaaS 看板？选 LangSmith。要快速 prompt 迭代不要统计层？选 promptfoo。**要发到生产且会被问「为什么应该相信这个数字」？选 omk。**
@@ -90,7 +100,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 | **线上 session 观测** | 解析 Claude Code session JSONL，测量各 skill 的失败率、耗时、token 成本、知识缺口信号 |
 | **知识缺口识别** | 严重度加权的信号量化风险敞口，不宣称完备性 |
 | **用例隔离 (construct validity)** | `--strict-baseline`（默认开）三堵 baseline 拿到被测 skill 的污染路径 |
-| **用例设计科学性** | Sample schema 加 `capability` / `difficulty` / `construct` / `provenance` 元数据字段（HF Dataset Cards 风），studio 输出 coverage 分桶 + `rubric_clarity_low` / `capability_thin` issue。[docs/specs/sample-design-spec.md](docs/specs/sample-design-spec.md) |
+| **用例设计科学性** | Sample schema 加 `capability` / `difficulty` / `construct` / `provenance` 元数据字段（HF Dataset Cards 风），studio 输出 coverage 分桶 + `rubric_clarity_low` / `capability_thin` issue。[docs/zh/specs/sample-design-spec.md](docs/zh/specs/sample-design-spec.md) |
 | **多评委 ensemble** | `--judge-models claude:opus,openai:gpt-4o` 跨厂商评分 + agreement 度量 |
 | **盲测 A/B** | `--blind` 隐藏变体名称，HTML 报告有揭晓按钮 |
 | **多轮方差分析** | `--repeat N` 重复 N 次，计算均值/标准差/置信区间/t 检验 |
@@ -101,14 +111,17 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 
 ## 文档
 
+完整文档已发布到 **[oh-my-knowledge.pages.dev/zh](https://oh-my-knowledge.pages.dev/zh/)** —— 可搜索，可切换英文。重点页面：
+
 - **[工作原理](docs/zh/explanation/architecture.md)** —— 交错调度、variant 解析、双通道评分、六维报告
-- **[评测样本格式](docs/zh/reference/eval-sample-format.md)** —— sample schema、评分公式、30+ 断言类型、自定义 JS 断言
-- **[CLI 参考](docs/zh/reference/cli.md)** —— 7 个命令的 bash 示例和 flag 表
-- **[执行器与 artifact 布局](docs/zh/reference/executors.md)** —— 内置 / 自定义执行器、Agent 评测、常见模型配置（Claude / OpenAI / GLM / 通义 / DeepSeek / Moonshot / Ollama）
+- **[评测用例格式](docs/zh/reference/eval-sample-format.md)** —— sample schema、评分公式、30+ 断言类型、自定义 JS 断言
+- **[CLI 参考](docs/zh/reference/cli.md)** —— 顶层命令的 bash 示例和 flag 表
+- **[执行器](docs/zh/reference/executors.md)** & **[artifact 布局](docs/zh/reference/artifact-layout.md)** —— 内置 / 自定义执行器；variant 如何解析为 artifact + runtime context
+- **[操作指南](docs/zh/guides/agent-eval.md)** —— [评测 agent](docs/zh/guides/agent-eval.md)（项目 runtime context）与[使用非 Claude 模型](docs/zh/guides/non-claude-models.md)（GLM / 通义 / DeepSeek / Moonshot / Ollama）
 - **[快速上手](docs/zh/quickstart-skill-eval.md)** —— 第一次跑评测的 5 分钟教程
-- **[用例设计规范](docs/specs/sample-design-spec.md)** —— capability / construct / provenance 元数据；行业 gap 映射
+- **[用例设计规范](docs/zh/specs/sample-design-spec.md)** —— capability / construct / provenance 元数据；行业 gap 映射
 - **[统计严谨性](docs/zh/explanation/statistical-rigor.md)** —— 为什么 Bootstrap CI / α / 长度去偏 / 饱和曲线重要
-- **[7 工具对比](docs/zh/reference/comparison.md)** —— promptfoo / DeepEval / LangSmith / Langfuse / Braintrust 等 25+ 维度横评
+- **[7 工具对比](docs/zh/reference/comparison.md)** —— promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai 等 25+ 维度横评
 
 ## 环境变量
 
@@ -130,7 +143,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 | 功能 | 风险 | 适用场景 |
 |------|------|----------|
 | **自定义断言**（`custom`） | 动态加载并执行用户指定的 `.mjs` 文件 | 仅使用自己编写或审查过的断言文件 |
-| **eval-samples.json** | 断言配置可引用外部文件路径 | 不要使用来源不明的样本文件 |
+| **eval-samples.json** | 断言配置可引用外部文件路径 | 不要使用来源不明的用例文件 |
 
 **建议：**
 

package/dist/analysis/coverage-analyzer.d.ts

@@ -54,4 +54,3 @@ export declare function computeCoverage(results: ResultEntry[], variant: string,
  * Returns a map of variant → CoverageReport.
  */
 export declare function computeReportCoverage(report: Report, artifactContents: Record<string, string | null>, cwds: Record<string, string | null>): Record<string, CoverageReport>;
-//# sourceMappingURL=coverage-analyzer.d.ts.map

package/dist/analysis/coverage-analyzer.js

@@ -259,4 +259,3 @@ export function computeReportCoverage(report, artifactContents, cwds) {
     }
     return coverageMap;
 }
-//# sourceMappingURL=coverage-analyzer.js.map

package/dist/analysis/failure-clusterer.d.ts

@@ -93,4 +93,3 @@ export interface FailureClusterReport {
 }
 export declare function clusterFailures(req: FailureClusterRequest): Promise<FailureClusterReport>;
 export declare function formatFailureClusterReport(r: FailureClusterReport): string;
-//# sourceMappingURL=failure-clusterer.d.ts.map

package/dist/analysis/failure-clusterer.js

@@ -295,4 +295,3 @@ export function formatFailureClusterReport(r) {
     lines.push('');
     return lines.join('\n');
 }
-//# sourceMappingURL=failure-clusterer.js.map

package/dist/analysis/gap-analyzer.d.ts

@@ -118,4 +118,3 @@ export declare function applyHedgingClassifierToReports(reports: Record<string,
     reports: Record<string, GapReport>;
     costUSD: number;
 }>;
-//# sourceMappingURL=gap-analyzer.d.ts.map

package/dist/analysis/gap-analyzer.js

@@ -468,4 +468,3 @@ export async function applyHedgingClassifierToReports(reports, executor, opts) {
     }
     return { reports: out, costUSD: totalCost };
 }
-//# sourceMappingURL=gap-analyzer.js.map

package/dist/analysis/hedging-classifier.d.ts

@@ -31,4 +31,3 @@ export declare function clearHedgingCache(): void;
  * 失败降级:单批 LLM 调用 / 解析失败 → 该 batch 全部 isUncertainty=true (保守保留)。
  */
 export declare function classifyHedgingCandidates(candidates: HedgingCandidate[], executor: ExecutorFn, opts?: ClassifyOptions): Promise<ClassifyResult>;
-//# sourceMappingURL=hedging-classifier.d.ts.map

package/dist/analysis/hedging-classifier.js

@@ -12,7 +12,7 @@
 import { createHash } from 'node:crypto';
 const DEFAULT_MAX_CANDIDATES = 50;
 const DEFAULT_BATCH_SIZE = 10;
-const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+const DEFAULT_MODEL = 'claude-haiku-4-5';
 // in-memory cache,进程内复用。key = sha256(sentence)。
 const verdictCache = new Map();
 export function clearHedgingCache() {
@@ -141,4 +141,3 @@ export async function classifyHedgingCandidates(candidates, executor, opts) {
     }
     return { verdicts, costUSD, truncated };
 }
-//# sourceMappingURL=hedging-classifier.js.map

package/dist/analysis/report-diagnostics.d.ts

@@ -31,4 +31,3 @@ export declare function analyzeResults(report: Report, opts?: AnalyzeResultsOpti
  */
 export declare function buildSampleQualityAggregate(samples: Sample[]): SampleQualityAggregate;
 export declare function generateAnalysisSummary(report: Report, lang?: Lang): string | undefined;
-//# sourceMappingURL=report-diagnostics.d.ts.map

package/dist/analysis/report-diagnostics.js

@@ -750,4 +750,3 @@ function detectHighCost(results, variants, insights) {
         });
     }
 }
-//# sourceMappingURL=report-diagnostics.js.map

package/dist/analysis/sample-diagnostics.d.ts

@@ -28,7 +28,7 @@ export type SampleIssueKind = 'flat_scores' | 'all_pass' | 'all_fail' | 'near_du
 export interface SampleIssue {
     sample_id: string;
     severity: 'error' | 'warning' | 'info';
-    kind: SampleIssueKind;
+    issueKind: SampleIssueKind;
     /** Minimal evidence to make the issue actionable. */
     evidence: Record<string, unknown>;
 }
@@ -82,4 +82,3 @@ export declare function formatSampleDiagnostics(diag: SampleDiagnosticReport, op
     lang?: DiagnosticLang;
 }): string;
 export {};
-//# sourceMappingURL=sample-diagnostics.d.ts.map

package/dist/analysis/sample-diagnostics.js

@@ -69,19 +69,19 @@ export function diagnoseSamples(report, options = {}) {
             const min = Math.min(...scores);
             if (max === 5 && min === 5) {
                 issues.push({
-                    sample_id: entry.sample_id, severity: 'info', kind: 'all_pass',
+                    sample_id: entry.sample_id, severity: 'info', issueKind: 'all_pass',
                     evidence: { scores: scoresMap(entry, variants) },
                 });
             }
             else if (max === 1 && min === 1) {
                 issues.push({
-                    sample_id: entry.sample_id, severity: 'error', kind: 'all_fail',
+                    sample_id: entry.sample_id, severity: 'error', issueKind: 'all_fail',
                     evidence: { scores: scoresMap(entry, variants) },
                 });
             }
             else if (max - min < opt.flatThreshold) {
                 issues.push({
-                    sample_id: entry.sample_id, severity: 'warning', kind: 'flat_scores',
+                    sample_id: entry.sample_id, severity: 'warning', issueKind: 'flat_scores',
                     evidence: { scores: scoresMap(entry, variants), spread: Number((max - min).toFixed(2)), threshold: opt.flatThreshold },
                 });
             }
@@ -89,7 +89,7 @@ export function diagnoseSamples(report, options = {}) {
         // Errored on at least one variant — sample may be broken (env / executor / fixture).
         if (errors > 0) {
             issues.push({
-                sample_id: entry.sample_id, severity: errors === variants.length ? 'error' : 'warning', kind: 'error_prone',
+                sample_id: entry.sample_id, severity: errors === variants.length ? 'error' : 'warning', issueKind: 'error_prone',
                 evidence: { errorCount: errors, variantCount: variants.length },
             });
         }
@@ -97,7 +97,7 @@ export function diagnoseSamples(report, options = {}) {
         const maxStddev = judgeStddevs.length > 0 ? Math.max(...judgeStddevs) : 0;
         if (maxStddev >= opt.ambiguousStddev) {
             issues.push({
-                sample_id: entry.sample_id, severity: 'warning', kind: 'ambiguous_rubric',
+                sample_id: entry.sample_id, severity: 'warning', issueKind: 'ambiguous_rubric',
                 evidence: { maxStddev: Number(maxStddev.toFixed(2)), threshold: opt.ambiguousStddev, stddevs: judgeStddevs.map((s) => Number(s.toFixed(2))) },
             });
         }
@@ -110,13 +110,13 @@ export function diagnoseSamples(report, options = {}) {
     for (const s of sampleStats) {
         if (medianCost > 0 && s.cost >= opt.costOutlierK * medianCost) {
             issues.push({
-                sample_id: s.entry.sample_id, severity: 'info', kind: 'cost_outlier',
+                sample_id: s.entry.sample_id, severity: 'info', issueKind: 'cost_outlier',
                 evidence: { cost: Number(s.cost.toFixed(4)), medianCost: Number(medianCost.toFixed(4)), multiplier: opt.costOutlierK },
             });
         }
         if (medianLatency > 0 && s.latencyMs >= opt.latencyOutlierK * medianLatency) {
             issues.push({
-                sample_id: s.entry.sample_id, severity: 'info', kind: 'latency_outlier',
+                sample_id: s.entry.sample_id, severity: 'info', issueKind: 'latency_outlier',
                 evidence: { latencyMs: s.latencyMs, medianMs: medianLatency, multiplier: opt.latencyOutlierK },
             });
         }
@@ -145,7 +145,7 @@ export function diagnoseSamples(report, options = {}) {
                         continue;
                     seenPair.add(key);
                     issues.push({
-                        sample_id: prompts[i].id, severity: 'warning', kind: 'near_duplicate',
+                        sample_id: prompts[i].id, severity: 'warning', issueKind: 'near_duplicate',
                         evidence: { duplicateOf: prompts[j].id, rouge1: Number(score.toFixed(2)), threshold: opt.duplicateRouge },
                     });
                 }
@@ -170,7 +170,7 @@ export function diagnoseSamples(report, options = {}) {
             if (containsRubricGradeKeyword(rubric))
                 continue;
             issues.push({
-                sample_id: entry.sample_id, severity: 'info', kind: 'rubric_clarity_low',
+                sample_id: entry.sample_id, severity: 'info', issueKind: 'rubric_clarity_low',
                 evidence: { rubricLength: rubric.length, rubricSnippet: rubric.slice(0, 80) },
             });
         }
@@ -205,7 +205,7 @@ export function diagnoseSamples(report, options = {}) {
                 // 报警挂在该 capability 的第一个 sample 上(便于定位),其他在 evidence 里列。
                 const primarySampleId = info.sampleIds[0];
                 issues.push({
-                    sample_id: primarySampleId, severity: 'warning', kind: 'capability_thin',
+                    sample_id: primarySampleId, severity: 'warning', issueKind: 'capability_thin',
                     evidence: { capability: cap, sampleCount: info.count, threshold, sampleIds: info.sampleIds },
                 });
             }
@@ -215,10 +215,10 @@ export function diagnoseSamples(report, options = {}) {
     issues.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.sample_id.localeCompare(b.sample_id));
     const byKind = {};
     for (const i of issues) {
-        if (!byKind[i.kind])
-            byKind[i.kind] = [];
-        if (!byKind[i.kind].includes(i.sample_id))
-            byKind[i.kind].push(i.sample_id);
+        if (!byKind[i.issueKind])
+            byKind[i.issueKind] = [];
+        if (!byKind[i.issueKind].includes(i.sample_id))
+            byKind[i.issueKind].push(i.sample_id);
     }
     const totals = {
         samples: results.length,
@@ -301,7 +301,7 @@ function evidenceString(evidence, key, fallback = '') {
 }
 export function formatSampleIssue(issue, lang = 'zh') {
     const evidence = issue.evidence;
-    switch (issue.kind) {
+    switch (issue.issueKind) {
         case 'all_pass':
             return lang === 'zh'
                 ? '所有 variant 得分均为 5——用例可能太简单或断言过宽'
@@ -371,8 +371,8 @@ export function formatSampleIssue(issue, lang = 'zh') {
         }
         default:
             return lang === 'zh'
-                ? `结构化诊断：${issue.kind}`
-                : `Structured diagnostic: ${issue.kind}`;
+                ? `结构化诊断：${issue.issueKind}`
+                : `Structured diagnostic: ${issue.issueKind}`;
     }
 }
 /**
@@ -401,7 +401,7 @@ export function formatSampleDiagnostics(diag, options = {}) {
         if (ids.length === 0)
             continue;
         lines.push(`  [${kind}] ${ids.length} sample(s)`);
-        const matching = diag.issues.filter((i) => i.kind === kind);
+        const matching = diag.issues.filter((i) => i.issueKind === kind);
         const display = topN ? matching.slice(0, topN) : matching;
         for (const issue of display) {
             const sev = issue.severity === 'error' ? '✗' : issue.severity === 'warning' ? '⚠' : 'ℹ';
@@ -455,4 +455,3 @@ export function formatSampleDiagnostics(diag, options = {}) {
     lines.push('');
     return lines.join('\n');
 }
-//# sourceMappingURL=sample-diagnostics.js.map

package/dist/analysis/saturation.d.ts

@@ -90,4 +90,3 @@ export declare function findSaturationPoint(cumulativeScores: number[][], method
  * Use this when feeding `runMultiple` results to `findSaturationPoint`.
  */
 export declare function buildCumulativeScores(runs: number[][]): number[][];
-//# sourceMappingURL=saturation.d.ts.map

package/dist/analysis/saturation.js

@@ -179,4 +179,3 @@ export function buildCumulativeScores(runs) {
     }
     return out;
 }
-//# sourceMappingURL=saturation.js.map

package/dist/assets/agent-skills/omk/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: omk
+description: |
+  oh-my-knowledge 知识载体评测工具的智能代理。评测 skill（系统提示词）质量，对比不同版本效果，自动迭代改进。
+  Use when: 用户提到"评测"、"测评"、"eval"、"benchmark"、"对比 skill"、"改进 skill"、"evolve"、"生成测试用例"、"gen-samples"、"omk"。
+user-invocable: true
+argument-hint: "<doctor|eval|evolve|init|install|observe|sample|studio> [options]"
+---
+
+# OMK — 知识载体评测
+
+你是 oh-my-knowledge（omk）的智能代理。帮助用户评测、对比、改进 AI skill（系统提示词），用数据说话。
+
+## 第一步：检查环境
+
+运行 `which omk` 检查是否已安装。如果未安装，告诉用户：
+
+```
+npm i oh-my-knowledge -g
+```
+
+omk CLI 顶层命令包括：`init` / `install` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
+
+## 第二步：理解用户意图
+
+根据用户的描述，匹配对应的操作：
+
+| 用户意图 | 操作 |
+|---------|------|
+| 评测 / 对比 skill | → `omk eval` |
+| 改进 / 优化 skill | → `omk evolve`（自动多轮迭代） |
+| 生成测试用例 | → `omk sample` |
+| 体检 skill 写法 | → `omk doctor` |
+| 查看 / 浏览报告 | → `omk studio`（启动本地报告浏览器） |
+| 看真实使用 trace | → `omk observe` |
+
+如果用户意图不明确，先扫描当前项目结构（skills/ 目录和 eval-samples 文件），然后推荐最合适的操作。
+
+## 第三步：检测项目结构
+
+使用 Glob 和 Read 工具检查：
+
+1. `skills/` 目录下有哪些 skill 文件（`.md` 或 `*/SKILL.md`）
+2. 是否存在 `eval-samples.json` / `eval-samples.yaml` / `eval-samples.yml` / `<skill>/.omk/samples.json`（推荐的标准位置）
+3. 是否有 `skills/*.eval-samples.json`（每 skill 配对文件 → `--batch` 模式）
+
+根据检测结果决定：
+
+- 多个 skill + 各自的 eval-samples → 建议 `--batch` 批量模式
+- 多个 skill + 共享 eval-samples → 建议版本对比模式
+- 只有一个 skill → 建议 `baseline` 对照（`omk eval --control baseline --treatment <skill>`）或 `omk evolve` 改进
+- 没有 eval-samples → 先 `omk sample <skill>` 生成
+
+## 第四步：执行操作
+
+### 评测 skill
+
+```bash
+# 单 skill 必要性测试（有 skill vs 没 skill）
+omk eval --control baseline --treatment my-skill
+
+# 版本 A/B 对比
+omk eval --control my-skill-v1 --treatment my-skill-v2
+
+# 对比 git 历史里的版本跟当前
+omk eval --control git:my-skill --treatment my-skill
+
+# 批量评测：每个 skill 独立 vs baseline
+omk eval --batch
+
+# 先预览任务计划再执行
+omk eval --control v1 --treatment v2 --dry-run
+
+# 复杂配置走 eval.yaml
+omk eval --config eval.yaml
+```
+
+常用选项：
+
+- `--model <name>` 任务执行模型（默认 opus；省钱用 sonnet / haiku）
+- `--effort <low|medium|high|xhigh|max>` 执行模型扩展思考预算（默认 low；跨 effort 报告不严格可比）
+- `--judge-models <executor:model[,...]>` 评委配置（默认 claude:haiku，≥ 2 条 = ensemble）
+- `--concurrency <n>` 并发数
+- `--skip-doctor` 跳过 doctor preflight 门禁（默认 doctor 会先跑一次卡掉 skill 写法大问题）
+- `--no-diagnostic` 关掉 diagnostic 诊断 LLM 调用（默认开启，给 failed sample 出「哪错了 + 怎么改」建议）
+- `--no-judge` 关掉评委主观评分（保留断言层）
+
+### 自动迭代改进
+
+```bash
+omk evolve skills/my-skill.md --rounds 5
+omk evolve skills/my-skill.md --rounds 10 --target 4.5
+# 严格留出 + 锁定 test：按 val 显著性接受、收尾给无偏泛化分
+omk evolve skills/my-skill.md --holdout-ratio 0.2 --test-ratio 0.2
+```
+
+evolve 默认开**显著性接受门**：候选只在相对当前最优**统计显著更好**时才被接受（`bootstrapDiffCI` 的 95% CI 排除 0），而不是「分数高一点点就收」—— 拒绝与评委噪声不可分的提升。决策样本太少时退回点估计并 warn；`--no-significance-gate` 可关。配 `--holdout-ratio` 留出 val 选择集、`--test-ratio` 再锁一份全程不参与选择的 test 集，收尾读一次给无偏泛化分。改动过大的候选评测前直接判拒（`--edit-budget`，默认 0.2）。
+
+**重要：evolve 必须在前台运行（不要用 `run_in_background`）。** 原因：evolve 自带实时进度输出，每个 sample 执行时会打印 `[1/5] s001/... ⏳ 执行中...`，每轮完成会打印 `Round N: score=... ✓ ACCEPT / ✗ REJECT`。前台运行时用户能实时看到这些进度，无需手动询问。设置足够长的 timeout（建议 600000ms）以确保命令不会中途超时。
+
+### 生成测试用例
+
+```bash
+# 为单个 skill 生成
+omk sample skills/my-skill.md
+
+# 显式指定数量（不指定时 LLM 根据 skill 类型自动决定 4-8 条）
+omk sample skills/my-skill.md --count 8
+
+# 自然语言指定重点覆盖场景
+omk sample skills/my-skill.md --focus "重点覆盖搜索失败 / 权限拒绝 / 跨工具 fallback 路径"
+
+# 为 skill 目录下所有缺测试集的 skill 批量生成
+omk sample --batch
+```
+
+输出位置：`<skill>/SKILL.md` 风格 → `<skill>/.omk/samples.json`（标准），其他 `.md` 路径 → 当前目录 `eval-samples.json`（兜底）。
+
+### 体检 skill 写法
+
+```bash
+# 全量体检（含 LLM-judge 维度）
+omk doctor
+
+# 只跑静态检查不调 LLM
+omk doctor --static-only
+
+# 针对单 skill
+omk doctor skills/my-skill.md
+```
+
+`omk eval` 默认会先跑一次 doctor 当 preflight 门禁，所以一般不用单独跑；想在 eval 之前先把结构问题先扫一遍再跑评测，就单独跑 `omk doctor`。
+
+### 查看 / 浏览报告
+
+```bash
+omk studio                                # 启动本地 web 报告浏览器
+omk studio --port 8080                    # 改端口
+omk studio --host 0.0.0.0                 # 局域网访问（默认 127.0.0.1）
+omk studio --no-open                      # 不自动开浏览器
+```
+
+Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势；详情页（`/skills/<name>`）左栏列关键问题清单，右栏画健康趋势 + 三档阶段卡（doctor / eval / observe）。访问 `/observations/inbox` 查看 observe inbox 看板。
+
+## 第五步：解读结果
+
+`omk eval` 跑完会自动启动 studio 并输出 JSON 结果。你需要用自然语言总结关键发现：
+
+### 版本对比模式
+
+总结要包含：
+
+1. **结论**：verdict 是 PROGRESS / NOISE / REGRESSION / CAUTIOUS，哪个 variant 更好
+2. **质量分数**：各 variant 的平均综合分（0-5 分）+ Δ + 95% CI
+3. **成本对比**：token 消耗、execCostUSD、判官花费、diagnostic 花费
+4. **低分样本**：哪些样本两个版本差异最大，rubric 期望 vs 实际差在哪
+5. **建议**：基于数据给出的下一步行动建议
+
+示例输出：
+
+```
+v2 比 v1 更好（verdict: PROGRESS，Δ=+0.7，95% CI [+0.3, +1.1]）：
+- 质量：v2 平均 4.5 分 vs v1 平均 3.8 分（+18%）
+- 成本：v2 略高（$0.15 vs $0.12），因为输出更详细
+- 亮点：v2 在 s002（错误处理）上显著提升（2.5 → 4.5），因为新增了"列出所有缺失的错误处理场景"指令
+- 建议：v2 可以上线，但 s003（XSS 检测）仍然有提升空间
+```
+
+### evolve 模式
+
+总结进化过程：起始分数 → 最终分数，接受 / 拒绝了哪些改进，总花费。如果用户想看具体改了什么，引导查看 `skills/evolve/` 目录下的版本文件。
+
+### 批量评测模式（`--batch`）
+
+列出每个 skill 的 baseline 分 vs skill 分和提升幅度，高亮表现最好和最差的 skill。
+
+## 指定工作目录（cwd）
+
+当评测用例需要模型读取特定仓库的代码时，可在 sample 中设置 `cwd` 字段：
+
+```yaml
+- sample_id: task-001
+  prompt: "实现用户登录功能，要求支持手机号和邮箱两种方式"
+  cwd: "/path/to/target-repo"
+  assertions:
+    - type: contains_all
+      values: ["auth.ts", "login.tsx"]
+```
+
+`cwd` 会作为 executor 的工作目录，`claude -p` 将在该目录下运行，能自动读取仓库代码。适用于「给一个任务 query，断言应该修改哪些文件」的 A/B 评测场景。
+
+## 注意事项
+
+- 评测需要调用 LLM，会产生费用。运行前告知用户预估成本（样本数 × 变体数 × 约 $0.01-0.05 美元 / 次）
+- 首次使用建议先 `--dry-run` 预览任务计划
+- `evolve` 命令会修改原始 skill 文件，原始版本保存在 `skills/evolve/*.r0.md`
+- 详细命令参考见 [commands.md](references/commands.md)