oh-my-knowledge 0.36.0 → 0.37.0

package/dist/server/report-server.js

@@ -5,8 +5,9 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { renderReportDocumentDetail, renderTrendsPage, renderRunList } from '../renderer/html-renderer.js';
 import { renderSkillList } from '../renderer/skill-list-renderer.js';
-import { renderSkillDetail } from '../renderer/skill-detail-renderer.js';
 import { renderSkillHealthReport } from '../renderer/skill-health-renderer.js';
+import { renderDoctorDetail } from '../renderer/doctor-detail-renderer.js';
+import { assessHealth } from '../renderer/skill-detail-renderer.js';
 import { renderObservationInboxPage } from '../renderer/observation-inbox-renderer.js';
 import { DEFAULT_LANG, t, layout } from '../renderer/layout.js';
 import { buildSkillIndex } from './skill-index.js';
@@ -80,6 +81,28 @@ function loadAnalysis(dir, id) {
         return null;
     }
 }
+/** 扫 doctorsDir 找 id 匹配的 doctor 报告（文件名不一定等于 report id）。
+ *  批量 doctor 会按 skill 拆成多份共享同一 id 的 per-skill 文件，传 skillName 时
+ *  优先返回含该 skill 的那份；都不含时回退首个 id 命中（单 skill / 无参行为不变）。 */
+function loadDoctorReport(dir, id, skillName) {
+    if (!existsSync(dir))
+        return null;
+    let fallback = null;
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+            if (data?.kind !== 'doctor' || data.id !== id)
+                continue;
+            if (!skillName || data.skills?.some((s) => s.skillName === skillName))
+                return data;
+            fallback ??= data;
+        }
+        catch { /* skip */ }
+    }
+    return fallback;
+}
 /**
  * 扫 analyses/ 所有 JSON,按 skillName 过滤,按时间排序成 trend points。
  */
@@ -204,6 +227,85 @@ function readJsonBody(req, maxBytes = 1024 * 1024) {
         req.on('error', reject);
     });
 }
+function fmtHistDate(ts, lang) {
+    if (!ts)
+        return '-';
+    try {
+        const d = new Date(ts);
+        return d.toLocaleString(lang === 'zh' ? 'zh-CN' : 'en-US', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' });
+    }
+    catch {
+        return ts;
+    }
+}
+// 报告详情页顶部「skill 上下文」:doctor/eval/observe 维度切换器 + 「全部历史」弹框(该 skill 历次 run)。
+// observe 详情是 fleet 级日报,无 per-skill 页,observe chip 只当状态点不可点。
+function buildSkillContext(entry, currentDim, currentReportId, insights, lang) {
+    const zh = lang === 'zh';
+    const langQ = lang === DEFAULT_LANG ? '' : `?lang=${lang}`;
+    const amp = lang === DEFAULT_LANG ? '' : `&lang=${lang}`;
+    // 综合健康分(= 跨维度聚合,与首页列表同一口径)— 报告页只显单维度分数,这里把「总分」也带上。
+    const health = assessHealth(entry, insights, lang);
+    const d = entry.doctor;
+    const dTotal = d ? d.passCount + d.warnCount + d.failCount : 0;
+    const dScore = d && dTotal > 0 ? Math.round(((d.passCount + d.warnCount * 0.5) / dTotal) * 100) : null;
+    const dBand = d ? (d.failCount > 0 ? 'red' : d.warnCount > 0 ? 'yellow' : 'green') : 'gray';
+    const ev = entry.eval;
+    const evScore = ev && ev.compositeScore != null ? Math.round((ev.compositeScore / 5) * 100) : null;
+    const evBand = ev && ev.compositeScore != null
+        ? (ev.compositeScore >= 4 ? 'green' : ev.compositeScore >= 3 ? 'yellow' : 'red') : 'gray';
+    const ob = entry.observe;
+    const obScore = ob ? Math.round((1 - ob.gapRate) * 100) : null;
+    const obBand = ob ? ob.healthBand : 'gray';
+    // 历史:eval + doctor 历次 run,各自新→旧。点行跳到那次报告。
+    // evalHistory 是「每轮一条」,但一份 evolve 报告(多轮)是同一个 reportId —— 按 reportId 去重,
+    // 一份报告只算一条(取末轮 treatment 分数,与报告头部一致),否则同一报告的多轮会都标「当前」。
+    const evalRoundCount = new Map();
+    const evalByReport = new Map();
+    for (const h of entry.evalHistory) {
+        evalRoundCount.set(h.reportId, (evalRoundCount.get(h.reportId) ?? 0) + 1);
+        evalByReport.set(h.reportId, h); // 末轮(最高 round)胜出 —— history 已按 timestamp#round 升序
+    }
+    const evalHist = [...evalByReport.values()].reverse().map((h) => {
+        const rounds = evalRoundCount.get(h.reportId) ?? 1;
+        return {
+            dim: 'eval',
+            dateText: fmtHistDate(h.timestamp, lang),
+            scoreText: h.compositeScore != null ? `${h.compositeScore.toFixed(2)} / 5` : '—',
+            band: (h.compositeScore == null ? 'gray' : h.compositeScore >= 4 ? 'green' : h.compositeScore >= 3 ? 'yellow' : 'red'),
+            metaText: `${h.passCount}/${h.totalSamples} ${zh ? '通过' : 'pass'}${h.failCount > 0 ? ` · ${h.failCount} ${zh ? '失败' : 'fail'}` : ''}${rounds > 1 ? ` · ${rounds} ${zh ? '轮' : 'rounds'}` : ''}`,
+            href: `/reports/${encodeURIComponent(h.reportId)}${langQ}`,
+            current: h.reportId === currentReportId,
+        };
+    });
+    const doctorHist = [...entry.doctorHistory].reverse().map((h) => {
+        const tot = h.passCount + h.warnCount + h.failCount;
+        return {
+            dim: 'doctor',
+            dateText: fmtHistDate(h.timestamp, lang),
+            scoreText: tot > 0 ? `${Math.round(((h.passCount + h.warnCount * 0.5) / tot) * 100)}` : '—',
+            band: (h.failCount > 0 ? 'red' : h.warnCount > 0 ? 'yellow' : 'green'),
+            metaText: `${h.passCount}✓ ${h.warnCount}⚠ ${h.failCount}✗`,
+            href: `/doctors/${encodeURIComponent(h.reportId)}?skill=${encodeURIComponent(entry.skillName)}${amp}`,
+            current: h.reportId === currentReportId,
+        };
+    });
+    return {
+        skillName: entry.skillName,
+        overall: { score: health.score, band: health.color },
+        // 当前维度 chip 不显分数(hero ring 已显示「本报告」分数,避免与「最新」分数冲突);非当前维度显「最新」分数 + 链接。
+        chips: [
+            { dim: 'doctor', label: zh ? '体检' : 'Doctor', score: currentDim === 'doctor' ? null : dScore, band: dBand,
+                href: currentDim === 'doctor' || !d ? null : `/doctors/${encodeURIComponent(d.reportId)}?skill=${encodeURIComponent(entry.skillName)}${amp}`,
+                active: currentDim === 'doctor' },
+            { dim: 'eval', label: zh ? '评测' : 'Eval', score: currentDim === 'eval' ? null : evScore, band: evBand,
+                href: currentDim === 'eval' || !ev ? null : `/reports/${encodeURIComponent(ev.reportId)}${langQ}`,
+                active: currentDim === 'eval' },
+            { dim: 'observe', label: zh ? '观察' : 'Observe', score: obScore, band: obBand, href: null, active: false },
+        ],
+        history: [...evalHist, ...doctorHist],
+    };
+}
 function renderSkillDiffPage(diff, lang = DEFAULT_LANG) {
     const { fromId, toId, fromAt, toAt, rows } = diff;
     const langQ = lang === DEFAULT_LANG ? '' : `?lang=${lang}`;
@@ -561,6 +663,29 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
                 res.end(JSON.stringify({ error: 'method not allowed' }));
                 return;
             }
+            const doctorDetailMatch = path.match(/^\/doctors\/(.+)$/);
+            if (doctorDetailMatch) {
+                const id = decodeURIComponent(doctorDetailMatch[1]);
+                const skillName = parsed.searchParams.get('skill') ?? '';
+                const report = loadDoctorReport(doctorsDir, id, skillName || undefined);
+                if (!report) {
+                    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(lang === 'en' ? 'doctor report not found' : '体检报告不存在');
+                    return;
+                }
+                let ctx;
+                if (skillName) {
+                    const runs = await reportStore.list();
+                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir);
+                    const entry = idx.entries.find((en) => en.skillName === skillName);
+                    if (entry)
+                        ctx = buildSkillContext(entry, 'doctor', id, idx.insightsBySkill.get(entry.skillName) ?? [], lang);
+                }
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                const langQ = lang === DEFAULT_LANG ? '' : `?lang=${lang}`;
+                res.end(renderDoctorDetail(report, skillName, langQ, lang, ctx));
+                return;
+            }
             const analysisDetailMatch = path.match(/^\/analyses\/(.+)$/);
             if (analysisDetailMatch) {
                 const id = decodeURIComponent(analysisDetailMatch[1]);
@@ -708,9 +833,19 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
             }
             const reportPageMatch = path.match(/^\/reports\/(.+)$/);
             if (reportPageMatch) {
-                const report = await queryRun(reportStore, decodeURIComponent(reportPageMatch[1]));
+                const reportId = decodeURIComponent(reportPageMatch[1]);
+                const report = await queryRun(reportStore, reportId);
+                let ctx;
+                if (report && report.kind === 'evaluation') {
+                    const runs = await reportStore.list();
+                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir);
+                    // 按 evalHistory 匹配(非仅最新),历史 eval 报告也能定位到所属 skill。
+                    const entry = idx.entries.find((en) => en.evalHistory.some((h) => h.reportId === reportId));
+                    if (entry)
+                        ctx = buildSkillContext(entry, 'eval', reportId, idx.insightsBySkill.get(entry.skillName) ?? [], lang);
+                }
                 res.writeHead(report ? 200 : 404, { 'Content-Type': 'text/html; charset=utf-8' });
-                res.end(renderReportDocumentDetail(report, lang));
+                res.end(renderReportDocumentDetail(report, lang, ctx));
                 return;
             }
             // 老 run 列表 — 兼容老书签。/skills/ 切换为默认后,run 列表挪这里。
@@ -745,31 +880,10 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
                 }));
                 return;
             }
-            // /skills/<name> 详情页 — 4 张卡片(doctor / eval-评分 / eval-功能 / observe)
-            // + 跨报告 cross-link + 行动建议。
-            const skillDetailMatch = path.match(/^\/skills\/(.+)$/);
-            if (skillDetailMatch) {
-                const skillName = decodeURIComponent(skillDetailMatch[1]);
-                const runs = await reportStore.list();
-                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir);
-                const entry = idx.entries.find((e) => e.skillName === skillName);
-                if (!entry) {
-                    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-                    res.end(`Skill not found: ${skillName}`);
-                    return;
-                }
-                // 加载完整 eval 报告(为详情页提供 layered scores / coverage / per-sample diagnostic)
-                let evalReport = null;
-                if (entry.eval) {
-                    const r = await reportStore.get(entry.eval.reportId);
-                    if (r && r.kind === 'evaluation')
-                        evalReport = r;
-                }
-                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                const insights = idx.insightsBySkill.get(skillName) ?? [];
-                res.end(renderSkillDetail(entry, evalReport, lang, insights));
-                return;
-            }
+            // 注:/skills/<name> 详情页(hub)已下线 — 首页点行直接进 eval/doctor 报告,跨维度靠
+            // 报告页 chip 条 +「全部历史」弹框,不再有中间汇总页。该路由不做兼容重定向:Studio
+            // 是本地临时服务器、端口每次启动都变,跨会话书签 localhost:<port> 本就失效,且 PR 内
+            // 已无任何链接指向它。未匹配的 /skills/<name> 直接落到下方通用 404。
             const skillDiagnosticsApiMatch = path.match(/^\/api\/skills\/(.+)\/diagnostics$/);
             if (skillDiagnosticsApiMatch) {
                 const skillName = decodeURIComponent(skillDiagnosticsApiMatch[1]);

package/dist/types/doctor.d.ts

@@ -85,6 +85,10 @@ export interface DoctorRule {
     severity: DoctorSeverity;
     /** i18n key,terminal 渲染时用作 rule 标题。 */
     labelKey: string;
+    /** true = 需要外部 I/O(网络 / LLM)的"在线"检查,跟 skill_health composer 同档:
+     *  默认 `omk doctor` 会跑,`--static-only` 离线模式跳过。endpoint 自定义维度置 true。
+     *  缺省(undefined/false)= 纯静态低成本检查(内置 4 条),静态模式才跑。 */
+    external?: boolean;
     check(ctx: DoctorContext): Promise<DoctorRuleCheckOutcome>;
 }
 export interface DoctorSkillReport {
@@ -126,6 +130,21 @@ export interface DoctorReport {
         total: number;
     };
 }
+/** 批量体检的 per-skill 进度事件。runDoctor 在遍历 artifacts 时,每个 skill
+ *  开始(skill_start)和结束(skill_done)各发一次,对齐 eval 的 per-sample 进度。 */
+export interface DoctorProgressInfo {
+    phase: 'skill_start' | 'skill_done';
+    /** 第几个 skill(1-based)。 */
+    index: number;
+    /** skill 总数。 */
+    total: number;
+    skillName: string;
+    /** 仅 skill_done:该 skill 的最终状态。 */
+    status?: DoctorSkillStatus;
+    /** 仅 skill_done:该 skill 全部 rule 的执行耗时(ms)。 */
+    durationMs?: number;
+}
+export type DoctorProgressCallback = (info: DoctorProgressInfo) => void;
 export interface DoctorRunOptions {
     /** 单 skill 文件 / 目录 / null(=cwd 当前目录批量)。当 artifacts 显式提供时, target 被忽略。 */
     target?: string | null;
@@ -153,4 +172,7 @@ export interface DoctorRunOptions {
      *  programmatic API 默认 false。 */
     runHealthCheck?: boolean;
     effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** 批量体检进度回调(per-skill)。CLI 非 gate 模式注入、写 stderr;eval 内嵌
+     *  调用不传(eval 有自己的进度体系,不应冒出 doctor 进度)。 */
+    onProgress?: DoctorProgressCallback;
 }

package/dist/types/managed.d.ts

@@ -52,12 +52,25 @@ export interface ManagedEvidenceRef {
     };
 }
 export type ManagedDecisionKind = 'promote' | 'reject' | 'rollback';
-/** 一次人工管理决定。install 时为空,promote/reject/rollback 追加。 */
+/** 一次人工管理决定。install 时为空,promote/reject/rollback 追加(append-only 事件流)。 */
 export interface ManagedDecision {
     decisionKind: ManagedDecisionKind;
     actor: string;
     decidedAt: string;
     reason?: string;
+    /** 被该决定接受 / 回滚到的内容 hash —— 锚定「决定的是哪份内容」。promote 取决定时的 record.contentHash;
+     *  读时只把与当前 contentHash 匹配的 promote 决定算作「当前版本已 promoted」(旧内容的决定不冒充当前)。 */
+    contentHash?: string;
+    /** 该决定锚定的证据 report(promote 取 latestCurrentEvidence 那条的 reportId)——可回溯「凭什么 ship」。 */
+    reportId?: string;
+    /** 越门记录:门禁本应拦下,经 --force 显式越过时记下供审计(spec §7「Overrides must be explicit and
+     *  recorded」)。无此字段 = 正常通过门禁。`verdict` 是越门时证据的 verdict(上下文);`overriddenBlocks`
+     *  是真正被越过的判据(drifted / incomparable / verdict_blocked),让审计能回答「越过了什么」—— 只看
+     *  verdict 会误导(仅因 drift 越门时 verdict 可能仍是 PROGRESS)。 */
+    override?: {
+        verdict: string;
+        overriddenBlocks?: string[];
+    };
 }
 export interface ManagedArtifactSource {
     /** 源类型(限定判别字,非裸 kind)。`file`=本地路径;`git`=当前仓库某 ref 或远端(带 url)。 */
@@ -92,8 +105,9 @@ export interface ManagedArtifactRecord {
     evidence: ManagedEvidenceRef[];
     decisions: ManagedDecision[];
 }
-/** 读时推导的生命周期标签——不持久(见文件头说明)。 */
-export type ManagedLifecycleLabel = 'discovered' | 'installed' | 'measurable' | 'stale';
+/** 读时推导的生命周期标签——不持久(见文件头说明)。`promoted` 由当前内容(contentHash 匹配)有一条
+ *  promote 决定推出:它是 measurable 之上的「已人工接受当前版本」,故优先级高于 measurable。 */
+export type ManagedLifecycleLabel = 'discovered' | 'installed' | 'measurable' | 'stale' | 'promoted';
 export interface DerivedManagedState {
     label: ManagedLifecycleLabel;
     /** 当前源 hash 与记录的 contentHash 不一致(或源已不在)。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-knowledge",
-  "version": "0.36.0",
+  "version": "0.37.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",