oh-my-knowledge 0.34.0 → 0.36.0

package/README.md

@@ -100,6 +100,8 @@ RAG-specific evals: see RAGAS (separate niche, complementary to omk). Full compa
 | **Production observability** | parse Claude Code session JSONL traces; measure per-skill failure rate / latency / cost / knowledge-gap signals |
 | **Knowledge-gap detection** | severity-weighted signals quantify risk exposure instead of claiming completeness |
 | **Construct-validity isolation** | `--strict-baseline` (default ON) cuts three contamination channels so baseline doesn't silently see the skill it's being compared against |
+| **Git & remote sources** | install / eval from a local git ref or a remote git URL (`--git-url`); directory-skills run in a content-addressed **isolated copy** so `references/` assets are real measured input, not just `SKILL.md` |
+| **Evidence-gated management** | `omk install` registers a managed record; `omk eval` auto-writes evidence bound by content fingerprint, moving a skill `installed → measurable`; `omk list` surfaces each managed skill's status (installed / measurable / stale). [spec →](docs/specs/evidence-gated-management.md) |
 | **Sample design science** | sample schema with `capability` / `difficulty` / `construct` / `provenance` metadata (HF Dataset Cards style); studio surfaces coverage breakdown plus `rubric_clarity_low` / `capability_thin` flags. [docs/specs/sample-design-spec.md](docs/specs/sample-design-spec.md) |
 | **Multi-judge ensemble** | `--judge-models claude:opus,openai:gpt-4o` cross-vendor scoring + agreement metrics |
 | **Blind A/B** | `--blind` hides variant names; HTML report has a reveal button |
@@ -122,6 +124,7 @@ The full docs are published at **[oh-my-knowledge.pages.dev](https://oh-my-knowl
 - **[Sample design spec](docs/specs/sample-design-spec.md)** — capability / construct / provenance metadata; industry-gap mapping
 - **[Statistical rigor](docs/explanation/statistical-rigor.md)** — why bootstrap CI / α / length-debias / saturation matter
 - **[Comparison with 7 tools](docs/reference/comparison.md)** — 25+ dimensions across promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai
+- **[Evidence-gated management](docs/specs/evidence-gated-management.md)** — managed records, lifecycle states (installed / measurable / stale), install → eval → measurable
 
 ## Environment variables
 

package/README.zh.md

@@ -100,6 +100,8 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 | **线上 session 观测** | 解析 Claude Code session JSONL，测量各 skill 的失败率、耗时、token 成本、知识缺口信号 |
 | **知识缺口识别** | 严重度加权的信号量化风险敞口，不宣称完备性 |
 | **用例隔离 (construct validity)** | `--strict-baseline`（默认开）三堵 baseline 拿到被测 skill 的污染路径 |
+| **Git / 远端源** | install / eval 支持本地 git ref 或远端 git URL（`--git-url`）；目录-skill 在内容寻址**隔离副本**里执行，`references/` 资产是真实测量输入，不只是 `SKILL.md` |
+| **证据门控管理** | `omk install` 登记受管记录；`omk eval` 按内容指纹自动写入证据，把 skill 从 `installed` 推到 `measurable`；`omk list` 查看各受管 skill 的状态（installed / measurable / stale）。[规范 →](docs/zh/specs/evidence-gated-management.md) |
 | **用例设计科学性** | Sample schema 加 `capability` / `difficulty` / `construct` / `provenance` 元数据字段（HF Dataset Cards 风），studio 输出 coverage 分桶 + `rubric_clarity_low` / `capability_thin` issue。[docs/zh/specs/sample-design-spec.md](docs/zh/specs/sample-design-spec.md) |
 | **多评委 ensemble** | `--judge-models claude:opus,openai:gpt-4o` 跨厂商评分 + agreement 度量 |
 | **盲测 A/B** | `--blind` 隐藏变体名称，HTML 报告有揭晓按钮 |
@@ -122,6 +124,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 - **[用例设计规范](docs/zh/specs/sample-design-spec.md)** —— capability / construct / provenance 元数据；行业 gap 映射
 - **[统计严谨性](docs/zh/explanation/statistical-rigor.md)** —— 为什么 Bootstrap CI / α / 长度去偏 / 饱和曲线重要
 - **[7 工具对比](docs/zh/reference/comparison.md)** —— promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai 等 25+ 维度横评
+- **[证据门控管理](docs/zh/specs/evidence-gated-management.md)** —— 受管记录、生命周期状态（installed / measurable / stale）、install → eval → measurable
 
 ## 环境变量
 

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

@@ -4,7 +4,7 @@ description: |
   oh-my-knowledge 知识载体评测工具的智能代理。评测 skill（系统提示词）质量，对比不同版本效果，自动迭代改进。
   Use when: 用户提到"评测"、"测评"、"eval"、"benchmark"、"对比 skill"、"改进 skill"、"evolve"、"生成测试用例"、"gen-samples"、"omk"。
 user-invocable: true
-argument-hint: "<doctor|eval|evolve|init|install|observe|sample|studio> [options]"
+argument-hint: "<doctor|eval|evolve|init|install|list|observe|sample|studio> [options]"
 ---
 
 # OMK — 知识载体评测
@@ -19,7 +19,7 @@ argument-hint: "<doctor|eval|evolve|init|install|observe|sample|studio> [options
 npm i oh-my-knowledge -g
 ```
 
-omk CLI 顶层命令包括：`init` / `install` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
+omk CLI 顶层命令包括：`init` / `install` / `list` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
 
 ## 第二步：理解用户意图
 

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

@@ -89,6 +89,7 @@ omk eval [flags]
 - `--no-cache` `boolean`:跳过 executor cache
 - `--no-debias-length` `boolean`:关 length-debias（默认开）
 - `--no-diagnostic` `boolean`:关闭 diagnostic 诊断 LLM 调用（默认开，给 failed sample 出「哪错了 + 怎么改」建议）。
+- `--no-evidence` `boolean`:不把本次评测写成证据追加进受管记录(默认会为已 install 的 skill 自动写)。
 - `--no-gate` `boolean`:关 verdict gate
 - `--no-judge` `boolean`:跳过 LLM judge
 - `--no-serve` `boolean`:不启 report server
@@ -303,6 +304,8 @@ omk install <input> [flags]
 - `--dest` `option`:自定义 skill 根目录；skill 安装到 <dir>/<name>（内置 omk-agent-skill 为 <dir>/omk）。
 - `--dry-run` `boolean`:只打印安装目标，不写文件。
 - `--force` `boolean`:覆盖目标位置已存在的 skill。
+- `--git-ref` `option`:远端 git 的 ref（分支 / tag / SHA），默认 HEAD。仅配合 --git-url 使用。
+- `--git-url` `option`:远端 git 仓库 URL（https / ssh / git@host:path）。给了它时，位置参数当作仓库内 skill 路径（spec）。
 - `--kind` `skill|prompt|agent|workflow`:用户 artifact 的 kind（对齐 Artifact.kind）。可省：命中 SKILL.md 自动推导，当前仅支持 skill。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--to` `option` (默认 `auto`):安装目标：auto（默认，本机已检测目标） / codex / claude / all。
@@ -339,6 +342,48 @@ omk install ./skills/review
 omk install git:main:skills/review
 ```
 
+> 从远端 git 仓库安装 skill（位置参数是仓库内路径；认证用本机 git 凭证；记录钉实际 SHA）
+
+```bash
+omk install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/review
+```
+
+## omk list
+
+列出受管 skill 及其证据状态：生命周期（installed / measurable / stale）、最新 verdict、证据数、源。
+
+**用法:**
+
+```bash
+omk list [flags]
+```
+
+**Flags:**
+
+- `--global` `boolean`:看全局受管目录（~/.oh-my-knowledge/managed）而非项目 .omk/managed
+- `--json` `boolean`:输出 JSON（含完整可比性 marker），供脚本消费
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+
+**示例:**
+
+> 列出当前项目的受管 skill
+
+```bash
+omk list
+```
+
+> 列出全局受管 skill
+
+```bash
+omk list --global
+```
+
+> 机器可读 JSON 输出
+
+```bash
+omk list --json
+```
+
 ## omk observe
 
 分析 sessions 目录的 skill 调用健康度（默认行为）。子命令:ingest / inbox / show。

package/dist/authoring/evolver.js

@@ -6,6 +6,7 @@ import { persistReport, DEFAULT_OUTPUT_DIR, generateRunId, hashString } from '..
 import { createFileStore } from '../server/report-store.js';
 import { analyzeResults } from '../analysis/report-diagnostics.js';
 import { loadSamples } from '../inputs/load-samples.js';
+import { hashArtifactSource } from '../inputs/content-hash.js';
 import { buildVariantSummary } from '../eval-core/schema.js';
 import { bootstrapDiffCI, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES } from '../eval-core/bootstrap.js';
 import { fixSamples } from './sample-fixer.js';
@@ -88,9 +89,13 @@ function singleVariantReport(report, variantKey) {
 async function findReusableBaselineReport(opts) {
     const store = createFileStore(DEFAULT_OUTPUT_DIR);
     const { samples } = loadSamples(opts.samplesPath);
-    const artifactHash = hashString(opts.skillContent);
+    const artifactHash = opts.artifactHash;
     const reports = await store.findByArtifactHash(artifactHash);
     for (const report of reports) {
+        // schemaVersion < 2 的报告 artifactHashes 是旧文本哈,与当前树哈不同空间:即便值偶合也不该复用
+        // (口径不同会让 lineage 串错身份)。直接跳过,让旧 baseline 重跑出树哈报告。
+        if ((report.meta.schemaVersion ?? 0) < 2)
+            continue;
         if (report.meta.model !== opts.model || report.meta.executor !== opts.executorName)
             continue;
         if ((report.meta.effort ?? undefined) !== (opts.effort ?? undefined))
@@ -541,7 +546,7 @@ export function mergeEvolveReports(roundReports, skillName, totalCostUSD, sample
     }
     const runId = `evolve-${skillName}-${generateRunId([skillName]).split('-').slice(-2).join('-')}`;
     const report = {
-        reportKind: 'evaluation',
+        kind: 'evaluation',
         id: runId,
         meta: {
             ...firstReport.meta,
@@ -669,10 +674,14 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
     let stopReason = 'rounds';
     // 给定一个 report 看任一 variant 的 exec/judge cost 是否未报告
     const reportHasUnreportedCost = (rep) => Object.values(rep.summary).some((v) => v.execCostReported === false || v.judgeCostReported === false);
-    // Round 0: baseline evaluation
+    // Round 0: baseline evaluation。复用查询键走整树哈,与 eval 报告口径一致:round 0 的 currentBest 即
+    // 磁盘上原始 skill,树哈取自磁盘(dir-skill 哈整目录、单文件 .md 哈单文件)。evolve 只改 SKILL.md 正文、
+    // 不动 references/ 资产,故磁盘树哈即该 baseline 的权威指纹。
+    const baselineIsDirSkill = basename(absSkillPath) === 'SKILL.md';
+    const baselineArtifactHash = hashArtifactSource(baselineIsDirSkill ? skillDir : absSkillPath, baselineIsDirSkill);
     let baselineReport = reuseLatestEval
         ? await findReusableBaselineReport({
-            skillContent: currentBest,
+            artifactHash: baselineArtifactHash,
             samplesPath: absSamplesPath,
             model,
             executorName,

package/dist/cli/commands/doctor.js

@@ -300,7 +300,8 @@ export function pruneDoctorHistory(dir, skillName, maxKeep) {
             continue;
         try {
             const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            if (data?.reportKind !== 'doctor' || !Array.isArray(data.skills) || data.skills.length !== 1)
+            const kind = data?.kind === 'doctor' ? data.kind : null;
+            if (!kind || !Array.isArray(data.skills) || data.skills.length !== 1)
                 continue;
             if (data.skills[0].skillName !== skillName)
                 continue;

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

@@ -50,6 +50,7 @@ export default class Eval extends BaseCommand {
         'trivial-diff': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'report-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-gate': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'no-evidence': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

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

@@ -8,6 +8,7 @@ import { parseRunConfig } from '../../lib/parse-run-config.js';
 import { makeOnProgress } from '../../lib/progress.js';
 import { computeRunTally } from '../../lib/run-tally.js';
 import { DEFAULT_BOOTSTRAP_SAMPLES } from '../../../eval-core/bootstrap.js';
+import { EVALUATION_REPORT_SCHEMA_VERSION } from '../../../eval-core/evaluation-reporting.js';
 function isDryRunReport(report) {
     return Boolean(report && typeof report === 'object' && report.dryRun === true);
 }
@@ -37,21 +38,44 @@ function applyGateExitCode(code, values, lang) {
     process.stderr.write(tCli('cli.run.report_only_gate_skipped', lang));
     return 0;
 }
-async function emitEvaluationVerdict(report, values) {
+async function emitEvaluationVerdict(report, values, lang) {
     const { computeVerdict, formatVerdictText } = await import('../../../eval-core/verdict.js');
     const result = computeVerdict(report, verdictOptions(values));
     console.log(formatVerdictText(result, { verbose: true }));
+    await recordEvidenceSafely(report, result.level, values, lang);
     return verdictPasses(result.level, result.headline) ? 0 : 1;
 }
+/**
+ * 把本次评测写成证据追加进**已纳管**记录(让 install 过的 skill 走到 measurable)。
+ * 永不致命:管理是 eval 的旁路,写入失败 / 无匹配记录都不影响 verdict 与 exit code。
+ * `--no-evidence` 关闭。仅对实际写入的记录打一行提示(无匹配则全静默)。
+ */
+async function recordEvidenceSafely(report, verdict, values, lang) {
+    if (values['no-evidence'] === true)
+        return;
+    try {
+        const { recordEvalEvidence } = await import('../../../managed/index.js');
+        const written = recordEvalEvidence(report, verdict, new Date().toISOString());
+        for (const w of written) {
+            process.stderr.write(tCli(w.bound ? 'cli.run.evidence_recorded' : 'cli.run.evidence_recorded_unbound', lang, { name: w.name }));
+        }
+    }
+    catch {
+        // 证据写入是旁路,任何异常都不该让评测失败
+    }
+}
 function batchItemFallbackReport(batch, item) {
     return {
-        reportKind: 'evaluation',
+        kind: 'evaluation',
         id: item.reportId,
         meta: {
             ...batch.meta,
             variants: ['baseline', item.name],
             sampleCount: item.sampleCount,
             totalCostUSD: item.totalCostUSD,
+            // item.artifactHash 来自子报告(走 aggregateReport 的整树哈),故 fallback 与之一致标当前 eval
+            // report schemaVersion,避免「树哈 artifactHashes + 错位 schemaVersion」的错配。
+            schemaVersion: EVALUATION_REPORT_SCHEMA_VERSION,
             artifactHashes: item.artifactHash ? { [item.name]: item.artifactHash } : {},
         },
         summary: item.summary,
@@ -65,7 +89,7 @@ async function loadBatchChildReports(batch, reportsDir, lang) {
     const reports = [];
     for (const item of batch.items) {
         const loaded = await store.get(item.reportId);
-        if (loaded?.reportKind === 'evaluation') {
+        if (loaded?.kind === 'evaluation') {
             reports.push(loaded);
         }
         else {
@@ -83,6 +107,11 @@ async function emitBatchVerdict(report, reportsDir, values, lang) {
         treatment: child.meta.variants[1] ?? child.id,
         verdict: computeVerdict(child, verdictOptions(values)),
     }));
+    // batch 每个子报告各自是一份独立 skill 的评测 → 各自写证据。
+    for (const child of childReports) {
+        const v = results.find((r) => r.id === child.id)?.verdict.level ?? 'SOLO';
+        await recordEvidenceSafely(child, v, values, lang);
+    }
     const passed = results.filter((r) => verdictPasses(r.verdict.level, r.verdict.headline)).length;
     const failed = results.length - passed;
     const status = lang === 'zh'
@@ -100,7 +129,7 @@ async function emitBatchVerdict(report, reportsDir, values, lang) {
 }
 async function announceSavedReport({ report, filePath, reportsDir, values, lang, }) {
     const tally = computeRunTally(report);
-    process.stderr.write(tCli(report.reportKind === 'batch-evaluation' ? 'cli.run.batch_complete' : 'cli.run.eval_complete', lang));
+    process.stderr.write(tCli(report.kind === 'batch-evaluation' ? 'cli.run.batch_complete' : 'cli.run.eval_complete', lang));
     process.stderr.write(tCli('cli.run.tally', lang, tally));
     process.stderr.write(tCli('cli.run.report_saved', lang, { path: filePath }));
     if (!values['no-serve'] && process.stdout.isTTY) {
@@ -255,7 +284,7 @@ async function runEval(_args, flags, lang) {
         if (filePath) {
             await announceSavedReport({ report, filePath, reportsDir: config.outputDir, values, lang });
         }
-        const exitCode = await emitEvaluationVerdict(report, values);
+        const exitCode = await emitEvaluationVerdict(report, values, lang);
         throw new CliExit(applyGateExitCode(exitCode, values, lang));
     }
     catch (err) {
@@ -466,6 +495,12 @@ export default class Eval extends BaseCommand {
         'no-gate': Flags.boolean({
             description: bilingual({ zh: '关 verdict gate', en: 'Disable verdict gate' }),
         }),
+        'no-evidence': Flags.boolean({
+            description: bilingual({
+                zh: '不把本次评测写成证据追加进受管记录(默认会为已 install 的 skill 自动写)。',
+                en: 'Do not append this run as evidence to managed records (auto-written for installed skills by default).',
+            }),
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Eval);

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

@@ -15,6 +15,8 @@ export default class Install extends BaseCommand {
         dest: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'git-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'git-ref': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     private installBuiltinAgentSkill;

package/dist/cli/commands/install.js

@@ -1,13 +1,13 @@
-import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { copyFileSync, cpSync, existsSync, mkdirSync, realpathSync, rmSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, relative, resolve, join, sep } from 'node:path';
+import { basename, dirname, resolve, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Args, Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../oclif/i18n.js';
 import { BaseCommand } from '../oclif/base-command.js';
 import { tCli } from '../lib/i18n.js';
-import { resolveInstallSource, SourceResolveError } from '../../inputs/source-resolver.js';
-import { buildManagedArtifactRecord, hashArtifactSource, isDistributablePath, managedDir, recordManagedArtifact } from '../../managed/index.js';
+import { resolveInstallSource, resolveRemoteGitSource, SourceResolveError } from '../../inputs/source-resolver.js';
+import { buildManagedArtifactRecord, hashArtifactSource, distributableCopyFilter, managedDir, recordManagedArtifact } from '../../managed/index.js';
 const BUILTIN_OMK_AGENT_SKILL_ID = 'omk-agent-skill';
 const INSTALLABLE_KINDS = ['skill', 'prompt', 'agent', 'workflow'];
 const TARGET_ORDER = ['codex', 'claude'];
@@ -163,17 +163,10 @@ function copyArtifactToTarget(params) {
     if (params.isDirectorySkill) {
         cpSync(params.source, params.targetPath, {
             recursive: true,
-            // 与 hashArtifactSource 共用过滤,保证"分发出去的 == 算进 hash 的":
-            // 源根永远拷;软链跳过(与 hash walk 一致,避免软链目标改了却不触发 drift);
-            // evolve 只在源根第一层排除(嵌套 references/evolve 正常分发),.omk/.git 任意层级排除。
-            filter: (src) => {
-                const rel = relative(params.source, src);
-                if (rel === '')
-                    return true;
-                if (lstatSync(src).isSymbolicLink())
-                    return false;
-                return isDistributablePath(rel.split(sep));
-            },
+            // 与 hashArtifactSource / eval 隔离副本共用同一处过滤(distributableCopyFilter),保证
+            // "分发出去的 == 算进 hash 的 == 测量的副本":源根永远拷;软链跳过;evolve 仅源根第一层排除、
+            // .omk/.git/node_modules 任意层级排除。
+            filter: distributableCopyFilter(params.source),
         });
     }
     else {
@@ -253,6 +246,13 @@ export default class Install extends BaseCommand {
             }),
             command: '<%= config.bin %> install git:main:skills/review',
         },
+        {
+            description: bilingual({
+                zh: '从远端 git 仓库安装 skill（位置参数是仓库内路径；认证用本机 git 凭证；记录钉实际 SHA）',
+                en: 'Install a skill from a remote git repo (positional arg is the in-repo path; auth via local git credentials; record pins the actual SHA)',
+            }),
+            command: '<%= config.bin %> install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/review',
+        },
     ];
     static args = {
         input: Args.string({
@@ -299,11 +299,35 @@ export default class Install extends BaseCommand {
             }),
             default: false,
         }),
+        'git-url': Flags.string({
+            description: bilingual({
+                zh: '远端 git 仓库 URL（https / ssh / git@host:path）。给了它时，位置参数当作仓库内 skill 路径（spec）。',
+                en: 'Remote git repository URL (https / ssh / git@host:path). When set, the positional arg is the in-repo skill path (spec).',
+            }),
+        }),
+        'git-ref': Flags.string({
+            description: bilingual({
+                zh: '远端 git 的 ref（分支 / tag / SHA），默认 HEAD。仅配合 --git-url 使用。',
+                en: 'Remote git ref (branch / tag / SHA), default HEAD. Only with --git-url.',
+            }),
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Install);
         const lang = this.lang;
         await this.runWithCliExit(async () => {
+            // --git-ref 必须配 --git-url(否则静默丢弃、误把 spec 当本地路径解析,报错令人困惑)。
+            if (flags['git-ref'] && !flags['git-url']) {
+                throw new Error(tCli('cli.install.git_ref_needs_url', lang));
+            }
+            // 远端 git:--git-url 在场时,位置参数是仓库内 spec(repo 相对路径),先于其它分支判定。
+            if (flags['git-url']) {
+                this.installManagedSkill(args.input, flags.kind, flags, lang, {
+                    url: flags['git-url'],
+                    ref: flags['git-ref'] || 'HEAD',
+                });
+                return;
+            }
             if (args.input === BUILTIN_OMK_AGENT_SKILL_ID) {
                 this.installBuiltinAgentSkill(flags, lang);
                 return;
@@ -330,17 +354,18 @@ export default class Install extends BaseCommand {
         if (!flags['dry-run'])
             console.log(tCli('cli.install.next_hint', lang));
     }
-    installManagedSkill(input, kindFlag, flags, lang) {
+    installManagedSkill(input, kindFlag, flags, lang, remote) {
         // kind 推导:--kind 显式优先;否则缺省 skill(Phase 1 仅 skill)。
         const kind = kindFlag ?? 'skill';
         if (kind !== 'skill') {
             throw new Error(tCli('cli.install.kind_unsupported', lang, { kind }));
         }
-        // 源解析委托给 source-resolver(file / git ...),install 主干源无关。
+        // 源解析委托给 source-resolver(file / 本地 git / 远端 git),install 主干源无关。
+        // 远端走结构化 resolveRemoteGitSource(url/ref/spec 分字段,URL 不经任何字符串切分);
         // resolver 不依赖 CLI,错误以 SourceResolveError(messageKey) 抛出,这里映射成本地化文案。
         let src;
         try {
-            src = resolveInstallSource(input);
+            src = remote ? resolveRemoteGitSource(remote.url, remote.ref, input) : resolveInstallSource(input);
         }
         catch (err) {
             if (err instanceof SourceResolveError) {
@@ -349,7 +374,7 @@ export default class Install extends BaseCommand {
             throw err;
         }
         try {
-            const { localRoot, name, isDirectorySkill, sourceKind, locator, ref } = src;
+            const { localRoot, name, isDirectorySkill, sourceKind, locator, ref, url } = src;
             // 目录-skill 哈整棵可分发树(排除 .omk/.git/evolve);git 源哈的是物化后的临时树。
             const contentHash = hashArtifactSource(localRoot, isDirectorySkill);
             const targets = resolveInstallTargets({ to: flags.to, dest: flags.dest, lang });
@@ -371,7 +396,7 @@ export default class Install extends BaseCommand {
                 const record = buildManagedArtifactRecord({
                     name,
                     kind,
-                    source: { sourceKind, locator, ...(ref ? { ref } : {}), isDirectorySkill },
+                    source: { sourceKind, locator, ...(ref ? { ref } : {}), ...(url ? { url } : {}), isDirectorySkill },
                     contentHash,
                     installedAt: now,
                     distribution,

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

@@ -0,0 +1,46 @@
+import { BaseCommand } from '../oclif/base-command.js';
+import { type ManagedListRow, type SourceProbe } from '../../managed/index.js';
+import type { ManagedArtifactRecord } from '../../types/index.js';
+import type { CliLang } from '../lib/i18n.js';
+/**
+ * 探测一条受管记录**当前源**的状态(三态,喂 buildManagedListRow 判 drift / 生命周期)。
+ *   - 远端 git(带 url):源身份钉不可变 SHA(install 时 pin),内容恒定 → 直接取 record.contentHash,
+ *     不联网(list 是快读命令,不为 drift 检查发网络请求)。reachable。
+ *   - 本地 git:locator `git:<ref>:<spec>` 复用 resolveInstallSource 在**仓库对象库**内重物化重哈
+ *     (读取受 git 边界约束,无任意文件读 DoS)。解析不到(常因 `omk list` 的 cwd 与 install 时不同、
+ *     spec 随 cwd 漂)→ 抛错 → **reachable:false(未核,不当 stale)**,避免对未改动的 skill 误报漂移。
+ *   - 本地 file:locator 是绝对路径,但受管 JSON **用户可手改 / 随仓库分发**(无 install、无 opt-in 即被
+ *     loadAllManagedRecords 读到)。只读命令绝不盲读任意路径:**拒软链、只读常规文件 / 真目录、单文件
+ *     设 size cap**(挡 `evil.md → /dev/zero` 这类 readFileSync 无界 DoS 与项目外任意读)。守卫不过 →
+ *     reachable:false。目录-skill 整树哈本就跳软链(hashArtifactSource 用 isFile() 过滤)。
+ */
+export declare function probeSourceState(record: ManagedArtifactRecord): SourceProbe;
+/** CJK 全角字符按 2 列计宽,使含中文表头的列也能对齐。 */
+export declare function dispWidth(s: string): number;
+/** 按**显示宽度**截断(不是 code unit):逐码点累加 dispWidth,绝不切断 surrogate 对、CJK 也不溢出列。 */
+export declare function truncate(s: string, max: number): string;
+/** 洗不可信显示字符:managed JSON 可随仓库分发,name / sourceLabel / verdict 等字段塞进表格前必须先洗,
+ *  否则会破坏表格甚至伪造终端输出。一律映射到可见 U+FFFD(--json 路径保留原值给脚本)。
+ *  用 Unicode **属性类**而非手列码点 —— 手列清单天然有缺口(BiDi、U+2028 / 2029、Tags 块都曾漏一轮补一轮),
+ *  属性类一次覆盖整类、新码点自动纳入:
+ *    - `\p{Cc}` 控制符(C0 / C1 / DEL,含 ESC / 换行 / 回车 / TAB)→ 杀 ANSI / OSC 转义与终端控制;
+ *    - `\p{Cf}` 格式符(BiDi 重排 / 隔离、零宽、joiners、BOM、Tags、interlinear)→ 防 Trojan-Source 视觉伪造与零宽隐藏 / 分割;
+ *    - `\p{Zl}` / `\p{Zp}` 行 / 段分隔(U+2028 / 2029)→ LF 的 Unicode 孪生,防换行伪造表格行;
+ *    - `\p{Mn}` / `\p{Me}` 非间距 / 封闭组合附加符 → 变可见,避免零前进宽度令 dispWidth 与终端列错位
+ *      (间距组合符 `\p{Mc}` 合法占 1 列,保留);
+ *    - Hangul filler(U+115F / U+1160 / U+3164,属 Lo 不在上述任何类)→ 零宽显示诡计,补列。 */
+export declare function sanitizeCell(s: string): string;
+export declare function renderTable(rows: ManagedListRow[], lang: CliLang): string;
+export default class List extends BaseCommand {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        lang: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}