@dommaker/harness 1.6.0 → 1.8.0

package/src/knowledge/audit-scoring.ts

@@ -0,0 +1,589 @@
+/**
+ * 知识库质量审计打分核心（harness#134：D1–D7 纯模块）
+ *
+ * 纯代码检测，零 token 成本，**零 IO**：入参只有条目集合与已取好的环境数据
+ * （消费统计、快照存活率由调用方经 store 取好喂进来），因此打分判定可脱离文件系统测试。
+ * 落盘与修复动作在 `audit.ts` 的引擎侧。
+ *
+ * 7 维度覆盖：结构完整性 / 内容质量 / 去重有效性 / 成熟度健康 / 新鲜度 / 飞轮验证 / 增量存活
+ */
+
+import { evaluateFlywheel, genuineRefs } from './flywheel-metrics';
+import type { KnowledgeEntry, SnapshotSurvival } from './types';
+
+// ── Types ─────────────────────────────────────────────────
+
+export type AuditRuleName =
+  // D1: 结构完整性
+  | 'frontmatter-missing'
+  // D2: 内容质量
+  | 'test-data-pollution'
+  | 'daily-audit-noise'
+  | 'event-noise'
+  | 'zero-content-proven'
+  | 'short-content'
+  | 'maturity-inflation'
+  // D3: 去重有效性
+  | 'title-duplicate'
+  | 'source-refs-bloat'
+  | 'fragment-cluster'
+  // D4: 成熟度健康
+  | 'promotion-blocked'
+  | 'orphan-draft'
+  // D5: 新鲜度
+  | 'stale-entry'
+  // D2: 领域相关性
+  | 'deprecated-domain';
+
+export type AuditAction = 'archive' | 'demote' | 'flag' | 'reject' | 'trim';
+
+export interface AuditIssue {
+  rule: AuditRuleName;
+  entryId: string;
+  title: string;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  action: AuditAction;
+  detail: string;
+}
+
+export interface DimensionMetrics {
+  score: number;  // 0-100
+  issues: number;
+  details: Record<string, number | string>;
+}
+
+export interface AuditReport {
+  timestamp: string;
+  totalEntries: number;
+  issues: AuditIssue[];
+  summary: Record<AuditRuleName, number>;
+  dimensions: {
+    structure: DimensionMetrics;
+    content: DimensionMetrics;
+    dedup: DimensionMetrics;
+    maturity: DimensionMetrics;
+    freshness: DimensionMetrics;
+    flywheel: DimensionMetrics;
+    incremental: DimensionMetrics;
+  };
+  autoFixed: number;
+  healthScore: { before: number; after: number };
+}
+
+/** 判定阈值（引擎构造入参，也是纯打分的判定口径） */
+export interface AuditOptions {
+  shortContentThreshold?: number;
+  staleDays?: number;
+  promotionBlockDays?: number;
+}
+
+/** 打分要吃的已取好环境数据——由调用方从存储层取，本模块不碰 fs */
+export interface AuditEnv {
+  /** `.consumption-stats.json` 的 dailyEvents（D6 飞轮）；未提供视为 0 */
+  dailyConsumptionEvents?: number;
+  /** N 天前快照的存活率（D7 增量存活）；未提供 = 无可用快照 */
+  survival?: SnapshotSurvival;
+}
+
+// ── Constants ─────────────────────────────────────────────
+
+export const DEFAULT_SHORT_CONTENT_THRESHOLD = 50;
+export const ZERO_CONTENT_THRESHOLD = 20;
+export const DEFAULT_STALE_DAYS = 90;
+export const DEFAULT_PROMOTION_BLOCK_DAYS = 30;
+export const MAX_SOURCE_REFS = 20;
+/** D7 增量存活取的快照龄期（天） */
+export const SURVIVAL_SNAPSHOT_DAYS = 30;
+
+const TEST_TAG_PATTERNS = [/^test-scope-/, /^test-empty-/, /^test-\d/];
+const DAILY_AUDIT_PATTERN = /^\[Auditor\] Daily audit/;
+const EVENT_NOISE_PATTERNS = [
+  /^\[Monitor\]\s/,
+  /^KnowledgeSync cycle:/,
+  /^\[Triage Fix\]\s/,
+  /^\[Session Feature\]\s/,
+];
+const REQUIRED_FRONTMATTER = ['id', 'type', 'title', 'maturity'];
+
+// ── Per-Entry Rules ───────────────────────────────────────
+
+interface AuditRule {
+  name: AuditRuleName;
+  /** 中文展示文案正本（#109）：定义即注册，CLI 经 AUDIT_RULE_LABELS 消费，无 label 即编译期失败 */
+  label: string;
+  severity: AuditIssue['severity'];
+  action: AuditAction;
+  /** 规则适用人口：active = 跳过 archived 条目；all = 全人口（含已归档） */
+  scope: AuditRuleScope;
+  detect: (entry: KnowledgeEntry, ctx: AuditContext) => string | null;
+}
+
+type AuditRuleScope = 'active' | 'all';
+
+interface AuditContext {
+  shortContentThreshold: number;
+  staleDays: number;
+  promotionBlockDays: number;
+  allEntries?: KnowledgeEntry[];
+}
+
+const perEntryRules: AuditRule[] = [
+  // D1: 结构完整性
+  {
+    name: 'frontmatter-missing',
+    label: 'frontmatter 缺失',
+    severity: 'high',
+    action: 'reject',
+    scope: 'all',
+    detect: (entry) => {
+      const missing = REQUIRED_FRONTMATTER.filter(f => {
+        const val = (entry as any)[f];
+        return val === undefined || val === null || val === '';
+      });
+      if (missing.length > 0) {
+        return `缺少必填字段: ${missing.join(', ')}`;
+      }
+      return null;
+    },
+  },
+
+  // D2: 内容质量
+  {
+    name: 'test-data-pollution',
+    label: '测试数据污染',
+    severity: 'critical',
+    action: 'archive',
+    scope: 'active',
+    detect: (entry) => {
+      // Match test ID patterns
+      if (/^(test-|inj-test)/.test(entry.id)) {
+        return `测试 ID: "${entry.id}"`;
+      }
+      const hasTestTag = (entry.tags ?? []).some(t => TEST_TAG_PATTERNS.some(p => p.test(t)));
+      if (hasTestTag) {
+        return `测试标签: ${(entry.tags ?? []).filter(t => TEST_TAG_PATTERNS.some(p => p.test(t))).join(', ')}`;
+      }
+      if (/^(Test Entry|Test pattern|Test incident|Empty Test)$/i.test(entry.title.trim())) {
+        return `测试标题: "${entry.title}"`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'daily-audit-noise',
+    label: '每日审计噪音',
+    severity: 'high',
+    action: 'archive',
+    scope: 'active',
+    detect: (entry) => {
+      if (DAILY_AUDIT_PATTERN.test(entry.title)) {
+        return `每日审计摘要: "${entry.title}"`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'event-noise',
+    label: '运维事件噪音',
+    severity: 'critical',
+    action: 'archive',
+    scope: 'active',
+    detect: (entry) => {
+      for (const pattern of EVENT_NOISE_PATTERNS) {
+        if (pattern.test(entry.title)) {
+          return `运维事件标题: "${entry.title}"`;
+        }
+      }
+      return null;
+    },
+  },
+  {
+    name: 'zero-content-proven',
+    label: '零内容 proven',
+    severity: 'critical',
+    action: 'demote',
+    scope: 'all',
+    detect: (entry) => {
+      if (entry.maturity === 'proven' && entry.content.trim().length < ZERO_CONTENT_THRESHOLD) {
+        return `proven 条目内容仅 ${entry.content.trim().length} 字符`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'maturity-inflation',
+    label: '成熟度虚高',
+    severity: 'high',
+    action: 'demote',
+    scope: 'all',
+    detect: (entry) => {
+      if (entry.maturity === 'verified' && entry.content.trim().length < ZERO_CONTENT_THRESHOLD) {
+        return `verified 条目内容仅 ${entry.content.trim().length} 字符`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'short-content',
+    label: '短内容',
+    severity: 'medium',
+    action: 'flag',
+    scope: 'active',
+    detect: (entry, ctx) => {
+      const len = entry.content.trim().length;
+      if (len < ctx.shortContentThreshold && len >= ZERO_CONTENT_THRESHOLD) {
+        return `内容 ${len} 字符 (阈值 ${ctx.shortContentThreshold})`;
+      }
+      return null;
+    },
+  },
+
+  // D3: 去重有效性
+  {
+    name: 'title-duplicate',
+    label: '标题重复',
+    severity: 'medium',
+    action: 'flag',
+    scope: 'active',
+    detect: (entry, ctx) => {
+      if (!ctx.allEntries) return null;
+      if (!entry.title) return null;
+      const dupes = ctx.allEntries.filter(e =>
+        e.id !== entry.id &&
+        e.maturity !== 'archived' &&
+        e.type === entry.type &&
+        e.title?.toLowerCase().trim() === entry.title.toLowerCase().trim()
+      );
+      if (dupes.length > 0) {
+        return `与 ${dupes.map(e => e.id).join(', ')} 标题重复`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'source-refs-bloat',
+    label: 'sourceReferences 膨胀',
+    severity: 'low',
+    action: 'trim',
+    scope: 'all',
+    detect: (entry) => {
+      if ((entry.sourceReferences?.length || 0) > MAX_SOURCE_REFS) {
+        return `sourceReferences ${entry.sourceReferences!.length} 条 (上限 ${MAX_SOURCE_REFS})`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'fragment-cluster',
+    label: '碎片集群',
+    severity: 'medium',
+    action: 'flag',
+    scope: 'active',
+    detect: (entry, ctx) => {
+      if (!ctx.allEntries || entry.content.trim().length >= 100) return null;
+      if (!entry.tags?.length) return null;
+
+      // Find peers: same type, short body, shared tags ≥2
+      const entryTags = new Set(entry.tags);
+      const peers = ctx.allEntries.filter(e =>
+        e.id !== entry.id &&
+        e.maturity !== 'archived' &&
+        e.type === entry.type &&
+        e.content.trim().length < 100 &&
+        e.tags?.filter(t => entryTags.has(t)).length >= 2
+      );
+
+      if (peers.length >= 2) {
+        return `碎片集群：与 ${peers.map(e => e.id).join(', ')} 同 type+tags 且 body 均 <100 字符，建议合并`;
+      }
+      return null;
+    },
+  },
+
+  // D4: 成熟度健康
+  {
+    name: 'promotion-blocked',
+    label: 'promotion 受阻',
+    severity: 'medium',
+    action: 'flag',
+    scope: 'all',
+    detect: (entry, ctx) => {
+      if (entry.maturity !== 'draft') return null;
+      const created = new Date(entry.created);
+      const daysSinceCreated = (Date.now() - created.getTime()) / (1000 * 60 * 60 * 24);
+      if (daysSinceCreated > ctx.promotionBlockDays && !entry.lastReferenced) {
+        return `draft 已 ${Math.floor(daysSinceCreated)} 天未被引用`;
+      }
+      return null;
+    },
+  },
+  {
+    name: 'orphan-draft',
+    label: '孤儿 draft',
+    severity: 'low',
+    action: 'flag',
+    scope: 'all',
+    detect: (entry) => {
+      if (entry.maturity !== 'draft') return null;
+      if (entry.contributors.length === 0 && entry.projects.length === 0 && genuineRefs(entry.referencedBy).length === 0) {
+        return `draft 无贡献者/项目/引用`;
+      }
+      return null;
+    },
+  },
+
+  // D5: 新鲜度
+  {
+    name: 'stale-entry',
+    label: '过期条目',
+    severity: 'medium',
+    action: 'flag',
+    scope: 'active',
+    detect: (entry, ctx) => {
+      const lastRef = entry.lastReferenced || entry.created;
+      if (!lastRef) return null;
+      const daysSinceRef = (Date.now() - new Date(lastRef).getTime()) / (1000 * 60 * 60 * 24);
+      if (daysSinceRef > ctx.staleDays) {
+        return `超过 ${Math.floor(daysSinceRef)} 天未引用 (阈值 ${ctx.staleDays})`;
+      }
+      return null;
+    },
+  },
+
+  // D2b: 领域相关性 — 检测已废弃领域的残留条目
+  {
+    name: 'deprecated-domain',
+    label: '废弃领域残留',
+    severity: 'high',
+    action: 'archive',
+    scope: 'active',
+    detect: (entry) => {
+      const tags = (entry.tags ?? []).map(t => t.toLowerCase());
+      // Tag-level: "pipeline" tag is deprecated (Studio Pipeline superseded by Agent Network)
+      if (tags.includes('pipeline')) {
+        return `标签 "pipeline" 属于已废弃领域（已被 Agent Network 取代）`;
+      }
+      // Title-level: strong domain-specific terms
+      const title = entry.title || '';
+      if (/pipeline|管线|GoalExecution|DeployAgent|Integration step/i.test(title)) {
+        return `标题引用已废弃领域: "${title}"`;
+      }
+      return null;
+    },
+  },
+];
+
+/** 规则 label 正本表（#109，ADR-0002 定义即注册）：派生自 perEntryRules，与规则键集编译期闭环，CLI 展示层直接消费 */
+export const AUDIT_RULE_LABELS: Record<AuditRuleName, string> = Object.fromEntries(
+  perEntryRules.map(r => [r.name, r.label])
+) as Record<AuditRuleName, string>;
+
+// ── Scoring ───────────────────────────────────────────────
+
+/** 阈值缺省落点（引擎与纯打分共用同一份兜底） */
+export function resolveThresholds(options: AuditOptions = {}): AuditContext {
+  return {
+    shortContentThreshold: options.shortContentThreshold ?? DEFAULT_SHORT_CONTENT_THRESHOLD,
+    staleDays: options.staleDays ?? DEFAULT_STALE_DAYS,
+    promotionBlockDays: options.promotionBlockDays ?? DEFAULT_PROMOTION_BLOCK_DAYS,
+  };
+}
+
+/** 按 scope 决定是否评估：active 规则对 archived 条目不判定（人口过滤唯一落点） */
+function ruleDetail(rule: AuditRule, entry: KnowledgeEntry, ctx: AuditContext): string | null {
+  if (rule.scope === 'active' && entry.maturity === 'archived') return null;
+  return rule.detect(entry, ctx);
+}
+
+/**
+ * 逐条目跑 perEntryRules（#111 收口，#134 纯化）：validate（单条目）、run（全量）与 autoFix 重扫共用。
+ * `population` = 跨条目规则（标题重复 / 碎片集群）的对照集合；不传 = 单条目入库模式，跨条目规则不判定。
+ */
+export function scanEntries(
+  entries: KnowledgeEntry[],
+  options: AuditOptions,
+  population?: KnowledgeEntry[],
+): AuditIssue[] {
+  const ctx: AuditContext = { ...resolveThresholds(options), allEntries: population };
+  const issues: AuditIssue[] = [];
+  for (const entry of entries) {
+    for (const rule of perEntryRules) {
+      const detail = ruleDetail(rule, entry, ctx);
+      if (detail) {
+        issues.push({
+          rule: rule.name,
+          entryId: entry.id,
+          title: entry.title,
+          severity: rule.severity,
+          action: rule.action,
+          detail,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+/** 规则命中计数：未命中的规则也出零值键（报告面的规则集合与规则表编译期闭环） */
+export function summarizeIssues(issues: AuditIssue[]): Record<AuditRuleName, number> {
+  const summary = {} as Record<AuditRuleName, number>;
+  for (const rule of perEntryRules) summary[rule.name] = 0;
+  for (const issue of issues) summary[issue.rule]++;
+  return summary;
+}
+
+export function computeDimensions(
+  entries: KnowledgeEntry[],
+  issues: AuditIssue[],
+  env: AuditEnv = {},
+): AuditReport['dimensions'] {
+  const active = entries.filter(e => e.maturity !== 'archived');
+  const now = Date.now();
+
+  // D1: 结构完整性
+  const d1Issues = issues.filter(i => i.rule === 'frontmatter-missing');
+  const d1Score = entries.length === 0 ? 100 : Math.max(0, 100 - (d1Issues.length / entries.length) * 100);
+
+  // D2: 内容质量
+  const d2Rules: AuditRuleName[] = ['test-data-pollution', 'daily-audit-noise', 'event-noise', 'zero-content-proven', 'short-content', 'maturity-inflation', 'deprecated-domain'];
+  const d2Issues = issues.filter(i => d2Rules.includes(i.rule));
+  const d2Score = active.length === 0 ? 100 : Math.max(0, 100 - (d2Issues.length / active.length) * 100);
+
+  // D3: 去重有效性
+  const d3Rules: AuditRuleName[] = ['title-duplicate', 'source-refs-bloat', 'fragment-cluster'];
+  const d3Issues = issues.filter(i => d3Rules.includes(i.rule));
+  const d3Score = active.length === 0 ? 100 : Math.max(0, 100 - (d3Issues.length / active.length) * 100);
+
+  // D4: 成熟度健康
+  const d4Rules: AuditRuleName[] = ['promotion-blocked', 'orphan-draft'];
+  const d4Issues = issues.filter(i => d4Rules.includes(i.rule));
+  const byMaturity: Record<string, number> = {};
+  for (const e of entries) byMaturity[e.maturity] = (byMaturity[e.maturity] || 0) + 1;
+  const draftRatio = entries.length > 0 ? (byMaturity['draft'] || 0) / entries.length : 0;
+  const provenRatio = entries.length > 0 ? (byMaturity['proven'] || 0) / entries.length : 0;
+  // Penalize: draft >50% or proven <2% or proven >20% (test inflation)
+  let d4Penalty = d4Issues.length * 2;
+  if (draftRatio > 0.5) d4Penalty += 10;
+  if (provenRatio < 0.02 && entries.length > 20) d4Penalty += 5;
+  if (provenRatio > 0.2) d4Penalty += 5; // likely test inflation
+  const d4Score = entries.length === 0 ? 100 : Math.max(0, 100 - (d4Penalty / entries.length) * 100);
+
+  // D5: 新鲜度
+  const d5Issues = issues.filter(i => i.rule === 'stale-entry');
+  const ages = active.map(e => {
+    const lastRef = e.lastReferenced || e.created;
+    return lastRef ? (now - new Date(lastRef).getTime()) / (1000 * 60 * 60 * 24) : 999;
+  });
+  const avgAge = ages.length > 0 ? ages.reduce((a, b) => a + b, 0) / ages.length : 0;
+  const staleRatio = active.length > 0 ? d5Issues.length / active.length : 0;
+  const d5Score = active.length === 0 ? 100 : Math.max(0, 100 - (staleRatio * 100));
+
+  // D6: 飞轮验证 —— 指标计算唯一实现在 flywheel-metrics，本模块只做报告层映射
+  const metrics = evaluateFlywheel({
+    entries: active,
+    dailyConsumptionEvents: env.dailyConsumptionEvents ?? 0,
+  });
+
+  // Score: refCoverage * 50 + avgRefs * 20 + consumptionHitRate * 30
+  const d6Score = Math.min(100, Math.round(
+    metrics.refCoverage * 50 +
+    Math.min(metrics.avgRefs / 5, 1) * 20 +
+    metrics.consumptionHitRate * 30
+  ));
+
+  return {
+    structure: {
+      score: Math.round(d1Score),
+      issues: d1Issues.length,
+      details: { invalidEntries: d1Issues.length },
+    },
+    content: {
+      score: Math.round(d2Score),
+      issues: d2Issues.length,
+      details: {
+        testData: issues.filter(i => i.rule === 'test-data-pollution').length,
+        dailyAudit: issues.filter(i => i.rule === 'daily-audit-noise').length,
+        zeroContent: issues.filter(i => i.rule === 'zero-content-proven').length,
+        shortContent: issues.filter(i => i.rule === 'short-content').length,
+        maturityInflation: issues.filter(i => i.rule === 'maturity-inflation').length,
+      },
+    },
+    dedup: {
+      score: Math.round(d3Score),
+      issues: d3Issues.length,
+      details: {
+        titleDuplicates: issues.filter(i => i.rule === 'title-duplicate').length,
+        sourceRefsBloat: issues.filter(i => i.rule === 'source-refs-bloat').length,
+      },
+    },
+    maturity: {
+      score: Math.round(d4Score),
+      issues: d4Issues.length,
+      details: {
+        draft: byMaturity['draft'] || 0,
+        verified: byMaturity['verified'] || 0,
+        proven: byMaturity['proven'] || 0,
+        archived: byMaturity['archived'] || 0,
+        draftRatio: Math.round(draftRatio * 100),
+        provenRatio: Math.round(provenRatio * 100),
+        promotionBlocked: issues.filter(i => i.rule === 'promotion-blocked').length,
+      },
+    },
+    freshness: {
+      score: Math.round(d5Score),
+      issues: d5Issues.length,
+      details: {
+        avgAgeDays: Math.round(avgAge),
+        staleEntries: d5Issues.length,
+        staleRatio: Math.round(staleRatio * 100),
+      },
+    },
+    flywheel: {
+      score: d6Score,
+      issues: 0,
+      details: {
+        activeEntries: metrics.activeEntries,
+        entriesWithRefs: metrics.entriesWithRefs,
+        refCoverage: Math.round(metrics.refCoverage * 100),
+        avgRefCount: Math.round(metrics.avgRefs * 10) / 10,
+        dailyConsumptionEvents: metrics.dailyConsumptionEvents,
+        consumptionHitRate: Math.round(metrics.consumptionHitRate * 100),
+      },
+    },
+    incremental: computeIncremental(env.survival),
+  };
+}
+
+export function computeIncremental(survival?: SnapshotSurvival): DimensionMetrics {
+  if (!survival) {
+    return { score: 100, issues: 0, details: { note: 'no 30d snapshot available' } };
+  }
+  // Score = survival rate directly (80% target → 80/100)
+  return {
+    score: survival.rate,
+    issues: survival.total - survival.survived,
+    details: {
+      survivalRate: survival.rate,
+      survived: survival.survived,
+      total: survival.total,
+      snapshotDate: survival.snapshotDate,
+    },
+  };
+}
+
+export function calculateHealthScore(entries: KnowledgeEntry[], issues: AuditIssue[]): number {
+  if (entries.length === 0) return 100;
+
+  const penalty = issues.reduce((sum, issue) => {
+    switch (issue.severity) {
+      case 'critical': return sum + 10;
+      case 'high': return sum + 5;
+      case 'medium': return sum + 2;
+      case 'low': return sum + 1;
+      default: return sum;
+    }
+  }, 0);
+
+  const maxPenalty = entries.length * 10;
+  return Math.max(0, 100 - Math.round((penalty / Math.max(maxPenalty, 1)) * 100));
+}