@dommaker/harness 0.13.0 → 0.13.2

package/src/hooks/pipeline.ts

@@ -0,0 +1,157 @@
+/**
+ * HookPipeline — hook 有序执行、错误隔离、采样
+ *
+ * 执行顺序：before hooks → consumer operation → after hooks
+ * 每个 hook 独立 try/catch，单个 hook 失败不影���其他 hook。
+ */
+
+import type {
+  HookDefinition,
+  HookPhase,
+  HookExecutionRecord,
+  PipelineResult,
+} from './types';
+import type { HookRegistry } from './registry';
+
+export class HookPipeline<C = unknown> {
+  private registry: HookRegistry<C, unknown>;
+
+  constructor(registry: HookRegistry<C, unknown>) {
+    this.registry = registry;
+  }
+
+  /**
+   * 执行指定 phase 的所有 enabled hook
+   *
+   * @param phase hook 时机
+   * @param context 传递给每个 hook 的上下文
+   * @returns 管线执行结果
+   */
+  async run(
+    phase: HookPhase,
+    context: C
+  ): Promise<PipelineResult> {
+    const hooks = this.registry.getEnabled(phase);
+    const records: HookExecutionRecord[] = [];
+    const blockedBy: string[] = [];
+    const warnings: string[] = [];
+    let passed = true;
+
+    for (const hook of hooks) {
+      const record = await this.executeOne(hook, context);
+      records.push(record);
+
+      if (!record.passed) {
+        if (hook.errorStrategy === 'block') {
+          passed = false;
+          blockedBy.push(hook.name);
+          break; // blocking hook 失败，停止执行后续 hook
+        }
+        if (hook.errorStrategy === 'warn') {
+          warnings.push(hook.name);
+        }
+        // 'ignore' 策略静默跳过
+      }
+    }
+
+    return { passed, records, blockedBy, warnings };
+  }
+
+  /**
+   * 执行 before + after 全套管线
+   *
+   * @param context 上下文
+   * @param operation 业务操作（在 before 和 after 之间执行）
+   * @returns 管线结果 + 操作结果
+   */
+  async runFull<R>(
+    context: C,
+    operation: () => Promise<R>
+  ): Promise<{ pipelineResult: PipelineResult; operationResult?: R }> {
+    // 1. Before hooks
+    const beforeResult = await this.run('before', context);
+    if (!beforeResult.passed) {
+      return { pipelineResult: beforeResult };
+    }
+
+    // 2. Execute operation
+    let operationResult: R;
+    try {
+      operationResult = await operation();
+    } catch (err) {
+      // 操作失败：仍执行 after hooks，但传递错误信息
+      const afterResult = await this.run('after', {
+        ...context,
+        _operationError: (err as Error).message,
+      } as unknown as C);
+      return {
+        pipelineResult: {
+          passed: false,
+          records: [...beforeResult.records, ...afterResult.records],
+          blockedBy: [...beforeResult.blockedBy, '_operation'],
+          warnings: [...beforeResult.warnings, ...afterResult.warnings],
+        },
+      };
+    }
+
+    // 3. After hooks
+    const afterResult = await this.run('after', context);
+    return {
+      pipelineResult: {
+        passed: beforeResult.passed && afterResult.passed,
+        records: [...beforeResult.records, ...afterResult.records],
+        blockedBy: [...beforeResult.blockedBy, ...afterResult.blockedBy],
+        warnings: [...beforeResult.warnings, ...afterResult.warnings],
+      },
+      operationResult,
+    };
+  }
+
+  /**
+   * 执行单个 hook（带采样和错误隔离）
+   */
+  private async executeOne(
+    hook: HookDefinition<C, unknown>,
+    context: C
+  ): Promise<HookExecutionRecord> {
+    const startedAt = Date.now();
+
+    // 采样检查
+    if (hook.sampleRate !== undefined && hook.sampleRate < 1) {
+      if (Math.random() > hook.sampleRate) {
+        return {
+          hookName: hook.name,
+          phase: hook.phase,
+          startedAt,
+          completedAt: Date.now(),
+          durationMs: 0,
+          passed: true,
+          sampled: true,
+        };
+      }
+    }
+
+    try {
+      const result = await hook.execute(context);
+      return {
+        hookName: hook.name,
+        phase: hook.phase,
+        startedAt,
+        completedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+        passed: result.passed !== false,
+        error: result.error,
+      };
+    } catch (err) {
+      return {
+        hookName: hook.name,
+        phase: hook.phase,
+        startedAt,
+        completedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+        passed: false,
+        error: (err as Error).message,
+      };
+    }
+  }
+}

package/src/hooks/registry.ts

@@ -0,0 +1,88 @@
+/**
+ * HookRegistry — hook 注册/注销/查询
+ *
+ * 纯簿记，无执行逻辑。线程不安全（Node.js 单线程）。
+ */
+
+import type { HookDefinition, HookPhase } from './types';
+
+export class HookRegistry<C = unknown, R = unknown> {
+  private hooks: Map<string, HookDefinition<C, R>> = new Map();
+
+  /**
+   * 注册 hook（同名覆盖）
+   */
+  register(hook: HookDefinition<C, R>): void {
+    this.hooks.set(hook.name, { ...hook });
+  }
+
+  /**
+   * 批量注册
+   */
+  registerAll(hooks: HookDefinition<C, R>[]): void {
+    for (const hook of hooks) {
+      this.register(hook);
+    }
+  }
+
+  /**
+   * 注销 hook
+   */
+  unregister(name: string): boolean {
+    return this.hooks.delete(name);
+  }
+
+  /**
+   * 获取单个 hook
+   */
+  get(name: string): HookDefinition<C, R> | undefined {
+    return this.hooks.get(name);
+  }
+
+  /**
+   * 获取指定时机、已启用的 hook，按优先级排序
+   */
+  getEnabled(phase: HookPhase): HookDefinition<C, R>[] {
+    return Array.from(this.hooks.values())
+      .filter(h => h.phase === phase && h.enabled !== false)
+      .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  }
+
+  /**
+   * 列出所有 hook 名称
+   */
+  listNames(): string[] {
+    return Array.from(this.hooks.keys());
+  }
+
+  /**
+   * 列出所有 hook（含禁用）
+   */
+  listAll(): HookDefinition<C, R>[] {
+    return Array.from(this.hooks.values());
+  }
+
+  /**
+   * 启用/禁用 hook
+   */
+  setEnabled(name: string, enabled: boolean): boolean {
+    const hook = this.hooks.get(name);
+    if (!hook) return false;
+    hook.enabled = enabled;
+    return true;
+  }
+
+  /**
+   * 清空所有 hook
+   */
+  clear(): void {
+    this.hooks.clear();
+  }
+
+  /**
+   * Hook 数量
+   */
+  get size(): number {
+    return this.hooks.size;
+  }
+}

package/src/hooks/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Hooks 类型定义
+ *
+ * 通用 hook 管线：注册、排序、错误隔离、采样。
+ * 无业务逻辑，consumer 自行定义 hook 名称和语义。
+ */
+
+/**
+ * Hook 执行时机
+ */
+export type HookPhase = 'before' | 'after' | 'around';
+
+/**
+ * Hook 错误处理策略
+ */
+export type HookErrorStrategy = 'block' | 'warn' | 'ignore';
+
+/**
+ * Hook 定义
+ *
+ * Consumer 自行选择 name（如 'beforeAgentExecute'），harness 只提供管线。
+ */
+export interface HookDefinition<C = unknown, R = unknown> {
+  /** Hook 唯一名称（consumer 定义语义） */
+  name: string;
+  /** 执行时机 */
+  phase: HookPhase;
+  /** 优先级（越小越先执行，默认 100） */
+  priority?: number;
+  /** 错误策略：block=阻断管线, warn=记录警告继续, ignore=静默跳过 */
+  errorStrategy?: HookErrorStrategy;
+  /** 采样率 0-1（1=100% 执行，0.1=10% 采样） */
+  sampleRate?: number;
+  /** 是否启用 */
+  enabled?: boolean;
+  /** Hook 执行函数 */
+  execute: (context: C) => Promise<HookResult<R>>;
+}
+
+/**
+ * Hook 执行结果
+ */
+export interface HookResult<R = unknown> {
+  /** 是否通过（blocking hook 必须返回 false 才阻断） */
+  passed: boolean;
+  /** 结果数据 */
+  data?: R;
+  /** 错误信息 */
+  error?: string;
+  /** 元数据（consumer 自行定义） */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Hook 执行记录
+ */
+export interface HookExecutionRecord {
+  hookName: string;
+  phase: HookPhase;
+  startedAt: number;
+  completedAt: number;
+  durationMs: number;
+  passed: boolean;
+  error?: string;
+  sampled?: boolean;
+}
+
+/**
+ * 管线执行结果
+ */
+export interface PipelineResult {
+  /** 是否全部通过（blocking hook 任一失败 = false） */
+  passed: boolean;
+  /** 各 hook 执行记录 */
+  records: HookExecutionRecord[];
+  /** 失败的 blocking hook 名称列表 */
+  blockedBy: string[];
+  /** 警告 hook 名称列表 */
+  warnings: string[];
+}

package/src/index.ts

@@ -0,0 +1,198 @@
+/**
+ * @dommaker/harness - 主入口
+ * 
+ * 通用工程约束框架
+ * 
+ * 三层约束体系：
+ * - Iron Laws：绝对禁止，无例外
+ * - Guidelines：优先建议，有例外
+ * - Tips：信息性提示，可忽略
+ * 
+ * 门禁系统：
+ * - PassesGate：测试门控
+ * - ReviewGate：审查门禁
+ * - SecurityGate：安全门禁
+ * - PerformanceGate：性能门禁
+ * - ContractGate：契约门禁
+ * - CheckpointValidator：检查点验证
+ */
+
+// ========================================
+// 类型导出
+// ========================================
+export * from './types';
+
+// ========================================
+// 核心功能导出
+// ========================================
+export * from './core';
+
+// ========================================
+// 门禁系统导出
+// ========================================
+export * from './gates';
+
+// ========================================
+// 监控导出
+// ========================================
+export * from './monitoring';
+
+// ========================================
+// 失败处理导出
+// ========================================
+export * from './failure';
+
+// ========================================
+// 架构约束导出
+// ========================================
+export * from './architecture/constraint-engine';
+export * from './architecture/cross-project-checker';
+
+// ========================================
+// Spec 检查导出
+// ========================================
+export * from './spec/annotation-checker';
+
+// ========================================
+// 上下文管理导出
+// ========================================
+export * from './context';
+
+// ========================================
+// 知识引擎导出
+// ========================================
+export * from './knowledge';
+
+// ========================================
+// 安全护栏导出
+// ========================================
+export * from './safety';
+
+// ========================================
+// 验证循环导出
+// ========================================
+export * from './verification';
+
+// ========================================
+// 约束分层导出
+// ========================================
+export * from './constraints';
+
+// ========================================
+// Dashboard 数据导出
+// ========================================
+export * from './dashboard';
+
+// ========================================
+// LLM 适配器导出
+// ========================================
+export * from './llm';
+
+// ========================================
+// 治理模块导出
+// ========================================
+export * from './governance';
+
+// ========================================
+// 工具注册表导出
+// ========================================
+export * from './tools';
+
+// ========================================
+// Hooks 管线导出（Phase 1）
+// ========================================
+export * from './hooks';
+
+// ========================================
+// Agent 生命周期导出
+// ========================================
+export * from './agents';
+
+// ========================================
+// 预设导出
+// ========================================
+export * from './presets';
+
+// ========================================
+// 约束进化导出
+// ========================================
+export * from './evolution';
+
+// ========================================
+// 便捷 API
+// ========================================
+
+import { constraintChecker } from './core/constraints/checker';
+import type { ConstraintContext, ConstraintCheckResult, ConstraintTrigger } from './types/constraint';
+import { constraintInterceptor } from './core/constraints/interceptor';
+import type { EnforcementExecutor, EnforcementId, InterceptionResult } from './types/enforcement';
+
+/** 约束拦截器单例，用于注册 enforcement executor 和拦截操作 */
+export const interceptor = constraintInterceptor;
+
+/**
+ * 拦截操作 — 在操作执行前检查约束
+ * @param trigger - 触发条件
+ * @param context - 约束上下文
+ * @returns 拦截结果（是否通过、违规列表）
+ */
+export async function interceptOperation(
+  trigger: ConstraintTrigger,
+  context: ConstraintContext
+): Promise<InterceptionResult> {
+  return constraintInterceptor.intercept(trigger, context);
+}
+
+/**
+ * 声明操作意图 — 声明即将执行的操作，但不执行检查
+ * @param trigger - 触发条件
+ * @param context - 约束上下文
+ */
+export async function claimOperation(
+  trigger: ConstraintTrigger,
+  context: ConstraintContext
+): Promise<void> {
+  return constraintInterceptor.claim(trigger, context);
+}
+
+/**
+ * 注册 enforcement executor — 将 enforcement ID 连接到实际检查逻辑
+ * @param enforcementId - enforcement ID（对应约束定义中的 enforcement 字段）
+ * @param executor - 执行器实现
+ * @param source - 注册来源（如 'builtin', 'plugin'）
+ */
+export function registerExecutor(
+  enforcementId: EnforcementId,
+  executor: EnforcementExecutor,
+  source?: string
+): void {
+  constraintInterceptor.register(enforcementId, executor, source);
+}
+
+/**
+ * 检查约束（三层）
+ *
+ * @param context - 约束上下文
+ * @param options.onTrace - 每条约束检查后的回调（用于记录 trace 到外部存储）
+ */
+export async function checkConstraints(
+  context: ConstraintContext,
+  options?: { onTrace?: (result: import('./types/constraint').ConstraintResult) => void }
+): Promise<ConstraintCheckResult> {
+  const result = await constraintChecker.checkConstraints(context);
+  if (options?.onTrace) {
+    for (const r of result.ironLaws) options.onTrace(r);
+    for (const r of result.guidelines) options.onTrace(r);
+    for (const r of result.tips) options.onTrace(r);
+  }
+  return result;
+}
+
+/**
+ * 执行前检查（仅 Iron Laws）
+ */
+export async function checkBeforeExecution(
+  context: ConstraintContext
+): Promise<void> {
+  return constraintChecker.beforeExecution(context);
+}

package/src/knowledge/CONTEXT.md

@@ -0,0 +1,29 @@
+# knowledge/
+
+## 职责
+知识引擎：知识存储(CRUD)、语义查询、引用追踪、质量检查(Linter)、生命周期管理、冷启动导入、健康评分。
+
+## 核心导出
+- `KnowledgeStore` — 知识条目 CRUD + 结构化存储
+- `KnowledgeQuery` — 语义搜索 + 类型/标签过滤
+- `KnowledgeLifecycle` — 知识生命周期: draft → candidate → validated → canonical → archived
+- `KnowledgeIngest` — 知识摄取引擎
+- `ReferenceTracker` — 知识引用关系图谱
+- `KnowledgeLinter` — 知识质量检查(完整性/一致性/时效性)
+- `ColdStartImporter` — 冷启动知识导入
+- `KnowledgeHealthScorer` — 知识健康评分
+- `KnowledgeLifecycleHooks` — 生命周期 hook
+
+## 依赖关系
+- 依赖 `src/types/` 知识相关类型
+- 依赖 `src/monitoring/` KnowledgeDoctor / KnowledgeEvolver
+- 被 `src/cli/commands/knowledge.ts` CLI 消费
+
+## 约定
+- 知识条目有明确的生命周期状态
+- 约束退化时自动写入 KnowledgeStore
+- Linter 检查完整性/一致性/时效性三个维度
+
+## 注意事项
+- Phase 1+4 实现的知识引擎核心
+- 约束"退化不删除"——降级时保留规则原文 + 退化原因 + 历史数据