oh-my-knowledge 0.33.0 → 0.35.0

package/dist/inputs/source-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 安装源解析器 —— 把"各种源"物化成统一的本地形态,让 install / managed 主干**源无关**。
+ * 新增一种源 = 加一个分支,install.ts 不动。本模块不依赖 CLI(不打印、不 tCli):错误以
+ * `SourceResolveError(messageKey)` 抛出,由调用方(install)映射成本地化文案。
+ *
+ * 当前支持:`file`(本地路径)、`git`(当前仓库的某个 ref)、远端 git(URL + ref,fetch 到临时 bare)。
+ * 三者沿同一 `ResolvedSource` 契约,install / managed 主干源无关。
+ */
+export { SourceResolveError } from './skill-loader.js';
+export type SourceKind = 'file' | 'git';
+export interface ResolvedSource {
+    sourceKind: SourceKind;
+    /** 物化后的本地根:目录-skill 为目录、文件-skill 为 .md;喂 hashArtifactSource + 分发。 */
+    localRoot: string;
+    /** skill 短名(分发落点 / 记录 name)。 */
+    name: string;
+    isDirectorySkill: boolean;
+    /** 记录身份:file=绝对路径;本地 git=`git:<ref>:<spec>`;远端 git=`git+<url>@<sha>:<spec>`
+     *  (均非临时物化路径;远端身份串仅作记录/相等比较,绝不回喂 parseGitInput 的 `:` 切分)。 */
+    locator: string;
+    /** git 来源的 ref;远端为 fetch 后 pin 的实际 SHA。 */
+    ref?: string;
+    /** 远端 git 的 URL(本地源 / 本地 git 无)。供受管记录结构化存、drift 重取,不挤进 locator 再 split。 */
+    url?: string;
+    /** 释放临时资源(git 删临时目录 / 远端另删 bare);file 源为 noop。 */
+    cleanup: () => void;
+}
+export declare function resolveInstallSource(input: string): ResolvedSource;
+/**
+ * 远端 git 源:`<url>` + `<ref>` + repo 相对 `<spec>`(三者结构化传入,URL 不经任何字符串切分,
+ * 避开 `parseGitInput` 的 `:` 与 `parseVariantCwd` 的 `@`)。fetch 到临时 bare → 复用既有
+ * classifyGitSkillRef / materializeGitSkillTree(repoRoot 换成 bare)。locator 落 `git+<url>@<sha>:<spec>`
+ * 仅作记录身份;url 另以结构化字段携带,供 drift 重取。失败 fail-closed 并清临时资源。
+ */
+export declare function resolveRemoteGitSource(url: string, ref: string, spec: string): ResolvedSource;

package/dist/inputs/source-resolver.js

@@ -0,0 +1,105 @@
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { classifyGitSkillRef, parseGitInput, resolveGitRepoContext, materializeGitSkillTree, skillNameFromPath, SourceResolveError, fetchRemoteGitRef } from './skill-loader.js';
+/**
+ * 安装源解析器 —— 把"各种源"物化成统一的本地形态,让 install / managed 主干**源无关**。
+ * 新增一种源 = 加一个分支,install.ts 不动。本模块不依赖 CLI(不打印、不 tCli):错误以
+ * `SourceResolveError(messageKey)` 抛出,由调用方(install)映射成本地化文案。
+ *
+ * 当前支持:`file`(本地路径)、`git`(当前仓库的某个 ref)、远端 git(URL + ref,fetch 到临时 bare)。
+ * 三者沿同一 `ResolvedSource` 契约,install / managed 主干源无关。
+ */
+// SourceResolveError 住在 skill-loader(让共享 materializeGitSkillTree 能抛它而不成环);此处 re-export
+// 保持 install 既有 import 不破。
+export { SourceResolveError } from './skill-loader.js';
+const noop = () => { };
+export function resolveInstallSource(input) {
+    if (input.startsWith('git:'))
+        return resolveGitSource(input);
+    return resolveFileSource(input);
+}
+/**
+ * 远端 git 源:`<url>` + `<ref>` + repo 相对 `<spec>`(三者结构化传入,URL 不经任何字符串切分,
+ * 避开 `parseGitInput` 的 `:` 与 `parseVariantCwd` 的 `@`)。fetch 到临时 bare → 复用既有
+ * classifyGitSkillRef / materializeGitSkillTree(repoRoot 换成 bare)。locator 落 `git+<url>@<sha>:<spec>`
+ * 仅作记录身份;url 另以结构化字段携带,供 drift 重取。失败 fail-closed 并清临时资源。
+ */
+export function resolveRemoteGitSource(url, ref, spec) {
+    const checkout = fetchRemoteGitRef(url, ref);
+    try {
+        // 远端 URL 指向仓库根,spec 是仓库相对路径 → gitRelDir 为空。
+        const resolved = classifyGitSkillRef(checkout.ref, '', spec, checkout.repoRoot);
+        if (!resolved)
+            throw new SourceResolveError('cli.install.remote_skill_not_found', { url, ref: checkout.ref, name: spec });
+        const mat = materializeGitSkillTree(checkout.ref, resolved, checkout.repoRoot);
+        return {
+            sourceKind: 'git',
+            localRoot: mat.localRoot,
+            name: mat.name,
+            isDirectorySkill: mat.isDirectorySkill,
+            locator: `git+${url}@${checkout.ref}:${spec}`,
+            ref: checkout.ref,
+            url,
+            cleanup: () => {
+                mat.cleanup();
+                checkout.cleanup();
+            },
+        };
+    }
+    catch (err) {
+        checkout.cleanup();
+        throw err;
+    }
+}
+function resolveFileSource(input) {
+    const abs = resolve(input);
+    if (!existsSync(abs))
+        throw new SourceResolveError('cli.install.path_not_found', { path: abs });
+    const isDir = statSync(abs).isDirectory();
+    if (isDir) {
+        const skillMd = join(abs, 'SKILL.md');
+        if (!existsSync(skillMd)) {
+            throw new SourceResolveError('cli.install.skillmd_missing', { path: abs });
+        }
+        // 软链 SKILL.md 会被分发跳过(与 git 物化、cpSync 的软链策略一致)→ 装出空壳。指向真源,让记录落在真源上。
+        if (lstatSync(skillMd).isSymbolicLink()) {
+            throw new SourceResolveError('cli.install.skillmd_is_symlink', { target: realpathSync(skillMd) });
+        }
+    }
+    if (!isDir && !/\.md$/i.test(abs)) {
+        throw new SourceResolveError('cli.install.not_a_skill', { path: abs });
+    }
+    const name = isDir ? skillNameFromPath(join(abs, 'SKILL.md')) : skillNameFromPath(abs);
+    return { sourceKind: 'file', localRoot: abs, name, isDirectorySkill: isDir, locator: abs, cleanup: noop };
+}
+function resolveGitSource(input) {
+    // 空 spec / 空 ref 由共享 parseGitInput 拒(返回 null):空 ref(`git::x`)会被 git 当 index/stage-0
+    // 解析,破坏"可复现、可重取"的前提;eval 与 install 经同一 helper 判定一致。
+    const parsed = parseGitInput(input);
+    if (!parsed)
+        throw new SourceResolveError('cli.install.git_skill_not_found', { ref: '', name: input });
+    const { ref, spec } = parsed;
+    let ctx;
+    try {
+        ctx = resolveGitRepoContext(resolve('.'));
+    }
+    catch {
+        throw new SourceResolveError('cli.install.not_a_git_repo', {});
+    }
+    const resolved = classifyGitSkillRef(ref, ctx.relDir, spec, ctx.repoRoot);
+    if (!resolved) {
+        throw new SourceResolveError('cli.install.git_skill_not_found', { ref, name: spec });
+    }
+    // 物化复用共享 materializeGitSkillTree(install 与 eval 同一条物化路径);install 只需在其上补
+    // locator / sourceKind 包成 ResolvedSource。
+    const mat = materializeGitSkillTree(ref, resolved, ctx.repoRoot);
+    return {
+        sourceKind: 'git',
+        localRoot: mat.localRoot,
+        name: mat.name,
+        isDirectorySkill: mat.isDirectorySkill,
+        locator: `git:${ref}:${spec}`,
+        ref,
+        cleanup: mat.cleanup,
+    };
+}

package/dist/inputs/url-fetcher.d.ts

@@ -16,4 +16,3 @@ export declare function isPlaceholderUrl(url: string): boolean;
  * @param skipUrls - URLs already resolved (e.g. by MCP), will be skipped
  */
 export declare function resolveUrls(samples: Sample[], skipUrls?: Set<string>): Promise<void>;
-//# sourceMappingURL=url-fetcher.d.ts.map

package/dist/inputs/url-fetcher.js

@@ -238,4 +238,3 @@ function getSolution(statusCode, result) {
     }
     return '请将文档内容复制到 eval-samples 的 context 字段中';
 }
-//# sourceMappingURL=url-fetcher.js.map

package/dist/managed/evidence.d.ts

@@ -0,0 +1,22 @@
+import type { EvaluationReport, ManagedEvidenceRef } from '../types/index.js';
+/**
+ * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ */
+export declare function buildEvidenceRef(report: EvaluationReport, variant: string, verdict: string, recordedAt: string): ManagedEvidenceRef | null;
+export interface RecordedEvidence {
+    recordId: string;
+    name: string;
+    contentHash: string;
+    /** true ⇒ evidence.contentHash 等于记录当前 contentHash → deriveManagedState 计为当前证据 →
+     *  measurable。false ⇒ 测的是旧内容(已 drift),证据留存但不绑当前版本。 */
+    bound: boolean;
+}
+/**
+ * 驱动:对每个能在报告里(按 contentHash 主键 / 同名回退)匹配到被测 variant 的**已纳管**记录,
+ * 追加一条 evidence。返回实际写入的清单(供 CLI 提示,`name` 取受管记录名而非 variant 键)。
+ * 无任何记录匹配 → 返回空(常见的非管理用户场景,静默无副作用)。
+ */
+export declare function recordEvalEvidence(report: EvaluationReport, verdict: string, recordedAt: string, opts?: {
+    dir?: string;
+}): RecordedEvidence[];

package/dist/managed/evidence.js

@@ -0,0 +1,143 @@
+/**
+ * eval → managed evidence 写入(承接 #203 管理支柱 / #214 验收第 3 条)。
+ *
+ * 一次 `omk eval` 跑完,把结果落成一条 `ManagedEvidenceRef` 追加进**已纳管**记录的 evidence[],
+ * 让 skill 从 `installed` 走到 `measurable`(由 `deriveManagedState` 读时推导)。承重前提是 #214/#218
+ * 已把 install 与 eval 的内容指纹统一到同一空间(整树哈),所以 `report.artifactHashes[variant]` 与
+ * `record.contentHash` 可直接相等比对、evidence 绑得上。
+ *
+ * 三条设计取舍(对应 issue #221 的"待定决策"):
+ *   - **触发**:eval 完成**自动**写,但只写**已存在**的受管记录 —— install 是显式 opt-in,未纳管的
+ *     skill 永不被凭空建记录(零副作用惊吓)。CLI 另给 `--no-evidence` 关闭。
+ *   - **多对一**:append-only + 按 (reportId, contentHash) 去重;保留全部历史条目,当前有效性仍由
+ *     `deriveManagedState` 按 contentHash 匹配裁定(重装新内容后旧证据留存供回滚,却不让新内容显得已测)。
+ *   - **跨源**:用三级身份消歧把被测 variant 对到受管记录(install 与 eval 命名不一致:记录名是
+ *     skill 短名 `review`,而 eval 报告 variant key 可能是整串表达式 `git:HEAD:skills/review`、
+ *     eval.yaml 别名 `candidate`、blind 模式的 `A`/`B`)。`applyBlindMode` 盲化 `variants` 但**不**动
+ *     `artifactHashes` / `variantConfigs` 的键面,故三级都按真实键工作:
+ *       (a) 显式**同名** variant —— 最强身份(本地 `--treatment <name>` 与 drift);
+ *       (b) **结构化源匹配** —— `variantConfigs[].locator(+ref)` 与 `record.source` 对齐(git / 远端 /
+ *           别名),即便内容撞哈也能精确消歧;
+ *       (c) **纯 contentHash 回退** —— 仅当该内容哈在受管记录中**唯一**才用。否则两条不同记录恰好当前
+ *           内容相同(同模板复制 / 刚装)时,只测了一条的 report 会把同哈的另一条也推成 measurable ——
+ *           唯一性闸门挡掉这种越权写入(撞哈又非同名 / 无结构化身份 → 跳过,不乱绑)。
+ *
+ * bundle 按 evidence-gated-management.md §5 denormalize 进记录(reportId / contentHash /
+ * verdict / sampleCoverage / comparability),不依赖 report 文件仍在盘。
+ */
+import { basename, dirname } from 'node:path';
+import { hashString } from '../eval-core/evaluation-reporting.js';
+import { loadAllManagedRecords, appendManagedEvidence, managedDir, resolveManagedDir } from './store.js';
+/** baseline / 无 skill 变体的 artifactHash 哨兵(见 report.ts artifactHashes 注释)——不产证据。 */
+const NO_SKILL = 'no-skill';
+/** 样本集覆盖摘要:report 的 sampleHashes 排序后取一个稳定 digest(同一样本集 ⇒ 同 hash)。
+ *  缺 sampleHashes(旧报告 / --dry-run)→ undefined,bundle 仍含其余三项 mandatory。 */
+function sampleCoverage(report) {
+    const sh = report.meta?.sampleHashes;
+    if (!sh)
+        return undefined;
+    const entries = Object.entries(sh).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return { count: entries.length, hash: hashString(JSON.stringify(entries)) };
+}
+/**
+ * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ */
+export function buildEvidenceRef(report, variant, verdict, recordedAt) {
+    const contentHash = report.meta?.artifactHashes?.[variant];
+    if (!contentHash || contentHash === NO_SKILL)
+        return null;
+    const meta = report.meta;
+    const cov = sampleCoverage(report);
+    return {
+        reportId: report.id,
+        contentHash,
+        recordedAt,
+        verdict,
+        ...(cov ? { sampleCoverage: cov } : {}),
+        comparability: {
+            cliVersion: meta.cliVersion,
+            ...(meta.judgePromptHash ? { judgePromptHash: meta.judgePromptHash } : {}),
+            ...(meta.debiasMode ? { debiasMode: meta.debiasMode } : {}),
+        },
+    };
+}
+/**
+ * variantConfig 的源身份是否与受管记录 source 对得上 —— install 与 eval 两侧 locator **口径不同**,
+ * 必须先归一化再比,不能裸字符串相等(否则同 hash 多记录场景下正确的本地 git / 目录-skill 也会因
+ * locator 不等而漏写):
+ *   - 直接相等:远端 git(两侧都 `git+<url>@<sha>:<spec>`)、本地 file-skill(两侧都是 .md 路径);
+ *   - 本地 git:install 记完整身份串 `git:<ref>:<spec>`,eval 把 spec 落 `cfg.locator`、ref 另存 `cfg.ref`
+ *     → 归一化成 `git:<cfg.ref>:<cfg.locator>` 再比;
+ *   - 本地目录-skill:install 记目录根,eval 记 `<dir>/SKILL.md` → 比 `dirname(cfg.locator)`。
+ */
+function sourceMatches(cfg, source) {
+    if (!cfg.locator)
+        return false;
+    if (cfg.locator === source.locator)
+        return true;
+    if (source.sourceKind === 'git' && cfg.ref && `git:${cfg.ref}:${cfg.locator}` === source.locator)
+        return true;
+    if (source.isDirectorySkill && basename(cfg.locator) === 'SKILL.md' && dirname(cfg.locator) === source.locator)
+        return true;
+    return false;
+}
+/**
+ * 给某条受管记录在报告里找该绑定的 variant key,三级身份消歧(见文件头「跨源」)。
+ * `hashIsUnique` 由调用方按全体受管记录的 contentHash 计数提供 —— 纯 hash 回退的越权闸门。
+ */
+function matchVariantKey(report, record, hashIsUnique) {
+    const hashes = report.meta?.artifactHashes ?? {};
+    // (a) 显式同名 variant(本地 --treatment <name> / drift)。
+    if (hashes[record.name] && hashes[record.name] !== NO_SKILL)
+        return record.name;
+    // (b) 结构化源匹配:variantConfig.locator(+ref) 对齐记录 source(git / 远端 / 别名)。
+    for (const cfg of report.meta?.variantConfigs ?? []) {
+        const h = hashes[cfg.variant];
+        if (!h || h === NO_SKILL)
+            continue;
+        if (sourceMatches(cfg, record.source))
+            return cfg.variant;
+    }
+    // (c) 纯 contentHash 回退 —— 仅当该哈在受管记录中唯一(否则撞哈会越权写到没测的记录)。
+    if (hashIsUnique(record.contentHash)) {
+        for (const [key, hash] of Object.entries(hashes)) {
+            if (hash !== NO_SKILL && hash === record.contentHash)
+                return key;
+        }
+    }
+    return undefined;
+}
+/**
+ * 驱动:对每个能在报告里(按 contentHash 主键 / 同名回退)匹配到被测 variant 的**已纳管**记录,
+ * 追加一条 evidence。返回实际写入的清单(供 CLI 提示,`name` 取受管记录名而非 variant 键)。
+ * 无任何记录匹配 → 返回空(常见的非管理用户场景,静默无副作用)。
+ */
+export function recordEvalEvidence(report, verdict, recordedAt, opts = {}) {
+    const out = [];
+    if (Object.keys(report.meta?.artifactHashes ?? {}).length === 0)
+        return out;
+    // 写回读方实际取记录的同一目录(project→global 同口径)。
+    const dir = resolveManagedDir(opts.dir ?? managedDir());
+    const records = loadAllManagedRecords(dir);
+    if (records.length === 0)
+        return out;
+    // 全体记录的 contentHash 计数 —— 纯 hash 回退只在唯一时放行(挡同内容多记录的越权写)。
+    const hashCount = new Map();
+    for (const r of records)
+        hashCount.set(r.contentHash, (hashCount.get(r.contentHash) ?? 0) + 1);
+    const hashIsUnique = (hash) => (hashCount.get(hash) ?? 0) === 1;
+    for (const rec of records) {
+        const variantKey = matchVariantKey(report, rec, hashIsUnique);
+        if (!variantKey)
+            continue;
+        const ref = buildEvidenceRef(report, variantKey, verdict, recordedAt);
+        if (!ref)
+            continue;
+        const merged = appendManagedEvidence(dir, rec.id, ref);
+        if (!merged)
+            continue;
+        out.push({ recordId: rec.id, name: rec.name, contentHash: ref.contentHash, bound: ref.contentHash === merged.contentHash });
+    }
+    return out;
+}

package/dist/managed/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 受管 artifact 域的单一公共入口。CLI、未来的 server / web / SDK 都从这里消费,
+ * 不直接依赖内部文件布局。
+ */
+export * from './store.js';
+export * from './evidence.js';

package/dist/managed/index.js

@@ -0,0 +1,6 @@
+/**
+ * 受管 artifact 域的单一公共入口。CLI、未来的 server / web / SDK 都从这里消费,
+ * 不直接依赖内部文件布局。
+ */
+export * from './store.js';
+export * from './evidence.js';

package/dist/managed/store.d.ts

@@ -0,0 +1,72 @@
+import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDistributionTarget, ManagedEvidenceRef } from '../types/index.js';
+/**
+ * 受管记录的 per-record 文件存储。一条记录一个 `.omk/managed/<id>.json`,镜像 report-store 的
+ * 成熟模式(原子 tmp+rename):每次 install 只碰自己那个文件,independent write、不丢别人、
+ * 天然可扩展。无数据库——这个规模(每项目几十条、CLI 单写者)JSON 文件足够,且保住"可读可
+ * grep 可 diff"的透明价值。
+ *
+ * **消费方无关的核心层**:本模块不依赖 CLI、不打印、不退出,所有函数接收显式 `dir`。CLI 命令只是
+ * 众多消费方之一;omk 长成平台后 server / web / SDK 复用同一模块,甚至换 DB 实现也只需镜像这组
+ * load/upsert 签名。记录的构造统一走 `buildManagedArtifactRecord`,新增字段只改这一处、所有消费方继承。
+ */
+export declare function managedDir(cwd?: string): string;
+export declare function globalManagedDir(): string;
+export declare function recordPath(dir: string, id: string): string;
+/** 稳定身份 = hash(kind, name)。源路径是可变属性、不进 id。kind 取自固定枚举(无 `|`),分隔可注入。 */
+export declare function managedRecordId(kind: ArtifactKind, name: string): string;
+export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from '../inputs/content-hash.js';
+export declare function loadManagedRecord(dir: string, id: string): ManagedArtifactRecord | null;
+/** 读全部记录。项目目录空 → 兜底全局(镜像 observe inbox 的 project→global)。 */
+export declare function loadAllManagedRecords(dir?: string): ManagedArtifactRecord[];
+/**
+ * 哪个 managed 目录是权威(有记录的那个):项目目录非空取项目,否则全局非空取全局,都空回项目。
+ * 与 `loadAllManagedRecords` 的 project→global 回退**同口径** —— 写方(append evidence)据此写回
+ * 读方实际取记录的同一目录,避免"读全局、写项目"把证据落到空目录。
+ */
+export declare function resolveManagedDir(dir?: string): string;
+/**
+ * 纯合并逻辑(无 IO):install 写的是事实,绝不动 evidence/decisions(那是 eval/promote 的地盘)。
+ *   - distribution 按 path 去重(同路径以新值替换);
+ *   - evidence / decisions 一律保留旧值(install 带来的恒为空)——这是设计要的"版本历史 + 附带证据",
+ *     用来支撑 rollback;**但保留 ≠ 当作当前有效**:每条 evidence 携带它测的 contentHash,读时由
+ *     `deriveManagedState` 只把与当前 contentHash 匹配的 evidence 算作当前证据,所以重装到新内容后
+ *     旧证据仍在记录里(可回滚),却不会让新内容被读成 measurable;
+ *   - installedAt 保留首次("under management since");contentHash / source 刷新到本次安装。
+ */
+export declare function mergeManagedRecord(prev: ManagedArtifactRecord | null, next: ManagedArtifactRecord): ManagedArtifactRecord;
+/** 读旧记录 → 合并 → 原子 tmp+rename 只写该 id 的文件。返回合并后记录。 */
+export declare function upsertManagedRecord(dir: string, record: ManagedArtifactRecord): ManagedArtifactRecord;
+/**
+ * 追加一条评测证据(append-only)。与 install 的 upsert 路径相反——`mergeManagedRecord` 刻意**保留旧
+ * evidence、丢弃 next.evidence**(install 只写事实),所以证据写入不能走 upsert,必须独立 load→push→
+ * 原子重写。按 `(reportId, contentHash)` 去重:重跑同一份 eval 不堆重复条目(reportId 含运行身份,
+ * 同内容重测会是新 reportId → 新条目,正是要的版本史)。记录不存在(未 install / 名字不匹配)返回
+ * null —— 这是"管理是 install 显式 opt-in"的体现:eval 绝不为未纳管的 skill 凭空建记录。
+ */
+export declare function appendManagedEvidence(dir: string, recordId: string, evidence: ManagedEvidenceRef): ManagedArtifactRecord | null;
+/**
+ * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
+ * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。
+ */
+export declare function buildManagedArtifactRecord(input: {
+    name: string;
+    kind: ArtifactKind;
+    source: ManagedArtifactSource;
+    contentHash: string;
+    installedAt: string;
+    distribution: ManagedDistributionTarget[];
+    id?: string;
+}): ManagedArtifactRecord;
+/** install 调用的便捷封装。 */
+export declare function recordManagedArtifact(record: ManagedArtifactRecord, opts?: {
+    dir?: string;
+}): ManagedArtifactRecord;
+/**
+ * 读时推导生命周期标签。
+ *   - 源缺失或 hash 漂(当前内容 ≠ 记录 contentHash)→ stale;
+ *   - 否则有**当前**证据 / samples → measurable;
+ *   - 否则 installed。
+ * 「当前证据」= contentHash 与记录当前 contentHash 匹配的 evidence —— 旧内容的 evidence 不算数,
+ * 这正是 #203「证据必须跟 artifact 一起走」的读时保证。`'discovered'` 留给无分发的记录,此函数不产生。
+ */
+export declare function deriveManagedState(input: DeriveManagedStateInput): DerivedManagedState;

package/dist/managed/store.js

@@ -0,0 +1,224 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, normalize } from 'node:path';
+import { hashString } from '../eval-core/evaluation-reporting.js';
+/**
+ * 受管记录的 per-record 文件存储。一条记录一个 `.omk/managed/<id>.json`,镜像 report-store 的
+ * 成熟模式(原子 tmp+rename):每次 install 只碰自己那个文件,independent write、不丢别人、
+ * 天然可扩展。无数据库——这个规模(每项目几十条、CLI 单写者)JSON 文件足够,且保住"可读可
+ * grep 可 diff"的透明价值。
+ *
+ * **消费方无关的核心层**:本模块不依赖 CLI、不打印、不退出,所有函数接收显式 `dir`。CLI 命令只是
+ * 众多消费方之一;omk 长成平台后 server / web / SDK 复用同一模块,甚至换 DB 实现也只需镜像这组
+ * load/upsert 签名。记录的构造统一走 `buildManagedArtifactRecord`,新增字段只改这一处、所有消费方继承。
+ */
+export function managedDir(cwd = process.cwd()) {
+    return join(cwd, '.omk', 'managed');
+}
+export function globalManagedDir() {
+    return join(homedir(), '.oh-my-knowledge', 'managed');
+}
+export function recordPath(dir, id) {
+    return join(dir, `${id}.json`);
+}
+/** 稳定身份 = hash(kind, name)。源路径是可变属性、不进 id。kind 取自固定枚举(无 `|`),分隔可注入。 */
+export function managedRecordId(kind, name) {
+    return hashString(`${kind}|${name}`);
+}
+// 内容指纹工具已下沉到 inputs 层(install 与 eval 共用同一处,保证指纹同空间);此处 re-export
+// 保持 managed 公共入口不破(install 仍从 managed 取 hashArtifactSource / isDistributablePath)。
+export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from '../inputs/content-hash.js';
+function isStringField(v) {
+    return typeof v === 'string';
+}
+// 校验到元素级:记录文件是用户可手改的(透明性是设计价值),`evidence:[null]` / 缺字段的 distribution
+// 都是现实的坏手改;若只查 Array.isArray,坏元素会在 deriveManagedState / mergeManagedRecord 里
+// 解引用崩溃(且在 load 的 try/catch 之外)。这里直接判脏 → load 丢弃该文件,消费方永远拿不到半成品。
+function isManagedArtifactRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const r = value;
+    if (!(r.recordKind === 'managed-artifact'
+        && r.schemaVersion === 2
+        && isStringField(r.id)
+        && isStringField(r.name)
+        && isStringField(r.kind)
+        && isStringField(r.contentHash)
+        && r.source && typeof r.source === 'object'
+        && isStringField(r.source.locator)
+        && isStringField(r.source.sourceKind)
+        && Array.isArray(r.distribution)
+        && Array.isArray(r.evidence)
+        && Array.isArray(r.decisions)))
+        return false;
+    const okDist = r.distribution.every((d) => d && typeof d === 'object'
+        && isStringField(d.path) && isStringField(d.contentHash));
+    const okEv = r.evidence.every((e) => e && typeof e === 'object'
+        && isStringField(e.reportId) && isStringField(e.contentHash));
+    const okDec = r.decisions.every((d) => d && typeof d === 'object'
+        && isStringField(d.decisionKind));
+    return okDist && okEv && okDec;
+}
+export function loadManagedRecord(dir, id) {
+    const path = recordPath(dir, id);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return isManagedArtifactRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readRecordsFromDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, entry), 'utf-8'));
+            if (isManagedArtifactRecord(parsed))
+                out.push(parsed);
+        }
+        catch {
+            // 跳过损坏文件
+        }
+    }
+    return out;
+}
+/** 读全部记录。项目目录空 → 兜底全局(镜像 observe inbox 的 project→global)。 */
+export function loadAllManagedRecords(dir = managedDir()) {
+    const local = readRecordsFromDir(dir);
+    if (local.length > 0)
+        return local;
+    const global = globalManagedDir();
+    if (dir !== global) {
+        const fallback = readRecordsFromDir(global);
+        if (fallback.length > 0)
+            return fallback;
+    }
+    return local;
+}
+/**
+ * 哪个 managed 目录是权威(有记录的那个):项目目录非空取项目,否则全局非空取全局,都空回项目。
+ * 与 `loadAllManagedRecords` 的 project→global 回退**同口径** —— 写方(append evidence)据此写回
+ * 读方实际取记录的同一目录,避免"读全局、写项目"把证据落到空目录。
+ */
+export function resolveManagedDir(dir = managedDir()) {
+    if (readRecordsFromDir(dir).length > 0)
+        return dir;
+    const global = globalManagedDir();
+    if (dir !== global && readRecordsFromDir(global).length > 0)
+        return global;
+    return dir;
+}
+/**
+ * 纯合并逻辑(无 IO):install 写的是事实,绝不动 evidence/decisions(那是 eval/promote 的地盘)。
+ *   - distribution 按 path 去重(同路径以新值替换);
+ *   - evidence / decisions 一律保留旧值(install 带来的恒为空)——这是设计要的"版本历史 + 附带证据",
+ *     用来支撑 rollback;**但保留 ≠ 当作当前有效**:每条 evidence 携带它测的 contentHash,读时由
+ *     `deriveManagedState` 只把与当前 contentHash 匹配的 evidence 算作当前证据,所以重装到新内容后
+ *     旧证据仍在记录里(可回滚),却不会让新内容被读成 measurable;
+ *   - installedAt 保留首次("under management since");contentHash / source 刷新到本次安装。
+ */
+export function mergeManagedRecord(prev, next) {
+    if (!prev)
+        return next;
+    // 按归一化路径去重(消除尾斜杠 / `.` / 重复分隔导致同一物理目标被记两条)。normalize 保留尾斜杠,故再去尾。
+    const normKey = (p) => normalize(p).replace(/[\\/]+$/, '') || p;
+    const byPath = new Map();
+    for (const t of prev.distribution)
+        byPath.set(normKey(t.path), t);
+    for (const t of next.distribution)
+        byPath.set(normKey(t.path), t);
+    // 维护点:`...next` 取本次安装的事实,下面四个字段从 prev 保留(历史 / 首次时间)。
+    // 将来若新增任何"必须从安装基线保留"的字段,务必加进这份覆盖清单,否则会被 next 静默覆盖成 undefined。
+    // 注意语义边界:distribution 是**多源容忍**的(按归一化 path 累积去重),而 source / contentHash 是
+    // **末次写入(单源)**。同一 (kind,name) 先 file 后 git 重装会得到一条 source=git 的记录,但 distribution
+    // 仍含 file 时代的落点 —— 那些落点会按 git 的 contentHash 被判 drift。这是"换源即重基线"的有意取舍。
+    return {
+        ...next,
+        installedAt: prev.installedAt,
+        distribution: [...byPath.values()],
+        evidence: prev.evidence,
+        decisions: prev.decisions,
+    };
+}
+/** 读旧记录 → 合并 → 原子 tmp+rename 只写该 id 的文件。返回合并后记录。 */
+export function upsertManagedRecord(dir, record) {
+    const merged = mergeManagedRecord(loadManagedRecord(dir, record.id), record);
+    mkdirSync(dir, { recursive: true });
+    const path = recordPath(dir, record.id);
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(merged, null, 2));
+    renameSync(tmp, path);
+    return merged;
+}
+/**
+ * 追加一条评测证据(append-only)。与 install 的 upsert 路径相反——`mergeManagedRecord` 刻意**保留旧
+ * evidence、丢弃 next.evidence**(install 只写事实),所以证据写入不能走 upsert,必须独立 load→push→
+ * 原子重写。按 `(reportId, contentHash)` 去重:重跑同一份 eval 不堆重复条目(reportId 含运行身份,
+ * 同内容重测会是新 reportId → 新条目,正是要的版本史)。记录不存在(未 install / 名字不匹配)返回
+ * null —— 这是"管理是 install 显式 opt-in"的体现:eval 绝不为未纳管的 skill 凭空建记录。
+ */
+export function appendManagedEvidence(dir, recordId, evidence) {
+    const prev = loadManagedRecord(dir, recordId);
+    if (!prev)
+        return null;
+    const dup = prev.evidence.some((e) => e.reportId === evidence.reportId && e.contentHash === evidence.contentHash);
+    const merged = dup
+        ? prev
+        : { ...prev, evidence: [...prev.evidence, evidence] };
+    if (!dup) {
+        mkdirSync(dir, { recursive: true });
+        const path = recordPath(dir, recordId);
+        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(merged, null, 2));
+        renameSync(tmp, path);
+    }
+    return merged;
+}
+/**
+ * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
+ * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。
+ */
+export function buildManagedArtifactRecord(input) {
+    return {
+        recordKind: 'managed-artifact',
+        schemaVersion: 2,
+        id: input.id ?? managedRecordId(input.kind, input.name),
+        name: input.name,
+        kind: input.kind,
+        source: input.source,
+        contentHash: input.contentHash,
+        installedAt: input.installedAt,
+        distribution: input.distribution,
+        evidence: [],
+        decisions: [],
+    };
+}
+/** install 调用的便捷封装。 */
+export function recordManagedArtifact(record, opts = {}) {
+    return upsertManagedRecord(opts.dir ?? managedDir(), record);
+}
+/**
+ * 读时推导生命周期标签。
+ *   - 源缺失或 hash 漂(当前内容 ≠ 记录 contentHash)→ stale;
+ *   - 否则有**当前**证据 / samples → measurable;
+ *   - 否则 installed。
+ * 「当前证据」= contentHash 与记录当前 contentHash 匹配的 evidence —— 旧内容的 evidence 不算数,
+ * 这正是 #203「证据必须跟 artifact 一起走」的读时保证。`'discovered'` 留给无分发的记录,此函数不产生。
+ */
+export function deriveManagedState(input) {
+    const { record, currentContentHash, hasSamplesOrDoctorPass } = input;
+    const hasEvidence = record.evidence.some((e) => e.contentHash === record.contentHash);
+    const drifted = currentContentHash === undefined || currentContentHash !== record.contentHash;
+    if (drifted)
+        return { label: 'stale', drifted: true, hasEvidence };
+    if (hasEvidence || hasSamplesOrDoctorPass)
+        return { label: 'measurable', drifted: false, hasEvidence };
+    return { label: 'installed', drifted: false, hasEvidence };
+}

package/dist/observability/experience-frontmatter.d.ts

@@ -34,4 +34,3 @@ export interface SkillDeclarationCheck {
 export declare function loadFrontmatterSkillType(skillName: string, cwd?: string): ExperienceRuntimeSkillType | undefined;
 export declare function loadSkillDeclarationCheck(skillName: string, cwd?: string): SkillDeclarationCheck;
 export declare function loadExpectedToolsForSkill(skillName: string, cwd?: string): string[];
-//# sourceMappingURL=experience-frontmatter.d.ts.map

package/dist/observability/experience-frontmatter.js

@@ -97,4 +97,3 @@ function normalizeRuntimeSkillType(value) {
 function unique(values) {
     return Array.from(new Set(values));
 }
-//# sourceMappingURL=experience-frontmatter.js.map