@dommaker/harness 0.13.0 → 0.13.2

package/src/knowledge/lint.ts

@@ -0,0 +1,360 @@
+/**
+ * 知识库 Lint（健康检查）
+ *
+ * 检查项：
+ * - 索引不一致（自动修复）
+ * - 孤儿条目（无引用、无验证）
+ * - 矛盾检测（同主题相反结论）
+ * - 过时检测（6 月未引用的 draft）
+ * - 重复/相似条目
+ * - 成熟度衰减
+ */
+
+import { KnowledgeStore } from './store';
+import { ReferenceTracker } from './reference-tracker';
+import type { KnowledgeEntry, LintIssue, LintIssueType, MaturityLevel } from './types';
+
+export interface LintReport {
+  timestamp: string;
+  totalEntries: number;
+  issues: LintIssue[];
+  fixed: number;
+  summary: Record<LintIssueType, number>;
+}
+
+export class KnowledgeLinter {
+  private store: KnowledgeStore;
+  private tracker: ReferenceTracker;
+
+  constructor(store: KnowledgeStore, tracker: ReferenceTracker) {
+    this.store = store;
+    this.tracker = tracker;
+  }
+
+  /**
+   * 执行完整 Lint 检查
+   */
+  run(autoFix: boolean = false): LintReport {
+    const entries = this.store.list({ excludeArchived: false });
+    const issues: LintIssue[] = [];
+
+    // 各项检查
+    issues.push(...this.checkIndexConsistency(entries));
+    issues.push(...this.checkOrphans(entries));
+    issues.push(...this.checkOutdated(entries));
+    issues.push(...this.checkDuplicates(entries));
+    issues.push(...this.checkContradictions(entries));
+
+    // 自动修复
+    let fixed = 0;
+    if (autoFix) {
+      fixed = this.autoFix(issues);
+    }
+
+    // 统计
+    const summary: Record<LintIssueType, number> = {
+      orphan: 0,
+      contradiction: 0,
+      outdated: 0,
+      duplicate: 0,
+      index_inconsistent: 0,
+    };
+    for (const issue of issues) {
+      summary[issue.type]++;
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      totalEntries: entries.length,
+      issues,
+      fixed,
+      summary,
+    };
+  }
+
+  /**
+   * 检查索引一致性
+   */
+  checkIndexConsistency(entries: KnowledgeEntry[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+    const index = this.store['readIndex']();
+
+    // 检查索引中的条目是否都有对应文件
+    for (const indexEntry of index) {
+      const fileEntry = this.store.get(indexEntry.id);
+      if (!fileEntry) {
+        issues.push({
+          type: 'index_inconsistent',
+          entryId: indexEntry.id,
+          severity: 'medium',
+          description: `索引条目 ${indexEntry.id} 无对应文件`,
+          suggestion: '从索引中移除或重建索引',
+        });
+      }
+    }
+
+    // 检查磁盘上的文件是否都在索引中
+    const indexIds = new Set(index.map(e => e.id));
+    const diskEntries = this.store['readEntriesFromDisk']();
+    for (const entry of diskEntries) {
+      if (!indexIds.has(entry.id)) {
+        issues.push({
+          type: 'index_inconsistent',
+          entryId: entry.id,
+          severity: 'medium',
+          description: `条目 ${entry.id} 不在索引中`,
+          suggestion: '重建索引',
+        });
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * 检查孤儿条目（无引用、无验证）
+   */
+  checkOrphans(entries: KnowledgeEntry[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+
+      const refs = this.tracker.getReferencesForEntry(entry.id);
+      const hasReferences = refs.length > 0;
+      const hasContributors = entry.contributors.length > 0;
+      const hasProjects = entry.projects.length > 0;
+
+      if (!hasReferences && !hasContributors && !hasProjects && entry.maturity === 'draft') {
+        issues.push({
+          type: 'orphan',
+          entryId: entry.id,
+          severity: 'low',
+          description: `条目 ${entry.id} (${entry.title}) 无引用、无贡献者、无项目验证`,
+          suggestion: '考虑归档或标记为需要验证',
+        });
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * 检查过时条目（6 月未引用的 draft）
+   */
+  checkOutdated(entries: KnowledgeEntry[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+    const sixMonthsAgo = new Date();
+    sixMonthsAgo.setMonth(sixMonthsAgo.getMonth() - 6);
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+
+      const lastRef = entry.lastReferenced ? new Date(entry.lastReferenced) : null;
+      const created = new Date(entry.created);
+      const relevantDate = lastRef || created;
+
+      if (relevantDate < sixMonthsAgo && entry.maturity === 'draft') {
+        issues.push({
+          type: 'outdated',
+          entryId: entry.id,
+          severity: 'medium',
+          description: `条目 ${entry.id} (${entry.title}) 超过 6 个月未引用且为 draft`,
+          suggestion: '考虑归档或提升成熟度',
+        });
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * 检查重复/相似条目
+   */
+  checkDuplicates(entries: KnowledgeEntry[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+    const seen = new Map<string, KnowledgeEntry[]>();
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+
+      // 基于 title + type 去重（大小写不敏感）
+      const key = `${entry.type}:${entry.title.toLowerCase().trim()}`;
+      const existing = seen.get(key) || [];
+      existing.push(entry);
+      seen.set(key, existing);
+    }
+
+    for (const [key, group] of seen) {
+      if (group.length > 1) {
+        for (const entry of group) {
+          issues.push({
+            type: 'duplicate',
+            entryId: entry.id,
+            severity: 'low',
+            description: `条目 ${entry.id} (${entry.title}) 与同类型同标题的其他条目重复`,
+            suggestion: `考虑合并: ${group.map(e => e.id).join(', ')}`,
+          });
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * 检查矛盾（同主题相反结论）
+   *
+   * 简单实现：同 tag 组合下成熟度冲突
+   */
+  checkContradictions(entries: KnowledgeEntry[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+    const byTagGroup = new Map<string, KnowledgeEntry[]>();
+
+    // 按 tag 组合分组
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+      if (entry.tags.length === 0) continue;
+
+      const tagKey = entry.tags.sort().join(',');
+      const existing = byTagGroup.get(tagKey) || [];
+      existing.push(entry);
+      byTagGroup.set(tagKey, existing);
+    }
+
+    // 检查同 tag 组合内是否有成熟度差异大的条目
+    for (const [tagKey, group] of byTagGroup) {
+      if (group.length < 2) continue;
+
+      const maturityOrder: MaturityLevel[] = ['draft', 'verified', 'proven'];
+      const levels = group.map(e => maturityOrder.indexOf(e.maturity));
+      const maxLevel = Math.max(...levels);
+      const minLevel = Math.min(...levels);
+
+      // 成熟度差异 >= 2 级（如 proven vs draft）
+      if (maxLevel - minLevel >= 2) {
+        const lowEntries = group.filter((_, i) => levels[i] === minLevel);
+        for (const entry of lowEntries) {
+          issues.push({
+            type: 'contradiction',
+            entryId: entry.id,
+            severity: 'high',
+            description: `条目 ${entry.id} (${entry.title}) 与同标签的高成熟度条目存在潜在矛盾`,
+            suggestion: `审查标签 [${tagKey}] 下的所有条目，确认或更新`,
+          });
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * P2.5: Validate a single entry before ingestion.
+   * Returns a list of issues (empty = valid, ready to ingest).
+   *
+   * Checks:
+   * - Content too short (< 20 chars) → reject
+   * - Title too vague (common stop words only) → flag
+   * - Contradicts a proven entry with same tags → reject
+   * - Near-duplicate of existing entry (title similarity > 80%) → flag merge
+   */
+  validateEntry(entry: { title: string; content: string; tags: string[]; type: string }): LintIssue[] {
+    const issues: LintIssue[] = [];
+
+    // Content too short
+    if ((entry.content || '').length < 20) {
+      issues.push({
+        type: 'orphan',
+        severity: 'high',
+        description: `Content too short (${entry.content.length} chars). LLM may have hallucinated.`,
+        suggestion: 'Reject — re-extract with better prompt or discard.',
+      });
+    }
+
+    // Title too vague
+    const vaguePatterns = /^(错误|失败|问题|异常|bug|error|fail|issue|problem|unknown|untitled)$/i;
+    if (vaguePatterns.test(entry.title.trim())) {
+      issues.push({
+        type: 'contradiction',
+        severity: 'medium',
+        description: `Title "${entry.title}" is too vague to be useful.`,
+        suggestion: 'Re-extract with root cause in title, not symptom.',
+      });
+    }
+
+    // Contradicts proven entry with same tags
+    if (entry.tags.length > 0) {
+      const allEntries = this.store.list({ excludeArchived: false });
+      for (const existing of allEntries) {
+        if (existing.maturity !== 'proven') continue;
+        if (existing.type !== entry.type) continue;
+        const sharedTags = entry.tags.filter(t => existing.tags.includes(t));
+        if (sharedTags.length >= 2) {
+          issues.push({
+            type: 'contradiction',
+            entryId: existing.id,
+            severity: 'high',
+            description: `New entry "${entry.title}" shares tags [${sharedTags.join(', ')}] with proven entry "${existing.title}" (${existing.id}). Contradiction risk.`,
+            suggestion: `Review against ${existing.id}. If aligned, merge. If contradictory, flag for human review.`,
+          });
+        }
+      }
+    }
+
+    // Near-duplicate title check (simple: case-insensitive substring match)
+    if (entry.title.length > 10) {
+      const allEntries = this.store.list({ excludeArchived: false });
+      for (const existing of allEntries) {
+        if (existing.id === entry.title) continue; // not same entry (entry doesn't have id yet)
+        const existingTitle = existing.title.toLowerCase();
+        const newTitle = entry.title.toLowerCase();
+        if (existingTitle === newTitle) {
+          issues.push({
+            type: 'duplicate',
+            entryId: existing.id,
+            severity: 'medium',
+            description: `Exact title match with existing entry "${existing.title}" (${existing.id}).`,
+            suggestion: `Merge into ${existing.id} instead of creating duplicate.`,
+          });
+          break;
+        }
+        // Check high similarity (either title contains the other)
+        if (existingTitle.includes(newTitle) || newTitle.includes(existingTitle)) {
+          issues.push({
+            type: 'duplicate',
+            entryId: existing.id,
+            severity: 'low',
+            description: `Title similarity with existing "${existing.title}" (${existing.id}).`,
+            suggestion: `Consider merging with ${existing.id}.`,
+          });
+          break;
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * 自动修复可修复的问题
+   */
+  private autoFix(issues: LintIssue[]): number {
+    let fixed = 0;
+
+    for (const issue of issues) {
+      if (issue.type === 'index_inconsistent') {
+        this.store.rebuildIndex();
+        fixed++;
+        break; // rebuildIndex 修复所有索引问题
+      }
+
+      if (issue.type === 'outdated' && issue.entryId) {
+        this.store.update(issue.entryId, { maturity: 'archived' });
+        fixed++;
+      }
+    }
+
+    return fixed;
+  }
+}

package/src/knowledge/query.ts

@@ -0,0 +1,150 @@
+/**
+ * Knowledge Query Engine
+ *
+ * Budget-aware query layer over KnowledgeStore.
+ * Supports filtering, sorting by maturity, and result caching.
+ */
+
+import type {
+  KnowledgeEntry,
+  KnowledgeType,
+  MaturityLevel,
+  StorageLayer,
+  QueryBudget,
+  QueryResult,
+  QueryFilter,
+  IndexEntry,
+} from './types';
+import { KnowledgeStore } from './store';
+import { KnowledgeLifecycle } from './lifecycle';
+
+// ── Constants ──────────────────────────────────────────────
+
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const MATURITY_RANK: Record<MaturityLevel, number> = {
+  proven: 3,
+  verified: 2,
+  draft: 1,
+  archived: 0,
+};
+
+// ── Cache ──────────────────────────────────────────────────
+
+interface CacheEntry {
+  result: QueryResult;
+  timestamp: number;
+}
+
+// ── Query Engine ───────────────────────────────────────────
+
+export class KnowledgeQuery {
+  private store: KnowledgeStore;
+  private lifecycle: KnowledgeLifecycle;
+  private cache = new Map<string, CacheEntry>();
+
+  constructor(store: KnowledgeStore, lifecycle?: KnowledgeLifecycle) {
+    this.store = store;
+    this.lifecycle = lifecycle || new KnowledgeLifecycle(store);
+  }
+
+  /**
+   * Query knowledge entries within a token budget.
+   *
+   * - Filters by budget.focusTypes (and optional extra filter)
+   * - Sorts: maturity desc → lastReferenced desc
+   * - Truncates to budget.maxEntries and budget.maxTokens
+   * - Caches results per phase+budget key (TTL 5 min)
+   */
+  query(budget: QueryBudget, filter?: QueryFilter): QueryResult {
+    const cacheKey = this.cacheKey(budget, filter);
+    const cached = this.cache.get(cacheKey);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+      return { ...cached.result, fromCache: true };
+    }
+
+    // Merge focusTypes from budget into filter
+    const mergedFilter: QueryFilter = {
+      ...filter,
+      types: budget.focusTypes.length > 0 ? budget.focusTypes : filter?.types,
+      excludeArchived: filter?.excludeArchived ?? true,
+    };
+
+    const candidates = this.store.list(mergedFilter);
+    const sorted = this.sortEntries(candidates);
+    const { entries, tokensUsed, truncated } = this.applyBudget(sorted, budget);
+
+    const result: QueryResult = { entries, tokensUsed, truncated, fromCache: false };
+    this.cache.set(cacheKey, { result, timestamp: Date.now() });
+
+    // P2a: Record references for all returned entries (drives maturity ladder)
+    for (const entry of entries) {
+      try {
+        this.lifecycle.recordReference(entry.id);
+      } catch { /* non-blocking */ }
+    }
+
+    return result;
+  }
+
+  /**
+   * Estimate token count for a piece of text.
+   * Rule of thumb: 1 CJK char ≈ 2 tokens, 1 ASCII char ≈ 0.25 tokens.
+   */
+  estimateTokens(text: string): number {
+    let tokens = 0;
+    for (const ch of text) {
+      // CJK Unified Ideographs + common CJK ranges
+      if (/[一-鿿㐀-䶿豈-﫿]/.test(ch)) {
+        tokens += 2;
+      } else {
+        tokens += 0.25;
+      }
+    }
+    return Math.ceil(tokens);
+  }
+
+  /** Clear the query cache. */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  // ── Internal ───────────────────────────────────────────────
+
+  private sortEntries(entries: KnowledgeEntry[]): KnowledgeEntry[] {
+    return [...entries].sort((a, b) => {
+      // Primary: maturity descending
+      const maturityDiff = MATURITY_RANK[b.maturity] - MATURITY_RANK[a.maturity];
+      if (maturityDiff !== 0) return maturityDiff;
+      // Secondary: lastReferenced descending (most recently used first)
+      return (b.lastReferenced || '').localeCompare(a.lastReferenced || '');
+    });
+  }
+
+  private applyBudget(
+    entries: KnowledgeEntry[],
+    budget: QueryBudget,
+  ): { entries: KnowledgeEntry[]; tokensUsed: number; truncated: boolean } {
+    const result: KnowledgeEntry[] = [];
+    let tokensUsed = 0;
+
+    for (const entry of entries) {
+      if (result.length >= budget.maxEntries) break;
+
+      const entryTokens = this.estimateTokens(entry.content) + this.estimateTokens(entry.title);
+      if (tokensUsed + entryTokens > budget.maxTokens) break;
+
+      result.push(entry);
+      tokensUsed += entryTokens;
+    }
+
+    return {
+      entries: result,
+      tokensUsed,
+      truncated: result.length < entries.length,
+    };
+  }
+
+  private cacheKey(budget: QueryBudget, filter?: QueryFilter): string {
+    return JSON.stringify({ budget, filter });
+  }
+}

package/src/knowledge/reference-tracker.ts

@@ -0,0 +1,99 @@
+/**
+ * Reference Tracker
+ *
+ * Tracks which decisions reference which knowledge entries.
+ * Storage: append-only JSONL at .harness/knowledge/references.jsonl
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ReferenceRecord } from './types';
+import { KnowledgeStore } from './store';
+
+const REFERENCES_FILE = 'references.jsonl';
+
+// ── Reference Tracker ──────────────────────────────────────
+
+export class ReferenceTracker {
+  private filePath: string;
+  private store: KnowledgeStore;
+
+  constructor(store: KnowledgeStore, baseDir?: string) {
+    const dir = baseDir || '.harness/knowledge';
+    this.filePath = path.join(dir, REFERENCES_FILE);
+    this.store = store;
+  }
+
+  /**
+   * Record that a decision referenced a set of knowledge entries.
+   */
+  record(decisionId: string, entryIds: string[]): void {
+    const record: ReferenceRecord = {
+      decisionId,
+      entryIds,
+      timestamp: new Date().toISOString(),
+    };
+    fs.appendFileSync(this.filePath, JSON.stringify(record) + '\n', 'utf-8');
+  }
+
+  /**
+   * Get all decision IDs that referenced a given entry.
+   */
+  getReferencesForEntry(entryId: string): string[] {
+    const records = this.readAll();
+    return records
+      .filter(r => r.entryIds.includes(entryId))
+      .map(r => r.decisionId);
+  }
+
+  /**
+   * Get all entry IDs referenced by a given decision.
+   */
+  getReferencesForDecision(decisionId: string): string[] {
+    const records = this.readAll();
+    const record = records.find(r => r.decisionId === decisionId);
+    return record ? record.entryIds : [];
+  }
+
+  /**
+   * Batch-update referencedBy fields on all knowledge entries.
+   * Scans all reference records and populates entry.referencedBy.
+   */
+  updateReferencedBy(): void {
+    const records = this.readAll();
+    const entryToDecisions = new Map<string, Set<string>>();
+
+    for (const record of records) {
+      for (const entryId of record.entryIds) {
+        if (!entryToDecisions.has(entryId)) {
+          entryToDecisions.set(entryId, new Set());
+        }
+        entryToDecisions.get(entryId)!.add(record.decisionId);
+      }
+    }
+
+    for (const [entryId, decisions] of entryToDecisions) {
+      const entry = this.store.get(entryId);
+      if (entry) {
+        this.store.update(entryId, {
+          referencedBy: [...decisions],
+        });
+      }
+    }
+  }
+
+  // ── Internal ───────────────────────────────────────────────
+
+  private readAll(): ReferenceRecord[] {
+    if (!fs.existsSync(this.filePath)) return [];
+    try {
+      const raw = fs.readFileSync(this.filePath, 'utf-8');
+      return raw
+        .split('\n')
+        .filter(line => line.trim())
+        .map(line => JSON.parse(line) as ReferenceRecord);
+    } catch {
+      return [];
+    }
+  }
+}