@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/src/images/prompt.ts

@@ -0,0 +1,289 @@
+import { IMAGE_REFERENCE_KEY } from '../turn/parts-to-model-messages.js';
+
+/**
+ * 图片递送的 prompt 层：把投影层发出的 `{[IMAGE_REFERENCE_KEY]: src}` 引用，在请求前变成
+ * 厂商真正吃得下的东西。只做重排 + 逐张交给 `ImageResolver`，三档的判据在 `delivery.ts`。
+ *
+ * ## 为什么在请求这一层、而不是投影层或 provider 包里
+ *
+ * - 投影层是纯函数、且「模型看得见的一切都必须能从库里重建」——库里只有 `src`。字节、URL、
+ *   厂商 file id 都是**这一次请求**的临时物，与历史无关。
+ * - chat-completions 的承载包把 tool-result 的 `content` 变体一律 `JSON.stringify`
+ *   （`@ai-sdk/deepseek@3.0.31` / `@ai-sdk/openai-compatible@3.0.35` dist 已核），图放在工具
+ *   输出里根本到不了模型；`@ai-sdk/openai` 的 responses 认 `content` 里的 data/url 却不认
+ *   `reference`（Files API 走不通）。所以两条协议**统一**：图从工具输出里剥出来，**挪进紧随
+ *   其后的一条合成 user 消息**——各承载包对 user 消息里的 file part 三种 data 形态都翻译得对。
+ * - 合成消息出现在 provider prompt 层，投影层 `ModelMessage[]` 条数不变，上下文预算的条数
+ *   守卫因此与它无关。
+ *
+ * ## 字节稳定
+ *
+ * 同一张图每一轮都要重发，前缀缓存要求它逐字节相同：`src` 内容不可变，这里只搬运不改动；
+ * 合成消息的文案也必须是 `src` / `path` / 工具名的确定函数（`DeliveryTexts` 由宿主换时同样要守）。
+ * **换档会破一次缓存**（首轮 base64、次轮 file id）——可接受，Files API 命中之后就稳定了。
+ */
+
+/** 递送看到的 V4 prompt 片段——只声明本层读写的字段。 */
+export type FileData =
+  | { type: 'data'; data: Uint8Array | string }
+  | { type: 'url'; url: URL }
+  | { type: 'reference'; reference: Record<string, string> }
+  | { type: 'text'; text: string };
+export interface V4FilePart {
+  type: 'file';
+  data: FileData;
+  mediaType: string;
+  filename?: string;
+  providerOptions?: Record<string, Record<string, unknown>>;
+}
+export interface V4TextPart {
+  type: 'text';
+  text: string;
+  providerOptions?: Record<string, Record<string, unknown>>;
+}
+type V4ToolOutput =
+  | { type: 'text'; value: string }
+  | { type: 'content'; value: Array<V4TextPart | V4FilePart> }
+  | { type: string; value?: unknown };
+interface V4ToolResultPart {
+  type: 'tool-result';
+  toolCallId: string;
+  toolName: string;
+  output: V4ToolOutput;
+}
+export type V4Message =
+  | { role: 'system'; content: string }
+  | { role: 'user'; content: Array<V4TextPart | V4FilePart> }
+  | { role: 'assistant'; content: unknown[] }
+  | { role: 'tool'; content: Array<V4ToolResultPart | { type: string }> };
+
+/** 一张待递送的图：投影层引用 + 它挂在哪次工具调用上。 */
+export interface PendingImage {
+  src: string;
+  mediaType: string;
+  path: string | null;
+  toolName: string;
+}
+
+/**
+ * 递送结果：一个能直接放进 user 消息的 file part，或一句解释。走了厂商 Files API 的那一档
+ * 带上 `vendorFileId`——请求被厂商以「file id 不存在」拒掉时要按它作废缓存。
+ */
+export type DeliveredImage =
+  | { kind: 'file'; part: V4FilePart; vendorFileId?: string }
+  | { kind: 'unavailable'; reason: string };
+
+export type ImageResolver = (image: PendingImage) => Promise<DeliveredImage>;
+
+/**
+ * 合成消息的文案。缺省是中文；宿主可整套或逐条换，但每一条都必须是入参的确定函数
+ * （见头注「字节稳定」）。
+ */
+export interface DeliveryTexts {
+  /** 一张图在合成消息里的标题行。`path` 缺席时报 src，好让模型知道是哪一张。 */
+  caption(image: PendingImage): string;
+  /** 图取不到时的那句话（接在标题后）。 */
+  unavailable: string;
+  /** 工具正文被剥掉图之后、正文又恰好为空时的占位（模型得知道图去了哪）。 */
+  stripped: string;
+  /**
+   * 合成 user 消息的尾注。这条消息挂着 `user` 角色，模型会把它读成「用户又发了一条消息、
+   * 还附了图」，于是有的模型（GLM）收到图之后再调一次看图工具去「处理这张新图」——白白多
+   * 一轮。角色改不了（图只在 user 消息里翻译得对），能做的是把话说明白。分两段：「不是新消息」
+   * 恒加（`trailer`）；「别再调」只在至少一张图真送到时加（`trailerDelivered`）——图递不出去时
+   * 文案本身就在建议重新读取，再接一句「不必再调」就自相矛盾。
+   */
+  trailer: string;
+  trailerDelivered: string;
+}
+
+export const DEFAULT_DELIVERY_TEXTS: DeliveryTexts = {
+  caption: img => `【${img.toolName} 的附图】${img.path ?? `图片 ${img.src}`}`,
+  unavailable:
+    '这张图已取不到（可能被清理）。它若仍在工作区，可以让工具重新读取。',
+  stripped: '（本次结果是图片，见紧随其后的消息。）',
+  trailer: '（以上是你刚才那次工具调用返回的附图，不是用户发来的新消息。）',
+  trailerDelivered:
+    '（以上是你刚才那次工具调用返回的附图，不是用户发来的新消息；' +
+    '图已经在这里了，不必再调用工具查看同一张图。）',
+};
+
+function isOurImage(part: V4TextPart | V4FilePart): part is V4FilePart {
+  return (
+    part.type === 'file' &&
+    part.data.type === 'reference' &&
+    typeof part.data.reference[IMAGE_REFERENCE_KEY] === 'string'
+  );
+}
+
+function pendingOf(part: V4FilePart, toolName: string): PendingImage {
+  const data = part.data as { reference: Record<string, string> };
+  const opts = part.providerOptions?.[IMAGE_REFERENCE_KEY];
+  const path = opts && typeof opts.path === 'string' ? opts.path : null;
+  return {
+    src: data.reference[IMAGE_REFERENCE_KEY],
+    mediaType: part.mediaType,
+    path,
+    toolName,
+  };
+}
+
+function ourImagesOf(part: { type: string }): V4FilePart[] {
+  if (part.type !== 'tool-result') return [];
+  const out = (part as V4ToolResultPart).output;
+  if (out.type !== 'content' || !Array.isArray(out.value)) return [];
+  return (out.value as Array<V4TextPart | V4FilePart>).filter(isOurImage);
+}
+
+/** prompt 里全部待递送的图（按出现顺序，可能有重复的 src）。 */
+export function collectPendingImages(
+  prompt: readonly V4Message[]
+): PendingImage[] {
+  const out: PendingImage[] = [];
+  for (const msg of prompt) {
+    if (msg.role !== 'tool') continue;
+    for (const part of msg.content) {
+      for (const f of ourImagesOf(part)) {
+        out.push(pendingOf(f, (part as V4ToolResultPart).toolName));
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * 把一份 prompt 里我们的图片引用全部解析掉。纯粹的重排 + 逐张 `resolve`（按出现顺序、
+ * 串行——第一张上传定下的账号要给后面的用），不碰别的消息。
+ */
+export async function deliverImages(
+  prompt: readonly V4Message[],
+  resolve: ImageResolver,
+  texts: DeliveryTexts = DEFAULT_DELIVERY_TEXTS
+): Promise<V4Message[]> {
+  const out: V4Message[] = [];
+  for (const msg of prompt) {
+    if (msg.role !== 'tool') {
+      out.push(msg);
+      continue;
+    }
+    const pending: PendingImage[] = [];
+    const content = msg.content.map(part => {
+      const ours = ourImagesOf(part);
+      if (ours.length === 0) return part;
+      const tr = part as V4ToolResultPart;
+      for (const f of ours) pending.push(pendingOf(f, tr.toolName));
+      const rest = (tr.output.value as Array<V4TextPart | V4FilePart>).filter(
+        p => !isOurImage(p)
+      );
+      // 剥掉图之后若只剩文本，就退回最普通的 `text` 变体——各家对它的翻译最稳；若还有别的
+      // file part（不是我们的引用），保留 `content` 变体原样交出去。
+      const onlyText = rest.every(p => p.type === 'text');
+      const text = rest
+        .filter((p): p is V4TextPart => p.type === 'text')
+        .map(p => p.text)
+        .join('\n');
+      return {
+        ...tr,
+        output: onlyText
+          ? { type: 'text', value: text.trim() === '' ? texts.stripped : text }
+          : { type: 'content', value: rest },
+      };
+    });
+    out.push({ ...msg, content } as V4Message);
+    if (pending.length === 0) continue;
+
+    const parts: Array<V4TextPart | V4FilePart> = [];
+    let anyDelivered = false;
+    for (const img of pending) {
+      const delivered = await resolve(img);
+      if (delivered.kind === 'file') {
+        anyDelivered = true;
+        parts.push({ type: 'text', text: texts.caption(img) }, delivered.part);
+      } else {
+        parts.push({
+          type: 'text',
+          text: `${texts.caption(img)}——无法显示：${delivered.reason}`,
+        });
+      }
+    }
+    parts.push({
+      type: 'text',
+      text: anyDelivered ? texts.trailerDelivered : texts.trailer,
+    });
+    out.push({ role: 'user', content: parts });
+  }
+  return out;
+}
+
+/**
+ * 公网 URL 那一档的判据：承载包声明它会自己去取这类 URL。`supportedUrls` 的 key 是媒体
+ * 类型模式（`image/*`），值是 URL 正则数组——照 `ai` 核心 `isUrlSupported` 的比对方式。
+ * （`ai` 核心在 middleware 之前已经转换完 prompt，不会替我们下载，所以这一档必须自己判。）
+ */
+export function urlSupported(
+  supportedUrls: Record<string, RegExp[]>,
+  mediaType: string,
+  url: string
+): boolean {
+  for (const [pattern, regexes] of Object.entries(supportedUrls)) {
+    if (!mediaTypeMatches(pattern, mediaType)) continue;
+    if (regexes.some(re => re.test(url))) return true;
+  }
+  return false;
+}
+
+function mediaTypeMatches(pattern: string, mediaType: string): boolean {
+  if (pattern === '*' || pattern === '*/*') return true;
+  if (pattern.endsWith('/*')) {
+    return mediaType
+      .toLowerCase()
+      .startsWith(pattern.slice(0, -1).toLowerCase());
+  }
+  return pattern.toLowerCase() === mediaType.toLowerCase();
+}
+
+/**
+ * 一个请求错误的全部文字：message、`responseBody`（AI SDK 的 `APICallError` 把中心 / 厂商的
+ * 原始响应体放在这里，message 往往只是厂商包解析过的一句）、`cause` 链。
+ */
+export function errorText(err: unknown): string {
+  const seen = new Set<unknown>();
+  const parts: string[] = [];
+  let cur: unknown = err;
+  while (cur && !seen.has(cur)) {
+    seen.add(cur);
+    if (cur instanceof Error) parts.push(cur.message);
+    else parts.push(String(cur));
+    const body = (cur as { responseBody?: unknown }).responseBody;
+    if (typeof body === 'string') parts.push(body);
+    cur = (cur as { cause?: unknown }).cause;
+  }
+  return parts.join('\n');
+}
+
+/**
+ * 厂商拒绝了我们交出去的 file id 吗。判据是错误文本里**点名了**这次用到的 id——比匹配某家的
+ * 措辞稳（DeepSeek 的原文是「the following file_ids do not exist or are not created under
+ * your account: file-api-…」，探针 2026-08-27），也天然厂商无关。
+ */
+export function mentionsVendorFile(
+  err: unknown,
+  vendorFileIds: readonly string[]
+): boolean {
+  return rejectedVendorFiles(err, vendorFileIds).length > 0;
+}
+
+/** 错误里点了名的那几个 id（只忘掉它们：别的文件还在，重传是白花配额）。 */
+export function rejectedVendorFiles(
+  err: unknown,
+  vendorFileIds: readonly string[]
+): string[] {
+  if (vendorFileIds.length === 0) return [];
+  const text = errorText(err);
+  return [...new Set(vendorFileIds.filter(id => text.includes(id)))];
+}
+
+/** 中心说钉住的那把 key 不可用（409 `pinned_credential_unavailable`，不会自己切换）。 */
+export function isPinnedCredentialUnavailable(err: unknown): boolean {
+  return errorText(err).includes('pinned_credential_unavailable');
+}

package/src/images/vendor-files.ts

@@ -0,0 +1,235 @@
+import { type Logger, silentLogger } from '../ports/logger.js';
+import type {
+  VendorFileCache,
+  VendorFileRecord,
+} from '../ports/vendor-file-cache.js';
+
+/** 直连模式（上传结果没有 `credentialRef`）下的账号名：只有一把 key，不 pin。 */
+export const DIRECT_ACCOUNT = 'direct';
+
+/**
+ * 到期前多久就当失效。DeepSeek 允许的最短 TTL 是 1h；6h 的边际保证一条长对话在我们判
+ * 「还有效」到请求真正发出之间不会跨过到期点。
+ */
+export const VENDOR_FILE_EXPIRY_MARGIN_MS = 6 * 60 * 60 * 1000;
+/**
+ * 上传 TTL 的下限：余量的两倍。TTL 短于余量的话文件一传上去就「不新鲜」，每一轮都重传
+ * （验收脚本配 1h 时踩到过）；短于两倍则新鲜期还不到 TTL 的一半。宿主配得更短时抬到这里。
+ */
+export const MIN_VENDOR_FILE_TTL_SECONDS =
+  (2 * VENDOR_FILE_EXPIRY_MARGIN_MS) / 1000;
+/** `lastUsedAt` 的写入节流：它只服务于排查与挑 pin，不值得每个请求写一次。 */
+const TOUCH_INTERVAL_MS = 60 * 60 * 1000;
+
+/** 上传要的那一点 Files API（`ModelHandle.fileStore` 的结构子集）。 */
+export interface VendorFileStoreLike {
+  /** `FilePart.data.reference` 的命名空间 key（跟承载包走）。 */
+  referenceKey: string;
+  upload(input: {
+    data: Uint8Array;
+    mediaType: string;
+    filename?: string;
+    ttlSeconds?: number;
+  }): Promise<{
+    fileId: string;
+    expiresAt: Date | null;
+    /** 中心模式：文件落在哪把 key 上；直连为 null。 */
+    credentialRef: string | null;
+  }>;
+  delete(fileId: string): Promise<void>;
+}
+
+export interface VendorFilesOptions {
+  cache: VendorFileCache;
+  /**
+   * 上传时的 `ttlSeconds`；省略或 ≤0 = 厂商默认（DeepSeek 是永久）。宿主可接系统参数，每次上传读一次。
+   * 低于 `MIN_VENDOR_FILE_TTL_SECONDS`（12h）时按 12h 发。
+   */
+  ttlSeconds?: () => number | undefined;
+  logger?: Logger;
+  now?: () => number;
+}
+
+export interface UploadInput {
+  vendor: string;
+  store: VendorFileStoreLike;
+  contentHash: string;
+  src: string | null;
+  data: Uint8Array;
+  mediaType: string;
+  filename?: string;
+  /**
+   * 这份字节已有的记录（任一账号，含快到期 / 已到期的）：传成功后，落在同一账号上的旧那份
+   * 顺手删掉厂商侧副本——上传前不知道会落在哪个账号，所以全给、传完再挑。
+   */
+  previous?: readonly VendorFileRecord[];
+}
+
+/**
+ * 厂商文件的取用与上传（agent-base 的 `LlmVendorFileService`）。
+ *
+ * 与 agent-base 的差别：(1) 存储换成 `VendorFileCache` 端口，进程内 Map 那一层由端口实现
+ * 自己决定（库实现可以自带）；(2) 键从「凭证 id」换成「厂商 + 账号」，账号由上传结果的
+ * `credentialRef` 定——中心替我们选 key，上传前不知道会落在哪；(3) 查询按「任一账号」查，
+ * 给挑 pin 用。
+ *
+ * **失败一律不抛**：上传不成就退到下一档递送（公网 URL / base64），一次厂商侧抖动不该让整轮失败。
+ */
+export class VendorFiles {
+  private readonly logger: Logger;
+  private readonly now: () => number;
+  private readonly inflight = new Map<
+    string,
+    Promise<VendorFileRecord | null>
+  >();
+
+  constructor(private readonly options: VendorFilesOptions) {
+    this.logger = options.logger ?? silentLogger('VendorFiles');
+    this.now = options.now ?? Date.now;
+  }
+
+  isFresh(record: VendorFileRecord): boolean {
+    return (
+      record.expiresAt === null ||
+      record.expiresAt.getTime() - VENDOR_FILE_EXPIRY_MARGIN_MS > this.now()
+    );
+  }
+
+  /** 这些字节在这家厂商任一账号上的记录（含不新鲜的，调用方据 `isFresh` 分）。查不了给空。 */
+  async lookup(
+    vendor: string,
+    contentHashes: readonly string[]
+  ): Promise<VendorFileRecord[]> {
+    if (contentHashes.length === 0) return [];
+    try {
+      return await this.options.cache.find(vendor, contentHashes);
+    } catch (err) {
+      this.logger.warn(`vendor file lookup failed (ignored): ${String(err)}`);
+      return [];
+    }
+  }
+
+  /** 用上了一条记录：节流地记 `lastUsedAt`。不抛。 */
+  touch(record: VendorFileRecord): void {
+    const at = this.now();
+    if (at - record.lastUsedAt.getTime() < TOUCH_INTERVAL_MS) return;
+    record.lastUsedAt = new Date(at);
+    this.options.cache.touch(record, new Date(at)).catch((err: unknown) => {
+      this.logger.warn(`vendor file touch failed (ignored): ${String(err)}`);
+    });
+  }
+
+  /**
+   * 上传并记账；拿不到给 null。同一进程内对同一 (厂商, 字节, 期望账号) 的并发调用合流成
+   * 一次上传。`expectedAccount` 只用来区分合流键（pin 不同的两次上传不能合）。
+   */
+  upload(
+    input: UploadInput,
+    expectedAccount: string | undefined
+  ): Promise<VendorFileRecord | null> {
+    const key = `${input.vendor}\u0000${expectedAccount ?? ''}\u0000${input.contentHash}`;
+    const pending = this.inflight.get(key);
+    if (pending) return pending;
+    const p = this.uploadSlow(input).finally(() => {
+      this.inflight.delete(key);
+    });
+    this.inflight.set(key, p);
+    return p;
+  }
+
+  private async uploadSlow(
+    input: UploadInput
+  ): Promise<VendorFileRecord | null> {
+    const ttl = this.options.ttlSeconds?.();
+    let uploaded: Awaited<ReturnType<VendorFileStoreLike['upload']>>;
+    try {
+      uploaded = await input.store.upload({
+        data: input.data,
+        mediaType: input.mediaType,
+        ...(input.filename !== undefined ? { filename: input.filename } : {}),
+        ...(ttl !== undefined && ttl > 0
+          ? { ttlSeconds: Math.max(ttl, MIN_VENDOR_FILE_TTL_SECONDS) }
+          : {}),
+      });
+    } catch (err) {
+      this.logger.warn(
+        `vendor file upload failed for ${input.vendor} (${input.contentHash.slice(0, 12)}): ${String(err)}`
+      );
+      return null;
+    }
+    const record: VendorFileRecord = {
+      vendor: input.vendor,
+      account: uploaded.credentialRef ?? DIRECT_ACCOUNT,
+      contentHash: input.contentHash,
+      fileId: uploaded.fileId,
+      src: input.src,
+      mediaType: input.mediaType,
+      bytes: input.data.byteLength,
+      expiresAt: uploaded.expiresAt,
+      lastUsedAt: new Date(this.now()),
+    };
+    try {
+      await this.options.cache.put(record);
+    } catch (err) {
+      // 传成功了但记账失败：这一轮仍然能用，只是下次要再传一遍。
+      this.logger.error(
+        `vendor file bookkeeping failed for ${input.contentHash.slice(0, 12)}: ${String(err)}`
+      );
+    }
+    const old = input.previous?.find(
+      r => r.account === record.account && r.fileId !== record.fileId
+    );
+    if (old) {
+      // 旧的那份顺手删，删不掉也无妨（它自己会到期）。
+      input.store.delete(old.fileId).catch((err: unknown) => {
+        this.logger.warn(
+          `vendor file ${old.fileId} delete failed (ignored): ${String(err)}`
+        );
+      });
+    }
+    return { ...record };
+  }
+
+  /** 厂商说这些 id 不存在了：忘掉。下一次递送重传。不去厂商侧 delete——它已经说没有了。 */
+  async forget(
+    vendor: string,
+    account: string,
+    fileIds: readonly string[]
+  ): Promise<void> {
+    if (fileIds.length === 0) return;
+    try {
+      await this.options.cache.forget(vendor, account, fileIds);
+      this.logger.warn(
+        `forgot ${fileIds.length} vendor file(s) rejected by ${vendor} (account ${account})`
+      );
+    } catch (err) {
+      this.logger.warn(`vendor file forget failed (ignored): ${String(err)}`);
+    }
+  }
+
+  /** 清掉已经到期的记录（厂商侧早已自动删除）。由宿主定时调用，或用 `startSweep`。 */
+  sweepExpired(): Promise<number> {
+    return this.options.cache.sweepExpired(new Date(this.now()));
+  }
+
+  /**
+   * 定时清到期记录（缺省 5 分钟一次，no-throw，定时器 unref）。返回停止函数。
+   * 删的是自己的记录、幂等，多实例各清各的也无妨。
+   */
+  startSweep(intervalMs = 5 * 60 * 1000): () => void {
+    const tick = () => {
+      this.sweepExpired().then(
+        n => {
+          if (n > 0) this.logger.log(`swept ${n} expired vendor file(s)`);
+        },
+        (err: unknown) => {
+          this.logger.warn(`vendor file sweep failed: ${String(err)}`);
+        }
+      );
+    };
+    tick();
+    const timer = setInterval(tick, intervalMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+  }
+}