oh-my-knowledge 0.32.0 → 0.34.0

package/dist/cli/commands/install.js

@@ -0,0 +1,411 @@
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, relative, resolve, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Args, Flags } from '@oclif/core';
+import { LANG_FLAG, bilingual } from '../oclif/i18n.js';
+import { BaseCommand } from '../oclif/base-command.js';
+import { tCli } from '../lib/i18n.js';
+import { resolveInstallSource, SourceResolveError } from '../../inputs/source-resolver.js';
+import { buildManagedArtifactRecord, hashArtifactSource, isDistributablePath, managedDir, recordManagedArtifact } from '../../managed/index.js';
+const BUILTIN_OMK_AGENT_SKILL_ID = 'omk-agent-skill';
+const INSTALLABLE_KINDS = ['skill', 'prompt', 'agent', 'workflow'];
+const TARGET_ORDER = ['codex', 'claude'];
+const TARGET_SPECS = {
+    codex: {
+        label: 'Codex/AGENTS',
+        skillsDir: (home) => join(home, '.agents', 'skills'),
+        detectDirs: (home) => [join(home, '.agents'), join(home, '.codex')],
+    },
+    claude: {
+        label: 'Claude Code',
+        skillsDir: (home) => join(home, '.claude', 'skills'),
+        detectDirs: (home) => [join(home, '.claude')],
+    },
+};
+function packagedOmkAgentSkillDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '..', '..', 'assets', 'agent-skills', 'omk');
+}
+function knownTarget(target) {
+    const home = homedir();
+    const spec = TARGET_SPECS[target];
+    return { label: spec.label, skillsDir: spec.skillsDir(home) };
+}
+function directoryExists(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function parseTargets(raw, lang) {
+    const parts = [...new Set(raw.split(',').map((part) => part.trim()).filter(Boolean))];
+    if (parts.length === 0)
+        return autoTargets();
+    if (parts.includes('auto')) {
+        if (parts.length > 1)
+            throw new Error(tCli('cli.install.invalid_target_combo', lang, { target: raw }));
+        return autoTargets();
+    }
+    if (parts.includes('all')) {
+        if (parts.length > 1)
+            throw new Error(tCli('cli.install.invalid_target_combo', lang, { target: raw }));
+        return TARGET_ORDER;
+    }
+    const out = [];
+    for (const part of parts) {
+        if (part !== 'codex' && part !== 'claude') {
+            throw new Error(tCli('cli.install.unknown_target', lang, { target: part }));
+        }
+        out.push(part);
+    }
+    return out;
+}
+function autoTargets() {
+    const home = homedir();
+    return TARGET_ORDER.filter((target) => TARGET_SPECS[target].detectDirs(home).some(directoryExists));
+}
+function resolveInstallTargets(params) {
+    if (params.dest) {
+        return [{ label: 'custom', skillsDir: resolve(params.dest) }];
+    }
+    const targets = parseTargets(params.to, params.lang);
+    if (targets.length === 0) {
+        throw new Error(tCli('cli.install.no_detected_targets', params.lang));
+    }
+    const seen = new Set();
+    return targets
+        .map(knownTarget)
+        .filter((target) => {
+        const key = resolve(target.skillsDir);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** 目标落点:目录-skill → {skillsDir}/{name};文件-skill → {skillsDir}/{name}.md。 */
+function targetArtifactPath(target, name, isDirectorySkill) {
+    return isDirectorySkill ? join(target.skillsDir, name) : join(target.skillsDir, `${name}.md`);
+}
+/** 内置 omk Agent Skill 固定落到 {skillsDir}/omk(目录-skill)。 */
+function targetSkillDir(target) {
+    return targetArtifactPath(target, 'omk', true);
+}
+/** 全部目标预检通过才拷任何一个(无部分安装)。源就是目标(就地接管)的目标跳过存在性检查。 */
+function validateInstallTargets(params) {
+    if (params.dryRun || params.force)
+        return;
+    for (const targetPath of params.targetPaths) {
+        if (params.source && classifyPaths(params.source, targetPath) === 'same')
+            continue;
+        if (existsSync(targetPath)) {
+            throw new Error(tCli('cli.install.target_exists', params.lang, { path: targetPath }));
+        }
+    }
+}
+/** 解析路径的物理形态:对存在的最长前缀做 realpath、余下保持字面,使尚不存在的目标也能比较。 */
+function realPathBestEffort(p) {
+    let cur = resolve(p);
+    const tail = [];
+    while (!existsSync(cur)) {
+        tail.unshift(basename(cur));
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    const base = existsSync(cur) ? realpathSync(cur) : cur;
+    return tail.length ? join(base, ...tail) : base;
+}
+/**
+ * 源与目标的物理关系(解析软链):
+ *   - same:同一节点 → 就地接管(绝不删/拷);
+ *   - overlap:一个是另一个的祖先 → rmSync(target) 会删掉源、或 cpSync 把目录拷进自身子目录,数据损坏,必须拒;
+ *   - disjoint:正常拷贝。
+ */
+function classifyPaths(source, targetPath) {
+    const rs = realPathBestEffort(source);
+    const rt = realPathBestEffort(targetPath);
+    if (rs === rt)
+        return 'same';
+    if (rs.startsWith(rt + sep) || rt.startsWith(rs + sep))
+        return 'overlap';
+    return 'disjoint';
+}
+/**
+ * 通用拷贝:目录递归 cp(过滤 .omk / .git / evolve 等非分发产物 + 软链)、单文件 copyFile。
+ * 不打印——由调用方决定文案。dry-run 不写。源即目标 → 就地接管(inPlace);源与目标互为祖先 → 拒绝(防自毁)。
+ */
+function copyArtifactToTarget(params) {
+    if (!existsSync(params.source)) {
+        throw new Error(tCli('cli.install.asset_missing', params.lang, { path: params.source }));
+    }
+    if (params.dryRun) {
+        return { targetPath: params.targetPath, planned: true, inPlace: false };
+    }
+    const relation = classifyPaths(params.source, params.targetPath);
+    // 就地接管:源就是目标(接管已安装的 skill),绝不 rmSync 源。
+    if (relation === 'same') {
+        return { targetPath: params.targetPath, planned: false, inPlace: true };
+    }
+    // 互为祖先:删除目标会删掉源、或自拷进子目录 —— 数据损坏,直接拒,哪怕带 --force。
+    if (relation === 'overlap') {
+        throw new Error(tCli('cli.install.target_overlaps_source', params.lang, { source: params.source, target: params.targetPath }));
+    }
+    if (existsSync(params.targetPath) && !params.force) {
+        throw new Error(tCli('cli.install.target_exists', params.lang, { path: params.targetPath }));
+    }
+    mkdirSync(params.skillsDir, { recursive: true });
+    rmSync(params.targetPath, { recursive: true, force: true });
+    if (params.isDirectorySkill) {
+        cpSync(params.source, params.targetPath, {
+            recursive: true,
+            // 与 hashArtifactSource 共用过滤,保证"分发出去的 == 算进 hash 的":
+            // 源根永远拷;软链跳过(与 hash walk 一致,避免软链目标改了却不触发 drift);
+            // evolve 只在源根第一层排除(嵌套 references/evolve 正常分发),.omk/.git 任意层级排除。
+            filter: (src) => {
+                const rel = relative(params.source, src);
+                if (rel === '')
+                    return true;
+                if (lstatSync(src).isSymbolicLink())
+                    return false;
+                return isDistributablePath(rel.split(sep));
+            },
+        });
+    }
+    else {
+        copyFileSync(params.source, params.targetPath);
+    }
+    return { targetPath: params.targetPath, planned: false, inPlace: false };
+}
+function installOmkAgentSkill(params) {
+    const targetDir = targetSkillDir(params.target);
+    const { planned } = copyArtifactToTarget({
+        source: params.sourceDir,
+        isDirectorySkill: true,
+        targetPath: targetDir,
+        skillsDir: params.target.skillsDir,
+        force: params.force,
+        dryRun: params.dryRun,
+        lang: params.lang,
+    });
+    console.log(tCli(planned ? 'cli.install.plan' : 'cli.install.installed', params.lang, { path: targetDir }));
+    return targetDir;
+}
+/**
+ * 是否当作用户 artifact 路径(否则按 typo 的内置 id 处理,报 unknown_input)。
+ *   - 显式路径意图(含 `/`)或 `.md` 结尾 → 是(后续 installManagedSkill 经 resolver 给出精确的存在性 / SKILL.md 报错);
+ *   - 裸短名 → 仅当它确实解析到一个含 SKILL.md 的目录才算;裸的同名普通文件(如 cwd 里恰好有个
+ *     `omk-agnt-skill` 文件)不该被当成 skill 安装,落回 unknown_input。
+ */
+function looksLikeArtifactPath(input) {
+    if (input.includes('/') || /\.md$/i.test(input))
+        return true;
+    try {
+        const abs = resolve(input);
+        return statSync(abs).isDirectory() && existsSync(join(abs, 'SKILL.md'));
+    }
+    catch {
+        return false;
+    }
+}
+export default class Install extends BaseCommand {
+    static description = bilingual({
+        zh: '安装 omk 官方 Agent Skill，或登记并分发用户自己的 skill（内置 id omk-agent-skill，本地路径，或 git:<ref>:<name> 取当前仓库某个 ref 的 skill）。默认写入本机已检测 agent 目标；安装用户 skill 时同时登记一条受管记录。',
+        en: 'Install the official omk Agent Skill, or register and distribute your own skill (built-in id omk-agent-skill, a local path, or git:<ref>:<name> for a skill at a ref of the current repo). Defaults to detected local agent targets; installing a user skill also records a managed entry.',
+    });
+    static examples = [
+        {
+            description: bilingual({
+                zh: '安装 omk 官方 Agent Skill 到默认本机目标',
+                en: 'Install the official omk Agent Skill into default local targets',
+            }),
+            command: '<%= config.bin %> install omk-agent-skill',
+        },
+        {
+            description: bilingual({
+                zh: '强制安装到当前 omk 已知的所有目标',
+                en: 'Install into every target currently known to omk',
+            }),
+            command: '<%= config.bin %> install omk-agent-skill --to all',
+        },
+        {
+            description: bilingual({
+                zh: '安装到自定义 skill 根目录',
+                en: 'Install into a custom skill root',
+            }),
+            command: '<%= config.bin %> install omk-agent-skill --dest ~/.my-agent/skills',
+        },
+        {
+            description: bilingual({
+                zh: '登记并分发用户自己的 skill（--kind 可省，命中 SKILL.md 自动推导）',
+                en: 'Register and distribute your own skill (--kind optional; inferred from SKILL.md)',
+            }),
+            command: '<%= config.bin %> install ./skills/review',
+        },
+        {
+            description: bilingual({
+                zh: '从当前仓库某个 ref 安装 skill（可复现；SHA 不可变、分支会随 ref 漂移）',
+                en: 'Install a skill from a ref of the current repo (reproducible; a SHA is immutable, a branch drifts with the ref)',
+            }),
+            command: '<%= config.bin %> install git:main:skills/review',
+        },
+    ];
+    static args = {
+        input: Args.string({
+            description: bilingual({
+                zh: '要安装的知识输入：内置 id omk-agent-skill，本地 skill 路径（目录或 .md），或 git:<ref>:<name>（当前仓库某 ref 的 skill）。',
+                en: 'Knowledge input to install: built-in id omk-agent-skill, a local skill path (directory or .md), or git:<ref>:<name> (a skill at a ref of the current repo).',
+            }),
+            required: true,
+        }),
+    };
+    static flags = {
+        lang: LANG_FLAG,
+        kind: Flags.string({
+            description: bilingual({
+                zh: '用户 artifact 的 kind（对齐 Artifact.kind）。可省：命中 SKILL.md 自动推导，当前仅支持 skill。',
+                en: 'Kind of the user artifact (aligns with Artifact.kind). Optional: inferred from SKILL.md; only skill is supported today.',
+            }),
+            options: INSTALLABLE_KINDS,
+        }),
+        to: Flags.string({
+            description: bilingual({
+                zh: '安装目标：auto（默认，本机已检测目标） / codex / claude / all。',
+                en: 'Install target: auto (default, detected local targets) / codex / claude / all.',
+            }),
+            default: 'auto',
+        }),
+        dest: Flags.string({
+            description: bilingual({
+                zh: '自定义 skill 根目录；skill 安装到 <dir>/<name>（内置 omk-agent-skill 为 <dir>/omk）。',
+                en: 'Custom skill root; a skill installs into <dir>/<name> (the built-in omk-agent-skill into <dir>/omk).',
+            }),
+        }),
+        force: Flags.boolean({
+            description: bilingual({
+                zh: '覆盖目标位置已存在的 skill。',
+                en: 'Overwrite an existing skill at the target location.',
+            }),
+            default: false,
+        }),
+        'dry-run': Flags.boolean({
+            description: bilingual({
+                zh: '只打印安装目标，不写文件。',
+                en: 'Print install targets without writing files.',
+            }),
+            default: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Install);
+        const lang = this.lang;
+        await this.runWithCliExit(async () => {
+            if (args.input === BUILTIN_OMK_AGENT_SKILL_ID) {
+                this.installBuiltinAgentSkill(flags, lang);
+                return;
+            }
+            if (args.input.startsWith('git:') || looksLikeArtifactPath(args.input)) {
+                this.installManagedSkill(args.input, flags.kind, flags, lang);
+                return;
+            }
+            throw new Error(tCli('cli.install.unknown_input', lang, { input: args.input }));
+        });
+    }
+    installBuiltinAgentSkill(flags, lang) {
+        const sourceDir = packagedOmkAgentSkillDir();
+        const targets = resolveInstallTargets({ to: flags.to, dest: flags.dest, lang });
+        validateInstallTargets({
+            targetPaths: targets.map(targetSkillDir),
+            force: flags.force,
+            dryRun: flags['dry-run'],
+            lang,
+        });
+        for (const target of targets) {
+            installOmkAgentSkill({ sourceDir, target, force: flags.force, dryRun: flags['dry-run'], lang });
+        }
+        if (!flags['dry-run'])
+            console.log(tCli('cli.install.next_hint', lang));
+    }
+    installManagedSkill(input, kindFlag, flags, lang) {
+        // kind 推导:--kind 显式优先;否则缺省 skill(Phase 1 仅 skill)。
+        const kind = kindFlag ?? 'skill';
+        if (kind !== 'skill') {
+            throw new Error(tCli('cli.install.kind_unsupported', lang, { kind }));
+        }
+        // 源解析委托给 source-resolver(file / git ...),install 主干源无关。
+        // resolver 不依赖 CLI,错误以 SourceResolveError(messageKey) 抛出,这里映射成本地化文案。
+        let src;
+        try {
+            src = resolveInstallSource(input);
+        }
+        catch (err) {
+            if (err instanceof SourceResolveError) {
+                throw new Error(tCli(err.messageKey, lang, err.params));
+            }
+            throw err;
+        }
+        try {
+            const { localRoot, name, isDirectorySkill, sourceKind, locator, ref } = src;
+            // 目录-skill 哈整棵可分发树(排除 .omk/.git/evolve);git 源哈的是物化后的临时树。
+            const contentHash = hashArtifactSource(localRoot, isDirectorySkill);
+            const targets = resolveInstallTargets({ to: flags.to, dest: flags.dest, lang });
+            validateInstallTargets({
+                targetPaths: targets.map((t) => targetArtifactPath(t, name, isDirectorySkill)),
+                force: flags.force,
+                dryRun: flags['dry-run'],
+                lang,
+                source: localRoot,
+            });
+            const now = new Date().toISOString();
+            const distribution = [];
+            const dir = managedDir();
+            // 即便多目标中途失败,也把已成功分发的落点登记进记录,保持"磁盘 == 记录"一致;
+            // 重跑 --force 时 upsert 会按 path 去重并补齐其余目标。
+            const writeRecordIfAny = () => {
+                if (flags['dry-run'] || distribution.length === 0)
+                    return;
+                const record = buildManagedArtifactRecord({
+                    name,
+                    kind,
+                    source: { sourceKind, locator, ...(ref ? { ref } : {}), isDirectorySkill },
+                    contentHash,
+                    installedAt: now,
+                    distribution,
+                });
+                recordManagedArtifact(record, { dir });
+                console.log(tCli('cli.install.registered', lang, { id: record.id, store: dir }));
+            };
+            try {
+                for (const target of targets) {
+                    const targetPath = targetArtifactPath(target, name, isDirectorySkill);
+                    const { planned, inPlace } = copyArtifactToTarget({
+                        source: localRoot,
+                        isDirectorySkill,
+                        targetPath,
+                        skillsDir: target.skillsDir,
+                        force: flags.force,
+                        dryRun: flags['dry-run'],
+                        lang,
+                    });
+                    if (planned) {
+                        console.log(tCli('cli.install.plan_skill', lang, { name, path: targetPath }));
+                    }
+                    else {
+                        console.log(tCli(inPlace ? 'cli.install.adopted' : 'cli.install.copied', lang, { name, path: targetPath }));
+                        distribution.push({ label: target.label, path: targetPath, contentHash, copiedAt: now });
+                    }
+                }
+            }
+            finally {
+                writeRecordIfAny();
+            }
+        }
+        finally {
+            src.cleanup(); // git 删临时物化目录;file noop
+        }
+    }
+}

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

@@ -20,4 +20,3 @@ export default class ObserveInbox extends BaseCommand {
     };
     run(): Promise<void>;
 }
-//# sourceMappingURL=inbox.d.ts.map

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

@@ -257,4 +257,3 @@ export default class ObserveInbox extends BaseCommand {
         });
     }
 }
-//# sourceMappingURL=inbox.js.map

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

@@ -19,4 +19,3 @@ export default class Observe extends BaseCommand {
     };
     run(): Promise<void>;
 }
-//# sourceMappingURL=index.d.ts.map

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

@@ -101,12 +101,16 @@ export default class Observe extends BaseCommand {
             const { sessionCount, segmentCount, toolCallCount, toolFailureRate } = report.meta;
             console.log('');
             console.log(`sessions: ${sessionCount} · segments: ${segmentCount} · tool calls: ${toolCallCount} · fail rate: ${(toolFailureRate * 100).toFixed(1)}%`);
-            console.log(`overall: gapRate ${(report.overall.gapRate * 100).toFixed(1)}% · weightedGapRate ${(report.overall.weightedGapRate * 100).toFixed(1)}% · health: ${report.overall.healthBand}`);
+            const overallConf = report.overall.confidence;
+            const confSuffix = overallConf === 'high'
+                ? ''
+                : ` · ⚠ confidence: ${overallConf} (N=${segmentCount} too small; band is indicative)`;
+            console.log(`overall: gapRate ${(report.overall.gapRate * 100).toFixed(1)}% · weightedGapRate ${(report.overall.weightedGapRate * 100).toFixed(1)}% · health: ${report.overall.healthBand}${confSuffix}`);
             console.log('');
             const skillRows = Object.values(report.bySkill)
                 .sort((a, b) => b.segmentCount - a.segmentCount)
                 .slice(0, 10)
-                .map((s) => `  ${s.skillName.padEnd(24)} segs=${String(s.segmentCount).padStart(4)}  gapRate=${String(Math.round(s.gap.gapRate * 100) + '%').padStart(4)}  weighted=${String(Math.round(s.gap.weightedGapRate * 100) + '%').padStart(4)}${s.coverage ? `  cov=${Math.round(s.coverage.fileCoverageRate * 100)}%` : ''}`);
+                .map((s) => `  ${s.skillName.padEnd(24)} segs=${String(s.segmentCount).padStart(4)}  gapRate=${String(Math.round(s.gap.gapRate * 100) + '%').padStart(4)}  weighted=${String(Math.round(s.gap.weightedGapRate * 100) + '%').padStart(4)}${s.coverage ? `  cov=${Math.round(s.coverage.fileCoverageRate * 100)}%` : ''}${s.confidence !== 'high' ? `  ⚠${s.confidence}` : ''}`);
             console.log('top skills:');
             console.log(skillRows.join('\n'));
             console.log('');
@@ -115,4 +119,3 @@ export default class Observe extends BaseCommand {
         });
     }
 }
-//# sourceMappingURL=index.js.map

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

@@ -10,4 +10,3 @@ export default class ObserveIngest extends BaseCommand {
     };
     run(): Promise<void>;
 }
-//# sourceMappingURL=ingest.d.ts.map

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

@@ -68,4 +68,3 @@ export default class ObserveIngest extends BaseCommand {
         });
     }
 }
-//# sourceMappingURL=ingest.js.map

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

@@ -10,4 +10,3 @@ export default class ObserveShow extends BaseCommand {
     };
     run(): Promise<void>;
 }
-//# sourceMappingURL=show.d.ts.map

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

@@ -46,4 +46,3 @@ export default class ObserveShow extends BaseCommand {
         });
     }
 }
-//# sourceMappingURL=show.js.map

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

@@ -32,7 +32,8 @@ export default class Sample extends BaseCommand {
         fix: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'reports-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         treatment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'from-traces': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'observations-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }
-//# sourceMappingURL=sample.d.ts.map

package/dist/cli/commands/sample.js

@@ -254,7 +254,65 @@ async function runSampleFix(args, flags, lang) {
         ? `\n🔧 修复完成: ${result.fixedCount}/${sampleDesignCount} 条已修复 → ${outputTarget}${cost}\n`
         : `\n🔧 Fix complete: ${result.fixedCount}/${sampleDesignCount} fixed → ${outputTarget}${cost}\n`);
 }
+async function runSampleFromTraces(flags, lang) {
+    const { queryObservationInbox, DEFAULT_OBSERVATIONS_DIR } = await import('../../observability/inbox.js');
+    const { generateSamplesFromTraces } = await import('../../authoring/generator.js');
+    const obsDir = resolve(flags['observations-dir'] ?? DEFAULT_OBSERVATIONS_DIR);
+    if (!existsSync(obsDir)) {
+        console.error(lang === 'zh'
+            ? `observations 目录不存在: ${obsDir}（先运行 omk observe 生成 inbox）`
+            : `Observations dir not found: ${obsDir} (run omk observe first)`);
+        throw new CliExit(1);
+    }
+    // Drop noise-tier signals up front: they're exactly what the generator is told to
+    // skip, so filtering here avoids feeding junk to the LLM and keeps the no-op path clean.
+    const items = queryObservationInbox(obsDir).filter((it) => it.severity !== 'noise');
+    if (items.length === 0) {
+        process.stderr.write(lang === 'zh'
+            ? `✅ ${obsDir} 没有可回流的失败信号（噪声级已跳过）\n`
+            : `✅ No recyclable failure signals in ${obsDir} (noise-level skipped)\n`);
+        return;
+    }
+    const outPath = join(obsDir, 'sample-drafts.json');
+    if (existsSync(outPath)) {
+        console.error(lang === 'zh'
+            ? `草稿已存在: ${outPath}，请先 review 并合入正式集（或删除）后再生成`
+            : `Draft already exists: ${outPath}; review/merge (or remove) it before regenerating`);
+        throw new CliExit(1);
+    }
+    const count = flags.count !== undefined ? Math.max(1, Number(flags.count) || 5) : undefined;
+    process.stderr.write(lang === 'zh'
+        ? `🔭 发现 ${items.length} 个失败信号，正在生成回归用例草稿...\n`
+        : `🔭 Found ${items.length} failure signal(s); generating regression-sample drafts...\n`);
+    try {
+        const { samples, costUSD } = await generateSamplesFromTraces({ items, count, model: flags.model });
+        const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
+        if (samples.length === 0) {
+            // The model conservatively skipped every signal (noise / unreproducible). That's a
+            // valid outcome, not a failure — don't write an empty draft file.
+            process.stderr.write(lang === 'zh'
+                ? `\n✅ 没有可复现的草稿用例（信号多为噪声 / 证据不足，已保守跳过），未写文件${cost}\n`
+                : `\n✅ No reproducible draft samples (signals were noise / insufficient evidence; conservatively skipped); nothing written${cost}\n`);
+            return;
+        }
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, JSON.stringify(samples, null, 2));
+        process.stderr.write(lang === 'zh'
+            ? `\n✅ 生成 ${samples.length} 条草稿用例 → ${outPath}（provenance: production-trace）${cost}\n   ⚠️ 这是草稿：trace 只抓失败信号，有抽样偏差。请人工 review 后再合入正式 eval-samples，不要直接当评测集。\n`
+            : `\n✅ Generated ${samples.length} draft sample(s) → ${outPath} (provenance: production-trace)${cost}\n   ⚠️ Draft only: traces capture failures, a biased sample. Review before merging into your eval-samples; don't use as-is.\n`);
+    }
+    catch (err) {
+        if (err instanceof CliExit)
+            throw err;
+        console.error(lang === 'zh' ? `生成失败: ${err.message}` : `Generation failed: ${err.message}`);
+        throw new CliExit(1);
+    }
+}
 async function runSample(args, flags, lang) {
+    if (flags['from-traces']) {
+        await runSampleFromTraces(flags, lang);
+        return;
+    }
     if (flags.fix) {
         await runSampleFix(args, flags, lang);
         return;
@@ -347,10 +405,24 @@ async function runSample(args, flags, lang) {
             throw new CliExit(1);
         }
         const skillContent = readFileSync(resolved.skillPath, 'utf-8');
-        const outputPath = resolved.samplesPath;
-        if (existsSync(outputPath)) {
-            console.error(tCli('cli.gen.samples_already_exists', lang));
-            throw new CliExit(1);
+        let outputPath;
+        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);
+                }
+            }
+            outputPath = 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 (count !== undefined) {
             process.stderr.write(tCli('cli.gen.single_generating', lang, { count }));
@@ -378,13 +450,13 @@ async function runSample(args, flags, lang) {
 }
 export default class Sample extends BaseCommand {
     static description = bilingual({
-        zh: '为指定 skill 生成评测用例（eval-samples），支持 batch / single / fix 三种模式。',
-        en: 'Generate eval samples for the given skill. Supports batch / single / fix modes.',
+        zh: '为指定 skill 生成评测用例（eval-samples），支持 batch / single / fix / from-traces 四种模式。',
+        en: 'Generate eval samples for the given skill. Supports batch / single / fix / from-traces modes.',
     });
     static examples = [
         {
             description: bilingual({
-                zh: '为单个 skill 生成默认数量的样本',
+                zh: '为单个 skill 生成默认数量的用例',
                 en: 'Generate default-count samples for a single skill',
             }),
             command: '<%= config.bin %> sample skills/my-skill/SKILL.md',
@@ -403,6 +475,13 @@ export default class Sample extends BaseCommand {
             }),
             command: '<%= config.bin %> sample skills/my-skill/SKILL.md --fix',
         },
+        {
+            description: bilingual({
+                zh: '从 observe inbox 的失败信号回流生成回归用例草稿',
+                en: 'Recycle observe-inbox failure signals into draft regression samples',
+            }),
+            command: '<%= config.bin %> sample --from-traces',
+        },
     ];
     static args = {
         skillPath: Args.string({
@@ -424,7 +503,7 @@ export default class Sample extends BaseCommand {
         }),
         count: Flags.string({
             description: bilingual({
-                zh: '生成样本条数。不传由 LLM 按 skill 类型自动决定。',
+                zh: '生成用例条数。不传由 LLM 按 skill 类型自动决定。',
                 en: 'Number of samples to generate. Defaults to LLM auto-selection by skill type.',
             }),
             parse: integerStringParser('--count', { min: 1 }),
@@ -475,6 +554,19 @@ export default class Sample extends BaseCommand {
                 en: 'Treatment name (fix mode), defaults to skill-path inference.',
             }),
         }),
+        'from-traces': Flags.boolean({
+            description: bilingual({
+                zh: 'from-traces 模式：从 observe inbox 的失败信号回流生成回归用例草稿（provenance: production-trace），落草稿待人工 review。',
+                en: 'from-traces mode: recycle observe-inbox failure signals into draft regression samples (provenance: production-trace) for review.',
+            }),
+            default: false,
+        }),
+        'observations-dir': Flags.string({
+            description: bilingual({
+                zh: 'observe inbox 目录（from-traces 模式用），默认项目 .omk/observations。',
+                en: 'Observe inbox dir (from-traces mode), default project .omk/observations.',
+            }),
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Sample);
@@ -484,4 +576,3 @@ export default class Sample extends BaseCommand {
         });
     }
 }
-//# sourceMappingURL=sample.js.map

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

@@ -20,4 +20,3 @@ export default class Studio extends BaseCommand {
     };
     run(): Promise<void>;
 }
-//# sourceMappingURL=studio.d.ts.map

package/dist/cli/commands/studio.js

@@ -155,4 +155,3 @@ export default class Studio extends BaseCommand {
         });
     }
 }
-//# sourceMappingURL=studio.js.map

package/dist/cli/index.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map