pi-tsgw 0.2.0 → 0.4.0
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 +28 -3
- package/extensions/images/README.md +81 -0
- package/extensions/images/adapter.ts +119 -0
- package/extensions/images/image-data.ts +228 -0
- package/extensions/images/models.ts +16 -0
- package/extensions/images/parameters.ts +136 -0
- package/extensions/images/request.ts +102 -0
- package/extensions/images/response.ts +128 -0
- 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/catalog.ts +3 -3
- package/extensions/models/vendors/openai.ts +19 -0
- package/extensions/provider/index.ts +22 -8
- 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 +76 -0
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { AssistantImages, ImageContent } from "@earendil-works/pi-ai";
|
|
2
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
3
|
+
import { normalizeImageParameters, type ImageOperation, type TsgwImagesContext, type TsgwImagesResult, type ImageUsageReport } from "./parameters.ts";
|
|
4
|
+
import { DEFAULT_IMAGE_MODEL, editImageSchema, generateImageSchema, imageToolResultSchema, prepareImageToolParameters } from "./tool-schema.ts";
|
|
5
|
+
import { ImageToolFileError, resolveImageSources, saveImageOutput, validateImageOutput, type ImageFileResult } from "./tool-files.ts";
|
|
6
|
+
|
|
7
|
+
export interface ImageToolDetails {
|
|
8
|
+
operation: ImageOperation;
|
|
9
|
+
model: string;
|
|
10
|
+
phase: "validate" | "input" | "request" | "output" | "save" | "complete";
|
|
11
|
+
/** unknown 包含 adapter error/aborted:只确认调用未成功,不能确认上游未处理/计费。 */
|
|
12
|
+
requestStatus: "not-started" | "unknown" | "failed" | "succeeded";
|
|
13
|
+
files: ImageFileResult[];
|
|
14
|
+
usage_note?: string;
|
|
15
|
+
usage_reports?: ImageUsageReport[];
|
|
16
|
+
error?: { code: string; message: string };
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** direct 工具复用宿主目录/过滤、认证与图片适配器;不解析凭据、不自行发 HTTP。 */
|
|
20
|
+
export function registerImageTools(pi: ExtensionAPI): void {
|
|
21
|
+
for (const operation of ["generate", "edit"] as const) {
|
|
22
|
+
pi.registerTool({
|
|
23
|
+
name: operation === "generate" ? "tsgw_generate_image" : "tsgw_edit_image",
|
|
24
|
+
label: operation === "generate" ? "TSGW 生成图片" : "TSGW 编辑图片",
|
|
25
|
+
description: (operation === "generate" ? "根据 prompt 生成图片,只需填写 prompt。" : "根据 prompt 和 images 编辑图片,可选 mask;蒙版对应第一张参考图。") +
|
|
26
|
+
"默认 Sunburst 用于成稿;AI 草稿任务可选 Flare(通常配 quality=low),不必为普通任务指定型号。" +
|
|
27
|
+
"默认 quality/size/background/moderation=auto、output_format=png、n=1、stream=false、partial_images=0、超时600000毫秒。" +
|
|
28
|
+
(operation === "edit" ? "本地图片以 Pi 进程操作系统权限直接只读原始字节并外传,不经过内置 read 审批,不是沙箱;仅普通文件,每个小于50 MB、含蒙版合计最多100 MB。不下载远程 URL;远程蒙版的格式与尺寸交上游验证。" : "") +
|
|
29
|
+
"返回实际图片块与唯一临时文件路径,不需 codemode 或 image()。请求可能计费;不自动重试或换模型,失败、取消或超时都不保证停止上游处理或未计费。",
|
|
30
|
+
parameters: operation === "generate" ? generateImageSchema : editImageSchema,
|
|
31
|
+
outputSchema: imageToolResultSchema,
|
|
32
|
+
exposure: "direct",
|
|
33
|
+
defaultActive: true,
|
|
34
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
|
|
35
|
+
async execute(_id, params, signal, _onUpdate, ctx) {
|
|
36
|
+
const details: ImageToolDetails = { operation, model: DEFAULT_IMAGE_MODEL, phase: "validate", requestStatus: "not-started", files: [] };
|
|
37
|
+
let usage: AssistantImages["usage"];
|
|
38
|
+
let images: ImageContent[] = [];
|
|
39
|
+
const caller = signal && ctx.signal && signal !== ctx.signal ? AbortSignal.any([signal, ctx.signal]) : signal ?? ctx.signal ?? new AbortController().signal;
|
|
40
|
+
try {
|
|
41
|
+
const prepared = prepareImageToolParameters(operation, params);
|
|
42
|
+
details.model = prepared.model;
|
|
43
|
+
caller.throwIfAborted();
|
|
44
|
+
const registry = ctx.modelRegistry;
|
|
45
|
+
if (typeof registry.getModelOfType !== "function" || typeof registry.generateImages !== "function")
|
|
46
|
+
throw new ImageToolFileError("unsupported-host", "图片工具需要支持 modelRegistry.getModelOfType/generateImages 的 Pi 1.2 或更新宿主。");
|
|
47
|
+
const model = registry.getModelOfType("image", "tsgw", prepared.model);
|
|
48
|
+
if (!model || model.provider !== "tsgw" || model.id !== prepared.model)
|
|
49
|
+
throw new ImageToolFileError("model-unavailable", "所选图片模型未在当前宿主目录中启用;不会绕过目录过滤或自动切换型号。");
|
|
50
|
+
details.phase = "input";
|
|
51
|
+
const references = operation === "edit" ? await resolveImageSources(prepared.images, prepared.mask, ctx.cwd, caller) : {};
|
|
52
|
+
const context: TsgwImagesContext = { input: [{ type: "text", text: prepared.prompt }],
|
|
53
|
+
tsgw: normalizeImageParameters({ ...prepared.parameters, operation, ...references }) };
|
|
54
|
+
caller.throwIfAborted();
|
|
55
|
+
details.phase = "request";
|
|
56
|
+
details.requestStatus = "unknown";
|
|
57
|
+
// 参数走显式 context.tsgw;timeout 是 options,不冒称 Pi 原生图片参数。
|
|
58
|
+
const response: TsgwImagesResult = await registry.generateImages(model, context, { timeoutMs: prepared.timeoutMs, signal: caller });
|
|
59
|
+
usage = response.usage;
|
|
60
|
+
if (response.tsgwUsage?.status === "unaggregated") {
|
|
61
|
+
usage = undefined;
|
|
62
|
+
details.usage_note = "多图流式用量归属未明确,逐事件报告未相加,也未计入会话总量;不是免费。";
|
|
63
|
+
details.usage_reports = response.tsgwUsage.reports.map(report => ({ ...report }));
|
|
64
|
+
}
|
|
65
|
+
if (response.stopReason !== "stop") {
|
|
66
|
+
details.requestStatus = "unknown";
|
|
67
|
+
throw new ImageToolFileError(response.stopReason === "aborted" ? "aborted" : "request-failed",
|
|
68
|
+
response.stopReason === "aborted" ? "图片调用已取消或超时;无法保证上游停止处理或未计费,请勿自动重试。" : "图片调用未成功;无法确认上游是否处理或计费,请勿自动重试。请检查宿主模型认证与网关;未切换模型。");
|
|
69
|
+
}
|
|
70
|
+
details.requestStatus = "succeeded";
|
|
71
|
+
details.phase = "output";
|
|
72
|
+
images = validateImageOutput(response.output, context.tsgw!.n!, context.tsgw!.output_format!);
|
|
73
|
+
details.phase = "save";
|
|
74
|
+
details.files = await saveImageOutput(images);
|
|
75
|
+
details.phase = "complete";
|
|
76
|
+
} catch (error) {
|
|
77
|
+
if (error instanceof ImageToolFileError) {
|
|
78
|
+
details.error = { code: error.code, message: error.message };
|
|
79
|
+
if (error.files.length) details.files = error.files;
|
|
80
|
+
} else {
|
|
81
|
+
// 不转发供应商异常、输入 URL、base64 或文件系统原始异常。
|
|
82
|
+
details.error = caller.aborted
|
|
83
|
+
? { code: "aborted", message: details.requestStatus === "not-started" ? "图片工具已取消,尚未调用上游。" : "图片调用已取消;上游结果未知,不保证停止处理或计费,请勿自动重试。" }
|
|
84
|
+
: details.phase === "validate" || details.phase === "input"
|
|
85
|
+
? { code: "invalid-parameters", message: "图片工具参数无效;请检查字段白名单、数值范围、图片来源与参数组合。未调用上游。" }
|
|
86
|
+
: { code: "request-unknown", message: "图片调用异常,无法确认上游结果或是否计费;未自动重试,请检查宿主与网关。" };
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return {
|
|
90
|
+
content: [{ type: "text" as const, text: JSON.stringify(details) }, ...images],
|
|
91
|
+
details, structuredContent: { ...details, files: details.files.map(file => ({ ...file })),
|
|
92
|
+
...(details.usage_reports ? { usage_reports: details.usage_reports.map(report => ({ ...report })) } : {}) }, ...(usage ? { usage } : {}),
|
|
93
|
+
...(details.error ? { isError: true } : {}),
|
|
94
|
+
};
|
|
95
|
+
},
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
}
|
|
@@ -57,10 +57,10 @@ function compilePatterns(patterns: readonly string[]): (id: string) => boolean {
|
|
|
57
57
|
}
|
|
58
58
|
|
|
59
59
|
/** 按“拉回优先”语义过滤模型目录;无过滤条件时原样返回。 */
|
|
60
|
-
export function filterModels(
|
|
61
|
-
models: readonly
|
|
60
|
+
export function filterModels<T extends { id: string }>(
|
|
61
|
+
models: readonly T[],
|
|
62
62
|
filter?: ModelFilter,
|
|
63
|
-
):
|
|
63
|
+
): T[] {
|
|
64
64
|
if (!filter) return [...models];
|
|
65
65
|
const include = filter.include?.length
|
|
66
66
|
? compilePatterns(filter.include)
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { ProviderModelConfig as AnyModelConfig } from "@earendil-works/pi-coding-agent";
|
|
1
2
|
import type { ChatModelConfig as ProviderModelConfig } from "../_tools.ts";
|
|
2
3
|
import { type PayloadWriter, type ThinkingApplier } from "../_tools.ts";
|
|
3
4
|
|
|
@@ -111,3 +112,21 @@ export const openaiThinking = {
|
|
|
111
112
|
"gpt-6-sol": (w, _c) => applyOpenAIResponses(w),
|
|
112
113
|
"gpt-6-luna": (w, _c) => applyOpenAIResponses(w),
|
|
113
114
|
} satisfies Record<string, ThinkingApplier>;
|
|
115
|
+
|
|
116
|
+
export const OPENAI_IMAGE_API = "tsgw-openai-images";
|
|
117
|
+
export const OPENAI_IMAGE_MODEL_IDS = ["gpt-image-2.5-flare", "gpt-image-2.5-sunburst"] as const;
|
|
118
|
+
export type OpenAIImageModelConfig = Extract<AnyModelConfig, { type: "image" }>;
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* 图片接口依据见记忆系统 942;两款模型共用生成与编辑适配。
|
|
122
|
+
* 价格暂未纳入计费映射,0 表示未知而非免费;不混入 openaiModels 的聊天目录。
|
|
123
|
+
*/
|
|
124
|
+
export function openaiImageModels(root: string): OpenAIImageModelConfig[] {
|
|
125
|
+
return OPENAI_IMAGE_MODEL_IDS.map((id, index) => ({
|
|
126
|
+
type: "image", id,
|
|
127
|
+
name: index === 0 ? "GPT Image 2.5 Flare" : "GPT Image 2.5 Sunburst",
|
|
128
|
+
api: OPENAI_IMAGE_API, baseUrl: `${root}/v1`,
|
|
129
|
+
input: ["text", "image"], output: ["image"],
|
|
130
|
+
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
131
|
+
}));
|
|
132
|
+
}
|
|
@@ -2,10 +2,12 @@ import type {
|
|
|
2
2
|
ExtensionAPI,
|
|
3
3
|
ExtensionCommandContext,
|
|
4
4
|
ExtensionContext,
|
|
5
|
+
ProviderModelConfig,
|
|
5
6
|
} from "@earendil-works/pi-coding-agent";
|
|
6
7
|
import {
|
|
7
8
|
getAgentDir,
|
|
8
9
|
readStoredCredential,
|
|
10
|
+
VERSION,
|
|
9
11
|
} from "@earendil-works/pi-coding-agent";
|
|
10
12
|
import { join } from "node:path";
|
|
11
13
|
import { randomUUID } from "node:crypto";
|
|
@@ -20,6 +22,8 @@ import {
|
|
|
20
22
|
import { getGatewayModelIds } from "../models/gateway-catalog.ts";
|
|
21
23
|
import { applyModelOperations } from "../models/operations.ts";
|
|
22
24
|
import { registerSearch } from "../search/index.ts";
|
|
25
|
+
import { IMAGE_API, imageModelsForRoot, supportsImageModels } from "../images/models.ts";
|
|
26
|
+
import { generateImages } from "../images/adapter.ts";
|
|
23
27
|
import {
|
|
24
28
|
catalogLabel,
|
|
25
29
|
catalogDiagnostics,
|
|
@@ -109,8 +113,12 @@ function effectiveModelsForGateway(
|
|
|
109
113
|
root: string,
|
|
110
114
|
filter: ModelFilter | undefined,
|
|
111
115
|
gatewayIds: ReadonlySet<string> | undefined,
|
|
112
|
-
|
|
113
|
-
|
|
116
|
+
imagesEnabled: boolean,
|
|
117
|
+
): ProviderModelConfig[] {
|
|
118
|
+
const staticModels: ProviderModelConfig[] = [
|
|
119
|
+
...modelsForRoot(root),
|
|
120
|
+
...(imagesEnabled ? imageModelsForRoot(root) : []),
|
|
121
|
+
];
|
|
114
122
|
const intersected = gatewayIds
|
|
115
123
|
? staticModels.filter((model) => gatewayHasModel(gatewayIds, model.id))
|
|
116
124
|
: staticModels;
|
|
@@ -125,8 +133,9 @@ async function resolveEffectiveModels(
|
|
|
125
133
|
root: string,
|
|
126
134
|
filter: ModelFilter | undefined,
|
|
127
135
|
cacheFilePath: string,
|
|
136
|
+
imagesEnabled: boolean,
|
|
128
137
|
): Promise<{
|
|
129
|
-
models:
|
|
138
|
+
models: ProviderModelConfig[];
|
|
130
139
|
gatewayIds: ReadonlySet<string> | undefined;
|
|
131
140
|
catalog: CatalogStatus;
|
|
132
141
|
}> {
|
|
@@ -161,7 +170,7 @@ async function resolveEffectiveModels(
|
|
|
161
170
|
}
|
|
162
171
|
}
|
|
163
172
|
if (catalog.error) console.warn(`TSGW: ${catalog.error}`);
|
|
164
|
-
const models = effectiveModelsForGateway(root, filter, gatewayIds);
|
|
173
|
+
const models = effectiveModelsForGateway(root, filter, gatewayIds, imagesEnabled);
|
|
165
174
|
return { models, gatewayIds, catalog: { ...catalog, count: models.length } };
|
|
166
175
|
}
|
|
167
176
|
|
|
@@ -169,6 +178,7 @@ export async function registerTsgwProvider(
|
|
|
169
178
|
pi: ExtensionAPI, settings: TsgwSettings,
|
|
170
179
|
): Promise<void> {
|
|
171
180
|
const root = rootForRuntime(settings.baseUrl);
|
|
181
|
+
const imagesEnabled = supportsImageModels(VERSION);
|
|
172
182
|
const defaultSearchMode: WebSearchMode =
|
|
173
183
|
settings.tsSearch === "cached" || settings.tsSearch === "live"
|
|
174
184
|
? settings.tsSearch
|
|
@@ -193,6 +203,7 @@ export async function registerTsgwProvider(
|
|
|
193
203
|
root,
|
|
194
204
|
modelFilter,
|
|
195
205
|
cacheFilePath,
|
|
206
|
+
imagesEnabled,
|
|
196
207
|
);
|
|
197
208
|
const { models } = initial;
|
|
198
209
|
let latestModels = models;
|
|
@@ -205,7 +216,7 @@ export async function registerTsgwProvider(
|
|
|
205
216
|
const search = registerSearch(pi, {
|
|
206
217
|
defaultMode: defaultSearchMode,
|
|
207
218
|
state: () => requestState,
|
|
208
|
-
models: () => latestModels,
|
|
219
|
+
models: () => latestModels.filter(model => model.type === undefined || model.type === "chat"),
|
|
209
220
|
revision: () => lifecycleRevision,
|
|
210
221
|
refreshState: refreshRequestState,
|
|
211
222
|
bindStatus: ctx => bindStatus(ctx),
|
|
@@ -234,6 +245,7 @@ export async function registerTsgwProvider(
|
|
|
234
245
|
api: "openai-completions",
|
|
235
246
|
apiKey: "$TSGW_API_KEY",
|
|
236
247
|
models,
|
|
248
|
+
...(imagesEnabled ? { images: { [IMAGE_API]: { generateImages } } } : {}),
|
|
237
249
|
async refreshModels(context) {
|
|
238
250
|
if (!context.allowNetwork) return latestModels;
|
|
239
251
|
context.signal.throwIfAborted();
|
|
@@ -256,7 +268,7 @@ export async function registerTsgwProvider(
|
|
|
256
268
|
if (gateway.stale)
|
|
257
269
|
throw new Error("TSGW 刷新失败;保留上次成功获取的目录。");
|
|
258
270
|
if (revision === refreshRevision) {
|
|
259
|
-
latestModels = effectiveModelsForGateway(root, modelFilter, new Set(gateway.ids));
|
|
271
|
+
latestModels = effectiveModelsForGateway(root, modelFilter, new Set(gateway.ids), imagesEnabled);
|
|
260
272
|
search.sync();
|
|
261
273
|
catalog = {
|
|
262
274
|
count: latestModels.length,
|
|
@@ -301,8 +313,10 @@ export async function registerTsgwProvider(
|
|
|
301
313
|
ctx.ui.notify("已跳过 TSGW 模型刷新:请先通过 /login 配置 API 密钥。", "warning");
|
|
302
314
|
return;
|
|
303
315
|
}
|
|
304
|
-
const count = () => ctx.modelRegistry.
|
|
305
|
-
.
|
|
316
|
+
const count = () => typeof ctx.modelRegistry.getModelsOfType === "function"
|
|
317
|
+
? ctx.modelRegistry.getModelsOfType("chat", PROVIDER_ID).length +
|
|
318
|
+
ctx.modelRegistry.getModelsOfType("image", PROVIDER_ID).length
|
|
319
|
+
: ctx.modelRegistry.getAvailable().filter((model) => model.provider === PROVIDER_ID).length;
|
|
306
320
|
const before = count();
|
|
307
321
|
revision = refreshRevision;
|
|
308
322
|
// 较旧的 Pi 版本返回 void,而非取消/错误元数据。
|
package/index.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { VERSION, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { supportsImageModels } from "./extensions/images/models.ts";
|
|
2
3
|
import { registerPrompts } from "./extensions/prompts.ts";
|
|
3
4
|
import { readTsgwSettings } from "./extensions/provider/config.ts";
|
|
4
5
|
import { registerTsgwProvider } from "./extensions/provider/index.ts";
|
|
@@ -7,6 +8,10 @@ import { registerUploadTool } from "./extensions/upload/index.ts";
|
|
|
7
8
|
/** 插件总入口:保持能力注册顺序,实现由各模块维护。 */
|
|
8
9
|
export default async function registerTsgw(pi: ExtensionAPI): Promise<void> {
|
|
9
10
|
registerUploadTool(pi);
|
|
11
|
+
if (supportsImageModels(VERSION)) {
|
|
12
|
+
const { registerImageTools } = await import("./extensions/images/tools.ts");
|
|
13
|
+
registerImageTools(pi);
|
|
14
|
+
}
|
|
10
15
|
registerPrompts(pi);
|
|
11
16
|
const settings = readTsgwSettings();
|
|
12
17
|
await registerTsgwProvider(pi, settings);
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-tsgw",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "面向 TOSSP AIH gateway 的 Pi
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "面向 TOSSP AIH gateway 的 Pi 扩展:按厂商维护聊天与图片模型目录及思考策略,支持四种聊天协议与图片生成、编辑工具。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"pi",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
]
|
|
25
25
|
},
|
|
26
26
|
"scripts": {
|
|
27
|
-
"test": "tsc -p tsconfig.test.json && node dist/extensions/provider/index.test.js && node dist/extensions/prompts.test.js && node dist/extensions/provider/status.test.js && node dist/extensions/search/index.test.js && node dist/extensions/search/proxy.test.js && node dist/extensions/search/host-integration.test.js && node dist/extensions/provider/status-integration.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/operations.test.js && node dist/extensions/models/catalog.test.js && node dist/extensions/models/web-search.test.js && node dist/extensions/models/gateway-catalog.test.js && node dist/extensions/models/gateway-catalog-isolation.test.js && node dist/extensions/models/vendor-strategies.test.js && node dist/index.test.js && node dist/extensions/skills.test.js && node dist/extensions/skill-resources.test.js && node dist/extensions/upload/protocol.test.js && node dist/extensions/upload/schema.test.js && node dist/extensions/upload/uploader.test.js && node dist/extensions/upload/transport.test.js && node dist/extensions/upload/host-integration.test.js && node dist/extensions/upload/readiness-host.test.js",
|
|
27
|
+
"test": "tsc -p tsconfig.test.json && node dist/extensions/provider/index.test.js && node dist/extensions/prompts.test.js && node dist/extensions/provider/status.test.js && node dist/extensions/search/index.test.js && node dist/extensions/search/proxy.test.js && node dist/extensions/search/host-integration.test.js && node dist/extensions/provider/status-integration.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/operations.test.js && node dist/extensions/models/catalog.test.js && node dist/extensions/models/web-search.test.js && node dist/extensions/models/gateway-catalog.test.js && node dist/extensions/models/gateway-catalog-isolation.test.js && node dist/extensions/models/vendor-strategies.test.js && node dist/extensions/images/models.test.js && node dist/extensions/images/parameters.test.js && node dist/extensions/images/input-budget.test.js && node dist/extensions/images/edit-request.test.js && node dist/extensions/images/image-data.test.js && node dist/extensions/images/response.test.js && node dist/extensions/images/stream-response.test.js && node dist/extensions/images/adapter.test.js && node dist/extensions/images/tool-files.test.js && node dist/extensions/images/tools.test.js && node dist/extensions/images/host-integration.test.js && node dist/extensions/images/tools-host.test.js && node dist/index.test.js && node dist/extensions/skills.test.js && node dist/extensions/skill-resources.test.js && node dist/extensions/upload/protocol.test.js && node dist/extensions/upload/schema.test.js && node dist/extensions/upload/uploader.test.js && node dist/extensions/upload/transport.test.js && node dist/extensions/upload/host-integration.test.js && node dist/extensions/upload/readiness-host.test.js",
|
|
28
28
|
"test:upload:live": "tsc -p tsconfig.test.json && node dist/extensions/upload/live.test.js"
|
|
29
29
|
},
|
|
30
30
|
"peerDependencies": {
|
|
@@ -44,7 +44,8 @@ compatibility: 需要宿主提供子代理工具及可用的 tsgw 模型。
|
|
|
44
44
|
|
|
45
45
|
- **MiniMax-M3** 只承担步骤明确的小任务。参考使用 Pi 的 high;非 off 档位均映射为 adaptive,不代表不同能力档。adaptive 不是 Pi 档位,此映射不适用于 M3.1 Flash Preview。
|
|
46
46
|
- **deepseek-flash** 作为按量付费补位时使用 max。
|
|
47
|
-
- **
|
|
48
|
-
-
|
|
47
|
+
- **Astra 审阅档位**:架构设计、正式设计文档的独立审阅与最终复核,默认使用 `gpt-6-astra` / `max`,不因材料篇幅短或范围明确而自动降档。局部检查、定向复审可按范围降低档位。
|
|
48
|
+
- **Kimi** 不承担长程执行;双模型复核固定为 **Kimi+Astra**,独立审查同一份材料。Kimi 使用 kimi-k3 / high,Astra 遵循上述审阅档位规则;其他任务的深度按任务选择。
|
|
49
|
+
- 不可用的模型或档位如实说明。
|
|
49
50
|
|
|
50
51
|
宿主支持 `Agent.model = provider/modelId:level` 时,例如 `tsgw/MiniMax-M3:high`、`tsgw/glm-5.3:max`;其他宿主使用其实际格式。
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tsgw-image-generation
|
|
3
|
+
description: 当用户要求生成图片、生图或画图,以及修改图片、参考图创作或蒙版编辑时使用。使用 tsgw_generate_image 或 tsgw_edit_image,根据草稿或成稿选择模型与参数,并展示图片结果。
|
|
4
|
+
license: MIT
|
|
5
|
+
compatibility: 需要 Pi 1.2+、pi-tsgw 图片工具及可用的 tsgw 图片模型。
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# 图片生成与编辑
|
|
9
|
+
|
|
10
|
+
## 选择工具和模型
|
|
11
|
+
|
|
12
|
+
- 从文字创建图片:调用 `tsgw_generate_image`,填写 `prompt`。
|
|
13
|
+
- 根据一张或多张图片修改、参考创作:调用 `tsgw_edit_image`,填写 `prompt` 和 `images`;局部修改可增加 `mask`。
|
|
14
|
+
- **草稿、构图探索、速度优先**:选择 `gpt-image-2.5-flare`,质量可用 `low`。
|
|
15
|
+
- **正式成图、精细修改、质量优先**:选择 `gpt-image-2.5-sunburst`,这是工具的默认模型;质量按需求从 `auto` 或 `high` 起选。
|
|
16
|
+
|
|
17
|
+
按用户任务选择模型和参数。`prompt` 写清主体、构图、风格、尺寸意图,以及需要呈现或保留的文字与细节;编辑时区分“修改什么”和“保留什么”。
|
|
18
|
+
|
|
19
|
+
## 最简调用
|
|
20
|
+
|
|
21
|
+
调用 `tsgw_generate_image`:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"prompt": "横版水墨山水,远山薄雾,一叶扁舟,不要文字"
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
快速草稿:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"prompt": "极简咖啡馆标志草稿,咖啡杯与山峰结合,无文字",
|
|
34
|
+
"model": "gpt-image-2.5-flare",
|
|
35
|
+
"quality": "low",
|
|
36
|
+
"size": "1024x1024"
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
调用 `tsgw_edit_image` 修改本地图片,蒙版对应第一张原图:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"prompt": "把蒙版标出的区域改为盛开的荷花,保留原图其余构图和水墨风格",
|
|
45
|
+
"images": [{ "path": "source.png" }],
|
|
46
|
+
"mask": { "path": "mask.png" }
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`images` 保留参考图顺序,支持 1–16 张;每个来源选择 `path`、`image_url`、`file_id` 其中之一。`path` 是 Pi 运行主机上的文件路径,相对路径以会话工作目录为准;`image_url` 接受 HTTP(S) URL 或图片 data URI,`file_id` 使用上游已有文件 ID。蒙版可省略;提供时,与第一张原图保持格式及尺寸一致,并带透明通道,用透明区域指示编辑范围。
|
|
51
|
+
|
|
52
|
+
## 可选参数
|
|
53
|
+
|
|
54
|
+
生成和编辑共用下列可选参数,省略时使用默认值;只填写任务需要覆盖的项。
|
|
55
|
+
|
|
56
|
+
| 参数 | 默认值 | 用途与取值 |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| `model` | `gpt-image-2.5-sunburst` | 草稿用 Flare,正式成图用 Sunburst |
|
|
59
|
+
| `quality` | `auto` | `low`、`medium`、`high`、`xhigh`、`max`、`auto`;`xhigh`/`max` 用于确实需要额外细节的任务 |
|
|
60
|
+
| `size` | `auto` | `宽x高`;例如 `1024x1024`、`1536x1024`、`1024x1536`、`2048x1152`、`3840x2160` |
|
|
61
|
+
| `background` | `auto` | `auto`、`opaque`、`transparent`;透明输出搭配 PNG 或 WebP |
|
|
62
|
+
| `output_format` | `png` | `png`、`jpeg`、`webp` |
|
|
63
|
+
| `output_compression` | JPEG/WebP 使用 `100` | `0–100` 整数,用于 JPEG/WebP |
|
|
64
|
+
| `n` | `1` | 一次请求生成 `1–10` 张图片 |
|
|
65
|
+
| `moderation` | `auto` | `auto` 或 `low` |
|
|
66
|
+
| `stream` | `false` | 是否使用上游流式响应;工具处理完成后返回最终图片 |
|
|
67
|
+
| `partial_images` | `0` | 流式请求中希望收到的过程图数量,`0–3` |
|
|
68
|
+
| `safety_identifier` | 省略 | 应用需要时提供稳定的匿名用户标识,最多 128 字符 |
|
|
69
|
+
| `user` | 省略 | 上游旧用户标识字段;新接入使用 `safety_identifier` |
|
|
70
|
+
| `timeout_ms` | `600000` | 单次调用等待时间,单位毫秒;可按任务覆盖。通过 codemode 包装调用时,脚本截止应留余量,例如默认请求配 `660000` |
|
|
71
|
+
|
|
72
|
+
自定义尺寸:宽高都是 16 的倍数,单边至多 3840,长短边比例至多 3,总像素为 655360–8294400;超过 3686400 像素属于上游实验范围。
|
|
73
|
+
|
|
74
|
+
## 使用结果
|
|
75
|
+
|
|
76
|
+
工具返回图片及原始文件的临时路径。根据返回结果展示或交付图片;继续编辑时,可以将该原始文件路径放入下一次 `images[].path`。若结果带 `usage_note`,按其说明报告计量状态;多图流式的逐事件用量可能无法确定汇总值。
|