autosnippet 3.2.8 → 3.2.9

package/lib/service/agent/core/ToolExecutionPipeline.js

@@ -0,0 +1,376 @@
+/**
+ * ToolExecutionPipeline — 工具执行的中间件管道
+ *
+ * 将 reactLoop 中 ~120 行的工具执行逻辑拆分为独立中间件:
+ *   before → execute → after
+ *
+ * 每个中间件负责一个横切关注点:
+ *   1. EventBusPublisher — 事件发布
+ *   2. ProgressEmitter — 进度回调
+ *   3. SafetyGate — SafetyPolicy 安全拦截
+ *   4. CacheCheck — MemoryCoordinator 缓存命中
+ *   5. ObservationRecord — 记忆记录
+ *   6. TrackerSignal — ExplorationTracker 信号收集
+ *   7. TraceRecord — ActiveContext 推理链记录
+ *   8. SubmitDedup — 提交去重
+ *
+ * @module core/ToolExecutionPipeline
+ */
+
+import { SafetyPolicy } from '../policies.js';
+
+/**
+ * @typedef {Object} ToolCall
+ * @property {string} name — 工具名称
+ * @property {Object} args — 工具参数
+ * @property {string} id — 调用 ID
+ */
+
+/**
+ * @typedef {Object} ToolExecContext
+ * @property {import('../AgentRuntime.js').AgentRuntime} runtime — 运行时实例
+ * @property {import('./LoopContext.js').LoopContext} loopCtx — 循环上下文
+ * @property {number} iteration — 当前迭代次数
+ */
+
+/**
+ * @typedef {Object} ToolMetadata
+ * @property {boolean} cacheHit — 是否缓存命中
+ * @property {boolean} blocked — 是否被安全策略拦截
+ * @property {boolean} isNew — 是否为新信息 (ExplorationTracker)
+ * @property {number} durationMs — 执行耗时
+ */
+
+/**
+ * @typedef {Object} ToolMiddleware
+ * @property {string} name — 中间件名称
+ * @property {Function} [before] — 前置钩子: (call, ctx, metadata) => { blocked?, result? } | void
+ * @property {Function} [after] — 后置钩子: (call, result, ctx, metadata) => void
+ */
+
+export class ToolExecutionPipeline {
+  /** @type {ToolMiddleware[]} */
+  #middlewares = [];
+
+  /**
+   * 注册中间件
+   * @param {ToolMiddleware} middleware
+   * @returns {this}
+   */
+  use(middleware) {
+    this.#middlewares.push(middleware);
+    return this;
+  }
+
+  /**
+   * 执行单个工具调用
+   *
+   * 执行流:
+   *   1. 依次调用 before 钩子 — 任一返回 blocked/result 则短路
+   *   2. 实际执行工具 (toolRegistry.execute)
+   *   3. 依次调用 after 钩子
+   *
+   * @param {ToolCall} call — { name, args, id }
+   * @param {ToolExecContext} context — { runtime, loopCtx, iteration }
+   * @returns {Promise<{ result: *, metadata: ToolMetadata }>}
+   */
+  async execute(call, context) {
+    let toolResult = null;
+    const metadata = { cacheHit: false, blocked: false, isNew: false, durationMs: 0 };
+
+    // ── before 阶段 ──
+    for (const mw of this.#middlewares) {
+      if (mw.before) {
+        const verdict = await mw.before(call, context, metadata);
+        if (verdict?.blocked) {
+          toolResult = verdict.result;
+          metadata.blocked = true;
+          break;
+        }
+        if (verdict?.result !== undefined) {
+          toolResult = verdict.result;
+          metadata.cacheHit = true;
+          break;
+        }
+      }
+    }
+
+    // ── execute 阶段 ──
+    if (toolResult === null) {
+      const t0 = Date.now();
+      try {
+        const { runtime, loopCtx } = context;
+        const safetyPolicy = runtime.policies.get?.(SafetyPolicy) || null;
+        toolResult = await runtime.toolRegistry.execute(call.name, call.args, {
+          agentId: runtime.id,
+          source: loopCtx.source || runtime.presetName,
+          container: runtime.container,
+          safetyPolicy,
+          projectRoot: runtime.projectRoot,
+          fileCache: runtime.fileCache,
+          lang: runtime.lang,
+          logger: runtime.logger || null,
+          aiProvider: runtime.aiProvider || null,
+          // ── bootstrap 维度上下文 (从 sharedState 透传) ──
+          _submittedTitles: loopCtx.sharedState?.submittedTitles || null,
+          _submittedPatterns: loopCtx.sharedState?.submittedPatterns || null,
+          _sharedState: loopCtx.sharedState || null,
+          _dimensionMeta: loopCtx.sharedState?._dimensionMeta || null,
+          _projectLanguage: loopCtx.sharedState?._projectLanguage || null,
+          _memoryCoordinator: loopCtx.memoryCoordinator || null,
+          _dimensionScopeId: loopCtx.sharedState?._dimensionScopeId || null,
+          _currentRound: loopCtx.iteration || 0,
+        });
+      } catch (err) {
+        toolResult = { error: err.message };
+      }
+      metadata.durationMs = Date.now() - t0;
+    }
+
+    // ── after 阶段 ──
+    for (const mw of this.#middlewares) {
+      if (mw.after) {
+        await mw.after(call, toolResult, context, metadata);
+      }
+    }
+
+    return { result: toolResult, metadata };
+  }
+}
+
+// ─────────────────────────────────────────────
+//  预置中间件
+// ─────────────────────────────────────────────
+
+/**
+ * AllowlistGate — 工具白名单守卫
+ *
+ * 防止 LLM hallucinate 不在当前 capability 允许列表中的工具调用。
+ * 从 LoopContext.toolSchemas 中提取允许的工具名列表，
+ * 拒绝不在列表中的调用（返回 error 提示）。
+ *
+ * before: 如果工具不在白名单中则短路返回 error
+ */
+export const allowlistGate = {
+  name: 'allowlistGate',
+  before(call, ctx) {
+    const schemas = ctx.loopCtx?.toolSchemas;
+    // 如果没有 schema 列表（全工具模式），跳过检查
+    if (!schemas || schemas.length === 0) return;
+
+    const allowedNames = new Set(schemas.map(s => s.name || s.function?.name));
+    if (!allowedNames.has(call.name)) {
+      ctx.runtime.logger.warn(
+        `[ToolPipeline] ⛔ Tool "${call.name}" not in allowlist — blocked (hallucinated call)`
+      );
+      return {
+        blocked: true,
+        result: {
+          error: `工具 "${call.name}" 不可用。当前可用工具: ${[...allowedNames].slice(0, 5).join(', ')}${allowedNames.size > 5 ? '...' : ''}`,
+        },
+      };
+    }
+  },
+};
+
+/**
+ * SafetyGate — SafetyPolicy 安全拦截
+ *
+ * before: 如果策略拒绝则短路返回 error
+ */
+export const safetyGate = {
+  name: 'safetyGate',
+  before(call, ctx) {
+    const check = ctx.runtime.policies.validateToolCall(call.name, call.args);
+    if (!check.ok) {
+      ctx.runtime.logger.warn(
+        `[ToolPipeline] Tool blocked by Policy: ${call.name} — ${check.reason}`
+      );
+      return { blocked: true, result: { error: check.reason } };
+    }
+  },
+};
+
+/**
+ * CacheCheck — MemoryCoordinator 缓存命中
+ *
+ * before: 如果缓存命中则短路返回缓存值
+ */
+export const cacheCheck = {
+  name: 'cacheCheck',
+  before(call, ctx) {
+    const mc = ctx.loopCtx.memoryCoordinator;
+    if (!mc) return;
+    const cached = mc.getCachedResult?.(call.name, call.args);
+    if (cached !== null && cached !== undefined) {
+      ctx.runtime.logger.info(
+        `[ToolPipeline] 🔧 CACHE HIT: ${call.name} → skipped execution`
+      );
+      return { result: cached };
+    }
+  },
+};
+
+/**
+ * ObservationRecord — MemoryCoordinator 观察记录
+ *
+ * after: 记录工具执行观察
+ */
+export const observationRecord = {
+  name: 'observationRecord',
+  after(call, result, ctx, meta) {
+    ctx.loopCtx.memoryCoordinator?.recordObservation?.(
+      call.name, call.args, result, ctx.iteration, meta.cacheHit
+    );
+  },
+};
+
+/**
+ * TrackerSignal — ExplorationTracker 信号收集
+ *
+ * after: 记录工具调用信号，更新 isNew 标记
+ */
+export const trackerSignal = {
+  name: 'trackerSignal',
+  after(call, result, ctx, meta) {
+    if (ctx.loopCtx.tracker) {
+      const r = ctx.loopCtx.tracker.recordToolCall(call.name, call.args, result);
+      meta.isNew = r.isNew;
+    }
+  },
+};
+
+/**
+ * TraceRecord — ActiveContext 推理链记录
+ *
+ * after: 记录 Action + Observation 到推理链
+ */
+export const traceRecord = {
+  name: 'traceRecord',
+  after(call, result, ctx, meta) {
+    ctx.loopCtx.trace?.recordToolCall(call.name, call.args, result, meta.isNew);
+  },
+};
+
+/**
+ * SubmitDedup — 提交去重
+ *
+ * after: 检查并标记重复提交 (修改 metadata)
+ */
+export const submitDedup = {
+  name: 'submitDedup',
+  after(call, result, ctx, meta) {
+    const { sharedState } = ctx.loopCtx;
+    if (!sharedState) return;
+    if (call.name !== 'submit_knowledge' && call.name !== 'submit_with_check') return;
+
+    const title = call.args?.title || call.args?.category || '';
+    const isRejected = typeof result === 'object' && result?.status === 'rejected';
+    const isError = typeof result === 'object' && (result?.error || result?.status === 'error');
+
+    if (!isRejected && !isError && sharedState.submittedTitles) {
+      const normalizedTitle = title.toLowerCase().trim();
+      if (sharedState.submittedTitles.has(normalizedTitle)) {
+        meta.dedupMessage = `⚠ 重复提交: "${title}" 已存在。`;
+        ctx.runtime.logger.info(`[ToolPipeline] 🔁 duplicate: "${title}"`);
+      } else {
+        sharedState.submittedTitles.add(normalizedTitle);
+        // 模式指纹去重
+        const pattern = call.args?.content?.pattern || '';
+        if (pattern.length >= 30 && sharedState.submittedPatterns) {
+          const fp = pattern
+            .replace(/\/\/[^\n]*/g, '')
+            .replace(/\/\*[\s\S]*?\*\//g, '')
+            .replace(/[\s]+/g, '')
+            .toLowerCase()
+            .slice(0, 200);
+          if (fp.length >= 20) {
+            sharedState.submittedPatterns.add(fp);
+          }
+        }
+        meta.isSubmit = true;
+      }
+    }
+  },
+};
+
+/**
+ * ProgressEmitter — 进度回调 (可选，需 runtime.emitProgress 为 public)
+ *
+ * NOTE: 默认管道不包含此中间件，因为 tool_end 事件需要 resultStr.length，
+ * 而 resultStr 在管道外部计算。由 #processToolCalls 直接处理。
+ */
+export const progressEmitter = {
+  name: 'progressEmitter',
+  before(call, ctx) {
+    ctx.runtime.emitProgress?.('tool_call', { tool: call.name, args: call.args });
+  },
+  after(call, result, ctx, meta) {
+    ctx.runtime.emitProgress?.('tool_end', {
+      tool: call.name,
+      duration: meta.durationMs,
+      status: result?.error ? 'error' : 'ok',
+      error: result?.error || undefined,
+    });
+  },
+};
+
+/**
+ * EventBusPublisher — EventBus 事件发布 (可选)
+ *
+ * NOTE: 默认管道不包含此中间件。由 #processToolCalls 直接处理，
+ * 与原始 reactLoop 保持完全一致的事件顺序。
+ */
+export const eventBusPublisher = {
+  name: 'eventBusPublisher',
+  before(call, ctx) {
+    if (ctx.runtime.bus?.publish) {
+      ctx.runtime.bus.publish('tool:call:start', {
+        agentId: ctx.runtime.id,
+        tool: call.name,
+      }, { source: ctx.runtime.id });
+    }
+  },
+  after(call, result, ctx, meta) {
+    if (ctx.runtime.bus?.publish) {
+      ctx.runtime.bus.publish('tool:call:end', {
+        agentId: ctx.runtime.id,
+        tool: call.name,
+        durationMs: meta.durationMs,
+        success: !result?.error,
+      }, { source: ctx.runtime.id });
+    }
+  },
+};
+
+// ─────────────────────────────────────────────
+//  Factory helper
+// ─────────────────────────────────────────────
+
+/**
+ * 创建预配置的工具执行管道
+ *
+ * 中间件顺序:
+ *   1. safetyGate (安全拦截 — 可短路)
+ *   2. cacheCheck (缓存检查 — 可短路)
+ *   3. observationRecord (记忆记录)
+ *   4. trackerSignal (信号收集)
+ *   5. traceRecord (推理链)
+ *   6. submitDedup (提交去重)
+ *
+ * NOTE: eventBusPublisher 和 progressEmitter 不在默认管道中，
+ * 由 #processToolCalls 直接处理，以保持与原始 reactLoop 完全一致的事件顺序
+ * (progress_end 需要 resultStr.length，在管道外计算)。
+ *
+ * @returns {ToolExecutionPipeline}
+ */
+export function createToolPipeline() {
+  return new ToolExecutionPipeline()
+    .use(allowlistGate)
+    .use(safetyGate)
+    .use(cacheCheck)
+    .use(observationRecord)
+    .use(trackerSignal)
+    .use(traceRecord)
+    .use(submitDedup);
+}

package/lib/service/{chat → agent/domain}/ChatAgentTasks.js

@@ -1,8 +1,8 @@
 /**
- * ChatAgentTasks — ChatAgent 预定义任务方法（从 ChatAgent.js 提取）
+ * ChatAgentTasks — Agent 预定义任务方法
  *
- * 每个任务接收 context 对象: { executeTool, aiProvider, container, logger }
- * - executeTool(toolName, params) — 执行指定工具
+ * 每个任务接收 context 对象: { invokeAgent, aiProvider, container, logger }
+ * - invokeAgent(toolName, params) — 直接执行工具 handler（纯数据工具）
  * - aiProvider — AI Provider 实例
  * - container — ServiceContainer
  * - logger — Logger 实例
@@ -14,10 +14,10 @@
  * 2. 顺便返回质量评估建议
  */
 export async function taskCheckAndSubmit(context, { candidate, projectRoot }) {
-  const { executeTool, aiProvider } = context;
+  const { invokeAgent, aiProvider } = context;
 
   // Step 1: 查重
-  const duplicates = await executeTool('check_duplicate', {
+  const duplicates = await invokeAgent('check_duplicate', {
     candidate,
     projectRoot,
     threshold: 0.5,
@@ -61,102 +61,23 @@ ${highSim.map((s) => `- ${s.title} (相似度: ${s.similarity})`).join('\n')}
 
 /**
  * 任务: 批量发现 Recipe 间的知识图谱关系
- * 遍历所有 Recipe，两两分析可能的关系
+ * 委托给 AgentFactory.scanKnowledge (Agent 多轮推理)
  */
 export async function taskDiscoverAllRelations(context, { batchSize = 20 } = {}) {
-  const { executeTool, aiProvider, container, logger } = context;
-
-  const knowledgeService = container.get('knowledgeService');
-  if (!knowledgeService) {
-    throw new Error('KnowledgeService 不可用');
-  }
-
-  if (!aiProvider) {
-    throw new Error('AI Provider 未配置，请先设置 API Key');
-  }
-
-  // 获取所有活跃知识条目
-  const { items = [], data = [] } = await knowledgeService.list(
-    { lifecycle: 'active' },
-    { page: 1, pageSize: 500 }
-  );
-  const recipes = items.length > 0 ? items : data;
-  if (recipes.length < 2) {
-    return {
-      discovered: 0,
-      totalPairs: 0,
-      message: `只有 ${recipes.length} 条 Recipe，至少需要 2 条`,
-    };
-  }
-
-  // 按 batch 分组分析
-  const pairs = [];
-  for (let i = 0; i < recipes.length; i++) {
-    for (let j = i + 1; j < recipes.length; j++) {
-      pairs.push([recipes[i], recipes[j]]);
-    }
-  }
-
-  let discovered = 0;
-  const results = [];
-  let batchErrors = 0;
-
-  // 分批处理，单批失败不终止整体
-  for (let b = 0; b < pairs.length; b += batchSize) {
-    const batch = pairs.slice(b, b + batchSize);
-    try {
-      const result = await executeTool('discover_relations', {
-        recipePairs: batch.map(([a, b]) => ({
-          a: {
-            id: a.id,
-            title: a.title,
-            category: a.category,
-            language: a.language,
-            code: String(a.content || a.code || '').substring(0, 500),
-          },
-          b: {
-            id: b.id,
-            title: b.title,
-            category: b.category,
-            language: b.language,
-            code: String(b.content || b.code || '').substring(0, 500),
-          },
-        })),
-      });
-
-      if (result.error) {
-        batchErrors++;
-        logger.warn(
-          `[DiscoverRelations] Batch ${Math.floor(b / batchSize) + 1} error: ${result.error}`
-        );
-        continue;
-      }
-      if (result.relations) {
-        discovered += result.relations.length;
-        results.push(...result.relations);
-      }
-    } catch (err) {
-      batchErrors++;
-      logger.warn(
-        `[DiscoverRelations] Batch ${Math.floor(b / batchSize) + 1} threw: ${err.message}`
-      );
-    }
-  }
-
-  return {
-    discovered,
-    totalPairs: pairs.length,
-    totalBatches: Math.ceil(pairs.length / batchSize),
-    batchErrors,
-    relations: results,
-  };
+  const { container } = context;
+  const agentFactory = container.get('agentFactory');
+  return agentFactory.scanKnowledge({
+    label: 'knowledge-graph',
+    files: [],
+    task: 'relations',
+  });
 }
 
 /**
  * 任务: 批量 AI 补全候选语义字段
  */
 export async function taskFullEnrich(context, { status = 'pending', maxCount = 50 } = {}) {
-  const { executeTool, container } = context;
+  const { invokeAgent, container } = context;
 
   const knowledgeService = container.get('knowledgeService');
 
@@ -179,7 +100,7 @@ export async function taskFullEnrich(context, { status = 'pending', maxCount = 5
     return { enriched: 0, message: 'All candidates already enriched' };
   }
 
-  const result = await executeTool('enrich_candidate', {
+  const result = await invokeAgent('enrich_candidate', {
     candidateIds: needEnrich.map((c) => c.id).slice(0, 20),
   });
 
@@ -191,7 +112,7 @@ export async function taskFullEnrich(context, { status = 'pending', maxCount = 5
  * 对活跃 Recipe 逐个评分，返回低于阈值的列表
  */
 export async function taskQualityAudit(context, { threshold = 0.6, maxCount = 100 } = {}) {
-  const { executeTool, container } = context;
+  const { invokeAgent, container } = context;
 
   const knowledgeService = container.get('knowledgeService');
 
@@ -208,7 +129,7 @@ export async function taskQualityAudit(context, { threshold = 0.6, maxCount = 10
   const gradeDistribution = { A: 0, B: 0, C: 0, D: 0, F: 0 };
 
   for (const recipe of recipes) {
-    const scoreResult = await executeTool('quality_score', { recipe });
+    const scoreResult = await invokeAgent('quality_score', { recipe });
     if (scoreResult.grade) {
       gradeDistribution[scoreResult.grade] = (gradeDistribution[scoreResult.grade] || 0) + 1;
     }
@@ -239,14 +160,14 @@ export async function taskQualityAudit(context, { threshold = 0.6, maxCount = 10
  * 对代码运行全部 Guard 规则 + 生成修复建议
  */
 export async function taskGuardFullScan(context, { code, language, filePath } = {}) {
-  const { executeTool, aiProvider } = context;
+  const { invokeAgent, aiProvider } = context;
 
   if (!code) {
     return { error: 'code is required' };
   }
 
   // Step 1: 静态检查
-  const checkResult = await executeTool('guard_check_code', {
+  const checkResult = await invokeAgent('guard_check_code', {
     code,
     language: language || 'unknown',
     scope: 'project',

package/lib/service/{chat → agent/domain}/EpisodicConsolidator.js

@@ -2,18 +2,18 @@
  * EpisodicConsolidator — Episodic → Semantic 固化引擎
  *
  * Bootstrap 完成后，将 SessionStore (Tier 2) 中的维度分析结果
- * 提炼为结构化记忆，固化到 ProjectSemanticMemory (Tier 3)。
+ * 提炼为结构化记忆，固化到 PersistentMemory (Tier 3)。
  *
  * 固化策略 (规则化，无需额外 AI 调用):
  *   1. 从每个维度的 findings 提取 fact 记忆
  *   2. 从 Tier Reflections 的 crossDimensionPatterns 提取 insight 记忆
  *   3. 从 analysisText 中提取项目级别事实 (正则匹配)
- *   4. 使用 ProjectSemanticMemory.consolidate() 进行去重和合并
+ *   4. 使用 PersistentMemory.consolidate() 进行去重和合并
  *
  * @module EpisodicConsolidator
  */
 
-import Logger from '../../infrastructure/logging/Logger.js';
+import Logger from '../../../infrastructure/logging/Logger.js';
 
 // ──────────────────────────────────────────────────────────────
 // 正则: 从分析文本中提取陈述性知识
@@ -57,14 +57,14 @@ const INSIGHT_PATTERNS = [
 // ──────────────────────────────────────────────────────────────
 
 export class EpisodicConsolidator {
-  /** @type {import('./ProjectSemanticMemory.js').ProjectSemanticMemory} */
+  /** @type {import('../memory/PersistentMemory.js').PersistentMemory} */
   #semanticMemory;
 
   /** @type {import('../../infrastructure/logging/Logger.js').default} */
   #logger;
 
   /**
-   * @param {import('./ProjectSemanticMemory.js').ProjectSemanticMemory} semanticMemory
+   * @param {import('../memory/PersistentMemory.js').PersistentMemory} semanticMemory
    * @param {object} [opts]
    * @param {object} [opts.logger]
    */
@@ -74,9 +74,9 @@ export class EpisodicConsolidator {
   }
 
   /**
-   * 执行固化: SessionStore → ProjectSemanticMemory
+   * 执行固化: SessionStore → PersistentMemory
    *
-   * @param {import('./memory/SessionStore.js').SessionStore} sessionStore
+   * @param {import('../memory/SessionStore.js').SessionStore} sessionStore
    * @param {object} [opts]
    * @param {string} [opts.bootstrapSession] — Bootstrap session ID
    * @param {boolean} [opts.clearPrevious=false] — 是否先清除旧的 bootstrap 记忆

package/lib/service/{chat → agent/domain}/EvidenceCollector.js

@@ -1,8 +1,10 @@
 /**
  * EvidenceCollector.js — 从 Analyst 工具调用中收集结构化证据
  *
- * HandoffProtocol v2 核心组件: 将 Analyst 的 toolCall 序列转化为
- * 类型化的证据地图、探索日志和负空间信号，供 Producer 直接引用。
+ * Bootstrap 质量门控核心组件: 将 Analyst 阶段的 toolCall 序列转化为
+ * 类型化的证据地图、探索日志和负空间信号，供 Producer 阶段直接引用。
+ *
+ * 被 bootstrap-gate.js (buildAnalysisArtifact) 调用。
  *
  * 设计原则:
  * - 不保留原始工具返回值 (体积过大)