@dommaker/harness 0.13.0 → 0.13.2

package/src/core/constraints/interceptor.ts

@@ -0,0 +1,220 @@
+/**
+ * ConstraintInterceptor - 约束拦截器
+ */
+
+import type {
+  Constraint,
+  ConstraintTrigger,
+  ConstraintContext,
+  ConstraintLevel,
+  ConstraintResult,
+} from '../../types/constraint';
+import { ConstraintViolationError } from '../../types/constraint';
+import { normalizeTriggers } from '../../utils/exec';
+import type {
+  EnforcementId,
+  EnforcementExecutor,
+  EnforcementContext,
+  EnforcementResult,
+  InterceptionResult,
+} from '../../types/enforcement';
+import { constraintChecker } from './checker';
+
+export class ConstraintInterceptor {
+  private static instance: ConstraintInterceptor;
+  private executors: Map<EnforcementId, EnforcementExecutor> = new Map();
+  private executorSources: Map<EnforcementId, string> = new Map();
+  private enabled: boolean = true;
+  private skipEnforcements: Set<EnforcementId> = new Set();
+
+  private constructor() {}
+
+  static getInstance(): ConstraintInterceptor {
+    if (!ConstraintInterceptor.instance) {
+      ConstraintInterceptor.instance = new ConstraintInterceptor();
+    }
+    return ConstraintInterceptor.instance;
+  }
+
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  register(
+    enforcementId: EnforcementId,
+    executor: EnforcementExecutor,
+    source?: string
+  ): void {
+    this.executors.set(enforcementId, executor);
+    if (source) this.executorSources.set(enforcementId, source);
+  }
+
+  registerBatch(
+    registrations: Array<{
+      enforcementId: EnforcementId;
+      executor: EnforcementExecutor;
+    }>
+  ): void {
+    for (const { enforcementId, executor } of registrations) {
+      this.register(enforcementId, executor);
+    }
+  }
+
+  unregister(enforcementId: EnforcementId): boolean {
+    return this.executors.delete(enforcementId);
+  }
+
+  hasExecutor(enforcementId: EnforcementId): boolean {
+    return this.executors.has(enforcementId);
+  }
+
+  getExecutor(enforcementId: EnforcementId): EnforcementExecutor | undefined {
+    return this.executors.get(enforcementId);
+  }
+
+  getRegistrations(): { id: EnforcementId; executor: EnforcementExecutor; registeredAt: Date; source?: string }[] {
+    return Array.from(this.executors.entries()).map(([id, executor]) => ({
+      id,
+      executor,
+      registeredAt: new Date(),
+      source: this.executorSources.get(id),
+    }));
+  }
+
+  skip(enforcementIds: EnforcementId[]): void {
+    for (const id of enforcementIds) {
+      this.skipEnforcements.add(id);
+    }
+  }
+
+  clearSkips(): void {
+    this.skipEnforcements.clear();
+  }
+
+  async intercept(
+    trigger: ConstraintTrigger,
+    context: ConstraintContext
+  ): Promise<InterceptionResult> {
+    if (!this.enabled) {
+      return {
+        passed: true,
+        constraints: [],
+        violations: [],
+        message: '拦截器已禁用',
+        interceptedAt: new Date(),
+      };
+    }
+
+    const result: InterceptionResult = {
+      passed: true,
+      constraints: [],
+      violations: [],
+      interceptedAt: new Date(),
+    };
+
+    const constraints = constraintChecker.getConstraints();
+    const allConstraints = [
+      ...Object.values(constraints.ironLaws),
+      ...Object.values(constraints.guidelines),
+      ...Object.values(constraints.tips),
+    ];
+
+    const applicableConstraints = allConstraints.filter(
+      (c) => normalizeTriggers<ConstraintTrigger>(c.trigger).includes(trigger)
+    );
+
+    const order: Record<ConstraintLevel, number> = { iron_law: 0, guideline: 1, tip: 2 };
+    const ordered = applicableConstraints.sort((a, b) => order[a.level] - order[b.level]);
+
+    for (const constraint of ordered) {
+      if (this.skipEnforcements.has(constraint.enforcement)) {
+        result.constraints.push({ constraint, skipped: true, skipReason: 'configured to skip' });
+        continue;
+      }
+
+      // Custom executor overrides built-in check
+      const executor = this.executors.get(constraint.enforcement);
+      let checkResult: ConstraintResult;
+
+      if (executor) {
+        const enforcementContext: EnforcementContext = { ...context, enforcementId: constraint.enforcement, constraint };
+        const start = Date.now();
+        try {
+          const enforcementResult = await executor.execute(enforcementContext);
+          enforcementResult.duration = Date.now() - start;
+          result.constraints.push({ constraint, enforcementResult });
+          checkResult = {
+            id: constraint.id, level: constraint.level,
+            satisfied: enforcementResult.passed,
+            message: enforcementResult.message,
+            checkedAt: new Date(),
+            constraint,
+          };
+        } catch (error) {
+          if (error instanceof ConstraintViolationError) throw error;
+          result.constraints.push({ constraint, enforcementResult: { passed: false, error: (error as Error).message, duration: Date.now() - start } });
+          checkResult = { id: constraint.id, level: constraint.level, satisfied: false, message: (error as Error).message, checkedAt: new Date(), constraint };
+        }
+      } else {
+        // Unified: constraint.check(context) delegates to checker
+        checkResult = await (constraint as any).check(context);
+        result.constraints.push({ constraint, enforcementResult: { passed: checkResult.satisfied, message: checkResult.message } });
+      }
+
+      if (!checkResult.satisfied) {
+        if (constraint.level === 'iron_law') {
+          result.passed = false;
+          result.violations.push(constraint);
+          throw new ConstraintViolationError(checkResult);
+        }
+        if (constraint.level === 'guideline') {
+          result.violations.push(constraint);
+        }
+      }
+    }
+
+    result.message = result.violations.length === 0 ? '✅ 拦截通过' : `❌ ${result.violations.length} 个约束违规`;
+    return result;
+  }
+
+  async claim(trigger: ConstraintTrigger, context: ConstraintContext): Promise<void> {
+    const result = await this.intercept(trigger, context);
+    if (!result.passed) {
+      throw new ConstraintViolationError({
+        id: result.violations[0]?.id || 'unknown',
+        level: 'iron_law',
+        satisfied: false,
+        message: result.message,
+        checkedAt: new Date(),
+      });
+    }
+  }
+
+  async canProceed(trigger: ConstraintTrigger, context: ConstraintContext): Promise<boolean> {
+    try {
+      return (await this.intercept(trigger, context)).passed;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export const constraintInterceptor = ConstraintInterceptor.getInstance();
+
+// 注册内置 executors
+import { registerDefaultExecutors } from './default-executors';
+registerDefaultExecutors();
+
+export async function interceptOperation(
+  trigger: ConstraintTrigger,
+  context: ConstraintContext
+): Promise<InterceptionResult> {
+  return constraintInterceptor.intercept(trigger, context);
+}
+
+export async function claimOperation(
+  trigger: ConstraintTrigger,
+  context: ConstraintContext
+): Promise<void> {
+  return constraintInterceptor.claim(trigger, context);
+}

package/src/core/constraints/prompt-injection.ts

@@ -0,0 +1,73 @@
+/**
+ * @deprecated 本模块已迁至 @dommaker/studio-shared。
+ *   从 harness v0.13 起，请改为 import { formatConstraintsForPrompt, AgentRole, ROLE_TRIGGERS } from '@dommaker/studio-shared';
+ *   本 re-export 将在下一个大版本移除。
+ *
+ * Constraint Prompt Injection — 将 harness 约束的前置声明注入 Agent prompt
+ */
+
+import { getAllConstraints } from './definitions';
+import type { ConstraintTrigger } from '../../types/constraint';
+
+export type AgentRole = 'analyst' | 'executor' | 'integration' | 'reviewer' | 'deploy' | 'monitor' | 'triage';
+
+const ROLE_TRIGGERS: Record<AgentRole, ConstraintTrigger[]> = {
+  analyst: ['design_request', 'api_change', 'code_implementation'],
+  executor: ['code_implementation', 'task_completion_claim', 'test_creation', 'api_change', 'file_modification', 'module_modification', 'module_creation'],
+  integration: ['code_implementation'],
+  reviewer: ['code_implementation'],
+  deploy: ['diagnosis'],
+  monitor: ['monitoring', 'diagnosis'],
+  triage: ['triage', 'diagnosis'],
+};
+
+export { ROLE_TRIGGERS };
+
+/**
+ * @deprecated 请使用 @dommaker/studio-shared 中的同名函数
+ */
+export function formatConstraintsForPrompt(role: AgentRole): string {
+  const allConstraints = getAllConstraints();
+  const triggers = ROLE_TRIGGERS[role] || [];
+  if (triggers.length === 0) return '';
+
+  const applicable = Object.values(allConstraints).filter(c => {
+    const ct = c.trigger;
+    if (Array.isArray(ct)) return ct.some(t => triggers.includes(t));
+    return triggers.includes(ct);
+  });
+
+  if (applicable.length === 0) return '';
+
+  const ironLaws = applicable.filter(c => c.level === 'iron_law');
+  const guidelines = applicable.filter(c => c.level === 'guideline');
+  const tips = applicable.filter(c => c.level === 'tip');
+
+  const lines: string[] = ['\n## 行为约束（前置声明）\n'];
+
+  if (ironLaws.length > 0) {
+    lines.push('### 铁律（绝对禁止，无例外）\n');
+    for (const c of ironLaws) {
+      if (c.promptInjection) lines.push(`- **${c.id}**: ${c.promptInjection}`);
+    }
+    lines.push('');
+  }
+
+  if (guidelines.length > 0) {
+    lines.push('### 指导原则（优先建议）\n');
+    for (const c of guidelines) {
+      if (c.promptInjection) lines.push(`- **${c.id}**: ${c.promptInjection}`);
+    }
+    lines.push('');
+  }
+
+  if (tips.length > 0) {
+    lines.push('### 提示\n');
+    for (const c of tips) {
+      if (c.promptInjection) lines.push(`- **${c.id}**: ${c.promptInjection}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/core/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 核心模块导出
+ */
+
+// 约束系统（三层：Iron Laws / Guidelines / Tips）
+// 包含向后兼容的 IronLaw* 导出
+export * from './constraints';
+
+export * from './validators';
+export * from './session';
+
+// Spec 验证器
+export { SpecValidator } from './spec/validator';
+export type {
+  SpecValidatorConfig,
+  SpecValidationResult,
+  BatchSpecValidationResult,
+  SpecSchemaDefinition,
+  SpecType,
+} from '../types/spec';
+
+// 项目配置加载器
+export * from './project-config-loader';

package/src/core/project-config-loader.ts

@@ -0,0 +1,252 @@
+/**
+ * 项目配置加载器
+ *
+ * 加载 .harness/config.yml 和 .harness/custom-constraints.yml
+ * 合并内置约束和项目自定义约束
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import type { Constraint, ConstraintTrigger } from '../types/constraint';
+import type {
+  ProjectConfig,
+  CustomConstraintDefinition,
+  MergedConstraintsConfig,
+} from '../types/project-config';
+import { IRON_LAWS, GUIDELINES, TIPS } from './constraints/definitions';
+
+/**
+ * 默认配置
+ */
+const DEFAULT_CONFIG: ProjectConfig = {
+  preset: 'standard',
+  custom_constraints_file: 'custom-constraints.yml',
+};
+
+/**
+ * 项目配置加载器
+ */
+export class ProjectConfigLoader {
+  private projectPath: string;
+  private config: ProjectConfig;
+  private customConstraints: Record<string, CustomConstraintDefinition>;
+
+  constructor(projectPath?: string) {
+    this.projectPath = projectPath || process.cwd();
+    this.config = { ...DEFAULT_CONFIG };
+    this.customConstraints = {};
+  }
+
+  /**
+   * 加载项目配置
+   */
+  load(): ProjectConfig {
+    // 1. 加载主配置
+    const configPath = path.join(this.projectPath, '.harness', 'config.yml');
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf-8');
+      const loaded = yaml.load(content) as ProjectConfig;
+      this.config = { ...DEFAULT_CONFIG, ...loaded };
+    }
+
+    // 2. 加载自定义约束
+    this.loadCustomConstraints();
+
+    return this.config;
+  }
+
+  /**
+   * 加载自定义约束
+   */
+  private loadCustomConstraints(): void {
+    // 方式 1：从单独文件加载
+    if (this.config.custom_constraints_file) {
+      const customPath = path.join(
+        this.projectPath,
+        '.harness',
+        this.config.custom_constraints_file
+      );
+      if (fs.existsSync(customPath)) {
+        const content = fs.readFileSync(customPath, 'utf-8');
+        const loaded = yaml.load(content) as {
+          custom_constraints?: Record<string, CustomConstraintDefinition>;
+        };
+        if (loaded.custom_constraints) {
+          this.customConstraints = { ...this.customConstraints, ...loaded.custom_constraints };
+        }
+      }
+    }
+
+    // 方式 2：从主配置文件中加载
+    if (this.config.custom_constraints) {
+      this.customConstraints = { ...this.customConstraints, ...this.config.custom_constraints };
+    }
+  }
+
+  /**
+   * 合并内置约束和自定义约束
+   */
+  mergeConstraints(): MergedConstraintsConfig {
+    const result: MergedConstraintsConfig = {
+      ironLaws: { ...IRON_LAWS },
+      guidelines: { ...GUIDELINES },
+      tips: { ...TIPS },
+      disabled: [],
+      custom: [],
+    };
+
+    // 1. 处理启用/禁用配置
+    if (this.config.constraints) {
+      for (const [constraintId, config] of Object.entries(this.config.constraints)) {
+        if (config.enabled === false) {
+          result.disabled.push(constraintId);
+          // 从对应层级中移除
+          delete result.ironLaws[constraintId];
+          delete result.guidelines[constraintId];
+          delete result.tips[constraintId];
+        }
+      }
+    }
+
+    // 2. 添加自定义约束
+    for (const [id, customDef] of Object.entries(this.customConstraints)) {
+      const extendExceptions = customDef.extend_exceptions;
+      const isExtendOnly =
+        !!extendExceptions && extendExceptions.length > 0 &&
+        !customDef.rule &&
+        !customDef.exceptions;
+
+      if (isExtendOnly) {
+        const builtIn = this.findBuiltInConstraint(id, result);
+        if (builtIn) {
+          const constraint = { ...builtIn };
+          constraint.exceptions = [
+            ...(builtIn.exceptions || []),
+            ...extendExceptions!,
+          ];
+          if (result.ironLaws[id]) result.ironLaws[id] = constraint;
+          if (result.guidelines[id]) result.guidelines[id] = constraint;
+          if (result.tips[id]) result.tips[id] = constraint;
+          continue;
+        }
+      }
+
+      const constraint = this.toConstraint(customDef, id);
+
+      if (extendExceptions && extendExceptions.length > 0) {
+        const builtIn = this.findBuiltInConstraint(id, result);
+        constraint.exceptions = [
+          ...(builtIn?.exceptions || []),
+          ...(customDef.exceptions || []),
+          ...extendExceptions,
+        ];
+      }
+
+      result.custom.push(id);
+
+      const level = customDef.level || 'guideline';
+      switch (level) {
+        case 'iron_law':
+          result.ironLaws[id] = constraint;
+          break;
+        case 'guideline':
+          result.guidelines[id] = constraint;
+          break;
+        case 'tip':
+          result.tips[id] = constraint;
+          break;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 在合并结果中查找内置约束
+   */
+  private findBuiltInConstraint(
+    id: string,
+    merged: MergedConstraintsConfig
+  ): Constraint | undefined {
+    return merged.ironLaws[id] || merged.guidelines[id] || merged.tips[id];
+  }
+
+  /**
+   * 将自定义约束定义转换为 Constraint
+   */
+  private toConstraint(def: CustomConstraintDefinition, defaultId: string): Constraint {
+    return {
+      id: def.id || defaultId,
+      level: def.level || 'guideline',
+      rule: def.rule || '',
+      message: def.message || '',
+      trigger: (def.trigger || 'manual') as ConstraintTrigger | ConstraintTrigger[],
+      exceptions: def.exceptions,
+      description: def.description,
+      enabled: def.enabled !== false,
+      enforcement: 'custom',
+    };
+  }
+
+  /**
+   * 获取当前配置
+   */
+  getConfig(): ProjectConfig {
+    return this.config;
+  }
+
+  /**
+   * 获取自定义约束
+   */
+  getCustomConstraints(): Record<string, CustomConstraintDefinition> {
+    return this.customConstraints;
+  }
+
+  /**
+   * 检查约束是否启用
+   */
+  isConstraintEnabled(constraintId: string): boolean {
+    // 1. 检查是否在禁用列表
+    if (this.config.constraints?.[constraintId]?.enabled === false) {
+      return false;
+    }
+
+    // 2. 检查自定义约束是否禁用
+    if (this.customConstraints[constraintId]?.enabled === false) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * 获取约束来源
+   */
+  getConstraintSource(constraintId: string): 'built-in' | 'custom' | 'disabled' {
+    if (this.config.constraints?.[constraintId]?.enabled === false) {
+      return 'disabled';
+    }
+    if (this.customConstraints[constraintId]) {
+      return 'custom';
+    }
+    return 'built-in';
+  }
+
+  /**
+   * 检查是否有自定义配置
+   */
+  hasCustomConfig(): boolean {
+    return (
+      Object.keys(this.customConstraints).length > 0 ||
+      (this.config.constraints !== undefined && Object.keys(this.config.constraints).length > 0)
+    );
+  }
+}
+
+/**
+ * 创建项目配置加载器
+ */
+export function createProjectConfigLoader(projectPath?: string): ProjectConfigLoader {
+  return new ProjectConfigLoader(projectPath);
+}