oh-my-knowledge 0.37.0 → 0.38.0

package/README.md

@@ -29,7 +29,7 @@ That's it — no editing required. `omk init` scaffolds two skill variants and t
 
 Walkthrough: [5-minute quickstart guide](docs/quickstart-skill-eval.md) (recommended for first-time users).
 
-Deeper: [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors](docs/reference/executors.md) · [artifact layout](docs/reference/artifact-layout.md)
+Deeper: [who omk is for](docs/explanation/who-omk-is-for.md) · [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors](docs/reference/executors.md) · [artifact layout](docs/reference/artifact-layout.md)
 
 ## Use inside AI Coding Agents
 

package/README.zh.md

@@ -29,7 +29,7 @@ omk eval --control code-review-v1 --treatment code-review-v2
 
 手把手教程：[5 分钟快速上手](docs/zh/quickstart-skill-eval.md)（推荐第一次跑评测的用户）。
 
-深入：[CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [artifact 布局](docs/zh/reference/artifact-layout.md)
+深入：[为谁、解决什么](docs/zh/explanation/who-omk-is-for.md) · [CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [artifact 布局](docs/zh/reference/artifact-layout.md)
 
 ## 在 AI Coding Agent 中使用
 

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

@@ -142,7 +142,7 @@ omk studio --host 0.0.0.0                 # 局域网访问（默认 127.0.0.1
 omk studio --no-open                      # 不自动开浏览器
 ```
 
-Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势；详情页（`/skills/<name>`）左栏列关键问题清单，右栏画健康趋势 + 三档阶段卡（doctor / eval / observe）。访问 `/observations/inbox` 查看 observe inbox 看板。
+Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势；详情页（`/skills/<name>`）左栏列关键问题清单，右栏画健康趋势 + 三档阶段卡（doctor / eval / observe）。访问 `/observe-inbox` 查看 observe inbox 看板。
 
 ## 第五步：解读结果
 

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

@@ -25,10 +25,11 @@ omk doctor [target] [flags]
 - `--executor` `option`:执行器名，默认 claude。指定为测试 fixture 路径可在测试里跑（同 omk doctor）。
 - `--fix` `boolean`:交互式修复：根据 doctor 报告问题，用 LLM agent 修复 skill。
 - `--gate` `boolean`:静默模式，只在 fail 时输出 stderr 摘要，exit code 标识结果。
+- `--global` `boolean`:写全局 ~/.oh-my-knowledge/doctors，而非项目 .omk/doctors
 - `--json` `boolean`:JSON 输出到 stdout，适合 CI / 外部脚本消费。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--model` `option`:LLM model 名，默认 sonnet。
-- `--output-dir` `option`:报告输出目录，默认 ~/.oh-my-knowledge/doctors。
+- `--output-dir` `option`:报告输出目录，默认项目级 .omk/doctors（--global 写全局）。
 - `--samples` `option`:用例文件路径（.json/.yaml）。不传则按 target / cwd 顺序自动发现。
 - `--static-only` `boolean`:离线静态模式，只跑 4 条静态 rule(skill_readable / skill_metadata / dependencies_present / samples_contract_aligned），不调 LLM。
 - `--timeout` `option`:单次 LLM 会话超时秒数，默认 600(10 分钟）。
@@ -79,6 +80,7 @@ omk eval [flags]
 - `--dry-run` `boolean`:只 plan 不实跑
 - `--effort` `option`:被测 LLM 扩展思考预算 low/medium/high/xhigh/max（默认 low；跨 effort 报告不严格可比）。
 - `--executor` `option`:执行器:claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令（默认 claude）。
+- `--global` `boolean`:报告写全局 ~/.oh-my-knowledge/reports，而非项目 .omk/
 - `--gold-dir` `option`:gold dataset 目录
 - `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。
 - `--judge-repeat` `option`:每个 dim 评 N 次
@@ -94,7 +96,7 @@ omk eval [flags]
 - `--no-judge` `boolean`:跳过 LLM judge
 - `--no-serve` `boolean`:不启 report server
 - `--no-strict-baseline` `boolean`:关闭 baseline 隔离
-- `--output-dir` `option`:报告输出目录
+- `--output-dir` `option`:报告输出目录（默认项目级 .omk/reports）
 - `--repeat` `option`:每个 sample 重复跑 N 次
 - `--report-only` `boolean`:生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
 - `--resume` `option`:从某次失败 run 续跑
@@ -234,6 +236,7 @@ omk evolve <skillPath> [flags]
 - `--significance-alpha` `option` (默认 `0.05`):显著性门的 diff CI 显著性水平（默认 0.05 = 95% CI）
 - `--skip-connectivity` `boolean`:跳过 LLM 连通性预检
 - `--skip-doctor` `boolean`:跳过 doctor 门禁（escape hatch，自负 garbage-in 风险）
+- `--snapshot-only` `boolean`:只产候选、不写回 source：胜出版本留在 evolve/<skillName>.r{N}.md 供你挑选，再 omk promote 接受。受管 skill 默认会写回 source 并记证据（measurable）。
 - `--stop-on-assertions-pass` `boolean`:普通用例断言全过时提前停止
 - `--target` `option`:目标 composite 分数，达到即停。不传则跑满 rounds
 - `--test-ratio` `option` (默认 `0`):锁定 test 集比例（0..1，默认 0=关），需配 --holdout-ratio。全程不参与选择，收尾读一次给无偏泛化分
@@ -255,7 +258,7 @@ omk evolve skills/my-skill/SKILL.md --target 4.5 --model opus --improve-model op
 
 ## omk init
 
-初始化 omk 项目脚手架（skills/ + eval-samples.json 模板）。
+初始化一个 omk 项目：在目标目录铺好待测知识载体（skills/）与评测用例（eval-samples.json），供 omk eval / doctor / evolve / observe / list 操作。默认是两版 code-review skill 的 A/B 起步模板。
 
 **用法:**
 
@@ -273,13 +276,13 @@ omk init [targetDir] [flags]
 
 **示例:**
 
-> 在当前目录初始化
+> 在当前目录初始化一个 omk 项目
 
 ```bash
 omk init
 ```
 
-> 在指定目录初始化
+> 在指定目录初始化一个 omk 项目
 
 ```bash
 omk init my-project
@@ -401,10 +404,11 @@ omk observe [sessionsDir] [flags]
 **Flags:**
 
 - `--from` `option`:起始时间 ISO，优先级高于 --last
+- `--global` `boolean`:写全局 ~/.oh-my-knowledge/observe-health，而非项目 .omk/observe-health
 - `--kb` `option`:知识库 root，启用 KB-aware 分析
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--last` `option`:时间窗(7d / 24h / 30m）
-- `--output-dir` `option`:分析结果输出目录
+- `--output-dir` `option`:健康报告输出目录，默认项目级 .omk/observe-health（--global 写全局）
 - `--skills` `option`:只看指定 skill，逗号分隔
 - `--to` `option`:结束时间 ISO
 
@@ -431,8 +435,9 @@ omk observe inbox [flags]
 - `--by-skill` `boolean`:按 skill 聚合输出
 - `--executor` `option`:LLM 增强复盘使用的执行器
 - `--explore` `option`:抽样 N 条 medium/low 长尾（replaces limit）
+- `--global` `boolean`:直接读取全局 ~/.oh-my-knowledge/observe-inbox（跳过项目级与兜底）。
 - `--include-noise` `boolean`:explore 时也包含 noise 桶
-- `--input-dir` `option`:inbox 数据目录，默认 .omk/observations（项目级，相对于 cwd）；目录不存在时兜底读 ~/.oh-my-knowledge/observations。
+- `--input-dir` `option`:inbox 数据目录，默认 .omk/observe-inbox（项目级，相对于 cwd）；目录不存在时兜底读 ~/.oh-my-knowledge/observe-inbox。
 - `--json` `boolean`:JSON 格式输出
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--limit` `option`:限制条数，默认 20
@@ -457,8 +462,9 @@ omk observe ingest <traceDir> [flags]
 
 **Flags:**
 
+- `--global` `boolean`:写入全局 ~/.oh-my-knowledge/observe-inbox，而非项目 .omk/observe-inbox。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
-- `--output-dir` `option`:输出目录，默认 .omk/observations（项目级，相对于 cwd）。
+- `--output-dir` `option`:输出目录，默认 .omk/observe-inbox（项目级，相对于 cwd；--global 写全局）。
 
 ## omk observe show
 
@@ -476,6 +482,7 @@ omk observe show <inboxId> [flags]
 
 **Flags:**
 
+- `--global` `boolean`:直接读取全局 ~/.oh-my-knowledge/observe-inbox（跳过项目级与兜底）。
 - `--input-dir` `option`:inbox 数据目录
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 
@@ -586,7 +593,7 @@ omk sample [skillPath] [flags]
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--model` `option` (默认 `sonnet`):生成 LLM model 名，默认 sonnet。
 - `--no-mock` `boolean`:不生成 mocks，eval 时所有工具调用真实执行。
-- `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observations。
+- `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observe-inbox。
 - `--reports-dir` `option`:报告目录（fix 模式用），默认 ~/.oh-my-knowledge/reports。
 - `--skill-dir` `option` (默认 `skills`):skill 根目录，默认 skills。batch 模式扫此目录。
 - `--treatment` `option`:指定 treatment 名（fix 模式用），默认推断自 skill 路径。
@@ -629,14 +636,16 @@ omk studio [flags]
 
 **Flags:**
 
-- `--analyses-dir` `option`:分析数据目录（可选）
+- `--analyses-dir` `option`:观测健康报告目录（可选，默认项目级 .omk/observe-health，空则全局兜底）
 - `--dev` `boolean`:dev 模式：子进程启动 + 热更新
+- `--doctors-dir` `option`:体检报告目录（可选，默认项目级 .omk/doctors，空则全局兜底）
+- `--global` `boolean`:只看全局 reports / observe-health / doctors / observe-inbox 目录（~/.oh-my-knowledge/*），而非机器级聚合 / 项目优先；managed 不受影响
 - `--host` `option`:监听 host，默认 localhost。改为 0.0.0.0 暴露给局域网
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--no-open` `boolean`:不自动打开浏览器
-- `--observations-dir` `option`:观测数据目录（可选）
+- `--observations-dir` `option`:观测收件箱数据目录（可选，默认 .omk/observe-inbox）
 - `--port` `option` (默认 `7799`):监听端口，默认 7799。传 0 让 OS 分配
-- `--reports-dir` `option`:报告目录，默认 ~/.oh-my-knowledge/reports
+- `--reports-dir` `option`:只看指定报告目录（可选；默认机器级聚合：当前项目 + 全局 + 别项目索引）
 
 **示例:**
 

package/dist/authoring/evolver.d.ts

@@ -182,6 +182,9 @@ interface EvolveOptions {
     /** Feed rejected candidate edits back into the next round's improvement prompt
      *  ("these were tried and did not help — don't repeat them"). Default true. */
     rejectMemory?: boolean;
+    /** 是否把胜出版本写回原 source 文件。默认 true（保「一键化」：evolve 跑完源即更新）。
+     *  `--snapshot-only` 置 false → 不写 source，候选仍落在 `evolve/<skillName>.r{N}.md` 供人工挑选 / promote。 */
+    writeBackToSource?: boolean;
     onProgress?: ProgressCallback | null;
     onRoundProgress?: ((progress: EvolveRoundProgressInfo) => void) | null;
 }
@@ -263,5 +266,5 @@ export interface RoundReport {
     report: Report;
 }
 export declare function mergeEvolveReports(roundReports: RoundReport[], skillName: string, totalCostUSD: number, samples?: Sample[], skillPath?: string): Report;
-export declare function evolveSkill({ skillPath, samplesPath, rounds, target, stopOnAssertionsPass, autoFixSamples, sampleFixMaxAttempts, reuseLatestEval, model, judgeModels, improveModel, improveMode, executorName, concurrency, timeoutMs, skipConnectivity, effort, noDiagnostic, skipDoctor, holdoutRatio, significanceGate, significanceAlpha, testRatio, editBudget, rejectMemory, onProgress, onRoundProgress, }: EvolveOptions): Promise<EvolveResult>;
+export declare function evolveSkill({ skillPath, samplesPath, rounds, target, stopOnAssertionsPass, autoFixSamples, sampleFixMaxAttempts, reuseLatestEval, model, judgeModels, improveModel, improveMode, executorName, concurrency, timeoutMs, skipConnectivity, effort, noDiagnostic, skipDoctor, holdoutRatio, significanceGate, significanceAlpha, testRatio, editBudget, rejectMemory, writeBackToSource, onProgress, onRoundProgress, }: EvolveOptions): Promise<EvolveResult>;
 export {};

package/dist/authoring/evolver.js

@@ -2,8 +2,9 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, join, dirname, basename } from 'node:path';
 import { runEvaluation } from '../eval-workflows/run-evaluation.js';
 import { createExecutor, DEFAULT_MODEL, JUDGE_MODEL } from '../executors/index.js';
-import { persistReport, DEFAULT_OUTPUT_DIR, generateRunId, hashString } from '../eval-core/evaluation-reporting.js';
-import { createFileStore } from '../server/report-store.js';
+import { persistReport, DEFAULT_OUTPUT_DIR, runIdSuffix, hashString } from '../eval-core/evaluation-reporting.js';
+import { createOverlayReportStore } from '../server/report-store.js';
+import { projectReportsDir, globalReportsDir } from '../eval-core/measurement-dirs.js';
 import { analyzeResults } from '../analysis/report-diagnostics.js';
 import { loadSamples } from '../inputs/load-samples.js';
 import { hashArtifactSource } from '../inputs/content-hash.js';
@@ -87,7 +88,9 @@ function singleVariantReport(report, variantKey) {
     };
 }
 async function findReusableBaselineReport(opts) {
-    const store = createFileStore(DEFAULT_OUTPUT_DIR);
+    // baseline 复用读 overlay(项目 .omk/reports ∪ 全局):eval 写默认翻项目后,复用既能命中 eval 新写的项目
+    // baseline,又继续覆盖全局(含 evolve 自身写到全局的合并报告),复用命中率与报告数字不降。
+    const store = createOverlayReportStore(projectReportsDir(), globalReportsDir());
     const { samples } = loadSamples(opts.samplesPath);
     const artifactHash = opts.artifactHash;
     const reports = await store.findByArtifactHash(artifactHash);
@@ -544,7 +547,7 @@ export function mergeEvolveReports(roundReports, skillName, totalCostUSD, sample
         if (originalKey)
             artifactHashes[variantLabels[i]] = hashes[originalKey];
     }
-    const runId = `evolve-${skillName}-${generateRunId([skillName]).split('-').slice(-2).join('-')}`;
+    const runId = `evolve-${skillName}-${runIdSuffix()}`;
     const report = {
         kind: 'evaluation',
         id: runId,
@@ -570,7 +573,7 @@ export function mergeEvolveReports(roundReports, skillName, totalCostUSD, sample
     report.analysis = analyzeResults(report, { samples });
     return report;
 }
-export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target = null, stopOnAssertionsPass = false, autoFixSamples = false, sampleFixMaxAttempts = 2, reuseLatestEval = false, model = DEFAULT_MODEL, judgeModels, improveModel = DEFAULT_MODEL, improveMode = 'agent', executorName = 'claude', concurrency = 1, timeoutMs, skipConnectivity = false, effort, noDiagnostic, skipDoctor, holdoutRatio = 0, significanceGate = true, significanceAlpha = DEFAULT_BOOTSTRAP_ALPHA, testRatio = 0, editBudget = 0.2, rejectMemory = true, onProgress = null, onRoundProgress = null, }) {
+export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target = null, stopOnAssertionsPass = false, autoFixSamples = false, sampleFixMaxAttempts = 2, reuseLatestEval = false, model = DEFAULT_MODEL, judgeModels, improveModel = DEFAULT_MODEL, improveMode = 'agent', executorName = 'claude', concurrency = 1, timeoutMs, skipConnectivity = false, effort, noDiagnostic, skipDoctor, holdoutRatio = 0, significanceGate = true, significanceAlpha = DEFAULT_BOOTSTRAP_ALPHA, testRatio = 0, editBudget = 0.2, rejectMemory = true, writeBackToSource = true, onProgress = null, onRoundProgress = null, }) {
     if (judgeModels && judgeModels.length > 1) {
         throw new Error('evolveSkill does not support multi-judge ensemble (received '
             + `${judgeModels.length} judges). Pass a single-judge array, e.g. `
@@ -712,7 +715,8 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
         onRoundProgress({ round: 0, totalRounds: rounds, phase: 'baseline', score: bestScore, costUSD: baselineCost, costReported: baselineCostReported, reused: baselineReused });
     if (stopOnAssertionsPass && allNonTripwireAssertionsPass(baselineReport, baselineVariantKey)) {
         stopReason = 'assertions-pass';
-        writeFileSync(absSkillPath, currentBest);
+        if (writeBackToSource)
+            writeFileSync(absSkillPath, currentBest);
         const { samples } = loadSamples(absSamplesPath);
         const mergedReport = mergeEvolveReports(roundReports, skillName, totalCostUSD, samples, absSkillPath);
         persistReport(mergedReport, DEFAULT_OUTPUT_DIR);
@@ -908,8 +912,9 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
             break;
         }
     }
-    // Write best version back to original file only if an improvement was accepted
-    if (bestRound > 0) {
+    // Write best version back to original file only if an improvement was accepted.
+    // `--snapshot-only`（writeBackToSource=false）跳过写回:候选仍在 evolve/<skillName>.r{N}.md,源不动。
+    if (bestRound > 0 && writeBackToSource) {
         writeFileSync(absSkillPath, currentBest);
     }
     // Merge all round reports into one and persist

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

@@ -17,6 +17,7 @@ export default class Doctor extends BaseCommand {
         samples: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         timeout: 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>;
         dimensions: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'static-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         fix: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/cli/commands/doctor.js

@@ -1,4 +1,3 @@
-import { homedir } from 'node:os';
 import { existsSync, statSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Args, Flags } from '@oclif/core';
@@ -8,6 +7,9 @@ import { numberStringParser } from '../oclif/parsers.js';
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { makeDoctorProgress } from '../lib/progress.js';
+import { DEFAULT_DOCTORS_DIR } from '../../eval-core/default-dirs.js';
+import { indexDoctorWrite, removeDoctorCard } from '../../eval-core/artifact-index.js';
+import { projectDoctorsDir, globalDoctorsDir } from '../../eval-core/measurement-dirs.js';
 const DEFAULT_SAMPLE_FILENAMES = ['eval-samples.json', 'eval-samples.yaml', 'eval-samples.yml'];
 function findSamplesInDir(dir) {
     for (const name of DEFAULT_SAMPLE_FILENAMES) {
@@ -131,8 +133,14 @@ export default class Doctor extends BaseCommand {
         }),
         'output-dir': Flags.string({
             description: bilingual({
-                zh: '报告输出目录，默认 ~/.oh-my-knowledge/doctors。',
-                en: 'Report output dir, default ~/.oh-my-knowledge/doctors.',
+                zh: '报告输出目录，默认项目级 .omk/doctors（--global 写全局）。',
+                en: 'Report output dir, default project-level .omk/doctors (--global for global).',
+            }),
+        }),
+        global: Flags.boolean({
+            description: bilingual({
+                zh: '写全局 ~/.oh-my-knowledge/doctors，而非项目 .omk/doctors',
+                en: 'Write to global ~/.oh-my-knowledge/doctors instead of project .omk/doctors',
             }),
         }),
         dimensions: Flags.string({
@@ -260,7 +268,9 @@ export default class Doctor extends BaseCommand {
                 }
                 renderDoctorReportText(report, lang);
             }
-            persistDoctorReport(report, flags['output-dir'] ? resolve(flags['output-dir']) : undefined);
+            persistDoctorReport(report, flags['output-dir']
+                ? resolve(flags['output-dir'])
+                : (flags.global ? globalDoctorsDir() : projectDoctorsDir()));
             if (flags.fix) {
                 const existing = report;
                 if (existing.outcome !== 'failed') {
@@ -279,7 +289,7 @@ export default class Doctor extends BaseCommand {
 // scanDoctorReports 扫盘成本)。50 = ~每天 1 跑撑 1.5 个月 sparkline,够用。
 const DOCTOR_HISTORY_MAX_PER_SKILL = 50;
 function persistDoctorReport(report, outputDir) {
-    const dir = outputDir ?? join(homedir(), '.oh-my-knowledge', 'doctors');
+    const dir = outputDir ?? DEFAULT_DOCTORS_DIR;
     mkdirSync(dir, { recursive: true });
     const safeId = report.id.replace(/[/\\:*?"<>|]/g, '_');
     for (const skill of report.skills) {
@@ -301,7 +311,14 @@ function persistDoctorReport(report, outputDir) {
             outcome: skill.status === 'fail' ? 'failed' : skill.status === 'warn' ? 'warnings_only' : 'passed',
         };
         const safeName = skill.skillName.replace(/[/\\:*?"<>|]/g, '_');
-        writeFileSync(join(dir, `${safeName}-${safeId}.json`), JSON.stringify(perSkill, null, 2), 'utf8');
+        const cardId = `${safeName}-${safeId}`;
+        const filePath = join(dir, `${cardId}.json`);
+        writeFileSync(filePath, JSON.stringify(perSkill, null, 2), 'utf8');
+        // 产物发现索引:per-skill 报告落项目本地后,best-effort 追加全局轻卡片,让 studio 跨项目聚合。
+        indexDoctorWrite({
+            id: cardId, path: filePath, skillName: skill.skillName, reportId: report.id, timestamp: report.timestamp,
+            status: skill.status, passCount: counts.pass, warnCount: counts.warn, failCount: counts.fail,
+        }, dir);
         pruneDoctorHistory(dir, skill.skillName, DOCTOR_HISTORY_MAX_PER_SKILL);
     }
 }
@@ -332,5 +349,8 @@ export function pruneDoctorHistory(dir, skillName, maxKeep) {
             unlinkSync(join(dir, file));
         }
         catch { /* ignore */ }
+        // 连带删卡片:否则被 prune 掉的报告会经 listDoctorCards 合并在本项目 studio「复活」(正文已删、卡片还在)。
+        // 卡片 id = 文件 stem(`{name}-{id}`),与 indexDoctorWrite 写入口径一致。
+        removeDoctorCard(file.replace(/\.json$/, ''));
     }
 }

package/dist/cli/commands/eval/gold/compare.js

@@ -4,7 +4,7 @@ import { BaseCommand } from '../../../oclif/base-command.js';
 import { LANG_FLAG, bilingual } from '../../../oclif/i18n.js';
 import { integerStringParser } from '../../../oclif/parsers.js';
 import { CliExit } from '../../../lib/cli-exit.js';
-import { DEFAULT_REPORTS_DIR } from '../../../lib/parse-run-config.js';
+import { projectReportsDir, globalReportsDir } from '../../../../eval-core/measurement-dirs.js';
 import { requireEvaluationReport } from '../../../lib/shared.js';
 export default class EvalGoldCompare extends BaseCommand {
     static description = bilingual({
@@ -62,7 +62,7 @@ export default class EvalGoldCompare extends BaseCommand {
             }
             const { loadGoldDataset } = await import('../../../../grading/gold-dataset.js');
             const { compareGoldToReport, formatGoldCompare } = await import('../../../../grading/gold-cli.js');
-            const { createFileStore } = await import('../../../../server/report-store.js');
+            const { createFileStore, createOverlayReportStore } = await import('../../../../server/report-store.js');
             const { dataset, issues } = loadGoldDataset(goldDir);
             if (!dataset) {
                 console.error('Cannot load gold dataset:');
@@ -72,8 +72,11 @@ export default class EvalGoldCompare extends BaseCommand {
             }
             for (const i of issues)
                 console.error(`warn: ${i.message}`);
-            const reportsDir = flags['reports-dir'] ?? DEFAULT_REPORTS_DIR;
-            const store = createFileStore(resolve(reportsDir));
+            // 显式 --reports-dir 固定该目录;默认 overlay(项目 .omk/reports 盖全局),get(reportId) 项目→全局兜底,
+            // 不因 eval 写默认翻项目而对比落空。
+            const store = flags['reports-dir']
+                ? createFileStore(resolve(flags['reports-dir']))
+                : createOverlayReportStore(projectReportsDir(), globalReportsDir());
             const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
             const samples = Math.max(100, Number(flags['bootstrap-samples'] ?? 1000) || 1000);
             const seedVal = flags.seed != null ? Number(flags.seed) : undefined;

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

@@ -18,6 +18,7 @@ export default class Eval extends BaseCommand {
         executor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'judge-models': 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>;
         'no-judge': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-cache': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;

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

@@ -84,8 +84,11 @@ function batchItemFallbackReport(batch, item) {
     };
 }
 async function loadBatchChildReports(batch, reportsDir, lang) {
-    const { createFileStore } = await import('../../../server/report-store.js');
-    const store = createFileStore(reportsDir);
+    // 读侧走 overlay(本次 reportsDir 优先 → 全局兜底):写默认翻项目后,batch.json 引用的存量 / 全局子报告
+    // 仍能 get 命中,不致降级到 batchItemFallbackReport(来自 batch metadata 的过时数据)。
+    const { createOverlayReportStore } = await import('../../../server/report-store.js');
+    const { globalReportsDir } = await import('../../../eval-core/measurement-dirs.js');
+    const store = createOverlayReportStore(reportsDir, globalReportsDir());
     const reports = [];
     for (const item of batch.items) {
         const loaded = await store.get(item.reportId);
@@ -134,6 +137,8 @@ async function announceSavedReport({ report, filePath, reportsDir, values, lang,
     process.stderr.write(tCli('cli.run.report_saved', lang, { path: filePath }));
     if (!values['no-serve'] && process.stdout.isTTY) {
         const { createReportServer } = await import('../../../server/report-server.js');
+        // eval 结束的即时 serve 刻意钉本次 outputDir(--global 时即全局),不走 overlay:它的语义是「看我刚跑的这份」,
+        // 单目录保证刚写的报告(含 --global 写到全局的)一定可见;浏览全机器历史是 omk studio 的事(默认 overlay 项目优先)。
         const server = createReportServer({ reportsDir });
         const serverUrl = await server.start();
         const reportUrl = `${serverUrl}/reports/${report.id}`;
@@ -368,7 +373,13 @@ export default class Eval extends BaseCommand {
             }),
         }),
         'output-dir': Flags.string({
-            description: bilingual({ zh: '报告输出目录', en: 'Report output dir' }),
+            description: bilingual({ zh: '报告输出目录（默认项目级 .omk/reports）', en: 'Report output dir (default project .omk/reports)' }),
+        }),
+        global: Flags.boolean({
+            description: bilingual({
+                zh: '报告写全局 ~/.oh-my-knowledge/reports，而非项目 .omk/',
+                en: 'Write report to global ~/.oh-my-knowledge/reports instead of project .omk/',
+            }),
         }),
         // ── 评测 toggle ──
         'no-judge': Flags.boolean({

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

@@ -41,6 +41,7 @@ export default class Evolve extends BaseCommand {
         'auto-fix-samples': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'sample-fix-max-attempts': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'reuse-latest-eval': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'snapshot-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'improve-mode': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'holdout-ratio': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'no-significance-gate': import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/cli/commands/evolve.js

@@ -7,6 +7,17 @@ import { enumStringParser, integerStringParser, numberStringParser } from '../oc
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { makeOnProgress } from '../lib/progress.js';
+/** 受管联动旁路:evolve 写回 source 后记证据 + re-baseline。任何异常都不该让 evolve 失败,
+ *  故 try/catch 吞掉、返回 null(同 eval 的 recordEvidenceSafely 口径)。 */
+async function recordEvolveOutcomeSafely(input) {
+    try {
+        const { recordEvolveOutcome } = await import('../lib/record-evolve-outcome.js');
+        return await recordEvolveOutcome(input);
+    }
+    catch {
+        return null;
+    }
+}
 const VALID_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
 function validateEvolveEffort(raw, lang) {
     if (!VALID_EFFORTS.has(raw)) {
@@ -77,6 +88,9 @@ export async function runEvolve(args, flags, lang) {
         throw new CliExit(1);
     }
     const skillPath = resolvedInput.skillPath;
+    // evolve 目标的形态(目录-skill / 文件-skill),供受管联动按形态精确匹配记录。**取解析后形态**而非「入参是不是
+    // 目录」:帮助文档鼓励传 `skills/foo/SKILL.md`,若按入参判会得 false、匹配不到 install 落的目录记录(漂移永不消)。
+    const skillIsDir = resolvedInput.isDirectorySkill;
     let samplesFile = flags.samples;
     if (samplesFile === 'eval-samples.json' && !existsSync(resolve(samplesFile))) {
         samplesFile = resolvedInput.samplesPath;
@@ -183,6 +197,8 @@ export async function runEvolve(args, flags, lang) {
             testRatio: Number(flags['test-ratio']),
             editBudget: flags['no-edit-budget'] ? 0 : Number(flags['edit-budget']),
             rejectMemory: !flags['no-reject-memory'],
+            // --snapshot-only:不写回 source,候选只留在 evolve/<skillName>.r{N}.md(供人工挑选 / promote)。
+            writeBackToSource: !flags['snapshot-only'],
             improveMode: flags['improve-mode'] === 'rewrite' ? 'rewrite' : 'agent',
             onProgress: makeOnProgress(lang),
             onRoundProgress({ round, totalRounds: _totalRounds, phase, score, delta, accepted, costUSD, costReported, error, significant }) {
@@ -246,6 +262,28 @@ export async function runEvolve(args, flags, lang) {
         if (result.reportId) {
             process.stderr.write(tCli('cli.evolve.report_link', lang, { id: result.reportId }));
         }
+        if (flags['snapshot-only']) {
+            // 不写回 source —— 候选留在 evolve/ 供人工挑选;受管记录不动。
+            process.stderr.write(tCli('cli.evolve.snapshot_only_hint', lang, {
+                dir: join(resolve(skillPath, '..'), 'evolve'),
+            }));
+        }
+        else {
+            // 受管 skill:把胜出版本记成带 verdict 的证据 + re-baseline → omk list 显 measurable。
+            // 升 promoted 仍由人 omk promote 决定(统计门 ≠ 人的接受)。未纳管 / 无改进 → 静默 no-op。
+            const recorded = await recordEvolveOutcomeSafely({
+                reportId: result.reportId,
+                bestRound: result.bestRound,
+                skillPath: resolvedInput.skillPath,
+                skillDir: resolvedInput.skillDir,
+                isDirectorySkill: skillIsDir,
+            });
+            if (recorded) {
+                process.stderr.write(tCli('cli.evolve.evidence_recorded_managed', lang, {
+                    name: recorded.name, verdict: recorded.verdict,
+                }));
+            }
+        }
         console.log(JSON.stringify(result, null, 2));
     }
     catch (err) {
@@ -398,6 +436,13 @@ export default class Evolve extends BaseCommand {
             }),
             default: false,
         }),
+        'snapshot-only': Flags.boolean({
+            description: bilingual({
+                zh: '只产候选、不写回 source：胜出版本留在 evolve/<skillName>.r{N}.md 供你挑选，再 omk promote 接受。受管 skill 默认会写回 source 并记证据（measurable）。',
+                en: 'Produce candidates only, do not write back to source: the winner stays in evolve/<skillName>.r{N}.md for you to pick and then omk promote. By default a managed skill is written back and evidence is recorded (measurable).',
+            }),
+            default: false,
+        }),
         'improve-mode': Flags.string({
             description: bilingual({
                 zh: '改写策略（默认：agent）',

package/dist/cli/commands/init.js

@@ -3,6 +3,15 @@ import { Args } from '@oclif/core';
 import { LANG_FLAG, bilingual, resolveLang } from '../oclif/i18n.js';
 import { BaseCommand } from '../oclif/base-command.js';
 import { tCli } from '../lib/i18n.js';
+// 预置 .omk/.gitignore:测量 bulk + doctor --fix 备份(项目本地、不该入库)默认不入库;
+// managed/ 治理档案 + 配置不在此列,默认 track。
+const INIT_OMK_GITIGNORE = `# omk 测量 bulk + doctor --fix 备份(项目本地)——不入库;前导 / 锚定 .omk/ 顶层,不误伤嵌套同名目录。
+/observe-health/
+/doctors/
+/observe-inbox/
+/reports/
+/backups/
+`;
 const INIT_SAMPLES = `[
   {
     "sample_id": "s001",
@@ -83,21 +92,21 @@ description: 多维度代码审查,覆盖安全 / 健壮 / 可维护 / 性能,
 `;
 export default class Init extends BaseCommand {
     static description = bilingual({
-        zh: '初始化 omk 项目脚手架（skills/ + eval-samples.json 模板）。',
-        en: 'Scaffold an omk project (skills/ + eval-samples.json templates).',
+        zh: '初始化一个 omk 项目：在目标目录铺好待测知识载体（skills/）与评测用例（eval-samples.json），供 omk eval / doctor / evolve / observe / list 操作。默认是两版 code-review skill 的 A/B 起步模板。',
+        en: 'Initialize an omk project: scaffold knowledge artifacts (skills/) and eval samples (eval-samples.json) in the target dir for omk eval / doctor / evolve / observe / list to work on. Ships a two-variant code-review A/B starter template by default.',
     });
     static examples = [
         {
             description: bilingual({
-                zh: '在当前目录初始化',
-                en: 'Init in current directory',
+                zh: '在当前目录初始化一个 omk 项目',
+                en: 'Initialize an omk project in the current directory',
             }),
             command: '<%= config.bin %> init',
         },
         {
             description: bilingual({
-                zh: '在指定目录初始化',
-                en: 'Init in specified directory',
+                zh: '在指定目录初始化一个 omk 项目',
+                en: 'Initialize an omk project in a specified directory',
             }),
             command: '<%= config.bin %> init my-project',
         },
@@ -139,6 +148,9 @@ export default class Init extends BaseCommand {
             writeFileSync(join(targetDir, 'eval-samples.json'), INIT_SAMPLES);
             writeFileSync(join(targetDir, 'skills', 'code-review-v1', 'SKILL.md'), INIT_SKILL_V1);
             writeFileSync(join(targetDir, 'skills', 'code-review-v2', 'SKILL.md'), INIT_SKILL_V2);
+            // 像 dvc init 那样预置忽略规则,开发者不会误把测量 bulk 提交进库。
+            mkdirSync(join(targetDir, '.omk'), { recursive: true });
+            writeFileSync(join(targetDir, '.omk', '.gitignore'), INIT_OMK_GITIGNORE);
             console.log(tCli('cli.init.scaffolded', lang, { dir: targetDir }));
             console.log('');
             console.log(tCli('cli.init.next_steps_title', lang));

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

@@ -1,9 +1,7 @@
 import { BaseCommand } from '../oclif/base-command.js';
-import { probeSourceState } from '../lib/source-probe.js';
 import { sanitizeCell } from '../lib/cell-format.js';
 import { type ManagedListRow } from '../../managed/index.js';
 import type { CliLang } from '../lib/i18n.js';
-export { probeSourceState };
 /** CJK 全角字符按 2 列计宽,使含中文表头的列也能对齐。 */
 export declare function dispWidth(s: string): number;
 /** 按**显示宽度**截断(不是 code unit):逐码点累加 dispWidth,绝不切断 surrogate 对、CJK 也不溢出列。 */

package/dist/cli/commands/list.js

@@ -2,12 +2,8 @@ import { 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 { probeSourceState } from '../lib/source-probe.js';
 import { sanitizeCell } from '../lib/cell-format.js';
-import { buildManagedListRows, globalManagedDir, loadAllManagedRecords, managedDir, resolveManagedDir, } from '../../managed/index.js';
-// 源探测(含 DoS / 软硬链 / 投毒守卫)已抽到 ../lib/source-probe.js,promote 复用同一套守卫与 drift 判定。
-// 此处 re-export 保持既有 import 入口不破(test/cli/list-probe.test.ts 仍从本文件取 probeSourceState)。
-export { probeSourceState };
+import { globalManagedDir, listManagedRows, managedDir, resolveManagedDir, } from '../../managed/index.js';
 /** CJK 全角字符按 2 列计宽,使含中文表头的列也能对齐。 */
 export function dispWidth(s) {
     let w = 0;
@@ -82,8 +78,7 @@ export default class List extends BaseCommand {
         const lang = this.lang;
         await this.runWithCliExit(async () => {
             const dir = flags.global ? globalManagedDir() : resolveManagedDir(managedDir());
-            const records = loadAllManagedRecords(dir);
-            const rows = buildManagedListRows(records, probeSourceState);
+            const rows = listManagedRows(dir);
             if (flags.json) {
                 // 版本化信封 —— 与 eval / doctor / diagnosis 等机读出口一致(都带 schemaVersion),让未来字段增删 /
                 // 改名是可检测的版本 bump,而非脚本静默 break。rows 的逐行形态见 ManagedListRow。

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

@@ -7,6 +7,7 @@ export default class ObserveInbox 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>;
         skill: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         limit: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         explore: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;