@dommaker/harness 0.13.0 → 0.13.2

package/src/constraints/lifecycle-runner.ts

@@ -0,0 +1,184 @@
+/**
+ * 约束生命周期执行器
+ *
+ * 将 ConstraintEvolver 生成的提案转化为 ConstraintRegistry 实际操作。
+ * 连接 monitoring 层（proposal）和 constraints 层（registry）。
+ */
+
+import { ConstraintRegistry } from './registry';
+import type { ConstraintProposal } from '../monitoring/constraint-evolver';
+import type { ConstraintLevel } from '../types/constraint';
+import type { DeprecationSchedule } from './types';
+
+/**
+ * 提案执行结果
+ */
+export interface ExecutionResult {
+  proposalId: string;
+  constraintId: string;
+  action: string;
+  success: boolean;
+  details: string;
+}
+
+/**
+ * 约束生命周期执行器
+ *
+ * 将 evolver 的提案（proposal）转化为 registry 的实际操作（degrade/rollback/scheduleDeprecation）
+ */
+export class ConstraintLifecycleRunner {
+  private registry: ConstraintRegistry;
+
+  constructor(registry?: ConstraintRegistry) {
+    this.registry = registry || new ConstraintRegistry();
+  }
+
+  getRegistry(): ConstraintRegistry {
+    return this.registry;
+  }
+
+  /**
+   * 执行单个已接受的提案
+   */
+  execute(proposal: ConstraintProposal): ExecutionResult {
+    switch (proposal.type) {
+      case 'change_level':
+        return this.executeLevelChange(proposal);
+      case 'add_exception':
+        return this.executeAddException(proposal);
+      case 'adjust_trigger':
+        return this.executeAdjustTrigger(proposal);
+      case 'modify_message':
+        return this.executeModifyMessage(proposal);
+      default:
+        return {
+          proposalId: proposal.id,
+          constraintId: proposal.constraintId,
+          action: proposal.type,
+          success: false,
+          details: `Unsupported proposal type: ${proposal.type}`,
+        };
+    }
+  }
+
+  /**
+   * 批量执行提案
+   */
+  executeBatch(proposals: ConstraintProposal[]): ExecutionResult[] {
+    return proposals.map(p => this.execute(p));
+  }
+
+  /**
+   * 回滚已降级的约束
+   */
+  rollbackConstraint(constraintId: string, originalLevel: ConstraintLevel): boolean {
+    return this.registry.rollback(constraintId, originalLevel);
+  }
+
+  /**
+   * 设置约束的弃用计划
+   */
+  scheduleDeprecation(constraintId: string, schedule: DeprecationSchedule): boolean {
+    return this.registry.scheduleDeprecation(constraintId, schedule);
+  }
+
+  private executeLevelChange(proposal: ConstraintProposal): ExecutionResult {
+    const constraint = this.registry.get(proposal.constraintId);
+    if (!constraint) {
+      return this.failResult(proposal, `Constraint ${proposal.constraintId} not found`);
+    }
+
+    if (constraint.layer === 'safety') {
+      return this.failResult(proposal, 'Cannot change level of safety-layer constraint');
+    }
+
+    const targetLevel = proposal.content.proposed as ConstraintLevel;
+    const currentLevel = constraint.level;
+
+    const levelOrder: Record<string, number> = { iron_law: 0, guideline: 1, tip: 2 };
+    if ((levelOrder[targetLevel] ?? 99) > (levelOrder[currentLevel] ?? 0)) {
+      const success = this.registry.degrade(proposal.constraintId);
+      return {
+        proposalId: proposal.id,
+        constraintId: proposal.constraintId,
+        action: 'degrade',
+        success,
+        details: success
+          ? `Degraded from ${currentLevel} to ${targetLevel}`
+          : 'Degradation failed',
+      };
+    }
+
+    return this.failResult(proposal, 'Level change direction not supported via registry');
+  }
+
+  private executeAddException(proposal: ConstraintProposal): ExecutionResult {
+    const constraint = this.registry.get(proposal.constraintId);
+    if (!constraint) {
+      return this.failResult(proposal, `Constraint ${proposal.constraintId} not found`);
+    }
+
+    const exception = proposal.content.proposed;
+    const currentExceptions = constraint.exceptions || [];
+
+    if (currentExceptions.includes(exception)) {
+      return this.failResult(proposal, `Exception ${exception} already exists`);
+    }
+
+    if (!constraint.exceptions) constraint.exceptions = [];
+    constraint.exceptions.push(exception);
+
+    return {
+      proposalId: proposal.id,
+      constraintId: proposal.constraintId,
+      action: 'add_exception',
+      success: true,
+      details: `Added exception: ${exception}`,
+    };
+  }
+
+  private executeAdjustTrigger(proposal: ConstraintProposal): ExecutionResult {
+    const constraint = this.registry.get(proposal.constraintId);
+    if (!constraint) {
+      return this.failResult(proposal, `Constraint ${proposal.constraintId} not found`);
+    }
+
+    const oldTrigger = constraint.trigger;
+    constraint.trigger = proposal.content.proposed;
+
+    return {
+      proposalId: proposal.id,
+      constraintId: proposal.constraintId,
+      action: 'adjust_trigger',
+      success: true,
+      details: `Changed trigger from ${JSON.stringify(oldTrigger)} to ${JSON.stringify(proposal.content.proposed)}`,
+    };
+  }
+
+  private executeModifyMessage(proposal: ConstraintProposal): ExecutionResult {
+    const constraint = this.registry.get(proposal.constraintId);
+    if (!constraint) {
+      return this.failResult(proposal, `Constraint ${proposal.constraintId} not found`);
+    }
+
+    constraint.message = proposal.content.proposed;
+
+    return {
+      proposalId: proposal.id,
+      constraintId: proposal.constraintId,
+      action: 'modify_message',
+      success: true,
+      details: 'Updated message',
+    };
+  }
+
+  private failResult(proposal: ConstraintProposal, details: string): ExecutionResult {
+    return {
+      proposalId: proposal.id,
+      constraintId: proposal.constraintId,
+      action: proposal.type,
+      success: false,
+      details,
+    };
+  }
+}

package/src/constraints/registry.ts

@@ -0,0 +1,134 @@
+/**
+ * 约束注册表
+ *
+ * 基于 core/constraints/definitions 构建，附加分层和退化元数据。
+ * 分层规则：iron_law → safety（高阈值），guideline/tip → quality（低阈值）
+ * 所有层级均可退化，区别仅在于退化阈值。
+ */
+
+import type { Constraint, ConstraintLevel, ConstraintTrigger } from '../types/constraint';
+import type { LayeredConstraint, ConstraintLayer, DeprecationStatus, LayerStats, DeprecationSchedule } from './types';
+import { IRON_LAWS, GUIDELINES, TIPS } from '../core/constraints/definitions';
+
+function toLayered(constraint: Constraint): LayeredConstraint {
+  const layer: ConstraintLayer = constraint.level === 'iron_law' ? 'safety' : 'quality';
+  const schedule: DeprecationSchedule = layer === 'safety'
+    ? { targetLevel: 'guideline' as ConstraintLevel, reason: '退化：拦截率持续低于 5%', rollbackable: true }
+    : { targetLevel: (constraint.level === 'guideline' ? 'tip' : 'info') as ConstraintLevel, reason: '退化：拦截率持续低于 30%', rollbackable: true };
+  return {
+    ...constraint,
+    layer,
+    deprecationStatus: 'active' as DeprecationStatus,
+    permanent: false,
+    deprecationSchedule: schedule,
+  };
+}
+
+export class ConstraintRegistry {
+  private constraints: Map<string, LayeredConstraint>;
+
+  constructor() {
+    this.constraints = new Map();
+    const all = { ...IRON_LAWS, ...GUIDELINES, ...TIPS };
+    for (const [id, constraint] of Object.entries(all)) {
+      this.constraints.set(id, toLayered(constraint));
+    }
+  }
+
+  get(id: string): LayeredConstraint | undefined {
+    return this.constraints.get(id);
+  }
+
+  getAll(): LayeredConstraint[] {
+    return Array.from(this.constraints.values());
+  }
+
+  getByLayer(layer: ConstraintLayer): LayeredConstraint[] {
+    return this.getAll().filter(c => c.layer === layer);
+  }
+
+  getByStatus(status: DeprecationStatus): LayeredConstraint[] {
+    return this.getAll().filter(c => c.deprecationStatus === status);
+  }
+
+  getByTrigger(trigger: ConstraintTrigger): LayeredConstraint[] {
+    return this.getAll().filter(c => {
+      const triggers = Array.isArray(c.trigger) ? c.trigger : [c.trigger];
+      return triggers.includes(trigger);
+    });
+  }
+
+  getDeprecationCandidates(interceptRates: Map<string, number>): LayeredConstraint[] {
+    return this.getAll().filter(c => {
+      if (c.layer !== 'quality' || !c.deprecationSchedule) return false;
+      if (c.deprecationStatus !== 'active') return false;
+      const threshold = c.deprecationSchedule.interceptRateThreshold;
+      if (threshold === undefined) return false;
+      const rate = interceptRates.get(c.id);
+      return rate !== undefined && rate < threshold;
+    });
+  }
+
+  degrade(id: string): boolean {
+    const constraint = this.constraints.get(id);
+    if (!constraint || !constraint.deprecationSchedule) return false;
+    if (constraint.deprecationStatus !== 'active') return false;
+    constraint.level = constraint.deprecationSchedule.targetLevel;
+    constraint.deprecationStatus = 'deprecated';
+    return true;
+  }
+
+  rollback(id: string, originalLevel: ConstraintLevel): boolean {
+    const constraint = this.constraints.get(id);
+    if (!constraint) return false;
+    if (!constraint.deprecationSchedule?.rollbackable) return false;
+    constraint.level = originalLevel;
+    constraint.deprecationStatus = 'active';
+    return true;
+  }
+
+  scheduleDeprecation(id: string, schedule: DeprecationSchedule): boolean {
+    const constraint = this.constraints.get(id);
+    if (!constraint || constraint.layer !== 'quality') return false;
+    constraint.deprecationSchedule = schedule;
+    constraint.deprecationStatus = 'scheduled';
+    return true;
+  }
+
+  getLayerStats(): LayerStats[] {
+    const layers: ConstraintLayer[] = ['safety', 'quality'];
+    return layers.map(layer => {
+      const constraints = this.getByLayer(layer);
+      return {
+        layer,
+        totalConstraints: constraints.length,
+        active: constraints.filter(c => c.deprecationStatus === 'active').length,
+        scheduled: constraints.filter(c => c.deprecationStatus === 'scheduled').length,
+        deprecated: constraints.filter(c => c.deprecationStatus === 'deprecated').length,
+        removed: constraints.filter(c => c.deprecationStatus === 'removed').length,
+      };
+    });
+  }
+
+  toLegacyConstraints(): Constraint[] {
+    return this.getAll().map(c => ({
+      id: c.id,
+      rule: c.rule,
+      message: c.message,
+      level: c.level,
+      trigger: c.trigger,
+      enforcement: c.enforcement,
+      description: c.description,
+      enabled: c.enabled,
+      exceptions: c.exceptions,
+    }));
+  }
+
+  register(constraint: LayeredConstraint): void {
+    this.constraints.set(constraint.id, constraint);
+  }
+
+  remove(id: string): boolean {
+    return this.constraints.delete(id);
+  }
+}

package/src/constraints/types.ts

@@ -0,0 +1,59 @@
+/**
+ * 约束分层类型定义
+ *
+ * 在原有 Constraint 基础上增加分层和退化元数据
+ */
+
+import type { Constraint, ConstraintLevel } from '../types/constraint';
+
+/** 约束分层 */
+export type ConstraintLayer = 'safety' | 'quality';
+
+/** 退化状态 */
+export type DeprecationStatus = 'active' | 'scheduled' | 'deprecated' | 'removed';
+
+/** 退化计划 */
+export interface DeprecationSchedule {
+  /** 目标级别（当前 → 目标） */
+  targetLevel: ConstraintLevel;
+  /** 触发条件：拦截率低于此值时触发退化 */
+  interceptRateThreshold?: number;
+  /** 计划退化日期 */
+  scheduledDate?: string;
+  /** 退化原因 */
+  reason: string;
+  /** 是否可回滚 */
+  rollbackable: boolean;
+}
+
+/** 带分层元数据的约束 */
+export interface LayeredConstraint extends Constraint {
+  /** 所属层 */
+  layer: ConstraintLayer;
+  /** 退化状态 */
+  deprecationStatus: DeprecationStatus;
+  /** 退化计划（所有层均有，iron_law 高阈值，guideline/tip 低阈值） */
+  deprecationSchedule?: DeprecationSchedule;
+  /** 是否永久保留（false = 所有层均可退化，区别仅在于阈值） */
+  permanent?: boolean;
+}
+
+/** 约束拦截统计 */
+export interface ConstraintStats {
+  constraintId: string;
+  triggerCount: number;
+  passCount: number;
+  interceptCount: number;
+  interceptRate: number;
+  lastTriggered?: string;
+}
+
+/** 约束层统计汇总 */
+export interface LayerStats {
+  layer: ConstraintLayer;
+  totalConstraints: number;
+  active: number;
+  scheduled: number;
+  deprecated: number;
+  removed: number;
+}

package/src/context/CONTEXT.md

@@ -0,0 +1,28 @@
+# context/
+
+## 职责
+上下文管理：Token 预算(多级分配)、渐进式加载(worker pool 并发)、文件/工具输出预算、会话压缩、Token 流水线、知识注入。
+
+## 核心导出
+- `TokenBudget` — 多级 token 预算(system/user/tool/reserve)
+- `ProgressiveLoader` — 渐进式加载 + worker pool 并发
+- `FileBudget` — 文件级 token 预算
+- `ToolOutputBudget` — 工具输出 token 预算
+- `Compaction` — 会话压缩(摘要/截断/滑动窗口)
+- `TokenPipeline` — Token 流水线
+- `SessionManager` — 会话管理
+- `KnowledgeInjector` — 知识注入引擎
+
+## 依赖关系
+- 依赖 `src/types/` 公共类型
+- 依赖 `src/core/` 核心模块
+- 被 Agent 会话管理消费
+
+## 约定
+- Token 预算策略由配置文件控制
+- 渐进式加载保证输入顺序(worker pool 模式)
+- 会话压缩策略可组合
+
+## 注意事项
+- Phase 2 实现的 Token 流水线 + 预算 + 压缩
+- 零 Token 成本：纯计算，不调用 LLM

package/src/context/__tests__/compaction.test.ts

@@ -0,0 +1,169 @@
+/**
+ * SessionCompaction 测试
+ */
+
+import { SessionCompaction } from '../compaction';
+import type { SessionMessage } from '../types';
+
+function makeMessages(count: number, contentLength: number = 100): SessionMessage[] {
+  return Array.from({ length: count }, (_, i) => ({
+    role: (i % 2 === 0 ? 'user' : 'assistant') as 'user' | 'assistant',
+    content: `message ${i} `.repeat(contentLength / 10),
+    timestamp: new Date(Date.now() + i * 1000).toISOString(),
+  }));
+}
+
+describe('SessionCompaction', () => {
+  describe('shouldCompact', () => {
+    it('应该返回 true 当超过触发比例', () => {
+      const compaction = new SessionCompaction({ triggerRatio: 0.5 });
+      const messages = makeMessages(10, 500);
+      // 10 * ~50 tokens each ≈ 500 tokens, budget=800 → ratio > 0.5
+      expect(compaction.shouldCompact(messages, 800)).toBe(true);
+    });
+
+    it('应该返回 false 当未超过触发比例', () => {
+      const compaction = new SessionCompaction({ triggerRatio: 0.9 });
+      const messages = makeMessages(2, 10);
+      expect(compaction.shouldCompact(messages, 10000)).toBe(false);
+    });
+  });
+
+  describe('compact (eviction)', () => {
+    it('应该按比例丢弃最早消息', () => {
+      const compaction = new SessionCompaction({ level: 'eviction', preserveToolCallPairs: false });
+      const messages = makeMessages(20, 500);
+      const result = compaction.compact(messages, 1000);
+      expect(result.level).toBe('eviction');
+      expect(result.compacted.length).toBeLessThan(messages.length);
+      expect(result.compacted.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('应该保留最近的消息', () => {
+      const compaction = new SessionCompaction({ level: 'eviction', preserveToolCallPairs: false });
+      const messages = makeMessages(20, 100);
+      const result = compaction.compact(messages, 1000);
+      const lastOriginal = messages[messages.length - 1];
+      expect(result.compacted[result.compacted.length - 1]).toBe(lastOriginal);
+    });
+
+    it('应该保留 tool-call 边界对', () => {
+      const compaction = new SessionCompaction({ level: 'eviction', preserveToolCallPairs: true });
+      const messages: SessionMessage[] = [
+        { role: 'user', content: 'a'.repeat(1000), timestamp: 't1' },
+        { role: 'assistant', content: 'b'.repeat(1000), toolCallId: 'call-1', timestamp: 't2' },
+        { role: 'tool', content: 'c'.repeat(1000), toolCallId: 'call-1', timestamp: 't3' },
+        { role: 'user', content: 'd'.repeat(1000), timestamp: 't4' },
+        { role: 'assistant', content: 'e'.repeat(1000), timestamp: 't5' },
+      ];
+      const result = compaction.compact(messages, 500);
+      // 如果 tool result is kept, its paired assistant call should also be kept
+      const toolResult = result.compacted.find(m => m.role === 'tool');
+      if (toolResult) {
+        const paired = result.compacted.find(m => m.toolCallId === toolResult.toolCallId && m.role === 'assistant');
+        expect(paired).toBeDefined();
+      }
+    });
+  });
+
+  describe('compact (summary)', () => {
+    it('应该生成结构化摘要', () => {
+      const compaction = new SessionCompaction({ level: 'summary' });
+      const messages = makeMessages(20, 100);
+      const result = compaction.compact(messages, 1000);
+      expect(result.level).toBe('summary');
+      expect(result.summary).toBeDefined();
+      expect(result.summary).toContain('用户目标');
+      expect(result.summary).toContain('消息总数');
+    });
+
+    it('应该保留最近 6 条消息', () => {
+      const compaction = new SessionCompaction({ level: 'summary' });
+      const messages = makeMessages(20, 100);
+      const result = compaction.compact(messages, 1000);
+      // 1 summary message + 6 recent
+      expect(result.compacted.length).toBe(7);
+    });
+  });
+
+  describe('compact (checkpoint)', () => {
+    it('应该压缩为单条 checkpoint 消息', () => {
+      const compaction = new SessionCompaction({ level: 'checkpoint' });
+      const messages = makeMessages(20, 100);
+      const result = compaction.compact(messages, 1000);
+      expect(result.level).toBe('checkpoint');
+      expect(result.compacted.length).toBe(1);
+      expect(result.compacted[0].content).toContain('Checkpoint');
+    });
+  });
+
+  describe('generateStructuredSummary', () => {
+    it('应该从用户消息提取目标', () => {
+      const compaction = new SessionCompaction();
+      const messages: SessionMessage[] = [
+        { role: 'user', content: '帮我写一个函数', timestamp: 't1' },
+        { role: 'assistant', content: '好的', timestamp: 't2' },
+      ];
+      const summary = compaction.generateStructuredSummary(messages);
+      expect(summary).toContain('帮我写一个函数');
+    });
+
+    it('应该统计工具调用', () => {
+      const compaction = new SessionCompaction();
+      const messages: SessionMessage[] = [
+        { role: 'tool', content: 'result1', timestamp: 't1' },
+        { role: 'tool', content: 'result2', timestamp: 't2' },
+      ];
+      const summary = compaction.generateStructuredSummary(messages);
+      expect(summary).toContain('2 次');
+    });
+  });
+
+  describe('getConfig', () => {
+    it('应该返回配置', () => {
+      const compaction = new SessionCompaction({ level: 'summary' });
+      expect(compaction.getConfig().level).toBe('summary');
+    });
+  });
+
+  describe('compact (default level)', () => {
+    it('应该在未知 level 时回退到 eviction', () => {
+      const compaction = new SessionCompaction({ level: 'eviction' as any, preserveToolCallPairs: false });
+      // 直接设置一个不会匹配的 level 来触发 default 分支
+      (compaction as any).config.level = 'unknown_level';
+      const messages = makeMessages(20, 500);
+      const result = compaction.compact(messages, 1000);
+      expect(result.level).toBe('eviction');
+    });
+  });
+
+  describe('preserveToolCallPairs 边界情况', () => {
+    it('应该在 paired assistant 已在 compacted 中时跳过', () => {
+      const compaction = new SessionCompaction({ level: 'eviction', preserveToolCallPairs: true });
+      const messages: SessionMessage[] = [
+        { role: 'user', content: 'a'.repeat(100), timestamp: 't1' },
+        { role: 'assistant', content: 'b'.repeat(100), toolCallId: 'call-1', timestamp: 't2' },
+        { role: 'tool', content: 'c'.repeat(100), toolCallId: 'call-1', timestamp: 't3' },
+        { role: 'user', content: 'd'.repeat(100), timestamp: 't4' },
+        { role: 'assistant', content: 'e'.repeat(100), timestamp: 't5' },
+      ];
+      // budget 足够大，所有消息都会保留
+      const result = compaction.compact(messages, 100000);
+      // paired assistant 已在 compacted 中，不应重复添加
+      const assistantCalls = result.compacted.filter(m => m.toolCallId === 'call-1' && m.role === 'assistant');
+      expect(assistantCalls.length).toBe(1);
+    });
+
+    it('应该处理无 toolCallId 的消息', () => {
+      const compaction = new SessionCompaction({ level: 'eviction', preserveToolCallPairs: true });
+      const messages: SessionMessage[] = [
+        { role: 'user', content: 'a'.repeat(1000), timestamp: 't1' },
+        { role: 'assistant', content: 'b'.repeat(1000), timestamp: 't2' },
+        { role: 'user', content: 'c'.repeat(1000), timestamp: 't3' },
+        { role: 'assistant', content: 'd'.repeat(1000), timestamp: 't4' },
+      ];
+      const result = compaction.compact(messages, 500);
+      expect(result.compacted.length).toBeGreaterThan(0);
+    });
+  });
+});