@dan-ai-studio/dshopencodego 0.1.83 → 0.1.85

package/README.en.md

@@ -95,7 +95,7 @@ Configuration lives in the profile's `cordis.patch.yml`:
     baseURL: https://opencode.ai/inference/go/v1    # default (OpenCode Go endpoint)
                                               # http(s) only, and no query or fragment; writing ?x=1 is refused when the profile is saved
                                               # or https://opencode.ai/inference/v1 (Console main endpoint, pay-as-you-go/free models)
-    refreshMinutes: 60                        # live catalog TTL, 1 ~ 10080 (7 days)
+    refreshMinutes: 60                        # live catalog TTL, 1 ~ 10080 (7 days); stale past 24 hours it refreshes in the background anyway
     streamIdleTimeoutMs: 300000               # stream idle timeout: longest silence between events (ms)
     keepAliveTimeoutMs: 600000                # connection kept idle between requests (ms, 1 ~ 1800000)
                                                # the timer restarts on every answer, so a connection in
@@ -199,8 +199,9 @@ The gateway's `/v1/models` answers only *which* models exist, never *how* to cal
 - a model the provider **adds** appears on the next refresh; if no metadata source describes it, it is labelled as inferred and can be pinned with `modelProtocols`;
 - a model the provider **retires** disappears on the next refresh;
 - the bundled catalog is **frozen at the plugin's version** and affects only the quality of the "how to call it" decision, never *which* models exist.
+- **fresh installs do not wait**: the bundle carries a directory snapshot from publish time (`src/catalog/seed.snapshot.json`), which answers at once when the disk cache is empty and refreshes behind it; past 24 hours without a refresh counts as stale and refreshes in the background too, whatever the TTL says. A timer re-checks on a live host, so long-running processes stay current without a request to trigger it.
 
-When the gateway is **temporarily unavailable**, the plugin keeps the last listing that succeeded, marks it stale on the page, and retries in the background. The retry rate is governed by a **five-minute back-off** rather than by the TTL, so a gateway that comes back is picked up within five minutes; while it stays down it is asked once, not once per model request. The settings page's Recheck button revalidates at any time and is not bound by that back-off.
+When the gateway is **temporarily unavailable**, the plugin keeps the last listing that succeeded, marks it stale on the page, and retries in the background. The retry rate is governed by a **five-minute back-off** rather than by the TTL, so a gateway that comes back is picked up within five minutes; while it stays down it is asked once, not once per model request. When the settings page opens on a stale reading, it follows up on its own (about every 5 seconds) until the reading turns current — the follow-ups are cheap local reads, and the host's back-off still decides when the gateway is really asked — so there is no need to press Recheck by hand. The settings page's Recheck button revalidates at any time and is not bound by that back-off.
 
 The only thing that waits on a plugin release is a missing wire quirk in the pi-ai catalog (DeepSeek's `thinkingFormat`, say) — the model itself is already usable.
 
@@ -285,17 +286,19 @@ npm run lint        # oxlint: static checks (the release workflow runs this too,
 npm run typecheck   # both halves: host and client
 npm run build       # build first: emits lib/index.js and lib/client.js
 npm test            # contract tests against a real local HTTP mock gateway
+npm run seed        # refresh the bundled catalog seed before a release (see "Releasing")
 ```
 
 **Order matters**: `npm run build` must come before `npm test` — `tests/pack-contents.spec.ts` walks every `exports` target, and whether `lib/` exists decides whether that check runs or is silently skipped (it does not fail, it just stops protecting you). `package.json` no longer carries `prepare`, so `npm ci` will not build for you; all three CI workflows run `npm run build` explicitly.
 
-The suite covers configuration validation, the protocol ladder, gateway and online metadata, the catalog projection, the adapter on the wire (all three protocols), Remote contracts and services, session-header invariants, usage windows and the meter, the client controller and usage pill, both halves' mounting and registration, the error mapping for stream idle timeouts and aborts, the exit-code contract of the verification scripts, and several **structural invariants** (inject declarations match the source's reads, peer coverage holds both ways, the READMEs match the manifest, and the READMEs' claims about the upstream match the upstream actually installed). That is **59 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
+The suite covers configuration validation, the protocol ladder, gateway and online metadata, the catalog projection, the adapter on the wire (all three protocols), Remote contracts and services, session-header invariants, usage windows and the meter, the client controller and usage pill, both halves' mounting and registration, the error mapping for stream idle timeouts and aborts, the exit-code contract of the verification scripts, and several **structural invariants** (inject declarations match the source's reads, peer coverage holds both ways, the READMEs match the manifest, and the READMEs' claims about the upstream match the upstream actually installed). That is **60 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
 
 ## Releasing (maintainers)
 
 1. **Version**: align `package.json`'s `version` with the tag you are about to push (`v<version>`); CI checks the asset name against the tag.
-2. **GitHub Release**: commit and push `main`, then push the tag. `release.yml` runs the tests, `npm pack`s, and uploads the tarball as the release asset.
-3. **npm (trusted publishing / OIDC, no token)**: `.github/workflows/publish-npm.yml` is manual-only and authenticates through GitHub Actions' OIDC — this repository **has no `NPM_TOKEN` and needs none**. Run it with:
+2. **Seed**: run `npm run seed` to refresh `src/catalog/seed.snapshot.json` (public endpoints, no key) and commit it, so fresh installs start with a usable catalog.
+3. **GitHub Release**: commit and push `main`, then push the tag. `release.yml` runs the tests, `npm pack`s, and uploads the tarball as the release asset.
+4. **npm (trusted publishing / OIDC, no token)**: `.github/workflows/publish-npm.yml` is manual-only and authenticates through GitHub Actions' OIDC — this repository **has no `NPM_TOKEN` and needs none**. Run it with:
 
    ```sh
    gh workflow run publish-npm --repo dan-ai-studio/dshopencodego -f tag=v<version>

package/README.md

@@ -95,7 +95,7 @@ DSH 桌面端是 Electron 壳 + 完整的 dsh Web 应用，本插件对它同样
     baseURL: https://opencode.ai/inference/go/v1    # 默认值（OpenCode Go 端点）
                                               # 只能是不带 query / fragment 的 http(s) 地址；写 ?x=1 会在保存配置时被拒
                                               # 也可指定为 https://opencode.ai/inference/v1（Console 主端点，含按量/免费模型）
-    refreshMinutes: 60                        # 目录缓存时长，1 ~ 10080（7 天）
+    refreshMinutes: 60                        # 目录缓存时长，1 ~ 10080（7 天）；超过 24 小时未刷新会被视为过期并在后台更新
     streamIdleTimeoutMs: 300000               # 流空闲超时：两次流事件之间的最长静默（毫秒）
     keepAliveTimeoutMs: 600000                # 连接空闲保留：两次请求之间连接留多久（毫秒，1 ~ 1800000）
                                                # 每次收到回答后重新计时，所以常用时连接不会被断开；
@@ -198,8 +198,9 @@ API Key 通过 Harness 凭证库提供（引用名 `OPENCODE_GO_API_KEY`），
 - 官方**新增**模型 → 下次刷新即出现，协议/容量若不在内置目录中则标为"推断"并可被 `modelProtocols` 覆盖；
 - 官方**下线**模型 → 下次刷新即消失；
 - 内置目录**冻结**在插件版本里，仅影响"怎么调"的推断质量，不影响"有哪些"。
+- **首次安装不等待**：包里带了一份发布时生成的目录快照（`src/catalog/seed.snapshot.json`，28 个模型上下），磁盘缓存为空时直接用它回答并在后台刷新；过期（超 24 小时未刷新）同样后台刷新，绝不为等网络拦住请求。插件挂载后还会定时触发一次，保证长期运行的进程目录常新。
 
-网关**临时不可用**时，插件保留上次成功获取的列表并在页面上标注陈旧，同时在后台重试：重试由**5 分钟的退避**控制，而不是等满一个 TTL，所以网关恢复后 5 分钟内列表就会更新；网关持续不可用时，它只被问一次，不会每次模型请求都去问一遍。设置页的「重新检查」随时可以强制重验，不受这个退避限制。
+网关**临时不可用**时，插件保留上次成功获取的列表并在页面上标注陈旧，同时在后台重试：重试由**5 分钟的退避**控制，而不是等满一个 TTL，所以网关恢复后 5 分钟内列表就会更新；网关持续不可用时，它只被问一次，不会每次模型请求都去问一遍。设置页打开时若读到的是旧目录，会自动跟进重读直到拿到最新的（约每 5 秒一次读本地快照；何时真问网关由 Host 的 5 分钟退避决定，不会因此多发请求），不用手动点「重新检查」；「重新检查」随时可以强制重验，不受这个退避限制。
 
 只有当 pi-ai 内置目录**缺了某个模型的线怪癖**（如 DeepSeek 的 `thinkingFormat`）时，才需要等插件同步 pi-ai 的新版本——而模型本身早已可用。
 
@@ -284,17 +285,19 @@ npm run lint        # oxlint：静态检查（发布流程也会跑，失败即
 npm run typecheck   # host 与 client 两半
 npm run build       # 先构建：产出 lib/index.js 与 lib/client.js
 npm test            # 契约测试：真实 HTTP mock 网关，断言请求头/体、目录阶梯、用量
+npm run seed        # 发版前刷新捆绑的目录种子（见「发布」）
 ```
 
 **顺序有讲究**：`npm run build` 要排在 `npm test` 之前——`tests/pack-contents.spec.ts` 会遍历 `exports` 的每个目标，`lib/` 存在与否决定这条检查是执行还是被跳过（不报错，但会少一层保护）。`package.json` 已移除 `prepare`，因此 `npm ci` 不会再替你隐式构建；三个 CI workflow 都显式跑了 `npm run build`。
 
-测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **59 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
+测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **60 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
 
 ## 发布（维护者）
 
 1. **版本**：把 `package.json` 的 `version` 与即将打出的 tag 对齐（`v<版本>`）。CI 会校验资产名与 tag。
-2. **GitHub Release**：提交并推送 `main`，打 tag 推送。`release.yml` 会跑测试、`npm pack` 并把 tarball 作为 Release 资产上传。
-3. **npm（Trusted Publishing / OIDC，无需令牌）**：`.github/workflows/publish-npm.yml` 仅手动触发，认证走 GitHub Actions 的 OIDC——本仓库**没有也不需要** `NPM_TOKEN`。运行方式：
+2. **种子**：运行 `npm run seed` 刷新 `src/catalog/seed.snapshot.json`（公开接口，无需 key）并一并提交，让新装用户开箱即有目录可用。
+3. **GitHub Release**：提交并推送 `main`，打 tag 推送。`release.yml` 会跑测试、`npm pack` 并把 tarball 作为 Release 资产上传。
+4. **npm（Trusted Publishing / OIDC，无需令牌）**：`.github/workflows/publish-npm.yml` 仅手动触发，认证走 GitHub Actions 的 OIDC——本仓库**没有也不需要** `NPM_TOKEN`。运行方式：
 
    ```sh
    gh workflow run publish-npm --repo dan-ai-studio/dshopencodego -f tag=v<版本>

package/lib/client.js

@@ -31,6 +31,7 @@ var BACKGROUND_RETRY_BACKOFF_MS = 5 * 6e4;
 var MODEL_LISTING_MAX_BYTES = 1024 * 1024;
 var MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;
 var UNKNOWN_MODEL_PROBE_COOLDOWN_MS = 5 * 6e4;
+var MAX_CATALOG_STALENESS_MS = 24 * 60 * 6e4;
 
 // src/catalog/metadata.ts
 var INPUT_MODALITIES = ["text", "image", "audio", "video", "pdf"];
@@ -1048,6 +1049,7 @@ var section_default = { "badge": "d7lz0W_badge", "block": "d7lz0W_block", "butto
 var import_jsx_runtime = require("react/jsx-runtime");
 var API_KEY_REF = "OPENCODE_GO_API_KEY";
 var VISIBILITY_WRITE_DELAY_MS = 250;
+var FOLLOW_UP_MS = 5e3;
 var INITIAL = {
   loading: true,
   reading: void 0,
@@ -1098,6 +1100,8 @@ var SectionController = class _SectionController {
   pendingVisibility;
   /** Timer of the coalescing window, when one is armed. */
   visibilityTimer;
+  /** The armed stale-reading follow-up, if one is waiting. */
+  followTimer;
   constructor(services) {
     this.services = services;
     const scope = services.scope;
@@ -1125,6 +1129,10 @@ var SectionController = class _SectionController {
   dispose() {
     this.listeners.clear();
     for (const dispose of this.disposers.splice(0)) dispose();
+    if (this.followTimer !== void 0) {
+      clearTimeout(this.followTimer);
+      this.followTimer = void 0;
+    }
     const scope = this.services.scope;
     if (this.visibilityTimer !== void 0 && scope !== void 0) void this.flushVisibility(scope);
   }
@@ -1139,6 +1147,7 @@ var SectionController = class _SectionController {
       const result = refresh ? await this.services.remote.opencodeGoCatalog.refresh() : await this.services.remote.opencodeGoCatalog.read();
       if (!result.ok) throw result.error;
       this.set({ loading: false, reading: result.value, failure: void 0 });
+      if (result.value.cached === true) this.followReading();
     } catch (error) {
       this.set({
         loading: false,
@@ -1146,6 +1155,35 @@ var SectionController = class _SectionController {
       });
     }
   }
+  /**
+   * Re-read a stale reading until it turns live, then stop.
+   *
+   * Only one follow-up is ever armed. The Host decides the real refresh
+   * rhythm, so this never hammers the gateway — a follow-up is a plain
+   * `read`, and the Host's own back-off decides how often the gateway is
+   * really asked. A failed or still-stale read re-arms; only a live reading
+   * or a disposal lets it lapse.
+   */
+  followReading() {
+    if (this.followTimer !== void 0) return;
+    const timer = setTimeout(() => {
+      this.followTimer = void 0;
+      void (async () => {
+        try {
+          const result = await this.services.remote.opencodeGoCatalog.read();
+          if (result.ok) {
+            this.set({ reading: result.value, failure: void 0 });
+            if (result.value.cached !== true) return;
+          }
+        } catch {
+        }
+        this.followReading();
+      })();
+    }, FOLLOW_UP_MS);
+    const releasable = timer;
+    if (typeof releasable.unref === "function") releasable.unref();
+    this.followTimer = timer;
+  }
   async loadKey() {
     try {
       const described = await this.services.remote.credentials.describe([API_KEY_REF]);