@dommaker/harness 0.13.0 → 0.13.2

package/src/context/__tests__/token-pipeline.test.ts

@@ -0,0 +1,178 @@
+/**
+ * TokenPipeline 测试
+ */
+
+import { TokenPipeline } from '../token-pipeline';
+import type { ContextSource, TokenBudgetAllocation } from '../types';
+
+const defaultBudget: TokenBudgetAllocation = {
+  total: 8000,
+  systemPrompt: 1000,
+  toolDefinitions: 500,
+  knowledge: 600,
+  notes: 300,
+  history: 5600,
+};
+
+function makeSource(overrides: Partial<ContextSource> & { priority: number }): ContextSource {
+  return {
+    type: 'user_message',
+    id: `src-${Math.random().toString(36).slice(2, 8)}`,
+    content: 'test content',
+    ...overrides,
+  };
+}
+
+describe('TokenPipeline', () => {
+  let pipeline: TokenPipeline;
+
+  beforeEach(() => {
+    pipeline = new TokenPipeline();
+  });
+
+  describe('run', () => {
+    it('应该执行完整流水线', () => {
+      const input = {
+        sources: [
+          makeSource({ type: 'system_prompt', priority: 1, content: 'You are helpful.' }),
+          makeSource({ type: 'user_message', priority: 6, content: 'Hello' }),
+        ],
+        budget: defaultBudget,
+      };
+
+      const result = pipeline.run(input);
+      expect(result.prompt).toContain('You are helpful.');
+      expect(result.prompt).toContain('Hello');
+      expect(result.snapshot).toBeDefined();
+      expect(result.snapshot.totalTokens).toBeGreaterThan(0);
+    });
+
+    it('应该把 P1 放在开头，P6 放在结尾', () => {
+      const input = {
+        sources: [
+          makeSource({ type: 'user_message', priority: 6, content: 'USER_MSG' }),
+          makeSource({ type: 'system_prompt', priority: 1, content: 'SYSTEM' }),
+          makeSource({ type: 'knowledge', priority: 3, content: 'KNOWLEDGE' }),
+        ],
+        budget: defaultBudget,
+      };
+
+      const result = pipeline.run(input);
+      const prompt = result.prompt;
+      const sysIdx = prompt.indexOf('SYSTEM');
+      const knowIdx = prompt.indexOf('KNOWLEDGE');
+      const userIdx = prompt.indexOf('USER_MSG');
+
+      expect(sysIdx).toBeLessThan(knowIdx);
+      expect(knowIdx).toBeLessThan(userIdx);
+    });
+
+    it('应该生成 ContextUsageSnapshot', () => {
+      const input = {
+        sources: [
+          makeSource({ type: 'system_prompt', priority: 1, content: 'system' }),
+          makeSource({ type: 'tool_output', priority: 5, content: 'output' }),
+        ],
+        budget: defaultBudget,
+      };
+
+      const result = pipeline.run(input);
+      expect(result.snapshot.breakdown.systemPrompt).toBeGreaterThan(0);
+      expect(result.snapshot.timestamp).toBeDefined();
+    });
+  });
+
+  describe('collect', () => {
+    it('应该按 priority 分组', () => {
+      const sources = [
+        makeSource({ priority: 1, content: 'a' }),
+        makeSource({ priority: 3, content: 'b' }),
+        makeSource({ priority: 1, content: 'c' }),
+      ];
+
+      const groups = pipeline.collect(sources);
+      expect(groups.length).toBe(2);
+      expect(groups[0].priority).toBe(1);
+      expect(groups[0].sources.length).toBe(2);
+      expect(groups[1].priority).toBe(3);
+    });
+  });
+
+  describe('sort', () => {
+    it('应该按 priority 排序', () => {
+      const groups = [
+        { priority: 1, sources: [makeSource({ priority: 1, content: 'p1' })] },
+        { priority: 3, sources: [makeSource({ priority: 3, content: 'p3' })] },
+      ];
+
+      const sorted = pipeline.sort(groups);
+      expect(sorted[0].priority).toBe(1);
+      expect(sorted[1].priority).toBe(3);
+    });
+  });
+
+  describe('compress', () => {
+    it('应该不压缩 P1 和 P6', () => {
+      const sorted = [
+        makeSource({ type: 'system_prompt', priority: 1, content: 'a'.repeat(5000) }),
+        makeSource({ type: 'user_message', priority: 6, content: 'b'.repeat(5000) }),
+      ];
+
+      const { compressed } = pipeline.compress(sorted, defaultBudget);
+      expect(compressed.length).toBe(2);
+    });
+
+    it('应该裁剪超出预算的 P3-P5', () => {
+      const sorted = [
+        makeSource({ priority: 3, content: 'x'.repeat(10000) }),
+        makeSource({ priority: 3, content: 'y'.repeat(10000) }),
+      ];
+
+      const { compressed, dropped } = pipeline.compress(sorted, defaultBudget);
+      // 预算不足时，部分项被截断，部分被丢弃
+      expect(compressed.length).toBeLessThanOrEqual(2);
+      expect(dropped.length).toBeGreaterThan(0);
+      expect(compressed.length + dropped.filter(d => d.reason.includes('超出预算')).length).toBe(2);
+    });
+  });
+
+  describe('applyBudget', () => {
+    it('应该按总预算裁剪', () => {
+      const compressed = [
+        makeSource({ priority: 5, content: 'x'.repeat(50000) }),
+      ];
+
+      const result = pipeline.applyBudget(compressed, { ...defaultBudget, total: 100 });
+      // 超预算的非 P1/P6 项应被丢弃
+      expect(result.length).toBeLessThanOrEqual(1);
+    });
+
+    it('应该强制保留 P1', () => {
+      const compressed = [
+        makeSource({ type: 'system_prompt', priority: 1, content: 'x'.repeat(50000) }),
+      ];
+
+      const result = pipeline.applyBudget(compressed, { ...defaultBudget, total: 100 });
+      expect(result.length).toBe(1);
+    });
+  });
+
+  describe('assemble', () => {
+    it('应该按优先级拼装', () => {
+      const budgeted = [
+        makeSource({ priority: 6, content: 'USER' }),
+        makeSource({ priority: 1, content: 'SYS' }),
+        makeSource({ priority: 3, content: 'KNOW' }),
+      ];
+
+      const prompt = pipeline.assemble(budgeted);
+      expect(prompt.indexOf('SYS')).toBeLessThan(prompt.indexOf('KNOW'));
+      expect(prompt.indexOf('KNOW')).toBeLessThan(prompt.indexOf('USER'));
+    });
+
+    it('应该处理空输入', () => {
+      const prompt = pipeline.assemble([]);
+      expect(prompt).toBe('');
+    });
+  });
+});

package/src/context/__tests__/tool-output-budget.test.ts

@@ -0,0 +1,95 @@
+/**
+ * ToolOutputBudget 测试
+ */
+
+import { ToolOutputBudget } from '../tool-output-budget';
+
+describe('ToolOutputBudget', () => {
+  describe('checkOutput', () => {
+    it('应该允许正常输出', () => {
+      const budget = new ToolOutputBudget();
+      const result = budget.checkOutput('short output');
+      expect(result.allowed).toBe(true);
+      expect(result.strategy).toBe('full');
+    });
+
+    it('应该标记超大输出为 preview', () => {
+      const budget = new ToolOutputBudget();
+      const largeOutput = 'x'.repeat(20000);
+      const result = budget.checkOutput(largeOutput);
+      expect(result.strategy).toBe('preview');
+      expect(result.reason).toContain('超过限制');
+    });
+
+    it('应该标记超大输出为 overflow 当配置开启', () => {
+      const budget = new ToolOutputBudget({ overflowToDisk: true });
+      const largeOutput = 'x'.repeat(20000);
+      const result = budget.checkOutput(largeOutput);
+      expect(result.strategy).toBe('overflow');
+    });
+
+    it('应该标记重复输出为 dedup', () => {
+      const budget = new ToolOutputBudget();
+      budget.checkOutput('same content');
+      const result = budget.checkOutput('same content');
+      expect(result.strategy).toBe('dedup');
+    });
+
+    it('应该按 token 比例检查', () => {
+      const budget = new ToolOutputBudget({ maxTokenRatio: 0.1 });
+      // 约 2500 tokens (10000 chars / 4)
+      const output = 'x'.repeat(10000);
+      const result = budget.checkOutput(output, 10000);
+      expect(result.strategy).toBe('preview');
+    });
+  });
+
+  describe('applyBudget', () => {
+    it('应该返回完整内容当策略为 full', () => {
+      const budget = new ToolOutputBudget();
+      const result = budget.applyBudget('hello world', 'full');
+      expect(result.content).toBe('hello world');
+      expect(result.keptTokens).toBe(result.originalTokens);
+    });
+
+    it('应该生成预览当策略为 preview', () => {
+      const budget = new ToolOutputBudget({ previewLines: 3 });
+      const lines = Array.from({ length: 100 }, (_, i) => `line ${i} with some extra content to make it longer`);
+      const result = budget.applyBudget(lines.join('\n'), 'preview');
+      expect(result.content).toContain('line 0');
+      expect(result.content).toContain('省略');
+      expect(result.keptTokens).toBeLessThan(result.originalTokens);
+    });
+
+    it('应该返回省略提示当策略为 dedup', () => {
+      const budget = new ToolOutputBudget();
+      const result = budget.applyBudget('duplicate content', 'dedup');
+      expect(result.content).toContain('重复内容');
+    });
+
+    it('应该处理 overflow 策略', () => {
+      const budget = new ToolOutputBudget({ previewLines: 2 });
+      const content = Array.from({ length: 20 }, (_, i) => `line${i}`).join('\n');
+      const result = budget.applyBudget(content, 'overflow');
+      expect(result.content).toContain('输出已写入磁盘');
+      expect(result.offloaded).toBeDefined();
+    });
+  });
+
+  describe('clearDedupCache', () => {
+    it('应该清除去重缓存', () => {
+      const budget = new ToolOutputBudget();
+      budget.checkOutput('content');
+      budget.clearDedupCache();
+      const result = budget.checkOutput('content');
+      expect(result.strategy).toBe('full');
+    });
+  });
+
+  describe('getConfig', () => {
+    it('应该返回配置', () => {
+      const budget = new ToolOutputBudget({ maxChars: 8000 });
+      expect(budget.getConfig().maxChars).toBe(8000);
+    });
+  });
+});

package/src/context/compaction.ts

@@ -0,0 +1,202 @@
+/**
+ * 会话压缩
+ *
+ * 三档策略：eviction / summary / checkpoint
+ * 不调用 LLM，零 token 成本
+ */
+
+import { TokenEstimator } from './token-budget';
+import type { CompactionConfig, CompactionLevel, SessionMessage } from './types';
+import { DEFAULT_COMPACTION_CONFIG } from './types';
+
+export interface CompactionResult {
+  compacted: SessionMessage[];
+  summary?: string;
+  level: CompactionLevel;
+  originalTokens: number;
+  compactedTokens: number;
+}
+
+export class SessionCompaction {
+  private config: CompactionConfig;
+
+  constructor(config?: Partial<CompactionConfig>) {
+    this.config = { ...DEFAULT_COMPACTION_CONFIG, ...config };
+  }
+
+  /**
+   * 检查是否需要压缩
+   */
+  shouldCompact(messages: SessionMessage[], budget: number): boolean {
+    const totalTokens = this.estimateMessages(messages);
+    return totalTokens / budget > this.config.triggerRatio;
+  }
+
+  /**
+   * 执行压缩
+   */
+  compact(messages: SessionMessage[], budget: number): CompactionResult {
+    const originalTokens = this.estimateMessages(messages);
+
+    switch (this.config.level) {
+      case 'eviction':
+        return this.evictionCompact(messages, budget, originalTokens);
+      case 'summary':
+        return this.summaryCompact(messages, budget, originalTokens);
+      case 'checkpoint':
+        return this.checkpointCompact(messages, budget, originalTokens);
+      default:
+        return this.evictionCompact(messages, budget, originalTokens);
+    }
+  }
+
+  /**
+   * 轻量压缩：按比例丢最早消息，保留 tool-call 边界对
+   */
+  private evictionCompact(messages: SessionMessage[], budget: number, originalTokens: number): CompactionResult {
+    const targetTokens = Math.floor(budget * 0.6); // 目标压缩到 60%
+    const keepRatio = targetTokens / originalTokens;
+
+    // 至少保留最近 2 条
+    const minKeep = Math.min(2, messages.length);
+    const keepCount = Math.max(minKeep, Math.floor(messages.length * keepRatio));
+
+    let compacted = messages.slice(-keepCount);
+
+    // 保留 tool-call 边界对
+    if (this.config.preserveToolCallPairs) {
+      compacted = this.preserveToolCallPairs(messages, compacted);
+    }
+
+    const compactedTokens = this.estimateMessages(compacted);
+
+    return {
+      compacted,
+      level: 'eviction',
+      originalTokens,
+      compactedTokens,
+    };
+  }
+
+  /**
+   * 中等压缩：结构化总结 + 保留最近 N 轮
+   */
+  private summaryCompact(messages: SessionMessage[], budget: number, originalTokens: number): CompactionResult {
+    const recentCount = Math.min(6, messages.length); // 保留最近 6 条
+    const recent = messages.slice(-recentCount);
+    const older = messages.slice(0, -recentCount);
+
+    // 生成结构化摘要
+    const summary = this.generateStructuredSummary(older);
+
+    // 摘要作为系统消息插入
+    const summarySessionMessage: SessionMessage = {
+      role: 'assistant',
+      content: `[会话摘要]\n${summary}`,
+      timestamp: new Date().toISOString(),
+    };
+
+    const compacted = [summarySessionMessage, ...recent];
+    const compactedTokens = this.estimateMessages(compacted);
+
+    return {
+      compacted,
+      summary,
+      level: 'summary',
+      originalTokens,
+      compactedTokens,
+    };
+  }
+
+  /**
+   * 重型压缩：checkpoint + 清空历史
+   */
+  private checkpointCompact(messages: SessionMessage[], budget: number, originalTokens: number): CompactionResult {
+    const summary = this.generateStructuredSummary(messages);
+
+    const checkpointSessionMessage: SessionMessage = {
+      role: 'assistant',
+      content: `[Checkpoint]\n${summary}\n\n[历史已压缩，共 ${messages.length} 条消息]`,
+      timestamp: new Date().toISOString(),
+    };
+
+    const compacted = [checkpointSessionMessage];
+    const compactedTokens = this.estimateMessages(compacted);
+
+    return {
+      compacted,
+      summary,
+      level: 'checkpoint',
+      originalTokens,
+      compactedTokens,
+    };
+  }
+
+  /**
+   * 生成结构化摘要（零 LLM 成本）
+   */
+  generateStructuredSummary(messages: SessionMessage[]): string {
+    const sections: string[] = [];
+
+    // 提取用户目标
+    const userSessionMessages = messages.filter(m => m.role === 'user');
+    if (userSessionMessages.length > 0) {
+      sections.push(`用户目标: ${userSessionMessages[0].content.slice(0, 200)}`);
+    }
+
+    // 提取工具调用
+    const toolCalls = messages.filter(m => m.role === 'tool');
+    if (toolCalls.length > 0) {
+      sections.push(`工具调用: ${toolCalls.length} 次`);
+    }
+
+    // 提取关键信息
+    const assistantSessionMessages = messages.filter(m => m.role === 'assistant');
+    if (assistantSessionMessages.length > 0) {
+      const lastAssistant = assistantSessionMessages[assistantSessionMessages.length - 1];
+      sections.push(`最近响应: ${lastAssistant.content.slice(0, 200)}`);
+    }
+
+    sections.push(`消息总数: ${messages.length}`);
+    sections.push(`时间范围: ${messages[0]?.timestamp || 'N/A'} → ${messages[messages.length - 1]?.timestamp || 'N/A'}`);
+
+    return sections.join('\n');
+  }
+
+  /**
+   * 保留 tool-call 边界对
+   *
+   * 如果 tool 结果被保留，对应的 tool 调用也要保留
+   */
+  private preserveToolCallPairs(all: SessionMessage[], compacted: SessionMessage[]): SessionMessage[] {
+    const compactedIds = new Set(compacted.map(m => m.toolCallId).filter(Boolean));
+    const result: SessionMessage[] = [];
+
+    for (const msg of compacted) {
+      // 如果是 tool 结果，确保对应的 tool 调用也在
+      if (msg.role === 'tool' && msg.toolCallId) {
+        const paired = all.find(m => m.toolCallId === msg.toolCallId && m.role === 'assistant');
+        if (paired && !compacted.some(m => m === paired)) {
+          result.push(paired);
+        }
+      }
+      result.push(msg);
+    }
+
+    return result;
+  }
+
+  /**
+   * 估算消息的 token 数
+   */
+  private estimateMessages(messages: SessionMessage[]): number {
+    return messages.reduce((sum, m) => sum + TokenEstimator.estimateText(m.content), 0);
+  }
+
+  /**
+   * 获取配置
+   */
+  getConfig(): CompactionConfig {
+    return { ...this.config };
+  }
+}

package/src/context/file-budget.ts

@@ -0,0 +1,142 @@
+/**
+ * 文件读取预算
+ *
+ * 按行数、字节数、Token 数三重限制读取文件
+ * 超限时生成 continuationHint 提示 offset
+ */
+
+import * as fs from 'fs';
+import { TokenEstimator } from './token-budget';
+import type { FileBudgetConfig } from './types';
+import { DEFAULT_FILE_BUDGET } from './types';
+
+export interface FileCheckResult {
+  allowed: boolean;
+  reason?: string;
+  lineCount?: number;
+  byteCount?: number;
+}
+
+export interface FileReadResult {
+  content: string;
+  truncated: boolean;
+  linesRead: number;
+  bytesRead: number;
+  tokensEstimate: number;
+  continuationHint?: string;
+}
+
+export class FileBudget {
+  private config: FileBudgetConfig;
+
+  constructor(config?: Partial<FileBudgetConfig>) {
+    this.config = { ...DEFAULT_FILE_BUDGET, ...config };
+  }
+
+  /**
+   * 检查文件是否在预算内（stat 检查）
+   */
+  checkFile(filePath: string): FileCheckResult {
+    try {
+      const stat = fs.statSync(filePath);
+
+      if (stat.size > this.config.maxBytes) {
+        return {
+          allowed: false,
+          reason: `文件大小 ${(stat.size / 1024).toFixed(1)}KB 超过限制 ${(this.config.maxBytes / 1024).toFixed(1)}KB`,
+          byteCount: stat.size,
+        };
+      }
+
+      return { allowed: true, byteCount: stat.size };
+    } catch (error) {
+      return {
+        allowed: false,
+        reason: `无法读取文件: ${(error as Error).message}`,
+      };
+    }
+  }
+
+  /**
+   * 按预算读取文件
+   *
+   * 三重限制：行数 → 字节数 → Token 数
+   */
+  readWithBudget(filePath: string, config?: Partial<FileBudgetConfig>): FileReadResult {
+    const effectiveConfig = { ...this.config, ...config };
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      let truncated = false;
+      let selectedLines = lines;
+      let continuationHint: string | undefined;
+
+      // 限制 1: 行数
+      if (lines.length > effectiveConfig.maxLines) {
+        selectedLines = lines.slice(0, effectiveConfig.maxLines);
+        truncated = true;
+
+        if (effectiveConfig.continuationHint) {
+          continuationHint = `文件被截断。已读取 ${effectiveConfig.maxLines} 行，共 ${lines.length} 行。使用 offset=${effectiveConfig.maxLines} 继续读取。`;
+        }
+      }
+
+      let result = selectedLines.join('\n');
+
+      // 限制 2: 字节数
+      const byteCount = Buffer.byteLength(result, 'utf-8');
+      if (byteCount > effectiveConfig.maxBytes) {
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(result);
+        const truncatedBytes = bytes.slice(0, effectiveConfig.maxBytes);
+        result = new TextDecoder().decode(truncatedBytes);
+        truncated = true;
+
+        if (!continuationHint && effectiveConfig.continuationHint) {
+          continuationHint = `文件内容被截断。已读取 ${effectiveConfig.maxBytes} 字节。`;
+        }
+      }
+
+      // 限制 3: Token 数
+      const tokensEstimate = TokenEstimator.estimateText(result);
+      if (tokensEstimate > effectiveConfig.maxTokenEstimate) {
+        // 按比例截断
+        const ratio = effectiveConfig.maxTokenEstimate / tokensEstimate;
+        const charLimit = Math.floor(result.length * ratio);
+        result = result.slice(0, charLimit);
+        truncated = true;
+
+        if (!continuationHint && effectiveConfig.continuationHint) {
+          continuationHint = `文件内容被截断。已读取约 ${effectiveConfig.maxTokenEstimate} tokens。`;
+        }
+      }
+
+      return {
+        content: result,
+        truncated,
+        linesRead: selectedLines.length,
+        bytesRead: Buffer.byteLength(result, 'utf-8'),
+        tokensEstimate: TokenEstimator.estimateText(result),
+        continuationHint,
+      };
+    } catch (error) {
+      return {
+        content: '',
+        truncated: false,
+        linesRead: 0,
+        bytesRead: 0,
+        tokensEstimate: 0,
+        continuationHint: `无法读取文件: ${(error as Error).message}`,
+      };
+    }
+  }
+
+  /**
+   * 获取当前配置
+   */
+  getConfig(): FileBudgetConfig {
+    return { ...this.config };
+  }
+}

package/src/context/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 上下文管理模块
+ *
+ * Phase 2: Token 流水线 + 预算 + 压缩
+ */
+
+export * from './types';
+export * from './token-budget';
+export * from './progressive-loader';
+export * from './file-budget';
+export * from './tool-output-budget';
+export * from './compaction';
+export * from './token-pipeline';
+export * from './session-manager';
+export * from './knowledge-injector';