oh-my-knowledge 0.34.0 → 0.36.0

package/dist/server/report-store.js

@@ -39,32 +39,33 @@ export function createFileStore(dir) {
         if (!data || typeof data !== 'object')
             return null;
         const record = data;
-        if (record.reportKind === 'evaluation') {
+        const kind = record.kind === 'evaluation' || record.kind === 'batch-evaluation'
+            ? record.kind
+            : undefined;
+        if (kind === 'evaluation') {
             if (!record.meta || !record.summary || !Array.isArray(record.results))
                 return null;
-            return { ...record, id: typeof record.id === 'string' && record.id ? record.id : fallbackId };
+            return {
+                ...record,
+                kind,
+                id: typeof record.id === 'string' && record.id ? record.id : fallbackId,
+            };
         }
-        if (record.reportKind === 'batch-evaluation') {
+        if (kind === 'batch-evaluation') {
             if (!record.meta || !Array.isArray(record.items))
                 return null;
-            return { ...record, id: typeof record.id === 'string' && record.id ? record.id : fallbackId };
-        }
-        if (record.kind === undefined
-            && record.overview === undefined
-            && record.artifacts === undefined
-            && record.meta
-            && record.summary
-            && Array.isArray(record.results)) {
             return {
                 ...record,
-                reportKind: 'evaluation',
+                kind,
                 id: typeof record.id === 'string' && record.id ? record.id : fallbackId,
             };
         }
+        // 只认 canonical 顶层 `kind`(evaluation / batch-evaluation)。不再为旧格式(顶层无该判别字段的
+        // 历史文件)做读兼容 —— 顶层 kind cutover 是硬切换,旧文件直接判脏丢弃。
         return null;
     }
     function isEvaluationReport(report) {
-        return report.reportKind === 'evaluation';
+        return report.kind === 'evaluation';
     }
     // Studio 每个 / 和 /skills/<name> 请求都调 list(),里面对每个 .json 同步 readFile +
     // JSON.parse。报告数上来后这是主性能瓶颈。缓存策略:fingerprint = dir mtime + 文件名
@@ -217,9 +218,9 @@ export async function queryJob(jobStore, id) {
 export async function queryRunList(reportStore) {
     return (await reportStore.list()).map((report) => ({
         id: report.id,
-        reportKind: report.reportKind,
+        kind: report.kind,
         meta: report.meta,
-        ...(report.reportKind === 'evaluation' ? { summary: report.summary } : { items: report.items }),
+        ...(report.kind === 'evaluation' ? { summary: report.summary } : { items: report.items }),
     }));
 }
 export async function queryRun(reportStore, id) {

package/dist/server/skill-index.js

@@ -69,7 +69,7 @@ function buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir
     // 每一段的 right-hand-side 从旧的 "{dir-mtime}-{file-count}" 双标量升级成
     // safeDirJsonContentFingerprint 返回的 "{dir-mtime}|{file1}:{m}:{s},..."
     // content-aware 字符串。
-    const reportIds = reports.map((r) => `${r.id}:${r.meta?.timestamp ?? ''}:${r.reportKind === 'evaluation' ? r.meta.evolve?.skillName ?? '' : ''}`).join(',');
+    const reportIds = reports.map((r) => `${r.id}:${r.meta?.timestamp ?? ''}:${r.kind === 'evaluation' ? r.meta.evolve?.skillName ?? '' : ''}`).join(',');
     const doctorsFp = safeDirJsonContentFingerprint(doctorsDir);
     const analysesFp = safeDirJsonContentFingerprint(analysesDir);
     const observationsFp = safeDirJsonContentFingerprint(observationsDir);
@@ -223,7 +223,8 @@ function scanDoctorReports(dir) {
             continue;
         try {
             const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            if (data?.reportKind !== 'doctor' || !Array.isArray(data.skills))
+            const kind = data?.kind === 'doctor' ? data.kind : null;
+            if (!kind || !Array.isArray(data.skills))
                 continue;
             const ts = data.timestamp;
             for (const sr of data.skills) {
@@ -260,7 +261,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     // ── eval 聚合(历史 list)─────────────────────────────────
     const evalBy = {};
     for (const r of reports) {
-        if (r.reportKind !== 'evaluation')
+        if (r.kind !== 'evaluation')
             continue;
         const variants = r.meta.variants || [];
         for (const v of variants) {
@@ -347,7 +348,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     // list 页对每个 entry 跑 detectInsights 的 CPU 开销迁移到这里,只 miss 时算一次。
     const insightsBySkill = new Map();
     for (const ent of entries) {
-        const evalReport = ent.eval ? reports.find((r) => r.id === ent.eval.reportId && r.reportKind === 'evaluation') : undefined;
+        const evalReport = ent.eval ? reports.find((r) => r.id === ent.eval.reportId && r.kind === 'evaluation') : undefined;
         insightsBySkill.set(ent.skillName, detectInsights(ent, evalReport ?? null, {
             diagnostics: diagnosisBundle.bySkill[ent.skillName] ?? [],
         }));

package/dist/types/doctor.d.ts

@@ -10,7 +10,7 @@ export type DoctorSkillStatus = 'pass' | 'warn' | 'fail';
 export type DoctorOutcome = 'passed' | 'warnings_only' | 'failed';
 /** Bumped whenever DoctorReport schema changes in a way CI consumers should
  *  be able to detect. CI can pin/check this when parsing the JSON. */
-export declare const DOCTOR_REPORT_SCHEMA_VERSION = "2.0.0";
+export declare const DOCTOR_REPORT_SCHEMA_VERSION = "3.0.0";
 export interface DoctorRuleResult {
     ruleId: string;
     severity: DoctorSeverity;
@@ -94,7 +94,7 @@ export interface DoctorSkillReport {
     status: DoctorSkillStatus;
 }
 export interface DoctorReport {
-    reportKind: 'doctor';
+    kind: 'doctor';
     /** Schema version the JSON consumer can pin/check. Bumped on any
      *  user-visible change to this report's shape. See DOCTOR_REPORT_SCHEMA_VERSION. */
     schemaVersion: string;

package/dist/types/doctor.js

@@ -1,6 +1,6 @@
 /** Bumped whenever DoctorReport schema changes in a way CI consumers should
  *  be able to detect. CI can pin/check this when parsing the JSON. */
-export const DOCTOR_REPORT_SCHEMA_VERSION = '2.0.0';
+export const DOCTOR_REPORT_SCHEMA_VERSION = '3.0.0';
 export function isComposerRule(r) {
     return r.ruleKind === 'composer';
 }

package/dist/types/eval.d.ts

@@ -136,10 +136,12 @@ export interface Artifact {
     kind: ArtifactKind;
     source: 'baseline' | 'variant-name' | 'file-path' | 'git' | 'inline' | 'custom';
     content: string | null;
+    contentHash?: string;
     locator?: string;
     ref?: string;
     cwd?: string;
     skillRoot?: string;
+    execRoot?: string;
     experimentRole?: ExperimentRole;
     allowedSkills?: string[];
     metadata?: Record<string, unknown>;
@@ -160,17 +162,26 @@ export interface VariantConfig {
     ref?: string;
     allowedSkills?: string[];
 }
+/** 远端 git 源的结构化引用 —— url/ref/spec 分字段,永不拼成单串再 split(避开 parseGitInput 的 `:`
+ *  与 parseVariantCwd 的 `@`)。eval 经 eval.yaml 结构化携带,install 经 --git-url/--git-ref。 */
+export interface RemoteGitRef {
+    url: string;
+    ref?: string;
+    spec: string;
+}
 export interface VariantSpec {
     name: string;
     role: ExperimentRole;
     expr: string;
+    git?: RemoteGitRef;
     cwd?: string;
     allowedSkills?: string[];
 }
 export interface EvalConfigVariant {
     name: string;
     role: ExperimentRole;
-    artifact: string;
+    artifact?: string;
+    git?: RemoteGitRef;
     cwd?: string;
     allowedSkills?: string[];
 }

package/dist/types/managed.d.ts

@@ -21,13 +21,35 @@ export interface ManagedDistributionTarget {
     contentHash: string;
     copiedAt: string;
 }
-/** 指向一份 Report 的引用——不是 verdict 本体。install 时为空,eval/promote 追加。 */
+/** 指向一份 Report 的引用 + 该 report 的最小可比性快照——不是 verdict 本体。install 时为空,
+ *  eval 完成后追加(见 `src/managed/evidence.ts`)。
+ *
+ *  `reportId` / `contentHash` 是承重的两根(读时门控只认这俩,validator 也只硬查这俩);其余三项是
+ *  `evidence-gated-management.md` §5 的 mandatory bundle —— **denormalize** 进记录(而非读时回 report
+ *  解析),让受管记录自解释、可 grep、不依赖 report 文件仍在盘。旧记录(eval 写入前)无这三项,按
+ *  optional 读;deriveManagedState 不依赖它们,故缺失不影响生命周期推导。 */
 export interface ManagedEvidenceRef {
     reportId: string;
     /** 该 report 测的是哪份内容(artifact contentHash)。读时只把与记录当前 contentHash 匹配的
      *  evidence 算作当前有效证据——重装到新内容后旧证据保留供回滚,但不让新内容显得已测。 */
     contentHash: string;
     recordedAt: string;
+    /** §5 mandatory:report 时计算的 verdict 等级(PROGRESS / CAUTIOUS / REGRESS / NOISE /
+     *  UNDERPOWERED / SOLO)。存字符串而非 import VerdictLevel —— 保 types 层为叶子、不依赖 eval-core。
+     *  measurable 不看 verdict(任何评测都算"已测");verdict 是 promote 门控的事。 */
+    verdict?: string;
+    /** §5 mandatory:样本集覆盖。`count`=被测样本数,`hash`=report 的 sampleHashes 排序后摘要
+     *  (同一样本集 ⇒ 同 hash),供 promote / list 不加载重 report 即可判覆盖与"同一用例集"。 */
+    sampleCoverage?: {
+        count: number;
+        hash: string;
+    };
+    /** §5 mandatory:可比性 marker。跨 report 比 verdict / Δ 前必须三者一致,否则不可比。 */
+    comparability?: {
+        cliVersion: string;
+        judgePromptHash?: string;
+        debiasMode?: Array<'length' | 'position'>;
+    };
 }
 export type ManagedDecisionKind = 'promote' | 'reject' | 'rollback';
 /** 一次人工管理决定。install 时为空,promote/reject/rollback 追加。 */
@@ -38,14 +60,17 @@ export interface ManagedDecision {
     reason?: string;
 }
 export interface ManagedArtifactSource {
-    /** 源类型(限定判别字,非裸 kind)。`file`=本地路径;`git`=当前仓库的某个 ref。 */
+    /** 源类型(限定判别字,非裸 kind)。`file`=本地路径;`git`=当前仓库某 ref 或远端(带 url)。 */
     sourceKind: 'file' | 'git';
     /** 源身份,按 sourceKind 分义:
      *   - file:本地重哈根(目录-skill 为根目录、文件-skill 为 .md),`hashArtifactSource(locator, isDirectorySkill)` 直接 round-trip;
-     *   - git:`git:<ref>:<name>`(非临时物化路径),drift 由 resolver 重物化重哈 —— mutable ref 给真实漂移、SHA 给不可变。 */
+     *   - 本地 git:`git:<ref>:<name>`;远端 git:`git+<url>@<sha>:<name>`(均非临时物化路径,远端串仅作身份、不回喂 parseGitInput)。
+     *     drift 由 resolver 重物化重哈 —— mutable ref 给真实漂移、SHA 给不可变。 */
     locator: string;
-    /** git 来源的 ref(file 源无)。 */
+    /** git 来源的 ref(file 源无);远端为 fetch 后 pin 的实际 SHA。 */
     ref?: string;
+    /** 远端 git 的 URL(本地源 / 本地 git 无)。结构化存,供 drift 重取,不必从 locator 反 parse。 */
+    url?: string;
     /** 目录-skill(SKILL.md + assets)还是裸 .md 文件-skill。 */
     isDirectorySkill: boolean;
 }

package/dist/types/observability.d.ts

@@ -43,8 +43,8 @@ export interface ObservationReviewStateEntry {
     snippet?: string;
 }
 export interface ObservationReviewState {
-    reportKind: 'observe-review-state';
-    schemaVersion: 1;
+    kind: 'observe-review-state';
+    schemaVersion: 2;
     updatedAt: string;
     entries: Record<string, ObservationReviewStateEntry>;
 }
@@ -184,8 +184,8 @@ export interface ObservationSessionTimeRange {
     durationMs?: number;
 }
 export interface ObservationInboxReport {
-    reportKind: 'observe-inbox';
-    schemaVersion: 1;
+    kind: 'observe-inbox';
+    schemaVersion: 2;
     meta: {
         tracePath: string;
         generatedAt: string;
@@ -735,8 +735,8 @@ export interface ExperienceSkillSummary {
     relatedObservationIds: string[];
 }
 export interface ObservationExperienceReport {
-    reportKind: 'observe-experience';
-    schemaVersion: 1;
+    kind: 'observe-experience';
+    schemaVersion: 2;
     scope: 'evidence-only';
     generatedAt: string;
     meta: {

package/dist/types/report.d.ts

@@ -237,10 +237,26 @@ export interface ReportMeta {
     timestamp: string;
     cliVersion: string;
     nodeVersion: string;
+    /** Per-artifact content fingerprint (variantName → SHA256-12, or 'no-skill' for baseline).
+     *  schemaVersion >= 3: hashes exactly the executor-visible input, and EVERY dir-skill (local OR
+     *  git) is materialized into an isolated content-addressed copy whose whole distributable tree
+     *  (SKILL.md + references/ assets, excluding .omk/.git/node_modules/evolve) is exposed to the
+     *  executor via cwd — so the fingerprint covers the whole tree and lives in the same space as the
+     *  install managed-record contentHash (evidence binds for all dir-skills). File-skill (local or
+     *  git) → the single .md bytes (also binds). schemaVersion 2 was a transitional era where local
+     *  dir-skills were tree-hashed but git dir-skills hashed SKILL.md bytes only (did not bind);
+     *  v2 git-dir-skill hashes are NOT comparable to v3. schemaVersion < 2 / absent: legacy
+     *  SKILL.md-body-text hash — NOT comparable to either. */
     artifactHashes: Record<string, string>;
-    /** v0.21 — Report JSON schema version. Reports without this field are treated as v0
-     *  (legacy field semantics: pre-v0.21 `gapRate`/`weightedGapRate` map to `evalGapRate`/
-     *  `evalWeightedGapRate` for eval-side reports). v0.21+ writes 1. */
+    /** Report JSON schema version. Reports without this field are treated as v0 (legacy field
+     *  semantics: pre-v0.21 `gapRate`/`weightedGapRate` map to `evalGapRate`/`evalWeightedGapRate`
+     *  for eval-side reports). Value 1 was specified for v0.21+ but never emitted in practice.
+     *  Value 2 marked the artifactHashes tree-hash era for local dir-skills (git dir-skills still
+     *  SKILL.md-only). Value 3 extends whole-tree hashing to git dir-skills via isolated copies
+     *  (all dir-skills bind). Value 4 keeps the v3 hash/binding semantics but marks the canonical
+     *  top-level discriminant era, so external consumers can version-gate the JSON shape. Drift /
+     *  lineage consumers gate on `>= 2` (tree-hash era); git-dir-skill binding additionally
+     *  requires `>= 3`. */
     schemaVersion?: number;
     /** SHA256-12 of every sample's content (sample_id → hash). Same hash = same sample. */
     sampleHashes?: Record<string, string>;
@@ -341,7 +357,7 @@ export interface SampleSnapshot {
     tripwire?: boolean;
 }
 export interface EvaluationReport {
-    reportKind: 'evaluation';
+    kind: 'evaluation';
     id: string;
     meta: ReportMeta;
     summary: Record<string, VariantSummary>;
@@ -355,6 +371,9 @@ export interface EvaluationReport {
 export type Report = EvaluationReport;
 export interface BatchEvaluationMeta {
     mode: 'skill';
+    /** Batch report JSON schema version. Kept in lockstep with child EvaluationReport top-level
+     *  shape so external consumers can identify the canonical discriminant era. */
+    schemaVersion: number;
     model: string;
     executor: string;
     skillDir: string;
@@ -394,7 +413,7 @@ export interface BatchEvaluationItem {
     variance?: VarianceData;
 }
 export interface BatchEvaluationReport {
-    reportKind: 'batch-evaluation';
+    kind: 'batch-evaluation';
     id: string;
     mode: 'skill';
     meta: BatchEvaluationMeta;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-knowledge",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "packageManager": "yarn@4.16.0",
   "description": "Evaluation framework for LLM knowledge inputs — prompts, RAG corpora, skills, agent workflows. Fix the model, vary the artifact. Built-in statistical rigor: bootstrap CI, Krippendorff α, length-debias, saturation curves.",
   "type": "module",
@@ -92,11 +92,11 @@
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
-    "@anthropic-ai/sdk": "^0.100.1",
+    "@anthropic-ai/sdk": "^0.102.0",
     "@inquirer/prompts": "^8.4.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@oclif/core": "^4",
-    "@openai/codex-sdk": "0.135.0",
+    "@openai/codex-sdk": "0.137.0",
     "ajv": "^8.18.0",
     "chart.js": "^4.5.1",
     "js-yaml": "^4.1.1",