pi-tsgw 0.1.1 → 0.3.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 CHANGED
@@ -1,8 +1,9 @@
1
1
  # pi-tsgw
2
2
 
3
- 面向 TOSSP AIH gateway 的 Pi 扩展。注册 `tsgw` 提供商,其模型目录涵盖四种通信协议
3
+ 面向 TOSSP AIH gateway 的 Pi 扩展。注册 `tsgw` 提供商,其聊天模型涵盖四种通信协议
4
4
  (openai-completions、openai-responses、anthropic-messages、google-generative-ai),
5
5
  并按厂商对请求体执行相应操作,使思考级别、推理格式和可选的内置网络搜索在网关上正常工作。
6
+ 图片模型通过 Pi 原生图片 API 调度,插件适配网关的 Images 接口,不经过 MCP。
6
7
 
7
8
  本项目不包含私有 API 密钥或网关端点。静态目录包含模型元数据和公开价格估算;
8
9
  这些价格并非你的网关计费费率。
@@ -17,6 +18,7 @@ index.test.ts # 宿主集成总测试
17
18
  extensions/provider/ # provider 注册、配置、状态及其测试
18
19
  extensions/models/ # 模型目录、策略与联网支持
19
20
  extensions/search/ # 搜索注册、代理与相邻测试
21
+ extensions/images/ # 原生图片生成适配与宿主集成测试
20
22
  extensions/prompts.ts # registerPrompts
21
23
  prompts/memory.ts # 记忆提示词正文
22
24
  extensions/upload/ # 本地上传及安全说明
@@ -48,7 +50,6 @@ pi install npm:pi-tsgw
48
50
  {
49
51
  "tsgw": {
50
52
  "baseUrl": "https://aih.example.net",
51
- "mcpUrl": "https://xn--oht.cc/mcp",
52
53
  "tsSearch": "live",
53
54
  "traceHeaders": false,
54
55
  "excludeModels": ["gpt-*", "claude-*"],
@@ -78,7 +79,6 @@ pi install npm:pi-tsgw
78
79
  | 设置(`settings.json` 中的 `tsgw.*`) | 默认值 | 含义 |
79
80
  | --- | --- | --- |
80
81
  | `baseUrl` | 占位地址 | 网关根地址(规范化时去掉 `/v1` 后缀) |
81
- | `mcpUrl` | `https://xn--oht.cc/mcp` | 可选的 `ts_oht` HTTP(S) 端点覆盖值;独立于模型网关 |
82
82
  | `tsSearch` | `live` | GPT:`cached` 或 `live`;未设置、旧值 `off` 和无效值均回退到 `live`。受支持的 Grok 模型始终使用实时搜索。 |
83
83
  | `traceHeaders` | `false` | 添加 `AH-Thread-Id` / `AH-Trace-Id` 请求头,用于网关侧追踪 |
84
84
  | `includeModels` | 未设置 | 重新纳入的覆盖规则:匹配的模型 ID 即使也被 `excludeModels` 匹配,仍会保留(精确 ID 或 `prefix-*` 通配模式) |
@@ -133,13 +133,30 @@ GLM 5.3 仅支持文本。注册并不证明网关支持推理或工具调用。
133
133
  重新获取。旧版无作用域缓存文件会被忽略,并在获取成功后替换。
134
134
  进程内请求排序可防止较晚返回的结果覆盖更新的缓存写入;这不是跨进程锁机制。
135
135
 
136
+ ## 原生图片生成
137
+
138
+ Pi 1.2+ 可在现有 `tsgw` provider 中注册 `gpt-image-2.5-flare` 和
139
+ `gpt-image-2.5-sunburst` 两个 `type: image` 模型。它们复用相同的 `baseUrl`、TSGW
140
+ 凭据及 `$TSGW_API_KEY`;由 Pi 宿主解析 `options.apiKey`。图片目录受静态目录、网关目录
141
+ 与 `includeModels` / `excludeModels` 的交集及过滤规则约束;不会自动登记裸别名
142
+ `gpt-image-2.5` 或其他图片模型。需要按前缀纳入时可用 `"includeModels": ["gpt-image-2.5*"]`,
143
+ 但 include 不能突破目录交集。
144
+
145
+ 初版仅支持文生图:一次生成一张 PNG,不支持图片编辑。图片模型不出现在聊天模型选择器中,
146
+ 也不会作为聊天模型提供给搜索代理。使用 Pi codemode 前提是宿主已启用该工具;本扩展不因
147
+ 没有 MCP 就自动启用工具。若宿主的 `defaultTools` 未包含 `codemode`,只在确有需要时手动
148
+ 启用 `+codemode`。具体调用、超时、结果与价格语义见[图片生成维护与使用说明](extensions/images/README.md)。
149
+
150
+ 图片价格显示为 0 表示尚未映射准确价格,不是免费;usage 只统计上游已报告的有效 tokens。
151
+ 当前说明不代表已完成真实网关图片生成验收。
152
+
136
153
  ## 状态栏与会话控制
137
154
 
138
155
  支持 `command:/…` 状态的 Pi Web 客户端会将其渲染为可点击按钮;终端 CLI 显示状态文本,
139
156
  并接受相同命令:
140
157
 
141
158
  - **`TSGW · N`**(`/tsgw`):在同一菜单中**刷新模型目录**和**查看诊断信息**。
142
- 数量表示过滤后已注册的目录条目数,而非健康推理端点的数量。
159
+ 数量表示过滤后已注册的聊天与图片目录条目数,而非健康推理端点的数量。
143
160
  🟢 表示新鲜的目录结果;🟡 表示静态/过期目录或刷新失败;⚠️ 表示缺少凭据或网关配置;
144
161
  ⏳ 表示正在刷新。
145
162
  - **内置联网**(`/tsgw-search`):GPT 仅为当前会话提供 `cached / live`,默认为 `live`。
@@ -225,30 +242,32 @@ GLM 指导使用 5.3,并以 Flash 和 FlashX 为备选。思考级别使用 Pi
225
242
  smemo/Blinko 仍称为“记忆系统”。技能迁移不操作 Blinko 数据或改变宿主认证与权限。
226
243
  从本地 `smemo` 迁入时,确认新版本插件与随包技能加载生效后,再移除原技能和用户规则中的重复内容。
227
244
 
228
- ## 默认 MCP 注册
245
+ ## MCP 服务配置
229
246
 
230
- 插件每次加载时都会向宿主登记以下会话默认值,暴露方式均为 `codemode`:
247
+ 插件不再自动登记 `ts_oht` 或 `ts_tool`,也不会自动写入任何配置。需要使用时,请由用户自行在
248
+ `~/.pi/agent/mcp.json` 配置;以下示例保留服务原名、原 URL,并以 `codemode` 暴露:
231
249
 
232
- | 服务器名称 | 默认端点 |
233
- | --- | --- |
234
- | `ts_oht` | `https://xn--oht.cc/mcp` |
235
- | `ts_tool` | `https://mcp.tossp.com/mm/ts/mcp` |
236
-
237
- 使用这些默认值无需手工配置 MCP。用户级设置中可选的 `tsgw.mcpUrl` 仅覆盖 `ts_oht`,
238
- 独立于 `tsgw.baseUrl`,且仅在初始化时读取一次;`ts_tool` 的覆盖交给宿主同名文件配置,
239
- 没有额外的插件配置项。显式 `mcpUrl` 无效时,安全警告并仅跳过 `ts_oht`,
240
- 不静默回退,也不影响 `ts_tool`。单个登记失败不阻断另一服务或模型提供方;
241
- 不支持 `registerMcpServer` 的旧宿主会跳过两者注册。
242
-
243
- Pi 管理连接、OAuth 登录和凭据。需要登录时,在会话内对相应服务使用 `/mcp login ts_oht` 或 `/mcp login ts_tool`。
244
- 插件不读写 `mcp.json` 或 `mcp-auth.json`,也不携带凭据。
245
- 保持相同的服务器名称和完全一致的 URL,才能复用宿主现有的 OAuth 作用域。
246
-
247
- 有效的全局/项目 `mcp.json` 中同名的 `ts_oht`、`ts_tool` 分别优先于插件注册,包括 `enabled: false`;
248
- 插件不会创建第二条连接,也不会绕过该选择。要覆盖 URL、暴露方式、超时、认证或启用状态,
249
- 请在文件中使用完整的同名配置。对插件提供的服务器所做的更改仅作用于当前会话,不会保存。
250
- Shell 中的 `pi mcp` 命令不加载插件,无法看到仅由此注册提供的服务器。
251
- 配置变更后请重新加载或重启。
250
+ ```json
251
+ {
252
+ "mcpServers": {
253
+ "ts_oht": {
254
+ "url": "https://xn--oht.cc/mcp",
255
+ "exposure": "codemode"
256
+ },
257
+ "ts_tool": {
258
+ "url": "https://mcp.tossp.com/mm/ts/mcp",
259
+ "exposure": "codemode"
260
+ }
261
+ }
262
+ }
263
+ ```
264
+
265
+ Pi 宿主管理 MCP 连接、OAuth 登录和凭据;可通过设置页或 `pi mcp login ts_oht` /
266
+ `pi mcp login ts_tool` 完成登录。迁移时保持相同名称和精确 URL 可复用已有认证记录;
267
+ 记录失效时仍需重新授权。旧的 `tsgw.mcpUrl` 已移除,不再生效。配置变更后请重新加载或重启。
268
+ 插件不自建 MCP
269
+ 客户端或认证逻辑,不读写 `mcp.json` / `mcp-auth.json`,也不携带凭据。
270
+ 上传工具仍复用宿主已连接且可调用的 `ts_oht`,不会自行连接或绕过禁用、权限及认证状态。
252
271
 
253
272
  ## 本地文件上传
254
273
 
@@ -0,0 +1,39 @@
1
+ # 原生图片生成
2
+
3
+ 本目录维护 `tsgw` provider 的原生图片生成适配,以及宿主集成测试 `host-integration.test.ts`。
4
+ 此功能使用 Pi 的 `type: image` 模型与 codemode 图片 API,不是聊天模型、MCP 服务或图片编辑功能。
5
+
6
+ ## 支持范围
7
+
8
+ - Pi `VERSION` 为 1.2.0 或更高稳定版本时才注册 `gpt-image-2.5-flare` 与 `gpt-image-2.5-sunburst`,类型为 `image`。低于 1.2 时不注册图片模型或 adapter,原有聊天功能保持不变;不提升 provider 最低 peer 版本。此兼容策略不是对真实旧版 Pi 的验收声明。
9
+ - 图片模型目录遵循静态目录 ∩ 网关目录,再应用 `includeModels` / `excludeModels`。include 优先于 exclude,但不能突破交集。不会自动登记 `gpt-image-2.5` 裸别名或其他图片模型;用户可用 `gpt-image-2.5*` 前缀规则纳入已在交集中的模型。
10
+ - 仅文生图:每次请求生成单张 PNG,不支持编辑或输入图片。图片模型不作为聊天模型提供,也不会被搜索代理选作聊天模型。provider 状态计数统计实际登记的聊天与图片条目。
11
+
12
+ ## 凭据、API 与调用
13
+
14
+ 图片能力沿用 provider 现有 `baseUrl` 和 TSGW 凭据(Pi 已存凭据或 `$TSGW_API_KEY`),宿主负责解析 `options.apiKey`。图片 API 适配仅以最小请求实现 `POST /v1/images/generations`;不新增 HTTP 客户端 SDK 或 MCP 依赖,不改动 `ts_oht` 服务端。请求默认 `quality` 与 `size` 为 `auto`,输出单张 PNG。
15
+
16
+ 在宿主已启用 codemode 的前提下,调用方式为:
17
+
18
+ ```ts
19
+ const available = await models.getAvailableOfType("image", "tsgw");
20
+ const model = available.find(model => model.id === "gpt-image-2.5-flare");
21
+ if (!model) throw new Error("图片模型未登记或 TSGW 凭据不可用");
22
+ const result = await models.generateImages(model, {
23
+ input: [{ type: "text", text: "横版水墨山水,远山薄雾,一叶扁舟,不要文字" }],
24
+ });
25
+ if (result.stopReason !== "stop") throw new Error(result.errorMessage);
26
+ const pictures = result.output.filter(block => block.type === "image");
27
+ if (pictures.length === 0) throw new Error("没有返回图片,不视为生成成功");
28
+ for (const block of pictures) image(block);
29
+ ```
30
+
31
+ 也可通过 `await models.getModelsOfType("image", "tsgw")` 查看已登记目录,或 `await models.getAvailableOfType("image", "tsgw")` 查询具有可用凭据的图片模型;`generateImages` 的原生调用仅有 `model` 和请求对象两个参数,不提供 `size` / `quality` 选项参数。宿主未启用 codemode 时,本扩展不会自动启用工具;仅在确有需要且 `defaultTools` 未含该工具时,手动为宿主启用 `+codemode`。本说明不要求改写用户配置。
32
+
33
+ 检查返回的 `stopReason` 和 image 内容后,使用 codemode 的 `image(block)` 展示图片并取得生成的临时路径。API 实现默认超时 300 秒,可响应 `signal`,并接受更短的 `options.timeoutMs`。不自动重试,也不自动切换模型。取消请求不保证上游停止处理或停止计费。
34
+
35
+ 响应 JSON 限制 32 MiB,PNG 限制单边 3840、总像素 8294400;校验容器与块 CRC,不声称完成像素解码。
36
+ usage 仅包括上游已报告且有效的 tokens;完整 JSON 已返回但图片校验失败时,也保留这些用量。图片价格显示为 0 表示尚未映射准确价格,不表示免费。实现、模拟响应或宿主集成测试均不等于真实网关生成验收;真实上游能力需要另行授权验证。
37
+
38
+ 型号与能力在 `extensions/models/vendors/openai.ts` 维护,接口依据见记忆系统 942;
39
+ `models.ts` 汇出图片入口并判断宿主基线,`adapter.ts` / `response.ts` 负责图片请求及结果校验。
@@ -0,0 +1,136 @@
1
+ import type { AssistantImages, ProviderHeaders, ProviderImages } from "@earendil-works/pi-ai";
2
+ import { IMAGE_API, IMAGE_MODEL_IDS } from "./models.ts";
3
+ import { abortable, ImageFailure, parseImage, parseUsage, readJson, record } from "./response.ts";
4
+
5
+ const DEFAULT_TIMEOUT_MS = 300_000;
6
+ const UNCERTAIN = "未自动重试;此结果不代表上游未计费。";
7
+ const QUALITIES = new Set(["low", "medium", "high", "xhigh", "max", "auto"]);
8
+
9
+ function validPrompt(value: unknown): value is string {
10
+ return typeof value === "string" && value.trim().length > 0 && value.length <= 32_000;
11
+ }
12
+
13
+ function validSize(value: unknown): boolean {
14
+ if (value === "auto") return true;
15
+ if (typeof value !== "string" || /^[1-9]\d{0,3}x[1-9]\d{0,3}$/.exec(value)?.[0] !== value) return false;
16
+ const [width, height] = value.split("x").map(Number);
17
+ return width % 16 === 0 && height % 16 === 0 && Math.max(width, height) <= 3840 &&
18
+ Math.max(width, height) / Math.min(width, height) <= 3 &&
19
+ width * height >= 655_360 && width * height <= 8_294_400;
20
+ }
21
+
22
+ function payloadBody(payload: unknown, id: string): string {
23
+ // 校验实际发送的 JSON,避免钩子对象的 getter/toJSON 绕过固定请求边界。
24
+ const body = JSON.stringify(payload);
25
+ const value: unknown = body === undefined ? undefined : JSON.parse(body);
26
+ if (!record(value) || value.model !== id || value.n !== 1 || value.output_format !== "png" ||
27
+ !validPrompt(value.prompt) || typeof value.quality !== "string" || !QUALITIES.has(value.quality) || !validSize(value.size)) {
28
+ throw new ImageFailure("图片请求参数无效:仅允许当前模型、单张 PNG、非空且不超过 32000 字符的提示词及受限质量和尺寸。");
29
+ }
30
+ return body;
31
+ }
32
+
33
+ function mergeHeaders(apiKey: string | undefined, ...sources: (ProviderHeaders | undefined)[]): Headers {
34
+ const headers = new Headers({ "Content-Type": "application/json" });
35
+ if (apiKey?.trim()) headers.set("Authorization", `Bearer ${apiKey}`);
36
+ let authSuppressed = false;
37
+ for (const source of sources) {
38
+ for (const [name, value] of Object.entries(source ?? {})) {
39
+ if (name.toLowerCase() === "authorization") authSuppressed = value === null;
40
+ if (value === null) headers.delete(name);
41
+ else headers.set(name, value);
42
+ }
43
+ }
44
+ // 显式 null 是调用者抑制默认认证的授权;缺省凭据则不发送匿名请求。
45
+ if (!headers.get("authorization") && !authSuppressed) throw new ImageFailure("图片请求缺少认证信息。");
46
+ return headers;
47
+ }
48
+
49
+ export const generateImages: ProviderImages["generateImages"] = async (model, context, options = {}) => {
50
+ const result: AssistantImages = {
51
+ api: IMAGE_API, provider: "tsgw", model: model.id, output: [], stopReason: "error", timestamp: Date.now(),
52
+ };
53
+ const controller = new AbortController();
54
+ let timedOut = false;
55
+ let timer: ReturnType<typeof setTimeout> | undefined;
56
+ let received: Response | undefined;
57
+ let deadline = Infinity;
58
+ const cancel = () => controller.abort();
59
+ const check = () => {
60
+ if (!controller.signal.aborted && Date.now() >= deadline) { timedOut = true; controller.abort(); }
61
+ controller.signal.throwIfAborted();
62
+ };
63
+ try {
64
+ options.signal?.addEventListener("abort", cancel, { once: true });
65
+ if (options.signal?.aborted) cancel();
66
+ check();
67
+ if (model.type !== "image" || model.provider !== "tsgw" || model.api !== IMAGE_API ||
68
+ !IMAGE_MODEL_IDS.some(id => id === model.id)) throw new ImageFailure("不支持此图片模型或协议。");
69
+ if (!Array.isArray(context.input) || context.input.length === 0 ||
70
+ context.input.some(block => !block || block.type !== "text" || !validPrompt(block.text))) {
71
+ throw new ImageFailure("图片生成仅接受非空文本块,不接受图片或空输入。");
72
+ }
73
+ const prompt = context.input.map(block => block.type === "text" ? block.text : "").join("\n");
74
+ if (!validPrompt(prompt)) throw new ImageFailure("图片提示词合并后不得超过 32000 字符。");
75
+ const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
76
+ if (!Number.isFinite(timeout) || timeout < 0) throw new ImageFailure("图片请求超时时间无效。");
77
+ const duration = Math.min(timeout, DEFAULT_TIMEOUT_MS);
78
+ deadline = Date.now() + duration;
79
+ timer = setTimeout(() => {
80
+ if (!controller.signal.aborted) { timedOut = true; controller.abort(); }
81
+ }, duration);
82
+ check();
83
+ const url = `${model.baseUrl.replace(/\/+$/, "")}/images/generations`;
84
+ const headers = mergeHeaders(options.apiKey, model.headers, options.headers);
85
+ const payload = { model: result.model, prompt, n: 1, quality: "auto", size: "auto", output_format: "png" };
86
+ const replacement = options.onPayload ? await abortable(controller.signal, () => options.onPayload!(payload, model)) : undefined;
87
+ check();
88
+ const body = payloadBody(replacement === undefined ? payload : replacement, result.model);
89
+ check();
90
+ const response = await abortable(controller.signal, async () => {
91
+ const response = await (options.fetch ?? globalThis.fetch)(url, {
92
+ method: "POST", headers, body, signal: controller.signal, redirect: "error",
93
+ });
94
+ received = response;
95
+ // 自定义 fetch 可能忽略 signal;迟到响应不再保留未消费的流。
96
+ if (controller.signal.aborted) void response.body?.cancel().catch(() => {});
97
+ return response;
98
+ });
99
+ check();
100
+ if (options.onResponse) {
101
+ await abortable(controller.signal, () => options.onResponse!({
102
+ status: response.status, headers: Object.fromEntries(response.headers.entries()),
103
+ }, model));
104
+ }
105
+ check();
106
+ if (response.status !== 200) {
107
+ const status = Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? `(HTTP ${response.status})` : "";
108
+ throw new ImageFailure(`图片请求失败${status}。`);
109
+ }
110
+ const raw = await readJson(response, controller.signal);
111
+ check();
112
+ // 上游可能已完成计费;图片校验失败也保留已报告且有效的用量。
113
+ const usage = parseUsage(raw, model);
114
+ if (usage) result.usage = usage;
115
+ const data = parseImage(raw);
116
+ check();
117
+ result.output = [{ type: "image", data, mimeType: "image/png" }];
118
+ result.stopReason = "stop";
119
+ return result;
120
+ } catch (error) {
121
+ if (!controller.signal.aborted && Date.now() >= deadline) { timedOut = true; controller.abort(); }
122
+ if (controller.signal.aborted) {
123
+ result.stopReason = timedOut ? "error" : "aborted";
124
+ result.errorMessage = `${timedOut ? "图片请求超时。" : "图片请求已取消。"}${UNCERTAIN}`;
125
+ } else {
126
+ result.errorMessage = `${error instanceof ImageFailure ? error.message : "图片请求失败,请检查认证、网络及请求钩子。"}${UNCERTAIN}`;
127
+ }
128
+ return result;
129
+ } finally {
130
+ if (timer !== undefined) clearTimeout(timer);
131
+ options.signal?.removeEventListener("abort", cancel);
132
+ controller.abort();
133
+ // 也覆盖 fetch 已完成但 race 被取消抢先结束、尚未赋值给局部 response 的情况。
134
+ if (received?.body && !received.body.locked) void received.body.cancel().catch(() => {});
135
+ }
136
+ };
@@ -0,0 +1,16 @@
1
+ // 厂商型号与能力仍由 vendor 维护;图片模块提供能力入口和宿主基线判断。
2
+ export {
3
+ OPENAI_IMAGE_API as IMAGE_API,
4
+ OPENAI_IMAGE_MODEL_IDS as IMAGE_MODEL_IDS,
5
+ openaiImageModels as imageModelsForRoot,
6
+ type OpenAIImageModelConfig as ImageModelConfig,
7
+ } from "../models/vendors/openai.ts";
8
+
9
+ /** 混合模型目录和图片实现登记以 Pi 1.2 为已验证基线;旧宿主保持聊天目录。 */
10
+ export function supportsImageModels(version: string): boolean {
11
+ const match = /^(\d+)\.(\d+)\.(\d+)(?:\+.*)?$/.exec(version);
12
+ if (!match) return false;
13
+ const major = Number(match[1]);
14
+ const minor = Number(match[2]);
15
+ return major > 1 || (major === 1 && minor >= 2);
16
+ }
@@ -0,0 +1,141 @@
1
+ import type { ImageApi, ImageModel, Usage } from "@earendil-works/pi-ai";
2
+
3
+ export const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
4
+
5
+ // 仅此类携带插件自行构造的安全错误;原始异常和服务端消息不进入结果。
6
+ export class ImageFailure extends Error {}
7
+
8
+ export function record(value: unknown): value is Record<string, unknown> {
9
+ return value !== null && typeof value === "object" && !Array.isArray(value);
10
+ }
11
+
12
+ // race 会观察迟到的拒绝;即使自定义 fetch 或钩子不响应 signal,也及时结束等待。
13
+ export async function abortable<T>(signal: AbortSignal, action: () => T | PromiseLike<T>): Promise<T> {
14
+ signal.throwIfAborted();
15
+ let listener: () => void = () => {};
16
+ const cancelled = new Promise<never>((_, reject) => {
17
+ listener = () => reject(signal.reason);
18
+ signal.addEventListener("abort", listener, { once: true });
19
+ });
20
+ try {
21
+ return await Promise.race([Promise.resolve().then(() => {
22
+ signal.throwIfAborted();
23
+ return action();
24
+ }), cancelled]);
25
+ } finally {
26
+ signal.removeEventListener("abort", listener);
27
+ }
28
+ }
29
+
30
+ export async function readJson(response: Response, signal: AbortSignal): Promise<unknown> {
31
+ const length = response.headers.get("content-length");
32
+ if (length && /^\d+$/.test(length) && Number(length) > MAX_RESPONSE_BYTES) {
33
+ throw new ImageFailure("图片响应超过 32 MiB 上限。");
34
+ }
35
+ if (!response.body) throw new ImageFailure("图片响应为空。");
36
+ const reader = response.body.getReader();
37
+ const chunks: Buffer[] = [];
38
+ let size = 0;
39
+ let complete = false;
40
+ try {
41
+ while (true) {
42
+ const item = await abortable(signal, () => reader.read());
43
+ if (item.done) { complete = true; break; }
44
+ size += item.value.byteLength;
45
+ if (size > MAX_RESPONSE_BYTES) throw new ImageFailure("图片响应超过 32 MiB 上限。");
46
+ chunks.push(Buffer.from(item.value));
47
+ }
48
+ try {
49
+ return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks, size)));
50
+ } catch {
51
+ throw new ImageFailure("图片响应不是有效 JSON。");
52
+ }
53
+ } finally {
54
+ // 不等待可能永不完成的自定义底层 cancel,同时观察其拒绝。
55
+ if (!complete) void reader.cancel().catch(() => {});
56
+ reader.releaseLock();
57
+ }
58
+ }
59
+
60
+ const crcTable = Array.from({ length: 256 }, (_, n) => {
61
+ for (let bit = 0; bit < 8; bit++) n = (n >>> 1) ^ ((n & 1) ? 0xedb88320 : 0);
62
+ return n >>> 0;
63
+ });
64
+
65
+ function validPng(data: string): boolean {
66
+ if (!data.length || data.length % 4 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) return false;
67
+ const bytes = Buffer.from(data, "base64");
68
+ if (bytes.toString("base64") !== data || bytes.length < 57 ||
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;
93
+ }
94
+ return false;
95
+ }
96
+
97
+ export function parseImage(raw: unknown): string {
98
+ if (!record(raw) || !Array.isArray(raw.data) || raw.data.length !== 1 || !record(raw.data[0]) ||
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;
104
+ }
105
+
106
+ function count(value: unknown): value is number {
107
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
108
+ }
109
+
110
+ export function parseUsage(raw: unknown, model: ImageModel<ImageApi>): Usage | undefined {
111
+ if (!record(raw) || !record(raw.usage)) return;
112
+ const usage = raw.usage;
113
+ if (!count(usage.input_tokens) || !count(usage.output_tokens)) return;
114
+ const total = usage.input_tokens + usage.output_tokens;
115
+ if (!count(total) || (usage.total_tokens !== undefined && usage.total_tokens !== total)) return;
116
+ const details = usage.input_tokens_details;
117
+ if (details !== undefined && !record(details)) return;
118
+ const cached = record(details) ? details.cached_tokens : undefined;
119
+ const write = record(details) ? details.cache_write_tokens : undefined;
120
+ if ((cached !== undefined && !count(cached)) || (write !== undefined && !count(write))) return;
121
+ const cacheWrite = write === undefined ? 0 : write as number;
122
+ // 与 Pi 的缓存计数约定一致:cached_tokens 包含 cache_write_tokens。
123
+ const allCached = cached === undefined ? cacheWrite : cached as number;
124
+ if (cacheWrite > allCached || allCached > usage.input_tokens) return;
125
+ const cacheRead = allCached - cacheWrite;
126
+ const input = usage.input_tokens - allCached, output = usage.output_tokens;
127
+ let rates = model.cost;
128
+ let threshold = -1;
129
+ for (const tier of model.cost.tiers ?? []) {
130
+ if (usage.input_tokens > tier.inputTokensAbove && tier.inputTokensAbove > threshold) {
131
+ rates = tier; threshold = tier.inputTokensAbove;
132
+ }
133
+ }
134
+ const cost = {
135
+ input: rates.input / 1e6 * input, output: rates.output / 1e6 * output,
136
+ cacheRead: rates.cacheRead / 1e6 * cacheRead, cacheWrite: rates.cacheWrite / 1e6 * cacheWrite, total: 0,
137
+ };
138
+ cost.total = cost.input + cost.output + cost.cacheRead + cost.cacheWrite;
139
+ if (Object.values(cost).some(value => !Number.isFinite(value) || value < 0)) return;
140
+ return { input, output, cacheRead, cacheWrite, totalTokens: total, cost };
141
+ }
@@ -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 ProviderModelConfig[],
60
+ export function filterModels<T extends { id: string }>(
61
+ models: readonly T[],
62
62
  filter?: ModelFilter,
63
- ): ProviderModelConfig[] {
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"], output: ["image"],
130
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
131
+ }));
132
+ }
@@ -9,7 +9,6 @@ import { join } from "node:path";
9
9
  */
10
10
  export interface TsgwSettings {
11
11
  baseUrl?: string;
12
- mcpUrl?: string;
13
12
  tsSearch?: string;
14
13
  traceHeaders?: boolean;
15
14
  includeModels?: string[];
@@ -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
- ): ReturnType<typeof modelsForRoot> {
113
- const staticModels = modelsForRoot(root);
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: ReturnType<typeof modelsForRoot>;
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.getAvailable()
305
- .filter((model) => model.provider === PROVIDER_ID).length;
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,而非取消/错误元数据。
@@ -8,12 +8,13 @@
8
8
 
9
9
  - Pi 需支持 `ctx.executeTool`(已在 1.1.0 和 1.2.0 上测试)。本包较低的提供商兼容性
10
10
  最低版本不代表承诺在旧宿主上支持上传。
11
- - 插件使用默认公共端点注册 `ts_oht`;可选的 `tsgw.mcpUrl` 可覆盖此端点。
12
- 全局/项目 MCP 文件中的同名条目优先,包括已禁用的条目。Pi 管理连接和 OAuth;
13
- 上传工具仅通过 `reachesTools` 声明其两个上传/URL 依赖。在 Pi 1.2+ 上,宿主可在执行
14
- 父工具前等待这些依赖的 MCP 连接/发现或重连。旧宿主忽略此提示,仍要求工具已经连接。
15
- 隐藏、禁用、被阻止或失败的工具仍不可用;插件不会启用它们、创建自己的连接,
16
- 或读取/修改 MCP 配置。就绪不等于通过认证或获得权限。
11
+ - 插件不自动登记 `ts_oht`。使用上传前,用户需自行在 `~/.pi/agent/mcp.json` 配置
12
+ `ts_oht`(`https://xn--oht.cc/mcp`,`codemode`),示例及 `ts_tool` 配置见根目录
13
+ [README](../../README.md#MCP-服务配置)。Pi 宿主管理连接和 OAuth;上传工具仅通过
14
+ `reachesTools` 声明其两个上传/URL 依赖。在 Pi 1.2+ 上,宿主可在执行父工具前等待这些
15
+ 依赖的 MCP 连接/发现或重连。旧宿主忽略此提示,仍要求工具已经连接。隐藏、禁用、被阻止
16
+ 或失败的工具仍不可用;插件不会启用它们、创建自己的连接,或读取/修改 MCP 配置。
17
+ 就绪不等于通过认证或获得权限。
17
18
  - 要求当前服务的 `mode` / `uploads[]` 协议约定。不支持仅有 `uploadUrl` 的旧协议约定。
18
19
  - 工具使用 Pi 进程的操作系统文件权限,而非沙箱或内置 `read` 工具的路径审批。
19
20
  授权的是**文件外传**,而非仅读取。必要时在权限扩展中管控 `upload_local_file`;
package/index.ts CHANGED
@@ -1,5 +1,4 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
- import { registerTsgwMcp } from "./extensions/mcp.ts";
3
2
  import { registerPrompts } from "./extensions/prompts.ts";
4
3
  import { readTsgwSettings } from "./extensions/provider/config.ts";
5
4
  import { registerTsgwProvider } from "./extensions/provider/index.ts";
@@ -10,6 +9,5 @@ export default async function registerTsgw(pi: ExtensionAPI): Promise<void> {
10
9
  registerUploadTool(pi);
11
10
  registerPrompts(pi);
12
11
  const settings = readTsgwSettings();
13
- registerTsgwMcp(pi, settings.mcpUrl);
14
12
  await registerTsgwProvider(pi, settings);
15
13
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-tsgw",
3
- "version": "0.1.1",
4
- "description": "面向 TOSSP AIH gateway 的 Pi 扩展:按厂商维护模型目录与思考策略,支持 openai-completions、openai-responses、anthropic-messages 和 google-generative-ai 协议。",
3
+ "version": "0.3.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/mcp.test.js && node dist/extensions/mcp-host-integration.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/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",
28
28
  "test:upload:live": "tsc -p tsconfig.test.json && node dist/extensions/upload/live.test.js"
29
29
  },
30
30
  "peerDependencies": {
package/extensions/mcp.ts DELETED
@@ -1,38 +0,0 @@
1
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
-
3
- export const TS_OHT_NAME = "ts_oht";
4
- export const TS_OHT_URL = "https://xn--oht.cc/mcp";
5
- export const TS_TOOL_NAME = "ts_tool";
6
- export const TS_TOOL_URL = "https://mcp.tossp.com/mm/ts/mcp";
7
-
8
- /** 仅设置会话默认值;文件覆盖、连接与 OAuth 由 Pi 管理。 */
9
- export function registerTsgwMcp(pi: ExtensionAPI, configuredUrl?: unknown): void {
10
- if (typeof pi.registerMcpServer !== "function") {
11
- console.error("TSGW:当前 Pi 宿主无法注册 MCP 服务器;已跳过 ts_oht、ts_tool 注册。");
12
- return;
13
- }
14
- const value = configuredUrl === undefined ? TS_OHT_URL : configuredUrl;
15
- let ohtUrl: string | undefined;
16
- try {
17
- if (typeof value !== "string" || value.trim() !== value) throw new Error();
18
- const url = new URL(value);
19
- if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.hash)
20
- throw new Error();
21
- ohtUrl = value;
22
- } catch {
23
- // 显式配置无效时,不得改用其他默认地址连接。
24
- // 常规日志中绝不包含 URL 或解析器错误。
25
- console.error("TSGW:mcpUrl 无效;已跳过 ts_oht 注册。");
26
- }
27
- // 保留精确 URL,因为 Pi 将 OAuth 绑定到服务器名称与 URL 的组合。
28
- // 独立登记:无效的 ts_oht 配置或单个登记失败不得阻止另一个服务和 provider。
29
- for (const [name, url] of [[TS_OHT_NAME, ohtUrl], [TS_TOOL_NAME, TS_TOOL_URL]] as const) {
30
- if (url === undefined) continue;
31
- try {
32
- pi.registerMcpServer(name, { url, exposure: "codemode" });
33
- } catch {
34
- // 不输出可能包含配置或凭据的宿主异常。
35
- console.error(`TSGW:宿主无法登记 ${name};已跳过,请检查 Pi MCP 支持或同名扩展。`);
36
- }
37
- }
38
- }