pi-tsgw 0.0.15 → 0.0.17

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.
Files changed (52) hide show
  1. package/README.md +211 -214
  2. package/extensions/index.ts +39 -66
  3. package/extensions/mcp.ts +22 -10
  4. package/extensions/models/_tools.ts +6 -6
  5. package/extensions/models/catalog.ts +8 -9
  6. package/extensions/models/gateway-catalog.ts +20 -20
  7. package/extensions/models/operations.ts +6 -6
  8. package/extensions/models/vendors/_protocols.ts +3 -3
  9. package/extensions/models/vendors/deepseek.ts +3 -3
  10. package/extensions/models/vendors/gemini.ts +2 -2
  11. package/extensions/models/vendors/glm.ts +2 -2
  12. package/extensions/models/vendors/grok.ts +4 -4
  13. package/extensions/models/vendors/kimi.ts +1 -1
  14. package/extensions/models/vendors/longcat.ts +1 -1
  15. package/extensions/models/vendors/mimo.ts +1 -1
  16. package/extensions/models/vendors/minimax.ts +5 -5
  17. package/extensions/models/vendors/openai.ts +6 -6
  18. package/extensions/models/web-search.ts +47 -8
  19. package/extensions/search-proxy.ts +104 -0
  20. package/extensions/search.ts +95 -0
  21. package/extensions/status.ts +10 -4
  22. package/extensions/upload/README.md +118 -137
  23. package/extensions/upload/errors.ts +3 -3
  24. package/extensions/upload/index.ts +19 -18
  25. package/extensions/upload/local-file.ts +14 -14
  26. package/extensions/upload/protocol.ts +12 -9
  27. package/extensions/upload/transport.ts +13 -13
  28. package/extensions/upload/uploader.ts +17 -17
  29. package/package.json +7 -5
  30. package/skills/{delegate-model-selection → tsgw-delegate-model-selection}/SKILL.md +1 -1
  31. package/skills/tsgw-git-commit/SKILL.md +65 -0
  32. package/skills/tsgw-git-commit/scripts/discover-repos.mjs +58 -0
  33. package/skills/tsgw-github/SKILL.md +85 -0
  34. package/skills/tsgw-mk-docs/SKILL.md +72 -0
  35. package/skills/tsgw-mk-docs/SOURCE.md +47 -0
  36. package/skills/tsgw-mk-docs/assets/000-todo.template.md +21 -0
  37. package/skills/tsgw-mk-docs/references/000-terminology.md +58 -0
  38. package/skills/tsgw-mk-docs/references/000-todo.md +106 -0
  39. package/skills/tsgw-mk-docs/references/a-series/checklist.md +20 -0
  40. package/skills/tsgw-mk-docs/references/a-series/modules.md +33 -0
  41. package/skills/tsgw-mk-docs/references/a-series/overview.md +24 -0
  42. package/skills/tsgw-mk-docs/references/b-series/checklist.md +20 -0
  43. package/skills/tsgw-mk-docs/references/b-series/modules.md +36 -0
  44. package/skills/tsgw-mk-docs/references/b-series/overview.md +24 -0
  45. package/skills/tsgw-mk-docs/references/c-series/checklist.md +20 -0
  46. package/skills/tsgw-mk-docs/references/c-series/modules.md +33 -0
  47. package/skills/tsgw-mk-docs/references/c-series/overview.md +23 -0
  48. package/skills/tsgw-mk-docs/references/design-doc-boundaries.md +146 -0
  49. package/skills/tsgw-programmer-go/SKILL.md +64 -0
  50. package/skills/tsgw-programmer-go/references/UPDATE_GUIDE.md +26 -0
  51. package/skills/tsgw-programmer-go/references/code_review_comments.md +50 -0
  52. package/skills/tsgw-programmer-go/references/effective_go.md +49 -0
package/README.md CHANGED
@@ -1,37 +1,32 @@
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
  {
@@ -46,197 +41,200 @@ Example:
46
41
  }
47
42
  ```
48
43
 
49
- ### Gateway address
44
+ ### 网关地址
50
45
 
51
- `baseUrl` points at your AIH gateway (any instance — the public one or a
52
- self-hosted one). The `/v1` suffix is normalized away. If unset, a neutral
53
- placeholder root is used that will not work.
46
+ `baseUrl` 指向你的 AIH 网关(可以是公共实例或自托管实例)。规范化时会去掉 `/v1` 后缀。
47
+ 未设置时使用一个中性的占位根地址,该地址无法实际使用。
54
48
 
55
- ### API key
49
+ ### API 密钥
56
50
 
57
- The extension delegates credential reading and resolution to Pi:
51
+ 扩展将凭据读取和解析交由 Pi 处理:
58
52
 
59
- 1. **`/login`** — select the `tsgw` provider and enter the key; pi stores it
60
- in `~/.pi/agent/auth.json` (preferred)
61
- 2. **`TSGW_API_KEY`** environment variable — Pi's fallback when nothing is
62
- stored
53
+ 1. **`/login`** — 选择 `tsgw` 提供商并输入密钥;pi 将其存储在
54
+ `~/.pi/agent/auth.json` 中(推荐方式)。
55
+ 2. **`TSGW_API_KEY` 环境变量** — 未存储凭据时由 Pi 回退使用。
63
56
 
64
- Startup discovery uses Pi's stored-credential API; later catalog refreshes use
65
- the credential supplied by Pi. With environment-only authentication, the initial
66
- catalog may fall back to static models until Pi refreshes it.
57
+ 启动时的发现使用 Pi 的已存储凭据 API;后续目录刷新使用 Pi 提供的凭据。
58
+ 如果仅通过环境变量认证,初始目录可能回退到静态模型,直到 Pi 刷新目录。
67
59
 
68
- ### Options
60
+ ### 选项
69
61
 
70
- | Setting (`settings.json` `tsgw.*`) | Default | Meaning |
62
+ | 设置(`settings.json` 中的 `tsgw.*`) | 默认值 | 含义 |
71
63
  | --- | --- | --- |
72
- | `baseUrl` | placeholder | Gateway root (the `/v1` suffix is normalized away) |
73
- | `mcpUrl` | `https://xn--oht.cc/mcp` | Optional `ts_oht` HTTP(S) endpoint override; independent of the model gateway |
74
- | `tsSearch` | `live` | GPT: `cached` or `live`; unset, legacy `off`, and invalid values fall back to `live`. Supported Grok models always use live search. |
75
- | `traceHeaders` | `false` | Adds `AH-Thread-Id` / `AH-Trace-Id` headers for gateway-side tracing |
76
- | `includeModels` | unset | Re-include override: matching model ids are kept even when also matched by `excludeModels` (exact id or `prefix-*` glob) |
77
- | `excludeModels` | unset | Blacklist: matching model ids are dropped unless pulled back by `includeModels` (exact id or `prefix-*` glob) |
78
-
79
- ## Model catalog
80
-
81
- The catalog is assembled from per-vendor slices (`extensions/models/vendors/`),
82
- covering 11 vendor families: DeepSeek, GLM (Zhipu), MiMo (Xiaomi), MiniMax,
83
- Kimi (Moonshot), Qwen (Alibaba), GPT (OpenAI), Gemini (Google), Claude
84
- (Anthropic), LongCat, and Grok (xAI). The current static catalog contains 36 chat
85
- model IDs, including retained aliases; this is not a live availability count.
86
- Vendor files carry documentation links and metadata caveats. Alias mappings,
87
- output limits, and shared thinking policies are not all individually verified
88
- against gateway endpoints; public-price estimates do not guarantee billing.
89
- MiMo uses `mimo-v2.6-pro` and `mimo-v2.6-flash`; the former V2.5 IDs are not
90
- registered. Update any explicit model selections or filter rules to the new IDs.
91
-
92
- The curated catalog keeps DeepSeek `deepseek-flash` and V4 Pro; GLM 5.2+,
93
- plus the explicit `glm-4.5-air` exception; MiniMax M3+; Kimi K3; GPT 6+;
94
- and Gemini 3.5+ plus the unversioned `gemini-flash` / `gemini-pro` aliases.
95
- Qwen, MiMo, LongCat, Claude, and Grok retain their existing registrations.
96
- Removed IDs and their dedicated request policies are no longer registered;
97
- include rules cannot restore them, even if a gateway still lists them. Existing
98
- explicit model selections referencing removed IDs need to be updated.
99
-
100
- Kimi offers `kimi-k3` and the gateway variant `kimi-k3-256k`, displayed as
101
- **Kimi K3 (256K)** with a 262,144-token context window. Its other metadata,
102
- price estimates, and thinking policy are inherited from K3; the 131,072-token
103
- output setting is separate from context size. These inherited values are not
104
- individual endpoint verification or a guarantee of the variant's billing rates.
105
-
106
- The catalog also includes `MiniMax-M3.1-Flash-Preview`, `glm-5.3`,
107
- `glm-5.3-flash`, and `glm-5.3-flashx`. All four require thinking: MiniMax
108
- uses low/medium/high/xhigh/max; GLM uses low/high/max. Unsupported `off` is
109
- disabled in model metadata, and stale off/minimal requests map to low rather
110
- than silently selecting the default max. MiniMax and GLM Flash/FlashX support
111
- image input; GLM 5.3 is text-only. Registration does not prove gateway
112
- inference or tool-call support.
113
-
114
- As checked on 2026-10-16, MiniMax publishes subscription access but no per-token
115
- price for M3.1 Flash Preview. Its zero cost fields mean **unknown**, not free,
116
- and usage cost totals therefore omit its actual charges. GLM 5.3 price estimates
117
- use domestic public rates and the existing fixed USD/CNY conversion; temporary
118
- free cache storage is recorded as zero, not a permanent billing guarantee.
119
-
120
- Use broad `excludeModels` rules to drop model families and precise
121
- `includeModels` rules to pull selected models back. `includeModels` is not a
122
- global whitelist: models matching neither list remain available. To register
123
- only selected models, use `"excludeModels": ["*"]` and pull them back through
124
- `includeModels`. Both lists are case-sensitive and support only exact IDs or
125
- trailing `*` prefix matching (not general globs); preserve `MiniMax-*` casing.
126
- When a gateway catalog is available, filtering applies after intersecting it
127
- with the static catalog. Include rules cannot add unknown or unavailable IDs.
128
-
129
- Opening `/model` refreshes the gateway catalog in the background, with a
130
- five-minute cache to avoid repeated requests. Run `/tsgw-refresh` to bypass the
131
- cache and force an immediate refresh without restarting or reloading Pi. If a
132
- refresh fails, the last successful model list remains active.
133
-
134
- Memory and disk caches are scoped to the gateway root and credential using a
135
- SHA-256 digest; plaintext credentials are not stored. The disk cache is a single
136
- slot at `<agent-dir>/tsgw/models-cache.json`: changing scope may require a fresh
137
- fetch. Legacy unscoped cache files are ignored and replaced after a successful
138
- fetch. In-process request ordering prevents late results from replacing newer
139
- cache writes; this is not a cross-process locking mechanism.
140
-
141
- ## Status bar and session controls
142
-
143
- Pi Web clients supporting `command:/…` statuses render these as clickable
144
- buttons; the terminal CLI displays status text and accepts the same commands:
145
-
146
- - **`TSGW · N`** (`/tsgw`): one menu for **refreshing the model catalog** and
147
- **viewing diagnostics**. The count is the filtered registered catalog, not a
148
- count of healthy inference endpoints. 🟢 means a fresh directory result;
149
- 🟡 means a static/expired directory or a failed refresh; ⚠️ means missing
150
- credentials or gateway configuration; ⏳ means a refresh is running.
151
- - **Built-in search** (`/tsgw-search`): GPT offers only `cached / live`
152
- for the current session, defaulting to `live`. Supported Grok models use
153
- fixed live search: the command only shows a notice, without a picker or
154
- changing the GPT session mode. Unsupported TSGW models are labeled
155
- accordingly; this button is hidden when another provider is selected.
156
-
157
- For GPT, you can also type `/tsgw-search cached` or `/tsgw-search live`;
158
- `off` is no longer accepted. These controls do not modify `settings.json` or
159
- persist across a reload or a new session; `tsgw.tsSearch` remains the startup
160
- default. Existing `cached` configuration is preserved; unset, legacy `off`,
161
- and invalid configuration now default to `live`.
162
-
163
- Injection remains limited to the existing model/protocol support list. GPT
164
- Responses appends a `web_search` tool (`external_web_access` is false for
165
- `cached`, true for `live`); Grok Completions appends
166
- `search_parameters: { mode: "on" }`. Existing search tools/fields are never
167
- overwritten. This setting does not control Qwen's vendor policy, external
168
- tools, or thinking mode and is not a global network-access switch.
169
-
170
- The standalone `ts_search` tool is no longer bundled. Use a separately configured
171
- search tool such as `ts_oht.search` instead. Built-in model search remains
172
- available and does not control external search tools.
173
-
174
- Diagnostics show directory source, original fetch time, cache freshness,
175
- configuration presence, and safe refresh error summaries—never API keys or
176
- URLs. They make no extra network requests. Statuses update on session/model
177
- activity and directory refreshes; there is no background health polling.
178
-
179
- Icons use Emoji/Unicode: Pi Web currently strips ANSI colors from command
180
- buttons. Busy sessions disable the buttons. The terminal CLI shows the same
181
- statuses as text; use the slash commands there. Pi Web may not show extension
182
- statuses until the session runtime has started.
183
-
184
- ## Subagent orchestration skill
185
-
186
- The package ships [delegate-model-selection](skills/delegate-model-selection/SKILL.md),
187
- which encourages suitable tasks to run through background subagents and provides
188
- model/thinking-level guidance, including independent Kimi + Astra reviews.
189
- Task splitting, parallelism, validation, and escalation remain the agent's choice.
190
-
191
- The plugin maintains the reference table in the same `SKILL.md`
192
- for direct use, without asking agents to check live rankings or data freshness.
193
- It is guidance, not a model whitelist or fixed execution sequence. Prices are
194
- API reference rates, not subscription charges. GLM guidance uses 5.3, with Flash
195
- and FlashX as alternatives. Thinking levels use Pi names: M3 recommends `high`,
196
- which maps to adaptive like its other non-off levels.
197
-
198
- Pi discovers the skill through the package manifest after installation and
199
- `/reload`, unless skills are disabled or filtered by the host/package settings.
200
- Loading only `extensions/index.ts` does not load package skills. A host-provided
201
- subagent tool with model selection and available `tsgw` models is required; this
202
- package does not supply that tool or change dispatch settings, user rules, or
203
- permissions.
204
-
205
- ## Default MCP registration
206
-
207
- The plugin registers `ts_oht` at `https://xn--oht.cc/mcp` with `codemode`
208
- exposure on each load. No MCP configuration is required to use this default.
209
- An optional `tsgw.mcpUrl` in the user-level settings changes the plugin's endpoint;
210
- it is independent of `tsgw.baseUrl` and is read once at initialization. Invalid
211
- explicit URLs skip this registration with a safe warning, rather than silently
212
- connecting to the default. Older hosts without `registerMcpServer` skip it.
213
-
214
- Pi manages connections, OAuth sign-in and credentials. Use `/mcp login ts_oht`
215
- inside a session if sign-in is required. The plugin does not read or write
216
- `mcp.json` or `mcp-auth.json`, and does not carry credentials. Keep the same
217
- server name and exact URL to reuse the host's existing OAuth scope.
218
-
219
- A same-name `ts_oht` in the effective global/project `mcp.json` takes precedence
220
- over the plugin registration, including `enabled: false`; the plugin does not
221
- create a second connection or bypass that choice. Use a complete same-name
222
- file configuration to override the URL, exposure, timeout, auth, or enabled state.
223
- Changes to a plugin-provided server apply only to the current session; they are
224
- not saved. Shell `pi mcp` commands do not load plugins and cannot see servers
225
- provided only by this registration. Reload or restart after configuration changes.
226
-
227
- ## Local file upload
228
-
229
- The `upload_local_file` tool uploads an authorized file from the Pi host directly
230
- to S3 using the already-connected `ts_oht` MCP for signing. It supports single
231
- PUTs and streaming multipart uploads, explicit recovery, custom download expiry
232
- and inline/attachment links. It uses the host-managed connection and stores no credentials.
233
-
234
- Upload support requires a host with `ctx.executeTool` (tested with Pi 1.1.0) and
235
- callable `ts_oht` upload tools. File access uses host OS permissions, not a
236
- sandbox. See [upload usage and safety boundaries](extensions/upload/README.md)
237
- before enabling it in an environment with sensitive files.
238
-
239
- ## 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
+ | 技能 | 用途 |
172
+ | --- | --- |
173
+ | [tsgw-git-commit](skills/tsgw-git-commit/SKILL.md) | 暂存内容核验、分批提交与中文提交说明;包含支持 worktree 的只读仓库发现脚本。 |
174
+ | [tsgw-github](skills/tsgw-github/SKILL.md) | 使用 gh 查询与维护 issue、PR、CI,安全发布正文并核验 Actions 升级。 |
175
+ | [tsgw-mk-docs](skills/tsgw-mk-docs/SKILL.md) | 需求、设计、执行计划、术语和状态证据的文档治理,含参考清单与模板,不依赖审阅插件。 |
176
+ | [tsgw-programmer-go](skills/tsgw-programmer-go/SKILL.md) | Go 编码与审查;自产 JSON 使用 PascalCase、零值省略优先 omitzero,真实变更中同步迁移相关旧标签。 |
177
+
178
+ 技能从本地维护的工作流整理并适配 Pi,按本项目 MIT 许可证提供;不包含第三方 gitmoji 数据集。
179
+ 项目规则和用户授权优先,不安装 Git hook,不自动推送或发布。已有同类用户级技能时,建议择一启用,避免重复指导。
180
+
181
+ ### 子代理编排与模型选型
182
+
183
+ 本包附带 [tsgw-delegate-model-selection](skills/tsgw-delegate-model-selection/SKILL.md),
184
+ 鼓励适合的任务通过后台子代理执行,并提供模型/思考级别指导,包括独立的 Kimi + Astra 审查。
185
+ 任务拆分、并行、验证和升级仍由代理自行决定。
186
+
187
+ 插件在同一份 `SKILL.md` 中维护参考表,供直接使用,无需要求代理检查实时排名或数据新鲜度。
188
+ 它是指导,不是模型白名单或固定执行顺序。价格是 API 参考费率,不是订阅费用。
189
+ GLM 指导使用 5.3,并以 Flash 和 FlashX 为备选。思考级别使用 Pi 名称:M3 推荐 `high`,
190
+ 与其其他非 off 级别一样,映射为 adaptive。
191
+
192
+ 安装并执行 `/reload` 后,Pi 会通过包清单发现随包技能,除非宿主/包设置禁用或过滤了技能。
193
+ 可以使用 `/skill:tsgw-git-commit` 等命令显式加载;仅加载 `extensions/index.ts` 不会加载包内技能。
194
+ 包设置中的 `skills: []` 可禁用全部技能,`skills: ["skills/tsgw-git-commit"]` 可仅加载指定技能,
195
+ 或用 `skills: ["!skills/tsgw-git-commit/**"]` 排除该技能;由宿主处理,不是 `tsgw` 配置项。
196
+
197
+ 只有模型选型技能需要宿主提供支持模型选择的子代理工具及可用的 `tsgw` 模型;通用开发技能不绑定模型 provider。
198
+ 本包不提供子代理工具,也不改变调度设置、用户规则或权限。
199
+
200
+ ## 默认 MCP 注册
201
+
202
+ 插件每次加载时都会向宿主登记以下会话默认值,暴露方式均为 `codemode`:
203
+
204
+ | 服务器名称 | 默认端点 |
205
+ | --- | --- |
206
+ | `ts_oht` | `https://xn--oht.cc/mcp` |
207
+ | `ts_tool` | `https://mcp.tossp.com/mm/ts/mcp` |
208
+
209
+ 使用这些默认值无需手工配置 MCP。用户级设置中可选的 `tsgw.mcpUrl` 仅覆盖 `ts_oht`,
210
+ 独立于 `tsgw.baseUrl`,且仅在初始化时读取一次;`ts_tool` 的覆盖交给宿主同名文件配置,
211
+ 没有额外的插件配置项。显式 `mcpUrl` 无效时,安全警告并仅跳过 `ts_oht`,
212
+ 不静默回退,也不影响 `ts_tool`。单个登记失败不阻断另一服务或模型提供方;
213
+ 不支持 `registerMcpServer` 的旧宿主会跳过两者注册。
214
+
215
+ Pi 管理连接、OAuth 登录和凭据。需要登录时,在会话内对相应服务使用 `/mcp login ts_oht` 或 `/mcp login ts_tool`。
216
+ 插件不读写 `mcp.json` 或 `mcp-auth.json`,也不携带凭据。
217
+ 保持相同的服务器名称和完全一致的 URL,才能复用宿主现有的 OAuth 作用域。
218
+
219
+ 有效的全局/项目 `mcp.json` 中同名的 `ts_oht`、`ts_tool` 分别优先于插件注册,包括 `enabled: false`;
220
+ 插件不会创建第二条连接,也不会绕过该选择。要覆盖 URL、暴露方式、超时、认证或启用状态,
221
+ 请在文件中使用完整的同名配置。对插件提供的服务器所做的更改仅作用于当前会话,不会保存。
222
+ Shell 中的 `pi mcp` 命令不加载插件,无法看到仅由此注册提供的服务器。
223
+ 配置变更后请重新加载或重启。
224
+
225
+ ## 本地文件上传
226
+
227
+ `upload_local_file` 工具使用已连接的 `ts_oht` MCP 进行签名,将 Pi 宿主上已获授权的文件
228
+ 直接上传到 S3。它支持单次 PUT 和流式分片上传、显式恢复、自定义下载有效期,
229
+ 以及 inline/attachment 链接。它使用宿主管理的连接,不存储凭据。
230
+
231
+ 上传功能要求宿主支持 `ctx.executeTool`(已在 Pi 1.1.0 和 1.2.0 上测试),
232
+ 且 `ts_oht` 上传工具可调用。在 Pi 1.2+ 上,`reachesTools` 允许宿主在发现/重连期间
233
+ 等待这两个依赖;旧宿主仍要求工具已经连接。它不会绕过禁用的工具、权限或认证。
234
+ 文件访问使用宿主操作系统权限,而非沙箱。在含有敏感文件的环境中启用前,
235
+ 请阅读[上传用法与安全边界](extensions/upload/README.md)。
236
+
237
+ ## 开发
240
238
 
241
239
  ```bash
242
240
  npm ci
@@ -245,20 +243,19 @@ npm exec -- tsc -p tsconfig.json
245
243
  npm pack --dry-run --json
246
244
  ```
247
245
 
248
- Pi is installed as a development dependency; the lockfile defines the test
249
- baseline. Tests isolate configuration and credentials using temporary agent
250
- directories. Unit tests use a fake host; host integration tests load the extension
251
- through the real Pi SDK with simulated HTTP responses, without production
252
- requests. They do not verify upstream inference, native search results, or Pi
253
- Web rendering. Run the full suite after upgrading Pi.
246
+ Pi 作为开发依赖安装;锁文件定义测试基线(Pi SDK 1.2.0,结构约束(schema)测试使用 TypeBox 1.3.37)。
247
+ SDK 保留其自身的 TypeBox 1.3.27 验证器,因此不假设结构约束构造与宿主验证使用相同版本。
248
+ Pi AI/MCP 是明确仅用于测试的开发依赖;运行时依赖和提供商的对等依赖最低版本保持不变。
249
+ 测试使用临时代理目录隔离配置和凭据。单元测试使用模拟宿主;宿主集成测试通过真实 Pi SDK
250
+ 加载扩展并模拟 HTTP 响应,不发起生产请求。它们不验证上游推理、原生搜索结果或 Pi Web
251
+ 渲染效果。升级 Pi 后请运行完整测试套件。
254
252
 
255
- ## Technical details
253
+ ## 技术细节
256
254
 
257
- - [Vendor profiles](https://github.com/tossp/pi-tsgw/tree/main/extensions/models/vendors): model metadata, compatibility flags, and thinking mappings.
258
- - [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.
259
- - [Built-in search](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/web-search.ts): exact model/protocol support and append-only injection.
260
- - [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.
255
+ - [厂商配置](https://github.com/tossp/pi-tsgw/tree/main/extensions/models/vendors):模型元数据、兼容性标志和思考映射。
256
+ - [请求操作](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/operations.ts):写时复制分派;DeepSeek/Claude 响应仍由 Pi 的适配器处理。
257
+ - [内置搜索](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/web-search.ts):精确的模型/协议支持范围和仅追加注入。
258
+ - [宿主集成](https://github.com/tossp/pi-tsgw/blob/main/extensions/index.ts):配置、刷新、命令和生命周期快照。延迟执行的请求回调不得访问过期的会话上下文。
261
259
 
262
- These source links describe the repository's current main branch; an installed
263
- release may differ. Development rules in `AGENTS.md` are repository-only and
264
- are not part of the npm package.
260
+ 这些源码链接描述仓库当前的 main 分支;已安装的发行版可能有所不同。
261
+ `AGENTS.md` 中的开发规则仅用于仓库,不属于 npm 包。