@downcity/agent 1.1.408 → 1.1.437

package/src/executor/messages/SessionMessageLog.ts

@@ -4,12 +4,12 @@
  * 该模块只提取可见文本并写入统一 Logger，不参与协议转换或持久化。
  */
 
-import type { SessionAssistantMessagePart } from "@/types/session/SessionMessage.js";
+import type { SessionAgentMessagePart } from "@downcity/type";
 import type { Logger } from "@/utils/logger/Logger.js";
 
 /** 从 canonical Assistant Parts 提取可见文本。 */
 export function extract_assistant_text_for_log(
-  parts: readonly SessionAssistantMessagePart[],
+  parts: readonly SessionAgentMessagePart[],
 ): string {
   return parts
     .flatMap((part) => part.type === "text" ? [part.text] : [])
@@ -20,7 +20,7 @@ export function extract_assistant_text_for_log(
 /** 立即输出 Assistant 文本日志。 */
 export async function log_assistant_message_now(
   logger: Logger,
-  parts: readonly SessionAssistantMessagePart[],
+  parts: readonly SessionAgentMessagePart[],
 ): Promise<void> {
   const text = extract_assistant_text_for_log(parts) || "-";
   const lines = text.replace(/\r\n/gu, "\n").split("\n");

package/src/executor/messages/SessionModelMessages.ts

@@ -13,34 +13,15 @@ import type {
   ModelJsonValue,
   ModelMessage,
 } from "@downcity/type";
-import { parse_chat_message_markup } from "@executor/messages/ChatMessageMarkup.js";
+import { render_session_user_context } from "@/session/messages/SessionUserContext.js";
 import type {
-  SessionAssistantMessage,
-  SessionAssistantToolPart,
+  SessionAgentMessage,
+  SessionAgentToolPart,
   SessionMessage,
   SessionUserFilePart,
   SessionUserMessage,
-} from "@/types/session/SessionMessage.js";
-import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
-
-/** 把完整 Session 上下文快照转换为模型消息。 */
-export async function session_context_to_model_messages(
-  snapshot: Readonly<SessionContextSnapshot>,
-  project_root?: string,
-): Promise<ModelMessage[]> {
-  const messages = await session_messages_to_model_messages(
-    snapshot.messages,
-    project_root,
-  );
-  if (!snapshot.summary?.text.trim()) return messages;
-  return [
-    {
-      role: "assistant",
-      content: [{ type: "text", text: snapshot.summary.text }],
-    },
-    ...messages,
-  ];
-}
+  SessionUserMessagePart,
+} from "@downcity/type";
 
 /** 把一组 canonical Session Message 转换为模型消息。 */
 export async function session_messages_to_model_messages(
@@ -49,9 +30,9 @@ export async function session_messages_to_model_messages(
 ): Promise<ModelMessage[]> {
   const output: ModelMessage[] = [];
   for (const message of messages) {
-    if (message.type === "user") {
+    if (message.role === "user") {
       output.push(...await convert_user_message(message, project_root));
-    } else if (message.type === "assistant") {
+    } else if (message.role === "agent") {
       output.push(...convert_assistant_message(message));
     }
   }
@@ -63,51 +44,94 @@ async function convert_user_message(
   message: SessionUserMessage,
   project_root?: string,
 ): Promise<ModelMessage[]> {
+  const converted = await convert_user_parts(message.parts, project_root);
+  return converted ? [converted] : [];
+}
+
+/** 将 canonical User Parts 投影为单条模型消息。 */
+async function convert_user_parts(
+  parts: readonly SessionUserMessagePart[],
+  project_root?: string,
+): Promise<ModelMessage | null> {
   const content: ModelContent[] = [];
-  const has_explicit_file = message.parts.some((part) => part.type === "file");
-  for (const part of message.parts) {
-    if (part.type === "text" && part.text.trim()) {
-      content.push({ type: "text", text: part.text });
-    } else if (part.type === "file") {
-      content.push(await convert_file_part(part, project_root));
+  for (const part of parts) {
+    switch (part.type) {
+      case "text":
+        if (part.text.trim()) content.push({ type: "text", text: part.text });
+        break;
+      case "context":
+        content.push({
+          type: "text",
+          text: render_session_user_context(part.tag, part.context),
+        });
+        break;
+      case "file":
+        content.push(await convert_file_part(part, project_root));
+        break;
+      case "data":
+        // Data Part 是持久化 UI 数据，不属于模型输入协议。
+        break;
+      default:
+        assert_never(part);
     }
   }
-  if (!has_explicit_file) {
-    content.push(...await read_markup_files(message, project_root));
-  }
-  return content.length > 0 ? [{ role: "user", content }] : [];
+  return content.length > 0 ? { role: "user", content } : null;
 }
 
-/** 把单条 canonical Assistant Message 转换为 assistant 与 tool 消息。 */
-function convert_assistant_message(message: SessionAssistantMessage): ModelMessage[] {
+/** 把单条 canonical Agent Message 转换为模型 assistant 与 tool 消息。 */
+function convert_assistant_message(message: SessionAgentMessage): ModelMessage[] {
+  const output: ModelMessage[] = [];
+  let current_step_id: string | null = null;
   const content: ModelContent[] = [];
   const tool_results: ModelContent[] = [];
-  for (const part of message.parts) {
-    if (part.type === "text" && part.text.trim()) {
-      content.push({ type: "text", text: part.text });
-    } else if (part.type === "reasoning" && part.text.trim()) {
-      content.push({
-        type: "reasoning",
-        text: part.text,
-        ...(part.reasoning_signature
-          ? { signature: part.reasoning_signature }
-          : {}),
-      });
-    } else if (part.type === "tool" && part.input !== undefined) {
-      append_tool_content(part, content, tool_results);
+  const flush_step = (): void => {
+    if (content.length > 0) output.push({ role: "assistant", content: [...content] });
+    if (tool_results.length > 0) output.push({ role: "tool", content: [...tool_results] });
+    content.length = 0;
+    tool_results.length = 0;
+  };
+  for (const part of [...message.parts].sort((left, right) => left.sequence - right.sequence)) {
+    const part_step_id = part.step_id ?? "__unscoped__";
+    if (current_step_id !== null && part_step_id !== current_step_id) flush_step();
+    current_step_id = part_step_id;
+    switch (part.type) {
+      case "text":
+        if (part.text.trim()) content.push({ type: "text", text: part.text });
+        break;
+      case "reasoning":
+        if (part.text.trim()) {
+          content.push({
+            type: "reasoning",
+            text: part.text,
+            ...(part.reasoning_signature
+              ? { signature: part.reasoning_signature }
+              : {}),
+          });
+        }
+        break;
+      case "tool":
+        if (part.input !== undefined) {
+          append_tool_content(part, content, tool_results);
+        }
+        break;
+      case "interaction":
+      case "file":
+      case "data":
+      case "action":
+      case "error":
+        // 这些 Part 只属于运行状态或宿主展示，不进入模型历史。
+        break;
+      default:
+        assert_never(part);
     }
   }
-  return [
-    ...(content.length > 0 ? [{ role: "assistant", content } as ModelMessage] : []),
-    ...(tool_results.length > 0
-      ? [{ role: "tool", content: tool_results } as ModelMessage]
-      : []),
-  ];
+  flush_step();
+  return output;
 }
 
 /** 把 canonical Tool Part 投影为模型工具调用和可选工具结果。 */
 function append_tool_content(
-  part: SessionAssistantToolPart,
+  part: SessionAgentToolPart,
   content: ModelContent[],
   tool_results: ModelContent[],
 ): void {
@@ -163,36 +187,6 @@ function build_model_file(
   };
 }
 
-/** 解析兼容聊天入口写入文本中的附件标记。 */
-async function read_markup_files(
-  message: SessionUserMessage,
-  project_root?: string,
-): Promise<ModelFileContent[]> {
-  const text = message.parts
-    .filter((part) => part.type === "text")
-    .map((part) => part.text)
-    .join("\n");
-  const output: ModelFileContent[] = [];
-  for (const file of parse_chat_message_markup(text).files) {
-    const media_type = guess_media_type(file.path);
-    if (!media_type || (!media_type.startsWith("image/") && media_type !== "application/pdf")) {
-      continue;
-    }
-    const file_path = resolve_local_file_path(file.path, project_root);
-    if (!await fs.pathExists(file_path)) continue;
-    output.push({
-      type: "file",
-      media_type,
-      source: {
-        type: "base64",
-        data: (await fs.readFile(file_path)).toString("base64"),
-      },
-      filename: path.basename(file_path),
-    });
-  }
-  return output;
-}
-
 /** 把本地文件引用限制在项目根目录内，绝对附件路径保持可读。 */
 function resolve_local_file_path(raw_path: string, project_root?: string): string {
   if (path.isAbsolute(raw_path)) return path.resolve(raw_path);
@@ -205,19 +199,13 @@ function resolve_local_file_path(raw_path: string, project_root?: string): strin
   return file_path;
 }
 
-/** 根据文件扩展名解析模型可用的 MIME type。 */
-function guess_media_type(file_path: string): string | undefined {
-  const extension = path.extname(file_path).toLowerCase();
-  if (extension === ".png") return "image/png";
-  if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
-  if (extension === ".webp") return "image/webp";
-  if (extension === ".gif") return "image/gif";
-  if (extension === ".pdf") return "application/pdf";
-  return undefined;
-}
-
 /** 将未知值限制为可传输 JSON。 */
 function to_model_json_value(value: unknown): ModelJsonValue {
   if (value === undefined) return null;
   return JSON.parse(JSON.stringify(value)) as ModelJsonValue;
 }
+
+/** 联合类型增加成员时，强制模型投影显式选择支持或忽略。 */
+function assert_never(value: never): never {
+  throw new Error(`Unsupported Session model part: ${String((value as { type?: unknown }).type)}`);
+}

package/src/executor/model/ModelGenerate.ts

@@ -9,10 +9,15 @@ import type {
   ModelClient,
   ModelFinishReason,
   ModelMessage,
+  ModelRequestKind,
   ModelToolCallContent,
   ModelUsage,
 } from "@downcity/type";
-import { ModelStreamValidator } from "@downcity/type";
+import { execute_model_request } from "@executor/model/ModelRequestRunner.js";
+import { consume_model_stream } from "@executor/model/ModelStreamConsumer.js";
+import type {
+  ModelRequestFailureReporter,
+} from "@/types/executor/ModelRequest.js";
 
 /** 单次非交互模型生成结果。 */
 export interface ModelGenerateResult {
@@ -26,38 +31,71 @@ export interface ModelGenerateResult {
   usage?: ModelUsage;
 }
 
+/** 非交互模型生成执行选项。 */
+export interface ModelGenerateOptions {
+  /** 当前模型请求用途。 */
+  request_kind: Exclude<ModelRequestKind, "turn">;
+  /** 可选取消信号。 */
+  signal?: AbortSignal;
+  /** 可选逐次失败通知入口。 */
+  on_failure?: ModelRequestFailureReporter;
+}
+
 /** 执行一次不包含 Agent 工具循环的模型调用。 */
 export async function generate_model(
+  model: ModelClient,
+  call: ModelCall,
+  options: ModelGenerateOptions,
+): Promise<ModelGenerateResult> {
+  return await execute_model_request({
+    request_kind: options.request_kind,
+    abort_signal: options.signal,
+    on_failure: options.on_failure,
+    execute_attempt: async () =>
+      await generate_model_once(model, call, options.signal),
+  });
+}
+
+/** 执行一次非交互模型调用并聚合完整结果。 */
+async function generate_model_once(
   model: ModelClient,
   call: ModelCall,
   signal?: AbortSignal,
 ): Promise<ModelGenerateResult> {
-  const stream = await model.stream(call, signal);
-  const text_by_id = new Map<string, string>();
   const tools = new Map<string, { tool_call_id: string; tool_name: string }>();
   const tool_calls: ModelToolCallContent[] = [];
   let text = "";
+  let has_partial_output = false;
   let finish_reason: ModelFinishReason | undefined;
   let usage: ModelUsage | undefined;
-  const validator = new ModelStreamValidator();
-  for await (const event of stream) {
-    validator.accept(event);
-    if (event.type === "model_error") throw new Error(event.error.message);
-    if (event.type === "text_start") text_by_id.set(event.content_id, "");
-    else if (event.type === "text_delta") {
-      text_by_id.set(event.content_id, (text_by_id.get(event.content_id) ?? "") + event.delta);
-      text += event.delta;
-    } else if (event.type === "tool_call_start") {
-      tools.set(event.content_id, { tool_call_id: event.tool_call_id, tool_name: event.tool_name });
-    } else if (event.type === "tool_call_finish") {
-      const tool = tools.get(event.content_id);
-      if (tool && !event.input_error) {
-        tool_calls.push({ type: "tool_call", ...tool, input: event.input });
+  await consume_model_stream(
+    model,
+    call,
+    signal,
+    () => has_partial_output,
+    (event) => {
+      if (
+        event.type === "text_delta" ||
+        event.type === "reasoning_start" ||
+        event.type === "reasoning_delta" ||
+        event.type === "tool_call_start" ||
+        event.type === "tool_call_delta"
+      ) {
+        has_partial_output = true;
       }
-    } else if (event.type === "model_usage") usage = event.usage;
-    else if (event.type === "model_finish") finish_reason = event.finish_reason;
-  }
-  validator.finish();
+      if (event.type === "text_delta") {
+        text += event.delta;
+      } else if (event.type === "tool_call_start") {
+        tools.set(event.content_id, { tool_call_id: event.tool_call_id, tool_name: event.tool_name });
+      } else if (event.type === "tool_call_finish") {
+        const tool = tools.get(event.content_id);
+        if (tool && !event.input_error) {
+          tool_calls.push({ type: "tool_call", ...tool, input: event.input });
+        }
+      } else if (event.type === "model_usage") usage = event.usage;
+      else if (event.type === "model_finish") finish_reason = event.finish_reason;
+    },
+  );
   if (!finish_reason) throw new Error("Model stream ended without model_finish");
   return { text, tool_calls, finish_reason, ...(usage ? { usage } : {}) };
 }

package/src/executor/model/ModelRequestRunner.ts

@@ -0,0 +1,107 @@
+/**
+ * Agent 模型请求统一执行器。
+ *
+ * 本模块唯一拥有请求重试次数、退避和逐次失败通知；具体模型流解析由调用方提供。
+ */
+
+import type { ModelRequestKind } from "@downcity/type";
+import type { ModelRequestFailureReporter } from "@/types/executor/ModelRequest.js";
+import {
+  ModelStreamFailure,
+  is_retryable_empty_model_stream_failure,
+} from "@executor/model/ModelStreamFailure.js";
+
+/** 首次模型调用失败后的最大自动重试次数。 */
+export const MAX_MODEL_REQUEST_RETRIES = 5;
+
+/** 包含首次调用与自动重试在内的最大模型调用次数。 */
+export const MAX_MODEL_REQUEST_ATTEMPTS = MAX_MODEL_REQUEST_RETRIES + 1;
+
+/** 模型请求重试退避，避免连续冲击同一 Provider。 */
+const MODEL_REQUEST_RETRY_DELAYS_MS = [300, 1_000, 2_000, 4_000, 8_000] as const;
+
+/** 统一模型请求执行参数。 */
+interface ExecuteModelRequestInput<TResult> {
+  /** 当前模型请求用途。 */
+  request_kind: ModelRequestKind;
+  /** 执行一次模型调用及其流消费。 */
+  execute_attempt: () => Promise<TResult>;
+  /** 可选取消信号。 */
+  abort_signal?: AbortSignal;
+  /** 可选逐次失败通知入口。 */
+  on_failure?: ModelRequestFailureReporter;
+  /** 判断错误是否交给当前执行器自动重试。 */
+  should_retry?: (error: ModelStreamFailure) => boolean;
+}
+
+/** 执行一次带统一恢复策略的模型请求。 */
+export async function execute_model_request<TResult>(
+  input: ExecuteModelRequestInput<TResult>,
+): Promise<TResult> {
+  for (let attempt = 1; attempt <= MAX_MODEL_REQUEST_ATTEMPTS; attempt += 1) {
+    try {
+      return await input.execute_attempt();
+    } catch (error) {
+      if (!(error instanceof ModelStreamFailure)) throw error;
+      const eligible_for_retry =
+        error.code !== "cancelled" &&
+        input.abort_signal?.aborted !== true &&
+        is_retryable_empty_model_stream_failure(error) &&
+        (input.should_retry?.(error) ?? true);
+      const can_retry =
+        eligible_for_retry && attempt < MAX_MODEL_REQUEST_ATTEMPTS;
+      if (error.code !== "cancelled" && input.abort_signal?.aborted !== true) {
+        try {
+          await input.on_failure?.({
+            request_kind: input.request_kind,
+            code: error.code,
+            message: error.message,
+            retryable: error.retryable,
+            attempt,
+            max_attempts: eligible_for_retry
+              ? MAX_MODEL_REQUEST_ATTEMPTS
+              : attempt,
+            will_retry: can_retry,
+            ...(error.provider_request_id
+              ? { provider_request_id: error.provider_request_id }
+              : {}),
+          }, error);
+        } catch {
+          // 关键点（中文）：诊断通知失败不能改变模型请求恢复结果。
+        }
+      }
+      if (!can_retry) throw error;
+      await wait_for_model_request_retry(
+        resolve_model_request_retry_delay(attempt),
+        input.abort_signal,
+      );
+    }
+  }
+  throw new Error("Model request retry state is invalid");
+}
+
+/** 读取指定重试序号对应的退避时间。 */
+function resolve_model_request_retry_delay(retry_count: number): number {
+  return MODEL_REQUEST_RETRY_DELAYS_MS[retry_count - 1] ??
+    MODEL_REQUEST_RETRY_DELAYS_MS.at(-1) ??
+    8_000;
+}
+
+/** 等待下一次模型请求，并在调用方取消时立即结束。 */
+async function wait_for_model_request_retry(
+  delay_ms: number,
+  abort_signal?: AbortSignal,
+): Promise<void> {
+  if (abort_signal?.aborted) throw abort_signal.reason;
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      abort_signal?.removeEventListener("abort", on_abort);
+      resolve();
+    }, delay_ms);
+    const on_abort = (): void => {
+      clearTimeout(timer);
+      reject(abort_signal?.reason);
+    };
+    abort_signal?.addEventListener("abort", on_abort, { once: true });
+  });
+}