openclaw-openagent 1.0.13 → 1.0.14

package/src/transport/oasn/oasn-files.ts

@@ -1,210 +0,0 @@
-/**
- * OASN 文件上传 + Artifact 下载
- *
- * 设计依据：
- *   - docs/specs/2026-06-16-oasn-api-module-mapping.md §2.16 / §2.17
- *   - docs/specs/2026-06-16-oasn-transport-abstraction-design.md §11.4（file_ref LRU）
- *
- * 端点：
- *   - POST /api/files                         multipart 上传 → file_ref
- *   - GET  /api/artifacts/{id}/content        二进制下载（带 Content-Disposition）
- *
- * §11.4 file_ref 过期刷新：
- *   - 维护内存 LRU：sha256(content) → { fileRef, expiresAt, mimeType, displayName }
- *   - 上传前调用 ensureFileRef(file)：命中且未过期 → 复用；否则重传
- *   - 条目数上限 100，淘汰用 LRU
- *   - expires_at 临近 60s 视为已过期（避免边缘竞态）
- *
- * 注意：
- *   - LRU 仅在单进程内有效；进程重启后丢失，会触发一次重传（可接受）
- *   - sha256 是 Node 内置，无外部依赖
- */
-
-import { createHash } from 'node:crypto';
-
-import { logger } from '../../util/logger.js';
-import type {
-  DownloadArtifactResult,
-  UploadFileParams,
-  UploadFileResult,
-} from '../types.js';
-import type { OasnHttpClient } from './oasn-http.js';
-import { OASN_ENDPOINTS, type UploadFileResponse } from './oasn-types.js';
-
-/** LRU 上限 */
-const FILE_REF_LRU_MAX = 100;
-/** expires_at 临近多少 ms 视为已过期 */
-const EXPIRY_MARGIN_MS = 60_000;
-
-interface FileRefCacheEntry {
-  fileRef: string;
-  /** epoch ms */
-  expiresAt: number;
-  mimeType: string;
-  displayName: string;
-  sizeBytes: number;
-}
-
-export class OasnFiles {
-  /**
-   * §11.4 LRU 缓存。
-   * 利用 Map 的插入顺序天然 = 访问顺序：每次访问后 delete + set 重新插入到尾部。
-   */
-  private _refCache = new Map<string, FileRefCacheEntry>();
-
-  constructor(private readonly _http: OasnHttpClient) {}
-
-  // ═══════════════════════════════════════════════════════════════
-  // 上传
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 上传文件，返回 file_ref。
-   *
-   * 调用方应优先用 ensureFileRef() 复用；本方法是"无脑重传"路径。
-   */
-  async uploadFile(file: UploadFileParams): Promise<UploadFileResult> {
-    const buffer = await this._toBuffer(file.content);
-    return this._doUpload(buffer, file);
-  }
-
-  /**
-   * §11.4 入口：根据内容 hash 命中缓存就复用，否则重传。
-   * sendTask 前应调用此方法，避免 file_ref 过期导致 invocation 400。
-   */
-  async ensureFileRef(file: UploadFileParams): Promise<UploadFileResult> {
-    const buffer = await this._toBuffer(file.content);
-    const hash = this._hashBuffer(buffer);
-    const cached = this._refCache.get(hash);
-
-    if (cached && cached.expiresAt - EXPIRY_MARGIN_MS > Date.now()) {
-      // LRU touch：移到尾部
-      this._refCache.delete(hash);
-      this._refCache.set(hash, cached);
-      logger.info(`[transport/oasn/files] file_ref cache HIT hash=${hash.slice(0, 8)} ref=${cached.fileRef}`);
-      return {
-        fileRef: cached.fileRef,
-        displayName: cached.displayName,
-        mimeType: cached.mimeType,
-        sizeBytes: cached.sizeBytes,
-        expiresAt: cached.expiresAt,
-      };
-    }
-
-    // 未命中或已过期 → 重传
-    if (cached) {
-      logger.info(`[transport/oasn/files] file_ref cache STALE hash=${hash.slice(0, 8)}, will re-upload`);
-      this._refCache.delete(hash);
-    }
-    const result = await this._doUpload(buffer, file);
-    this._cachePut(hash, result);
-    return result;
-  }
-
-  // ═══════════════════════════════════════════════════════════════
-  // 下载（Artifact 二进制内容）
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 下载 Artifact 内容。
-   *
-   * 注意：不缓存（artifact 一般是大文件 / 一次性消费），需要缓存的请上层包装。
-   */
-  async downloadArtifact(artifactIdOrContentUrl: string): Promise<DownloadArtifactResult> {
-    logger.info(`[transport/oasn/files] downloadArtifact ref=${artifactIdOrContentUrl}`);
-    const path = this._artifactContentPath(artifactIdOrContentUrl);
-    const resp = await this._http.getBinary(path);
-    return {
-      content: resp.content,
-      mimeType: resp.mimeType,
-      displayName: resp.displayName,
-    };
-  }
-
-  // ═══════════════════════════════════════════════════════════════
-  // 内部
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * 实际上传逻辑。multipart/form-data：
-   *   - file       文件二进制
-   *   - display_name / purpose / expires_in_seconds  字段（按需）
-   */
-  private async _doUpload(buffer: Buffer, file: UploadFileParams): Promise<UploadFileResult> {
-    const fields: Record<string, string> = {
-      display_name: file.displayName,
-    };
-    if (file.purpose) fields.purpose = file.purpose;
-    if (file.expiresInSeconds !== undefined) fields.expires_in_seconds = String(file.expiresInSeconds);
-
-    logger.info(
-      `[transport/oasn/files] upload name=${file.displayName} size=${buffer.byteLength} `
-      + `mime=${file.mimeType ?? 'auto'} purpose=${file.purpose ?? 'none'}`,
-    );
-
-    const resp = await this._http.postMultipart<UploadFileResponse>(
-      OASN_ENDPOINTS.FILES,
-      {
-        file: {
-          content: buffer,
-          filename: file.displayName,
-          mimeType: file.mimeType,
-        },
-        fields,
-      },
-    );
-
-    return {
-      fileRef: resp.fileRef ?? resp.file_ref ?? '',
-      displayName: resp.displayName ?? resp.display_name ?? 'unknown',
-      mimeType: resp.mimeType ?? resp.mime_type ?? 'application/octet-stream',
-      sizeBytes: resp.sizeBytes ?? resp.size_bytes ?? 0,
-      expiresAt: this._parseExpiresAt(resp.expiresAt ?? resp.expires_at ?? ''),
-    };
-  }
-
-  /** Map LRU put：满了就淘汰最旧 */
-  private _cachePut(hash: string, result: UploadFileResult): void {
-    if (this._refCache.size >= FILE_REF_LRU_MAX) {
-      // 淘汰第一个 key（Map 迭代顺序 = 插入/touch 顺序）
-      const firstKey = this._refCache.keys().next().value;
-      if (firstKey !== undefined) {
-        this._refCache.delete(firstKey);
-        logger.info(`[transport/oasn/files] LRU evict hash=${(firstKey as string).slice(0, 8)}`);
-      }
-    }
-    this._refCache.set(hash, {
-      fileRef: result.fileRef,
-      expiresAt: result.expiresAt,
-      mimeType: result.mimeType,
-      displayName: result.displayName,
-      sizeBytes: result.sizeBytes,
-    });
-  }
-
-  private _artifactContentPath(artifactIdOrContentUrl: string): string {
-    if (/^https?:\/\//i.test(artifactIdOrContentUrl) || artifactIdOrContentUrl.startsWith('/')) {
-      return artifactIdOrContentUrl;
-    }
-    return OASN_ENDPOINTS.ARTIFACT_CONTENT(artifactIdOrContentUrl);
-  }
-
-  /** Blob | Buffer → Buffer */
-  private async _toBuffer(content: Blob | Buffer): Promise<Buffer> {
-    if (Buffer.isBuffer(content)) return content;
-    // Browser Blob path（Node 18+ 内置 Blob）
-    const ab = await content.arrayBuffer();
-    return Buffer.from(ab);
-  }
-
-  /** sha256 hex —— 标识文件唯一性 */
-  private _hashBuffer(buf: Buffer): string {
-    return createHash('sha256').update(buf).digest('hex');
-  }
-
-  /** ISO 8601 → epoch ms（解析失败时给 0，让缓存下次 miss） */
-  private _parseExpiresAt(iso: string): number {
-    const ms = Date.parse(iso);
-    return Number.isNaN(ms) ? 0 : ms;
-  }
-}