异步记忆召回 — 设计规范

type MemoryPrefetchHandle = {
  promise: Promise<RelevantAutoMemoryPromptResult>;
  /** 由 promise.finally() 设置。在 promise 完成前为 null。 */
  settledAt: number | null;
  /** 在记忆被注入后设为 true——防止重复注入。 */
  consumed: boolean;
  controller: AbortController;
};

// 在安装新 handle 之前，终止来自前一个 UserQuery 的任何正在进行中的预取
// （当用户在召回完成前再次输入时，防止产生孤立的侧查询）。
this.pendingMemoryPrefetch?.controller.abort();
this.pendingMemoryPrefetch = undefined;
 
const controller = new AbortController();
// 将调用者的信号桥接到预取控制器，以便父轮次的用户中止
// （Ctrl-C / Esc）也能终止召回侧查询。
const onParentAbort = () => controller.abort();
if (signal.aborted) {
  controller.abort();
} else {
  signal.addEventListener('abort', onParentAbort, { once: true });
}
 
const promise = this.config
  .getMemoryManager()
  .recall(projectRoot, partToString(request), {
    config: this.config,
    excludedFilePaths: this.surfacedRelevantAutoMemoryPaths,
    abortSignal: controller.signal,
  })
  .catch((error: unknown) => {
    if (!(error instanceof DOMException && error.name === 'AbortError')) {
      debugLogger.warn('托管自动记忆召回预取失败。', error);
    }
    return EMPTY_RELEVANT_AUTO_MEMORY_RESULT;
  });
 
const handle: MemoryPrefetchHandle = {
  promise,
  settledAt: null,
  consumed: false,
  controller,
};
void promise.finally(() => {
  handle.settledAt = Date.now();
  signal.removeEventListener('abort', onParentAbort);
});
this.pendingMemoryPrefetch = handle;
// 不 await —— 立即继续

const prefetchHandle = this.pendingMemoryPrefetch;
if (
  prefetchHandle &&
  prefetchHandle.settledAt !== null &&
  !prefetchHandle.consumed
) {
  prefetchHandle.consumed = true;
  this.pendingMemoryPrefetch = undefined;
  const result = await prefetchHandle.promise; // 已经完成，立即返回
  if (result.prompt) {
    // 使用 unshift 而非 push：将记忆放在 systemReminders 的前面，以便在
    // UserQuery 轮次中它成为 system-reminder 块的头部。（ToolResult
    // 轮次则追加到 requestToSend 中以保持 functionCall /
    // functionResponse 配对——参见下文。）
    systemReminders.unshift(result.prompt);
    for (const doc of result.selectedDocs) {
      this.surfacedRelevantAutoMemoryPaths.add(doc.filePath);
    }
  }
}

if (messageType === SendMessageType.ToolResult) {
  const prefetchHandle = this.pendingMemoryPrefetch;
  if (
    prefetchHandle &&
    prefetchHandle.settledAt !== null &&
    !prefetchHandle.consumed
  ) {
    prefetchHandle.consumed = true;
    this.pendingMemoryPrefetch = undefined;
    const result = await prefetchHandle.promise;
    if (result.prompt) {
      // 追加（不前置）以保持 functionResponse 部分在前，
      // 确保在原生 Gemini 路径上不破坏模型的 functionCall/functionResponse 配对。
      requestToSend = [...requestToSend, result.prompt];
      for (const doc of result.selectedDocs) {
        this.surfacedRelevantAutoMemoryPaths.add(doc.filePath);
      }
    }
  }
}

this.pendingMemoryPrefetch?.controller.abort();
this.pendingMemoryPrefetch = undefined;

prefetchHandle.consumed = true;
this.pendingMemoryPrefetch = undefined;