oh-my-knowledge 0.38.0 → 0.40.0

package/dist/assets/agent-skills/omk/references/commands.md

@@ -403,6 +403,7 @@ omk observe [sessionsDir] [flags]
 
 **Flags:**
 
+- `--feedback` `boolean`:把生产健康观测反哺已纳管的同名 skill（--no-feedback 关闭）
 - `--from` `option`:起始时间 ISO，优先级高于 --last
 - `--global` `boolean`:写全局 ~/.oh-my-knowledge/observe-health，而非项目 .omk/observe-health
 - `--kb` `option`:知识库 root，启用 KB-aware 分析
@@ -584,6 +585,7 @@ omk sample [skillPath] [flags]
 
 **Flags:**
 
+- `--append` `boolean`:在已有用例文件上追加新生成的用例（撞 sample_id 自动加后缀去重，保留原 json/yaml 格式）。仅单 skill 模式，不支持 --batch / --from-traces / --fix。不传则已有文件时报错保护。常配 --focus 补特定场景。
 - `--batch` `boolean`:批量模式：扫 --skill-dir 下所有缺 samples 的 skill，逐个生成。
 - `--count` `option`:生成用例条数。不传由 LLM 按 skill 类型自动决定。
 - `--executor` `option`:执行器名，默认 claude（同 omk eval / doctor / evolve）。指定 codex 等其它执行器时，记得连带传一个该执行器能识别的 --model。

package/dist/authoring/evolver.js

@@ -868,11 +868,15 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
         // Significance accept gate: accept only when the candidate is *significantly*
         // above the current best on the decision (val) set, not merely numerically higher
         // — rejecting gains indistinguishable from judge noise. `lastReport` is the current
-        // best's fresh eval and `candidateReport` the candidate's, over the same samples;
-        // bootstrapDiffCI resamples the two arrays independently (conservative — not a paired
-        // bootstrap). Under-powered decision sets degrade to the legacy point-estimate accept
-        // (note: that path compares the prior-round best scalar, not this fresh re-eval) and
-        // flag `gate.underpowered`.
+        // best's fresh eval and `candidateReport` the candidate's, over the same samples.
+        // **Deliberately UNPAIRED here** (independent resampling, `decideAccept` → `bootstrapDiffCI`),
+        // unlike the report verdict / debias which switched to `bootstrapPairedDiffCI`: this is an
+        // *optimization accept-gate*, and the unpaired bootstrap's wider, conservative CI is the
+        // wanted bias — it raises the bar to accept, so evolve does not chase paired-tightened,
+        // marginally-significant gains that risk overfitting the decision set. Power is not the goal
+        // for de-/escalation gates; not accepting noise is. Under-powered decision sets degrade to the
+        // legacy point-estimate accept (note: that path compares the prior-round best scalar, not this
+        // fresh re-eval) and flag `gate.underpowered`.
         const valIds = split ? split.valIds : new Set(allSampleIds);
         const bestScores = perSampleComposite(lastReport, lastVariantKey, valIds);
         const candScores = perSampleComposite(candidateReport, candidateVariantKey, valIds);

package/dist/cli/commands/list.d.ts

@@ -2,7 +2,10 @@ import { BaseCommand } from '../oclif/base-command.js';
 import { sanitizeCell } from '../lib/cell-format.js';
 import { type ManagedListRow } from '../../managed/index.js';
 import type { CliLang } from '../lib/i18n.js';
-/** CJK 全角字符按 2 列计宽,使含中文表头的列也能对齐。 */
+/** CJK 全角字符 + 星平面 emoji 按 2 列计宽,使含中文表头 / emoji 标记(如 🔬)的列也能对齐。
+ *  逐**码点**迭代(for...of),星平面 emoji 是单码点,加 `\u{1F300}-\u{1FAFF}`(含 🔬 U+1F52C)判 2 列。
+ *  注:`⚠️` 是「U+26A0 + U+FE0F」两码点、各 1 列合计 2,本就与 2 列渲染对齐,不另判(避免重复计数);
+ *  `✓`(U+2713)终端按 1 列渲染、保持 1。 */
 export declare function dispWidth(s: string): number;
 /** 按**显示宽度**截断(不是 code unit):逐码点累加 dispWidth,绝不切断 surrogate 对、CJK 也不溢出列。 */
 export declare function truncate(s: string, max: number): string;

package/dist/cli/commands/list.js

@@ -4,11 +4,14 @@ import { BaseCommand } from '../oclif/base-command.js';
 import { tCli } from '../lib/i18n.js';
 import { sanitizeCell } from '../lib/cell-format.js';
 import { globalManagedDir, listManagedRows, managedDir, resolveManagedDir, } from '../../managed/index.js';
-/** CJK 全角字符按 2 列计宽,使含中文表头的列也能对齐。 */
+/** CJK 全角字符 + 星平面 emoji 按 2 列计宽,使含中文表头 / emoji 标记(如 🔬)的列也能对齐。
+ *  逐**码点**迭代(for...of),星平面 emoji 是单码点,加 `\u{1F300}-\u{1FAFF}`(含 🔬 U+1F52C)判 2 列。
+ *  注:`⚠️` 是「U+26A0 + U+FE0F」两码点、各 1 列合计 2,本就与 2 列渲染对齐,不另判(避免重复计数);
+ *  `✓`(U+2713)终端按 1 列渲染、保持 1。 */
 export function dispWidth(s) {
     let w = 0;
     for (const ch of s)
-        w += /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/.test(ch) ? 2 : 1;
+        w += /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1F300}-\u{1FAFF}]/u.test(ch) ? 2 : 1;
     return w;
 }
 function pad(s, width) {
@@ -45,7 +48,9 @@ export function renderTable(rows, lang) {
         truncate(sanitizeCell(r.name), 40), // name 与 source 同为用户可控、可超长 → 同样按显示宽度截断,防撑爆表宽
         r.kind, // ArtifactKind 枚举(validator 已收窄),无需洗
         // 不可达 → 标「?」(drift 未核),绝不冒充 stale;reachable 且漂移才 stale ⚠️;已人工接受标 promoted ✓。
-        !r.reachable ? `${r.state} ?` : r.state === 'stale' ? 'stale ⚠️' : r.state === 'promoted' ? 'promoted ✓' : r.state,
+        // 生产盲区 🔬 与生命周期**正交**(observe 量线上部署版),叠加在 state token 之后,不替换 state。
+        (!r.reachable ? `${r.state} ?` : r.state === 'stale' ? 'stale ⚠️' : r.state === 'promoted' ? 'promoted ✓' : r.state)
+            + (r.productionGap ? ' 🔬' : ''),
         r.latestVerdict ? sanitizeCell(r.latestVerdict) : '—',
         `${r.currentEvidenceCount}/${r.totalEvidenceCount}`,
         truncate(sanitizeCell(r.sourceLabel), 48),
@@ -99,7 +104,8 @@ export default class List extends BaseCommand {
             const hasDrift = rows.some((r) => r.drifted);
             const hasUnreachable = rows.some((r) => !r.reachable);
             const hasPromoted = rows.some((r) => r.state === 'promoted');
-            if (hasDrift || hasUnreachable || hasPromoted)
+            const hasProductionGap = rows.some((r) => r.productionGap);
+            if (hasDrift || hasUnreachable || hasPromoted || hasProductionGap)
                 process.stderr.write('\n');
             if (hasPromoted)
                 process.stderr.write(tCli('cli.list.promoted_note', lang));
@@ -107,6 +113,8 @@ export default class List extends BaseCommand {
                 process.stderr.write(tCli('cli.list.drift_note', lang));
             if (hasUnreachable)
                 process.stderr.write(tCli('cli.list.unreachable_note', lang));
+            if (hasProductionGap)
+                process.stderr.write(tCli('cli.list.production_gap_note', lang));
             process.stderr.write(tCli('cli.list.legend', lang));
         });
     }

package/dist/cli/commands/observe/index.d.ts

@@ -9,6 +9,14 @@ export declare function persistObserveHealthReport(report: SkillHealthReport, ou
     id: string;
     jsonPath: string;
 };
+/**
+ * SkillHealthReport → managed 反哺的结构化最小入参(#235)。纯映射、可单测 —— 把「observe 报告 →
+ * ObserveReportView」这段层间胶水从 CLI 副作用里拆出来,免得 healthBand 取错字段 / observedAt 取错时刻
+ * 这类映射 bug 无人验。`observedAt` 取**流量窗口结束时刻**(timeRange.to,空则退 generatedAt),不是「此刻」
+ * 的 generatedAt —— 否则 latest-wins 会把所有观测当成一样新(见 ManagedObservation.observedAt)。
+ * `healthBand` 由 observability 的 `healthBandOf` 逐 skill 算(阈值单一来源,注入以保可测)。
+ */
+export declare function buildObserveReportView(report: SkillHealthReport, reportId: string, healthBandOf: (weightedGapRate: number) => 'green' | 'yellow' | 'red'): import('../../../managed/index.js').ObserveReportView;
 export default class Observe extends BaseCommand {
     static description: string;
     static examples: {
@@ -27,6 +35,7 @@ export default class Observe extends BaseCommand {
         skills: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'output-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        feedback: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/cli/commands/observe/index.js

@@ -23,6 +23,68 @@ export function persistObserveHealthReport(report, outDir) {
     indexObserveWrite(report, jsonPath, outDir, id);
     return { id, jsonPath };
 }
+// 盲区信号类型 → 人话标签(建议补样本提示用)。技术枚举键的展示名,zh/en 分列。
+const GAP_AREA_LABELS = {
+    failed_search: { zh: '检索失败', en: 'failed search' },
+    explicit_marker: { zh: '显式缺口', en: 'explicit gap' },
+    hedging: { zh: '含糊回避', en: 'hedging' },
+    repeated_failure: { zh: '反复失败', en: 'repeated failure' },
+};
+/** 取盲区计数最高的前几类,组成「建议补哪类用例」的人话区域串(只展示信号所在,不生成具体用例)。
+ *  只迭代**四个已知盲区类型**(GAP_AREA_LABELS 的键),记录 / 报告里若混入额外键一律忽略,不进展示。 */
+function topGapAreas(gapByType, lang) {
+    const sep = lang === 'zh' ? '、' : ', ';
+    const areas = Object.keys(GAP_AREA_LABELS)
+        .map((k) => [k, gapByType[k] ?? 0])
+        .filter(([, n]) => n > 0)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([k]) => GAP_AREA_LABELS[k][lang])
+        .join(sep);
+    return areas || (lang === 'zh' ? '未归类盲区' : 'uncategorized gaps');
+}
+/**
+ * SkillHealthReport → managed 反哺的结构化最小入参(#235)。纯映射、可单测 —— 把「observe 报告 →
+ * ObserveReportView」这段层间胶水从 CLI 副作用里拆出来,免得 healthBand 取错字段 / observedAt 取错时刻
+ * 这类映射 bug 无人验。`observedAt` 取**流量窗口结束时刻**(timeRange.to,空则退 generatedAt),不是「此刻」
+ * 的 generatedAt —— 否则 latest-wins 会把所有观测当成一样新(见 ManagedObservation.observedAt)。
+ * `healthBand` 由 observability 的 `healthBandOf` 逐 skill 算(阈值单一来源,注入以保可测)。
+ */
+export function buildObserveReportView(report, reportId, healthBandOf) {
+    return {
+        reportId,
+        observedAt: report.meta.timeRange?.to || report.meta.generatedAt,
+        skills: Object.values(report.bySkill).map((s) => ({
+            skillName: s.skillName,
+            segmentCount: s.segmentCount,
+            gapRate: s.gap.gapRate,
+            weightedGapRate: s.gap.weightedGapRate,
+            confidence: s.confidence,
+            healthBand: healthBandOf(s.gap.weightedGapRate),
+            gapByType: s.gap.byType,
+        })),
+    };
+}
+/**
+ * observe → 管理支柱反哺(#235):把每个 skill 的生产健康落成观测追加进同名受管记录,并打印「已记录 / 生产
+ * 盲区警示」。**非致命**:管理是 observe 旁路,任何异常都不该让 observe 失败(try/catch 吞掉)。observability /
+ * managed 运行时函数动态 import,与 observe 主体一致、不拖累 CLI 启动。
+ */
+async function recordObserveFeedback(report, reportId, lang) {
+    try {
+        const { healthBandOf } = await import('../../../observability/skill-health-analyzer.js');
+        const { recordObserveHealth } = await import('../../../managed/index.js');
+        const written = recordObserveHealth(buildObserveReportView(report, reportId, healthBandOf));
+        for (const w of written) {
+            process.stdout.write(w.isProductionGap
+                ? tCli('cli.observe.production_gap', lang, { name: w.name, areas: topGapAreas(w.gapByType, lang) })
+                : tCli('cli.observe.observation_recorded', lang, { name: w.name }));
+        }
+    }
+    catch {
+        // 反哺是 observe 旁路,任何异常都不该让 observe 失败。
+    }
+}
 // `omk observe <sessions-dir>` 是默认命令 —— 分析 sessions 目录的 skill 调用健康度，产出 observe-health 报告(JSON)，
 // 由 Studio 健康报告页按需渲染。observe 这条线的另一条产物是观测收件箱(observe-inbox)，走子命令 ingest / inbox / show。
 export default class Observe extends BaseCommand {
@@ -80,6 +142,14 @@ export default class Observe extends BaseCommand {
                 en: 'Write to global ~/.oh-my-knowledge/observe-health instead of project .omk/observe-health',
             }),
         }),
+        feedback: Flags.boolean({
+            default: true,
+            allowNo: true,
+            description: bilingual({
+                zh: '把生产健康观测反哺已纳管的同名 skill（--no-feedback 关闭）',
+                en: 'Feed production-health observations back to managed skills of the same name (--no-feedback to disable)',
+            }),
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Observe);
@@ -120,7 +190,7 @@ export default class Observe extends BaseCommand {
             const outDir = flags['output-dir']
                 ? resolve(flags['output-dir'])
                 : (flags.global ? globalObserveHealthDir() : projectObserveHealthDir());
-            const { jsonPath } = persistObserveHealthReport(report, outDir);
+            const { id, jsonPath } = persistObserveHealthReport(report, outDir);
             const { sessionCount, segmentCount, toolCallCount, toolFailureRate } = report.meta;
             console.log('');
             console.log(`sessions: ${sessionCount} · segments: ${segmentCount} · tool calls: ${toolCallCount} · fail rate: ${(toolFailureRate * 100).toFixed(1)}%`);
@@ -139,6 +209,9 @@ export default class Observe extends BaseCommand {
             console.log('');
             console.log(`report written to: ${jsonPath}`);
             console.log(tCli('cli.observe.view_hint', lang));
+            // #235 受管反哺:把生产健康观测落进同名受管 skill(--no-feedback 关)。非致命旁路。
+            if (flags.feedback)
+                await recordObserveFeedback(report, id, lang);
         });
     }
 }

package/dist/cli/commands/sample.d.ts

@@ -2,6 +2,18 @@ import { BaseCommand } from '../oclif/base-command.js';
 import { type CliLang } from '../lib/i18n.js';
 import { type LoadSamplesResult } from '../../inputs/load-samples.js';
 import type { Report, Sample as SampleType } from '../../types/index.js';
+/** --append 合并:已有用例原样保留,新用例逐条接在后面;sample_id 撞已有(或本批已用)时
+ *  自动加 `-2`/`-3` 后缀去重。模型每次从 s001 重编号,撞 id 不代表内容重复,所以是改名保留
+ *  而非丢弃(不做内容级去重)。`reserved` 为额外要避开的 id 集(目录模式跨同目录其它 sample
+ *  文件去重用,见 collectDirSampleIds)。 */
+export declare function mergeAppendSamples(existing: SampleType[], fresh: SampleType[], reserved?: ReadonlySet<string>): SampleType[];
+/** 目录模式 append 选写回目标:复用 listSampleFilesInDir 的排序/过滤(与 eval 目录合并同口径),
+ *  优先 canonical `samples.json`,否则排序后第一个 —— 确定性、不依赖文件系统枚举顺序,
+ *  用户可预测改哪个文件。无候选返回 null。 */
+export declare function pickAppendTargetFile(dir: string): string | null;
+/** 把新用例追加进已有 sample 文件:读 → 合并(撞 id 去重)→ 保留原 json/yaml 格式与
+ *  `{samples:[...]}` wrapper 写回。返回合并后总条数。 */
+export declare function appendSamplesToFile(existingFile: string, fresh: SampleType[], reserved?: ReadonlySet<string>): number;
 export declare function collectSampleDesignFailureIds(report: Pick<Report, 'results'>, treatmentName: string): Set<string>;
 export declare function assertFixReportMatchesCurrentInputs(params: {
     report: Pick<Report, 'meta'>;
@@ -29,6 +41,7 @@ export default class Sample extends BaseCommand {
         executor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'skill-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         focus: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        append: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-mock': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         fix: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'reports-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/cli/commands/sample.js

@@ -8,7 +8,7 @@ import { integerStringParser } from '../oclif/parsers.js';
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
-import { loadSamples, parseYaml } from '../../inputs/load-samples.js';
+import { loadSamples, parseYaml, listSampleFilesInDir } from '../../inputs/load-samples.js';
 import { hashSample } from '../../eval-core/evaluation-reporting.js';
 import { hashArtifactSource } from '../../inputs/content-hash.js';
 function isRecord(value) {
@@ -33,6 +33,78 @@ function stringifySampleDocument(filePath, document) {
         return yaml.dump(document, { lineWidth: -1, noRefs: true });
     return JSON.stringify(document, null, 2);
 }
+/** --append 合并:已有用例原样保留,新用例逐条接在后面;sample_id 撞已有(或本批已用)时
+ *  自动加 `-2`/`-3` 后缀去重。模型每次从 s001 重编号,撞 id 不代表内容重复,所以是改名保留
+ *  而非丢弃(不做内容级去重)。`reserved` 为额外要避开的 id 集(目录模式跨同目录其它 sample
+ *  文件去重用,见 collectDirSampleIds)。 */
+export function mergeAppendSamples(existing, fresh, reserved) {
+    const used = new Set(existing.map((s) => s.sample_id));
+    if (reserved)
+        for (const id of reserved)
+            used.add(id);
+    const merged = [...existing];
+    for (const sample of fresh) {
+        let id = sample.sample_id;
+        if (used.has(id)) {
+            let n = 2;
+            while (used.has(`${id}-${n}`))
+                n += 1;
+            id = `${id}-${n}`;
+        }
+        used.add(id);
+        merged.push(id === sample.sample_id ? sample : { ...sample, sample_id: id });
+    }
+    return merged;
+}
+/** 目录模式 append:收集目录内所有 sample 文件的 sample_id,跨文件去重用 —— eval 走目录模式
+ *  会把目录下所有文件合并加载,跨文件撞 id 直接报错(load-samples 的 duplicate sample_id)。
+ *  复用 listSampleFilesInDir 的排序/过滤口径;best-effort:解析失败的文件跳过。 */
+function collectDirSampleIds(dir) {
+    const ids = new Set();
+    let files;
+    try {
+        files = listSampleFilesInDir(dir);
+    }
+    catch {
+        return ids;
+    }
+    for (const f of files) {
+        const full = join(dir, f);
+        try {
+            for (const s of getSamplesArray(parseSampleDocument(full), full)) {
+                if (typeof s.sample_id === 'string')
+                    ids.add(s.sample_id);
+            }
+        }
+        catch { /* skip unparseable / 非 sample 文件 */ }
+    }
+    return ids;
+}
+/** 目录模式 append 选写回目标:复用 listSampleFilesInDir 的排序/过滤(与 eval 目录合并同口径),
+ *  优先 canonical `samples.json`,否则排序后第一个 —— 确定性、不依赖文件系统枚举顺序,
+ *  用户可预测改哪个文件。无候选返回 null。 */
+export function pickAppendTargetFile(dir) {
+    let files;
+    try {
+        files = listSampleFilesInDir(dir);
+    }
+    catch {
+        return null;
+    }
+    if (files.length === 0)
+        return null;
+    const chosen = files.includes('samples.json') ? 'samples.json' : files[0];
+    return join(dir, chosen);
+}
+/** 把新用例追加进已有 sample 文件:读 → 合并(撞 id 去重)→ 保留原 json/yaml 格式与
+ *  `{samples:[...]}` wrapper 写回。返回合并后总条数。 */
+export function appendSamplesToFile(existingFile, fresh, reserved) {
+    const doc = parseSampleDocument(existingFile);
+    const merged = mergeAppendSamples(getSamplesArray(doc, existingFile), fresh, reserved);
+    const nextDoc = Array.isArray(doc) ? merged : { ...doc, samples: merged };
+    writeFileSync(existingFile, stringifySampleDocument(existingFile, nextDoc));
+    return merged.length;
+}
 function formatIdList(ids) {
     const shown = ids.slice(0, 5);
     const suffix = ids.length > shown.length ? ` +${ids.length - shown.length}` : '';
@@ -328,6 +400,12 @@ async function runSampleFromTraces(flags, lang) {
     }
 }
 async function runSample(args, flags, lang) {
+    // --append 目前只在单 skill 生成路径实现;batch / from-traces / fix 不处理它,
+    // 静默忽略会误导(用户以为在追加,实际没有)。提前互斥校验,明确报错。
+    if (flags.append && (flags.batch || flags['from-traces'] || flags.fix)) {
+        console.error(tCli('cli.gen.append_single_only', lang));
+        throw new CliExit(2);
+    }
     if (flags['from-traces']) {
         await runSampleFromTraces(flags, lang);
         return;
@@ -425,23 +503,23 @@ async function runSample(args, flags, lang) {
         }
         const skillContent = readFileSync(resolved.skillPath, 'utf-8');
         let outputPath;
+        let existingFile = null;
         if (!extname(resolved.samplesPath)) {
             const dir = resolved.samplesPath;
             if (existsSync(dir) && statSync(dir).isDirectory()) {
-                const existing = readdirSync(dir).find((f) => /\.(json|ya?ml)$/i.test(f) && !/^(report|health|_)/i.test(f));
-                if (existing) {
-                    console.error(tCli('cli.gen.samples_already_exists', lang));
-                    throw new CliExit(1);
-                }
+                existingFile = pickAppendTargetFile(dir);
             }
-            outputPath = join(dir, 'samples.json');
+            outputPath = existingFile ?? join(dir, 'samples.json');
         }
         else {
             outputPath = resolved.samplesPath;
-            if (existsSync(outputPath)) {
-                console.error(tCli('cli.gen.samples_already_exists', lang));
-                throw new CliExit(1);
-            }
+            if (existsSync(outputPath))
+                existingFile = outputPath;
+        }
+        // 已有用例文件:默认报错保护;--append 时追加(下面合并),不报错。
+        if (existingFile && !flags.append) {
+            console.error(tCli('cli.gen.samples_already_exists', lang));
+            throw new CliExit(1);
         }
         if (count !== undefined) {
             process.stderr.write(tCli('cli.gen.single_generating', lang, { count }));
@@ -451,12 +529,24 @@ async function runSample(args, flags, lang) {
         }
         try {
             const { samples, costUSD } = await generateSamples({ skillContent, count, model, focus, noMock: flags['no-mock'], executorName: flags.executor });
-            mkdirSync(dirname(outputPath), { recursive: true });
-            writeFileSync(outputPath, JSON.stringify(samples, null, 2));
             const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
-            process.stderr.write(tCli('cli.gen.single_done', lang, {
-                n: samples.length, path: outputPath, cost,
-            }));
+            if (existingFile && flags.append) {
+                // 追加:读已有 → 合并(撞 id 去重)→ 保留原 json/yaml 格式与 wrapper 写回。
+                // 目录模式额外跨同目录其它 sample 文件去重,避免 eval 合并加载时撞 id 报错;
+                // 显式单文件路径无同目录合并语义,不需要。
+                const reserved = extname(resolved.samplesPath) ? undefined : collectDirSampleIds(dirname(existingFile));
+                const total = appendSamplesToFile(existingFile, samples, reserved);
+                process.stderr.write(tCli('cli.gen.append_done', lang, {
+                    added: samples.length, total, path: existingFile, cost,
+                }));
+            }
+            else {
+                mkdirSync(dirname(outputPath), { recursive: true });
+                writeFileSync(outputPath, JSON.stringify(samples, null, 2));
+                process.stderr.write(tCli('cli.gen.single_done', lang, {
+                    n: samples.length, path: outputPath, cost,
+                }));
+            }
             console.log(tCli('cli.gen.review_hint', lang));
         }
         catch (err) {
@@ -553,6 +643,13 @@ export default class Sample extends BaseCommand {
                 en: 'Generation focus (NL hint). Steers LLM toward certain sample types.',
             }),
         }),
+        append: Flags.boolean({
+            description: bilingual({
+                zh: '在已有用例文件上追加新生成的用例（撞 sample_id 自动加后缀去重，保留原 json/yaml 格式）。仅单 skill 模式，不支持 --batch / --from-traces / --fix。不传则已有文件时报错保护。常配 --focus 补特定场景。',
+                en: 'Append newly generated samples to the existing samples file (colliding sample_id auto-suffixed, original json/yaml shape kept). Single-skill mode only; not supported with --batch / --from-traces / --fix. Without it, an existing file errors out. Often paired with --focus.',
+            }),
+            default: false,
+        }),
         'no-mock': Flags.boolean({
             description: bilingual({
                 zh: '不生成 mocks，eval 时所有工具调用真实执行。',

package/dist/cli/lib/cmd-flags.d.ts

@@ -155,6 +155,7 @@ export interface SampleFlags {
     executor?: string;
     'skill-dir': string;
     focus?: string;
+    append: boolean;
     'no-mock': boolean;
     fix: boolean;
     'reports-dir'?: string;

package/dist/cli/lib/i18n-dict/common.d.ts

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type CommonMessageKey = 'cli.common.unknown_domain' | 'cli.common.error_prefix' | 'cli.common.skill_dir_not_found' | 'cli.common.skill_file_not_found' | 'cli.common.skill_dir_no_skill_md' | 'cli.common.report_not_found' | 'cli.common.no_judge_model' | 'cli.common.judge_models_single_only' | 'cli.common.warn_load_samples_failed' | 'cli.update.new_version_available' | 'cli.update.box_title' | 'cli.update.box_version_line' | 'cli.update.box_upgrade_line' | 'cli.update.box_silence_line' | 'cli.observe.view_hint' | 'cli.studio.started' | 'cli.studio.stop_hint' | 'cli.studio.open_failed' | 'cli.doctor.no_skill_found' | 'cli.doctor.samples_detected' | 'cli.doctor.progress_skill_start' | 'cli.doctor.progress_skill_done';
+export type CommonMessageKey = 'cli.common.unknown_domain' | 'cli.common.error_prefix' | 'cli.common.skill_dir_not_found' | 'cli.common.skill_file_not_found' | 'cli.common.skill_dir_no_skill_md' | 'cli.common.report_not_found' | 'cli.common.no_judge_model' | 'cli.common.judge_models_single_only' | 'cli.common.warn_load_samples_failed' | 'cli.update.new_version_available' | 'cli.update.box_title' | 'cli.update.box_version_line' | 'cli.update.box_upgrade_line' | 'cli.update.box_silence_line' | 'cli.observe.view_hint' | 'cli.observe.observation_recorded' | 'cli.observe.production_gap' | 'cli.studio.started' | 'cli.studio.stop_hint' | 'cli.studio.open_failed' | 'cli.doctor.no_skill_found' | 'cli.doctor.samples_detected' | 'cli.doctor.progress_skill_start' | 'cli.doctor.progress_skill_done';
 export declare const commonDict: Record<CommonMessageKey, CliMessage>;

package/dist/cli/lib/i18n-dict/common.js

@@ -59,6 +59,14 @@ export const commonDict = {
         zh: '分析 JSON 已写入 output-dir；后续可用 omk observe 持续生成健康报告。',
         en: 'Analysis JSON written to output-dir; use omk observe to keep producing health reports.',
     },
+    'cli.observe.observation_recorded': {
+        zh: '🔭 已为受管 skill「{name}」记录生产健康观测。\n',
+        en: '🔭 Recorded a production-health observation for managed skill "{name}".\n',
+    },
+    'cli.observe.production_gap': {
+        zh: '⚠️ 受管 skill「{name}」线上检测到生产盲区（{areas}）。建议补充对应用例后重跑 omk eval —— observe 只提示，不改样本集。\n',
+        en: '⚠️ Managed skill "{name}" shows production gaps in real traffic ({areas}). Consider adding matching samples and re-running omk eval — observe only suggests, it does not edit the sample set.\n',
+    },
     'cli.studio.started': {
         zh: 'studio 已启动：{url}',
         en: 'Studio running at {url}',

package/dist/cli/lib/i18n-dict/gen.d.ts

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type GenMessageKey = 'cli.gen.skill_skipped_existing' | 'cli.gen.skill_generating' | 'cli.gen.skill_generating_auto' | 'cli.gen.skill_done' | 'cli.gen.skill_failed' | 'cli.gen.batch_none_needed' | 'cli.gen.batch_summary' | 'cli.gen.specify_skill_path' | 'cli.gen.samples_already_exists' | 'cli.gen.single_generating' | 'cli.gen.single_generating_auto' | 'cli.gen.single_done' | 'cli.gen.review_hint' | 'cli.gen.failed' | 'cli.gen.focus_applied';
+export type GenMessageKey = 'cli.gen.skill_skipped_existing' | 'cli.gen.skill_generating' | 'cli.gen.skill_generating_auto' | 'cli.gen.skill_done' | 'cli.gen.skill_failed' | 'cli.gen.batch_none_needed' | 'cli.gen.batch_summary' | 'cli.gen.specify_skill_path' | 'cli.gen.samples_already_exists' | 'cli.gen.single_generating' | 'cli.gen.single_generating_auto' | 'cli.gen.single_done' | 'cli.gen.append_done' | 'cli.gen.append_single_only' | 'cli.gen.review_hint' | 'cli.gen.failed' | 'cli.gen.focus_applied';
 export declare const genDict: Record<GenMessageKey, CliMessage>;

package/dist/cli/lib/i18n-dict/gen.js

@@ -47,6 +47,14 @@ export const genDict = {
         zh: '✅ 已生成 {n} 条用例 → {path}{cost}\n',
         en: '✅ Generated {n} samples → {path}{cost}\n',
     },
+    'cli.gen.append_done': {
+        zh: '✅ 新增 {added} 条用例（撞 id 已自动改名），合并后共 {total} 条 → {path}{cost}\n',
+        en: '✅ Appended {added} samples (colliding ids auto-renamed), {total} total → {path}{cost}\n',
+    },
+    'cli.gen.append_single_only': {
+        zh: '--append 目前仅支持单 skill 模式，不能与 --batch / --from-traces / --fix 同用。\n',
+        en: '--append currently supports single-skill mode only; it cannot be combined with --batch / --from-traces / --fix.\n',
+    },
     'cli.gen.review_hint': {
         zh: '\n请审查生成的评测用例后运行: omk eval',
         en: '\nReview the generated test cases, then run: omk eval',

package/dist/cli/lib/i18n-dict/list.d.ts

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type ListMessageKey = 'cli.list.header' | 'cli.list.empty' | 'cli.list.empty_hint' | 'cli.list.col_name' | 'cli.list.col_kind' | 'cli.list.col_state' | 'cli.list.col_verdict' | 'cli.list.col_evidence' | 'cli.list.col_source' | 'cli.list.drift_note' | 'cli.list.unreachable_note' | 'cli.list.promoted_note' | 'cli.list.legend';
+export type ListMessageKey = 'cli.list.header' | 'cli.list.empty' | 'cli.list.empty_hint' | 'cli.list.col_name' | 'cli.list.col_kind' | 'cli.list.col_state' | 'cli.list.col_verdict' | 'cli.list.col_evidence' | 'cli.list.col_source' | 'cli.list.drift_note' | 'cli.list.unreachable_note' | 'cli.list.promoted_note' | 'cli.list.production_gap_note' | 'cli.list.legend';
 export declare const listDict: Record<ListMessageKey, CliMessage>;

package/dist/cli/lib/i18n-dict/list.js

@@ -29,6 +29,10 @@ export const listDict = {
         zh: '✓ = 当前版本已按证据人工接受为 promoted（omk promote）。\n',
         en: '✓ = current version accepted as promoted on evidence (omk promote).\n',
     },
+    'cli.list.production_gap_note': {
+        zh: '🔬 = observe 在线上检测到生产盲区（与生命周期无关的版本无关信号）；建议补对应用例后重跑 omk eval。\n',
+        en: '🔬 = observe detected a production gap in real traffic (a version-agnostic signal, orthogonal to lifecycle); add matching samples and re-run omk eval.\n',
+    },
     'cli.list.legend': {
         zh: '证据列 = 当前有效 / 全部（历史含旧内容证据，供回滚）。\n',
         en: 'EVIDENCE column = current / total (history keeps old-content evidence for rollback).\n',

package/dist/cli/lib/record-evolve-outcome.js

@@ -2,26 +2,35 @@ import { resolve } from 'node:path';
 import { createOverlayReportStore } from '../../server/report-store.js';
 import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
 import { computeVerdict } from '../../eval-core/verdict.js';
-import { bootstrapDiffCI, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES } from '../../eval-core/bootstrap.js';
+import { bootstrapPairedDiffCI, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES } from '../../eval-core/bootstrap.js';
 import { resolveManagedDir, managedDir, loadAllManagedRecords, appendManagedEvidence, rebaselineManagedContentHash, buildEvidenceRef, probeSourceState, } from '../../managed/index.js';
 /**
  * round-bestRound vs round-0 的忠实 verdict：复刻 eval 管线（evaluation-reporting.ts）对两变体抽
- * per-sample composite → bootstrapDiffCI → computeVerdict，与 `omk eval --bootstrap` 同口径、同 α / 重采样数。
+ * per-sample composite → 按 sample 配对 bootstrapPairedDiffCI → computeVerdict，与 `omk eval --bootstrap`
+ * 同口径、同 α / 重采样数。
  * 不自造门限：评委是否显著、是否 PROGRESS 全交给既有 computeVerdict。
  */
 function winnerVerdict(report, winnerVariant) {
     const baseline = 'round-0';
-    const scoresOf = (v) => report.results
-        .map((r) => r.variants[v])
-        .filter((e) => !!e && typeof e.compositeScore === 'number' && e.compositeScore > 0)
-        .map((e) => e.compositeScore);
-    const ctrl = scoresOf(baseline);
-    const treat = scoresOf(winnerVariant);
-    const pairComparisons = ctrl.length >= 2 && treat.length >= 2
+    // 按 sample **配对**(与 evaluation-reporting 主 A/B 同口径 —— 本函数职责就是复刻 eval 管线):baseline 与
+    // winner 在同一 sample 上都可测(composite > 0)才入对。同一 sample 两版分数正相关,配对 bootstrap 收紧 diff
+    // CI;独立重采样会高估方差、保守失功效。diff = b − a = winner − baseline。
+    const compositeOf = (v, r) => {
+        const e = r.variants[v];
+        return e && typeof e.compositeScore === 'number' && e.compositeScore > 0 ? e.compositeScore : undefined;
+    };
+    const pairs = [];
+    for (const r of report.results) {
+        const a = compositeOf(baseline, r);
+        const b = compositeOf(winnerVariant, r);
+        if (a !== undefined && b !== undefined)
+            pairs.push({ a, b });
+    }
+    const pairComparisons = pairs.length >= 2
         ? [{
                 control: baseline,
                 treatment: winnerVariant,
-                diffBootstrapCI: bootstrapDiffCI(ctrl, treat, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES),
+                diffBootstrapCI: bootstrapPairedDiffCI(pairs, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES),
             }]
         : undefined;
     const slice = {