@dommaker/harness 0.13.0 → 0.13.2

package/src/monitoring/traces.ts

@@ -0,0 +1,339 @@
+/**
+ * Execution Trace 收集器
+ *
+ * 轻量设计，零 Token 成本
+ *
+ * 功能：
+ * - 记录约束检查结果（追加写入）
+ * - 批量读取 traces（按时间范围过滤）
+ * - 文件滚动（防止文件过大）
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type {
+  ExecutionTrace,
+  TraceFilter,
+  TraceCollectorConfig,
+} from '../types/trace';
+
+/**
+ * 默认配置
+ */
+const DEFAULT_CONFIG: TraceCollectorConfig = {
+  traceFile: '.harness/logs/traces.log',
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  enabled: true,
+};
+
+/**
+ * Trace 收集器
+ *
+ * 使用方式：
+ * ```typescript
+ * const collector = new TraceCollector();
+ * collector.record({
+ *   constraintId: 'no_fix_without_root_cause',
+ *   level: 'iron_law',
+ *   timestamp: Date.now(),
+ *   result: 'fail',
+ * });
+ * ```
+ */
+export class TraceCollector {
+  private config: TraceCollectorConfig;
+  private traceFile: string;
+
+  constructor(config?: Partial<TraceCollectorConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.traceFile = this.config.traceFile!;
+    this.ensureDirectory();
+  }
+
+  /**
+   * 确保 trace 目录存在
+   */
+  private ensureDirectory(): void {
+    const dir = path.dirname(this.traceFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * 记录一条 trace
+   *
+   * 轻量操作：
+   * - 追加写入（不读取现有内容）
+   * - 单行 JSON（便于批量处理）
+   * - 零 Token 成本
+   */
+  record(trace: ExecutionTrace): void {
+    if (!this.config.enabled) return;
+
+    // 检查文件大小，必要时滚动
+    this.checkFileSize();
+
+    // 追加写入
+    const line = JSON.stringify(trace);
+    fs.appendFileSync(this.traceFile, line + '\n', 'utf-8');
+  }
+
+  /**
+   * 快捷方法：记录通过
+   */
+  recordPass(
+    constraintId: string,
+    level: 'iron_law' | 'guideline' | 'tip',
+    options?: Partial<ExecutionTrace>
+  ): void {
+    this.record({
+      constraintId,
+      level,
+      timestamp: Date.now(),
+      result: 'pass',
+      ...options,
+    });
+  }
+
+  /**
+   * 快捷方法：记录失败
+   */
+  recordFail(
+    constraintId: string,
+    level: 'iron_law' | 'guideline' | 'tip',
+    options?: Partial<ExecutionTrace>
+  ): void {
+    this.record({
+      constraintId,
+      level,
+      timestamp: Date.now(),
+      result: 'fail',
+      ...options,
+    });
+  }
+
+  /**
+   * 快捷方法：记录绕过
+   */
+  recordBypass(
+    constraintId: string,
+    level: 'iron_law' | 'guideline' | 'tip',
+    bypassReason?: string,
+    options?: Partial<ExecutionTrace>
+  ): void {
+    this.record({
+      constraintId,
+      level,
+      timestamp: Date.now(),
+      result: 'bypassed',
+      userAction: 'bypass',
+      bypassReason,
+      ...options,
+    });
+  }
+
+  /**
+   * 批量读取 traces
+   *
+   * 支持过滤条件：
+ * - 时间范围
+ * - 约束 ID
+   * - 结果类型
+   */
+  read(filter?: TraceFilter): ExecutionTrace[] {
+    if (!fs.existsSync(this.traceFile)) {
+      return [];
+    }
+
+    const content = fs.readFileSync(this.traceFile, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+
+    let traces = lines.map(line => JSON.parse(line) as ExecutionTrace);
+
+    // 应用过滤条件
+    if (filter) {
+      traces = this.applyFilter(traces, filter);
+    }
+
+    return traces;
+  }
+
+  /**
+   * 读取最近 N 小时的 traces
+   */
+  readRecent(hours: number): ExecutionTrace[] {
+    const start = Date.now() - hours * 3600 * 1000;
+    return this.read({ timeRange: { start, end: Date.now() } });
+  }
+
+  /**
+   * 读取特定约束的 traces
+   */
+  readByConstraint(constraintId: string): ExecutionTrace[] {
+    return this.read({ constraintId });
+  }
+
+  /**
+   * 应用过滤条件
+   */
+  private applyFilter(traces: ExecutionTrace[], filter: TraceFilter): ExecutionTrace[] {
+    return traces.filter(trace => {
+      // 约束 ID
+      if (filter.constraintId && trace.constraintId !== filter.constraintId) {
+        return false;
+      }
+
+      // 层级
+      if (filter.level && trace.level !== filter.level) {
+        return false;
+      }
+
+      // 结果
+      if (filter.result && trace.result !== filter.result) {
+        return false;
+      }
+
+      // 时间范围
+      if (filter.timeRange) {
+        if (trace.timestamp < filter.timeRange.start) {
+          return false;
+        }
+        if (filter.timeRange.end && trace.timestamp > filter.timeRange.end) {
+          return false;
+        }
+      }
+
+      // 项目路径
+      if (filter.projectPath && trace.projectPath !== filter.projectPath) {
+        return false;
+      }
+
+      // 会话 ID
+      if (filter.sessionId && trace.sessionId !== filter.sessionId) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * 检查文件大小，必要时滚动
+   */
+  private checkFileSize(): void {
+    if (!fs.existsSync(this.traceFile)) {
+      return;
+    }
+
+    const stats = fs.statSync(this.traceFile);
+    if (stats.size >= this.config.maxFileSize!) {
+      this.rotateFile();
+    }
+  }
+
+  /**
+   * 滚动文件
+   *
+   * 将当前文件重命名为带时间戳的备份
+   */
+  private rotateFile(): void {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupFile = this.traceFile.replace('.log', `-${timestamp}.log`);
+
+    // 重命名当前文件
+    fs.renameSync(this.traceFile, backupFile);
+
+    // 创建新文件
+    fs.writeFileSync(this.traceFile, '', 'utf-8');
+  }
+
+  /**
+   * 清理旧备份文件
+   *
+   * 删除超过 maxAge 天的备份文件
+   */
+  cleanupOldFiles(maxAgeDays: number = 30): number {
+    const dir = path.dirname(this.traceFile);
+    if (!fs.existsSync(dir)) {
+      return 0;
+    }
+
+    const files = fs.readdirSync(dir);
+    const backupFiles = files.filter(f => f.endsWith('.log') && f !== 'execution.log');
+
+    const cutoffTime = Date.now() - maxAgeDays * 24 * 3600 * 1000;
+    let deletedCount = 0;
+
+    for (const file of backupFiles) {
+      const filePath = path.join(dir, file);
+      const stats = fs.statSync(filePath);
+
+      if (stats.mtimeMs < cutoffTime) {
+        fs.unlinkSync(filePath);
+        deletedCount++;
+      }
+    }
+
+    return deletedCount;
+  }
+
+  /**
+   * 获取 trace 文件统计信息
+   */
+  getStats(): {
+    fileExists: boolean;
+    fileSize: number;
+    totalLines: number;
+    oldestTrace?: number;
+    newestTrace?: number;
+  } {
+    if (!fs.existsSync(this.traceFile)) {
+      return { fileExists: false, fileSize: 0, totalLines: 0 };
+    }
+
+    const stats = fs.statSync(this.traceFile);
+    const content = fs.readFileSync(this.traceFile, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+
+    let oldest: number | undefined;
+    let newest: number | undefined;
+
+    if (lines.length > 0) {
+      const firstTrace = JSON.parse(lines[0]) as ExecutionTrace;
+      const lastTrace = JSON.parse(lines[lines.length - 1]) as ExecutionTrace;
+      oldest = firstTrace.timestamp;
+      newest = lastTrace.timestamp;
+    }
+
+    return {
+      fileExists: true,
+      fileSize: stats.size,
+      totalLines: lines.length,
+      oldestTrace: oldest,
+      newestTrace: newest,
+    };
+  }
+}
+
+/**
+ * 全局单例（可选）
+ */
+let globalCollector: TraceCollector | null = null;
+
+/**
+ * 获取全局收集器
+ */
+export function getTraceCollector(): TraceCollector {
+  if (!globalCollector) {
+    globalCollector = new TraceCollector();
+  }
+  return globalCollector;
+}
+
+/**
+ * 配置全局收集器
+ */
+export function configureTraceCollector(config: Partial<TraceCollectorConfig>): void {
+  globalCollector = new TraceCollector(config);
+}

package/src/presets/__tests__/standard.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for standard.ts — applyPreset, getPreset, getIronLawPreset
+ *
+ * Pure logic, no I/O — tests preset selection and constraint filtering.
+ */
+
+import { applyPreset, getPreset, getIronLawPreset } from '../standard';
+
+describe('getPreset', () => {
+  it('returns strict preset', () => {
+    const preset = getPreset('strict');
+    expect(preset.name).toBe('strict');
+    expect(preset.ironLaws).toBeNull();
+    expect(preset.guidelines).toBeNull();
+    expect(preset.tips).toBeNull();
+  });
+
+  it('returns standard preset', () => {
+    const preset = getPreset('standard');
+    expect(preset.name).toBe('standard');
+  });
+
+  it('returns relaxed preset', () => {
+    const preset = getPreset('relaxed');
+    expect(preset.name).toBe('relaxed');
+    expect(preset.ironLaws).toHaveLength(3);
+    expect(preset.guidelines).toHaveLength(2);
+    expect(preset.tips).toEqual([]);
+  });
+
+  it('defaults to standard for unknown preset name', () => {
+    const preset = getPreset('unknown' as any);
+    expect(preset.name).toBe('standard');
+  });
+});
+
+describe('applyPreset with string preset names', () => {
+  it('strict enables all iron laws and guidelines', () => {
+    const config = applyPreset('strict');
+    expect(config.ironLaws).toBeDefined();
+    expect(Object.keys(config.ironLaws).length).toBeGreaterThan(0);
+    expect(config.guidelines).toBeDefined();
+    expect(Object.keys(config.guidelines).length).toBeGreaterThan(0);
+    expect(config.disabled).toEqual([]);
+  });
+
+  it('relaxed enables only specific constraints', () => {
+    const config = applyPreset('relaxed');
+    expect(config.ironLaws).toBeDefined();
+    expect(config.ironLaws.no_self_approval).toBeDefined();
+    expect(Object.keys(config.tips).length).toBe(0);
+    expect(config.disabled.length).toBeGreaterThan(0);
+  });
+});
+
+describe('applyPreset with PresetConfig object', () => {
+  it('filters iron laws when ids are provided', () => {
+    const config = applyPreset({
+      name: 'custom',
+      ironLaws: ['no_self_approval', 'no_completion_without_verification'],
+      guidelines: null,
+      tips: null,
+    });
+    expect(Object.keys(config.ironLaws)).toHaveLength(2);
+    expect(config.ironLaws.no_self_approval).toBeDefined();
+    expect(config.ironLaws.no_fix_without_root_cause).toBeUndefined();
+  });
+
+  it('includes all guidelines when null', () => {
+    const config = applyPreset({
+      name: 'custom',
+      ironLaws: null,
+      guidelines: null,
+      tips: [],
+    });
+    expect(Object.keys(config.guidelines).length).toBeGreaterThan(0);
+    expect(Object.keys(config.tips).length).toBe(0);
+  });
+
+  it('creates disabled list for omitted constraints', () => {
+    const config = applyPreset({
+      name: 'custom',
+      ironLaws: [],
+      guidelines: [],
+      tips: [],
+    });
+    expect(config.disabled.length).toBeGreaterThan(0);
+  });
+});
+
+describe('getIronLawPreset (deprecated)', () => {
+  it('returns iron law config for strict preset', () => {
+    const config = getIronLawPreset('strict');
+    expect(config.preset).toBe('strict');
+    expect(config.enabled).toBe(true);
+    expect(config.ironLaws.length).toBeGreaterThan(5);
+  });
+
+  it('returns iron law config for relaxed preset', () => {
+    const config = getIronLawPreset('relaxed');
+    expect(config.preset).toBe('relaxed');
+    expect(config.ironLaws).toHaveLength(3);
+  });
+});

package/src/presets/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 预设模块入口
+ */
+
+export {
+  STRICT_PRESET,
+  STANDARD_PRESET,
+  RELAXED_PRESET,
+  getPreset,
+  applyPreset,
+  // 向后兼容
+  STANDARD_IRON_LAWS_CONFIG,
+  getIronLawPreset,
+} from './standard';
+
+export type { PresetConfig } from './standard';

package/src/presets/standard.ts

@@ -0,0 +1,163 @@
+/**
+ * 约束预设
+ * 
+ * 预设定义哪些约束被启用
+ */
+
+import type { ConstraintLevel, Constraint } from '../types/constraint';
+import type { MergedConstraintsConfig } from '../types/project-config';
+import { IRON_LAWS, GUIDELINES, TIPS } from '../core/constraints/definitions';
+
+/**
+ * 预设配置
+ */
+export interface PresetConfig {
+  /** 预设名称 */
+  name: string;
+
+  /** 启用的铁律 ID 列表（null 表示全部启用） */
+  ironLaws: string[] | null;
+
+  /** 启用的指导原则 ID 列表（null 表示全部启用） */
+  guidelines: string[] | null;
+
+  /** 启用的提示 ID 列表（null 表示全部启用） */
+  tips: string[] | null;
+}
+
+/**
+ * 应用预设，生成 MergedConstraintsConfig（S12）
+ *
+ * 将 PresetConfig 转换为 ConstraintChecker.checkConstraints() 所需的 customConfig。
+ * 支持 per-request 预设切换，不再局限于 CLI。
+ *
+ * @param preset 预设名称（'strict' | 'standard' | 'relaxed'）或 PresetConfig 对象
+ * @returns 可直接传入 checkConstraints() 的 merged config
+ *
+ * 用法：
+ * ```typescript
+ * const config = applyPreset('relaxed');
+ * await checker.checkConstraints(ctx, config);
+ * ```
+ */
+export function applyPreset(
+  preset: string | PresetConfig
+): MergedConstraintsConfig {
+  const cfg = typeof preset === 'string' ? getPreset(preset) : preset;
+
+  const filterByIds = (
+    source: Record<string, Constraint>,
+    ids: string[] | null,
+  ): Record<string, Constraint> => {
+    if (ids === null) return { ...source };
+    const filtered: Record<string, Constraint> = {};
+    for (const id of ids) {
+      if (source[id]) filtered[id] = source[id];
+    }
+    return filtered;
+  };
+
+  const disabled: string[] = [];
+  if (cfg.ironLaws !== null) {
+    for (const id of Object.keys(IRON_LAWS)) {
+      if (!cfg.ironLaws.includes(id)) disabled.push(id);
+    }
+  }
+  if (cfg.guidelines !== null) {
+    for (const id of Object.keys(GUIDELINES)) {
+      if (!cfg.guidelines.includes(id)) disabled.push(id);
+    }
+  }
+
+  return {
+    ironLaws: filterByIds(IRON_LAWS, cfg.ironLaws),
+    guidelines: filterByIds(GUIDELINES, cfg.guidelines),
+    tips: filterByIds(TIPS, cfg.tips),
+    disabled,
+    custom: [],
+  };
+}
+
+/**
+ * 严格预设
+ * 
+ * 所有约束全部启用
+ */
+export const STRICT_PRESET: PresetConfig = {
+  name: 'strict',
+  ironLaws: null,    // 全部启用
+  guidelines: null,  // 全部启用
+  tips: null,        // 全部启用
+};
+
+/**
+ * 标准预设
+ * 
+ * 铁律全部启用，指导原则和提示选择性启用
+ */
+export const STANDARD_PRESET: PresetConfig = {
+  name: 'standard',
+  ironLaws: null,    // 全部启用
+  guidelines: null,  // 全部启用
+  tips: null,        // 全部启用
+};
+
+/**
+ * 宽松预设
+ * 
+ * 仅启用核心铁律，禁用提示
+ */
+export const RELAXED_PRESET: PresetConfig = {
+  name: 'relaxed',
+  ironLaws: [
+    'no_bypass_checkpoint',
+    'no_self_approval',
+    'no_completion_without_verification',
+  ],
+  guidelines: [
+    'no_fix_without_root_cause',
+    'no_code_without_test',
+  ],
+  tips: [],  // 禁用提示
+};
+
+/**
+ * 获取预设
+ */
+export function getPreset(name: string): PresetConfig {
+  switch (name) {
+    case 'strict':
+      return STRICT_PRESET;
+    case 'standard':
+      return STANDARD_PRESET;
+    case 'relaxed':
+      return RELAXED_PRESET;
+    default:
+      return STANDARD_PRESET;
+  }
+}
+
+// ========================================
+// 向后兼容
+// ========================================
+
+import type { IronLawConfig } from '../types/iron-law';
+
+/**
+ * @deprecated 使用 PresetConfig 代替
+ */
+export { STANDARD_PRESET as STANDARD_IRON_LAWS_CONFIG };
+
+/**
+ * @deprecated 使用 getPreset 代替
+ */
+export function getIronLawPreset(preset: string): IronLawConfig {
+  const config = getPreset(preset);
+  return {
+    preset: preset as 'strict' | 'standard' | 'relaxed',
+    enabled: true,
+    ironLaws: config.ironLaws 
+      ? Object.values(IRON_LAWS).filter(c => config.ironLaws!.includes(c.id))
+      : Object.values(IRON_LAWS),
+  };
+}

package/src/safety/CONTEXT.md

@@ -0,0 +1,23 @@
+# safety/
+
+## 职责
+安全护栏：输入/输出/Tool Guardrail + 沙箱执行环境(L1-L4)。
+
+## 核心导出
+- `Sandbox` — 沙箱执行环境: 级别 L1-L4 / 资源限制 / 隔离策略
+- `InputGuardrail` — 输入安全检查: 注入检测 / 敏感信息 / 格式校验
+- `OutputGuardrail` — 输出安全检查: 泄露检测 / 有害内容 / 格式合规
+- `ToolGuardrail` — 工具调用安全: 权限验证 / 参数校验 / 速率限制
+
+## 依赖关系
+- 依赖 `src/types/` 安全相关类型
+- 被 Agent 执行管线消费
+
+## 约定
+- Guardrail 检查在操作前/后执行
+- 沙箱级别 L1(最宽松) → L4(最严格)
+- 安全策略由配置文件控制
+
+## 注意事项
+- Phase 3 实现的核心安全模块
+- Guardrail 检查失败阻断执行(非警告)