pi-tsgw 0.0.13 → 0.0.16

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,42 +1,38 @@
1
1
  # pi-tsgw
2
2
 
3
- Pi extension for the TOSSP AIH gateway. Registers the `tsgw` provider with a
4
- model catalog spanning four wire protocols (openai-completions,
5
- openai-responses, anthropic-messages, google-generative-ai) and applies
6
- per-vendor request-body operations so thinking levels, reasoning formats, and
7
- optional built-in web search behave correctly on the gateway.
3
+ 面向 TOSSP AIH gateway 的 Pi 扩展。注册 `tsgw` 提供商,其模型目录涵盖四种通信协议
4
+ (openai-completions、openai-responses、anthropic-messages、google-generative-ai),
5
+ 并按厂商对请求体执行相应操作,使思考级别、推理格式和可选的内置网络搜索在网关上正常工作。
8
6
 
9
- No private API keys or gateway endpoints are included. The static catalog
10
- contains model metadata and public-price estimates; these are not your gateway's
11
- billing rates.
7
+ 本项目不包含私有 API 密钥或网关端点。静态目录包含模型元数据和公开价格估算;
8
+ 这些价格并非你的网关计费费率。
12
9
 
13
- ## Install
10
+ ## 安装
14
11
 
15
12
  ```bash
16
13
  pi install git:github.com/tossp/pi-tsgw
17
14
  ```
18
15
 
19
- or, for npm:
16
+ 或通过 npm 安装:
20
17
 
21
18
  ```bash
22
19
  pi install npm:pi-tsgw
23
20
  ```
24
21
 
25
- Then `/reload` (or restart pi). The provider appears as `tsgw` in the model
26
- picker.
22
+ 然后执行 `/reload`(或重启 pi)。模型选择器中会出现 `tsgw` 提供商。
27
23
 
28
- ## Configuration
24
+ ## 配置
29
25
 
30
- All configuration lives in the `tsgw` namespace of `~/.pi/agent/settings.json`.
31
- The plugin reads no environment variables; only Pi's own credential
32
- resolution handles API keys.
26
+ 所有配置均位于 `~/.pi/agent/settings.json` 的 `tsgw` 命名空间下。
27
+ 插件不读取环境变量;API 密钥仅由 Pi 自身的凭据解析机制处理。
33
28
 
34
- Example:
29
+ 示例:
35
30
 
36
31
  ```json
37
32
  {
38
33
  "tsgw": {
39
34
  "baseUrl": "https://aih.example.net",
35
+ "mcpUrl": "https://xn--oht.cc/mcp",
40
36
  "tsSearch": "live",
41
37
  "traceHeaders": false,
42
38
  "excludeModels": ["gpt-*", "claude-*"],
@@ -45,141 +41,177 @@ Example:
45
41
  }
46
42
  ```
47
43
 
48
- ### Gateway address
44
+ ### 网关地址
49
45
 
50
- `baseUrl` points at your AIH gateway (any instance — the public one or a
51
- self-hosted one). The `/v1` suffix is normalized away. If unset, a neutral
52
- placeholder root is used that will not work.
46
+ `baseUrl` 指向你的 AIH 网关(可以是公共实例或自托管实例)。规范化时会去掉 `/v1` 后缀。
47
+ 未设置时使用一个中性的占位根地址,该地址无法实际使用。
53
48
 
54
- ### API key
49
+ ### API 密钥
55
50
 
56
- The extension delegates credential reading and resolution to Pi:
51
+ 扩展将凭据读取和解析交由 Pi 处理:
57
52
 
58
- 1. **`/login`** — select the `tsgw` provider and enter the key; pi stores it
59
- in `~/.pi/agent/auth.json` (preferred)
60
- 2. **`TSGW_API_KEY`** environment variable — Pi's fallback when nothing is
61
- stored
53
+ 1. **`/login`** — 选择 `tsgw` 提供商并输入密钥;pi 将其存储在
54
+ `~/.pi/agent/auth.json` 中(推荐方式)。
55
+ 2. **`TSGW_API_KEY` 环境变量** — 未存储凭据时由 Pi 回退使用。
62
56
 
63
- Startup discovery uses Pi's stored-credential API; later catalog refreshes use
64
- the credential supplied by Pi. With environment-only authentication, the initial
65
- catalog may fall back to static models until Pi refreshes it.
57
+ 启动时的发现使用 Pi 的已存储凭据 API;后续目录刷新使用 Pi 提供的凭据。
58
+ 如果仅通过环境变量认证,初始目录可能回退到静态模型,直到 Pi 刷新目录。
66
59
 
67
- ### Options
60
+ ### 选项
68
61
 
69
- | Setting (`settings.json` `tsgw.*`) | Default | Meaning |
62
+ | 设置(`settings.json` 中的 `tsgw.*`) | 默认值 | 含义 |
70
63
  | --- | --- | --- |
71
- | `baseUrl` | placeholder | Gateway root (the `/v1` suffix is normalized away) |
72
- | `tsSearch` | `live` | GPT: `cached` or `live`; unset, legacy `off`, and invalid values fall back to `live`. Supported Grok models always use live search. |
73
- | `traceHeaders` | `false` | Adds `AH-Thread-Id` / `AH-Trace-Id` headers for gateway-side tracing |
74
- | `includeModels` | unset | Re-include override: matching model ids are kept even when also matched by `excludeModels` (exact id or `prefix-*` glob) |
75
- | `excludeModels` | unset | Blacklist: matching model ids are dropped unless pulled back by `includeModels` (exact id or `prefix-*` glob) |
76
-
77
- ## Model catalog
78
-
79
- The catalog is assembled from per-vendor slices (`extensions/models/vendors/`),
80
- covering 11 vendor families: DeepSeek, GLM (Zhipu), MiMo (Xiaomi), MiniMax,
81
- Kimi (Moonshot), Qwen (Alibaba), GPT (OpenAI), Gemini (Google), Claude
82
- (Anthropic), LongCat, and Grok (xAI). The current static catalog contains 36 chat
83
- model IDs, including retained aliases; this is not a live availability count.
84
- Vendor files carry documentation links and metadata caveats. Alias mappings,
85
- output limits, and shared thinking policies are not all individually verified
86
- against gateway endpoints; public-price estimates do not guarantee billing.
87
- MiMo uses `mimo-v2.6-pro` and `mimo-v2.6-flash`; the former V2.5 IDs are not
88
- registered. Update any explicit model selections or filter rules to the new IDs.
89
-
90
- The curated catalog keeps DeepSeek `deepseek-flash` and V4 Pro; GLM 5.2+,
91
- plus the explicit `glm-4.5-air` exception; MiniMax M3+; Kimi K3; GPT 6+;
92
- and Gemini 3.5+ plus the unversioned `gemini-flash` / `gemini-pro` aliases.
93
- Qwen, MiMo, LongCat, Claude, and Grok retain their existing registrations.
94
- Removed IDs and their dedicated request policies are no longer registered;
95
- include rules cannot restore them, even if a gateway still lists them. Existing
96
- explicit model selections referencing removed IDs need to be updated.
97
-
98
- Kimi offers `kimi-k3` and the gateway variant `kimi-k3-256k`, displayed as
99
- **Kimi K3 (256K)** with a 262,144-token context window. Its other metadata,
100
- price estimates, and thinking policy are inherited from K3; the 131,072-token
101
- output setting is separate from context size. These inherited values are not
102
- individual endpoint verification or a guarantee of the variant's billing rates.
103
-
104
- The catalog also includes `MiniMax-M3.1-Flash-Preview`, `glm-5.3`,
105
- `glm-5.3-flash`, and `glm-5.3-flashx`. All four require thinking: MiniMax
106
- uses low/medium/high/xhigh/max; GLM uses low/high/max. Unsupported `off` is
107
- disabled in model metadata, and stale off/minimal requests map to low rather
108
- than silently selecting the default max. MiniMax and GLM Flash/FlashX support
109
- image input; GLM 5.3 is text-only. Registration does not prove gateway
110
- inference or tool-call support.
111
-
112
- As checked on 2026-10-16, MiniMax publishes subscription access but no per-token
113
- price for M3.1 Flash Preview. Its zero cost fields mean **unknown**, not free,
114
- and usage cost totals therefore omit its actual charges. GLM 5.3 price estimates
115
- use domestic public rates and the existing fixed USD/CNY conversion; temporary
116
- free cache storage is recorded as zero, not a permanent billing guarantee.
117
-
118
- Use broad `excludeModels` rules to drop model families and precise
119
- `includeModels` rules to pull selected models back. `includeModels` is not a
120
- global whitelist: models matching neither list remain available. To register
121
- only selected models, use `"excludeModels": ["*"]` and pull them back through
122
- `includeModels`. Both lists are case-sensitive and support only exact IDs or
123
- trailing `*` prefix matching (not general globs); preserve `MiniMax-*` casing.
124
- When a gateway catalog is available, filtering applies after intersecting it
125
- with the static catalog. Include rules cannot add unknown or unavailable IDs.
126
-
127
- Opening `/model` refreshes the gateway catalog in the background, with a
128
- five-minute cache to avoid repeated requests. Run `/tsgw-refresh` to bypass the
129
- cache and force an immediate refresh without restarting or reloading Pi. If a
130
- refresh fails, the last successful model list remains active.
131
-
132
- Memory and disk caches are scoped to the gateway root and credential using a
133
- SHA-256 digest; plaintext credentials are not stored. The disk cache is a single
134
- slot at `<agent-dir>/tsgw/models-cache.json`: changing scope may require a fresh
135
- fetch. Legacy unscoped cache files are ignored and replaced after a successful
136
- fetch. In-process request ordering prevents late results from replacing newer
137
- cache writes; this is not a cross-process locking mechanism.
138
-
139
- ## Status bar and session controls
140
-
141
- Pi Web clients supporting `command:/…` statuses render these as clickable
142
- buttons; the terminal CLI displays status text and accepts the same commands:
143
-
144
- - **`TSGW · N`** (`/tsgw`): one menu for **refreshing the model catalog** and
145
- **viewing diagnostics**. The count is the filtered registered catalog, not a
146
- count of healthy inference endpoints. 🟢 means a fresh directory result;
147
- 🟡 means a static/expired directory or a failed refresh; ⚠️ means missing
148
- credentials or gateway configuration; ⏳ means a refresh is running.
149
- - **Built-in search** (`/tsgw-search`): GPT offers only `cached / live`
150
- for the current session, defaulting to `live`. Supported Grok models use
151
- fixed live search: the command only shows a notice, without a picker or
152
- changing the GPT session mode. Unsupported TSGW models are labeled
153
- accordingly; this button is hidden when another provider is selected.
154
-
155
- For GPT, you can also type `/tsgw-search cached` or `/tsgw-search live`;
156
- `off` is no longer accepted. These controls do not modify `settings.json` or
157
- persist across a reload or a new session; `tsgw.tsSearch` remains the startup
158
- default. Existing `cached` configuration is preserved; unset, legacy `off`,
159
- and invalid configuration now default to `live`.
160
-
161
- Injection remains limited to the existing model/protocol support list. GPT
162
- Responses appends a `web_search` tool (`external_web_access` is false for
163
- `cached`, true for `live`); Grok Completions appends
164
- `search_parameters: { mode: "on" }`. Existing search tools/fields are never
165
- overwritten. This setting does not control Qwen's vendor policy, external
166
- tools, or thinking mode and is not a global network-access switch.
167
-
168
- The standalone `ts_search` tool is no longer bundled. Use a separately configured
169
- search tool such as `ts_oht.search` instead. Built-in model search remains
170
- available and does not control external search tools.
171
-
172
- Diagnostics show directory source, original fetch time, cache freshness,
173
- configuration presence, and safe refresh error summaries—never API keys or
174
- URLs. They make no extra network requests. Statuses update on session/model
175
- activity and directory refreshes; there is no background health polling.
176
-
177
- Icons use Emoji/Unicode: Pi Web currently strips ANSI colors from command
178
- buttons. Busy sessions disable the buttons. The terminal CLI shows the same
179
- statuses as text; use the slash commands there. Pi Web may not show extension
180
- statuses until the session runtime has started.
181
-
182
- ## Development
64
+ | `baseUrl` | 占位地址 | 网关根地址(规范化时去掉 `/v1` 后缀) |
65
+ | `mcpUrl` | `https://xn--oht.cc/mcp` | 可选的 `ts_oht` HTTP(S) 端点覆盖值;独立于模型网关 |
66
+ | `tsSearch` | `live` | GPT:`cached` 或 `live`;未设置、旧值 `off` 和无效值均回退到 `live`。受支持的 Grok 模型始终使用实时搜索。 |
67
+ | `traceHeaders` | `false` | 添加 `AH-Thread-Id` / `AH-Trace-Id` 请求头,用于网关侧追踪 |
68
+ | `includeModels` | 未设置 | 重新纳入的覆盖规则:匹配的模型 ID 即使也被 `excludeModels` 匹配,仍会保留(精确 ID 或 `prefix-*` 通配模式) |
69
+ | `excludeModels` | 未设置 | 黑名单:匹配的模型 ID 会被移除,除非通过 `includeModels` 重新纳入(精确 ID 或 `prefix-*` 通配模式) |
70
+
71
+ ## 模型目录
72
+
73
+ 目录由各厂商的分片(`extensions/models/vendors/`)组装而成,涵盖 11 个厂商系列:
74
+ DeepSeek、GLM(智谱)、MiMo(小米)、MiniMax、Kimi(Moonshot)、Qwen(阿里巴巴)、
75
+ GPT(OpenAI)、Gemini(Google)、Claude(Anthropic)、LongCat 和 Grok(xAI)。
76
+ 当前静态目录包含 36 个聊天模型 ID(含保留的别名);这不是实时可用模型数量。
77
+ 厂商文件包含文档链接和元数据注意事项。别名映射、输出限制和共享思考策略并未全部
78
+ 针对网关端点逐项验证;公开价格估算不构成计费保证。
79
+ MiMo 使用 `mimo-v2.6-pro` 和 `mimo-v2.6-flash`;不再注册原有 V2.5 ID。
80
+ 请将显式模型选择或过滤规则更新为新 ID。
81
+
82
+ 精选目录保留 DeepSeek `deepseek-flash` 和 V4 Pro;GLM 5.2+,以及明确例外
83
+ `glm-4.5-air`;MiniMax M3+;Kimi K3;GPT 6+;以及 Gemini 3.5+ 和无版本号的
84
+ `gemini-flash` / `gemini-pro` 别名。Qwen、MiMo、LongCat、Claude 和 Grok 保留现有注册。
85
+ 已移除的 ID 及其专用请求策略不再注册;即使网关仍列出这些 ID,纳入规则也无法恢复它们。
86
+ 现有显式模型选择若引用了已移除的 ID,需要更新。
87
+
88
+ Kimi 提供 `kimi-k3` 和网关变体 `kimi-k3-256k`,后者显示为
89
+ **Kimi K3 (256K)**,上下文窗口为 262,144 个 token。其余元数据、价格估算和思考策略
90
+ 继承自 K3;131,072 个 token 的输出设置与上下文大小彼此独立。
91
+ 这些继承值不代表已逐项验证该端点,也不保证该变体的计费费率。
92
+
93
+ 目录还包含 `MiniMax-M3.1-Flash-Preview`、`glm-5.3`、`glm-5.3-flash` 和
94
+ `glm-5.3-flashx`。这四个模型都要求启用思考:MiniMax 使用 low/medium/high/xhigh/max;
95
+ GLM 使用 low/high/max。模型元数据中禁用了不受支持的 `off`,过时的 off/minimal 请求
96
+ 会映射到 low,而不是静默选择默认的 max。MiniMax 和 GLM Flash/FlashX 支持图像输入;
97
+ GLM 5.3 仅支持文本。注册并不证明网关支持推理或工具调用。
98
+
99
+ 截至 2026-10-16 的核查,MiniMax 已公布 M3.1 Flash Preview 的订阅访问方式,
100
+ 但未公布按 token 计费的价格。其费用字段为零表示**未知**,而非免费,因此用量费用总计
101
+ 会遗漏其实际收费。GLM 5.3 的价格估算使用国内公开费率和现有的固定 USD/CNY 换算率;
102
+ 临时免费的缓存存储记为零,不代表永久计费保证。
103
+
104
+ 使用宽泛的 `excludeModels` 规则排除模型系列,再用精确的 `includeModels` 规则
105
+ 重新纳入指定模型。`includeModels` 不是全局白名单:两个列表都未匹配的模型仍然可用。
106
+ 若只想注册指定模型,使用 `"excludeModels": ["*"]`,再通过 `includeModels` 重新纳入。
107
+ 两个列表均区分大小写,仅支持精确 ID 或末尾 `*` 前缀匹配(不支持通用通配模式);
108
+ 请保留 `MiniMax-*` 的大小写。网关目录可用时,先与静态目录取交集,再应用过滤。
109
+ 纳入规则无法添加未知或不可用的 ID。
110
+
111
+ 打开 `/model` 会在后台刷新网关目录,并使用五分钟缓存避免重复请求。
112
+ 运行 `/tsgw-refresh` 可绕过缓存立即强制刷新,无需重启或重新加载 Pi。
113
+ 刷新失败时,继续使用最近一次成功获取的模型列表。
114
+
115
+ 内存和磁盘缓存通过 SHA-256 摘要限定在网关根地址与凭据对应的作用域内;不存储明文凭据。
116
+ 磁盘缓存仅有一个槽位,位于 `<agent-dir>/tsgw/models-cache.json`:改变作用域可能需要
117
+ 重新获取。旧版无作用域缓存文件会被忽略,并在获取成功后替换。
118
+ 进程内请求排序可防止较晚返回的结果覆盖更新的缓存写入;这不是跨进程锁机制。
119
+
120
+ ## 状态栏与会话控制
121
+
122
+ 支持 `command:/…` 状态的 Pi Web 客户端会将其渲染为可点击按钮;终端 CLI 显示状态文本,
123
+ 并接受相同命令:
124
+
125
+ - **`TSGW · N`**(`/tsgw`):在同一菜单中**刷新模型目录**和**查看诊断信息**。
126
+ 数量表示过滤后已注册的目录条目数,而非健康推理端点的数量。
127
+ 🟢 表示新鲜的目录结果;🟡 表示静态/过期目录或刷新失败;⚠️ 表示缺少凭据或网关配置;
128
+ ⏳ 表示正在刷新。
129
+ - **内置联网**(`/tsgw-search`):GPT 仅为当前会话提供 `cached / live`,默认为 `live`。
130
+ 受支持的 Grok 模型固定使用实时搜索:此命令只显示提示,不提供选择器,也不改变 GPT
131
+ 的会话模式。其他 TSGW 模型通过 `tsgw_search` 使用**委托搜索**,前提是有效目录中
132
+ 仍有支持搜索的模型。状态显示 `代理`(live)或 `代理缓存`(cached);对其他提供商隐藏。
133
+
134
+ 对于原生 GPT 或 GPT 委托模型,输入 `/tsgw-search cached` 或 `/tsgw-search live`;
135
+ 不再接受 `off`。这些控制不会修改 `settings.json`,也不会在重新加载或新会话后保留;
136
+ `tsgw.tsSearch` 仍是启动默认值。现有 `cached` 配置会保留;未设置、旧值 `off` 和
137
+ 无效配置现在均默认使用 `live`。
138
+
139
+ 注入仍仅限于现有的模型/协议支持列表。GPT Responses 追加一个 `web_search` 工具
140
+ (`cached` 时 `external_web_access` 为 false,`live` 时为 true);Grok Completions
141
+ 追加 `search_parameters: { mode: "on" }`。绝不覆盖现有搜索工具/字段。
142
+ 此设置不控制 Qwen 的厂商策略、外部工具或思考模式,也不是全局网络访问开关。
143
+
144
+ 当当前 TSGW 模型缺少原生搜索能力时,插件会启用 `tsgw_search`:当前模型用搜索问题
145
+ 调用它,由支持搜索的模型执行内置网络搜索,再将答案/来源返回当前模型。
146
+ 对话模型不会改变。仅发送问题,不发送会话历史或本地工具。原生搜索模型不暴露此代理工具。
147
+
148
+ 委托模型从过滤后的有效目录中选择,优先顺序为 **GPT 6 Luna**,其次是 GPT 6 Sol、
149
+ GPT 6.1 Sol、GPT 6 Astra,然后是受支持的 Grok 模型。没有候选模型时搜索不可用。
150
+ 推理失败会直接报告,不会静默改用更昂贵的模型重试。每次工具调用都会额外产生一次模型请求,
151
+ 以及网关可能收取的搜索费用。GPT 委托模型遵循 `cached/live`;Grok 委托模型始终实时搜索。
152
+ 此工具由当前模型按需调用,不会在每条用户消息后自动搜索。
153
+
154
+ 委托搜索要求 `modelRegistry.streamSimple`(已在 Pi 1.1.0 上测试)。
155
+ 它复用 Pi 的注册表认证和适配器,包括 token 用量/费用统计;不会自行解析 HTTP 响应或凭据。
156
+ 委托请求不继承主会话的请求/请求头钩子(包括 `traceHeaders`)。
157
+ 可用时从适配器流元数据中收集来源 URL;同时也会要求搜索模型提供链接。
158
+ 状态显示或请求成功都不能证明端点确实执行了搜索或返回了可靠引用。
159
+ 不会恢复旧的 `ts_search` 工具。`ts_oht.search` 等外部工具仍然独立。
160
+
161
+ 诊断信息显示目录来源、最初获取时间、缓存新鲜度、配置是否存在以及安全的刷新错误摘要,
162
+ 绝不显示 API 密钥或 URL。诊断不会额外发起网络请求。状态会随会话/模型活动和目录刷新更新;
163
+ 不会在后台轮询健康状态。
164
+
165
+ 图标使用 Emoji/Unicode:Pi Web 目前会移除命令按钮中的 ANSI 颜色。
166
+ 会话忙碌时按钮不可用。终端 CLI 以文本显示相同状态;请在那里使用斜杠命令。
167
+ Pi Web 可能要等会话运行时启动后才显示扩展状态。
168
+
169
+ ## 子代理编排技能
170
+
171
+ 本包附带 [delegate-model-selection](skills/delegate-model-selection/SKILL.md),
172
+ 鼓励适合的任务通过后台子代理执行,并提供模型/思考级别指导,包括独立的 Kimi + Astra 审查。
173
+ 任务拆分、并行、验证和升级仍由代理自行决定。
174
+
175
+ 插件在同一份 `SKILL.md` 中维护参考表,供直接使用,无需要求代理检查实时排名或数据新鲜度。
176
+ 它是指导,不是模型白名单或固定执行顺序。价格是 API 参考费率,不是订阅费用。
177
+ GLM 指导使用 5.3,并以 Flash 和 FlashX 为备选。思考级别使用 Pi 名称:M3 推荐 `high`,
178
+ 与其其他非 off 级别一样,映射为 adaptive。
179
+
180
+ 安装并执行 `/reload` 后,Pi 会通过包清单发现该技能,除非宿主/包设置禁用或过滤了技能。
181
+ 仅加载 `extensions/index.ts` 不会加载包内技能。需要宿主提供支持模型选择的子代理工具,
182
+ 且有可用的 `tsgw` 模型;本包不提供该工具,也不改变调度设置、用户规则或权限。
183
+
184
+ ## 默认 MCP 注册
185
+
186
+ 插件每次加载时都会注册 `ts_oht`,端点为 `https://xn--oht.cc/mcp`,
187
+ 暴露方式为 `codemode`。使用此默认配置无需任何 MCP 配置。
188
+ 用户级设置中可选的 `tsgw.mcpUrl` 会改变插件使用的端点;它独立于 `tsgw.baseUrl`,
189
+ 且仅在初始化时读取一次。显式 URL 无效时,会安全地发出警告并跳过注册,
190
+ 而不是静默连接默认端点。不支持 `registerMcpServer` 的旧宿主会跳过注册。
191
+
192
+ Pi 管理连接、OAuth 登录和凭据。需要登录时,在会话内使用 `/mcp login ts_oht`。
193
+ 插件不读写 `mcp.json` 或 `mcp-auth.json`,也不携带凭据。
194
+ 保持相同的服务器名称和完全一致的 URL,才能复用宿主现有的 OAuth 作用域。
195
+
196
+ 有效的全局/项目 `mcp.json` 中同名的 `ts_oht` 优先于插件注册,包括 `enabled: false`;
197
+ 插件不会创建第二条连接,也不会绕过该选择。要覆盖 URL、暴露方式、超时、认证或启用状态,
198
+ 请在文件中使用完整的同名配置。对插件提供的服务器所做的更改仅作用于当前会话,不会保存。
199
+ Shell 中的 `pi mcp` 命令不加载插件,无法看到仅由此注册提供的服务器。
200
+ 配置变更后请重新加载或重启。
201
+
202
+ ## 本地文件上传
203
+
204
+ `upload_local_file` 工具使用已连接的 `ts_oht` MCP 进行签名,将 Pi 宿主上已获授权的文件
205
+ 直接上传到 S3。它支持单次 PUT 和流式分片上传、显式恢复、自定义下载有效期,
206
+ 以及 inline/attachment 链接。它使用宿主管理的连接,不存储凭据。
207
+
208
+ 上传功能要求宿主支持 `ctx.executeTool`(已在 Pi 1.1.0 和 1.2.0 上测试),
209
+ 且 `ts_oht` 上传工具可调用。在 Pi 1.2+ 上,`reachesTools` 允许宿主在发现/重连期间
210
+ 等待这两个依赖;旧宿主仍要求工具已经连接。它不会绕过禁用的工具、权限或认证。
211
+ 文件访问使用宿主操作系统权限,而非沙箱。在含有敏感文件的环境中启用前,
212
+ 请阅读[上传用法与安全边界](extensions/upload/README.md)。
213
+
214
+ ## 开发
183
215
 
184
216
  ```bash
185
217
  npm ci
@@ -188,20 +220,19 @@ npm exec -- tsc -p tsconfig.json
188
220
  npm pack --dry-run --json
189
221
  ```
190
222
 
191
- Pi is installed as a development dependency; the lockfile defines the test
192
- baseline. Tests isolate configuration and credentials using temporary agent
193
- directories. Unit tests use a fake host; host integration tests load the extension
194
- through the real Pi SDK with simulated HTTP responses, without production
195
- requests. They do not verify upstream inference, native search results, or Pi
196
- Web rendering. Run the full suite after upgrading Pi.
223
+ Pi 作为开发依赖安装;锁文件定义测试基线(Pi SDK 1.2.0,结构约束(schema)测试使用 TypeBox 1.3.37)。
224
+ SDK 保留其自身的 TypeBox 1.3.27 验证器,因此不假设结构约束构造与宿主验证使用相同版本。
225
+ Pi AI/MCP 是明确仅用于测试的开发依赖;运行时依赖和提供商的对等依赖最低版本保持不变。
226
+ 测试使用临时代理目录隔离配置和凭据。单元测试使用模拟宿主;宿主集成测试通过真实 Pi SDK
227
+ 加载扩展并模拟 HTTP 响应,不发起生产请求。它们不验证上游推理、原生搜索结果或 Pi Web
228
+ 渲染效果。升级 Pi 后请运行完整测试套件。
197
229
 
198
- ## Technical details
230
+ ## 技术细节
199
231
 
200
- - [Vendor profiles](https://github.com/tossp/pi-tsgw/tree/main/extensions/models/vendors): model metadata, compatibility flags, and thinking mappings.
201
- - [Request operations](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/operations.ts): copy-on-write dispatch; DeepSeek/Claude response handling stays with Pi's adapters.
202
- - [Built-in search](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/web-search.ts): exact model/protocol support and append-only injection.
203
- - [Host integration](https://github.com/tossp/pi-tsgw/blob/main/extensions/index.ts): configuration, refreshes, commands, and lifecycle snapshots. Late request callbacks must not access stale session contexts.
232
+ - [厂商配置](https://github.com/tossp/pi-tsgw/tree/main/extensions/models/vendors):模型元数据、兼容性标志和思考映射。
233
+ - [请求操作](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/operations.ts):写时复制分派;DeepSeek/Claude 响应仍由 Pi 的适配器处理。
234
+ - [内置搜索](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/web-search.ts):精确的模型/协议支持范围和仅追加注入。
235
+ - [宿主集成](https://github.com/tossp/pi-tsgw/blob/main/extensions/index.ts):配置、刷新、命令和生命周期快照。延迟执行的请求回调不得访问过期的会话上下文。
204
236
 
205
- These source links describe the repository's current main branch; an installed
206
- release may differ. Development rules in `AGENTS.md` are repository-only and
207
- are not part of the npm package.
237
+ 这些源码链接描述仓库当前的 main 分支;已安装的发行版可能有所不同。
238
+ `AGENTS.md` 中的开发规则仅用于仓库,不属于 npm 包。