dsh-neartoken 0.16.2 → 0.17.1

package/README.md

@@ -5,7 +5,7 @@
   <a href="https://dshfind.com/zh/plugins/huanlinoto/dsh-neartoken"><img src="https://dshfind.com/api/card/huanlinoto/dsh-neartoken?lang=zh" alt="dsh-neartoken card"></a>
 </p>
 
-把 New API 站点（NearToken，`https://llm.pko.svcfusion.com`）变成 DSH 的模型供应商：**在设置页发起设备授权 → 用户在自己浏览器里登录站点并确认 → 插件自动接入 `neartoken` provider**。插件全程不接触密码。模型选择器再把这批模型按 New API 的渠道分组折成 **模型 → 分组 → 推理等级** 三级。
+把 New API 站点（NearToken，`https://neartoken.cc`）变成 DSH 的模型供应商：**在设置页发起设备授权 → 用户在自己浏览器里登录站点并确认 → 插件自动接入 `neartoken` provider**。插件全程不接触密码。模型选择器再把这批模型按 New API 的渠道分组折成 **模型 → 分组 → 推理等级** 三级。
 
 ## 架构
 
@@ -62,7 +62,7 @@
 
 | 字段 | 默认 | 说明 |
 |---|---|---|
-| `baseURL` | `https://llm.pko.svcfusion.com` | 站点根地址，不带尾斜杠 |
+| `baseURL` | `https://neartoken.cc` | 站点根地址，不带尾斜杠 |
 | `apiKeyEnv` | `NEARTOKEN_API_KEY` | 授权写入、adapter 读取的凭据引用名 |
 | `catalogTtlMs` | `300000` | `/api/pricing` 目录缓存时长 |
 | `defaultContextWindow` | `200000` | 没有任何来源能说明某模型上下文窗口时上报的值 |
@@ -85,6 +85,29 @@
         reasoning: [low, medium, high, max]
 ```
 
+### 站点地址迁移（0.17.0）
+
+站点从 `https://llm.pko.svcfusion.com` 迁到 `https://neartoken.cc`，`baseURL` 的默认值随之改变。凭据里存的 key 不变：同一套 New API 数据下，升级后不需要重新登录。
+
+**旧域名要给还在跑旧版插件的客户端继续用，只能做反向代理，不能做 302/307 重定向**：
+
+- **302 把 POST 降级成 GET 并丢掉请求体**：登录（`/api/dsh/device/*`）、出字（`/v1/*`）、生图（`/v1/images/generations`）、充值全部失败。只剩匿名的 `GET /api/pricing` 和 `GET /api/status` 还能过，现场表现是「模型列表能显示，一发消息就报错」。
+- **跨 origin 的重定向会剥掉 `Authorization` 头**（302 / 307 / 308 一样，是 fetch 规范行为）：凡是带 key 的请求落到新域名都成了未认证请求，一律 401。307 只救得回匿名端点，结果更迷惑 —— 登录能成功，之后每个模型都 401。
+
+反向代理保留方法、请求体和请求头，SSE 也不会断：
+
+```nginx
+location / {
+  proxy_pass https://neartoken.cc;
+  proxy_http_version 1.1;
+  proxy_set_header Host $host;
+  proxy_buffering off;        # 不关会把流式出字整段缓冲
+  proxy_read_timeout 600s;    # 生图有 114 秒的先例
+}
+```
+
+旧域名退役前，新版插件照常直连 `https://neartoken.cc`，两者互不影响。
+
 ### 图片压缩
 
 **图片在离开本机前先被重编码**，不是原图直传：请求前把每张图交给 harness 的附件服务（`attachments.readImageRequest`）按 `imageMaxEdge` / `imageMaxBytes` 生成一份请求版，sharp 缩放 + 质量阶梯重编码（有 alpha 走 WebP、无 alpha 走 JPEG），结果按「附件 + 目标尺寸 + 字节预算」缓存，同一张图重复发不重复编码。已经被上游视觉网格丢掉的分辨率不再上传，也就不再计费。
@@ -205,6 +228,8 @@ Gemini 系走原生 surface 而不是 openai 兼容层：同模型同提示词
 
 - 四套 wire（chat / anthropic / genai / responses）各自解析 SSE；**图片按各协议发送** —— chat 用 `image_url` part、anthropic 用 `source.base64`、genai 用 `inlineData`、responses 用 `input_image`。发送前先按 `imageMaxEdge` / `imageMaxBytes` 重编码（见「图片压缩」），所以线上字节与媒体类型未必等于附件里的原图。**工具结果里的图片也发**（`read_image` 的结果就是一段文本信封 + 一张图）：anthropic 把图塞回同一个 `tool_result` 的 content 块数组；genai 在同一 user turn 的 parts 里补 `inlineData`；chat 的 tool 消息只能放字符串、responses 的 `function_call_output` 同理，所以图跟在**整段连续工具结果之后**的一条 user 消息 / 条目里（并行调用时不会把 tool 消息切断）。字节由 `attachments.readImage` 在请求前内联；没有 attachments 服务或读不出来会**让请求失败**，不再静默降级成纯文本（曾经就是这样：贴的截图模型根本收不到）。会话里被 image-offload 标记的图片（`offloaded: true`）不发字节；插件也不替它生成占位文本，所以那一次图片对模型完全不可见。文件块（非图片附件）仍不发；`/model` 弹窗仍是内置平铺列表；箭头键盘导航未接。
 - **genai 线的并行工具调用必须收在同一个 user turn 里**：Gemini 校验「一个 functionCall turn ↔ 紧随其后那条 user turn 里等量的 functionResponse parts」，每条工具结果各开一条 user turn 会被上游拒成 400 `Please ensure that the number of function response parts is equal to the number of function call parts of the function call turn`。它是**确定性**错误：历史不变就必然复现，重试、换分组都无用，只能新开会话（0.16.1 及以前踩中过一次：一轮发了 6 个并行 `read`，整轮就此作废）。0.16.2 起把整段连续的工具结果折进同一个 user turn；Gemini ≥ 3 另给 `functionCall` / `functionResponse` 带上 `id`（同一个函数被并行调多次时才分得清谁答谁），`gemma*` 与更早的 Gemini 不发该字段，只按函数名匹配。
+- **anthropic 线的工具结果同样必须合批**：messages API 校验「一条 assistant turn 的 `tool_use` ↔ 紧随其后那条 user turn 的 `tool_result`」一一对应。并行调用时若每条结果各开一条 user 消息，网关报 400 `Invalid message sequence: tool_use and tool_result blocks must be correctly paired and ordered`（0.17.1 以前 anthropic 线就是这个形状 —— genai 线 0.16.2 修了同类问题，anthropic 线漏了）。现在整段连续结果折进紧邻 assistant 的那一条 user 消息；结果没记录（中断、fork、压缩裁剪）的调用补一句占位结果；对不上任何调用的结果丢弃；批内混进来的 user 文本移到结果之后；相邻同角色轮次合并、`tool_result` 固定排在 user 消息首位。这条是**请求体形状**的错，与历史记录无关：升级后此前必挂的会话下一轮就能继续。
+- **请求体按需 brotli 压缩**：每次请求都带全量工具定义，body 常在几十到几百 KB，带截图时上 MB。上游（New API 的 `DecompressRequestMiddleware`）在解析前解压 `content-encoding` 为 gzip / br / zstd 的 body，实测三条 wire（chat / messages / responses）全通；deflate 不支持，且不带该头就按明文解析。所以 **≥16 KB 的 body 以 brotli quality 5 发送**：实测 57 KB 的工具密集请求压到 468 B、2 MB 真实源码压到 418 KB（19%）。四条聊天 wire 与出图的三条通道（`images` / `genai` / `chat`）共用同一个出口 `postJson`，阈值与回落只有一份 —— 带参考图的出图请求是另一个 base64 大户。选型依据：同 CPU 下 brotli 比 gzip 小 8–14%；zstd level 3 与 gzip 等大但快 5 倍，只在 CPU 吃紧时更优；而 brotli 的**运行时默认 quality 是 11**，2 MB 上要 3.7 秒，必须显式钉 5。低于阈值走明文 —— 那么小的上行不值一次压缩加解压。图片主导的请求收益有天花板（base64 编码的已压缩图只能压到 75%，那 25% 只是还原 base64 膨胀），真正的杠杆仍是 `imageMaxEdge` / `imageMaxBytes`。若上游某天不认该编码（400 且 body 解析失败），同一请求立刻以明文重发一次：被拒的请求从未计费，代价是一个往返而不是整次调用。
 - 四套 wire 的 SSE 解析都有「帧样本 → 期望 chunk 序列」回归测试（`src/host/wire-parse.spec.ts`），帧样本取自生产网关的真实响应。网关在内容帧上发 `"usage": null`，只有末帧带真值：任何一处把 `usage` 当对象直接读都会让整条流中途崩掉（曾导致 claude 模型全不可用）。
 - **每个请求都带会话亲和键**：chat 与 responses 发 `prompt_cache_key`，anthropic 发 `metadata.user_id`，取值都是 DSH 的 `GenerateOptions.sessionId`。站点就是靠这个值挑上游渠道的（New API 的「codex cli trace」规则：`^gpt-.*$` + `/v1/responses`，键取自 body 的 `prompt_cache_key`，取不到就把整条规则跳过），而提示词缓存按**上游账号**存 —— 不带键时每个请求随机换账号，缓存永远不中。实测同一 6k 前缀：不带键连发 4 次 `cached_tokens` 全 0；带键后第 2 次起 5888/6011 ≈ 98%。`/v1/chat/completions` 上目前没有对应规则，chat 线即使带键也只是偶发命中，要彻底解决需要站点加一条匹配该路径的亲和规则；anthropic 线的 `metadata.user_id` 同理（规则只作用于 `/v1/messages`，这一条已经匹配）。
 - **anthropic 线显式打缓存断点**：Anthropic 只在 `cache_control` 断点处写缓存，没有断点就整段 prompt 按新输入计价（亲和键只保证落在同一上游账号，不产生缓存）。每个请求打 4 个断点：`tools` 末项、`system` 末块、最后两条消息各自末块 —— harness 每轮全量重放历史，尾部双断点保证下一轮几乎全命中，每轮只写新增片段。实测（Claude Max 超惠分组，~6.3k token 前缀）：无断点连发两次 `cache_read` 全 0；打点后第 2 次起 `in=4, cr=6316`，三轮增长历史 `cr` 累积到 10811、`in` 恒为个位数。断点也覆盖 `tool_result` 结尾的轮次（DSH 会话的常态形态）。