oh-my-knowledge 0.36.0 → 0.37.0

package/dist/doctor/endpoint-rule.js

@@ -0,0 +1,381 @@
+/**
+ * endpoint-rule — 接口驱动的自定义检查维度。
+ *
+ * 普通自定义维度走 LLM health composer(promptSection 喂 prompt);带 `endpoint`
+ * 的维度则注册成独立 DoctorRule:doctor 运行时把 skill 完整快照 POST 给用户的
+ * 接口,接口按协议返回判定结果。适合"调外部服务做深度审查"(eg. 安全风险审查)
+ * 这类靠 prompt 表达不了、需要真实逻辑/模型的场景。
+ *
+ * 请求协议(doctor → endpoint):
+ *   POST <endpoint>  Content-Type: application/json
+ *   {
+ *     "dimensionId": "deep-security-audit",
+ *     "params": { ... },                  // YAML 里用户透传的自定义参数
+ *     "skill": {
+ *       "name": "my-skill",
+ *       "content": "SKILL.md 全文",        // file-skill / directory-skill 主文件
+ *       "skillRoot": "/abs/path" | null,   // git / inline 来源可能为 null
+ *       "ref": "abc1234" | null,           // git 来源的 commit
+ *       "files": { "references/x.md": "...", "scripts/y.sh": "..." }  // 子文件快照
+ *     }
+ *   }
+ *
+ * 响应协议(endpoint → doctor):
+ *   { "status": "pass" | "warn" | "fail", "message": "...", "hint"?: "...", "detail"?: {...} }
+ */
+import { existsSync, readFileSync, readdirSync, lstatSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+const DEFAULT_MAX_FILE_BYTES = 200 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+/** 二进制 / 大文件不可读时跳过;只收文本。简单按扩展名 + 内容嗅探。 */
+const SKIP_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.pdf',
+    '.zip', '.gz', '.tar', '.tgz', '.exe', '.bin', '.so', '.dylib',
+    '.woff', '.woff2', '.ttf', '.mp4', '.mov', '.mp3', '.wav',
+]);
+function extOf(name) {
+    const i = name.lastIndexOf('.');
+    return i >= 0 ? name.slice(i).toLowerCase() : '';
+}
+/** 收集 skillRoot 下的子文件内容(排除主 SKILL.md / 隐藏文件 / node_modules)。
+ *  受 maxFileBytes / maxTotalBytes 双重限制,避免 payload 过大。 */
+function collectFiles(skillRoot, maxFileBytes, maxTotalBytes) {
+    const files = {};
+    if (!skillRoot || !existsSync(skillRoot))
+        return files;
+    let total = 0;
+    const walk = (dir, rel, depth) => {
+        if (depth > 3 || total >= maxTotalBytes)
+            return;
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (total >= maxTotalBytes)
+                return;
+            if (entry.startsWith('.'))
+                continue;
+            if (entry === 'node_modules')
+                continue;
+            if (entry === 'SKILL.md' && rel === '')
+                continue;
+            const full = join(dir, entry);
+            const relPath = rel ? `${rel}/${entry}` : entry;
+            let st;
+            // lstat(不跟随 symlink):跳过符号链接,防止 skillRoot 下的 link 指向 root 外
+            // (如 /etc/passwd)被读取并随 payload 外发。
+            try {
+                st = lstatSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink())
+                continue;
+            if (st.isDirectory()) {
+                walk(full, relPath, depth + 1);
+            }
+            else if (st.isFile()) {
+                if (SKIP_EXTENSIONS.has(extOf(entry)))
+                    continue;
+                let buf;
+                if (st.size > maxFileBytes) {
+                    // 大文件守卫:不整文件读入(超大文件会撑内存,超 Buffer 上限的 throw
+                    // 还会被 catch 静默跳过),只读前 maxFileBytes + 1 字节,NUL 嗅探与
+                    // 截断都在这个前缀上做。
+                    let fd;
+                    try {
+                        fd = openSync(full, 'r');
+                    }
+                    catch {
+                        continue;
+                    }
+                    try {
+                        const head = Buffer.allocUnsafe(maxFileBytes + 1);
+                        const n = readSync(fd, head, 0, head.length, 0);
+                        buf = head.subarray(0, n);
+                    }
+                    catch {
+                        continue;
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                }
+                else {
+                    try {
+                        buf = readFileSync(full);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                // 内容嗅探:含 NUL 字节 → 二进制,跳过(扩展名漏网的 binary 兜底)。
+                if (buf.includes(0))
+                    continue;
+                // 按字节截断(中文等多字节内容也不会冲穿上限);单文件受 maxFileBytes 与
+                // 剩余总预算双重收口,超限只收前缀,toString 会把尾部可能被切断的半个
+                // UTF-8 字符替换成 U+FFFD。total 按实际写入的字节数累计(含截断标记与
+                // U+FFFD 展开),所以 maxTotalBytes 至多被末文件冲破十几个字节(常数级)。
+                const cap = Math.min(maxFileBytes, maxTotalBytes - total);
+                const over = buf.length > cap;
+                const slice = over ? buf.subarray(0, cap) : buf;
+                const text = slice.toString('utf-8') + (over ? '\n…[truncated]' : '');
+                files[relPath] = text;
+                total += Buffer.byteLength(text, 'utf-8');
+            }
+        }
+    };
+    walk(skillRoot, '', 0);
+    return files;
+}
+function isValidStatus(s) {
+    return s === 'pass' || s === 'warn' || s === 'fail';
+}
+/** ::ffff:a.b.c.d / 规范化后的 ::ffff:hhhh:hhhh 还原成点分 IPv4;无法解析返回 null。
+ *  WHATWG URL 会把 ::ffff:127.0.0.1 规范成 hex 形态 ::ffff:7f00:1。 */
+function mappedToIPv4(suffix) {
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(suffix))
+        return suffix;
+    const hx = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(suffix);
+    if (!hx)
+        return null;
+    const hi = parseInt(hx[1], 16);
+    const lo = parseInt(hx[2], 16);
+    return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}
+/** 私网/本机 hostname 判定(SSRF 防护用)。只做字面 hostname 检查的
+ *  defense-in-depth:不做 DNS 解析,公网域名解析到内网(DNS rebinding)不在
+ *  防护范围。WHATWG URL 会把 0x7f.0.0.1 / 0 之类写法规整成点分十进制,所以
+ *  IPv4 直接按规范化后的 hostname 判断即可。 */
+function isPrivateHostname(hostname) {
+    // 转小写、去 IPv6 字面量方括号([::1] → ::1)、去 FQDN 尾点(localhost. / foo.local.)。
+    let h = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    if (h === 'localhost' || h.endsWith('.local'))
+        return true;
+    if (h.includes(':')) {
+        // IPv6 字面量。
+        if (h === '::1' || h === '::')
+            return true; // loopback / unspecified
+        if (/^f[cd]/.test(h))
+            return true; // fc00::/7 ULA
+        if (/^fe[89ab]/.test(h))
+            return true; // fe80::/10 link-local
+        // IPv4-mapped(::ffff:…)归并到点分 IPv4 再判;无法解析的保守拒绝。
+        const mapped = /^::ffff:(.+)$/.exec(h);
+        if (!mapped)
+            return false;
+        const dotted = mappedToIPv4(mapped[1]);
+        if (dotted == null)
+            return true;
+        h = dotted;
+    }
+    const m = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(h);
+    if (!m)
+        return false;
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    if (a === 0)
+        return true; // 0.0.0.0/8(含 0.0.0.0、http://0/)
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16(含云 metadata 169.254.169.254)
+    return false;
+}
+/** outcome 自由文本/JSON 字段的统一上限(字符),与协议违规路径的 received 截断对齐。 */
+const MAX_OUTCOME_CHARS = 2000;
+/** 响应体声明长度(Content-Length)上限(字节):超过即拒读,避免超大 body 撑爆内存。
+ *  注意只挡声明了 Content-Length 的情况;分块且不声明长度的响应仍只受 timeoutMs 墙钟约束。 */
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+function clampText(s) {
+    return s.length > MAX_OUTCOME_CHARS ? `${s.slice(0, MAX_OUTCOME_CHARS)}…[truncated]` : s;
+}
+/** detail 先序列化判长:超限替换成 { truncated: true, preview } 结构,
+ *  保证仍是合法 JSON 值且不会无界塞进 report。 */
+function clampDetail(detail) {
+    const json = JSON.stringify(detail) ?? '';
+    if (json.length <= MAX_OUTCOME_CHARS)
+        return detail;
+    return { truncated: true, preview: json.slice(0, MAX_OUTCOME_CHARS) };
+}
+/**
+ * 把一个 endpoint spec 编译成 DoctorRule。check() 内组装 skill 快照、POST、
+ * 校验响应协议并映射成 DoctorRuleCheckOutcome。
+ *
+ * 所有失败(网络错误 / 非 2xx / 非法 JSON / 协议字段缺失)都返回 status='fail',
+ * 让用户立刻看到接口侧的问题,而不是静默放行。
+ */
+export function makeEndpointRule(spec, fetchFn = fetch) {
+    return {
+        id: spec.id,
+        severity: spec.severity,
+        // 自定义 key 不在 DOCTOR_MESSAGES 字典里,renderer 会 fallback 到 ruleId(=spec.id)。
+        labelKey: `cli.doctor.endpoint.${spec.id}`,
+        // 网络检查,与 health composer 同档:默认跑,--static-only 跳过。
+        external: true,
+        async check(ctx) {
+            // SSRF 防护(defense-in-depth):endpoint 会收到 skill 完整快照,且响应
+            // 原样回填进报告(response oracle),所以组装请求前先校验 scheme 与 host,
+            // 私网/本机地址默认拒绝(云 metadata 169.254.169.254、内网主机等)。
+            // 只做字面校验、不做 DNS 解析:公网域名解析到内网(DNS rebinding)不在
+            // 防护范围。
+            let endpointUrl;
+            try {
+                endpointUrl = new URL(spec.endpoint);
+            }
+            catch {
+                return {
+                    status: 'fail',
+                    message: failMsg(ctx, spec, `endpoint 不是合法 URL：${spec.endpoint}`, `endpoint is not a valid URL: ${spec.endpoint}`),
+                    detail: { endpoint: spec.endpoint },
+                };
+            }
+            if (endpointUrl.protocol !== 'http:' && endpointUrl.protocol !== 'https:') {
+                return {
+                    status: 'fail',
+                    message: failMsg(ctx, spec, `endpoint 协议必须是 http/https，实际是 ${endpointUrl.protocol}`, `endpoint protocol must be http/https, got ${endpointUrl.protocol}`),
+                    detail: { endpoint: spec.endpoint, protocol: endpointUrl.protocol },
+                };
+            }
+            if (!spec.allowPrivateHost && isPrivateHostname(endpointUrl.hostname)) {
+                return {
+                    status: 'fail',
+                    message: failMsg(ctx, spec, `endpoint 指向私网/本机地址（${endpointUrl.hostname}），默认拒绝以防 SSRF（skill 快照会被外发、响应会回填进报告）；确认该内网服务可信后，可在维度配置加 allowPrivateHost: true 放行`, `endpoint points to a private/loopback host (${endpointUrl.hostname}); refused by default to prevent SSRF (the skill snapshot is sent out and the response is echoed into the report). Set allowPrivateHost: true in the dimension config if this internal service is trusted`),
+                    detail: { endpoint: spec.endpoint, hostname: endpointUrl.hostname },
+                };
+            }
+            const artifact = ctx.artifact;
+            const content = artifact.content ?? '';
+            const skillName = artifact.name.replace(/\.md$/, '').split('/').pop() ?? artifact.name;
+            const skillRoot = artifact.skillRoot ?? null;
+            const includeFiles = spec.includeFiles !== false;
+            const files = includeFiles
+                ? collectFiles(skillRoot, spec.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES, spec.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES)
+                : {};
+            const body = {
+                dimensionId: spec.id,
+                params: spec.params ?? {},
+                skill: {
+                    name: skillName,
+                    content,
+                    skillRoot,
+                    ref: artifact.ref ?? null,
+                    files,
+                },
+            };
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), ctx.timeoutMs);
+            let parsed;
+            try {
+                let res;
+                try {
+                    res = await fetchFn(spec.endpoint, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json', ...spec.headers },
+                        body: JSON.stringify(body),
+                        signal: controller.signal,
+                        // redirect:'manual' —— 不跟随重定向。否则一个可信公网 endpoint 返回
+                        // 302 Location: http://169.254.169.254/… 即可让 fetch 透明跳到私网,
+                        // 绕过上面的 host 校验(请求前只校验一次原始 URL)。3xx 一律拒绝。
+                        redirect: 'manual',
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        status: 'fail',
+                        message: failMsg(ctx, spec, `请求失败：${msg}`, `request failed: ${msg}`),
+                        hint: hintNet(ctx, spec.endpoint),
+                        detail: { endpoint: spec.endpoint, error: msg },
+                    };
+                }
+                if (res.status >= 300 && res.status < 400) {
+                    const location = res.headers?.get?.('location') ?? null;
+                    return {
+                        status: 'fail',
+                        message: failMsg(ctx, spec, `endpoint 返回重定向（HTTP ${res.status}），默认拒绝以防 SSRF（重定向目标可能指向私网）`, `endpoint returned a redirect (HTTP ${res.status}); refused by default to prevent SSRF (the redirect target may point to a private host)`),
+                        hint: hintNet(ctx, spec.endpoint),
+                        detail: { endpoint: spec.endpoint, httpStatus: res.status, location },
+                    };
+                }
+                const declaredLen = Number(res.headers?.get?.('content-length') ?? '');
+                if (Number.isFinite(declaredLen) && declaredLen > MAX_RESPONSE_BYTES) {
+                    return {
+                        status: 'fail',
+                        message: failMsg(ctx, spec, `响应体过大（Content-Length ${declaredLen} 字节，上限 ${MAX_RESPONSE_BYTES}）`, `response body too large (Content-Length ${declaredLen} bytes, limit ${MAX_RESPONSE_BYTES})`),
+                        hint: hintProto(ctx),
+                        detail: { endpoint: spec.endpoint, contentLength: declaredLen },
+                    };
+                }
+                if (!res.ok) {
+                    return {
+                        status: 'fail',
+                        message: failMsg(ctx, spec, `接口返回 HTTP ${res.status}`, `endpoint returned HTTP ${res.status}`),
+                        hint: hintNet(ctx, spec.endpoint),
+                        detail: { endpoint: spec.endpoint, httpStatus: res.status },
+                    };
+                }
+                try {
+                    parsed = await res.json();
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        status: 'fail',
+                        message: failMsg(ctx, spec, `响应不是合法 JSON：${msg}`, `response is not valid JSON: ${msg}`),
+                        hint: hintProto(ctx),
+                        detail: { endpoint: spec.endpoint, error: msg },
+                    };
+                }
+            }
+            finally {
+                // timer 覆盖 fetch + body 读取(res.json()):两者都完成或任一出错后才清,
+                // 防止慢速/滴流响应体绕过 ctx.timeoutMs 无限挂起。
+                clearTimeout(timer);
+            }
+            const resp = parsed;
+            if (!isValidStatus(resp.status) || typeof resp.message !== 'string') {
+                return {
+                    status: 'fail',
+                    message: failMsg(ctx, spec, '响应缺少必填字段 status(pass/warn/fail) 或 message', 'response missing required field status (pass/warn/fail) or message'),
+                    hint: hintProto(ctx),
+                    // received 截断:接口可能返回超大 body,避免无界塞进 report JSON。
+                    detail: { endpoint: spec.endpoint, received: JSON.stringify(parsed).slice(0, MAX_OUTCOME_CHARS) },
+                };
+            }
+            // 合法响应同样截断:message / hint / detail 都来自外部接口,不加界会被
+            // 无界写入 outcome 落盘(与上面 received 的处理风格对齐)。
+            return {
+                status: resp.status,
+                message: `${spec.displayName}: ${clampText(resp.message)}`,
+                hint: typeof resp.hint === 'string' ? clampText(resp.hint) : resp.hint,
+                detail: resp.detail == null ? { endpoint: spec.endpoint } : clampDetail(resp.detail),
+            };
+        },
+    };
+}
+function failMsg(ctx, spec, zh, en) {
+    const head = `${spec.displayName}`;
+    return ctx.lang === 'zh' ? `${head}: ${zh}` : `${head}: ${en}`;
+}
+function hintNet(ctx, endpoint) {
+    return ctx.lang === 'zh'
+        ? `确认接口 ${endpoint} 可达、鉴权 header 正确，或调大 --timeout`
+        : `Verify endpoint ${endpoint} is reachable, auth headers are correct, or raise --timeout`;
+}
+function hintProto(ctx) {
+    return ctx.lang === 'zh'
+        ? '接口需返回 JSON: { status: "pass"|"warn"|"fail", message: string, hint?, detail? }'
+        : 'Endpoint must return JSON: { status: "pass"|"warn"|"fail", message: string, hint?, detail? }';
+}

package/dist/doctor/health/load-custom-dimensions.d.ts

@@ -1 +1,7 @@
+/**
+ * 加载自定义维度 YAML 并注册。两类维度按字段自动分流:
+ *   - 带 `endpoint` → 接口维度,注册成独立 DoctorRule(运行时 POST skill 快照)。
+ *   - 带 `promptSection` → LLM 维度,注册进 health composer(原逻辑)。
+ * 返回成功注册的维度数量。
+ */
 export declare function loadAndRegisterCustomDimensions(filePath: string): number;

package/dist/doctor/health/load-custom-dimensions.js

@@ -1,7 +1,25 @@
 import { readFileSync, existsSync } from 'node:fs';
 import yaml from 'js-yaml';
 import { registerHealthDimension } from './dimension-registry.js';
+import { registerRule } from '../rules.js';
+import { makeEndpointRule } from '../endpoint-rule.js';
 const VALID_SEVERITIES = new Set(['fatal', 'warn', 'info']);
+/** 缺省 → warn;非法值直接 throw(与 id 缺失同等对待),避免用户写了
+ *  `severity: critical` 想要 fatal 却被静默降成 warn、endpoint fail 不再 gate。 */
+function resolveSeverity(dimId, raw) {
+    if (raw == null)
+        return 'warn'; // 缺省/空值 → 默认 warn
+    if (!VALID_SEVERITIES.has(raw)) {
+        throw new Error(`自定义维度 ${dimId} 的 severity 非法：${raw}（合法值：fatal / warn / info）`);
+    }
+    return raw;
+}
+/**
+ * 加载自定义维度 YAML 并注册。两类维度按字段自动分流:
+ *   - 带 `endpoint` → 接口维度,注册成独立 DoctorRule(运行时 POST skill 快照)。
+ *   - 带 `promptSection` → LLM 维度,注册进 health composer(原逻辑)。
+ * 返回成功注册的维度数量。
+ */
 export function loadAndRegisterCustomDimensions(filePath) {
     if (!existsSync(filePath)) {
         throw new Error(`自定义维度配置文件不存在: ${filePath}`);
@@ -12,10 +30,32 @@ export function loadAndRegisterCustomDimensions(filePath) {
         return 0;
     let count = 0;
     for (const dim of doc.dimensions) {
-        if (!dim.id || !dim.displayName || !dim.promptSection) {
-            throw new Error(`自定义维度缺少必填字段（id/displayName/promptSection）: ${JSON.stringify(dim).slice(0, 100)}`);
+        if (!dim.id || !dim.displayName) {
+            throw new Error(`自定义维度缺少必填字段（id/displayName）: ${JSON.stringify(dim).slice(0, 100)}`);
+        }
+        if (dim.endpoint && dim.promptSection) {
+            throw new Error(`自定义维度 ${dim.id} 不能同时配置 endpoint 与 promptSection（二选一）`);
+        }
+        const severity = resolveSeverity(dim.id, dim.severity);
+        if (dim.endpoint) {
+            registerRule(makeEndpointRule({
+                id: dim.id,
+                displayName: dim.displayName,
+                severity,
+                endpoint: dim.endpoint,
+                params: dim.params,
+                includeFiles: dim.includeFiles,
+                headers: dim.headers,
+                maxFileBytes: dim.maxFileBytes,
+                maxTotalBytes: dim.maxTotalBytes,
+                allowPrivateHost: dim.allowPrivateHost,
+            }));
+            count++;
+            continue;
+        }
+        if (!dim.promptSection) {
+            throw new Error(`自定义维度 ${dim.id} 必须配置 endpoint 或 promptSection 之一`);
         }
-        const severity = VALID_SEVERITIES.has(dim.severity ?? '') ? dim.severity : 'warn';
         const spec = {
             id: dim.id,
             displayName: dim.displayName,

package/dist/doctor/index.js

@@ -206,11 +206,17 @@ export async function runDoctor(opts) {
     const skillReports = [];
     const totals = { pass: 0, warn: 0, fail: 0 };
     const ruleStats = { pass: 0, warn: 0, fail: 0, skipped: 0, total: 0 };
+    const total = artifacts.length;
+    let index = 0;
     for (const artifact of artifacts) {
+        index += 1;
+        const skillName = basename(artifact.name).replace(/\.md$/, '');
+        opts.onProgress?.({ phase: 'skill_start', index, total, skillName });
+        const startedAt = Date.now();
         const results = await runRulesOnArtifact(artifact, effectiveRules, ctxBase);
         const status = classifySkillStatus(results);
         skillReports.push({
-            skillName: basename(artifact.name).replace(/\.md$/, ''),
+            skillName,
             skillPath: inferSkillPath(artifact, opts.cwd),
             results,
             status,
@@ -220,6 +226,7 @@ export async function runDoctor(opts) {
             ruleStats[r.status] += 1;
             ruleStats.total += 1;
         }
+        opts.onProgress?.({ phase: 'skill_done', index, total, skillName, status, durationMs: Date.now() - startedAt });
     }
     // Single-enum verdict for CI / agent code. fatal-fail dominates;
     // warnings_only when no fatal-fail but at least one warn; otherwise passed.

package/dist/executors/codex-cli.js

@@ -113,7 +113,11 @@ export function buildCodexArgs({ model, cwd, prompt }) {
         args.push('--model', model);
     if (cwd)
         args.push('-C', cwd);
-    args.push(prompt);
+    // `--` end-of-options 分隔符:prompt 必须放在 `--` 之后。system prompt 被 prepend 时,
+    // skill 内容常以 YAML frontmatter `---` 开头,codex(clap)会把以 `-`/`--` 开头的位置参数
+    // 当未知 flag → exit 2(unexpected argument),72ms 秒退、不跑 agent。`--` 之后一律当
+    // positional,不再按 flag 解析(codex 自身的报错 tip 即建议此法)。bug:整个 skill eval 全失败。
+    args.push('--', prompt);
     return args;
 }
 // codex 看到 stdin 是 pipe 就当作 `<stdin>` 块读,会卡到 timeout。spawn 后立刻

package/dist/managed/index.d.ts

@@ -5,3 +5,4 @@
 export * from './store.js';
 export * from './evidence.js';
 export * from './list-view.js';
+export * from './promote-gate.js';

package/dist/managed/index.js

@@ -5,3 +5,4 @@
 export * from './store.js';
 export * from './evidence.js';
 export * from './list-view.js';
+export * from './promote-gate.js';

package/dist/managed/list-view.d.ts

@@ -43,6 +43,9 @@ export interface ManagedListRow {
     totalEvidenceCount: number;
     distributionCount: number;
 }
+/** 当前有效证据(contentHash == record.contentHash)里 recordedAt 最新那条;无则 undefined。
+ *  list(展示最新 verdict)与 promote(门禁取证)共用同一口径——旧内容的证据不冒充当前。 */
+export declare function latestCurrentEvidence(record: ManagedArtifactRecord): import("../types/managed.js").ManagedEvidenceRef | undefined;
 export declare function buildManagedListRow(record: ManagedArtifactRecord, probe: SourceProbe): ManagedListRow;
 /**
  * 组装全部行。`probeOf` 给每条记录探测当前源(三态,见文件头)。

package/dist/managed/list-view.js

@@ -1,5 +1,7 @@
-import { deriveManagedState } from './store.js';
-function latestCurrentEvidence(record) {
+import { deriveManagedState, isCurrentlyPromoted } from './store.js';
+/** 当前有效证据(contentHash == record.contentHash)里 recordedAt 最新那条;无则 undefined。
+ *  list(展示最新 verdict)与 promote(门禁取证)共用同一口径——旧内容的证据不冒充当前。 */
+export function latestCurrentEvidence(record) {
     const current = record.evidence.filter((e) => e.contentHash === record.contentHash);
     if (current.length === 0)
         return undefined;
@@ -26,8 +28,10 @@ export function buildManagedListRow(record, probe) {
         drifted = d.drifted;
     }
     else {
-        // 不可达:不据此判 stale —— 只按证据给 installed/measurable,drift 标未核。
-        state = currentEvidenceCount > 0 ? 'measurable' : 'installed';
+        // 不可达:不据此判 stale。promote 决定是**内容锚定**的(只看 record.decisions + record.contentHash,
+        // 不依赖源能否被 probe),故当前内容仍处于 promoted 态时保留 promoted —— 它比 evidence 更不该因源不可达
+        // 丢失(deriveManagedState 的 promoted 分支同理)。否则按证据给 measurable/installed,drift 标未核。
+        state = isCurrentlyPromoted(record) ? 'promoted' : currentEvidenceCount > 0 ? 'measurable' : 'installed';
         drifted = false;
     }
     const latest = latestCurrentEvidence(record);

package/dist/managed/promote-gate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * promote 证据门禁(纯函数,无 IO)——`omk list` 读侧判据的写侧对应。
+ *
+ * 把「这份当前版本是否值得 ship」收成一组可拦截原因(spec evidence-gated-management.md §5 mandatory four
+ * + §7 default gate)。默认只放行 verdict=PROGRESS(omk default-strict:影响「值得 ship」判定的默认必须严格);
+ * CAUTIOUS 需显式 `acceptCautious`;其余 verdict 一律拦。可比性核对(judge prompt 是否还是当前评委)用
+ * **注入**的当前 judge hash 集合,故本模块不依赖 grading 层、保持叶子可测。
+ *
+ * force(越门)不在此处:门禁只产「客观判定」。CLI 拿到结果后决定是否 `--force` 越过——但**无当前证据时
+ * 无 evidence 可锚定,force 也越不过**(返回的 evidence 为 undefined,CLI 据此拒绝空证据 promote)。
+ */
+import type { ManagedArtifactRecord, ManagedEvidenceRef } from '../types/index.js';
+export type PromoteBlockKind = 'drifted' | 'no_current_evidence' | 'incomparable' | 'verdict_blocked';
+export interface PromoteBlock {
+    /** 限定判别字(裸 kind 留给 ArtifactKind,见 terminology-spec §5.4);这是「拦截原因」分类、非持久。 */
+    blockKind: PromoteBlockKind;
+    /** 供 CLI 拼 i18n 参数的可读细节(被拦的 verdict / judge hash 等)。 */
+    detail?: Record<string, string>;
+}
+export interface PromoteGateInput {
+    record: ManagedArtifactRecord;
+    /** 当前源内容 hash;undefined = 源不可达 / 解析失败(probeSourceState reachable:false)。 */
+    currentContentHash?: string;
+    /** 接受 CAUTIOUS(默认只接受 PROGRESS)。 */
+    acceptCautious?: boolean;
+    /** 当前 omk 的 judge prompt hash 集合(debias on/off 两变体)。CLI 用 getJudgePromptHash 算好注入,
+     *  使本模块不依赖 grading 层。空集 / 省略 = 跳过可比性核对(只在无法取 judge hash 时)。 */
+    currentJudgeHashes?: ReadonlySet<string>;
+}
+export interface PromoteGateResult {
+    /** 无任何拦截原因 → 门禁通过。 */
+    ok: boolean;
+    blocked: PromoteBlock[];
+    /** 非拦截级提醒(如 judgePromptHash 缺失、无从核对可比性)。 */
+    warnings: PromoteBlock[];
+    /** 命中判定的当前有效证据;无当前证据时 undefined —— CLI 据此判定「force 也不能空证据 promote」。 */
+    evidence?: ManagedEvidenceRef;
+    drifted: boolean;
+}
+export declare function evaluatePromoteGate(input: PromoteGateInput): PromoteGateResult;

package/dist/managed/promote-gate.js

@@ -0,0 +1,37 @@
+import { latestCurrentEvidence } from './list-view.js';
+// 默认接受集:只 PROGRESS。
+const DEFAULT_ACCEPTED = new Set(['PROGRESS']);
+export function evaluatePromoteGate(input) {
+    const { record, currentContentHash, acceptCautious, currentJudgeHashes } = input;
+    const blocked = [];
+    const warnings = [];
+    const drifted = currentContentHash === undefined || currentContentHash !== record.contentHash;
+    // 1. drift:源不可达 / 内容已变 → 当前盘上的源不是被测内容,门禁不过(force 可越,见 CLI)。
+    if (drifted)
+        blocked.push({ blockKind: 'drifted' });
+    // 2. 当前有效证据(contentHash == record.contentHash;源 drift 不影响——证据绑的是记录基线内容)。
+    const evidence = latestCurrentEvidence(record);
+    if (!evidence) {
+        // 无证据无从谈 verdict / 可比性,且 force 也无 evidence 可锚定 → 提前收,终态拦截。
+        blocked.push({ blockKind: 'no_current_evidence' });
+        return { ok: false, blocked, warnings, drifted };
+    }
+    // 3. 可比性:judgePromptHash 在场且不属当前任一评委模板 → 评委已变、旧 verdict 不可比 → 拦。
+    //    缺失 → 无从核对(旧报告 / 无 judge 评测)→ warn 不拦。cliVersion 仅展示、不硬卡(否则每次发版即全失效)。
+    const judgeHash = evidence.comparability?.judgePromptHash;
+    if (judgeHash !== undefined && currentJudgeHashes && currentJudgeHashes.size > 0) {
+        if (!currentJudgeHashes.has(judgeHash)) {
+            blocked.push({ blockKind: 'incomparable', detail: { judgePromptHash: judgeHash } });
+        }
+    }
+    else if (judgeHash === undefined) {
+        warnings.push({ blockKind: 'incomparable' });
+    }
+    // 4. verdict ∈ 接受集。
+    const accepted = acceptCautious ? new Set([...DEFAULT_ACCEPTED, 'CAUTIOUS']) : DEFAULT_ACCEPTED;
+    const verdict = evidence.verdict;
+    if (!verdict || !accepted.has(verdict)) {
+        blocked.push({ blockKind: 'verdict_blocked', detail: { verdict: verdict ?? 'UNKNOWN' } });
+    }
+    return { ok: blocked.length === 0, blocked, warnings, evidence, drifted };
+}