autosnippet 3.2.8 → 3.2.9

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

@@ -0,0 +1,170 @@
+/**
+ * LoopContext — reactLoop 单次执行的完整状态
+ *
+ * 封装原 reactLoop 内散落的 10+ 局部变量:
+ *   - 注入依赖 (messages, tracker, trace, memoryCoordinator, sharedState)
+ *   - 循环状态 (iteration, lastReply, toolCalls, tokenUsage)
+ *   - 错误恢复 (consecutiveAiErrors, consecutiveEmptyResponses)
+ *   - 配置 (source, budget, capabilities, baseSystemPrompt, toolSchemas, prompt)
+ *
+ * 使 reactLoop 的提取方法只需接收一个 ctx 参数。
+ *
+ * @module core/LoopContext
+ */
+
+/**
+ * @typedef {Object} LoopContextConfig
+ * @property {import('./MessageAdapter.js').MessageAdapter} messages — 统一消息适配器
+ * @property {Object|null} [tracker] — ExplorationTracker 实例
+ * @property {Object|null} [trace] — ActiveContext 实例
+ * @property {Object|null} [memoryCoordinator] — MemoryCoordinator 实例
+ * @property {Object|null} [sharedState] — 共享状态 { submittedTitles, submittedPatterns }
+ * @property {string} [source] — 'user' | 'system'
+ * @property {Object} budget — 预算配置
+ * @property {import('../capabilities.js').Capability[]} capabilities — 本轮使用的 capabilities
+ * @property {string} baseSystemPrompt — 基础系统提示词
+ * @property {Array} toolSchemas — 工具 schema 列表
+ * @property {string} prompt — 原始用户提示
+ * @property {Function|null} [onToolCall] — 本轮工具调用钩子
+ * @property {Object} [context] — 额外上下文
+ * @property {import('../context/ContextWindow.js').ContextWindow|null} [contextWindow] — 原始 ContextWindow (供 forced-summary 等外部逻辑)
+ */
+
+export class LoopContext {
+  // ─── 注入依赖 ───
+
+  /** @type {import('./MessageAdapter.js').MessageAdapter} 统一消息适配器 */
+  messages;
+
+  /** @type {Object|null} ExplorationTracker 实例 */
+  tracker;
+
+  /** @type {Object|null} ActiveContext 实例 */
+  trace;
+
+  /** @type {Object|null} MemoryCoordinator 实例 */
+  memoryCoordinator;
+
+  /** @type {Object|null} 共享状态 */
+  sharedState;
+
+  // ─── 循环状态 ───
+
+  /** @type {number} 当前迭代次数 */
+  iteration = 0;
+
+  /** @type {string} 最终回复文本 */
+  lastReply = '';
+
+  /** @type {Array} 本轮工具调用记录 */
+  toolCalls = [];
+
+  /** @type {{input: number, output: number}} 本轮 token 用量 */
+  tokenUsage = { input: 0, output: 0 };
+
+  /** @type {number} 循环开始时间戳 */
+  loopStartTime = 0;
+
+  // ─── 错误恢复 ───
+
+  /** @type {number} 连续 AI 错误计数 (2-strike 策略) */
+  consecutiveAiErrors = 0;
+
+  /** @type {number} 连续空响应计数 */
+  consecutiveEmptyResponses = 0;
+
+  // ─── 配置 (只读) ───
+
+  /** @type {string} 来源 'user' | 'system' */
+  source;
+
+  /** @type {Object} 预算配置 */
+  budget;
+
+  /** @type {import('../capabilities.js').Capability[]} */
+  capabilities;
+
+  /** @type {string} 基础系统提示词 */
+  baseSystemPrompt;
+
+  /** @type {Array} 工具 schemas */
+  toolSchemas;
+
+  /** @type {string} 原始用户提示 */
+  prompt;
+
+  /** @type {Function|null} 工具调用钩子 */
+  onToolCall;
+
+  /** @type {Object} 额外上下文 */
+  context;
+
+  /** @type {import('../../chat/ContextWindow.js').ContextWindow|null} 原始 ContextWindow 引用 */
+  contextWindow;
+
+  /** @type {string|null} 首轮 toolChoice 覆盖 ('required'/'auto'/'none') */
+  toolChoiceOverride;
+
+  /**
+   * @param {LoopContextConfig} config
+   */
+  constructor(config) {
+    this.messages = config.messages;
+    this.tracker = config.tracker || null;
+    this.trace = config.trace || null;
+    this.memoryCoordinator = config.memoryCoordinator || null;
+    this.sharedState = config.sharedState || null;
+    this.source = config.source || 'user';
+    this.budget = config.budget;
+    this.capabilities = config.capabilities;
+    this.baseSystemPrompt = config.baseSystemPrompt;
+    this.toolSchemas = config.toolSchemas;
+    this.prompt = config.prompt;
+    this.onToolCall = config.onToolCall || null;
+    this.context = config.context || {};
+    this.contextWindow = config.contextWindow || null;
+    this.toolChoiceOverride = config.toolChoiceOverride || null;
+    this.loopStartTime = Date.now();
+  }
+
+  // ─── 计算属性 ───
+
+  /** 是否为 system 场景 */
+  get isSystem() {
+    return this.source === 'system';
+  }
+
+  /** 最大迭代数 */
+  get maxIterations() {
+    return this.budget.maxIterations || 20;
+  }
+
+  // ─── Token 累计辅助 ───
+
+  /**
+   * 累加 token 用量到循环级统计
+   * @param {Object} usage — { inputTokens, outputTokens }
+   */
+  addTokenUsage(usage) {
+    if (!usage) return;
+    const inTok = usage.inputTokens || 0;
+    const outTok = usage.outputTokens || 0;
+    this.tokenUsage.input += inTok;
+    this.tokenUsage.output += outTok;
+  }
+
+  // ─── 结果构建 ───
+
+  /**
+   * 构建循环返回值
+   * @returns {{ reply: string, toolCalls: Array, tokenUsage: Object, iterations: number }}
+   */
+  buildResult() {
+    return {
+      reply: this.lastReply,
+      toolCalls: [...this.toolCalls],
+      tokenUsage: { ...this.tokenUsage },
+      iterations: this.iteration,
+    };
+  }
+}

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

@@ -0,0 +1,223 @@
+/**
+ * MessageAdapter — 统一消息操作接口
+ *
+ * 消除 reactLoop 内的 useCtxWin 双模式分支:
+ *   - ContextWindowAdapter: 委托给 ContextWindow 实例 (bootstrap/system 场景)
+ *   - SimpleArrayAdapter: 裸数组模式 (对话场景)
+ *
+ * 两个实现对外暴露完全相同的 API，
+ * 使得 reactLoop 及其提取方法无需关心底层消息存储方式。
+ *
+ * @module core/MessageAdapter
+ */
+
+import { limitToolResult } from '../context/ContextWindow.js';
+
+// ─────────────────────────────────────────────
+//  Base class (接口定义 + JSDoc)
+// ─────────────────────────────────────────────
+
+/**
+ * @abstract
+ */
+export class MessageAdapter {
+  /**
+   * 追加用户消息
+   * @param {string} text
+   */
+  appendUserMessage(_text) { throw new Error('not implemented'); }
+
+  /**
+   * 追加助手纯文本回复
+   * @param {string} text
+   */
+  appendAssistantText(_text) { throw new Error('not implemented'); }
+
+  /**
+   * 追加助手带工具调用的回复
+   * @param {string|null} text
+   * @param {Array} calls — functionCalls 数组
+   */
+  appendAssistantWithToolCalls(_text, _calls) { throw new Error('not implemented'); }
+
+  /**
+   * 追加工具执行结果
+   * @param {string} callId
+   * @param {string} name
+   * @param {string} content
+   */
+  appendToolResult(_callId, _name, _content) { throw new Error('not implemented'); }
+
+  /**
+   * 追加系统/用户 nudge 消息
+   * @param {string} text
+   */
+  appendUserNudge(_text) { throw new Error('not implemented'); }
+
+  /**
+   * 导出当前消息列表 (供 LLM 调用)
+   * @returns {Array<{role: string, content: string}>}
+   */
+  toMessages() { throw new Error('not implemented'); }
+
+  /**
+   * 重置到仅保留初始 prompt (错误恢复)
+   */
+  resetToPromptOnly() { throw new Error('not implemented'); }
+
+  /**
+   * 获取工具结果限额 (字符数)
+   * @returns {number}
+   */
+  getToolResultQuota() { throw new Error('not implemented'); }
+
+  /**
+   * 压缩检查 — 如果消息过多则自动压缩
+   * @returns {{ level: number, removed: number }}
+   */
+  compactIfNeeded() { throw new Error('not implemented'); }
+
+  /**
+   * 格式化工具结果字符串 (统一 limitToolResult 调用)
+   * @param {string} toolName
+   * @param {*} rawResult — 工具原始返回值
+   * @returns {string}
+   */
+  formatToolResult(toolName, rawResult) {
+    const quota = this.getToolResultQuota();
+    return limitToolResult(toolName, rawResult, quota);
+  }
+}
+
+// ─────────────────────────────────────────────
+//  ContextWindowAdapter — 委托给 ContextWindow
+// ─────────────────────────────────────────────
+
+/**
+ * 委托所有消息操作给 ContextWindow 实例。
+ *
+ * 用于 bootstrap / system 场景，
+ * ContextWindow 提供三级递进压缩 + 动态 token 预算。
+ */
+export class ContextWindowAdapter extends MessageAdapter {
+  /** @type {import('../context/ContextWindow.js').ContextWindow} */
+  #ctxWin;
+
+  /**
+   * @param {import('../context/ContextWindow.js').ContextWindow} ctxWin
+   */
+  constructor(ctxWin) {
+    super();
+    this.#ctxWin = ctxWin;
+  }
+
+  /** 获取底层 ContextWindow 实例 (供 forced-summary 等外部逻辑使用) */
+  get contextWindow() {
+    return this.#ctxWin;
+  }
+
+  appendUserMessage(text) {
+    this.#ctxWin.appendUserMessage(text);
+  }
+
+  appendAssistantText(text) {
+    this.#ctxWin.appendAssistantText(text);
+  }
+
+  appendAssistantWithToolCalls(text, calls) {
+    this.#ctxWin.appendAssistantWithToolCalls(text, calls);
+  }
+
+  appendToolResult(callId, name, content) {
+    this.#ctxWin.appendToolResult(callId, name, content);
+  }
+
+  appendUserNudge(text) {
+    this.#ctxWin.appendUserNudge(text);
+  }
+
+  toMessages() {
+    return this.#ctxWin.toMessages();
+  }
+
+  resetToPromptOnly() {
+    this.#ctxWin.resetToPromptOnly();
+  }
+
+  getToolResultQuota() {
+    return this.#ctxWin.getToolResultQuota();
+  }
+
+  compactIfNeeded() {
+    return this.#ctxWin.compactIfNeeded();
+  }
+}
+
+// ─────────────────────────────────────────────
+//  SimpleArrayAdapter — 裸数组模式
+// ─────────────────────────────────────────────
+
+/**
+ * 简单数组消息管理 — 对话场景。
+ *
+ * 不做任何压缩，getToolResultQuota 返回固定 8000。
+ * compactIfNeeded 始终返回 no-op。
+ */
+export class SimpleArrayAdapter extends MessageAdapter {
+  /** @type {Array<Object>} */
+  #messages = [];
+
+  appendUserMessage(text) {
+    this.#messages.push({ role: 'user', content: text });
+  }
+
+  appendAssistantText(text) {
+    this.#messages.push({ role: 'assistant', content: text });
+  }
+
+  appendAssistantWithToolCalls(text, calls) {
+    this.#messages.push({ role: 'assistant', content: text, toolCalls: calls });
+  }
+
+  appendToolResult(callId, name, content) {
+    this.#messages.push({ role: 'tool', toolCallId: callId, name, content });
+  }
+
+  appendUserNudge(text) {
+    this.#messages.push({ role: 'user', content: text });
+  }
+
+  toMessages() {
+    return [...this.#messages];
+  }
+
+  resetToPromptOnly() {
+    const first = this.#messages[0];
+    this.#messages.length = 0;
+    if (first) this.#messages.push(first);
+  }
+
+  getToolResultQuota() {
+    return { maxChars: 8000, maxMatches: 20 };
+  }
+
+  compactIfNeeded() {
+    return { level: 0, removed: 0 };
+  }
+}
+
+// ─────────────────────────────────────────────
+//  Factory helper
+// ─────────────────────────────────────────────
+
+/**
+ * 根据是否提供 contextWindow 创建对应适配器
+ * @param {import('../context/ContextWindow.js').ContextWindow|null|undefined} contextWindow
+ * @returns {MessageAdapter}
+ */
+export function createMessageAdapter(contextWindow) {
+  if (contextWindow) {
+    return new ContextWindowAdapter(contextWindow);
+  }
+  return new SimpleArrayAdapter();
+}