@dommaker/harness 0.13.0 → 0.13.2

package/src/knowledge/store.ts

@@ -0,0 +1,264 @@
+/**
+ * Knowledge Store
+ *
+ * File-based storage for knowledge entries.
+ * Each entry is a markdown file with YAML frontmatter.
+ * An index.json provides fast listing without reading all files.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import type { KnowledgeEntry, IndexEntry, QueryFilter, StorageLayer } from './types';
+
+const DEFAULT_DIR = '.harness/knowledge';
+const INDEX_FILE = 'index.json';
+
+interface StoreConfig {
+  baseDir: string;
+}
+
+const DEFAULT_CONFIG: StoreConfig = {
+  baseDir: DEFAULT_DIR,
+};
+
+export class KnowledgeStore {
+  private baseDir: string;
+
+  constructor(config?: Partial<StoreConfig>) {
+    this.baseDir = config?.baseDir || DEFAULT_CONFIG.baseDir;
+    this.ensureDirectory();
+  }
+
+  // ── CRUD ─────────────────────────────────────────────────
+
+  get(id: string): KnowledgeEntry | undefined {
+    const filePath = this.findFile(id);
+    if (!filePath) return undefined;
+    return this.readFile(filePath);
+  }
+
+  list(filter?: QueryFilter): KnowledgeEntry[] {
+    const index = this.readIndex();
+    const effectiveFilter: QueryFilter = { excludeArchived: true, ...filter };
+    let entries = index.filter(e => this.matchesFilter(e, effectiveFilter));
+
+    return entries.map(idx => {
+      const full = this.get(idx.id);
+      return full || this.indexToEntry(idx);
+    });
+  }
+
+  save(entry: KnowledgeEntry): void {
+    const filePath = this.entryPath(entry);
+    const frontmatter = this.toFrontmatter(entry);
+    const content = `---\n${frontmatter}---\n\n${entry.content}`;
+    fs.writeFileSync(filePath, content, 'utf-8');
+    this.updateIndexEntry(entry);
+  }
+
+  delete(id: string): boolean {
+    const filePath = this.findFile(id);
+    if (!filePath) return false;
+    fs.unlinkSync(filePath);
+    this.removeFromIndex(id);
+    return true;
+  }
+
+  update(id: string, partial: Partial<KnowledgeEntry>): KnowledgeEntry | undefined {
+    const existing = this.get(id);
+    if (!existing) return undefined;
+    const updated = { ...existing, ...partial, id };
+    this.save(updated);
+    return updated;
+  }
+
+  // ── Index ────────────────────────────────────────────────
+
+  rebuildIndex(): void {
+    const files = this.listFiles();
+    const entries: IndexEntry[] = [];
+    for (const file of files) {
+      const entry = this.readFile(file);
+      if (entry) {
+        entries.push(this.toIndexEntry(entry));
+      }
+    }
+    this.writeIndex(entries);
+  }
+
+  /**
+   * 从磁盘读取所有条目（不依赖索引）
+   * 用于 Lint 检查索引一致性
+   */
+  readEntriesFromDisk(): KnowledgeEntry[] {
+    const files = this.listFiles();
+    const entries: KnowledgeEntry[] = [];
+    for (const file of files) {
+      const entry = this.readFile(file);
+      if (entry) {
+        entries.push(entry);
+      }
+    }
+    return entries;
+  }
+
+  // ── Internal ─────────────────────────────────────────────
+
+  private ensureDirectory(): void {
+    if (!fs.existsSync(this.baseDir)) {
+      fs.mkdirSync(this.baseDir, { recursive: true });
+    }
+  }
+
+  private entryPath(entry: KnowledgeEntry): string {
+    const safeType = path.basename(entry.type);
+    const safeId = path.basename(entry.id);
+    return path.join(this.baseDir, `${safeType}-${safeId}.md`);
+  }
+
+  private findFile(id: string): string | undefined {
+    const files = this.listFiles();
+    return files.find(f => path.basename(f).includes(`-${id}.md`));
+  }
+
+  private listFiles(): string[] {
+    if (!fs.existsSync(this.baseDir)) return [];
+    return fs.readdirSync(this.baseDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => path.join(this.baseDir, f));
+  }
+
+  private readFile(filePath: string): KnowledgeEntry | undefined {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      return this.parseFile(raw, filePath);
+    } catch {
+      return undefined;
+    }
+  }
+
+  private parseFile(raw: string, filePath: string): KnowledgeEntry | undefined {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+    if (!match) return undefined;
+
+    const meta = yaml.load(match[1]) as Record<string, unknown>;
+    const content = match[2];
+
+    return {
+      id: meta.id as string || path.basename(filePath, '.md'),
+      type: meta.type as KnowledgeEntry['type'],
+      title: meta.title as string,
+      content,
+      maturity: meta.maturity as KnowledgeEntry['maturity'],
+      layer: meta.layer as KnowledgeEntry['layer'],
+      created: meta.created as string,
+      lastReferenced: meta.lastReferenced as string || '',
+      contributors: (meta.contributors as string[]) || [],
+      projects: (meta.projects as string[]) || [],
+      tags: (meta.tags as string[]) || [],
+      applicablePhases: (meta.applicablePhases as string[]) || [],
+      sourceReferences: (meta.sourceReferences as KnowledgeEntry['sourceReferences']) || [],
+      referencedBy: (meta.referencedBy as string[]) || [],
+      decayAt: meta.decayAt as string | undefined,
+    };
+  }
+
+  private toFrontmatter(entry: KnowledgeEntry): string {
+    const meta: Record<string, unknown> = {
+      id: entry.id,
+      type: entry.type,
+      title: entry.title,
+      maturity: entry.maturity,
+      layer: entry.layer,
+      created: entry.created,
+      lastReferenced: entry.lastReferenced,
+      contributors: entry.contributors,
+      projects: entry.projects,
+      tags: entry.tags,
+      applicablePhases: entry.applicablePhases,
+      sourceReferences: entry.sourceReferences,
+      referencedBy: entry.referencedBy,
+    };
+    if (entry.decayAt) meta.decayAt = entry.decayAt;
+    return yaml.dump(meta, { lineWidth: 120 });
+  }
+
+  private toIndexEntry(entry: KnowledgeEntry): IndexEntry {
+    return {
+      id: entry.id,
+      type: entry.type,
+      title: entry.title,
+      maturity: entry.maturity,
+      layer: entry.layer,
+      tags: entry.tags,
+      applicablePhases: entry.applicablePhases,
+      lastReferenced: entry.lastReferenced,
+      created: entry.created,
+    };
+  }
+
+  private indexToEntry(idx: IndexEntry): KnowledgeEntry {
+    return {
+      id: idx.id,
+      type: idx.type,
+      title: idx.title,
+      content: '',
+      maturity: idx.maturity,
+      layer: idx.layer,
+      created: idx.created,
+      lastReferenced: idx.lastReferenced,
+      contributors: [],
+      projects: [],
+      tags: idx.tags,
+      applicablePhases: idx.applicablePhases,
+      sourceReferences: [],
+      referencedBy: [],
+    };
+  }
+
+  private matchesFilter(entry: IndexEntry, filter: QueryFilter): boolean {
+    if (filter.types && filter.types.length > 0 && !filter.types.includes(entry.type)) return false;
+    if (filter.maturity && filter.maturity.length > 0 && !filter.maturity.includes(entry.maturity)) return false;
+    if (filter.layers && filter.layers.length > 0 && !filter.layers.includes(entry.layer)) return false;
+    if (filter.tags && filter.tags.length > 0 && !filter.tags.some(t => entry.tags.includes(t))) return false;
+    if (filter.applicablePhases && filter.applicablePhases.length > 0 && !filter.applicablePhases.some(p => entry.applicablePhases.includes(p))) return false;
+    if (filter.excludeArchived !== false && entry.maturity === 'archived') return false;
+    return true;
+  }
+
+  // ── Index I/O ────────────────────────────────────────────
+
+  private readIndex(): IndexEntry[] {
+    const indexPath = path.join(this.baseDir, INDEX_FILE);
+    if (!fs.existsSync(indexPath)) return [];
+    try {
+      const raw = fs.readFileSync(indexPath, 'utf-8');
+      return JSON.parse(raw) as IndexEntry[];
+    } catch {
+      return [];
+    }
+  }
+
+  private writeIndex(entries: IndexEntry[]): void {
+    const indexPath = path.join(this.baseDir, INDEX_FILE);
+    fs.writeFileSync(indexPath, JSON.stringify(entries, null, 2), 'utf-8');
+  }
+
+  private updateIndexEntry(entry: KnowledgeEntry): void {
+    const index = this.readIndex();
+    const idx = index.findIndex(e => e.id === entry.id);
+    const indexEntry = this.toIndexEntry(entry);
+    if (idx >= 0) {
+      index[idx] = indexEntry;
+    } else {
+      index.push(indexEntry);
+    }
+    this.writeIndex(index);
+  }
+
+  private removeFromIndex(id: string): void {
+    const index = this.readIndex().filter(e => e.id !== id);
+    this.writeIndex(index);
+  }
+}

package/src/knowledge/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Knowledge engine type definitions.
+ *
+ * Three orthogonal dimensions:
+ * - StorageLayer: where knowledge lives (shared boundary)
+ * - KnowledgeType: what knowledge describes (MECE)
+ * - MaturityLevel: how trusted (lifecycle)
+ */
+
+// ── Dimensions ──────────────────────────────────────────────
+
+export type KnowledgeType = 'model' | 'decision' | 'guideline' | 'pitfall' | 'process' | 'architecture';
+
+export type MaturityLevel = 'draft' | 'verified' | 'proven' | 'archived';
+
+export type StorageLayer = 'personal' | 'team' | 'tech' | 'domain' | 'project' | 'system';
+
+// ── Core Entry ──────────────────────────────────────────────
+
+export interface KnowledgeEntry {
+  id: string;
+  type: KnowledgeType;
+  title: string;
+  content: string;
+  maturity: MaturityLevel;
+  layer: StorageLayer;
+  created: string;
+  lastReferenced: string;
+  contributors: string[];
+  projects: string[];
+  tags: string[];
+  applicablePhases: string[];
+  sourceReferences: SourceRef[];
+  referencedBy: string[];
+  decayAt?: string;
+}
+
+export interface SourceRef {
+  workflow?: string;
+  step?: string;
+  commit?: string;
+  timestamp: string;
+}
+
+// ── Query ───────────────────────────────────────────────────
+
+export interface KnowledgeReference {
+  id: string;
+  title: string;
+  usedIn: string;
+}
+
+export interface QueryBudget {
+  phase: string;
+  maxTokens: number;
+  maxEntries: number;
+  focusTypes: KnowledgeType[];
+}
+
+export interface QueryResult {
+  entries: KnowledgeEntry[];
+  tokensUsed: number;
+  truncated: boolean;
+  fromCache: boolean;
+}
+
+export interface QueryFilter {
+  types?: KnowledgeType[];
+  maturity?: MaturityLevel[];
+  layers?: StorageLayer[];
+  tags?: string[];
+  applicablePhases?: string[];
+  excludeArchived?: boolean;
+}
+
+// ── Lint ────────────────────────────────────────────────────
+
+export type LintIssueType = 'orphan' | 'contradiction' | 'outdated' | 'duplicate' | 'index_inconsistent';
+
+export interface LintIssue {
+  type: LintIssueType;
+  entryId?: string;
+  severity: 'low' | 'medium' | 'high';
+  description: string;
+  suggestion: string;
+}
+
+// ── Ingest ──────────────────────────────────────────────────
+
+export interface IngestOptions {
+  source: string;
+  layer: StorageLayer;
+  maturity?: MaturityLevel;
+  tags?: string[];
+  projects?: string[];
+}
+
+// ── Lifecycle ───────────────────────────────────────────────
+
+export interface MaturityChange {
+  entryId: string;
+  from: MaturityLevel;
+  to: MaturityLevel;
+  reason: string;
+}
+
+export interface DecayConfig {
+  provenDecayMonths: number;
+  verifiedDecayMonths: number;
+  draftDecayMonths: number;
+}
+
+export const DEFAULT_DECAY_CONFIG: DecayConfig = {
+  provenDecayMonths: 12,
+  verifiedDecayMonths: 6,
+  draftDecayMonths: 3,
+};
+
+// ── Reference ───────────────────────────────────────────────
+
+export interface ReferenceRecord {
+  decisionId: string;
+  entryIds: string[];
+  timestamp: string;
+}
+
+// ── Index ───────────────────────────────────────────────────
+
+export interface IndexEntry {
+  id: string;
+  type: KnowledgeType;
+  title: string;
+  maturity: MaturityLevel;
+  layer: StorageLayer;
+  tags: string[];
+  applicablePhases: string[];
+  lastReferenced: string;
+  created: string;
+}

package/src/llm/CONTEXT.md

@@ -0,0 +1,21 @@
+# llm/
+
+## 职责
+LLM 适配层：统一的 LLM 调用接口(Adapter 模式)，支持多模型切换。
+
+## 核心导出
+- `types.ts` — LLM 相关类型定义
+- `adapter.ts` — LLM Adapter: 统一调用接口
+
+## 依赖关系
+- 依赖 `src/types/` 公共类型
+- 被上层需要 LLM 调用的模块消费
+
+## 约定
+- Adapter 模式：统一接口屏蔽底层模型差异
+- 不直接依赖特定 LLM SDK
+- 类型定义与实现分离
+
+## 注意事项
+- 轻量模块，提供 LLM 调用抽象
+- 具体模型配置由环境变量/配置文件提供

package/src/llm/__tests__/adapter.test.ts

@@ -0,0 +1,172 @@
+/**
+ * LLM Adapter 测试
+ */
+
+import { createLLMAdapter, DefaultLLMAdapter } from '../adapter';
+import type { LLMAdapter, Message } from '../types';
+
+describe('LLM Adapter', () => {
+  describe('createLLMAdapter', () => {
+    it('应该创建默认适配器', () => {
+      const adapter = createLLMAdapter({ provider: 'openai' });
+      expect(adapter).toBeInstanceOf(DefaultLLMAdapter);
+    });
+
+    it('应该使用自定义适配器', () => {
+      const custom: LLMAdapter = {
+        complete: async () => 'custom',
+        chat: async () => 'custom',
+        streamChat: async function* () { yield 'custom'; },
+        summarize: async () => 'custom summary',
+        extract: async () => ({}),
+      };
+
+      const adapter = createLLMAdapter({
+        provider: 'custom',
+        customAdapter: custom,
+      });
+
+      expect(adapter).toBe(custom);
+    });
+  });
+
+  describe('DefaultLLMAdapter', () => {
+    let adapter: DefaultLLMAdapter;
+
+    beforeEach(() => {
+      adapter = new DefaultLLMAdapter({ provider: 'openai', model: 'gpt-4' });
+    });
+
+    describe('complete', () => {
+      it('应该抛出未实现错误', async () => {
+        await expect(adapter.complete('test')).rejects.toThrow('LLM complete 未实现');
+      });
+    });
+
+    describe('chat', () => {
+      it('应该抛出未实现错误', async () => {
+        await expect(adapter.chat([{ role: 'user', content: 'test' }])).rejects.toThrow('LLM chat 未实现');
+      });
+    });
+
+    describe('streamChat', () => {
+      it('应该抛出未实现错误', async () => {
+        const gen = adapter.streamChat([{ role: 'user', content: 'test' }]);
+        await expect(async () => {
+          for await (const _ of gen) { /* noop */ }
+        }).rejects.toThrow('LLM streamChat 未实现');
+      });
+    });
+
+    describe('summarize', () => {
+      it('应该提取用户目标', async () => {
+        const messages: Message[] = [
+          { role: 'user', content: '帮我修复登录 bug' },
+          { role: 'assistant', content: '好的，我来查看代码' },
+          { role: 'user', content: '问题出在 token 验证' },
+        ];
+
+        const summary = await adapter.summarize(messages, {
+          maxTokens: 200,
+          preserve: ['user_goals'],
+        });
+
+        expect(summary).toContain('用户目标');
+        expect(summary).toContain('登录 bug');
+      });
+
+      it('应该提取工具调用', async () => {
+        const messages: Message[] = [
+          { role: 'user', content: 'test' },
+          { role: 'tool', content: 'result 1' },
+          { role: 'tool', content: 'result 2' },
+        ];
+
+        const summary = await adapter.summarize(messages, {
+          maxTokens: 200,
+          preserve: ['tool_calls'],
+        });
+
+        expect(summary).toContain('工具调用');
+        expect(summary).toContain('2');
+      });
+
+      it('应该提取错误信息', async () => {
+        const messages: Message[] = [
+          { role: 'user', content: 'test' },
+          { role: 'assistant', content: 'Error: connection failed' },
+        ];
+
+        const summary = await adapter.summarize(messages, {
+          maxTokens: 200,
+          preserve: ['errors'],
+        });
+
+        expect(summary).toContain('错误');
+      });
+
+      it('应该提取决策', async () => {
+        const messages: Message[] = [
+          { role: 'user', content: '选择方案 A 还是方案 B？' },
+          { role: 'assistant', content: '决策：使用方案 A，因为性能更好' },
+        ];
+
+        const summary = await adapter.summarize(messages, {
+          maxTokens: 200,
+          preserve: ['decisions'],
+        });
+
+        expect(summary).toContain('决策');
+      });
+
+      it('应该限制长度', async () => {
+        const messages: Message[] = [
+          { role: 'user', content: 'x'.repeat(10000) },
+        ];
+
+        const summary = await adapter.summarize(messages, {
+          maxTokens: 100,
+          preserve: ['user_goals'],
+        });
+
+        expect(summary.length).toBeLessThanOrEqual(400); // 100 tokens * 4 chars
+      });
+    });
+
+    describe('extract', () => {
+      it('应该提取结构化数据', async () => {
+        const content = 'name: John\nage: 30\ncity: Beijing';
+        const result = await adapter.extract(content, {
+          name: 'string',
+          age: 'string',
+          city: 'string',
+        }) as Record<string, string>;
+
+        expect(result.name).toBe('John');
+        expect(result.age).toBe('30');
+        expect(result.city).toBe('Beijing');
+      });
+
+      it('应该处理缺失字段', async () => {
+        const content = 'name: John';
+        const result = await adapter.extract(content, {
+          name: 'string',
+          missing: 'string',
+        }) as Record<string, string>;
+
+        expect(result.name).toBe('John');
+        expect(result.missing).toBeUndefined();
+      });
+    });
+
+    describe('getters', () => {
+      it('应该返回 provider', () => {
+        expect(adapter.getProvider()).toBe('openai');
+      });
+
+      it('应该返回 model', () => {
+        expect(adapter.getModel()).toBe('gpt-4');
+      });
+    });
+  });
+});