pi-tsgw 0.3.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.
@@ -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
+ }
@@ -118,7 +118,7 @@ export const OPENAI_IMAGE_MODEL_IDS = ["gpt-image-2.5-flare", "gpt-image-2.5-sun
118
118
  export type OpenAIImageModelConfig = Extract<AnyModelConfig, { type: "image" }>;
119
119
 
120
120
  /**
121
- * 图片接口依据见记忆系统 942;仅登记本插件已实现的文生图能力,不宣称支持编辑。
121
+ * 图片接口依据见记忆系统 942;两款模型共用生成与编辑适配。
122
122
  * 价格暂未纳入计费映射,0 表示未知而非免费;不混入 openaiModels 的聊天目录。
123
123
  */
124
124
  export function openaiImageModels(root: string): OpenAIImageModelConfig[] {
@@ -126,7 +126,7 @@ export function openaiImageModels(root: string): OpenAIImageModelConfig[] {
126
126
  type: "image", id,
127
127
  name: index === 0 ? "GPT Image 2.5 Flare" : "GPT Image 2.5 Sunburst",
128
128
  api: OPENAI_IMAGE_API, baseUrl: `${root}/v1`,
129
- input: ["text"], output: ["image"],
129
+ input: ["text", "image"], output: ["image"],
130
130
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
131
131
  }));
132
132
  }
package/index.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
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.3.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/extensions/images/models.test.js && node dist/extensions/images/adapter.test.js && node dist/extensions/images/host-integration.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
- - **Kimi** 不承担长程执行;双模型复核固定为 **Kimi+Astra**,独立审查同一份材料。Kimi 使用 kimi-k3 / high,Astra 深度按任务选择。
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`,按其说明报告计量状态;多图流式的逐事件用量可能无法确定汇总值。