@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.0

package/dist/services/AssetService.d.ts

@@ -0,0 +1,338 @@
+/**
+ * 素材服务：上传产物的落定与登记、取用时变成内容段（F-H7 / R44）、按引用清理（R33）、
+ * 以及「落库只有 `__asset_id`」这条口径的两端。
+ *
+ * 它围着 `assets` 这一份真相做五件事：
+ *
+ *   1. **落定**（{@link AssetService.finalizeUpload}）：上传接收器（`net/UploadReceiver`）把字节收进
+ *      临时文件之后，本服务把它改名为正式文件、在 `assets` 表登记一行、回一个 {@link AssetRef}。
+ *      库里已经有同摘要的那一行时不重复落文件（全局去重），回既有那一行。
+ *   2. **取用**（{@link AssetService.prepareAttachments}）：`MessageInput.assetIds` → core 的内容段。
+ *      走文件引用、内联 base64 还是退化成文字，由**实发模型与它所用端点**决定，判定逻辑用 SDK 的
+ *      `fileToContentSection`（同一份口径，不在这里另写一遍）。没送出去的一律如实记账，不假装成功。
+ *      同时给出「落库用」的那一份内容：素材在那里写成段上的 `__asset_id`（本地扩展字段）。
+ *   3. **重放**（{@link AssetService.resolveHistory}）：历史里的 `__asset_id` 在每轮发送前还原成
+ *      当前模型能吃的内容段 —— 换了模型、重启之后再跑，同一条历史照样发得出去。发出去的那一份
+ *      经 core 的 `formatContent` 按字段白名单重建，`__` 开头的键不会出网。
+ *   4. **厂商 file_id 的缓存**：`assets` 是真相；厂商的 `file_id` 是端点维度资源，落在
+ *      `asset_vendor_files`（{@link AssetService.vendorFiles}）。三条：
+ *        - 这个端点上有缓存行 → 直接用那个 `vendorFileId`；
+ *        - 这个端点上没有、别的端点上有（换厂商 / 换端点）→ 内联 base64，不往新端点重传；
+ *        - 哪个端点上都没有 → 上传一次并写回。
+ *      发送失败就报失败：不自动重试、不判失效、不清缓存。
+ *   5. **清理**（{@link AssetService.sweepUnreferenced}）：引用归零的素材才删行、删文件。关系行
+ *      （`conversation_assets`）由外键级联删，所以这里判的是「删完之后还剩几张引用」。
+ *      这一层是碰 `assets/` 下**正式文件**的地方（临时文件的生与死归上传接收器）。
+ *
+ * 它被 `ChatRunner` 当作 `prepareAttachments` / `prepareHistory` / `linkMessageAssets` 注入
+ * （PRD F-H7 / 裁定 R44）。
+ */
+import type { AgentNS } from "@ai-zen/agents-core";
+import type { Endpoint, Model, ToolEnvDeps } from "@ai-zen/agents-sdk";
+import type { HostPaths } from "../config.js";
+import type { UploadFinalizeRequest } from "../net/UploadReceiver.js";
+import type { AttachmentPreparer, MessageAssetLinker } from "../runtime/ChatRunner.js";
+import { type AssetGetResult, type AssetRef, type AssetVariant, type LocalMessageContentSection, type ProblemFact } from "../wire/index.js";
+/**
+ * 素材行：本服务用到的字段（结构上等于存储层的 `AssetRow`）。
+ *
+ * 这里单独声明一份窄形状，是为了让本服务只依赖「它真的读的那些字段」，
+ * `AssetRepository` 结构上满足它，接线处直接传进来即可。
+ */
+export interface AssetRecord {
+    id: string;
+    name: string | null;
+    /** 数据根下的相对路径（如 `assets/<id>.png`） */
+    path: string;
+    mime: string;
+    bytes: number;
+    /** 内容摘要；全库唯一，所以它也是去重的键 */
+    sha256: string;
+    /** 像素宽度：落定时按文件头解出（PNG / JPEG），解不出来为 `null` */
+    width: number | null;
+    /** 像素高度；口径同 `width` */
+    height: number | null;
+    createdAt: number;
+}
+/** 一条厂商 file_id 缓存行（结构上等于存储层的 `AssetVendorFileRow`） */
+export interface VendorFileRecord {
+    assetId: string;
+    endpointId: string;
+    vendorFileId: string;
+    createdAt: number;
+}
+/** 一个素材的缓存行分布：这个端点上有没有、别的端点上有没有 */
+export interface VendorFilePresence {
+    /** 这个端点上已经有缓存行（命中就复用那个 file_id） */
+    onEndpoint: boolean;
+    /** 别的端点上有（换过厂商 / 端点，这次走内联） */
+    elsewhere: boolean;
+}
+/** 素材仓储里本服务用到的部分（`AssetRepository` 结构上满足） */
+export interface AssetRegistry {
+    /** 插入；库里已有同摘要的那一行时回既有行（`created: false`） */
+    upsert(input: {
+        id: string;
+        name?: string | null;
+        path: string;
+        mime: string;
+        bytes: number;
+        sha256: string;
+        width?: number | null;
+        height?: number | null;
+        createdAt: number;
+    }): Promise<{
+        row: AssetRecord;
+        created: boolean;
+    }>;
+    get(id: string): Promise<AssetRecord | undefined>;
+    /** 按内容摘要找（`asset.begin` 带 sha256 时的去重命中判定，全库范围） */
+    findByDigest(sha256: string): Promise<AssetRecord | undefined>;
+    /** 记一行「这条消息引用了这份素材」；已经有这一行时返回 0 */
+    linkAsset(input: {
+        conversationId: string;
+        messageId: string;
+        assetId: string;
+        createdAt: number;
+    }): Promise<number>;
+    /** 这份素材被几行引用 */
+    countReferences(assetId: string): Promise<number>;
+    /** 归零才删（还有引用时返回 0，删不掉） */
+    deleteIfUnreferenced(assetId: string): Promise<number>;
+}
+/**
+ * 厂商 file_id 缓存表的窄接口（`AssetRepository` 结构上满足）。
+ *
+ * 单列一个口子是为了让「缓存只是一张表」这件事在类型上就是真的：本服务只用这三个动作，
+ * 没有第二个地方会去改它。
+ */
+export interface AssetVendorRegistry {
+    getVendorFile(assetId: string, endpointId: string): Promise<VendorFileRecord | undefined>;
+    upsertVendorFile(input: VendorFileRecord): Promise<void>;
+    /** 这个素材的缓存行分布（决定这次是复用、内联还是上传） */
+    describeVendorFiles(assetId: string, endpointId: string): Promise<VendorFilePresence>;
+}
+/**
+ * 实发模型的上下文：模型与它绑定的端点。
+ *
+ * 两者都不能只看 id 就猜：`file_id` 是端点维度的资源（传错端点会 not found），
+ * 「这个模型能不能看图」在模型定义上。谁解析出来由配置层决定，这里只收结果。
+ */
+export interface AttachmentModelContext {
+    model: Model | null;
+    endpoint: Endpoint | null;
+}
+/** 按模型 id 找模型与端点；找不到就回 `null` 字段（调用方按「没有能力信息」处理） */
+export type AttachmentModelResolver = (modelId: string | null) => Promise<AttachmentModelContext> | AttachmentModelContext;
+/** `ChatRunner` 注入点的入参（结构即契约，直接从那里取，不另定义一份） */
+export type AttachmentPrepareContext = Parameters<AttachmentPreparer>[0];
+/** `prepareAttachments` 的出参（同上） */
+export type AttachmentPreparation = Awaited<ReturnType<AttachmentPreparer>>;
+/** `ChatRunner` 的素材关系登记口（结构即契约，同上） */
+export type MessageAssetLinkContext = Parameters<MessageAssetLinker>[0];
+/** 素材服务依赖；由单根组装后注入 */
+export interface AssetServiceOptions {
+    assets: AssetRegistry;
+    /** 厂商 file_id 的缓存表；不注入时每次发送都真上传（缓存那一层不生效） */
+    vendorFiles?: AssetVendorRegistry;
+    paths: HostPaths;
+    /**
+     * 按实发模型取模型与端点（F-H7 的判定依据）。不给时按「既没有视觉能力信息、也没有端点能力」
+     * 处理：图片会走内联，超过内联上限的会如实报失败。
+     */
+    resolveModelContext?: AttachmentModelResolver;
+    /** 传给 SDK 转换器的依赖（测试替身上传；生产缺省走 OpenAI 兼容的 Files API） */
+    toolEnv?: ToolEnvDeps;
+    /** 时钟，缺省 `Date.now` */
+    now?: () => number;
+    /** 素材 id 生成，缺省 `crypto.randomUUID` */
+    newId?: () => string;
+    /** 降级 / 失败的事实上报口（日志或通知）；缺省忽略 */
+    onProblem?: (problem: ProblemFact, context: string) => void;
+}
+export declare class AssetService {
+    private readonly options;
+    private readonly assets;
+    private readonly vendorFiles?;
+    private readonly now;
+    private readonly newId;
+    constructor(options: AssetServiceOptions);
+    /**
+     * 把收完的临时文件变成正式素材（`UploadReceiver` 的落定回调）。
+     *
+     * 顺序是「先改名、再登记行、失败就把文件删回去」：库里出现一行指向不存在的文件，
+     * 比文件多留一份更难收拾（取用时会变成「有引用但读不到」）。
+     *
+     * 登记走 upsert，键是 `sha256`（全库唯一）：库里已经有同一份字节时（另一段对话传过、或
+     * 两个上传撞在一起），唯一约束会挡住插入，这时把刚写出去的文件删掉、回库里既有那一行 ——
+     * 全局去重的目的（整台机器只占一份磁盘）因此对两条路都成立。
+     *
+     * 「这段素材归哪段对话」不在这张表上：归属在消息落库那一刻写进 `conversation_assets`
+     * （{@link AssetService.linkMessageAssets}），所以这个入参里的 `conversationId` 不参与登记。
+     *
+     * 文件落到正式位置之后读一次文件头，把像素尺寸一并登记（{@link readImageSizeFromFile}）：
+     * 客户端拿 `width` / `height` 先排占位框，图显示出来时界面不会跳。量不到就是 `null`。
+     */
+    finalizeUpload(request: UploadFinalizeRequest): Promise<AssetRef>;
+    /**
+     * 「库里已经有这张图了」时回既有那一行（`UploadReceiver.begin` 的去重判定）。
+     *
+     * 两个条件同时成立才算命中：同一个 `sha256`、同一个字节数。第二个条件看着多余
+     * （摘要相同就是同一份内容），但它是「客户端报的总长与宿主那一行对得上」的交叉校验：对不上
+     * 就当作没命中，让客户端老老实实传一遍。
+     *
+     * 去重是**全局**的：另一段对话传过的同一张图也算命中，命中之后两个对话各自在
+     * `conversation_assets` 里留一行引用，磁盘上仍然只有一份。
+     */
+    findExistingAsset(input: {
+        sha256: string;
+        bytes: number;
+    }): Promise<AssetRef | null>;
+    /**
+     * 登记素材行失败的翻译。
+     *
+     * `assets` 这一行不挂任何外键（归属在关系表上），所以这里没有「对话不存在」这类可判别失败：
+     * 盘坏了、库坏了都是 internal，原因写进 detail 并进日志。
+     */
+    private registrationError;
+    /**
+     * 消息落库那一刻：扫 `content` 里的 `__asset_id` 记关系行（同一 message + asset 只一行）。
+     *
+     * 关系行是「谁引用了它」的唯一记录，所以它跟消息行同一步写：之后撤回、删对话、删消息都由
+     * 外键级联删关系行，不需要谁去减计数。写不进去（素材 id 认不得、库出错）不让这一轮失败 ——
+     * 后果只是这份素材的引用少记一次，{@link AssetService.sweepUnreferenced} 因此会晚一步删。
+     */
+    linkMessageAssets(context: MessageAssetLinkContext): Promise<number>;
+    /** 一条素材行（取用方要按 id 查 ref 时用） */
+    get(assetId: string): Promise<AssetRecord | undefined>;
+    /**
+     * 用户输入 + 已上传的素材 → 真正发给模型的内容（`ChatRunner` 的 `prepareAttachments`）。
+     *
+     * 口径（F-H7 逐条）：
+     *   - **文本段在前**：用户打的字始终是第一段，素材段按用户摆放的顺序跟在后面；
+     *   - **按实发模型选传输方式**：能不能走 Files API 看端点声明、图片能不能进上下文看模型，
+     *     判定与转换交给 SDK 的 `fileToContentSection`（与工具链里那段代码同一份口径）；
+     *   - **失败要告警**：每张图各自的结局都记账（`deliveredAs` + `problem`），不合并成一句「成功」；
+     *   - **全失败退回纯文本**：一张都没送出去时内容就是用户原来那段文字，
+     *     既没有凭空多出来的段，也没有假装发出去的占位。
+     *
+     * 同时给出**落库用**的那一份（`storedContent`）：素材在那里是段上的 `__asset_id`。
+     * 一份内容、两种形状是故意的 —— 发给模型的带着厂商产物（`file_id` / base64），存下的带的是引用，
+     * 否则这条消息绑在「这一次发送所用的端点」上，换模型 / 换端点 / 重启之后就发了。
+     */
+    prepareAttachments(context: AttachmentPrepareContext): Promise<AttachmentPreparation>;
+    /**
+     * 历史里的 `__asset_id` → 当前模型能吃的内容段（`ChatRunner` 的 `prepareHistory`）。
+     *
+     * 每轮发送前跑一次，因为「能不能吃」跟着模型 / 端点变：换个支持 Files API 的端点就会走文件引用，
+     * 换个不支持视觉的模型就退化成一句文字提示。还原不出来的那一段换成一句文字说明而不是把
+     * 引用原样交给厂商（那会让整条请求 400）。
+     *
+     * 无论有没有素材引用，内容都按 core 的字段白名单重建一次（`formatContent`）：`__` 开头的键
+     * 是本机扩展，出网的那一份里不该有它们。没有引用时不读盘、不上传。
+     */
+    resolveHistory(context: {
+        conversationId: string;
+        modelId: string | null;
+        messages: AgentNS.Message[];
+    }): Promise<AgentNS.Message[]>;
+    /**
+     * 按 id 取回素材内容（`asset.get`）。
+     *
+     * `thumb` 目前**等同原图**：本波不引入原生图像库，两档返回同一份字节与同一个 mime；
+     * 客户端要小图时按回包里的 `width` / `height`（未知为 `null`）自己缩。
+     */
+    getAsset(input: {
+        assetId: string;
+        variant?: AssetVariant;
+    }): Promise<AssetGetResult>;
+    /**
+     * 一张素材的送达过程：读出字节来源、交给 SDK 转换、把结论译成 wire 上的「怎么走的」。
+     *
+     * 抛错不往上扔：一张图没送出去不该让整轮消息发不出去（F-H7 的「全失败退回纯文本」前提是
+     * 其余内容照发），所以这里收敛成一个 `dropped` 的结局并上报。
+     *
+     * `quiet` 是历史重放用的：重放是每一轮的内部动作，一张旧图今天没送出去不等于用户刚做错了什么，
+     * 不再往 `onProblem` 里塞一条（发送链上的告警留给“用户这一轮挂的图”）。
+     */
+    private deliver;
+    /**
+     * 这次交给 SDK 的端点。
+     *
+     * 这个端点上已经有这个素材的缓存行（或者哪个端点上都没有）时原样给它：前者命中复用，
+     * 后者上传一次。只有「这个端点上没有、别的端点上有」才给 `null` —— 那是换厂商 / 换端点，
+     * 不往新端点重传，SDK 于是走内联 base64。
+     */
+    private vendorEndpoint;
+    /**
+     * 交给 SDK 转换器的依赖：只把 `upload` 换成一个「先查缓存、miss 才真上传」的版本。
+     *
+     * SDK 那边不记任何 file_id，所以「同一张图不重复上传」由持有持久存储的这一层承担。
+     * 缓存行以 `(assetId, endpointId)` 为键：命中就拿那个 `vendorFileId`，miss 才发 HTTP 并写回。
+     *
+     * 每张素材各自拿一个闭包（不共享可变状态），并发发送两张不同的图不会互相写错行。
+     */
+    private conversionDeps;
+    /**
+     * 素材 → `fileToContentSection` 的来源。
+     *
+     * 扩展名能推出同一个 MIME 时给路径（SDK 自己 stat + 读，省一次我们的读盘）；
+     * 推不出来时给字节 + 显式 mime，否则 SDK 会因为「不认识的扩展名」直接拒掉一个我们明明知道类型的文件。
+     */
+    private sourceOf;
+    /**
+     * 按 id 找模型与端点。
+     *
+     * 解析失败不让整轮崩掉：拿不到能力信息就按「没有端点能力、也没有模型信息」继续 ——
+     * 后果是图片走内联、超过内联上限的那张如实报「发不出去」，而不是整条消息失败。
+     */
+    private resolveTarget;
+    /**
+     * 一批素材 id → 引用归零的那些：删行、删文件。
+     *
+     * 调用时机是「消息清理完之后」：撤回、删对话、删项目都已经交给外键把关系行级联删掉了，
+     * 这里再问一次「这张素材还剩几行引用」（`COUNT(*)`）——还剩就不动，归零才删。
+     * `assets` 那行的删除走 {@link AssetRegistry.deleteIfUnreferenced}（`RESTRICT` 是护栏：
+     * 判完之后又有人引用上时，物理删不掉）。
+     *
+     * 返回真正删掉的文件（数据根相对路径）；行在而文件已经不在时不报错（清理要能重复执行）。
+     */
+    sweepUnreferenced(assetIds: string[]): Promise<string[]>;
+    /**
+     * 只删文件。
+     *
+     * 入参是数据根下的相对路径（`assets` 行的 `path` 就是这个形状）。路径必须落在 `assets/` 里：
+     * 这是唯一会让本服务删掉库外文件的地方，越界的路径一律不碰。
+     */
+    removeFiles(relativePaths: string[]): Promise<string[]>;
+    /** 数据根相对路径 → 绝对路径（已经是绝对路径的原样返回） */
+    private resolveAssetPath;
+    /** 只认 `assets/` 目录里面的路径（含 `..` 绕出去的都不认） */
+    private isInsideAssetsDir;
+    /**
+     * 一条给人看的事实（`LocalizedText` 的血缘：码 + 文案键 + 参数 + 当前语言下的句子）。
+     *
+     * 这里的语言用默认语言：素材转换发生在 `ChatRunner` 那一轮里，那一层拿不到「这是哪条连接」。
+     * 客户端要按自己连接的语言显示时，用 `messageKey` + `params` 重新渲染即可（D8 的存码不存句子）。
+     */
+    private problem;
+    private report;
+}
+/** 素材行 → wire 上的引用（尺寸未知时为 `null`，客户端按「未知」排占位） */
+export declare function toAssetRef(row: AssetRecord): AssetRef;
+/**
+ * 素材 → 落库用的内容段。
+ *
+ * 图片是 `image_url`（`url` 留空），其余是 `file`（`filename` 记原始名字，`file_id` / `file_data`
+ * 都不出现）；两种都只带本地扩展字段 `__asset_id`。真字段留空是故意的：库里存的是「引用哪份
+ * 素材」，而不是任何一种厂商产物。发送前由 {@link AssetService.resolveHistory} 按当时的模型
+ * 换成它能吃的真段。
+ */
+export declare function assetSectionOf(row: AssetRecord): LocalMessageContentSection;
+/**
+ * 一条内容里的全部素材 id（按出现顺序、去重）。
+ *
+ * 撤回时的“回填输入框”（R62）与消息落库时的关系行都靠它复原「这条消息挂了哪几张图」：
+ * `assets` 行上不再记消息，`conversation_assets` 才是那个事实，而它的来源是 content。
+ */
+export declare function assetIdsOf(content: AgentNS.MessageContent | undefined): string[];