pi-tsgw 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -6
- package/extensions/images/README.md +65 -23
- package/extensions/images/adapter.ts +31 -48
- package/extensions/images/image-data.ts +228 -0
- package/extensions/images/parameters.ts +136 -0
- package/extensions/images/request.ts +102 -0
- package/extensions/images/response.ts +34 -47
- package/extensions/images/stream-response.ts +180 -0
- package/extensions/images/tool-files.ts +156 -0
- package/extensions/images/tool-schema.ts +73 -0
- package/extensions/images/tools.ts +98 -0
- package/extensions/models/vendors/openai.ts +2 -2
- package/index.ts +6 -1
- package/package.json +3 -3
- package/skills/tsgw-delegate-model-selection/SKILL.md +3 -2
- package/skills/tsgw-image-generation/SKILL.md +150 -0
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import type { ImagesContext } from "@earendil-works/pi-ai";
|
|
2
|
+
import { inspectImage } from "./image-data.ts";
|
|
3
|
+
import { IMAGE_PARAMETER_KEYS, MAX_IMAGE_INPUT_TOTAL_BYTES, imageReferenceInputBytes,
|
|
4
|
+
normalizeImageParameters, normalizeImageReference, plainImageObject,
|
|
5
|
+
type ImageFormat, type ImageOperation, type ImageReference, type NormalizedImageParameters } from "./parameters.ts";
|
|
6
|
+
import { ImageFailure } from "./response.ts";
|
|
7
|
+
|
|
8
|
+
export interface ImageRequest {
|
|
9
|
+
operation: ImageOperation;
|
|
10
|
+
payload: Record<string, unknown>;
|
|
11
|
+
}
|
|
12
|
+
export interface ImageResponseExpectation { count: number; format: ImageFormat; stream: boolean; operation: ImageOperation }
|
|
13
|
+
export interface SerializedImageRequest { body: string; expected: ImageResponseExpectation }
|
|
14
|
+
|
|
15
|
+
export function validPrompt(value: unknown): value is string {
|
|
16
|
+
return typeof value === "string" && value.trim().length > 0 && value.length <= 32_000;
|
|
17
|
+
}
|
|
18
|
+
function dataImage(ref: ImageReference) {
|
|
19
|
+
const match = /^data:image\/(png|jpeg|webp);base64,(.*)$/.exec(ref.image_url ?? "");
|
|
20
|
+
return match ? inspectImage(match[2], match[1] as ImageFormat) : undefined;
|
|
21
|
+
}
|
|
22
|
+
function validateOperation(parameters: NormalizedImageParameters, operation: ImageOperation): void {
|
|
23
|
+
const images = parameters.images, mask = parameters.mask;
|
|
24
|
+
if (operation === "generate") {
|
|
25
|
+
if (images || mask) throw new ImageFailure("图片生成不接受参考图或蒙版;请使用图片编辑。");
|
|
26
|
+
return;
|
|
27
|
+
}
|
|
28
|
+
if (!images?.length) throw new ImageFailure("图片编辑需要 1..16 张参考图。");
|
|
29
|
+
// 输入预算独立于输出预算;远程引用仅交上游,不在插件内下载。
|
|
30
|
+
const refs = mask ? [...images, mask] : images;
|
|
31
|
+
if (refs.reduce((sum, ref) => sum + imageReferenceInputBytes(ref), 0) > MAX_IMAGE_INPUT_TOTAL_BYTES) {
|
|
32
|
+
throw new ImageFailure("图片参考图与蒙版的总输入不得超过 100000000 字节。");
|
|
33
|
+
}
|
|
34
|
+
if (mask) {
|
|
35
|
+
const first = dataImage(images[0]), maskData = dataImage(mask);
|
|
36
|
+
if (maskData && !maskData.hasAlpha) throw new ImageFailure("图片编辑蒙版需要 alpha 通道。");
|
|
37
|
+
if (first && maskData && (first.width !== maskData.width || first.height !== maskData.height || first.mimeType !== maskData.mimeType)) {
|
|
38
|
+
throw new ImageFailure("图片编辑蒙版必须与第一张参考图尺寸和格式一致。");
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
function apiParameters(parameters: NormalizedImageParameters): Record<string, unknown> {
|
|
43
|
+
const { operation: _operation, partial_images, ...api } = parameters;
|
|
44
|
+
return parameters.stream ? { ...api, partial_images } : api;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** 只构造自己的新对象,不更改冻结的模型、context、参数或原始图片。 */
|
|
48
|
+
export function createImageRequest(context: ImagesContext, modelId: string): ImageRequest {
|
|
49
|
+
if (!plainImageObject(context) || !Array.isArray(context.input) || !context.input.length) {
|
|
50
|
+
throw new ImageFailure("图片请求需要非空输入与文本提示词。");
|
|
51
|
+
}
|
|
52
|
+
const parameters = normalizeImageParameters(Object.hasOwn(context, "tsgw") ? context.tsgw : undefined);
|
|
53
|
+
const texts: string[] = [], nativeImages: ImageReference[] = [];
|
|
54
|
+
for (const block of context.input) {
|
|
55
|
+
if (!plainImageObject(block)) throw new ImageFailure("图片请求输入块无效。");
|
|
56
|
+
if (block.type === "text" && validPrompt(block.text)) texts.push(block.text);
|
|
57
|
+
else if (block.type === "image") {
|
|
58
|
+
if (typeof block.data !== "string" || !["image/png", "image/jpeg", "image/webp"].includes(block.mimeType)) {
|
|
59
|
+
throw new ImageFailure("参考图需要有效的 PNG、JPEG 或 WebP 图片块。");
|
|
60
|
+
}
|
|
61
|
+
// 引用校验先检查输入预算,再核对声明 MIME 与容器,避免先解码无界输入。
|
|
62
|
+
nativeImages.push(normalizeImageReference({ image_url: `data:${block.mimeType};base64,${block.data}` }));
|
|
63
|
+
} else throw new ImageFailure("图片请求仅接受非空文本和有效图片块。");
|
|
64
|
+
}
|
|
65
|
+
const prompt = texts.join("\n");
|
|
66
|
+
if (!validPrompt(prompt)) throw new ImageFailure("图片提示词须非空且合并后不得超过 32000 字符。");
|
|
67
|
+
if (nativeImages.length) {
|
|
68
|
+
if (parameters.images) throw new ImageFailure("原生图片块与 tsgw.images 不得同时提供。");
|
|
69
|
+
if (nativeImages.length > 16) throw new ImageFailure("图片编辑最多接受 16 张参考图。");
|
|
70
|
+
parameters.images = nativeImages;
|
|
71
|
+
}
|
|
72
|
+
const operation = parameters.operation ?? (parameters.images ? "edit" : "generate");
|
|
73
|
+
validateOperation(parameters, operation);
|
|
74
|
+
return { operation, payload: { model: modelId, prompt, ...apiParameters(parameters) } };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** 先序列化,再验证实际发送值,避免 getter/toJSON 改写模型或端点边界。 */
|
|
78
|
+
export function serializeImageRequest(payload: unknown, modelId: string, operation: ImageOperation): SerializedImageRequest {
|
|
79
|
+
let body: string;
|
|
80
|
+
let value: unknown;
|
|
81
|
+
try {
|
|
82
|
+
const encoded = JSON.stringify(payload);
|
|
83
|
+
if (encoded === undefined) throw new Error();
|
|
84
|
+
body = encoded;
|
|
85
|
+
value = JSON.parse(body);
|
|
86
|
+
} catch { throw new ImageFailure("图片请求无法序列化为有效 JSON。"); }
|
|
87
|
+
if (!plainImageObject(value) || value.model !== modelId || !validPrompt(value.prompt)) {
|
|
88
|
+
throw new ImageFailure("图片请求必须保留当前模型及非空且不超过 32000 字符的提示词。");
|
|
89
|
+
}
|
|
90
|
+
// 未知 hook 字段原样保留;但不能借旧协议字段切换操作、返回 URL 或伪造不支持的能力。
|
|
91
|
+
for (const key of ["operation", "image", "response_format", "style", "standard", "hd", "input_fidelity"]) {
|
|
92
|
+
if (Object.hasOwn(value, key)) throw new ImageFailure("图片请求包含不支持或混淆端点的字段。");
|
|
93
|
+
}
|
|
94
|
+
if (operation === "generate" && (Object.hasOwn(value, "images") || Object.hasOwn(value, "mask"))) {
|
|
95
|
+
throw new ImageFailure("图片生成端点不接受参考图或蒙版。");
|
|
96
|
+
}
|
|
97
|
+
const selected: Record<string, unknown> = {};
|
|
98
|
+
for (const key of IMAGE_PARAMETER_KEYS) if (Object.hasOwn(value, key)) selected[key] = value[key];
|
|
99
|
+
const parameters = normalizeImageParameters(selected);
|
|
100
|
+
validateOperation(parameters, operation);
|
|
101
|
+
return { body, expected: { count: parameters.n, format: parameters.output_format, stream: parameters.stream, operation } };
|
|
102
|
+
}
|
|
@@ -1,10 +1,9 @@
|
|
|
1
|
-
import type { ImageApi, ImageModel, Usage } from "@earendil-works/pi-ai";
|
|
1
|
+
import type { ImageApi, ImageContent, ImageModel, Usage } from "@earendil-works/pi-ai";
|
|
2
|
+
import { ImageFailure, inspectImage, type ImageFormat, type InspectedImage } from "./image-data.ts";
|
|
2
3
|
|
|
4
|
+
export { ImageFailure } from "./image-data.ts";
|
|
3
5
|
export const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
|
|
4
6
|
|
|
5
|
-
// 仅此类携带插件自行构造的安全错误;原始异常和服务端消息不进入结果。
|
|
6
|
-
export class ImageFailure extends Error {}
|
|
7
|
-
|
|
8
7
|
export function record(value: unknown): value is Record<string, unknown> {
|
|
9
8
|
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
10
9
|
}
|
|
@@ -27,10 +26,11 @@ export async function abortable<T>(signal: AbortSignal, action: () => T | Promis
|
|
|
27
26
|
}
|
|
28
27
|
}
|
|
29
28
|
|
|
30
|
-
export async function readJson(response: Response, signal: AbortSignal): Promise<unknown> {
|
|
29
|
+
export async function readJson(response: Response, signal: AbortSignal, maxBytes = MAX_RESPONSE_BYTES): Promise<unknown> {
|
|
30
|
+
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new ImageFailure("图片响应预算无效。");
|
|
31
31
|
const length = response.headers.get("content-length");
|
|
32
|
-
if (length && /^\d+$/.test(length) && Number(length) >
|
|
33
|
-
throw new ImageFailure(
|
|
32
|
+
if (length && /^\d+$/.test(length) && Number(length) > maxBytes) {
|
|
33
|
+
throw new ImageFailure(`图片响应超过 ${maxBytes / 1024 / 1024} MiB 读取预算上限。`);
|
|
34
34
|
}
|
|
35
35
|
if (!response.body) throw new ImageFailure("图片响应为空。");
|
|
36
36
|
const reader = response.body.getReader();
|
|
@@ -42,7 +42,7 @@ export async function readJson(response: Response, signal: AbortSignal): Promise
|
|
|
42
42
|
const item = await abortable(signal, () => reader.read());
|
|
43
43
|
if (item.done) { complete = true; break; }
|
|
44
44
|
size += item.value.byteLength;
|
|
45
|
-
if (size >
|
|
45
|
+
if (size > maxBytes) throw new ImageFailure(`图片响应超过 ${maxBytes / 1024 / 1024} MiB 读取预算上限。`);
|
|
46
46
|
chunks.push(Buffer.from(item.value));
|
|
47
47
|
}
|
|
48
48
|
try {
|
|
@@ -57,50 +57,37 @@ export async function readJson(response: Response, signal: AbortSignal): Promise
|
|
|
57
57
|
}
|
|
58
58
|
}
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
60
|
+
function declaredMetadata(raw: Record<string, unknown>, image: InspectedImage, format: ImageFormat): void {
|
|
61
|
+
if (raw.output_format !== undefined && raw.output_format !== format) throw new ImageFailure("图片声明格式与字节不一致。");
|
|
62
|
+
if (raw.size !== undefined && raw.size !== "auto" && raw.size !== `${image.width}x${image.height}`) {
|
|
63
|
+
throw new ImageFailure("图片声明尺寸与字节不一致。");
|
|
64
|
+
}
|
|
65
|
+
if ((raw.width !== undefined && raw.width !== image.width) || (raw.height !== undefined && raw.height !== image.height) ||
|
|
66
|
+
(raw.mime_type !== undefined && raw.mime_type !== image.mimeType)) throw new ImageFailure("图片声明元数据与字节不一致。");
|
|
67
|
+
}
|
|
64
68
|
|
|
65
|
-
function
|
|
66
|
-
if (!
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return false;
|
|
70
|
-
let offset = 8;
|
|
71
|
-
let idat = false;
|
|
72
|
-
while (offset + 12 <= bytes.length) {
|
|
73
|
-
const length = bytes.readUInt32BE(offset);
|
|
74
|
-
const end = offset + 12 + length;
|
|
75
|
-
if (end > bytes.length) return false;
|
|
76
|
-
const type = bytes.toString("latin1", offset + 4, offset + 8);
|
|
77
|
-
if (!/^[A-Za-z]{4}$/.test(type)) return false;
|
|
78
|
-
let crc = 0xffffffff;
|
|
79
|
-
for (let i = offset + 4; i < end - 4; i++) crc = (crc >>> 8) ^ crcTable[(crc ^ bytes[i]) & 255];
|
|
80
|
-
if (((crc ^ 0xffffffff) >>> 0) !== bytes.readUInt32BE(end - 4)) return false;
|
|
81
|
-
if (offset === 8) {
|
|
82
|
-
if (type !== "IHDR" || length !== 13) return false;
|
|
83
|
-
const width = bytes.readUInt32BE(offset + 8), height = bytes.readUInt32BE(offset + 12);
|
|
84
|
-
const depth = bytes[offset + 16], color = bytes[offset + 17];
|
|
85
|
-
const depths: Record<number, number[]> = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
|
|
86
|
-
// 返回值也受模型最大边长/像素约束,避免小压缩包触发宿主巨量像素解码。
|
|
87
|
-
if (!width || !height || width > 3840 || height > 3840 || width * height > 8_294_400 || !depths[color]?.includes(depth) ||
|
|
88
|
-
bytes[offset + 18] !== 0 || bytes[offset + 19] !== 0 || bytes[offset + 20] > 1) return false;
|
|
89
|
-
} else if (type === "IHDR") return false;
|
|
90
|
-
if (type === "IDAT" && length > 0) idat = true;
|
|
91
|
-
if (type === "IEND") return length === 0 && idat && end === bytes.length;
|
|
92
|
-
offset = end;
|
|
69
|
+
export function parseImages(raw: unknown, count: number, format: ImageFormat): ImageContent[] {
|
|
70
|
+
if (!Number.isInteger(count) || count < 1 || count > 10 || !["png", "jpeg", "webp"].includes(format) ||
|
|
71
|
+
!record(raw) || !Array.isArray(raw.data) || raw.data.length !== count) {
|
|
72
|
+
throw new ImageFailure("图片响应数量必须与请求一致,且只包含有效的 base64 图片。");
|
|
93
73
|
}
|
|
94
|
-
return
|
|
74
|
+
return raw.data.map(item => {
|
|
75
|
+
if (!record(item)) throw new ImageFailure("图片响应缺少 base64 图片。");
|
|
76
|
+
if (typeof item.b64_json === "string" && item.b64_json.length > MAX_RESPONSE_BYTES) {
|
|
77
|
+
throw new ImageFailure("单张图片的 base64 响应超过 32 MiB 上限。");
|
|
78
|
+
}
|
|
79
|
+
const image = inspectImage(item.b64_json, format);
|
|
80
|
+
if (image.width > 3840 || image.height > 3840 || image.width * image.height > 8_294_400) {
|
|
81
|
+
throw new ImageFailure("图片单边不得超过 3840、总像素不得超过 8294400。");
|
|
82
|
+
}
|
|
83
|
+
declaredMetadata(raw, image, format); declaredMetadata(item, image, format);
|
|
84
|
+
return { type: "image", data: image.data, mimeType: image.mimeType };
|
|
85
|
+
});
|
|
95
86
|
}
|
|
96
87
|
|
|
88
|
+
// 兼容旧的单 PNG 调用方;绝不下载响应中的远程 URL。
|
|
97
89
|
export function parseImage(raw: unknown): string {
|
|
98
|
-
|
|
99
|
-
typeof raw.data[0].b64_json !== "string" || !validPng(raw.data[0].b64_json)) {
|
|
100
|
-
throw new ImageFailure("图片响应必须包含且仅包含一张有效的 base64 PNG 图片,单边不超过 3840、总像素不超过 8294400。");
|
|
101
|
-
}
|
|
102
|
-
// 只检查 PNG 容器、IHDR、各块 CRC 和 IEND,不解压或解码像素;绝不下载远程 URL。
|
|
103
|
-
return raw.data[0].b64_json;
|
|
90
|
+
return parseImages(raw, 1, "png")[0].data;
|
|
104
91
|
}
|
|
105
92
|
|
|
106
93
|
function count(value: unknown): value is number {
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import type { ImageContent } from "@earendil-works/pi-ai";
|
|
2
|
+
import type { ImageFormat, ImageOperation } from "./parameters.ts";
|
|
3
|
+
import { ImageFailure, MAX_RESPONSE_BYTES, abortable, parseImages, readJson, record } from "./response.ts";
|
|
4
|
+
|
|
5
|
+
export interface ExpectedImageResponse { count: number; format: ImageFormat; stream: boolean; operation: ImageOperation }
|
|
6
|
+
// 单事件仍是单图预算;总预算覆盖每图最多三张 partial、一张 completed 及少量控制帧。
|
|
7
|
+
export const MAX_SSE_EVENT_BYTES = MAX_RESPONSE_BYTES;
|
|
8
|
+
const CONTROL_BYTES = 64 * 1024;
|
|
9
|
+
const fail = (message: string): never => { throw new ImageFailure(message); };
|
|
10
|
+
|
|
11
|
+
export async function readImageResponse(
|
|
12
|
+
response: Response, signal: AbortSignal, expected: ExpectedImageResponse, reportUsage: (raw: unknown) => void,
|
|
13
|
+
): Promise<ImageContent[]> {
|
|
14
|
+
if (!Number.isInteger(expected.count) || expected.count < 1 || expected.count > 10 ||
|
|
15
|
+
!["png", "jpeg", "webp"].includes(expected.format) || !["generate", "edit"].includes(expected.operation) ||
|
|
16
|
+
typeof expected.stream !== "boolean") return fail("图片响应解析参数无效。");
|
|
17
|
+
if (!expected.stream) {
|
|
18
|
+
const raw = await readJson(response, signal, MAX_RESPONSE_BYTES * expected.count);
|
|
19
|
+
reportUsage(raw); // 即使坏图或数量错误,也保留上游已报告的有效 usage。
|
|
20
|
+
return parseImages(raw, expected.count, expected.format);
|
|
21
|
+
}
|
|
22
|
+
const contentType = response.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase();
|
|
23
|
+
if (contentType !== "text/event-stream") return fail("图片流式响应不是 SSE。");
|
|
24
|
+
return readSse(response, signal, expected, reportUsage);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
async function readSse(
|
|
28
|
+
response: Response, signal: AbortSignal, expected: ExpectedImageResponse, reportUsage: (raw: unknown) => void,
|
|
29
|
+
): Promise<ImageContent[]> {
|
|
30
|
+
const budget = MAX_SSE_EVENT_BYTES * 4 * expected.count + CONTROL_BYTES;
|
|
31
|
+
const length = response.headers.get("content-length");
|
|
32
|
+
if (length && /^\d+$/.test(length) && Number(length) > budget) return fail("图片流式响应超过读取预算上限。");
|
|
33
|
+
if (!response.body) return fail("图片响应为空。");
|
|
34
|
+
const reader = response.body.getReader(), decoder = new TextDecoder("utf-8", { fatal: true });
|
|
35
|
+
const finals: ImageContent[] = [], usageReports: unknown[] = [];
|
|
36
|
+
const completedIndices = new Set<number>();
|
|
37
|
+
const prefix = expected.operation === "edit" ? "image_edit" : "image_generation";
|
|
38
|
+
let usageSeen = false, partials = 0, terminated = false;
|
|
39
|
+
let totalBytes = 0, eventBytes = 0, frames = 0, complete = false;
|
|
40
|
+
let line = "", event = "", data: string[] = [], skipLf = false, touched = false;
|
|
41
|
+
let previousCrEventBytes: number | undefined;
|
|
42
|
+
|
|
43
|
+
function usage(raw: Record<string, unknown>): void {
|
|
44
|
+
if (raw.usage === undefined) return;
|
|
45
|
+
if (expected.count > 1) {
|
|
46
|
+
// 保留原始报告而非猜测逐图/累计归属;交调用方标记未汇总,不合成 usage。
|
|
47
|
+
if (usageReports.length === 10) return;
|
|
48
|
+
usageReports.push(raw.usage);
|
|
49
|
+
reportUsage({ usage_reports: [...usageReports] });
|
|
50
|
+
} else if (!usageSeen) {
|
|
51
|
+
usageSeen = true; reportUsage(raw);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
function dispatch(): void {
|
|
55
|
+
if (++frames > 1024 + 4 * expected.count) return fail("图片流式响应事件过多。");
|
|
56
|
+
if (!data.length) {
|
|
57
|
+
if (event === "error") return fail("图片流式请求返回错误事件。");
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
if (terminated) return fail("图片流式响应在结束标记之后仍有数据。");
|
|
61
|
+
const payload = data.join("\n");
|
|
62
|
+
if (payload === "[DONE]") {
|
|
63
|
+
if (finals.length !== expected.count) return fail("图片流式响应未完成全部图片。");
|
|
64
|
+
terminated = true; return;
|
|
65
|
+
}
|
|
66
|
+
let raw: unknown;
|
|
67
|
+
try { raw = JSON.parse(payload); } catch { return fail("图片 SSE 事件不是有效 JSON。"); }
|
|
68
|
+
if (!record(raw)) return fail("图片 SSE 事件结构无效。");
|
|
69
|
+
if (event === "error" || raw.type === "error" || raw.error !== undefined) {
|
|
70
|
+
usage(raw); return fail("图片流式请求返回错误事件。");
|
|
71
|
+
}
|
|
72
|
+
if (event && raw.type !== undefined && raw.type !== event) return fail("图片 SSE 事件类型不一致。");
|
|
73
|
+
const type = event || raw.type;
|
|
74
|
+
if (type !== `${prefix}.partial_image` && type !== `${prefix}.completed`) return fail("图片 SSE 事件类型不受支持。");
|
|
75
|
+
const final = type === `${prefix}.completed`;
|
|
76
|
+
if (final) {
|
|
77
|
+
// 单图的第二个完成事件不能覆盖首次报告;多图保留超额事件的 usage(最多十项)。
|
|
78
|
+
if (expected.count === 1 && finals.length) return fail("图片 SSE 超额完成。");
|
|
79
|
+
usage(raw); // 在坏图、显式序号及数量检查前保留上游报告。
|
|
80
|
+
}
|
|
81
|
+
const index = raw.image_index;
|
|
82
|
+
if (index !== undefined && (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= expected.count)) {
|
|
83
|
+
return fail("图片 SSE 序号无效。");
|
|
84
|
+
}
|
|
85
|
+
if (!final) {
|
|
86
|
+
if (++partials > 3 * expected.count || !Number.isInteger(raw.partial_image_index) ||
|
|
87
|
+
(raw.partial_image_index as number) < 0 || (raw.partial_image_index as number) > 2 ||
|
|
88
|
+
finals.length === expected.count || (index !== undefined && completedIndices.has(index as number))) {
|
|
89
|
+
return fail("图片 SSE 中间图事件超额或顺序无效。");
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
const image = parseImages({ ...raw, data: [{ b64_json: raw.b64_json }] }, 1, expected.format)[0];
|
|
93
|
+
if (!final) return; // 只验证并丢弃 partial;Promise 不代表实时 UI 或逐帧交付。
|
|
94
|
+
// image_index 仅是可选的上游扩展;不要求每张都有,不据此重排,也不按相同字节去重。
|
|
95
|
+
if (finals.length >= expected.count || (index !== undefined && completedIndices.has(index as number))) {
|
|
96
|
+
return fail("图片 SSE 显式序号重复或超额完成。");
|
|
97
|
+
}
|
|
98
|
+
if (typeof index === "number") completedIndices.add(index);
|
|
99
|
+
finals.push(image);
|
|
100
|
+
}
|
|
101
|
+
function acceptLine(): void {
|
|
102
|
+
if (!line) {
|
|
103
|
+
dispatch(); event = ""; data = []; eventBytes = 0; touched = false;
|
|
104
|
+
} else {
|
|
105
|
+
const colon = line.indexOf(":"), field = colon < 0 ? line : line.slice(0, colon);
|
|
106
|
+
let value = colon < 0 ? "" : line.slice(colon + 1);
|
|
107
|
+
if (value.startsWith(" ")) value = value.slice(1);
|
|
108
|
+
if (field === "event") event = value;
|
|
109
|
+
if (field === "data") data.push(value);
|
|
110
|
+
line = "";
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
function eventBudget(bytes: number): void {
|
|
114
|
+
eventBytes += bytes;
|
|
115
|
+
if (eventBytes > MAX_SSE_EVENT_BYTES) return fail("图片 SSE 单事件超过 32 MiB 上限。");
|
|
116
|
+
}
|
|
117
|
+
function text(value: string): void {
|
|
118
|
+
let start = 0;
|
|
119
|
+
// CR 立即交付整行(迟到错误前仍保留 usage);跨块 LF 计入原事件而非新事件。
|
|
120
|
+
if (skipLf && value.length) {
|
|
121
|
+
skipLf = false;
|
|
122
|
+
if (value[0] === "\n") {
|
|
123
|
+
if (previousCrEventBytes === undefined) eventBudget(1);
|
|
124
|
+
else if (previousCrEventBytes + 1 > MAX_SSE_EVENT_BYTES) return fail("图片 SSE 单事件超过 32 MiB 上限。");
|
|
125
|
+
start = 1;
|
|
126
|
+
}
|
|
127
|
+
previousCrEventBytes = undefined;
|
|
128
|
+
}
|
|
129
|
+
while (start < value.length) {
|
|
130
|
+
const cr = value.indexOf("\r", start), lf = value.indexOf("\n", start);
|
|
131
|
+
const end = cr < 0 ? lf : lf < 0 ? cr : Math.min(cr, lf);
|
|
132
|
+
const part = value.slice(start, end < 0 ? value.length : end);
|
|
133
|
+
eventBudget(Buffer.byteLength(part, "utf8") + (end < 0 ? 0 : 1));
|
|
134
|
+
touched = true; line += part;
|
|
135
|
+
if (end < 0) return;
|
|
136
|
+
start = end + 1;
|
|
137
|
+
if (value[end] === "\r") {
|
|
138
|
+
if (start === value.length) {
|
|
139
|
+
previousCrEventBytes = line ? undefined : eventBytes;
|
|
140
|
+
acceptLine(); skipLf = true; return;
|
|
141
|
+
}
|
|
142
|
+
if (value[start] === "\n") { eventBudget(1); start++; }
|
|
143
|
+
}
|
|
144
|
+
acceptLine();
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
function decodeLines(bytes: Uint8Array): void {
|
|
148
|
+
// 逐行交给严格 UTF-8 解码器:同一网络 chunk 的后续坏字节不能抹掉先前完成事件的 usage。
|
|
149
|
+
let start = 0, cr = bytes.indexOf(13), lf = bytes.indexOf(10);
|
|
150
|
+
while (start < bytes.length) {
|
|
151
|
+
const end = cr < 0 ? lf : lf < 0 ? cr : Math.min(cr, lf);
|
|
152
|
+
const next = end < 0 ? bytes.length : end + 1;
|
|
153
|
+
text(decoder.decode(bytes.subarray(start, next), { stream: true })); start = next;
|
|
154
|
+
// 两种分隔符的游标各自只前进,避免仅 LF 的多行事件反复扫描剩余整块。
|
|
155
|
+
if (end >= 0 && end === cr) cr = bytes.indexOf(13, next);
|
|
156
|
+
if (end >= 0 && end === lf) lf = bytes.indexOf(10, next);
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
try {
|
|
160
|
+
while (true) {
|
|
161
|
+
const item = await abortable(signal, () => reader.read());
|
|
162
|
+
if (item.done) { complete = true; break; }
|
|
163
|
+
const available = budget - totalBytes;
|
|
164
|
+
decodeLines(item.value.subarray(0, available));
|
|
165
|
+
totalBytes += item.value.byteLength;
|
|
166
|
+
if (totalBytes > budget) return fail("图片流式响应超过读取预算上限。");
|
|
167
|
+
}
|
|
168
|
+
text(decoder.decode());
|
|
169
|
+
if (touched || line || data.length || event) return fail("图片 SSE 事件意外截断。");
|
|
170
|
+
if (finals.length !== expected.count) return fail("图片流式响应未完成全部图片。");
|
|
171
|
+
return finals;
|
|
172
|
+
} catch (error) {
|
|
173
|
+
if (signal.aborted) throw signal.reason;
|
|
174
|
+
if (error instanceof ImageFailure) throw error;
|
|
175
|
+
throw new ImageFailure("图片流式响应读取失败或 UTF-8 无效。");
|
|
176
|
+
} finally {
|
|
177
|
+
if (!complete) void reader.cancel().catch(() => {});
|
|
178
|
+
reader.releaseLock();
|
|
179
|
+
}
|
|
180
|
+
}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import { constants } from "node:fs";
|
|
2
|
+
import { mkdtemp, open, realpath, rm, stat, unlink, type FileHandle } from "node:fs/promises";
|
|
3
|
+
import { join, resolve } from "node:path";
|
|
4
|
+
import { tmpdir } from "node:os";
|
|
5
|
+
import type { ImageContent } from "@earendil-works/pi-ai";
|
|
6
|
+
import { inspectImage } from "./image-data.ts";
|
|
7
|
+
import { MAX_IMAGE_INPUT_BYTES, MAX_IMAGE_INPUT_TOTAL_BYTES, type ImageFormat, type ImageReference } from "./parameters.ts";
|
|
8
|
+
import { plainObject } from "./tool-schema.ts";
|
|
9
|
+
|
|
10
|
+
// 与适配器共用十进制字节预算;保留工具测试的导出入口。
|
|
11
|
+
export const MAX_INPUT_FILE_BYTES = MAX_IMAGE_INPUT_BYTES;
|
|
12
|
+
export const MAX_INPUT_TOTAL_BYTES = MAX_IMAGE_INPUT_TOTAL_BYTES;
|
|
13
|
+
const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
|
|
14
|
+
export interface ImageFileResult { path: string; mimeType: string; width: number; height: number }
|
|
15
|
+
export class ImageToolFileError extends Error {
|
|
16
|
+
constructor(readonly code: string, message: string, readonly files: ImageFileResult[] = []) { super(message); }
|
|
17
|
+
}
|
|
18
|
+
type Inspected = ReturnType<typeof inspectImage>;
|
|
19
|
+
interface LoadedSource { reference: ImageReference; inspected?: Inspected }
|
|
20
|
+
interface Budget { used: number }
|
|
21
|
+
const fail = (code: string, message: string): never => { throw new ImageToolFileError(code, message); };
|
|
22
|
+
function charge(size: number, budget: Budget): void {
|
|
23
|
+
if (size <= 0 || size >= MAX_INPUT_FILE_BYTES || budget.used + size > MAX_INPUT_TOTAL_BYTES)
|
|
24
|
+
fail("input-too-large", "每个本地或内联图片必须小于50 MB,全部参考图与蒙版合计不超过100 MB。");
|
|
25
|
+
budget.used += size;
|
|
26
|
+
}
|
|
27
|
+
function inspect(data: string): Inspected {
|
|
28
|
+
try { return inspectImage(data); }
|
|
29
|
+
catch { return fail("invalid-image", "本地或内联图片不是有效的 PNG、JPEG 或 WebP 容器;未转码或修复图片。"); }
|
|
30
|
+
}
|
|
31
|
+
const fileStat = (handle: FileHandle) => handle.stat({ bigint: true });
|
|
32
|
+
type FileStat = Awaited<ReturnType<typeof fileStat>>;
|
|
33
|
+
const identity = (value: FileStat): string => [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs].join(":");
|
|
34
|
+
|
|
35
|
+
/** 本工具的读取权限等同 Pi 进程的 OS 权限;不依赖内置 read,也不声称沙箱。 */
|
|
36
|
+
async function localImage(path: string, cwd: string, signal: AbortSignal, budget: Budget): Promise<LoadedSource> {
|
|
37
|
+
let handle: FileHandle | undefined;
|
|
38
|
+
try {
|
|
39
|
+
signal.throwIfAborted();
|
|
40
|
+
if (!path || path.includes("\0")) fail("invalid-path", "必须提供有效的本地文件路径。");
|
|
41
|
+
const full = await realpath(resolve(cwd, path));
|
|
42
|
+
const before = await stat(full, { bigint: true });
|
|
43
|
+
if (!before.isFile()) fail("not-file", "图片输入只支持普通文件,不能读取目录、FIFO 或设备。");
|
|
44
|
+
// 防止检查后被替换成 FIFO/符号链接;open 后再检查实际文件身份。
|
|
45
|
+
handle = await open(full, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
|
|
46
|
+
const initial = await fileStat(handle);
|
|
47
|
+
if (!initial.isFile() || identity(initial) !== identity(before)) fail("file-changed", "图片源文件在读取期间发生变化。");
|
|
48
|
+
const size = Number(initial.size);
|
|
49
|
+
charge(size, budget);
|
|
50
|
+
const bytes = Buffer.allocUnsafe(size);
|
|
51
|
+
let offset = 0;
|
|
52
|
+
while (offset < size) {
|
|
53
|
+
signal.throwIfAborted();
|
|
54
|
+
const result = await handle.read(bytes, offset, Math.min(1024 * 1024, size - offset), offset);
|
|
55
|
+
if (!result.bytesRead) fail("file-changed", "图片源文件在读取期间被截断。");
|
|
56
|
+
offset += result.bytesRead;
|
|
57
|
+
}
|
|
58
|
+
signal.throwIfAborted();
|
|
59
|
+
if (identity(await fileStat(handle)) !== identity(initial) || identity(await stat(full, { bigint: true })) !== identity(initial))
|
|
60
|
+
fail("file-changed", "图片源文件在读取期间发生变化。");
|
|
61
|
+
const inspected = inspect(bytes.toString("base64"));
|
|
62
|
+
return { reference: { image_url: `data:${inspected.mimeType};base64,${inspected.data}` }, inspected };
|
|
63
|
+
} catch (error) {
|
|
64
|
+
if (error instanceof ImageToolFileError) throw error;
|
|
65
|
+
if (signal.aborted) return fail("aborted", "读取图片输入已取消。");
|
|
66
|
+
return fail("file-unavailable", "无法稳定读取 Pi 主机上的图片文件;请检查路径与操作系统权限。");
|
|
67
|
+
} finally { await handle?.close().catch(() => {}); }
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
async function loadSource(value: unknown, cwd: string, signal: AbortSignal, budget: Budget): Promise<LoadedSource> {
|
|
71
|
+
signal.throwIfAborted();
|
|
72
|
+
if (!plainObject(value)) return fail("invalid-source", "图片来源必须是仅含 path、image_url 或 file_id 之一的对象。");
|
|
73
|
+
const keys = Reflect.ownKeys(value);
|
|
74
|
+
if (keys.length !== 1 || typeof keys[0] !== "string" || !["path", "image_url", "file_id"].includes(keys[0]))
|
|
75
|
+
return fail("invalid-source", "每个图片来源必须且只能指定 path、image_url 或 file_id 一个字段。");
|
|
76
|
+
const key = keys[0], source = value[key];
|
|
77
|
+
if (typeof source !== "string" || !source.trim()) return fail("invalid-source", "图片来源不能是空值。");
|
|
78
|
+
if (key === "path") return localImage(source, cwd, signal, budget);
|
|
79
|
+
if (key === "file_id") {
|
|
80
|
+
if (source.length > 8192) return fail("invalid-source", "图片文件 ID 过长。");
|
|
81
|
+
return { reference: { file_id: source } };
|
|
82
|
+
}
|
|
83
|
+
if (source.startsWith("data:")) {
|
|
84
|
+
// 先限制字符串大小,再让 inspectImage 验证 canonical base64 和真实容器。
|
|
85
|
+
if (source.length > Math.ceil(MAX_INPUT_FILE_BYTES / 3) * 4 + 64) return fail("input-too-large", "内联图片超过输入字节预算。");
|
|
86
|
+
const match = /^data:(image\/(?:png|jpeg|webp));base64,([A-Za-z0-9+/]*={0,2})$/.exec(source);
|
|
87
|
+
if (!match) return fail("invalid-source", "内联图片必须是 PNG/JPEG/WebP 的 base64 data URI。");
|
|
88
|
+
charge(Math.floor(match[2].length * 3 / 4) - (match[2].endsWith("==") ? 2 : match[2].endsWith("=") ? 1 : 0), budget);
|
|
89
|
+
const inspected = inspect(match[2]);
|
|
90
|
+
if (inspected.mimeType !== match[1]) return fail("invalid-image", "内联图片声明的 MIME 与原始字节格式不一致。");
|
|
91
|
+
return { reference: { image_url: source }, inspected };
|
|
92
|
+
}
|
|
93
|
+
try {
|
|
94
|
+
const url = new URL(source);
|
|
95
|
+
if (source.length > 8192 || /[\u0000-\u0020\u007f]/.test(source) || !/^https?:\/\//i.test(source) || /^https?:\/\/[^/?#]*@/i.test(source) ||
|
|
96
|
+
!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password)
|
|
97
|
+
throw new Error();
|
|
98
|
+
} catch { return fail("invalid-source", "图片 URL 必须是无用户名密码的有效 HTTP(S) URL;本工具不会下载校验远程引用。"); }
|
|
99
|
+
return { reference: { image_url: source } };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export async function resolveImageSources(images: unknown, mask: unknown, cwd: string, signal: AbortSignal): Promise<{ images: ImageReference[]; mask?: ImageReference }> {
|
|
103
|
+
if (!Array.isArray(images) || images.length < 1 || images.length > 16) return fail("invalid-images", "编辑必须提供1..16张参考图片,蒙版不计入此张数。");
|
|
104
|
+
const budget = { used: 0 };
|
|
105
|
+
const loaded: LoadedSource[] = [];
|
|
106
|
+
for (const source of images) loaded.push(await loadSource(source, cwd, signal, budget));
|
|
107
|
+
const loadedMask = mask === undefined || mask === null ? undefined : await loadSource(mask, cwd, signal, budget);
|
|
108
|
+
if (loadedMask?.inspected) {
|
|
109
|
+
if (!loadedMask.inspected.hasAlpha) return fail("invalid-mask", "可本地校验的蒙版必须具有透明通道。");
|
|
110
|
+
const first = loaded[0].inspected;
|
|
111
|
+
if (first && (first.width !== loadedMask.inspected.width || first.height !== loadedMask.inspected.height || first.mimeType !== loadedMask.inspected.mimeType))
|
|
112
|
+
return fail("invalid-mask", "蒙版的尺寸与图片格式必须和第一张参考图一致。");
|
|
113
|
+
}
|
|
114
|
+
return { images: loaded.map(item => item.reference), ...(loadedMask ? { mask: loadedMask.reference } : {}) };
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** 再检查宿主返回的数量/格式/容器,防止绕过适配器的错误实现被当作成功。 */
|
|
118
|
+
export function validateImageOutput(output: unknown, count: number, format: ImageFormat): ImageContent[] {
|
|
119
|
+
if (!Array.isArray(output) || output.length !== count) return fail("invalid-output", "上游成功响应的最终图片数量不符合请求;不要自动重新生成。");
|
|
120
|
+
return output.map(block => {
|
|
121
|
+
if (!plainObject(block) || block.type !== "image" || typeof block.data !== "string" || block.data.length > Math.ceil(MAX_OUTPUT_BYTES / 3) * 4)
|
|
122
|
+
return fail("invalid-output", "上游成功响应包含无效或过大的图片块;不要自动重新生成。");
|
|
123
|
+
let inspected: Inspected;
|
|
124
|
+
try { inspected = inspectImage(block.data, format); }
|
|
125
|
+
catch { return fail("invalid-output", "上游成功响应的图片容器或格式不符合请求;不要自动重新生成。"); }
|
|
126
|
+
if (inspected.mimeType !== block.mimeType || inspected.width > 3840 || inspected.height > 3840 || inspected.width * inspected.height > 8_294_400)
|
|
127
|
+
return fail("invalid-output", "上游成功响应的图片 MIME 或尺寸不符合要求;不要自动重新生成。");
|
|
128
|
+
return { type: "image", data: inspected.data, mimeType: inspected.mimeType };
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** 唯一临时目录 + 排他创建;只保存原始字节,绝不覆盖用户路径。 */
|
|
133
|
+
export async function saveImageOutput(images: ImageContent[]): Promise<ImageFileResult[]> {
|
|
134
|
+
const files: ImageFileResult[] = [];
|
|
135
|
+
let directory: string | undefined;
|
|
136
|
+
try {
|
|
137
|
+
directory = await mkdtemp(join(tmpdir(), "tsgw-images-"));
|
|
138
|
+
for (const [index, block] of images.entries()) {
|
|
139
|
+
const inspected = inspectImage(block.data);
|
|
140
|
+
const extension = ({ "image/png": "png", "image/jpeg": "jpeg", "image/webp": "webp" } as const)[inspected.mimeType];
|
|
141
|
+
const path = join(directory, `${index + 1}.${extension}`);
|
|
142
|
+
const file = await open(path, "wx", 0o600);
|
|
143
|
+
try { await file.writeFile(Buffer.from(inspected.data, "base64")); await file.close(); }
|
|
144
|
+
catch (error) {
|
|
145
|
+
await file.close().catch(() => {});
|
|
146
|
+
await unlink(path).catch(() => {});
|
|
147
|
+
throw error;
|
|
148
|
+
}
|
|
149
|
+
files.push({ path, mimeType: inspected.mimeType, width: inspected.width, height: inspected.height });
|
|
150
|
+
}
|
|
151
|
+
return files;
|
|
152
|
+
} catch {
|
|
153
|
+
if (directory && !files.length) await rm(directory, { recursive: true, force: true }).catch(() => {});
|
|
154
|
+
throw new ImageToolFileError("save-failed", "上游已返回图片,但本地临时文件保存失败;不要重新生成。已保存的文件列于 files。", files);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { Type } from "typebox";
|
|
2
|
+
import { normalizeImageParameters, type ImageOperation } from "./parameters.ts";
|
|
3
|
+
|
|
4
|
+
export const DEFAULT_IMAGE_MODEL = "gpt-image-2.5-sunburst";
|
|
5
|
+
export const DEFAULT_IMAGE_TIMEOUT_MS = 600_000;
|
|
6
|
+
export const MAX_IMAGE_TIMEOUT_MS = 2_147_483_647;
|
|
7
|
+
const IMAGE_MODELS = ["gpt-image-2.5-sunburst", "gpt-image-2.5-flare"] as const;
|
|
8
|
+
const optional = <T extends import("typebox").TSchema>(schema: T) => Type.Optional(Type.Union([schema, Type.Null()]));
|
|
9
|
+
|
|
10
|
+
export const imageSourceSchema = Type.Union([
|
|
11
|
+
Type.Object({ path: Type.String({ minLength: 1, description: "Pi 主机本地普通文件;相对路径以会话 cwd 为基准。直接读取原始字节并外传,不经过内置 read 的审批或缩放。" }) }, { additionalProperties: false }),
|
|
12
|
+
Type.Object({ image_url: Type.String({ minLength: 1, description: "无用户名密码的 HTTP(S) URL,或 PNG/JPEG/WebP 的 base64 data URI。本工具不下载远程 URL。" }) }, { additionalProperties: false }),
|
|
13
|
+
Type.Object({ file_id: Type.String({ minLength: 1, description: "上游已有图片的文件 ID。" }) }, { additionalProperties: false }),
|
|
14
|
+
], { description: "恰好一个来源:path、image_url 或 file_id;不可混用。" });
|
|
15
|
+
|
|
16
|
+
const common = {
|
|
17
|
+
prompt: Type.String({ minLength: 1, maxLength: 32_000, description: "图片生成或编辑要求,最多32000字符。" }),
|
|
18
|
+
model: Type.Optional(Type.Enum(IMAGE_MODELS, { description: "默认 gpt-image-2.5-sunburst,适合成稿;AI 草稿任务可选 gpt-image-2.5-flare,常配 quality=low。" })),
|
|
19
|
+
quality: optional(Type.Enum(["auto", "low", "medium", "high", "xhigh", "max"], { description: "质量,默认 auto;选择 Flare 不会自动改为 low。" })),
|
|
20
|
+
size: optional(Type.String({ description: "默认 auto;也可宽x高,均为16倍数、边≤3840、宽高比≤3、像素655360..8294400。" })),
|
|
21
|
+
background: optional(Type.Enum(["auto", "opaque", "transparent"], { description: "背景,默认 auto。透明背景需 PNG/WebP。" })),
|
|
22
|
+
output_format: optional(Type.Enum(["png", "jpeg", "webp"], { description: "输出格式,默认 png;原始字节不转码。" })),
|
|
23
|
+
output_compression: optional(Type.Integer({ minimum: 0, maximum: 100, description: "仅用于 JPEG/WebP 的压缩质量;省略采用上游默认100。" })),
|
|
24
|
+
n: optional(Type.Integer({ minimum: 1, maximum: 10, description: "返回图片数量;默认1,最多10。" })),
|
|
25
|
+
moderation: optional(Type.Enum(["auto", "low"], { description: "审核强度,默认 auto。" })),
|
|
26
|
+
stream: optional(Type.Boolean({ description: "默认 false;支持解析流式响应,不承诺界面渐进预览。" })),
|
|
27
|
+
partial_images: optional(Type.Integer({ minimum: 0, maximum: 3, description: "仅 stream=true 时使用;默认0。最终仅返回完成图。" })),
|
|
28
|
+
safety_identifier: optional(Type.String({ maxLength: 128, description: "可选安全标识,最长128字符。" })),
|
|
29
|
+
user: optional(Type.String({ description: "已废弃的上游 user 参数,仅为兼容保留。" })),
|
|
30
|
+
timeout_ms: Type.Optional(Type.Number({ minimum: 0, maximum: MAX_IMAGE_TIMEOUT_MS, description: "调用超时毫秒数;默认600000,可显式缩短或延长,最多2147483647。取消不保证上游停止处理或计费。" })),
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
export const generateImageSchema = Type.Object(common, { additionalProperties: false });
|
|
34
|
+
export const editImageSchema = Type.Object({ ...common,
|
|
35
|
+
images: Type.Array(imageSourceSchema, { minItems: 1, maxItems: 16, description: "1..16张参考图。每个本地/内联图片小于50 MB,合计最多100 MB;mask另算张数,但计入字节预算。" }),
|
|
36
|
+
mask: optional(imageSourceSchema),
|
|
37
|
+
}, { additionalProperties: false });
|
|
38
|
+
|
|
39
|
+
export const imageToolResultSchema = Type.Object({
|
|
40
|
+
operation: Type.Enum(["generate", "edit"]), model: Type.String(),
|
|
41
|
+
phase: Type.Enum(["validate", "input", "request", "output", "save", "complete"]),
|
|
42
|
+
requestStatus: Type.Enum(["not-started", "unknown", "failed", "succeeded"]),
|
|
43
|
+
files: Type.Array(Type.Object({ path: Type.String(), mimeType: Type.String(), width: Type.Integer(), height: Type.Integer() })),
|
|
44
|
+
usage_note: Type.Optional(Type.String()),
|
|
45
|
+
usage_reports: Type.Optional(Type.Array(Type.Object({ input: Type.Number(), output: Type.Number(),
|
|
46
|
+
cacheRead: Type.Number(), cacheWrite: Type.Number(), totalTokens: Type.Number() }))),
|
|
47
|
+
error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String() })),
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
const API_KEYS = ["quality", "size", "background", "output_format", "output_compression", "n", "moderation",
|
|
51
|
+
"stream", "partial_images", "safety_identifier", "user"];
|
|
52
|
+
|
|
53
|
+
/** 运行时再验证白名单;程序化调用也不能静默丢弃未知参数。 */
|
|
54
|
+
export function prepareImageToolParameters(operation: ImageOperation, value: unknown) {
|
|
55
|
+
if (!plainObject(value)) throw new Error("invalid-parameters");
|
|
56
|
+
const allowed = new Set(["prompt", "model", "timeout_ms", ...API_KEYS, ...(operation === "edit" ? ["images", "mask"] : [])]);
|
|
57
|
+
if (Reflect.ownKeys(value).some(key => typeof key !== "string" || !allowed.has(key))) throw new Error("unknown-parameters");
|
|
58
|
+
if (typeof value.prompt !== "string" || !value.prompt.trim() || value.prompt.length > 32_000) throw new Error("invalid-prompt");
|
|
59
|
+
const model = value.model === undefined ? DEFAULT_IMAGE_MODEL : value.model;
|
|
60
|
+
if (typeof model !== "string" || !IMAGE_MODELS.includes(model as typeof IMAGE_MODELS[number])) throw new Error("invalid-model");
|
|
61
|
+
const timeoutMs = value.timeout_ms === undefined ? DEFAULT_IMAGE_TIMEOUT_MS : value.timeout_ms;
|
|
62
|
+
if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_IMAGE_TIMEOUT_MS)
|
|
63
|
+
throw new Error("invalid-timeout");
|
|
64
|
+
const parameters: Record<string, unknown> = {};
|
|
65
|
+
for (const key of API_KEYS) if (Object.hasOwn(value, key)) parameters[key] = value[key];
|
|
66
|
+
return { prompt: value.prompt, model, timeoutMs, parameters: normalizeImageParameters(parameters),
|
|
67
|
+
images: value.images, mask: value.mask };
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function plainObject(value: unknown): value is Record<string, unknown> {
|
|
71
|
+
return value !== null && typeof value === "object" && !Array.isArray(value) &&
|
|
72
|
+
(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
|
|
73
|
+
}
|