oh-my-knowledge 0.36.0 → 0.38.0

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

@@ -1,4 +1,14 @@
 import { BaseCommand } from '../../oclif/base-command.js';
+import type { SkillHealthReport } from '../../../observability/skill-health-analyzer.js';
+/**
+ * observe-health 报告落盘:id / 文件名加 4 位随机段,根治「同秒两次 omk observe 直接覆盖、数据丢失」的 bug。
+ * 保留 `-observe-health.json` 后缀 —— resolveObserveHealthDir 靠它判项目优先、listAnalyses 靠它取 id stem、
+ * loadAnalysis 靠 `${id}.json` 读真身。落盘后 best-effort 追加全局轻卡片,让 studio 跨项目聚合。
+ */
+export declare function persistObserveHealthReport(report: SkillHealthReport, outDir: string): {
+    id: string;
+    jsonPath: string;
+};
 export default class Observe extends BaseCommand {
     static description: string;
     static examples: {
@@ -16,6 +26,7 @@ export default class Observe extends BaseCommand {
         to: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         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>;
     };
     run(): Promise<void>;
 }

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

@@ -1,3 +1,4 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { Args, Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../../oclif/i18n.js';
@@ -5,12 +6,29 @@ import { BaseCommand } from '../../oclif/base-command.js';
 import { CliExit } from '../../lib/cli-exit.js';
 import { tCli } from '../../lib/i18n.js';
 import { parseLastWindow } from '../../lib/shared.js';
-// oclif 版 observe 默认命令 — `omk observe <sessions-dir>` 走 health 分析。
-// 三个子命令(ingest / inbox / show)由 src/cli/commands/observe/ 文件目录托管。
+import { projectObserveHealthDir, globalObserveHealthDir } from '../../../eval-core/measurement-dirs.js';
+import { indexObserveWrite } from '../../../eval-core/artifact-index.js';
+/**
+ * observe-health 报告落盘:id / 文件名加 4 位随机段,根治「同秒两次 omk observe 直接覆盖、数据丢失」的 bug。
+ * 保留 `-observe-health.json` 后缀 —— resolveObserveHealthDir 靠它判项目优先、listAnalyses 靠它取 id stem、
+ * loadAnalysis 靠 `${id}.json` 读真身。落盘后 best-effort 追加全局轻卡片,让 studio 跨项目聚合。
+ */
+export function persistObserveHealthReport(report, outDir) {
+    mkdirSync(outDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const rand = Math.random().toString(36).slice(2, 6);
+    const id = `${timestamp}-${rand}-observe-health`;
+    const jsonPath = join(outDir, `${id}.json`);
+    writeFileSync(jsonPath, JSON.stringify(report, null, 2));
+    indexObserveWrite(report, jsonPath, outDir, id);
+    return { id, jsonPath };
+}
+// `omk observe <sessions-dir>` 是默认命令 —— 分析 sessions 目录的 skill 调用健康度，产出 observe-health 报告(JSON)，
+// 由 Studio 健康报告页按需渲染。observe 这条线的另一条产物是观测收件箱(observe-inbox)，走子命令 ingest / inbox / show。
 export default class Observe extends BaseCommand {
     static description = bilingual({
         zh: '分析 sessions 目录的 skill 调用健康度（默认行为）。子命令:ingest / inbox / show。',
-        en: 'Analyze skill invocation health from sessions dir (default). Subcommands: ingest / inbox / show.',
+        en: 'Analyze skill invocation health from a sessions dir (default). Subcommands: ingest / inbox / show.',
     });
     static examples = [
         {
@@ -52,8 +70,14 @@ export default class Observe extends BaseCommand {
         }),
         'output-dir': Flags.string({
             description: bilingual({
-                zh: '分析结果输出目录',
-                en: 'Analysis output directory',
+                zh: '健康报告输出目录，默认项目级 .omk/observe-health（--global 写全局）',
+                en: 'Health report output dir, default project-level .omk/observe-health (--global for global)',
+            }),
+        }),
+        global: Flags.boolean({
+            description: bilingual({
+                zh: '写全局 ~/.oh-my-knowledge/observe-health，而非项目 .omk/observe-health',
+                en: 'Write to global ~/.oh-my-knowledge/observe-health instead of project .omk/observe-health',
             }),
         }),
     };
@@ -67,7 +91,7 @@ export default class Observe extends BaseCommand {
                 throw new CliExit(1);
             }
             const tracePath = resolve(dir);
-            const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');
+            const { existsSync } = await import('node:fs');
             if (!existsSync(tracePath)) {
                 console.error(`Trace path does not exist: ${tracePath}`);
                 throw new CliExit(1);
@@ -92,12 +116,11 @@ export default class Observe extends BaseCommand {
                 to,
                 skills,
             });
-            // JSON 是主产物；HTML 由 report server 的 /analyses/:id 按需渲染。
-            const outDir = resolve(flags['output-dir'] || join(process.env.HOME || '.', '.oh-my-knowledge', 'analyses'));
-            mkdirSync(outDir, { recursive: true });
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-            const jsonPath = join(outDir, `${timestamp}-skill-health.json`);
-            writeFileSync(jsonPath, JSON.stringify(report, null, 2));
+            // JSON 是主产物；HTML 由 report server 的健康报告详情页按需渲染。
+            const outDir = flags['output-dir']
+                ? resolve(flags['output-dir'])
+                : (flags.global ? globalObserveHealthDir() : projectObserveHealthDir());
+            const { 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)}%`);

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

@@ -7,6 +7,7 @@ export default class ObserveIngest extends BaseCommand {
     static flags: {
         lang: import("@oclif/core/interfaces").OptionFlag<string, 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>;
     };
     run(): Promise<void>;
 }

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

@@ -21,10 +21,17 @@ export default class ObserveIngest extends BaseCommand {
         lang: LANG_FLAG,
         'output-dir': Flags.string({
             description: bilingual({
-                zh: '输出目录，默认 .omk/observations（项目级，相对于 cwd）。',
-                en: 'Output dir, default .omk/observations (project-local, relative to cwd).',
+                zh: '输出目录，默认 .omk/observe-inbox（项目级，相对于 cwd；--global 写全局）。',
+                en: 'Output dir, default .omk/observe-inbox (project-local, relative to cwd; --global writes global).',
             }),
         }),
+        global: Flags.boolean({
+            description: bilingual({
+                zh: '写入全局 ~/.oh-my-knowledge/observe-inbox，而非项目 .omk/observe-inbox。',
+                en: 'Write to global ~/.oh-my-knowledge/observe-inbox instead of project .omk/observe-inbox.',
+            }),
+            default: false,
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(ObserveIngest);
@@ -54,8 +61,10 @@ export default class ObserveIngest extends BaseCommand {
                     : 'Error: --output-dir must not be an empty string.');
                 throw new CliExit(2);
             }
-            const { buildObservationInboxReport, saveObservationInboxReport, DEFAULT_OBSERVATIONS_DIR } = await import('../../../observability/inbox.js');
-            const outDir = resolve(outDirRaw ?? DEFAULT_OBSERVATIONS_DIR);
+            const { buildObservationInboxReport, saveObservationInboxReport, DEFAULT_PROJECT_OBSERVATIONS_DIR, DEFAULT_GLOBAL_OBSERVATIONS_DIR } = await import('../../../observability/inbox.js');
+            // 显式 --output-dir 最高;否则 --global 写全局、默认写项目(读侧 loadObservationInboxReports 会从项目兜底到全局)。
+            const defaultDir = flags.global ? DEFAULT_GLOBAL_OBSERVATIONS_DIR : DEFAULT_PROJECT_OBSERVATIONS_DIR;
+            const outDir = resolve(outDirRaw ?? defaultDir);
             const { loadObservationReviewState } = await import('../../../observability/review-state.js');
             const { buildObserveDiagnosticsFromReport } = await import('../../../diagnosis/observe-producer.js');
             const report = buildObservationInboxReport(tracePath, { reviewState: loadObservationReviewState(outDir) });

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

@@ -7,6 +7,7 @@ export default class ObserveShow extends BaseCommand {
     static flags: {
         lang: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'input-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

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

@@ -25,6 +25,13 @@ export default class ObserveShow extends BaseCommand {
                 en: 'Inbox data dir',
             }),
         }),
+        global: Flags.boolean({
+            description: bilingual({
+                zh: '直接读取全局 ~/.oh-my-knowledge/observe-inbox（跳过项目级与兜底）。',
+                en: 'Read directly from global ~/.oh-my-knowledge/observe-inbox (skip project-local and fallback).',
+            }),
+            default: false,
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(ObserveShow);
@@ -35,8 +42,11 @@ export default class ObserveShow extends BaseCommand {
                 console.error(lang === 'zh' ? '用法：omk observe show <inbox_id> [--input-dir <path>]' : 'Usage: omk observe show <inbox_id> [--input-dir <path>]');
                 throw new CliExit(1);
             }
-            const { findObservationInboxItem, formatObservationShow, DEFAULT_OBSERVATIONS_DIR } = await import('../../../observability/inbox.js');
-            const dir = resolve(flags['input-dir'] || DEFAULT_OBSERVATIONS_DIR);
+            const { findObservationInboxItem, formatObservationShow, DEFAULT_OBSERVATIONS_DIR, DEFAULT_GLOBAL_OBSERVATIONS_DIR } = await import('../../../observability/inbox.js');
+            // 显式 --input-dir 最高;否则 --global 直读全局、默认读项目(空则 findObservationInboxItem 兜底全局)。与 observe inbox 同口径。
+            const dir = flags['input-dir']
+                ? resolve(flags['input-dir'])
+                : (flags.global ? DEFAULT_GLOBAL_OBSERVATIONS_DIR : DEFAULT_OBSERVATIONS_DIR);
             const item = findObservationInboxItem(id, dir);
             if (!item) {
                 console.error(lang === 'zh' ? `未找到 observation：${id}` : `Observation not found: ${id}`);

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

@@ -0,0 +1,24 @@
+import { BaseCommand } from '../oclif/base-command.js';
+export default class Promote extends BaseCommand {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        lang: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        kind: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'accept-cautious': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        actor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private emitBlocked;
+    private emitPromoted;
+}

package/dist/cli/commands/promote.js

@@ -0,0 +1,157 @@
+import { execFileSync } from 'node:child_process';
+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 { CliExit } from '../lib/cli-exit.js';
+import { sanitizeCell } from '../lib/cell-format.js';
+import { getJudgePromptHash } from '../../grading/judge.js';
+import { appendManagedDecision, evaluatePromoteGate, globalManagedDir, isCurrentlyPromoted, loadManagedRecord, probeSourceState, managedDir, managedRecordId, resolveManagedDir, } from '../../managed/index.js';
+const SUPPORTED_KINDS = ['skill'];
+/** 决定的 actor:--actor > git config user.name > $USER / $LOGNAME > unknown。git 参数无用户输入,安全。 */
+function resolveActor(flagActor) {
+    if (flagActor && flagActor.trim())
+        return flagActor.trim();
+    try {
+        const name = execFileSync('git', ['config', 'user.name'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (name)
+            return name;
+    }
+    catch { /* git 缺失 / 无配置 → 回退环境 */ }
+    return process.env.USER || process.env.LOGNAME || 'unknown';
+}
+/** 洗 detail 里来自受管 JSON 的不可信值(verdict / judgePromptHash),文本输出防 ANSI/OSC 注入。 */
+function safeDetail(detail) {
+    if (!detail)
+        return undefined;
+    return Object.fromEntries(Object.entries(detail).map(([k, v]) => [k, sanitizeCell(v)]));
+}
+/** blockKind → i18n key(细节 detail 作为 tCli params,文本路径经 safeDetail 洗白)。 */
+const BLOCK_KEY = {
+    drifted: 'cli.promote.drifted',
+    no_current_evidence: 'cli.promote.no_current_evidence',
+    incomparable: 'cli.promote.incomparable',
+    verdict_blocked: 'cli.promote.verdict_blocked',
+};
+export default class Promote extends BaseCommand {
+    static description = bilingual({
+        zh: '把受管 skill 的当前版本按证据门禁「接受」为 promoted：默认仅放行 verdict=PROGRESS,在记录里追加一条带证据指针的人工决定。',
+        en: 'Accept a managed skill\'s current version as promoted, gated on evidence: by default only verdict=PROGRESS passes; appends a human decision with an evidence pointer to the record.',
+    });
+    static examples = [
+        { description: bilingual({ zh: 'promote 一个证据达标的 skill', en: 'Promote a skill whose evidence passes the gate' }), command: '<%= config.bin %> promote review' },
+        { description: bilingual({ zh: '接受 CAUTIOUS 结果（显式放宽门禁）', en: 'Accept a CAUTIOUS result (explicitly loosen the gate)' }), command: '<%= config.bin %> promote review --accept-cautious' },
+        { description: bilingual({ zh: '越门 promote 并记录理由（人工 override）', en: 'Override the gate and record a reason (human override)' }), command: '<%= config.bin %> promote review --force --reason "已人工复核"' },
+    ];
+    static args = {
+        name: Args.string({ description: bilingual({ zh: '受管 skill 名（omk list 里的 NAME）', en: 'Managed skill name (the NAME shown by omk list)' }), required: true }),
+    };
+    static flags = {
+        lang: LANG_FLAG,
+        kind: Flags.string({ description: bilingual({ zh: 'artifact 类型（当前仅 skill）', en: 'artifact kind (only skill today)' }), default: 'skill' }),
+        'accept-cautious': Flags.boolean({ description: bilingual({ zh: '把 CAUTIOUS 也算可接受（默认仅 PROGRESS）', en: 'also accept CAUTIOUS (default PROGRESS only)' }) }),
+        force: Flags.boolean({ description: bilingual({ zh: '越过可越门拦截强制 promote，记为人工 override 决定（无当前证据或源 hash 已变时仍拒）', en: 'override forceable gate blocks and force-promote, recorded as a human override (still refused with no current evidence or changed source hash)' }) }),
+        reason: Flags.string({ description: bilingual({ zh: 'promote / 越门的理由（写入决定）', en: 'reason for the promotion / override (stored on the decision)' }) }),
+        actor: Flags.string({ description: bilingual({ zh: '决定的 actor（默认取 git config user.name）', en: 'decision actor (defaults to git config user.name)' }) }),
+        global: Flags.boolean({ description: bilingual({ zh: '操作全局受管目录而非项目 .omk/managed', en: 'operate on the global managed dir instead of project .omk/managed' }) }),
+        json: Flags.boolean({ description: bilingual({ zh: '输出 JSON（版本化信封）供脚本消费', en: 'output JSON (versioned envelope) for scripts' }) }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Promote);
+        const lang = this.lang;
+        await this.runWithCliExit(async () => {
+            const name = args.name;
+            const kind = flags.kind;
+            if (!SUPPORTED_KINDS.includes(kind)) {
+                process.stderr.write(tCli('cli.promote.kind_unsupported', lang, { kind: sanitizeCell(String(kind)) }) + '\n');
+                throw new CliExit(1);
+            }
+            const dir = flags.global ? globalManagedDir() : resolveManagedDir(managedDir());
+            const record = loadManagedRecord(dir, managedRecordId(kind, name));
+            if (!record) {
+                process.stderr.write(tCli('cli.promote.not_managed', lang, { name: sanitizeCell(name), kind }) + '\n');
+                throw new CliExit(1);
+            }
+            const probe = probeSourceState(record);
+            const currentContentHash = probe.reachable ? probe.hash : undefined;
+            const sourceHashMismatch = probe.reachable && currentContentHash !== record.contentHash;
+            // 幂等：当前内容已 promote 过 → 无操作成功退出，不堆冗余事件。与 list 的不可达分支同口径：
+            // 源不可达不代表内容已变；只有源可达且 hash 已变时，才不把旧 promote 当作当前 no-op。
+            const alreadyPromoted = !sourceHashMismatch && isCurrentlyPromoted(record);
+            if (alreadyPromoted) {
+                if (flags.json)
+                    this.log(JSON.stringify({ schemaVersion: 1, alreadyPromoted: { name, contentHash: record.contentHash } }, null, 2));
+                else
+                    process.stderr.write(tCli('cli.promote.already_promoted', lang, { name: sanitizeCell(name) }) + '\n');
+                return;
+            }
+            const currentJudgeHashes = new Set([getJudgePromptHash(true), getJudgePromptHash(false)]);
+            const gate = evaluatePromoteGate({ record, currentContentHash, acceptCautious: flags['accept-cautious'], currentJudgeHashes });
+            // 拦截：无当前证据 force 也越不过；源可达但 hash 已变也不可越门，因为 decision 仍锚在
+            // record.contentHash，越过去后 list 仍会按当前源 hash 判 stale。源不可达则可作为人工未核越门。
+            const forceable = gate.evidence !== undefined && !sourceHashMismatch;
+            const reason = flags.reason?.trim();
+            if (!gate.ok && flags.force && forceable && !reason) {
+                if (flags.json)
+                    this.log(JSON.stringify({ schemaVersion: 1, blocked: { name, reasons: [{ blockKind: 'force_reason_required' }] } }, null, 2));
+                else
+                    process.stderr.write(tCli('cli.promote.force_reason_required', lang) + '\n');
+                throw new CliExit(1);
+            }
+            if (!gate.ok && !(flags.force && forceable)) {
+                this.emitBlocked(name, gate, lang, flags.json, forceable);
+                throw new CliExit(1);
+            }
+            // 通过 或 force 越门:写决定。
+            const overridden = !gate.ok; // 走到这里且未提前 return,说明是 force 越门
+            const evidence = gate.evidence; // forceable 已保证非空(无证据分支在上面已拦)
+            const decision = {
+                decisionKind: 'promote',
+                actor: resolveActor(flags.actor),
+                decidedAt: new Date().toISOString(),
+                contentHash: record.contentHash,
+                ...(evidence.reportId ? { reportId: evidence.reportId } : {}),
+                ...(reason ? { reason } : {}),
+                ...(overridden ? { override: { verdict: evidence.verdict ?? 'UNKNOWN', overriddenBlocks: gate.blocked.map((b) => b.blockKind) } } : {}),
+            };
+            appendManagedDecision(dir, record.id, decision);
+            // 非拦截级提醒(如 judgePromptHash 缺失)始终提示。当前 warnings 仅 incomparable_unverified 一类。
+            if (gate.warnings.length > 0)
+                process.stderr.write(tCli('cli.promote.incomparable_unverified', lang) + '\n');
+            this.emitPromoted(name, record, evidence.verdict, evidence.reportId, overridden, lang, flags.json);
+        });
+    }
+    emitBlocked(name, gate, lang, json, forceable) {
+        if (json) {
+            this.log(JSON.stringify({ schemaVersion: 1, blocked: { name, reasons: gate.blocked.map((b) => ({ blockKind: b.blockKind, ...(b.detail ? { detail: b.detail } : {}) })) } }, null, 2));
+            return;
+        }
+        process.stderr.write(tCli('cli.promote.blocked_header', lang, { name: sanitizeCell(name) }) + '\n');
+        // detail 里的 verdict / judgePromptHash 来自不可信受管 JSON,文本路径先洗(与 list 同口径,防 ANSI/OSC 注入)。
+        for (const b of gate.blocked)
+            process.stderr.write(tCli(BLOCK_KEY[b.blockKind], lang, safeDetail(b.detail)) + '\n');
+        if (gate.warnings.length > 0)
+            process.stderr.write(tCli('cli.promote.incomparable_unverified', lang) + '\n');
+        // 有可锚定证据(非「无证据」终态)才提示 --force 可越门。
+        if (forceable)
+            process.stderr.write(tCli('cli.promote.force_hint', lang) + '\n');
+    }
+    emitPromoted(name, record, verdict, reportId, overridden, lang, json) {
+        const hash = record.contentHash;
+        if (json) {
+            this.log(JSON.stringify({
+                schemaVersion: 1,
+                promoted: { name, kind: record.kind, contentHash: hash, ...(reportId ? { reportId } : {}), verdict: verdict ?? null, override: overridden },
+            }, null, 2));
+            return;
+        }
+        // hash / verdict / reportId 来自不可信受管 JSON,文本路径先洗(--json 路径上面已 return、保留原值)。
+        const short = sanitizeCell(hash.slice(0, 12));
+        const safeVerdict = sanitizeCell(verdict ?? 'UNKNOWN');
+        const safeName = sanitizeCell(name);
+        if (overridden)
+            this.log(tCli('cli.promote.forced_override', lang, { name: safeName, hash: short, verdict: safeVerdict }));
+        else
+            this.log(tCli('cli.promote.promoted', lang, { name: safeName, hash: short, verdict: safeVerdict, reportId: sanitizeCell(reportId ?? '—') }));
+    }
+}

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

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../oclif/base-command.js';
+export default class Rollback extends BaseCommand {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        lang: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        kind: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        actor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/cli/commands/rollback.js

@@ -0,0 +1,95 @@
+import { execFileSync } from 'node:child_process';
+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 { CliExit } from '../lib/cli-exit.js';
+import { sanitizeCell } from '../lib/cell-format.js';
+import { appendManagedDecision, globalManagedDir, isCurrentlyPromoted, loadManagedRecord, managedDir, managedRecordId, resolveManagedDir, } from '../../managed/index.js';
+const SUPPORTED_KINDS = ['skill'];
+/** 决定的 actor:--actor > git config user.name > $USER / $LOGNAME > unknown。git 参数无用户输入,安全。 */
+function resolveActor(flagActor) {
+    if (flagActor && flagActor.trim())
+        return flagActor.trim();
+    try {
+        const name = execFileSync('git', ['config', 'user.name'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (name)
+            return name;
+    }
+    catch { /* git 缺失 / 无配置 → 回退环境 */ }
+    return process.env.USER || process.env.LOGNAME || 'unknown';
+}
+export default class Rollback extends BaseCommand {
+    static description = bilingual({
+        zh: '回退受管 skill 当前版本的 promoted 接受：撤销最近一次 promote，在记录里追加一条 rollback 决定（源未漂移则状态回到 measurable，源已漂移则仍 stale）。',
+        en: 'Roll back a managed skill\'s current promoted acceptance: revoke the latest promote by appending a rollback decision (state returns to measurable if the source is unchanged, or stays stale if it has drifted).',
+    });
+    static examples = [
+        { description: bilingual({ zh: '回退一个已 promoted 的 skill', en: 'Roll back a promoted skill' }), command: '<%= config.bin %> rollback review' },
+        { description: bilingual({ zh: '回退并记录理由', en: 'Roll back and record a reason' }), command: '<%= config.bin %> rollback review --reason "线上发现回归"' },
+    ];
+    static args = {
+        name: Args.string({ description: bilingual({ zh: '受管 skill 名（omk list 里的 NAME）', en: 'Managed skill name (the NAME shown by omk list)' }), required: true }),
+    };
+    static flags = {
+        lang: LANG_FLAG,
+        kind: Flags.string({ description: bilingual({ zh: 'artifact 类型（当前仅 skill）', en: 'artifact kind (only skill today)' }), default: 'skill' }),
+        reason: Flags.string({ description: bilingual({ zh: '回退的理由（写入决定）', en: 'reason for the rollback (stored on the decision)' }) }),
+        actor: Flags.string({ description: bilingual({ zh: '决定的 actor（默认取 git config user.name）', en: 'decision actor (defaults to git config user.name)' }) }),
+        global: Flags.boolean({ description: bilingual({ zh: '操作全局受管目录而非项目 .omk/managed', en: 'operate on the global managed dir instead of project .omk/managed' }) }),
+        json: Flags.boolean({ description: bilingual({ zh: '输出 JSON（版本化信封）供脚本消费', en: 'output JSON (versioned envelope) for scripts' }) }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Rollback);
+        const lang = this.lang;
+        await this.runWithCliExit(async () => {
+            const name = args.name;
+            const kind = flags.kind;
+            if (!SUPPORTED_KINDS.includes(kind)) {
+                process.stderr.write(tCli('cli.rollback.kind_unsupported', lang, { kind: sanitizeCell(String(kind)) }) + '\n');
+                throw new CliExit(1);
+            }
+            const dir = flags.global ? globalManagedDir() : resolveManagedDir(managedDir());
+            const record = loadManagedRecord(dir, managedRecordId(kind, name));
+            if (!record) {
+                process.stderr.write(tCli('cli.rollback.not_managed', lang, { name: sanitizeCell(name), kind }) + '\n');
+                throw new CliExit(1);
+            }
+            // rollback 是内容锚定的纯决定撤销:只看 record.contentHash 上的 promote/rollback 事件流,不探源、不设门禁
+            // (降级永远安全)。当前未 promoted → 无可回退;若曾对当前内容 promote 过(即已回退)则幂等成功,否则报错。
+            if (!isCurrentlyPromoted(record)) {
+                const hadPromote = record.decisions.some((d) => d.decisionKind === 'promote' && d.contentHash === record.contentHash);
+                if (hadPromote) {
+                    if (flags.json)
+                        this.log(JSON.stringify({ schemaVersion: 1, alreadyRolledBack: { name, contentHash: record.contentHash } }, null, 2));
+                    else
+                        process.stderr.write(tCli('cli.rollback.already_rolled_back', lang, { name: sanitizeCell(name) }) + '\n');
+                    return;
+                }
+                if (flags.json)
+                    this.log(JSON.stringify({ schemaVersion: 1, notPromoted: { name } }, null, 2));
+                else
+                    process.stderr.write(tCli('cli.rollback.not_promoted', lang, { name: sanitizeCell(name) }) + '\n');
+                throw new CliExit(1);
+            }
+            const reason = flags.reason?.trim();
+            const decision = {
+                decisionKind: 'rollback',
+                actor: resolveActor(flags.actor),
+                decidedAt: new Date().toISOString(),
+                contentHash: record.contentHash,
+                ...(reason ? { reason } : {}),
+            };
+            appendManagedDecision(dir, record.id, decision);
+            if (flags.json) {
+                this.log(JSON.stringify({
+                    schemaVersion: 1,
+                    rolledBack: { name, kind: record.kind, contentHash: record.contentHash, ...(reason ? { reason } : {}) },
+                }, null, 2));
+                return;
+            }
+            // hash 来自不可信受管 JSON,文本路径先洗(--json 路径上面已 return、保留原值)。
+            this.log(tCli('cli.rollback.rolled_back', lang, { name: sanitizeCell(name), hash: sanitizeCell(record.contentHash.slice(0, 12)) }));
+        });
+    }
+}

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

@@ -26,6 +26,7 @@ export default class Sample extends BaseCommand {
         batch: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         count: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         model: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        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>;
         'no-mock': import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/cli/commands/sample.js

@@ -7,7 +7,7 @@ import { BaseCommand } from '../oclif/base-command.js';
 import { integerStringParser } from '../oclif/parsers.js';
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
-import { DEFAULT_REPORTS_DIR } from '../lib/parse-run-config.js';
+import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
 import { loadSamples, parseYaml } from '../../inputs/load-samples.js';
 import { hashSample } from '../../eval-core/evaluation-reporting.js';
 import { hashArtifactSource } from '../../inputs/content-hash.js';
@@ -154,9 +154,8 @@ export function writeFixedSamplesToSources(loaded, samples, changedIds) {
 }
 async function runSampleFix(args, flags, lang) {
     const { fixSamples } = await import('../../authoring/sample-fixer.js');
-    const { createFileStore } = await import('../../server/report-store.js');
+    const { createFileStore, createOverlayReportStore } = await import('../../server/report-store.js');
     const model = flags.model;
-    const reportsDir = resolve(flags['reports-dir'] ?? DEFAULT_REPORTS_DIR);
     const skillPath = args.skillPath;
     if (!skillPath) {
         console.error(lang === 'zh' ? '请指定 skill 路径，如: omk sample skills/my-skill/SKILL.md --fix' : 'Specify skill path: omk sample skills/my-skill/SKILL.md --fix');
@@ -181,10 +180,17 @@ async function runSampleFix(args, flags, lang) {
         : basename(resolvedSkillPath, extname(resolvedSkillPath));
     const treatmentName = flags.treatment ?? defaultTreatmentName;
     process.stderr.write(lang === 'zh' ? `🔍 正在查找 ${treatmentName} 的最新评测报告...\n` : `🔍 Scanning latest report for ${treatmentName}...\n`);
-    const store = createFileStore(reportsDir);
+    // 显式 --reports-dir 固定该目录;默认 overlay(项目 .omk/reports 盖全局),findByVariant 记录优先看项目、
+    // 空则全局兜底,不因 eval 写默认翻项目而查不到报告。
+    const store = flags['reports-dir']
+        ? createFileStore(resolve(flags['reports-dir']))
+        : createOverlayReportStore(projectReportsDir(), globalReportsDir());
     const reports = await store.findByVariant(treatmentName);
     if (reports.length === 0) {
-        console.error(lang === 'zh' ? `未找到 ${treatmentName} 的评测报告（报告目录: ${reportsDir}）` : `No eval report found for ${treatmentName} in ${reportsDir}`);
+        const where = flags['reports-dir']
+            ? resolve(flags['reports-dir'])
+            : (lang === 'zh' ? '项目 .omk/reports 或全局 ~/.oh-my-knowledge/reports' : 'project .omk/reports or global ~/.oh-my-knowledge/reports');
+        console.error(lang === 'zh' ? `未找到 ${treatmentName} 的评测报告（报告目录: ${where}）` : `No eval report found for ${treatmentName} in ${where}`);
         throw new CliExit(1);
     }
     const report = reports[0];
@@ -225,7 +231,7 @@ async function runSampleFix(args, flags, lang) {
     }
     process.stderr.write(lang === 'zh' ? `🔧 发现 ${sampleDesignCount} 条 sample_design 失败，开始修复...\n` : `🔧 Found ${sampleDesignCount} sample_design failure(s), fixing...\n`);
     const { createExecutor } = await import('../../executors/index.js');
-    const exec = createExecutor('claude');
+    const exec = createExecutor(flags.executor ?? 'claude');
     const executorFn = async (opts) => {
         const result = await exec({
             model: opts.model,
@@ -273,8 +279,8 @@ async function runSampleFromTraces(flags, lang) {
     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)`);
+            ? `observe-inbox 目录不存在: ${obsDir}（先运行 omk observe ingest 生成）`
+            : `Observe-inbox dir not found: ${obsDir} (run omk observe ingest first)`);
         throw new CliExit(1);
     }
     // Drop noise-tier signals up front: they're exactly what the generator is told to
@@ -298,7 +304,7 @@ async function runSampleFromTraces(flags, lang) {
         ? `🔭 发现 ${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 { samples, costUSD } = await generateSamplesFromTraces({ items, count, model: flags.model, executorName: flags.executor });
         const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
         if (samples.length === 0) {
             // The model conservatively skipped every signal (noise / unreproducible). That's a
@@ -380,7 +386,7 @@ async function runSample(args, flags, lang) {
             }
             try {
                 const skillContent = readFileSync(skillPath, 'utf-8');
-                const { samples, costUSD } = await generateSamples({ skillContent, count, model, focus, noMock: flags['no-mock'] });
+                const { samples, costUSD } = await generateSamples({ skillContent, count, model, focus, noMock: flags['no-mock'], executorName: flags.executor });
                 mkdirSync(dirname(samplesPath), { recursive: true });
                 writeFileSync(samplesPath, JSON.stringify(samples, null, 2));
                 const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
@@ -444,7 +450,7 @@ async function runSample(args, flags, lang) {
             process.stderr.write(tCli('cli.gen.single_generating_auto', lang));
         }
         try {
-            const { samples, costUSD } = await generateSamples({ skillContent, count, model, focus, noMock: flags['no-mock'] });
+            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)}` : '';
@@ -528,6 +534,12 @@ export default class Sample extends BaseCommand {
             }),
             default: 'sonnet',
         }),
+        executor: Flags.string({
+            description: bilingual({
+                zh: '执行器名，默认 claude（同 omk eval / doctor / evolve）。指定 codex 等其它执行器时，记得连带传一个该执行器能识别的 --model。',
+                en: 'Executor name, default claude (same as omk eval / doctor / evolve). When using another executor like codex, also pass a --model it recognizes.',
+            }),
+        }),
         'skill-dir': Flags.string({
             description: bilingual({
                 zh: 'skill 根目录，默认 skills。batch 模式扫此目录。',
@@ -576,8 +588,8 @@ export default class Sample extends BaseCommand {
         }),
         'observations-dir': Flags.string({
             description: bilingual({
-                zh: 'observe inbox 目录（from-traces 模式用），默认项目 .omk/observations。',
-                en: 'Observe inbox dir (from-traces mode), default project .omk/observations.',
+                zh: 'observe inbox 目录（from-traces 模式用），默认项目 .omk/observe-inbox。',
+                en: 'Observe inbox dir (from-traces mode), default project .omk/observe-inbox.',
             }),
         }),
     };

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

@@ -14,7 +14,9 @@ export default class Studio extends BaseCommand {
         host: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'reports-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'analyses-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'doctors-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'observations-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-open': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         dev: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };