@dommaker/harness 0.13.0 → 0.13.2

package/src/context/token-pipeline.ts

@@ -0,0 +1,265 @@
+/**
+ * Token 流水线
+ *
+ * 五步：收集 → 排序 → 压缩 → 预算 → 组装
+ * 每次 LLM 调用前运行
+ */
+
+import { TokenEstimator, TokenBudget } from './token-budget';
+import type {
+  ContextSource,
+  TokenBudgetAllocation,
+  PipelineInput,
+  PipelineOutput,
+  ContextUsageSnapshot,
+} from './types';
+
+interface CollectedGroup {
+  priority: number;
+  sources: ContextSource[];
+}
+
+export class TokenPipeline {
+  /**
+   * 完整流水线：收集 → 排序 → 压缩 → 预算 → 组装
+   */
+  run(input: PipelineInput): PipelineOutput {
+    const { sources, budget } = input;
+
+    // Step 1: 收集 — 按 priority 分组
+    const collected = this.collect(sources);
+
+    // Step 2: 排序 — 按 P1→P6 排序
+    const sorted = this.sort(collected);
+
+    // Step 3: 压缩 — 对 P3-P5 应用预算裁剪
+    const { compressed, dropped } = this.compress(sorted, budget);
+
+    // Step 4: 预算 — 按分配裁剪
+    const budgeted = this.applyBudget(compressed, budget);
+
+    // Step 5: 组装 — 拼装最终 prompt
+    const prompt = this.assemble(budgeted);
+
+    // 生成快照
+    const snapshot = this.buildSnapshot(budgeted, dropped);
+
+    return { prompt, snapshot, dropped };
+  }
+
+  /**
+   * Step 1: 收集 — 从 sources 按 priority 分组
+   */
+  collect(sources: ContextSource[]): CollectedGroup[] {
+    const groups = new Map<number, ContextSource[]>();
+
+    for (const source of sources) {
+      const existing = groups.get(source.priority) || [];
+      existing.push(source);
+      groups.set(source.priority, existing);
+    }
+
+    return Array.from(groups.entries())
+      .map(([priority, sources]) => ({ priority, sources }))
+      .sort((a, b) => a.priority - b.priority);
+  }
+
+  /**
+   * Step 2: 排序 — 按 P1→P6，组内保持原序
+   */
+  sort(groups: CollectedGroup[]): ContextSource[] {
+    const sorted: ContextSource[] = [];
+
+    for (const group of groups) {
+      sorted.push(...group.sources);
+    }
+
+    return sorted;
+  }
+
+  /**
+   * Step 3: 压缩 — 对 P3-P5 应用 token 预算裁剪
+   *
+   * P1（系统提示词）和 P6（用户消息）不压缩
+   * P2（工具定义）按需懒加载，这里不处理
+   */
+  compress(sorted: ContextSource[], budget: TokenBudgetAllocation): {
+    compressed: ContextSource[];
+    dropped: Array<{ type: string; id: string; reason: string }>;
+  } {
+    const compressed: ContextSource[] = [];
+    const dropped: Array<{ type: string; id: string; reason: string }> = [];
+
+    // 各段预算
+    const budgetMap: Record<number, number> = {
+      1: budget.systemPrompt,
+      2: budget.toolDefinitions,
+      3: budget.knowledge,
+      4: budget.notes,
+      5: budget.history,
+      6: Infinity, // 用户消息不限
+    };
+
+    // 按优先级分组处理
+    const byPriority = new Map<number, ContextSource[]>();
+    for (const item of sorted) {
+      const existing = byPriority.get(item.priority) || [];
+      existing.push(item);
+      byPriority.set(item.priority, existing);
+    }
+
+    for (const [priority, items] of byPriority) {
+      const sectionBudget = budgetMap[priority] || budget.history;
+
+      if (priority === 1 || priority === 6) {
+        // P1/P6 不压缩
+        compressed.push(...items);
+        continue;
+      }
+
+      // 按 token 预算裁剪
+      let usedTokens = 0;
+      for (const item of items) {
+        const tokens = TokenEstimator.estimateText(item.content);
+
+        if (usedTokens + tokens <= sectionBudget) {
+          compressed.push(item);
+          usedTokens += tokens;
+        } else {
+          // 尝试截断
+          const remaining = sectionBudget - usedTokens;
+          if (remaining > 50) {
+            const ratio = remaining / tokens;
+            const truncatedContent = item.content.slice(0, Math.floor(item.content.length * ratio));
+            compressed.push({ ...item, content: truncatedContent });
+            dropped.push({
+              type: item.type,
+              id: item.id,
+              reason: `截断: ${tokens} → ${Math.floor(tokens * ratio)} tokens`,
+            });
+          } else {
+            dropped.push({
+              type: item.type,
+              id: item.id,
+              reason: `超出预算: 需要 ${tokens} tokens，剩余 ${remaining}`,
+            });
+          }
+          usedTokens += tokens; // 仍然计入已用
+        }
+      }
+    }
+
+    return { compressed, dropped };
+  }
+
+  /**
+   * Step 4: 预算 — 按 TokenBudgetAllocation 分配各段
+   */
+  applyBudget(compressed: ContextSource[], budget: TokenBudgetAllocation): ContextSource[] {
+    const tokenBudget = new TokenBudget(budget.total);
+    const result: ContextSource[] = [];
+
+    for (const item of compressed) {
+      const tokens = TokenEstimator.estimateText(item.content);
+
+      if (tokenBudget.canAfford(tokens)) {
+        tokenBudget.consume(tokens);
+        result.push(item);
+      } else if (item.priority === 1 || item.priority === 6) {
+        // P1/P6 强制保留
+        tokenBudget.forceConsume(tokens);
+        result.push(item);
+      }
+      // 其他优先级的超预算项被丢弃
+    }
+
+    return result;
+  }
+
+  /**
+   * Step 5: 组装 — 拼装最终 prompt
+   *
+   * P1 开头 + P6 结尾，中间 P2-P5
+   */
+  assemble(budgeted: ContextSource[]): string {
+    const sections: Record<number, string[]> = {
+      1: [], 2: [], 3: [], 4: [], 5: [], 6: [],
+    };
+
+    for (const item of budgeted) {
+      sections[item.priority] = sections[item.priority] || [];
+      sections[item.priority].push(item.content);
+    }
+
+    const parts: string[] = [];
+
+    // P1: 系统提示词（开头）
+    if (sections[1].length > 0) {
+      parts.push(sections[1].join('\n'));
+    }
+
+    // P2-P5: 中间部分
+    for (const priority of [2, 3, 4, 5]) {
+      if (sections[priority].length > 0) {
+        parts.push(sections[priority].join('\n'));
+      }
+    }
+
+    // P6: 用户消息（结尾）
+    if (sections[6].length > 0) {
+      parts.push(sections[6].join('\n'));
+    }
+
+    return parts.join('\n\n');
+  }
+
+  /**
+   * 构建上下文使用快照
+   */
+  private buildSnapshot(budgeted: ContextSource[], dropped: Array<{ type: string; id: string; reason: string }>): ContextUsageSnapshot {
+    const breakdown = {
+      systemPrompt: 0,
+      messages: 0,
+      toolOutputs: 0,
+      knowledge: 0,
+      other: 0,
+    };
+
+    for (const item of budgeted) {
+      const tokens = TokenEstimator.estimateText(item.content);
+
+      switch (item.type) {
+        case 'system_prompt':
+          breakdown.systemPrompt += tokens;
+          break;
+        case 'user_message':
+        case 'session_event':
+          breakdown.messages += tokens;
+          break;
+        case 'tool_output':
+        case 'tool_definition':
+          breakdown.toolOutputs += tokens;
+          break;
+        case 'knowledge':
+          breakdown.knowledge += tokens;
+          break;
+        default:
+          breakdown.other += tokens;
+      }
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      totalTokens: breakdown.systemPrompt + breakdown.messages + breakdown.toolOutputs + breakdown.knowledge + breakdown.other,
+      breakdown,
+      truncatedItems: dropped.filter(d => d.reason.startsWith('截断')).map(d => ({
+        type: d.type,
+        id: d.id,
+        originalTokens: 0,
+        keptTokens: 0,
+      })),
+      offloadedItems: [],
+      compactionTriggered: false,
+    };
+  }
+}

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

@@ -0,0 +1,178 @@
+/**
+ * 工具输出预算
+ *
+ * 控制工具输出对上下文的占用
+ * 策略：full / preview / overflow / dedup
+ */
+
+import * as crypto from 'crypto';
+import { TokenEstimator } from './token-budget';
+import type { ToolOutputBudgetConfig } from './types';
+import { DEFAULT_TOOL_OUTPUT_BUDGET } from './types';
+
+export type OutputStrategy = 'full' | 'preview' | 'overflow' | 'dedup';
+
+export interface OutputCheckResult {
+  allowed: boolean;
+  strategy: OutputStrategy;
+  reason?: string;
+}
+
+export interface OutputApplyResult {
+  content: string;
+  offloaded?: { path: string };
+  originalTokens: number;
+  keptTokens: number;
+}
+
+export class ToolOutputBudget {
+  private config: ToolOutputBudgetConfig;
+  private seenHashes: Map<string, boolean> = new Map();
+
+  constructor(config?: Partial<ToolOutputBudgetConfig>) {
+    this.config = { ...DEFAULT_TOOL_OUTPUT_BUDGET, ...config };
+  }
+
+  /**
+   * 检查工具输出应该使用什么策略
+   */
+  checkOutput(output: string, totalBudget?: number): OutputCheckResult {
+    const charCount = output.length;
+    const tokens = TokenEstimator.estimateText(output);
+
+    // 去重检查
+    if (this.config.dedup) {
+      const hash = this.computeHash(output);
+      if (this.seenHashes.has(hash)) {
+        return { allowed: true, strategy: 'dedup', reason: '重复内容，将被去重' };
+      }
+      // 记录 hash（无论最终策略是什么）
+      this.seenHashes.set(hash, true);
+    }
+
+    // 硬上限检查
+    if (charCount > this.config.maxChars) {
+      return {
+        allowed: true,
+        strategy: this.config.overflowToDisk ? 'overflow' : 'preview',
+        reason: `输出 ${charCount} 字符超过限制 ${this.config.maxChars}`,
+      };
+    }
+
+    // Token 比例检查
+    if (totalBudget) {
+      const maxTokens = totalBudget * this.config.maxTokenRatio;
+      if (tokens > maxTokens) {
+        return {
+          allowed: true,
+          strategy: 'preview',
+          reason: `输出 ${tokens} tokens 超过预算比例 ${(this.config.maxTokenRatio * 100).toFixed(0)}% (${Math.floor(maxTokens)} tokens)`,
+        };
+      }
+    }
+
+    return { allowed: true, strategy: 'full' };
+  }
+
+  /**
+   * 应用预算策略
+   */
+  applyBudget(output: string, strategy: OutputStrategy, totalBudget?: number): OutputApplyResult {
+    const originalTokens = TokenEstimator.estimateText(output);
+
+    switch (strategy) {
+      case 'full': {
+        if (this.config.dedup) {
+          this.recordHash(output);
+        }
+        return { content: output, originalTokens, keptTokens: originalTokens };
+      }
+
+      case 'preview': {
+        const preview = this.generatePreview(output);
+        const keptTokens = TokenEstimator.estimateText(preview);
+        return { content: preview, originalTokens, keptTokens };
+      }
+
+      case 'overflow': {
+        const path = this.writeToOverflow(output);
+        const summary = `[输出已写入磁盘: ${path}]\n前 ${this.config.previewLines} 行预览:\n${output.split('\n').slice(0, this.config.previewLines).join('\n')}`;
+        const keptTokens = TokenEstimator.estimateText(summary);
+        return { content: summary, offloaded: { path }, originalTokens, keptTokens };
+      }
+
+      case 'dedup': {
+        const dedupContent = `[重复内容，已省略。原始大小: ${output.length} 字符]`;
+        return { content: dedupContent, originalTokens, keptTokens: TokenEstimator.estimateText(dedupContent) };
+      }
+
+      default:
+        return { content: output, originalTokens, keptTokens: originalTokens };
+    }
+  }
+
+  /**
+   * 生成预览内容
+   */
+  private generatePreview(output: string): string {
+    const lines = output.split('\n');
+    const previewLines = this.config.previewLines;
+
+    if (lines.length <= previewLines) {
+      return output;
+    }
+
+    const head = lines.slice(0, previewLines).join('\n');
+    const omitted = lines.length - previewLines;
+    return `${head}\n\n... [省略 ${omitted} 行] ...\n\n${lines.slice(-3).join('\n')}`;
+  }
+
+  /**
+   * 写入溢出文件
+   */
+  private writeToOverflow(output: string): string {
+    const hash = this.computeHash(output).slice(0, 8);
+    const path = `.harness/overflow/tool-output-${hash}.txt`;
+
+    try {
+      const fs = require('fs');
+      const dir = require('path').dirname(path);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path, output, 'utf-8');
+    } catch {
+      // 写入失败时回退到 preview
+      return '';
+    }
+
+    return path;
+  }
+
+  /**
+   * 计算内容 hash
+   */
+  private computeHash(content: string): string {
+    return crypto.createHash('md5').update(content).digest('hex');
+  }
+
+  /**
+   * 记录已见 hash
+   */
+  private recordHash(content: string): void {
+    const hash = this.computeHash(content);
+    this.seenHashes.set(hash, true);
+  }
+
+  /**
+   * 清除去重缓存
+   */
+  clearDedupCache(): void {
+    this.seenHashes.clear();
+  }
+
+  /**
+   * 获取配置
+   */
+  getConfig(): ToolOutputBudgetConfig {
+    return { ...this.config };
+  }
+}

package/src/context/types.ts

@@ -0,0 +1,160 @@
+/**
+ * 上下文管理类型定义
+ *
+ * Phase 2: Token 流水线 + 预算 + 压缩
+ */
+
+import type { QueryResult } from '../knowledge/types';
+
+// ========================================
+// 文件读取预算
+// ========================================
+
+export interface FileBudgetConfig {
+  maxLines: number;           // 默认 2000
+  maxBytes: number;           // 默认 50KB (51200)
+  maxTokenEstimate: number;   // 默认 8000
+  continuationHint: boolean;  // 默认 true
+}
+
+export const DEFAULT_FILE_BUDGET: FileBudgetConfig = {
+  maxLines: 2000,
+  maxBytes: 51200,
+  maxTokenEstimate: 8000,
+  continuationHint: true,
+};
+
+// ========================================
+// 工具输出预算
+// ========================================
+
+export interface ToolOutputBudgetConfig {
+  maxChars: number;           // 默认 16000
+  maxTokenRatio: number;      // 默认 0.3 (占总预算 30%)
+  previewLines: number;       // 默认 50
+  overflowToDisk: boolean;    // 默认 false
+  dedup: boolean;             // 默认 true
+}
+
+export const DEFAULT_TOOL_OUTPUT_BUDGET: ToolOutputBudgetConfig = {
+  maxChars: 16000,
+  maxTokenRatio: 0.3,
+  previewLines: 50,
+  overflowToDisk: false,
+  dedup: true,
+};
+
+// ========================================
+// 会话压缩
+// ========================================
+
+export type CompactionLevel = 'eviction' | 'summary' | 'checkpoint';
+
+export interface CompactionConfig {
+  triggerRatio: number;            // 默认 0.8
+  level: CompactionLevel;
+  preserveToolCallPairs: boolean;  // 默认 true
+  structuredSummary: boolean;      // 默认 true
+  maxSummaryTokens: number;        // 默认 2000
+  fallbackStrategy: 'truncate-middle' | 'head-drop' | 'retry-with-clamp';
+}
+
+export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
+  triggerRatio: 0.8,
+  level: 'eviction',
+  preserveToolCallPairs: true,
+  structuredSummary: true,
+  maxSummaryTokens: 2000,
+  fallbackStrategy: 'truncate-middle',
+};
+
+export interface SessionMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  toolCallId?: string;
+  timestamp: string;
+}
+
+// ========================================
+// Token Pipeline
+// ========================================
+
+export type ContextSourceType = 'session_event' | 'tool_output' | 'knowledge' | 'user_message' | 'system_prompt' | 'tool_definition';
+
+export interface ContextSource {
+  type: ContextSourceType;
+  id: string;
+  content: string;
+  priority: number;  // P1-P6
+  metadata?: Record<string, any>;
+}
+
+export interface TokenBudgetAllocation {
+  total: number;
+  systemPrompt: number;    // 固定，不压缩
+  toolDefinitions: number; // 按需懒加载
+  knowledge: number;       // 500-800
+  notes: number;           // 200-500
+  history: number;         // 剩余预算
+}
+
+export interface PipelineInput {
+  sources: ContextSource[];
+  budget: TokenBudgetAllocation;
+  knowledge?: QueryResult;
+}
+
+export interface PipelineOutput {
+  prompt: string;
+  snapshot: ContextUsageSnapshot;
+  dropped: Array<{ type: string; id: string; reason: string }>;
+}
+
+// ========================================
+// 上下文使用快照
+// ========================================
+
+export interface ContextUsageSnapshot {
+  timestamp: string;
+  totalTokens: number;
+  breakdown: {
+    systemPrompt: number;
+    messages: number;
+    toolOutputs: number;
+    knowledge: number;
+    other: number;
+  };
+  truncatedItems: Array<{ type: string; id: string; originalTokens: number; keptTokens: number }>;
+  offloadedItems: Array<{ type: string; id: string; target: 'disk' | 'summary' | 'dropped' }>;
+  compactionTriggered: boolean;
+  compactionLevel?: CompactionLevel;
+}
+
+// ========================================
+// Session Manager
+// ========================================
+
+export type SessionEventType = 'user_message' | 'assistant_message' | 'tool_call' | 'tool_result' | 'checkpoint' | 'system';
+
+export interface SessionEvent {
+  type: SessionEventType;
+  id: string;
+  content: string;
+  timestamp: string;
+  metadata?: Record<string, any>;
+}
+
+export interface SessionHandle {
+  id: string;
+  events: SessionEvent[];
+  createdAt: string;
+  lastActiveAt: string;
+}
+
+export interface SessionCheckpoint {
+  id: string;
+  sessionId: string;
+  timestamp: string;
+  eventCount: number;
+  summary: string;
+}

package/src/core/CONTEXT.md

@@ -0,0 +1,26 @@
+# core/
+
+## 职责
+约束引擎核心：三层约束系统(Iron Laws / Guidelines / Tips)、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
+
+## 核心导出
+- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/TIPS) + 检查引擎(ConstraintChecker) + 拦截器(ConstraintInterceptor) + 缓存(CheckCache)
+- `validators/` — checkpoints、passes-gate、CSO 验证器
+- `session/` — 会话管理
+- `spec/validator` — SpecValidator
+- `project-config-loader` — 项目配置加载 + 约束合并
+
+## 依赖关系
+- 被所有模块依赖（基础层，无上层依赖）
+- 依赖 `src/types/` 类型定义
+- 依赖 `src/utils/` 工具函数
+- 依赖 `src/monitoring/traces` TraceCollector
+
+## 约定
+- 约束定义在 `constraints/definitions.ts`，不在运行时代码中定义
+- Iron Law 违规必须 throw ConstraintViolationError
+- 检查器使用单例模式(ConstraintChecker.getInstance())
+
+## 注意事项
+- 零 Token 成本：所有分析纯文件操作，无 LLM 调用
+- 约束配置支持 .harness/config.yml 自定义合并

package/src/core/constraints/__tests__/default-executors.test.ts

@@ -0,0 +1,57 @@
+/**
+ * default-executors 注册测试
+ */
+
+import { constraintInterceptor } from '../interceptor';
+
+describe('registerDefaultExecutors', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Reset the singleton state for clean test
+    (constraintInterceptor as any).executors.clear();
+    (constraintInterceptor as any).executorSources.clear();
+  });
+
+  it('应该注册 architecture-check executor', async () => {
+    const { registerDefaultExecutors } = await import('../default-executors');
+    registerDefaultExecutors();
+
+    expect(constraintInterceptor.hasExecutor('architecture-check')).toBe(true);
+  });
+
+  it('应该注册 cross-project-check executor', async () => {
+    const { registerDefaultExecutors } = await import('../default-executors');
+    registerDefaultExecutors();
+
+    expect(constraintInterceptor.hasExecutor('cross-project-check')).toBe(true);
+  });
+
+  it('架构检查 executor 应有描述', async () => {
+    const { registerDefaultExecutors } = await import('../default-executors');
+    registerDefaultExecutors();
+
+    const executor = constraintInterceptor.getExecutor('architecture-check');
+    expect(executor?.description).toBeDefined();
+    expect(executor?.description).toContain('架构');
+  });
+
+  it('跨工程检查 executor 应有描述', async () => {
+    const { registerDefaultExecutors } = await import('../default-executors');
+    registerDefaultExecutors();
+
+    const executor = constraintInterceptor.getExecutor('cross-project-check');
+    expect(executor?.description).toBeDefined();
+    expect(executor?.description).toContain('跨工程');
+  });
+
+  it('重复注册应该覆盖', async () => {
+    const { registerDefaultExecutors } = await import('../default-executors');
+    registerDefaultExecutors();
+    registerDefaultExecutors(); // Second call
+
+    const registrations = constraintInterceptor.getRegistrations();
+    const archRegs = registrations.filter(r => r.id === 'architecture-check');
+    // Should only have one registration (last one wins)
+    expect(archRegs.length).toBe(1);
+  });
+});