@downcity/agent 1.1.320 → 1.1.324

package/src/types/sdk/AgentSessionPrompt.ts

@@ -19,6 +19,28 @@ export type SessionUserMessagePart = UIMessagePart<UIDataTypes, UITools>;
 
 /**
  * Session prompt 输入。
+ *
+ * 输入示例（中文）：
+ * ```ts
+ * session.prompt({
+ *   query: [
+ *     { type: "text", text: "请分析这个附件" },
+ *     {
+ *       type: "file",
+ *       mediaType: "image/png",
+ *       url: "data:image/png;base64,...",
+ *       filename: "image.png",
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * 生命周期说明（中文）：
+ * - `string` 会直接成为新的文本 User Message。
+ * - `file` part 如果携带 Data URL，会在 Message 入库前解码到 Session 的 attachments 目录。
+ * - 持久化 Message 里的 `url` 变成相对 Workspace 根目录的文件路径，而不是 Base64 内容。
+ * - 模型执行前，Executor 再按该路径读取文件，并转换成 AI SDK / Provider 可消费的 ModelMessage。
+ * - 远程 Session 中，Data URL 在服务端落盘；调用方本地路径必须对服务端可访问。
  */
 export interface AgentSessionPromptInput {
   /**

package/src/types/session/SessionMessages.ts

@@ -7,6 +7,7 @@
 import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 import type { SessionMessageStore } from "@/types/store/SessionStore.js";
+import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   SessionAssistantMessagePart,
@@ -20,6 +21,8 @@ export interface SessionMessagesOptions {
   session_id: string;
   /** Message 快照持久化 Store。 */
   store: SessionMessageStore;
+  /** 当前 Session 的附件持久化能力。 */
+  attachment_store: SessionAttachmentStore;
   /** 持久化成功后的实时 Mutation 发布函数。 */
   publish: (mutation: SessionMutation) => void;
 }

package/src/types/session/SessionOptions.ts

@@ -31,6 +31,9 @@ export interface AgentManagedSession extends AgentSession {
    */
   get_runtime_port(): SessionPort;
 
+  /** 取消并释放当前 Session 的标题后台任务。 */
+  dispose_title_generation?(): void;
+
   /**
    * 返回当前 session 是否正在执行。
    */

package/src/types/store/SessionAttachmentStore.ts

@@ -0,0 +1,29 @@
+/**
+ * Session 附件持久化能力。
+ *
+ * Session Message 只保存附件引用，附件内容由该 Store 在 Session 生命周期内持有。
+ *
+ * 数据边界（中文）：
+ * - 输入边界：`session.prompt()` 接收 `type: "file"`、`mediaType` 和 Data URL。
+ * - 存储边界：Store 解码 Data URL，写入 `.downcity/.../attachments/att_<id>.<ext>`。
+ * - Message 边界：Session Message 只记录相对 Workspace 根目录的附件路径。
+ * - 模型边界：模型转换器读取该路径，在内存中恢复成模型需要的文件内容。
+ *
+ * 因此，Data URL 不会直接进入 JSONL Message；Session Message 是附件路径的唯一引用。
+ */
+
+/** 可持久化的 Data URL 附件。 */
+export interface SessionAttachmentStore {
+  /**
+   * 保存 Data URL，并返回相对 Workspace 根目录的稳定文件路径。
+   * 调用成功后，返回路径对应的附件文件必须已经完整落盘。
+   */
+  persist_data_url(input: {
+    /** 完整的 Data URL。 */
+    data_url: string;
+    /** 调用侧声明的 MIME 类型。 */
+    media_type: string;
+    /** 可选的原始文件名，仅用于推导扩展名。 */
+    filename?: string;
+  }): Promise<string>;
+}

package/src/types/store/SessionStore.ts

@@ -17,6 +17,7 @@ import type {
   SessionSegmentSnapshot,
   SessionSegmentSummary,
 } from "@/types/session/SessionSegment.js";
+import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
 /** 在 Message Store 写事务中创建新消息所需的稳定状态。 */
 export interface SessionMessageCommitState {
@@ -88,6 +89,9 @@ export interface SessionStore {
   /** 当前 Session 的 Message 持久化能力。 */
   readonly messages: SessionMessageStore;
 
+  /** 当前 Session 的附件持久化能力。 */
+  readonly attachments: SessionAttachmentStore;
+
   /** 读取 Session Metadata；不存在时返回规范化的初始值。 */
   read_metadata(): Promise<SessionHistoryMetaV1>;
 

package/src/workspace/store/LocalSessionAttachmentStore.ts

@@ -0,0 +1,96 @@
+/**
+ * Workspace 内 Session 附件的本地实现。
+ *
+ * Data URL 在这里解码为文件；Message 层只接收相对 Workspace 根目录的文件引用。
+ */
+
+import path from "node:path";
+import { generate_id } from "@/utils/Id.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
+
+const DATA_URL_PATTERN = /^data:([^;,]+)?((?:;[^;,]+)*),(.*)$/s;
+
+const MEDIA_TYPE_EXTENSIONS: Record<string, string> = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/webm": ".webm",
+  "application/pdf": ".pdf",
+};
+
+export interface LocalSessionAttachmentStoreOptions {
+  /** Workspace 文件能力。 */
+  files: FileSystem;
+  /** 当前 Session 附件目录的绝对路径。 */
+  attachments_dir_path: string;
+}
+
+/** Session 附件本地持久化实现。 */
+export class LocalSessionAttachmentStore implements SessionAttachmentStore {
+  private readonly files: FileSystem;
+  private readonly attachments_dir_path: string;
+
+  constructor(options: LocalSessionAttachmentStoreOptions) {
+    this.files = options.files;
+    this.attachments_dir_path = path.resolve(options.attachments_dir_path);
+  }
+
+  async persist_data_url(input: {
+    data_url: string;
+    media_type: string;
+    filename?: string;
+  }): Promise<string> {
+    const parsed = parse_data_url(input.data_url, input.media_type);
+    const extension = resolve_extension(parsed.media_type, input.filename);
+    const attachment_name = `att_${generate_id()}${extension}`;
+    const absolute_path = path.join(this.attachments_dir_path, attachment_name);
+    await this.files.ensure_directory(this.attachments_dir_path);
+    await this.files.write_file_atomically(absolute_path, parsed.bytes);
+    return path.relative(this.files.root_path, absolute_path);
+  }
+}
+
+function parse_data_url(data_url: string, fallback_media_type: string): {
+  media_type: string;
+  bytes: Buffer;
+} {
+  const match = DATA_URL_PATTERN.exec(String(data_url || "").trim());
+  if (!match) throw new Error("Invalid data URL");
+
+  const media_type = String(match[1] || fallback_media_type || "").trim();
+  if (!media_type || !media_type.includes("/")) {
+    throw new Error("Data URL requires a valid media type");
+  }
+
+  const metadata = String(match[2] || "");
+  const payload = String(match[3] || "");
+  try {
+    const normalized_payload = payload.replace(/\s/g, "");
+    if (
+      metadata.includes(";base64") &&
+      (!/^[A-Za-z0-9+/]*={0,2}$/.test(normalized_payload) ||
+        normalized_payload.length % 4 === 1)
+    ) {
+      throw new Error("invalid base64 payload");
+    }
+    return {
+      media_type,
+      bytes: metadata.includes(";base64")
+        ? Buffer.from(normalized_payload, "base64")
+        : Buffer.from(decodeURIComponent(payload), "utf8"),
+    };
+  } catch (error) {
+    throw new Error(`Invalid data URL payload: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function resolve_extension(media_type: string, filename?: string): string {
+  const known = MEDIA_TYPE_EXTENSIONS[media_type.toLowerCase()];
+  if (known) return known;
+  const filename_extension = path.extname(String(filename || "")).toLowerCase();
+  return /^[.][a-z0-9]{1,10}$/.test(filename_extension) ? filename_extension : ".bin";
+}

package/src/workspace/store/LocalSessionStore.ts

@@ -12,12 +12,14 @@ import {
   get_sdk_agent_session_meta_path,
   get_sdk_agent_session_assistant_message_path,
   get_sdk_agent_session_messages_path,
+  get_sdk_agent_session_attachments_dir_path,
 } from "@/workspace/store/LocalStorePaths.js";
 import { normalize_session_metadata } from "@/session/storage/Metadata.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type { SessionStore } from "@/types/store/SessionStore.js";
 import type { FileSystem } from "@/types/workspace/FileSystem.js";
 import type { LocalSessionStoreOptions } from "@/types/store/LocalStore.js";
+import { LocalSessionAttachmentStore } from "@/workspace/store/LocalSessionAttachmentStore.js";
 
 /** 本地 Session Store。 */
 export class LocalSessionStore implements SessionStore {
@@ -27,6 +29,9 @@ export class LocalSessionStore implements SessionStore {
   /** 当前 Session 的 JSONL Message Store。 */
   readonly messages: JsonlSessionMessageStore;
 
+  /** 当前 Session 的附件持久化能力。 */
+  readonly attachments: LocalSessionAttachmentStore;
+
   /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
   private readonly files: FileSystem;
 
@@ -51,6 +56,14 @@ export class LocalSessionStore implements SessionStore {
         this.session_id,
       ),
     });
+    this.attachments = new LocalSessionAttachmentStore({
+      files: this.files,
+      attachments_dir_path: get_sdk_agent_session_attachments_dir_path(
+        this.files.root_path,
+        this.agent_id,
+        this.session_id,
+      ),
+    });
   }
 
   /** 读取规范化 Session Metadata。 */

package/src/workspace/store/LocalStorePaths.ts

@@ -161,6 +161,22 @@ export function get_sdk_agent_session_messages_dir_path(
   );
 }
 
+/**
+ * 单个 Session 的附件目录路径。
+ *
+ * 附件与 Session 目录同生命周期，归档或删除 Session 时随目录一起迁移或清理。
+ */
+export function get_sdk_agent_session_attachments_dir_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_session_dir_path(workspace_path, agent_id, session_id),
+    "attachments",
+  );
+}
+
 /**
  * 单个 session 的 Active JSONL 文件路径。
  */