dsh-zen-free 2.0.0 → 2.0.1

package/README.md

@@ -19,6 +19,16 @@
 
 未列出的 `-free` 模型 id 也可以手填进模型列表，会被原样透传到上游。
 
+**不需要任何手工配置。** 供应商路由由本包的 `cordis.patch.yml` 在 bundle 层声明
+（`base` 里 `llm-pi-ai` 是「mounted dormant」——零 provider，装好不出现任何模型，
+必须由某一层提供 profile 才有路由）。
+
+> ⚠️ **只有一个例外**：如果你**手工**在自己的 profile `cordis.patch.yml` 里写死了
+> `llm-pi-ai` 的 `providers`，那一层在 bundle 层之后应用，会**整体替换**掉本插件提供的
+> `opencode-zen`（cordis patch 对 `config` 是整体赋值，不做深合并）。
+> 此时请把 `opencode-zen` 那段一并合并进你自己的 `providers`。
+> 通过**设置页**增删 provider 的用户不会遇到这个问题：设置页提交的是当前完整列表。
+
 ## 用量统计
 
 **设置 → Zen 免费池统计**（独立一整页，不是「插件」下的标签页）显示：
@@ -59,8 +69,8 @@ webServer 上而不是转发口 —— 转发口在 18793、页面在 19387，
 1. 在 `127.0.0.1:18793` 起一个本地直连转发口，把请求用 `node:https` + 显式自建
    `https.Agent` 转发到 `opencode.ai`（不读任何代理环境变量，也不复用进程级
    undici dispatcher）。
-2. 通过 profile 的 `cordis.patch.yml` 把 `opencode-zen` 声明成 `llm-pi-ai` 的一条
-   provider，`baseURL` 指向上面那个转发口。
+2. 通过**本包自己的** `cordis.patch.yml`，把 `opencode-zen` 声明成 `llm-pi-ai` 的一条
+   provider（`baseURL` 指向上面那个转发口），因此装完即用、无需手工配置。
 
 请求本身由官方 `llm-pi-ai` 适配器发出，所以设置页的编辑器对该路由完全可用。
 
@@ -68,6 +78,11 @@ webServer 上而不是转发口 —— 转发口在 18793、页面在 19387，
 两个内置命名空间渲染可提交的表单；第三方插件自注册的命名空间一律是只读的
 `unknown` layout。
 
+**为什么路由必须挂在那一个 entry 上**：`llm-pi-ai` 用 `ctx.fiber.entry.options.id`
+当设置命名空间，所以命名空间就是 entry id。想让它可编辑，entry id 必须正好是
+`llm-pi-ai` —— 因此**不能**另插一个 `llm-pi-ai` 的第二实例（换个 id 就掉进只读
+的 unknown layout）。
+
 ## 免费池的三条准入（2026-10-17 直连实测）
 
 | # | 条件 | 本插件怎么做 |
@@ -96,11 +111,12 @@ webServer 上而不是转发口 —— 转发口在 18793、页面在 19387，
 | `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：一条 loader 挂载行 |
+| `cordis.patch.yml` | bundle patch：挂载插件 **+ 声明 `opencode-zen` 供应商路由**（两者缺一不可） |
 | `package.json` | 标准 DSH 插件包契约（`dsh.bundle.patch` + `dsh.client` + `exports["./client"]`） |
 
-`opencode-zen` 路由的配置写在 **profile 的** `cordis.patch.yml` 的 `llm-pi-ai`
-条目下（默认值层）。用户在设置页的改动写入 user 层并覆盖它，因此不会被本插件冲掉。
+路由的**默认值**来自本包 bundle 层；用户在设置页的改动写进 profile 层并覆盖它
+（cordis patch 对 `config` 整体赋值），因此本插件不会把默认值塞回去，删掉该路由
+也不会被重新加回。
 
 ## 源码位置
 

package/cordis.patch.yml

@@ -1,13 +1,63 @@
-# dsh-zen-free bundle patch — one loader entry mounting the plugin package.
+# dsh-zen-free bundle patch。
 #
-# 挂载行是普通的 cordis loader entry（id + 包名）。插件在 apply() 里起本地直连
-# 转发口，因此不需要任何 config。
+# 这里有两件事，缺一不可：
 #
-# loader id 不叫 opencode-zen —— 那是 llm-pi-ai 里 provider 的路由名，撞名会让
-# profile 配置难以阅读。这里用 dsh-zen-free-relay。
+#   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: 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-zen-free",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "OpenCode Zen 免费池供应商：把 opencode-zen 注册进设置 → 模型的供应商列表，可增删改模型、配置图片输入与上下文；无需 API Key，请求强制直连（不走任何代理）。附带「Zen 免费池统计」设置页，按模型累计调用次数与输入/输出/缓存 token。",
   "license": "MIT",
   "type": "module",