pi-tsgw 1.0.1 → 1.2.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-tsgw",
3
- "version": "1.0.1",
3
+ "version": "1.2.0",
4
4
  "description": "面向 TOSSP AIH gateway 的 Pi 扩展:按厂商维护聊天与图片模型目录及思考策略,支持四种聊天协议、图片生成与编辑工具,以及原生 System One 分类模型。",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -28,7 +28,7 @@
28
28
  ]
29
29
  },
30
30
  "scripts": {
31
- "test": "tsc -p tsconfig.test.json && node scripts/prepare-test-runtime.mjs && node dist/extensions/provider/index.test.js && node dist/extensions/provider/refresh-tool.test.js && node dist/extensions/provider/startup-catalog.test.js && node dist/extensions/provider/catalog-state.test.js && node dist/extensions/models/gateway-catalog-service.test.js && node dist/extensions/models/gateway-catalog-recovery.test.js && node dist/extensions/provider/catalog-coordinator.test.js && node dist/extensions/provider/catalog-coordination.test.js && node dist/extensions/provider/catalog-recovery.test.js && node dist/extensions/provider/catalog-host.test.js && node dist/extensions/provider/catalog-preemption-host.test.js && node dist/extensions/provider/classifier-host.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/provider/catalog-lifecycle.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/gateway-catalog-policy.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/models/grok-new.test.js && node dist/extensions/models/gemini-new.test.js && node dist/extensions/models/longcat-new.test.js && node dist/extensions/models/capabilities.test.js && node dist/extensions/models/classifier-catalog.test.js && node dist/extensions/models/adapter/classifiers/adapter.test.js && node dist/extensions/models/image-catalog.test.js && node dist/extensions/models/adapter/images/parameters.test.js && node dist/extensions/models/adapter/images/input-budget.test.js && node dist/extensions/models/adapter/images/edit-request.test.js && node dist/extensions/models/adapter/images/image-data.test.js && node dist/extensions/models/adapter/images/response.test.js && node dist/extensions/models/adapter/images/stream-response.test.js && node dist/extensions/models/adapter/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",
31
+ "test": "tsc -p tsconfig.test.json && node scripts/prepare-test-runtime.mjs && node dist/extensions/provider/index.test.js && node dist/extensions/provider/refresh-tool.test.js && node dist/extensions/provider/startup-catalog.test.js && node dist/extensions/provider/catalog-state.test.js && node dist/extensions/models/gateway-catalog-service.test.js && node dist/extensions/models/gateway-catalog-recovery.test.js && node dist/extensions/provider/catalog-coordinator.test.js && node dist/extensions/provider/catalog-coordination.test.js && node dist/extensions/provider/catalog-recovery.test.js && node dist/extensions/provider/catalog-host.test.js && node dist/extensions/provider/catalog-preemption-host.test.js && node dist/extensions/provider/classifier-host.test.js && node dist/extensions/delegation/policy.test.js && node dist/extensions/delegation/index.test.js && node dist/extensions/delegation/host-integration.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/provider/catalog-lifecycle.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/gateway-catalog-policy.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/models/grok-new.test.js && node dist/extensions/models/gemini-new.test.js && node dist/extensions/models/longcat-new.test.js && node dist/extensions/models/capabilities.test.js && node dist/extensions/models/classifier-catalog.test.js && node dist/extensions/models/adapter/classifiers/adapter.test.js && node dist/extensions/models/image-catalog.test.js && node dist/extensions/models/adapter/images/parameters.test.js && node dist/extensions/models/adapter/images/input-budget.test.js && node dist/extensions/models/adapter/images/edit-request.test.js && node dist/extensions/models/adapter/images/image-data.test.js && node dist/extensions/models/adapter/images/response.test.js && node dist/extensions/models/adapter/images/stream-response.test.js && node dist/extensions/models/adapter/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",
32
32
  "test:upload:live": "tsc -p tsconfig.test.json && node scripts/prepare-test-runtime.mjs && node dist/extensions/upload/live.test.js"
33
33
  },
34
34
  "peerDependencies": {
@@ -1,72 +1,24 @@
1
1
  ---
2
2
  name: tsgw-delegate-model-selection
3
- description: 当本技能存在时,应更倾向于把适合委派的任务编排为子代理背景执行。本技能定义编排中的模型与思考深度选择,应尽量遵循;具体任务拆分、并行方式与升级策略由模型结合现场自行判断。
3
+ description: 鼓励将适合的任务派给独立后台子代理。直接调用 Agent 并提供完整任务,TSGW 仅在新建且未指定模型时自动分类选型;不需要阅读选型表或编写分类脚本。
4
4
  license: MIT
5
- compatibility: 需要宿主提供子代理工具及可用的 tsgw 模型。
5
+ compatibility: 自动选型需要 Pi 1.2+、兼容的 model-only Agent 工具,以及可用的 tsgw 分类和聊天模型。
6
6
  ---
7
7
 
8
- # 子代理编排与模型选型
8
+ # 子代理派遣
9
9
 
10
- 当本技能存在时,应更倾向于把适合委派的任务编排为子代理背景执行,并尽量遵循本技能的模型与思考深度定义。具体编排由模型根据任务自行判断。
10
+ 主代理负责拆分任务,提供目标、必要事实、文件路径、约束和验收标准;判断依赖、并行方式、权限和验收。输入未齐备时先查证,不用分类代替授权或依赖验证。
11
11
 
12
- ## 选型参考
12
+ ## 调用
13
13
 
14
- 结合任务、套餐、速度和费用参考下表,同档顺序不是单纯按评分排序;表格不是白名单或固定派遣路线。
14
+ - 新建子代理:直接调用宿主 `Agent`,填写 `prompt`、`description`、适合的 `subagent_type` 和执行选项。没有明确模型要求时省略 `model`;插件在创建前完成一次分类选型并补入模型和思考档位,原 `Agent` 随即执行。
15
+ - 独立任务优先 `run_in_background: true`;前置依赖未完成或存在并发修改冲突时不要假装独立。不要重复派遣已在执行的任务。
16
+ - 用户指定模型、项目固定模型或审阅组合时,直接显式传入 `model`(`provider/modelId:level`),跳过分类。正式架构/设计文档独立审阅默认 `tsgw/gpt-6-astra:max`;固定双模型审阅分别使用 `tsgw/kimi-k3:high` 与 `tsgw/gpt-6-astra:max`,不能把一份双审任务交给一次自动选择。
17
+ - 续接已有会话时传 `resume`,不传新模型;查询结果、补充指令及子代理后续轮次不触发分类,也不运行中换模型。
18
+ - 分类失败、取消、结果未决或选定模型失效时,本次自动创建被阻止。核对任务与取消状态后,可显式选择模型再新建;不反复发起同一自动选型请求,不自动换分类器。
15
19
 
16
- 评分为 AA Intelligence Index v4.3.2 原始分;价格单位为美元/百万 tokens,是 API 参考单价而非套餐扣费;思考深度使用 Pi 档位。
20
+ 选型结果、分类器和已报告用量附在原 `Agent` 的工具结果中。无需编写 codemode 脚本,也不需要先询问分类器再组织第二次 `Agent` 调用。
17
21
 
18
- | 任务等级 | 模型 | 思考深度 | 评分 | 输入价 | 输出价 |
19
- | --- | --- | --- | ---: | ---: | ---: |
20
- | 轻量执行 | `MiniMax-M3` | `high` | 29† | 0.30 | 1.20 |
21
- | 轻量执行 | `gpt-6-luna` | `high` | 33 | 0.10 | 0.50 |
22
- | 通用工程 | `glm-5.3` | `low` | 34 | 1.18 | 4.13 |
23
- | 通用工程 | `glm-5.3` | `high` | 待评 | 1.18 | 4.13 |
24
- | 通用工程 | `glm-5.3` | `max` | 45 | 1.18 | 4.13 |
25
- | 通用工程 | `gpt-6-luna` | `max` | 38 | 0.10 | 0.50 |
26
- | 通用工程(低成本备选) | `glm-5.3-flash` | `max` | 42 | 0.118 | 0.413 |
27
- | 通用工程 | `gpt-6.1-sol` | `medium` | 48 | 2.00 | 10.00 |
28
- | 通用工程(优先候选) | `deepseek-flash` | `high` | 待评‡ | 0.1475–0.295 | 0.59–1.18 |
29
- | 复杂实现(优先候选) | `deepseek-flash` | `max` | 待评‡ | 0.1475–0.295 | 0.59–1.18 |
30
- | 复杂任务 | `gpt-6.1-sol` | `high` | 50 | 2.00 | 10.00 |
31
- | 高难任务 | `gpt-6.1-sol` | `xhigh` | 51 | 2.00 | 10.00 |
32
- | 高难任务 | `gpt-6-astra` | `high` | 51 | 10.00 | 50.00 |
33
- | 高难任务 | `gpt-6-astra` | `xhigh` | 52 | 10.00 | 50.00 |
34
- | 极难任务 | `gpt-6.1-sol` | `max` | 52 | 2.00 | 10.00 |
35
- | 极难任务 | `gpt-6-astra` | `max` | 53 | 10.00 | 50.00 |
36
- | 双模型复核专用 | `kimi-k3` | `high` | 待评 | 3.00 | 15.00 |
22
+ 自动选型不修改任务提示词、档案、后台标志、隔离选项、宿主权限或调度规则。没有兼容宿主工具或低版本 Pi 时不挂接自动选型;需按宿主实际能力显式选择模型,不将技能提示当作已加载运行时代码。
37
23
 
38
- - † MiniMax 的 29 分为模型级参考,Pi high 映射为 adaptive;待评项不借用其他型号或档位的分数。
39
- - ‡ DeepSeek 原有 39 分不作为 1017 更新版的评分;更新版及各档位暂无本表同口径评分。
40
- - GLM 5.3 三型号始终思考,实际 effort 为 low/high/max;Pi medium 映射 high,xhigh 映射 max。FlashX 可作未定档备选,评分待评,输入/输出参考价为 0.295/1.0325。
41
- - `gpt-6.1-sol` 按用户确认的网关 Codex 接入采用 500000 tokens 上下文;最大输出仍为 128000,不与上下文窗口混淆。
42
- - GPT 价格对应输入 ≤272K,超过后输入 ×2、输出 ×1.5;MiniMax 输入超过 512K 为 0.60/2.40。
43
- - DeepSeek 采用国内价(2026-10-16 核验,Blinko #604):输入 1–2 元、输出 4–8 元/百万 tokens,按固定 0.1475 USD/CNY 折算;区间为低谷/高峰价。静态目录采用区间高端,不自动按时段切换;高峰为北京时间工作日(不含中国法定节假日)9–12、14–18。
44
- - GLM 依据 Blinko #929,同样以固定 0.1475 USD/CNY 折算国内人民币标价。其余数值沿用既有选型资料。
45
-
46
- 新增目录候选 `grok-4.7`、`gemini-3.5-flash-lite`、`gemini-3.8-flash-high`、
47
- `longcat-2.5-preview` 暂不进入上表排序:Grok 工具完整往返尚未通过,
48
- LongCat 受上游额度阻塞;两款 Gemini 仅通过最小文本/工具往返,尚无本表同口径评分。
49
- 登记不等于适合长期工程委派,不借用同族评分。
50
-
51
- ## 工程任务选型补充
52
-
53
- 代码修改、缺陷修复、补测试等常规工程任务,优先考虑 `deepseek-flash` / `high`;复杂实现使用 `max`。GLM 5.3 / Flash 仍是工程候选,结合套餐、速度与任务匹配选择,不设固定派遣路线。MiniMax、Luna 保留步骤明确的轻量执行分工。
54
-
55
- 复杂任务选择 `gpt-6.1-sol` 时优先 `high`;仅在任务确需更深推理时考虑 `xhigh` / `max`,不把提高档位当作必然提升。通用工程的 `medium` 仍保留,Astra 与 Kimi 的审阅分工遵循下文。
56
-
57
- 依据与适用范围:
58
-
59
- - [DeepSeek 官方更新日志](https://api-docs.deepseek.com/updates/)(2026-10-17)确认官方 API 的 `deepseek-flash` 已升级为 V4.1 Flash-1017,并报告 DeepSWE v1.1 为 77.0%;该评测使用 Mini-SWE-V2,不是 Pi 子代理实测。
60
- - 用户提供的 DeepSWE v1.1 通过率/每任务费用图用于工程选型参考,与上表 AA 综合能力评分分开,不混用分数,也不将某个代码评测推广为设计审阅能力排名。
61
- - 官方 API 的别名更新不证明网关已经同步;当前未独立确认网关的具体后端版本,不将 77.0% 当作网关实测成绩,不新增猜测的模型 ID。选型模型直接参考本表及这些限制,无需自行查榜或探测版本。
62
- - 图中每任务费用受评测框架、token 用量、定价及汇率影响,不等于本表 token 单价或用户网关实际扣费,也不保证本地任务的通过率与耗时。
63
-
64
- ## 必要边界
65
-
66
- - **MiniMax-M3** 只承担步骤明确的小任务。参考使用 Pi 的 high;非 off 档位均映射为 adaptive,不代表不同能力档。adaptive 不是 Pi 档位,此映射不适用于 M3.1 Flash Preview。
67
- - **deepseek-flash** 常规工程默认 high,复杂实现使用 max;这是选型指导,不自动切换模型、修改用户启用配置或触发付费探测。
68
- - **Astra 审阅档位**:架构设计、正式设计文档的独立审阅与最终复核,默认使用 `gpt-6-astra` / `max`,不因材料篇幅短或范围明确而自动降档。局部检查、定向复审可按范围降低档位。
69
- - **Kimi** 不承担长程执行;双模型复核固定为 **Kimi+Astra**,独立审查同一份材料。Kimi 使用 kimi-k3 / high,Astra 遵循上述审阅档位规则;其他任务的深度按任务选择。
70
- - 不可用的模型或档位如实说明。
71
-
72
- 宿主支持 `Agent.model = provider/modelId:level` 时,例如 `tsgw/MiniMax-M3:high`、`tsgw/glm-5.3:max`;其他宿主使用其实际格式。
24
+ 固定选型知识及维护边界位于插件的 `extensions/delegation/`,由插件维护,不要求执行任务的主模型查榜、探测型号或读取完整参考资料。分类会增加一次请求的延迟与费用;隔离回归不证明选型质量已提升。
@@ -1,79 +0,0 @@
1
- # 图片生成与编辑
2
-
3
- 本目录维护 `tsgw` 的两个直接图片工具、参数 schema 与本地文件处理。工具通过 Pi 模型注册表和供应商认证,调用 `extensions/models/adapter/images/` 的同一套请求/响应实现,不另建凭据解析或 HTTP SDK。
4
-
5
- ## 入口与模型
6
-
7
- - `tsgw_generate_image`:从文字生成图片,只有 `prompt` 必填。
8
- - `tsgw_edit_image`:根据 `prompt` 和 `images` 编辑图片,`mask` 可选且对应第一张参考图。
9
- - 两个工具默认直接向模型声明,不要求启用 codemode;仅 Pi 1.2.0 或更高稳定版登记,旧宿主保持聊天能力,不提高最低 peer。
10
- - 只登记 `gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst` 两款 `type: image` 模型,输入为文本/图片,输出为图片。草稿/速度优先选 Flare,成稿/质量优先选 Sunburst;工具默认 Sunburst,不自动选择另一型号重试。
11
- - 图片目录仍取静态目录与网关目录的交集,再应用 include/exclude。`includeModels: ["gpt-image-2.5*"]` 不能突破交集;图片不进入聊天模型选择器或联网代理候选。
12
-
13
- 工具输入示例及完整可选参数表见随包[图片技能](../../skills/tsgw-image-generation/SKILL.md)。技能用于任务选型与参数使用,不代替实际工具执行;图片目录是否登记由 `extensions/models/capabilities.ts` 的版本门判定。
14
-
15
- ## 请求与参数
16
-
17
- 生成使用 `POST /v1/images/generations`;编辑使用 `POST /v1/images/edits` 的 JSON `images[]` / `mask` 引用形式。不创建上游 Files 对象,不自动改用 multipart 重试。两种请求沿用 provider 的 `baseUrl`,由宿主解析现有 TSGW 认证并传入 `options.apiKey`。
18
-
19
- 默认值是使用便利,不是功能限制:
20
-
21
- - `quality`、`size`、`background`、`moderation` 默认 `auto`;`n` 默认 1,可选 1–10。
22
- - `output_format` 默认 `png`,也支持 `jpeg` / `webp`;JPEG/WebP 可用 `output_compression: 0..100`,省略采用上游默认 100。PNG 不发送压缩参数,透明背景不能配 JPEG。
23
- - `quality` 支持 `auto/low/medium/high/xhigh/max`。尺寸支持 auto 或符合上游边长、像素、16 倍数和宽高比条件的 `宽x高`;超过 3686400 像素为上游实验范围。
24
- - `stream` 默认 false;`partial_images` 默认 0,仅流式时可指定 0–3。流式响应中的过程图不计作额外生成图;当前接口返回最终图片,不承诺 Pi Web 渐进预览。
25
- - `safety_identifier` 默认省略,最多 128 字符;`user` 仅为上游废弃字段兼容保留。不自动采集或生成用户身份。
26
- - `response_format`、`style`、`standard/hd` 是旧模型字段或取值,不混入这两款能力;`input_fidelity` 没有两款 2.5 的明确支持证据,不据共享 schema 自动开放。
27
-
28
- 未知参数、无效取值和冲突组合在请求前报错。`onPayload` 可改变有效参数,序列化后仍核对实际发送内容和端点边界,不允许换模型、把生成悄悄变成编辑或绕过验证。
29
-
30
- ## 原图、蒙版与本地权限
31
-
32
- 每个 `images[]` 或 `mask` 来源必须且只能选择一种:
33
-
34
- - `{ path: "source.png" }`:Pi 主机本地普通文件,相对路径按 `ctx.cwd` 解析;直接读取原始字节,不经内置 `read` 的缩放或转码。
35
- - `{ image_url: "https://…" }`:无用户名密码的 HTTP(S) URL,或 PNG/JPEG/WebP 的 base64 data URI。
36
- - `{ file_id: "file-…" }`:调用方已有的上游图片文件 ID。
37
-
38
- 参考图 1–16 张,保持顺序。蒙版不占参考图张数;可读取的蒙版须有 alpha 通道,并与第一张图的尺寸、格式匹配。
39
-
40
- 本地文件和内联图片每个严格小于 50 MB,参考图与蒙版合计不超过 100 MB;这是插件资源预算,不代表上游最大业务容量。只读普通文件,核对读取前后身份与大小;不修改输入、不转码或丢弃透明通道。URL/file_id 交上游解析,不在插件内下载,无法本地检查的尺寸/蒙版条件由上游验证。
41
-
42
- 文件读取及外传由图片工具整体和宿主工具钩子控制,使用 Pi 进程的操作系统权限,**不等于内置 read 的审批或文件沙箱**。输入引用可能含临时签名,结果和普通错误不复述这些值。
43
-
44
- ## 原生程序化入口
45
-
46
- 原生 `models.generateImages(model, context)` 仍可用,只有两个参数。`context.tsgw` 是本插件增加的供应商参数,不是 Pi 通用 ImagesContext 的标准字段;TypeScript 调用方可使用 `TsgwImagesContext` 类型。
47
-
48
- ```js
49
- // @options: {"timeout_ms": 660000}
50
- const model = await models.getModelOfType("image", "tsgw", "gpt-image-2.5-sunburst");
51
- const result = await models.generateImages(model, {
52
- input: [{ type: "text", text: "横版水墨山水,远山薄雾,一叶扁舟,不要文字" }],
53
- tsgw: { quality: "high", size: "1536x1024", output_format: "webp", output_compression: 85 },
54
- });
55
- if (result.stopReason !== "stop") throw new Error(result.errorMessage);
56
- for (const block of result.output) if (block.type === "image") image(block);
57
- ```
58
-
59
- 原生 `input` 的图片块用于参考图编辑,也可使用 `tsgw.images` 的上游引用;两者不能同时提供。显式 `tsgw.operation` 为 `generate` / `edit`,省略时按是否有参考图决定;工具始终明确指定操作。蒙版通过 `tsgw.mask` 提供。原生调用不直接读取本地 path,读取原文件由工具层负责。
60
-
61
- codemode 原生桥接不传第三参数,不会通过修改 model 对象转发参数。宿主 SDK 的 `ctx.modelRegistry.generateImages()` 仍可在 options 中传 `timeoutMs`、signal 和钩子。
62
-
63
- ## 超时、输出与用量
64
-
65
- 请求默认 600000ms,可通过工具的 `timeout_ms` 或 SDK 的 `options.timeoutMs` 显式缩短或延长,最大不超过 Node timer 范围。codemode 包装脚本应留余量,例如默认请求配 660000ms;它不是请求超时参数。取消、超时或失败都不自动重试或改用其他模型,也不保证上游停止处理或计费。
66
-
67
- 成功结果包含实际图片块和原始文件临时路径。原始文件以唯一临时目录、排他创建写入,不覆盖用户文件;保存失败保留上游用量及可用图片,明确区别“生成成功但保存失败”。预览进入会话后可能由宿主缩放/转码;后续精确编辑应使用保存的原始文件。
68
-
69
- 响应读取有界:普通 JSON 按每张 32 MiB 预算扩展,流式按单事件 32 MiB 及总流预算控制。返回图片单边不超过 3840,总像素不超过 8294400。PNG/JPEG/WebP 校验容器、必要头、尺寸等;PNG 保留 CRC 验证,不声称完整解码压缩像素流。JPEG 接受常见 Huffman 顺序/渐进编码,WebP 不接受动画容器。
70
-
71
- usage 仅取上游报告的有效 tokens;坏图、断流等失败路径仍尽量保留已报告用量。多图 SSE 的逐事件用量是否共享、累计或重复汇总尚无明确契约,工具以 `usage_reports` 保留有效报告并标注 `usage_note`,不相加、不当作请求总量计入会话,也不因计量不明而丢弃有效图片;原生结果以 `tsgwUsage` 携带此扩展信息。图片价格 0 表示未映射准确价格,不表示免费。模型登记、参数注入和合成 SDK 测试都不等于真实端点、全部组合或 UI 行为验收。
72
-
73
- ## 维护与验证
74
-
75
- - 本目录只承担图片工具与文件处理:`tools.ts` / `tool-schema.ts` / `tool-files.ts` 与对应 `tools.test.ts` / `tool-files.test.ts` / `tools-host.test.ts` / `host-integration.test.ts`。
76
- - 图片协议实现位于 `extensions/models/adapter/images/`:`adapter.ts`(宿主凭据、HTTP、钩子与取消/超时)、`parameters.ts` / `request.ts`(参数、引用、生成/编辑请求及序列化)、`response.ts` / `image-data.ts` / `stream-response.ts`(用量、格式校验、普通/流式响应)及对应单测;共享原图夹具 `image-fixtures.test.ts` 随协议层迁移,工具层继续跨目录复用而不复制数据。
77
- - `extensions/models/capabilities.ts` 提供纯版本判断,由根入口和 provider 决定图片工具、模型与适配器是否登记;它不读 `VERSION` 全局,不将模块加载与能力登记混为一谈。
78
-
79
- 接口与模型证据见记忆系统 942;用户确认网关编辑端点兼容,不替代本插件新组合的独立验收。测试不读取个人配置或请求真实网关,真实推理另需授权。
@@ -1,128 +0,0 @@
1
- # 本地文件上传
2
-
3
- `upload_local_file` 是一个本地 Pi 工具。它编排宿主现有的 `ts_oht.upload_file` 和
4
- `ts_oht.get_file_url` MCP 工具,然后将原始字节以流式方式直接传输到返回的 S3 目标。
5
- 不会引入新的 MCP 服务器/客户端、S3 SDK、运行时依赖、MCP 密钥存储或 S3 凭据。
6
-
7
- ## 要求与授权
8
-
9
- - Pi 需支持 `ctx.executeTool`(已在 1.1.0 和 1.2.0 上测试)。本包较低的提供商兼容性
10
- 最低版本不代表承诺在旧宿主上支持上传。
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
- 就绪不等于通过认证或获得权限。
18
- - 要求当前服务的 `mode` / `uploads[]` 协议约定。不支持仅有 `uploadUrl` 的旧协议约定。
19
- - 工具使用 Pi 进程的操作系统文件权限,而非沙箱或内置 `read` 工具的路径审批。
20
- 授权的是**文件外传**,而非仅读取。必要时在权限扩展中管控 `upload_local_file`;
21
- 外层工具和嵌套 MCP 调用都会经过宿主权限钩子。
22
- - 路径属于插件所在的机器/容器,不一定是浏览器所在的计算机。相对路径以会话 cwd 为基准;
23
- `~/` 展开为宿主的主目录。符号链接解析为其规范路径对应的普通文件;
24
- 目录/设备/FIFO 会被拒绝。不存在隐式的仅限 cwd 白名单。
25
- - 服务器声明规划/完成操作的时限为 300 秒。必要时将宿主 MCP 超时配置为至少 330 秒。
26
- 插件无法逐次调用覆盖该配置,也绝不编辑用户设置。宿主默认值可能更早结束调用。
27
- 本地 330 秒 MCP 截止时限约束的是嵌套 MCP 等待,不约束远端工作或宿主执行前的就绪等待。
28
- 在 Pi 1.2 的隔离空闲 `ctx.executeTool` 测试中,取消不会立即结束就绪等待;
29
- 发现完成后,宿主会阻止已取消的父工具执行。不要将取消理解为远端任务已取消。
30
-
31
- ## 工具接口
32
-
33
- ```ts
34
- upload_local_file({
35
- path: string,
36
- contentType?: string,
37
- expiresIn?: number, // 整数,范围 1–604800;默认 86400
38
- disposition?: "inline" | "attachment", // 默认 inline
39
- resume?: string // 失败调用返回的原样恢复凭条
40
- })
41
- ```
42
-
43
- `contentType` 不得包含 charset 或其他参数。默认值尽力根据扩展名映射,无法匹配时
44
- 回退到 `application/octet-stream`;这不是内容嗅探。程序读取真实大小和时间戳,
45
- 绝不从模型提供的参数中获取这些值。文件名必须满足服务的 UTF-8 名称限制。
46
- 结构约束(schema)与 MIME 语法/长度以及恢复凭条的 base64url 字符集/长度保持一致;
47
- 运行时验证仍会检查凭条内容、文件身份和远端协议。
48
-
49
- Pi 在规范化/强制类型转换后验证工具参数。在 Pi 1.1/1.2 宿主集成测试中,
50
- `expiresIn: "3600"` 变为 `3600`,`expiresIn: 1.5` 变为 `1`,可选的 `null` 字段会被移除。
51
- 直接调用业务逻辑会拒绝非整数有效期,但无法拒绝已被宿主转换的原始小数。
52
- 结构约束并不保证对原始输入进行严格验证。
53
-
54
- - 1 字节至 32 MiB:读取有界快照,并发送一次原始 PUT。
55
- - 超过 32 MiB、直至服务当前 5 TiB 安全上限:最多使用 **3 个并发工作单元**流式传输返回的
56
- 分片范围,不会将整个文件或整个大分片缓存在内存中。后端可能施加更低限制;
57
- 这个极限大小是协议边界,不表示端点一定接受或具备相应性能。
58
- - 验证模式、key/uid、分片布局、分片编号唯一性、大小、HTTP 方法、请求头和有效期。
59
- 仅剩一个分片的计划仍属于分片上传。
60
- - 不跟随重定向,不自动重试 PUT。目标必须使用端口 443 上的公共 HTTPS。
61
- 每次 PUT 都会检查并固定 DNS 地址;拒绝私有/本地目标、凭据类/逐跳请求头及非 PUT 方法。
62
- 下载与上传目标必须同源。
63
- - 所有分片 PUT 完成后,使用相同元数据调用 `upload_file` **一次**,核对状态并完成上传。
64
- 只有服务返回的 `uploaded:true` 才算分片对象已完成。不使用自动完成循环。
65
- - 默认请求会复用服务提供的 24 小时 inline URL,前提是它仍有效。
66
- attachment/自定义有效期(或默认链接已过期)仅在上传成功后通过 `get_file_url` 签名。
67
-
68
- 预签名 PUT 的截止时限同时受签名有效期和按大小确定的总超时约束。用户取消会停止本地 PUT,
69
- 并等待所有工作单元结束后才释放文件/锁。取消 MCP **不保证**服务端工作被取消。
70
- 插件不重试 MCP 调用;宿主传输层可以独立重连/重新认证。
71
-
72
- ## 失败与显式恢复
73
-
74
- 结果包含 `uploaded`(`true`、`false`,或结果未知时的 `null`)、`uploadStatus`、
75
- `phase`、`linkStatus` 和安全的错误信息。绝不能仅因收到 key 或签名 URL 就认定上传已完成。
76
-
77
- | 情况 | 结果 / 恢复方式 |
78
- | --- | --- |
79
- | 输入无效、文件缺失或 MCP 不可用 | 报错;不自动连接、不改用其他认证方式、不重试 |
80
- | 分片失败、超时或取消 | 停止该批次;已知时保留 `key`、`uid` 和 `resume`;不自动重新签名或重试 |
81
- | 完成响应丢失 | 结果未知,而非失败;显式恢复时先检查原有 key |
82
- | 上传成功但链接签名失败 | `uploaded:true`、`linkStatus:failed`;保留 key 和 resume;仍有效的默认链接标记为 `fallback`,而非所请求的链接 |
83
- | 单次 PUT 结果未知 | 恢复时仅检查旧 key;绝不重复 PUT 或请求新对象 |
84
-
85
- 恢复时,使用返回的 `resume` 凭条、原始路径和所需链接选项再次调用同一工具。
86
- 凭条包含元数据/身份信息和对象 key,**不含 URL、凭据或文件内容**。
87
- 它是不透明的恢复记录,不是认证令牌。不要编辑它,也不要丢弃它后盲目重新上传。
88
-
89
- 恢复时首先为旧 key 调用 `get_file_url`。若对象存在,则直接返回链接,不读取/重新上传文件
90
- (即使本地文件之后已被删除也可用)。只有远端明确返回 `not-found`,才允许继续未完成的
91
- 分片上传。其他错误会使结果保持未知。已完成上传的对象若被删除,不会重新创建。
92
-
93
- 分片恢复要求文件的规范路径、设备/inode、大小、mtime、ctime 和内容类型仍然一致。
94
- 服务按原始元数据重新规划,仅返回缺失的分片。客户端要求 **key 和 uid 均与原先相同**,
95
- 才会发送字节。如果服务已不再保留旧任务,可能在此次查询中创建不同的计划;
96
- 客户端会拒绝该计划且不上传字节,并由服务器现有清理机制处理它。
97
- 服务端没有按 uid 恢复的端点,因此无法避免此规划副作用。
98
-
99
- 工具在流式传输各范围前后以及完成上传前检查文件身份和时间戳。这能检测常规修改,
100
- 但不能防范恶意时间戳伪造;对可变的大文件而言,它不构成内容哈希或快照保证。
101
- 不要修改正在上传的文件。源文件变化会阻止完成操作;客户端绝不会自行删除或中止对象/任务。
102
- 服务端清理机制仍可能独立核对并处理已上传的分片。
103
-
104
- 进程内元数据锁防止通过此模块发起的调用相互重叠,包括已超时的宿主调用仍在收尾期间。
105
- 它**不是**跨进程/客户端锁。恢复前请停止其他客户端,并等待尚未结束的 PUT 完成。
106
- 服务器在所有获授权客户端之间共享存储桶访问权限;不存在按用户隔离对象的机制。
107
-
108
- ## 链接、存储与验证
109
-
110
- 下载 URL 是临时持有者凭据。任何持有链接的人都能访问对象。工具结果会有意包含所请求的链接,
111
- 但插件绝不记录签名 URL、请求头、原始 MCP 结果或网络错误,也绝不将恢复状态持久化到磁盘。
112
- 宿主会话记录和受信任的工具钩子可以看到工具结果;处理/导出时请据此采取措施。
113
- `inline` 可在存储域名下执行 HTML 等活动内容;必要时使用 `attachment`。
114
-
115
- 私有临时存储桶中的对象会在约七天后清理。重新签名 URL 不会延长对象保留时间;
116
- 对象删除/凭据过期可能导致链接早于其标示的有效期失效。
117
-
118
- 自动化测试分别检查原始结构约束、真实宿主的输入规范化,以及实际成功/失败/恢复输出是否符合结构约束。
119
- 就绪测试延迟真实的 JSON-RPC 发现响应,覆盖冷启动、重连、连接失败、已禁用服务器和取消。
120
- 测试使用合成文件以及隔离的宿主/MCP 测试环境;绝不使用个人配置或生产网关。
121
- 真实端点验证必须获得明确授权,并与模拟宿主测试分开报告。
122
-
123
- 获得授权后,`TSGW_UPLOAD_LIVE=1 npm run test:upload:live` 会运行真实 Pi SDK,
124
- 使用宿主现有的 `ts_oht` 配置/认证和本地测试模型(不发送推理请求)。
125
- 它创建两个小文件和一个 33 MiB 的分片对象,验证下载内容的 SHA-256、inline/attachment
126
- 和自定义有效期,中断一个分片批次,并在显式恢复前模拟完成响应丢失。
127
- 它不修改客户端/服务器配置,也不删除远端对象;由现有服务器保留策略清理它们。
128
- 本地测试文件和内存中的会话状态会被丢弃。不打印任何签名链接。