@downcity/agent 1.1.337 → 1.1.399

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -1,288 +1,30 @@
 /**
- * SessionAttachmentMapper：把 `<file>` 附件描述映射为模型可消费的 file parts。
+ * Session 附件持久化模块。
  *
- * 关键点（中文）
- * - 兼容 Telegram / Feishu / TUI 等统一的 `<file>` 协议入口。
- * - Data URL 附件先由 Session Attachment Store 落盘，Message 只保存文件路径。
- * - 模型执行阶段再读取本地文件，并转换为模型可消费的数据格式。
- * - 历史中的相对路径与旧版 `file://` 会在喂给模型前临时 hydrate。
- *
- * 输入到输出（中文）：
- * `file.url = data:<media-type>;base64,...`
- *   → Session Attachment Store 解码并写入附件文件
- *   → `file.url = .downcity/.../attachments/att_<id>.<ext>`
- *   → Message 持久化路径引用
- *   → 模型执行前读取文件并恢复为 Data URL
- *   → `convertToModelMessages()` 生成最终 ModelMessage。
+ * 本模块只负责在 User Message 入库前把 Data URL 写入 Session Attachment Store。
+ * 模型执行阶段的文件读取与 `ModelFileContent` 转换由 `SessionModelMessages` 负责。
  */
 
-import fs from "fs-extra";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-  isFileUIPart,
-  isTextUIPart,
-  type FileUIPart,
-} from "ai";
-import type { SessionUserMessagePart } from "@/types/sdk/AgentSessionPrompt.js";
+import type { SessionPromptPart } from "@/types/session/SessionContent.js";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
-import type {
-  SessionRecordV1,
-  SessionMessageRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import { parse_chat_message_markup } from "@/executor/messages/ChatMessageMarkup.js";
-
-/**
- * 从 `<file>` 标签中解析附件描述。
- */
-function parseAttachmentLinesFromText(text: string): Array<{
-  type: "photo" | "document" | "voice" | "audio" | "video";
-  path: string;
-  caption?: string;
-}> {
-  const raw = String(text || "");
-  if (!raw.trim()) return [];
-  return parse_chat_message_markup(raw).files.map((file) => ({
-    type: file.type,
-    path: file.path,
-    ...(typeof file.caption === "string" && file.caption.trim()
-      ? { caption: file.caption.trim() }
-      : {}),
-  }));
-}
-
-function guessAttachmentMediaTypeFromPath(filePath: string): string | undefined {
-  const ext = (path.extname(filePath) || "").toLowerCase();
-  if (ext === ".png") return "image/png";
-  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
-  if (ext === ".webp") return "image/webp";
-  if (ext === ".gif") return "image/gif";
-  if (ext === ".pdf") return "application/pdf";
-  if (ext === ".zip") return "application/zip";
-  if (ext === ".mp3") return "audio/mpeg";
-  if (ext === ".m4a") return "audio/mp4";
-  if (ext === ".ogg") return "audio/ogg";
-  if (ext === ".opus") return "audio/opus";
-  if (ext === ".mp4") return "video/mp4";
-  if (ext === ".mov") return "video/quicktime";
-  if (ext === ".webm") return "video/webm";
-  if (ext === ".m4v") return "video/x-m4v";
-  return undefined;
-}
-
-function buildDataUrl(mediaType: string, buffer: Buffer): string {
-  const base64 = buffer.toString("base64");
-  const safeType = mediaType || "application/octet-stream";
-  return `data:${safeType};base64,${base64}`;
-}
 
-function resolveHydratableFilePath(
-  project_root: string | undefined,
-  rawPath: string,
-): string | null {
-  const raw = String(rawPath || "").trim();
-  if (!raw || raw.startsWith("data:") || /^https?:\/\//i.test(raw)) return null;
-  if (raw.startsWith("file://")) return fileURLToPath(raw);
-  if (path.isAbsolute(raw)) return path.resolve(raw);
-
-  const root = path.resolve(String(project_root || "").trim() || process.cwd());
-  const absPath = path.resolve(root, raw);
-  const rel = path.relative(root, absPath);
-  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
-  return absPath;
-}
-
-async function hydrateFileUrlPart(
-  part: FileUIPart,
-  project_root?: string,
-): Promise<FileUIPart> {
-  const url = String(part.url || "").trim();
-  const filePath = resolveHydratableFilePath(project_root, url);
-  if (!filePath) return part;
-  try {
-    const buffer = await fs.readFile(filePath);
-    const mediaType =
-      String(part.mediaType || "").trim() ||
-      guessAttachmentMediaTypeFromPath(filePath) ||
-      "application/octet-stream";
-    return {
-      ...part,
-      mediaType,
-      url: buildDataUrl(mediaType, buffer),
-    };
-  } catch {
-    return part;
-  }
-}
-
-/**
- * 在用户 prompt 入库前，将 Data URL file part 保存为 Session 附件路径。
- *
- * 关键点（中文）
- * - 只有 Data URL 会在此处落盘；远程 URL 和本地路径保持引用不变。
- * - 附件成功落盘后才把 URL 替换为相对 Workspace 根目录的路径。
- * - canonical filename 保留调用侧传入的用户可见文件名；真实落盘路径只写入 url。
- */
+/** 在用户 prompt 入库前持久化 Data URL 文件。 */
 export async function persist_user_prompt_file_parts(
-  parts: SessionUserMessagePart[],
+  parts: SessionPromptPart[],
   attachment_store: SessionAttachmentStore,
-): Promise<SessionUserMessagePart[]> {
-  if (!Array.isArray(parts) || parts.length === 0) return [];
-
-  const out: SessionUserMessagePart[] = [];
+): Promise<SessionPromptPart[]> {
+  const output: SessionPromptPart[] = [];
   for (const part of parts) {
-    if (!isFileUIPart(part as FileUIPart)) {
-      out.push(part);
-      continue;
-    }
-
-    const file_part = part as FileUIPart;
-    const url = String(file_part.url || "").trim();
-    if (!url.startsWith("data:")) {
-      out.push(part);
+    if (part.type !== "file" || !part.url.startsWith("data:")) {
+      output.push(part);
       continue;
     }
-
     const stored_path = await attachment_store.persist_data_url({
-      data_url: url,
-      media_type: String(file_part.mediaType || "").trim(),
-      ...(file_part.filename ? { filename: file_part.filename } : {}),
-    });
-    out.push({ ...file_part, url: stored_path } as SessionUserMessagePart);
-  }
-
-  return out;
-}
-
-/**
- * 将历史中的本地 file part 临时转换为模型可消费的 data URL。
- *
- * 关键点（中文）
- * - 该函数只修改本轮内存消息，不回写历史。
- * - 新历史保留 Agent 根目录相对路径，旧历史的 `file://` 仍继续兼容。
- */
-export async function hydrate_file_url_parts_for_model(
-  messages: SessionMessageRecordV1[],
-  project_root?: string,
-): Promise<SessionMessageRecordV1[]> {
-  if (!Array.isArray(messages) || messages.length === 0) return messages;
-
-  const out: SessionMessageRecordV1[] = [];
-  for (const message of messages) {
-    const parts = Array.isArray(message?.parts) ? message.parts : [];
-    if (!parts.some((part) => isFileUIPart(part as FileUIPart))) {
-      out.push(message);
-      continue;
-    }
-
-    const nextParts: SessionMessageRecordV1["parts"] = [];
-    let changed = false;
-    for (const part of parts) {
-      if (!isFileUIPart(part as FileUIPart)) {
-        nextParts.push(part);
-        continue;
-      }
-      const nextPart = await hydrateFileUrlPart(part as FileUIPart, project_root);
-      if (nextPart !== part) changed = true;
-      nextParts.push(nextPart as SessionMessageRecordV1["parts"][number]);
-    }
-
-    out.push(changed ? { ...message, parts: nextParts } : message);
-  }
-
-  return out;
-}
-
-/**
- * 在 user 消息上注入 FileUIPart，以便多模态模型直接消费本地附件。
- */
-export async function inject_file_parts_from_attachments(
-  messages: SessionMessageRecordV1[],
-  project_root?: string,
-): Promise<SessionMessageRecordV1[]> {
-  if (!Array.isArray(messages) || messages.length === 0) return messages;
-
-  const root = path.resolve(String(project_root || "").trim() || process.cwd());
-  const out: SessionMessageRecordV1[] = [];
-
-  for (const message of messages) {
-    if (!message || typeof message !== "object" || message.role !== "user") {
-      out.push(message);
-      continue;
-    }
-    const parts = Array.isArray(message.parts) ? message.parts : [];
-    if (parts.length === 0) {
-      out.push(message);
-      continue;
-    }
-
-    if (parts.some((part) => isFileUIPart(part as FileUIPart))) {
-      out.push(message);
-      continue;
-    }
-
-    const fullText = parts
-      .map((part) => {
-        const candidate = part as unknown;
-        if (!isTextUIPart(candidate as any)) return "";
-        const value = (candidate as { text?: unknown }).text;
-        return typeof value === "string" ? value : "";
-      })
-      .filter((text) => text)
-      .join("\n");
-    if (!fullText.trim()) {
-      out.push(message);
-      continue;
-    }
-
-    const attachments = parseAttachmentLinesFromText(fullText);
-    if (attachments.length === 0) {
-      out.push(message);
-      continue;
-    }
-
-    const fileParts: FileUIPart[] = [];
-
-    for (const attachment of attachments) {
-      const mediaTypeGuess = guessAttachmentMediaTypeFromPath(attachment.path);
-      if (
-        !mediaTypeGuess ||
-        (!mediaTypeGuess.startsWith("image/") && mediaTypeGuess !== "application/pdf")
-      ) {
-        continue;
-      }
-
-      const absPath = path.isAbsolute(attachment.path)
-        ? attachment.path
-        : path.resolve(root, attachment.path);
-      try {
-        const exists = await fs.pathExists(absPath);
-        if (!exists) continue;
-        const buffer = await fs.readFile(absPath);
-        const dataUrl = buildDataUrl(mediaTypeGuess, buffer);
-        const filename = path.basename(absPath) || "image";
-
-        fileParts.push({
-          type: "file",
-          mediaType: mediaTypeGuess,
-          filename,
-          url: dataUrl,
-        });
-      } catch {
-        continue;
-      }
-    }
-
-    if (fileParts.length === 0) {
-      out.push(message);
-      continue;
-    }
-
-    out.push({
-      ...message,
-      parts: [...parts, ...fileParts],
+      data_url: part.url,
+      media_type: part.media_type,
+      ...(part.filename ? { filename: part.filename } : {}),
     });
+    output.push({ ...part, url: stored_path });
   }
-
-  return out;
+  return output;
 }

package/src/executor/messages/SessionMessageLog.ts

@@ -1,41 +1,28 @@
 /**
- * SessionMessageLog：assistant 消息日志提取与输出辅助模块。
+ * Canonical Assistant Part 日志输出辅助。
  *
- * 关键点（中文）
- * - 只负责从 session message 中提取可读文本。
- * - 只负责把最终 assistant 文本稳定写入统一 logger。
- * - 不参与模型消息转换，也不感知附件注入逻辑。
+ * 该模块只提取可见文本并写入统一 Logger，不参与协议转换或持久化。
  */
 
-import { isTextUIPart } from "ai";
+import type { SessionAssistantMessagePart } from "@/types/session/SessionMessage.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
 
-/**
- * 从 UI message 中提取 assistant 文本部分。
- */
+/** 从 canonical Assistant Parts 提取可见文本。 */
 export function extract_assistant_text_for_log(
-  message: SessionMessageRecordV1,
+  parts: readonly SessionAssistantMessagePart[],
 ): string {
-  if (!Array.isArray(message.parts)) return "";
-  return message.parts
-    .filter(isTextUIPart)
-    .map((part) => String(part.text ?? ""))
+  return parts
+    .flatMap((part) => part.type === "text" ? [part.text] : [])
     .join("\n")
     .trim();
 }
 
-/**
- * 立即输出 assistant 文本日志。
- */
+/** 立即输出 Assistant 文本日志。 */
 export async function log_assistant_message_now(
   logger: Logger,
-  message: SessionMessageRecordV1,
+  parts: readonly SessionAssistantMessagePart[],
 ): Promise<void> {
-  const text = extract_assistant_text_for_log(message) || "-";
-  const normalized = text.replace(/\r\n/g, "\n");
-  const lines = normalized.split("\n");
-  const out = [`[assistant] ${lines[0] || "-"}`];
-  if (lines.length > 1) out.push(...lines.slice(1));
-  await logger.log("info", out.join("\n"));
+  const text = extract_assistant_text_for_log(parts) || "-";
+  const lines = text.replace(/\r\n/gu, "\n").split("\n");
+  await logger.log("info", [`[assistant] ${lines[0] || "-"}`, ...lines.slice(1)].join("\n"));
 }

package/src/executor/messages/SessionModelMessages.ts

@@ -0,0 +1,223 @@
+/**
+ * Canonical Session Message 到 Downcity ModelMessage 的转换模块。
+ *
+ * SessionMessage 是持久化事实，ModelMessage 是模型上下文。该模块是两者之间的唯一转换边界，
+ * 不经过 UI Message、Executor Record 或 Provider 私有格式。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type {
+  ModelContent,
+  ModelFileContent,
+  ModelJsonValue,
+  ModelMessage,
+} from "@downcity/type";
+import { parse_chat_message_markup } from "@executor/messages/ChatMessageMarkup.js";
+import type {
+  SessionAssistantMessage,
+  SessionAssistantToolPart,
+  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,
+  ];
+}
+
+/** 把一组 canonical Session Message 转换为模型消息。 */
+export async function session_messages_to_model_messages(
+  messages: readonly SessionMessage[],
+  project_root?: string,
+): Promise<ModelMessage[]> {
+  const output: ModelMessage[] = [];
+  for (const message of messages) {
+    if (message.type === "user") {
+      output.push(...await convert_user_message(message, project_root));
+    } else if (message.type === "assistant") {
+      output.push(...convert_assistant_message(message));
+    }
+  }
+  return output;
+}
+
+/** 把单条 canonical User Message 转换为模型消息。 */
+async function convert_user_message(
+  message: SessionUserMessage,
+  project_root?: string,
+): Promise<ModelMessage[]> {
+  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));
+    }
+  }
+  if (!has_explicit_file) {
+    content.push(...await read_markup_files(message, project_root));
+  }
+  return content.length > 0 ? [{ role: "user", content }] : [];
+}
+
+/** 把单条 canonical Assistant Message 转换为 assistant 与 tool 消息。 */
+function convert_assistant_message(message: SessionAssistantMessage): ModelMessage[] {
+  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);
+    }
+  }
+  return [
+    ...(content.length > 0 ? [{ role: "assistant", content } as ModelMessage] : []),
+    ...(tool_results.length > 0
+      ? [{ role: "tool", content: tool_results } as ModelMessage]
+      : []),
+  ];
+}
+
+/** 把 canonical Tool Part 投影为模型工具调用和可选工具结果。 */
+function append_tool_content(
+  part: SessionAssistantToolPart,
+  content: ModelContent[],
+  tool_results: ModelContent[],
+): void {
+  content.push({
+    type: "tool_call",
+    tool_call_id: part.tool_call_id,
+    tool_name: part.tool_name,
+    input: part.input ?? null,
+  });
+  if (part.state !== "completed" && part.state !== "failed") return;
+  tool_results.push({
+    type: "tool_result",
+    tool_call_id: part.tool_call_id,
+    tool_name: part.tool_name,
+    outcome: part.state === "completed" ? "succeeded" : "failed",
+    content: [{
+      type: "json",
+      value: to_model_json_value(part.output ?? part.error ?? null),
+    }],
+  });
+}
+
+/** 把 Session 文件引用转换为单一来源的模型文件。 */
+async function convert_file_part(
+  part: Pick<SessionUserFilePart, "media_type" | "url" | "filename">,
+  project_root?: string,
+): Promise<ModelFileContent> {
+  const data_match = /^data:[^;,]+;base64,(.*)$/isu.exec(part.url);
+  if (data_match) {
+    return build_model_file(part, {
+      type: "base64",
+      data: data_match[1] ?? "",
+    });
+  }
+  if (/^https?:\/\//iu.test(part.url)) {
+    return build_model_file(part, { type: "url", url: part.url });
+  }
+  const file_path = resolve_local_file_path(part.url, project_root);
+  const data = (await fs.readFile(file_path)).toString("base64");
+  return build_model_file(part, { type: "base64", data });
+}
+
+/** 构造标准模型文件内容。 */
+function build_model_file(
+  part: Pick<SessionUserFilePart, "media_type" | "filename">,
+  source: ModelFileContent["source"],
+): ModelFileContent {
+  return {
+    type: "file",
+    media_type: part.media_type,
+    source,
+    ...(part.filename ? { filename: part.filename } : {}),
+  };
+}
+
+/** 解析兼容聊天入口写入文本中的附件标记。 */
+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);
+  const root = path.resolve(String(project_root || "").trim() || process.cwd());
+  const file_path = path.resolve(root, raw_path);
+  const relative_path = path.relative(root, file_path);
+  if (relative_path.startsWith("..") || path.isAbsolute(relative_path)) {
+    throw new Error(`Session file escapes project root: ${raw_path}`);
+  }
+  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;
+}

package/src/executor/model/ModelGenerate.ts

@@ -0,0 +1,71 @@
+/**
+ * Downcity ModelClient 非交互生成辅助模块。
+ *
+ * 标题、压缩和调度等旁路复用同一标准协议，不建立第二套模型运行时。
+ */
+
+import type {
+  ModelCall,
+  ModelClient,
+  ModelFinishReason,
+  ModelMessage,
+  ModelToolCallContent,
+  ModelUsage,
+} from "@downcity/type";
+import { ModelStreamValidator } from "@downcity/type";
+
+/** 单次非交互模型生成结果。 */
+export interface ModelGenerateResult {
+  /** 聚合后的普通文本。 */
+  text: string;
+  /** 聚合后的工具调用。 */
+  tool_calls: ModelToolCallContent[];
+  /** 标准完成原因。 */
+  finish_reason: ModelFinishReason;
+  /** Provider 返回的可选 usage。 */
+  usage?: ModelUsage;
+}
+
+/** 执行一次不包含 Agent 工具循环的模型调用。 */
+export async function generate_model(
+  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 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) 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;
+  }
+  validator.finish();
+  if (!finish_reason) throw new Error("Model stream ended without model_finish");
+  return { text, tool_calls, finish_reason, ...(usage ? { usage } : {}) };
+}
+
+/** 构造单轮 system + user 文本消息。 */
+export function build_text_model_messages(system: string, prompt: string): ModelMessage[] {
+  return [
+    ...(system.trim()
+      ? [{ role: "system", content: [{ type: "text", text: system }] } as ModelMessage]
+      : []),
+    { role: "user", content: [{ type: "text", text: prompt }] },
+  ];
+}