fix(adapter): strip orphaned functionResponses before sending to cloud

JerryliDe · JerryliDe · commit 1fb305e233f1 · 2026-06-05T12:23:11.000+08:00
diff --git a/packages/core/src/core/DeepVServerAdapter.mergeStreamContent.test.ts b/packages/core/src/core/DeepVServerAdapter.mergeStreamContent.test.ts
@@ -354,7 +354,10 @@ describe('mergeStreamContent + finalize end-to-end (streamed local_time call)',
 });
 
 describe('DeepVServerAdapter.cleanContents', () => {
-  const cleanContents = (contents: any[]) => proto.cleanContents.call({}, contents);
+  // cleanContents 内部会调用 this.removeOrphanedToolResponses，
+  // 白盒测试需提供一个挂载了该方法的 this 上下文。
+  const ctx = { removeOrphanedToolResponses: proto.removeOrphanedToolResponses };
+  const cleanContents = (contents: any[]) => proto.cleanContents.call(ctx, contents);
 
   it('filters out empty or whitespace-only text parts within a message', () => {
     const input = [
@@ -402,3 +405,201 @@ describe('DeepVServerAdapter.cleanContents', () => {
     expect(result[0].parts[0].text).toBe('Keep this');
   });
 });
+
+/**
+ * 单元测试：DeepVServerAdapter.removeOrphanedToolResponses
+ *
+ * 守护生产 bug 修复（用户实拍 easyrouter 400）：
+ *   "Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"
+ *
+ * 根因：上下文压缩/历史截断把 functionCall 切掉、却保留了它的 functionResponse，
+ *   形成"孤儿 functionResponse"。该孤儿被客户端 sanitizeRequestContents 的
+ *   "全局 name 兜底"误判为有配对而存活，发往云端转 OpenAI 格式后变成无前驱
+ *   tool_calls 的 role:'tool' 消息 → 严格网关 (easyrouter) 报 400。
+ *
+ * 修复策略（对 Gemini / Claude / OpenAI 三家均无害）：在发往云端的出口处，
+ *   按"真实配对关系 + 计数消耗"删除真孤儿——
+ *     - 优先 id 精确配对（消耗，防两个 fr 抢同一个 fc）
+ *     - 回退 name 计数配对（N 个同名 fc 最多配 N 个 fr，多出的才删）
+ *   合法会话里 fr 数 ≤ 同名 fc 数，计数永远够，不会删任何合法配对。
+ */
+describe('DeepVServerAdapter.removeOrphanedToolResponses', () => {
+  const removeOrphans = (contents: any[]) =>
+    proto.removeOrphanedToolResponses.call({}, contents);
+
+  it('removes a truly orphaned functionResponse (its functionCall was dropped)', () => {
+    // 压缩后场景：只剩下一个 functionResponse，对应的 functionCall 已被截断丢弃
+    const input = [
+      { role: 'user', parts: [{ text: 'do something' }] },
+      {
+        role: 'user',
+        parts: [
+          { functionResponse: { id: 'read_file-123-abc', name: 'read_file', response: { ok: true } } },
+        ],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    // 孤儿 fr 被删除 → 该 user 消息只剩 0 个有效 part → 整条消息移除
+    expect(result).toHaveLength(1);
+    expect(result[0].parts[0].text).toBe('do something');
+  });
+
+  it('keeps a functionResponse that has a matching functionCall by id', () => {
+    const input = [
+      {
+        role: 'model',
+        parts: [{ functionCall: { id: 'call_1', name: 'read_file', args: { path: 'a.ts' } } }],
+      },
+      {
+        role: 'user',
+        parts: [{ functionResponse: { id: 'call_1', name: 'read_file', response: { ok: true } } }],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].parts[0].functionResponse.id).toBe('call_1');
+  });
+
+  it('keeps a functionResponse matched by name when ids are absent (Gemini native)', () => {
+    // Gemini 原生：functionCall 常无 id，functionResponse 靠 name 配对
+    const input = [
+      {
+        role: 'model',
+        parts: [{ functionCall: { name: 'get_weather', args: { city: 'SH' } } }],
+      },
+      {
+        role: 'user',
+        parts: [{ functionResponse: { name: 'get_weather', response: { temp: 20 } } }],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].parts[0].functionResponse.name).toBe('get_weather');
+  });
+
+  it('does NOT mis-delete parallel same-name calls (N functionCalls ↔ N functionResponses)', () => {
+    // 并行同名工具调用：3 个 read_file 全无 id，3 个 fr 也全无 id（或仅 name）
+    const input = [
+      {
+        role: 'model',
+        parts: [
+          { functionCall: { name: 'read_file', args: { path: 'a.ts' } } },
+          { functionCall: { name: 'read_file', args: { path: 'b.ts' } } },
+          { functionCall: { name: 'read_file', args: { path: 'c.ts' } } },
+        ],
+      },
+      {
+        role: 'user',
+        parts: [
+          { functionResponse: { name: 'read_file', response: { c: 'A' } } },
+          { functionResponse: { name: 'read_file', response: { c: 'B' } } },
+          { functionResponse: { name: 'read_file', response: { c: 'C' } } },
+        ],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    // 3 个 fr 全部保留（计数 3 配 3）
+    expect(result).toHaveLength(2);
+    expect(result[1].parts).toHaveLength(3);
+    expect(result[1].parts.every((p: any) => p.functionResponse?.name === 'read_file')).toBe(true);
+  });
+
+  it('removes only the EXCESS orphan when fr count exceeds same-name fc count', () => {
+    // 2 个 fc 但 3 个 fr：保留 2 个、删除 1 个多余孤儿
+    const input = [
+      {
+        role: 'model',
+        parts: [
+          { functionCall: { name: 'read_file', args: { path: 'a.ts' } } },
+          { functionCall: { name: 'read_file', args: { path: 'b.ts' } } },
+        ],
+      },
+      {
+        role: 'user',
+        parts: [
+          { functionResponse: { name: 'read_file', response: { c: 'A' } } },
+          { functionResponse: { name: 'read_file', response: { c: 'B' } } },
+          { functionResponse: { name: 'read_file', response: { c: 'C' } } },
+        ],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].parts).toHaveLength(2);
+  });
+
+  it('does not consume one functionCall for two functionResponses (id pool exhaustion)', () => {
+    // 1 个 fc (id=call_1) 但 2 个 fr 都声称 id=call_1：只保留 1 个，另一个判为孤儿
+    const input = [
+      {
+        role: 'model',
+        parts: [{ functionCall: { id: 'call_1', name: 'read_file', args: {} } }],
+      },
+      {
+        role: 'user',
+        parts: [
+          { functionResponse: { id: 'call_1', name: 'read_file', response: { c: 'A' } } },
+          { functionResponse: { id: 'call_1', name: 'read_file', response: { c: 'B' } } },
+        ],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].parts).toHaveLength(1);
+  });
+
+  it('leaves contents unchanged when there are no functionResponses', () => {
+    const input = [
+      { role: 'user', parts: [{ text: 'hello' }] },
+      { role: 'model', parts: [{ text: 'hi there' }] },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toEqual(input);
+  });
+
+  it('leaves a fully paired history untouched (idempotent on healthy data)', () => {
+    const input = [
+      { role: 'user', parts: [{ text: 'q' }] },
+      { role: 'model', parts: [{ functionCall: { id: 'c1', name: 'read_file', args: {} } }] },
+      { role: 'user', parts: [{ functionResponse: { id: 'c1', name: 'read_file', response: {} } }] },
+      { role: 'model', parts: [{ text: 'answer' }] },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toEqual(input);
+  });
+
+  it('preserves non-functionResponse parts in the same message when removing an orphan', () => {
+    // 同一条 user 消息里既有孤儿 fr 又有正常文本：只删 fr，保留文本
+    const input = [
+      {
+        role: 'user',
+        parts: [
+          { functionResponse: { id: 'ghost-999', name: 'ghost_tool', response: {} } },
+          { text: 'user follow-up text' },
+        ],
+      },
+    ];
+
+    const result = removeOrphans(input);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].parts).toHaveLength(1);
+    expect(result[0].parts[0].text).toBe('user follow-up text');
+  });
+});
diff --git a/packages/core/src/core/DeepVServerAdapter.ts b/packages/core/src/core/DeepVServerAdapter.ts
@@ -539,21 +539,29 @@ export class DeepVServerAdapter implements ContentGenerator {
       return hasValidPart;
     });
 
+    // 🛡️ 协议安全网：删除"真孤儿 functionResponse"（找不到任何可配对 functionCall）
+    // 修复用户实拍 easyrouter 400：
+    //   "Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"
+    // 上下文压缩/历史截断可能切掉 functionCall 却保留其 functionResponse，
+    // 该孤儿转 OpenAI 格式后变成无前驱 tool_calls 的 role:'tool' → 严格网关 400。
+    // 此清理对 Gemini / Claude / OpenAI 三家均无害：合法配对全部保留，仅删真孤儿。
+    const orphanCleaned = this.removeOrphanedToolResponses(cleaned);
+
     // 🔧 安全保障：确保清理后 contents 不以 model/assistant 结尾
     // 某些模型（如 AWS Bedrock Claude）不支持 assistant prefill，
     // 要求对话必须以 user 消息结尾。过滤空消息后末尾可能变成 model。
-    if (cleaned.length > 0 && cleaned[cleaned.length - 1].role === MESSAGE_ROLES.MODEL) {
+    if (orphanCleaned.length > 0 && orphanCleaned[orphanCleaned.length - 1].role === MESSAGE_ROLES.MODEL) {
       logger.warn('[cleanContents] Contents ends with model message after cleanup — appending user placeholder');
-      cleaned.push({
+      orphanCleaned.push({
         role: MESSAGE_ROLES.USER,
         parts: [{ text: '[Conversation continues]' }],
       });
     }
 
     // 🆕 调试日志：输出整理后的历史结构，帮助诊断多轮对话中的思维块合并情况
     if (process.env.DEBUG || process.env.NODE_ENV === 'development' || true) { // 🌟 暂时强制开启以便在用户的终端中显示，极其利于排除故障
-      console.log(`[cleanContents] 整理后的历史记录列表 (共 ${cleaned.length} 条):`);
-      cleaned.forEach((c, idx) => {
+      console.log(`[cleanContents] 整理后的历史记录列表 (共 ${orphanCleaned.length} 条):`);
+      orphanCleaned.forEach((c, idx) => {
         const partTypes = (c.parts || []).map((p: any) => {
           if (p.text !== undefined) return `text(${p.text.length})`;
           if (p.functionCall) return `functionCall(${p.functionCall.name})`;
@@ -565,7 +573,107 @@ export class DeepVServerAdapter implements ContentGenerator {
       });
     }
 
-    return cleaned;
+    return orphanCleaned;
+  }
+
+  /**
+   * 🛡️ 删除"真孤儿 functionResponse"——在整个 contents 里找不到任何可配对
+   * functionCall 的 functionResponse。
+   *
+   * 修复生产 bug（用户实拍 easyrouter 400）：
+   *   "Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"
+   *
+   * 根因：上下文压缩/历史截断会把 functionCall 切掉、却保留其 functionResponse，
+   * 形成孤儿。它被上游 sanitizeRequestContents 的"全局 name 兜底"误判存活，
+   * 转 OpenAI 格式后变成无前驱 tool_calls 的 role:'tool' → 严格网关报 400。
+   *
+   * 配对算法（模拟服务端真实配对，以 fc 为单位按"配对槽消耗"避免误删）：
+   *   1) 先扫描所有 functionCall，每个 fc 建一个配对槽 {id?, name, consumed:false}。
+   *   2) 按出现顺序遍历每个 functionResponse，为其寻找一个未消耗的槽：
+   *        - 优先匹配 id 相同的未消耗槽 → 命中则消耗
+   *        - 否则匹配 name 相同的未消耗槽 → 命中则消耗
+   *        - 都没有 → 真孤儿，删除
+   *      （以 fc 为单位建槽，保证一个 fc 只配 1 个 fr，id 与 name 不会各放行一个。）
+   *
+   * 无害性保证（对 Gemini / Claude / OpenAI 三家均成立）：
+   *   - 合法会话里 fr 数 ≤ 同名 fc 数，计数永远够 → 不删任何合法配对。
+   *   - 并行同名 N 对：nameCount=N，N 个 fr 各消耗 1，全部保留 → 不误删。
+   *   - 仅当 fr 数 > 可配对 fc 数（真出现孤儿）才删多出来的那些。
+   *   - 孤儿 functionResponse 本就是三家协议的共同禁忌，删除只会让请求更合法。
+   */
+  private removeOrphanedToolResponses(contents: any[]): any[] {
+    if (!Array.isArray(contents) || contents.length === 0) return contents;
+
+    // 快速通道：没有任何 functionResponse 时直接返回，零开销、零改动
+    const hasAnyFunctionResponse = contents.some(
+      (c) => Array.isArray(c?.parts) && c.parts.some((p: any) => p?.functionResponse),
+    );
+    if (!hasAnyFunctionResponse) return contents;
+
+    // 1) 扫描所有 functionCall，每个 fc 建一个"配对槽"（含 id?/name，初始未消耗）。
+    //    以 fc 为单位建槽是关键：一个 fc 同时有 id 和 name 时只能配 1 个 fr，
+    //    绝不能让 id 和 name 各放行一个 fr（否则一个 fc 被算成 2 份配对额度）。
+    const slots: Array<{ id?: string; name?: string; consumed: boolean }> = [];
+    for (const content of contents) {
+      if (!Array.isArray(content?.parts)) continue;
+      for (const part of content.parts) {
+        const fc = part?.functionCall;
+        if (!fc) continue;
+        slots.push({ id: fc.id, name: fc.name, consumed: false });
+      }
+    }
+
+    // 2) 遍历每条消息，为每个 functionResponse 寻找一个未消耗的配对槽
+    let removedCount = 0;
+    const result: any[] = [];
+    for (const content of contents) {
+      if (!Array.isArray(content?.parts)) {
+        result.push(content);
+        continue;
+      }
+
+      const keptParts = content.parts.filter((part: any) => {
+        const fr = part?.functionResponse;
+        if (!fr) return true; // 非 functionResponse 一律保留
+
+        // 优先 id 精确配对：找一个未消耗、id 相同的槽
+        if (fr.id) {
+          const slot = slots.find((s) => !s.consumed && s.id === fr.id);
+          if (slot) {
+            slot.consumed = true;
+            return true;
+          }
+        }
+        // 回退 name 配对：找一个未消耗、name 相同的槽（覆盖 Gemini 无 id 及并行同名）
+        if (fr.name) {
+          const slot = slots.find((s) => !s.consumed && s.name === fr.name);
+          if (slot) {
+            slot.consumed = true;
+            return true;
+          }
+        }
+        // 真孤儿：没有任何可配对的 functionCall 槽
+        removedCount++;
+        logger.warn(
+          `[removeOrphanedToolResponses] ❌ Removing orphaned functionResponse: ` +
+          `${fr.name} (id: ${fr.id ?? 'n/a'}) — no matching functionCall found.`,
+        );
+        return false;
+      });
+
+      // 若该消息所有 part 都被删空，则整条丢弃；否则保留（可能含其他 part）
+      if (keptParts.length > 0) {
+        result.push(keptParts.length === content.parts.length ? content : { ...content, parts: keptParts });
+      }
+    }
+
+    if (removedCount > 0) {
+      logger.warn(
+        `[removeOrphanedToolResponses] Removed ${removedCount} orphaned functionResponse(s) before sending to cloud.`,
+      );
+    }
+
+    return result;
   }
 
   /**
