dsh-zen-free 1.2.0 → 2.0.1

package/README.md

@@ -1,129 +1,124 @@
 # dsh-zen-free
 
-给 DSH 加一个**免费**供应商 `zenfree`，带两个模型：
-
-| DSH 模型 id | 上游模型 | 说明 |
-|---|---|---|
-| `ds4.1f` | `deepseek-v4.1-flash-free` | DeepSeek V4.1 Flash，OpenCode Zen 免费池 |
-| `glm5.3f` | `glm-5.3-flash-free` | GLM 5.3 Flash，OpenCode Zen 免费池 |
+把 **OpenCode Zen 免费池**接成 DSH 的一条供应商路由 `opencode-zen`，注册进
+**设置 → 模型** 的供应商列表，因此可以像其他供应商一样增删改模型、勾选图片输入、
+填上下文窗口与输出上限。
 
 - **不需要 API Key**，不需要账号，不需要 9Router。
-- **请求强制直连**：不走 `HTTP(S)_PROXY` / `ALL_PROXY`，也不经过 Harness 的全局代理
-  dispatcher —— 本机 Clash（7897）从 CONNECT 隧道打 `opencode.ai` 会 TLS 失败，所以必须绕开。
-- **带设置页**：模型参数（上下文窗口 / 输出上限 / 图片输入）与请求统计都在
-  设置 → 「zenfree 模型」和「zenfree 统计」里。
-
-## 安装
+- **请求强制直连**：绕开 `HTTP(S)_PROXY` / `ALL_PROXY` 与 Harness 的全局代理
+  dispatcher —— 本机 Clash（7897）从 CONNECT 隧道打 `opencode.ai` 会 TLS 失败。
 
-### 标准安装（npm 包）
+## 装完怎么用
 
-GUI 设置 → 插件 → 安装框输入包名 `dsh-zen-free`。
-（`installBundle` 会读本包的 `dsh.bundle.patch` → `cordis.patch.yml`，装完即启用。）
+设置 → 模型 → 会看到 **OpenCode Zen（免费）** 一行，点「编辑」即可：
 
-装完在模型选择器里会多出供应商 **zenfree**，下面两个模型。
+- 增删改模型（`deepseek-v4.1-flash-free` / `glm-5.3-flash-free` 是默认两条）
+- 每个模型单独勾选输入模态（text / image）
+- 填上下文窗口、单次输出上限
+- 「获取可用模型」按钮可直接向上游拉取模型列表
 
-### 手工挂载（本地开发）
+未列出的 `-free` 模型 id 也可以手填进模型列表，会被原样透传到上游。
 
-1. 把本目录拷进 `$DSH_HOME/profiles/<profile>/node_modules/`（目录名保持 `dsh-zen-free`）。
-2. 在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 末尾追加：
+**不需要任何手工配置。** 供应商路由由本包的 `cordis.patch.yml` 在 bundle 层声明
+（`base` 里 `llm-pi-ai` 是「mounted dormant」——零 provider，装好不出现任何模型，
+必须由某一层提供 profile 才有路由）。
 
-   ```yaml
-   - insert:
-       - id: zenfree
-         name: 'dsh-zen-free'
-   ```
+> ⚠️ **只有一个例外**：如果你**手工**在自己的 profile `cordis.patch.yml` 里写死了
+> `llm-pi-ai` 的 `providers`，那一层在 bundle 层之后应用，会**整体替换**掉本插件提供的
+> `opencode-zen`（cordis patch 对 `config` 是整体赋值，不做深合并）。
+> 此时请把 `opencode-zen` 那段一并合并进你自己的 `providers`。
+> 通过**设置页**增删 provider 的用户不会遇到这个问题：设置页提交的是当前完整列表。
 
-3. 生效：`cordis.patch.yml` 的改动由 HMR 即时生效；**新插件代码**首次加载若未被拾取，
-   关闭并重新打开 DeepSeek Harness。
+## 用量统计
 
-## 设置页
+**设置 → Zen 免费池统计**（独立一整页，不是「插件」下的标签页）显示：
 
-### zenfree 模型
+- 顶部四个总量：调用次数 / 输入 token / 输出 token / 命中缓存
+- 按模型分行的明细：调用、失败、输入、输出、缓存、合计、最近使用时间
+- 面板开着时每 5 秒自刷一次；底部「清零统计」按钮可重置
 
-每个模型一张卡片，三个字段：
+**怎么算的**：所有请求都必须经过 `127.0.0.1:18793` 的转发口（它是 pi-ai 路由的
+`baseURL`），转发口在透传 SSE 的同时旁路解析末块的 `usage`，因此不额外发请求、
+不改动流的内容。token 口径与上游一致：
 
-| 字段 | 含义 | 默认 |
-|---|---|---|
-| 上下文窗口 | 该模型声明给 Harness 的上下文长度 | `200000` |
-| 单次输出上限 | `max_tokens` | `32768` |
-| 图片输入 | 是否接受图片（关闭后图片以占位文字发给上游） | 开启 |
+| 面板列 | 来源 |
+|---|---|
+| 输入 | `usage.prompt_tokens` |
+| 输出 | `usage.completion_tokens` |
+| 命中缓存 | `usage.prompt_tokens_details.cached_tokens` |
+| 推理 | `usage.completion_tokens_details.reasoning_tokens` |
 
-改动写入插件的运行期配置，点「保存」立即生效，不用重启。校验从严：非正整数、
-输出上限大于上下文窗口都会被拒并显示原因。
+非 2xx 响应（403 限流、426 UA 被拒等）不解析 usage，但仍计一次**失败调用**，
+所以面板能区分「用了多少」和「被挡了多少」。
 
-也可以在 `cordis.patch.yml` 的挂载行直接写配置（页面改的是同一份设置）：
+**数据在哪**：`$DSH_HOME/zen-free-usage.json`（缺省 `~/.dsh/zen-free-usage.json`）。
+写盘做了 500ms 去抖，进程退出时补一次 flush。文件损坏或不存在时按空统计处理，
+绝不会因为统计把转发口搞挂。
 
-```yaml
-- insert:
-    - id: zenfree
-      name: 'dsh-zen-free'
-      config:
-        models:
-          ds4.1f:  { contextWindow: 200000, maxTokens: 32768, input: [text, image] }
-          glm5.3f: { contextWindow: 200000, maxTokens: 32768, input: [text] }
-```
+**接口**：`GET /zen-free/api` 取汇总、`POST /zen-free/api/reset` 清零。挂在宿主的
+webServer 上而不是转发口 —— 转发口在 18793、页面在 19387，跨源会被浏览器拦，
+也不该为一个只读面板放开 CORS。接口有 Host 回环校验与跨站拦截。
 
-`input` 里 `text` 始终保留（没有文本模态的模型在 Harness 里不可用），
-`image` 完全由配置决定。
+> ⚠️ 客户端面板（`lib/client.js`）属于**插件代码**，改动后需要重启一次 DSH 才生效；
+> 热重载只覆盖配置，不覆盖插件代码。重启后设置侧边栏才会出现「Zen 免费池统计」。
 
-### zenfree 统计
+## 它是怎么工作的
 
-进程内的请求统计，5 秒自动刷新一次：
+本插件**不实现 LlmAdapter**，只做两件事：
 
-- 请求总数 / 成功 / 失败 / 输入 tokens / 输出 tokens / 图片数；
-- 按模型分布（请求数、失败数、平均耗时、token 与图片数）；
-- 最近 20 次请求明细（时间、模型、结果、耗时、token）；
-- 错误码直方图（`RATE_LIMIT` / `TRANSPORT` / `EMPTY_RESPONSE` …）。
+1. 在 `127.0.0.1:18793` 起一个本地直连转发口，把请求用 `node:https` + 显式自建
+   `https.Agent` 转发到 `opencode.ai`（不读任何代理环境变量，也不复用进程级
+   undici dispatcher）。
+2. 通过**本包自己的** `cordis.patch.yml`，把 `opencode-zen` 声明成 `llm-pi-ai` 的一条
+   provider（`baseURL` 指向上面那个转发口），因此装完即用、无需手工配置。
 
-数据只在内存里，**进程重启清零** —— 它是「这次用得怎么样」的观察窗，不是持久账单。
+请求本身由官方 `llm-pi-ai` 适配器发出，所以设置页的编辑器对该路由完全可用。
 
-## 免费是怎么成立的
+**为什么必须走 pi-ai**：设置页的供应商编辑器只对 `llm-pi-ai` 与 `llm-deepseek`
+两个内置命名空间渲染可提交的表单；第三方插件自注册的命名空间一律是只读的
+`unknown` layout。
 
-OpenCode Zen 的免费池不校验密钥，只校验「你像不像 OpenCode 客户端」。三条准入规则：
+**为什么路由必须挂在那一个 entry 上**：`llm-pi-ai` 用 `ctx.fiber.entry.options.id`
+当设置命名空间，所以命名空间就是 entry id。想让它可编辑，entry id 必须正好是
+`llm-pi-ai` —— 因此**不能**另插一个 `llm-pi-ai` 的第二实例（换个 id 就掉进只读
+的 unknown layout）。
 
-1. `User-Agent` 能解析出 `opencode/<major>.<minor>.<patch>` 且 **≥ 1.18.0**
-   → 本插件固定发 `opencode/1.18.31`。
-2. `x-opencode-session` 必须是结构合法的 opencode 会话 id：
-   `ses_` + 12 位小写 hex + 14 位 base62，且那 12 位 hex 取反后低 12 位（counter）
-   **≤ 63**（时间戳那 36 位服务端不校验）→ 本插件每次请求新生成一个 counter = 1 的 id。
-3. 请求体 `tools` 必须同时声明 **`bash` / `glob` / `grep` / `read`** 四个名字
-   → 本插件把 Harness 自带的同名工具原样发出，缺的那个（Windows 上是 `bash`）补一个
-   占位条目（描述写明「本机不提供、不要调用」，因为服务端只看名字）。
+## 免费池的三条准入（2026-10-17 直连实测）
 
-## 强制直连是怎么做的
+| # | 条件 | 本插件怎么做 |
+|---|---|---|
+| 1 | `User-Agent` 解析出 `opencode/<x.y.z>` 且 **≥ 1.18.0** | 转发口注入 `opencode/1.18.31` |
+| 2 | `x-opencode-session` 是结构合法的会话 id：`ses_` + 12 位小写 hex + 14 位 base62，hex 取反后低 12 位（counter）≤ 63 | 转发口注入一个进程级固定 id；实测同一 id 可无限复用 |
+| 3 | 请求体 `tools` 非空**且含名为 `read` 的工具**（大小写敏感） | DSH 自带 `read`，pi-ai 原样发出，天然满足 |
 
-- 请求用 `node:https` 发出，并**显式传入自建 `https.Agent`**：
-  - 显式 agent 覆盖 Node `NODE_USE_ENV_PROXY`（`--use-env-proxy`）安装的默认 agent；
-  - `node:https` 本身不读 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`；
-  - 完全绕开 `globalThis.fetch` 走的 undici 全局 dispatcher —— 那正是 Harness
-    `dsh-http-proxy` 安装代理的入口。
-- 该 Agent 不带任何 `proxy` 选项，只做 TCP/TLS 直连 + keep-alive。
+> 旧版 README 说第 3 条要求同时声明 `bash`/`glob`/`grep`/`read` 四个名字，
+> **这是错的**。实测：只发 `read` → 200；只发 `bash`、`glob`、`grep` → 均 403；
+> 发五个任意名（`a`–`e`）→ 403。真正的要求是「含 `read`」。
 
 ## 已知限制
 
-- **占位 `bash` 工具**：准入只认名字，Harness 在 Windows 上没有 `bash`（只有 `pwsh`）。
-  若模型仍然去调用这个占位工具，Harness 会给出「未知工具」的工具结果。
-- **限流挂在出口 IP**：免费池按出口 IP / 账号限流，命中时失败码是 `RATE_LIMIT`（429）。
-- **地区限制**：部分免费模型对某些地区返回 `403 RegionError`。那与准入门槛无关，是另一道闸。
-- 未列出的模型 id 会**原样透传**到上游，因此也可以手输其它 `-free` 模型。
-- 设置页里的模型参数是**运行期配置**，重启 DSH 后回到 `cordis.patch.yml` 里写的值。
-  想永久生效就写进 patch 的 `config`。
+- **图片**：两个免费模型在默认配置里只声明 `text`。若上游实际支持图片，可在设置页
+  给模型勾上 image；但免费池模型大概率不收图，建议保持 text。
+- **限流挂在出口 IP**：命中时上游返回 429，由 `dsh-llm-retry` 按默认策略重试。
+- **地区限制**：部分免费模型对某些地区返回 `403 RegionError`，与准入门槛无关。
+- **端口占用**：转发口固定用 `18793`。若被占用，日志会报错，此时需改
+  `lib/index.js` 的 `RELAY_PORT` 与 profile 里 `baseURL` 的端口，两者保持一致。
 
 ## 结构
 
 | 文件 | 作用 |
 |---|---|
-| `lib/index.js` | 适配器 + 设置页的 host 侧服务（无第三方依赖，只用 `node:https` 与 `node:crypto`） |
-| `lib/client.js` | 设置页的浏览器侧（`__ModuleLoader__` 入口，`dsh.client` 声明） |
-| `cordis.patch.yml` | bundle patch：一条 loader 挂载行 |
-| `package.json` | 标准 DSH 插件包契约（`dsh.bundle.patch` + `dsh.client` + `files` + peer） |
-
-本包**不 import** 任何 `@deepseek-ai/*` 运行时包：第三方插件装在 profile 的
-`node_modules` 下，解析不到 asar 内的官方包。所需的 `LlmAdapter` 方法形状按契约实现，
-失败码则通过 Error 上的自有 `code` / `failure` 数据属性给出 —— Harness 的
-`normalizeLlmFailure` 专门采纳这条跨包副本路径（`AUTH` / `RATE_LIMIT` /
-`TRANSPORT` / `TIMEOUT` / `ABORTED` …）。
-
-设置页走 typert 的 Remote 通道：host 侧用 `ctx.typert.register()` 写入 invocation
-descriptor 并 `ctx.provide()` 一个带 `typertRemote` 绑定的服务，浏览器侧用同一套
-descriptor 通过 `ctx.remote.$mount()` 消费。两边的 descriptor 必须逐字段一致。
+| `lib/index.js` | 本地直连转发口（无第三方依赖，只用 `node:http` / `node:https` / `node:crypto`）+ 统计接口 |
+| `lib/usage.js` | 按模型累计调用次数与 token，落盘 `$DSH_HOME/zen-free-usage.json` |
+| `lib/client.js` | 浏览器半边：设置 → Zen 免费池统计 面板（`settings.section`） |
+| `cordis.patch.yml` | bundle patch：挂载插件 **+ 声明 `opencode-zen` 供应商路由**（两者缺一不可） |
+| `package.json` | 标准 DSH 插件包契约（`dsh.bundle.patch` + `dsh.client` + `exports["./client"]`） |
+
+路由的**默认值**来自本包 bundle 层；用户在设置页的改动写进 profile 层并覆盖它
+（cordis patch 对 `config` 整体赋值），因此本插件不会把默认值塞回去，删掉该路由
+也不会被重新加回。
+
+## 源码位置
+
+本包在 profile 的 `node_modules` 下，**`pnpm install` 会把它覆盖回 npm 上的版本**。
+改代码请改 `C:\Users\XIAOPAN\Desktop\dsh\dsh-zen-free-src`，再同步过来。

package/cordis.patch.yml

@@ -1,15 +1,63 @@
-# dsh-zen-free bundle patch — one loader entry mounting the plugin package.
+# dsh-zen-free bundle patch。
 #
-# 挂载行是普通的 cordis loader entry（id + 包名）。插件在 apply() 里向 llm
-# 服务注册 zenfree 路由，因此不需要任何 config。
+# 这里有两件事，缺一不可：
 #
-# 可选配置（全部可省略）：
-#   models:
-#     ds4.1f:  { contextWindow: 200000, maxTokens: 32768, input: [text, image] }
-#     glm5.3f: { contextWindow: 200000, maxTokens: 32768, input: [text, image] }
+#   1. 挂载插件本体（转发口 + 设置页「Zen 免费池统计」）。
+#   2. 往 `llm-pi-ai` 的 config 里补一条 `opencode-zen` 供应商路由。
 #
-# 手工挂载：把同一行加进 profile 的 cordis.patch.yml。
-# 标准安装：GUI 插件页安装框（installBundle 会自己读本文件）。
+# 为什么第 2 条必须写在这里：
+#   base 里 `llm-pi-ai` 是「mounted dormant」—— 零 provider 配置，装好也不出现任何
+#   模型，直到有配置提供 provider profile。官方注释的原话是「which providers run
+#   is the user's settings document」，即 provider 由设置层提供。本插件若不在这里
+#   提供，用户装完只会看到转发口和统计页，模型列表里什么都没有。
+#
+#   路由必须挂在 **id 为 `llm-pi-ai` 的那个 entry** 上：llm-pi-ai 用
+#   `ctx.fiber.entry.options.id` 当 settings 命名空间（见其 apply()），而 DSH 设置页
+#   只对命名空间 `llm-pi-ai` / `llm-deepseek` 渲染可提交的编辑器，其余一律渲染成
+#   只读的 unknown layout。所以不能再插第二个 llm-pi-ai 实例（换个 id 就不可编辑）。
+#
+# ⚠️ 两个已知语义（都是 cordis patch 的固有行为，不是本插件的 bug）：
+#
+#   a) patch 对顶层键是**整体赋值**，不做深合并。因此这一层设置的 `providers`
+#      会替换掉 base 层的值（base 是空的，无影响）。而 profile 层在 bundle 层**之后**
+#      应用，若用户手工在自己的 profile `cordis.patch.yml` 里写死了 `providers`
+#      且不含 `opencode-zen`，本插件的这条路由会被那一层整体覆盖掉。
+#      此时请把 `opencode-zen` 那段手工合并进自己的 `providers`。
+#      普通用户不会遇到：设置页保存时提交的是当前完整 provider 列表，天然包含本路由。
+#
+#   b) 用户在设置页对 OpenCode Zen 的任何改动都会写进 profile 层的同名 config，
+#      从而覆盖这里的默认值 —— 这正是期望行为，本插件不会再把默认值塞回去。
+#      删掉这条路由也不会被重新加回。
 - insert:
-    - id: zenfree
+    - id: dsh-zen-free-relay
       name: 'dsh-zen-free'
+
+- id: llm-pi-ai
+  name: '@deepseek-ai/dsh-llm-pi-ai'
+  config:
+    providers:
+      opencode-zen:
+        displayName: OpenCode Zen（免费）
+        api: openai-completions
+        baseURL: http://127.0.0.1:18793/zen/v1
+        # pi-ai 的 openai-completions 客户端在 getClientApiKey() 里要求
+        # 「有 apiKey」或「headers 带 authorization / cf-aig-authorization」，
+        # 否则直接抛 `No API key for provider`。免费池不需要密钥，所以放一个占位头
+        # 满足该断言；真实准入（UA + x-opencode-session）由 18793 转发口注入，
+        # 且转发口用白名单构造请求头，这个占位头不会传到上游。
+        headers:
+          authorization: Bearer zen-free
+        defaultContextWindow: 262144
+        defaultMaxTokens: 32768
+        defaultInput:
+          - text
+        models:
+          - id: deepseek-v4.1-flash-free
+            name: DeepSeek V4.1 Flash（免费）
+            input:
+              - text
+              - image
+          - id: glm-5.3-flash-free
+            name: GLM 5.3 Flash（免费）
+            input:
+              - text