dsh-model-pool 0.0.0-stage → 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# dsh-model-pool — DSH bundle patch.
+#
+# Inserts the Host half. The pool's preference is written back into this row's
+# `config` by the Settings page through the ordinary `settings.mutate` path,
+# e.g.
+#
+#   config:
+#     strategy: least-used
+#     fallback: true
+#     cooldownMs: 60000
+#
+# Every field is volatile, so edits apply to the running Host without a restart.
+- insert:
+    - id: model-pool
+      name: dsh-model-pool

package/docs/installation.md

@@ -0,0 +1,115 @@
+# Installing dsh-model-pool
+
+`dsh-model-pool` is a DeepSeek Harness bundle: one npm package that ships a Host half
+(`dsh.bundle.patch` → `index.js` + `lib/`) and a browser half (`dsh.client` →
+`client.js`). There is nothing to build and nothing to copy by hand — pick the install path
+that matches how you run DSH, restart, and the plugin is live.
+
+- Package: [`dsh-model-pool`](https://www.npmjs.com/package/dsh-model-pool) on
+  registry.npmjs.org (current version `0.1.0`, MIT).
+- Source: [github.com/BruceZhang1993/dsh-model-pool](https://github.com/BruceZhang1993/dsh-model-pool).
+- DeepSeek Harness: [github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).
+
+## Requirements
+
+| Requirement | Detail |
+|---|---|
+| DSH | DeepSeek Harness Desktop or the DSH CLI. The plugin is verified against the `0.2.x` Host generation (`@deepseek-ai/dsh-desktop-runtime` 0.2.1-rc.3). |
+| Node.js | **>= 20** (`engines` in `package.json`). |
+| Peer dependencies | `@deepseek-ai/dsh-llm` and `@deepseek-ai/schemastery` are provided by the Host; you do not install them yourself. |
+| Build tooling | None. No bundler, no runtime dependencies — the browser half is a hand-written `window.__ModuleLoader__` module that only `require('react')`s. |
+
+## DSH Desktop
+
+1. Open the **plugin manager** in Settings.
+2. Search the registry for `dsh-model-pool`.
+3. Install it, then **restart DSH Desktop**.
+
+The plugin manager resolves the package from npm, so there is no path or tarball to select.
+Installing a specific version is a matter of picking `0.1.0` in the same dialog when the
+manager offers versions.
+
+## CLI profiles
+
+`dsh plugin` installs into one profile. `web` is the usual profile name; substitute your own
+if you use a different one.
+
+```sh
+# latest release
+dsh plugin --profile web add dsh-model-pool
+
+# pin the current release
+dsh plugin --profile web add dsh-model-pool@0.1.0
+```
+
+What happens underneath: `dsh plugin` delegates to pnpm inside the profile directory, so the
+package lands in that profile's `node_modules`, and it adds the package to
+`dsh.profile.bundles` in the profile's `package.json` — that list is what makes DSH load the
+bundle at startup. **Restart the profile afterwards**; a running profile does not pick up a
+new bundle.
+
+## Local checkout
+
+For development, install the directory instead of the registry package:
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-model-pool
+```
+
+pnpm links the directory rather than copying it, so edits are picked up on the next restart
+— no republish, no `npm pack`. Use the absolute path; a relative one is resolved against the
+current shell directory and will not survive later restarts.
+
+If you want the same checkout installed under both halves of DSH (Desktop and CLI), install it
+in each target separately.
+
+## Verify the install
+
+1. **Settings → Model Pool** exists. It lists every pooled model with its provider count,
+   thinking depths, per-route state badges, the strategy selector, and the peak/idle card.
+2. The composer model picker contains a **Model Pool** provider; its models are the pooled
+   ones, each with a thinking-depth menu.
+3. Pick a pooled model and send a prompt. The composer dock shows the live route, for example
+   `实际路由  workbuddy  deepseek-v4.1-flash  max  DeepSeek V4.1 Flash`.
+4. Optional: a frozen or empty pool usually means no provider currently advertises models.
+   Check the provider rows in Settings → Model Pool, and remember that `include` /
+   `exclude` / `excludeModels` in `cordis.patch.yml` narrow what reaches the pool.
+
+If the bundle is installed but the page does not show it, restart the profile or Desktop
+first — the Host builds its plugin and route list at startup.
+
+## Troubleshooting
+
+**The bundle is not visible after `dsh plugin add`.**
+Restart the profile. Then check the profile's `package.json`: `dsh-model-pool` must appear in
+`dependencies`, and `dsh.profile.bundles` must list it. A package that is installed but not
+listed in `dsh.profile.bundles` is a normal npm dependency, not a loaded bundle. Re-running
+the `add` command repairs both in one step.
+
+**The plugin is installed but there is no Settings → Model Pool entry and no picker row.**
+Restart DSH, then open **Settings → Model Pool** directly to confirm whether the section is
+there. If it is still missing, the Host did not load the bundle: verify the entry in
+`dsh.profile.bundles`, confirm the Node.js version is 20 or newer, and check that the Host is
+the `0.2.x` generation the plugin targets.
+
+**The section renders but the pool has no models.**
+Pool models come from the providers DSH has registered. Confirm your providers advertise
+models, then review the `include`, `exclude` and `excludeModels` settings — an allowlist that
+names one provider excludes every other one.
+
+**The composer picker has no Model Pool row.**
+The virtual route is registered at startup. Restart the profile; if a second plugin replaced
+the model catalog, remove it and compare. Pooled models only appear when at least one
+concrete provider contributes a model.
+
+**Calls fail with a provider error.**
+That is the pool forwarding the last attempt's failure: every candidate failed. Settings →
+Model Pool shows each route's failure state and reason; **Reset health** clears the markers
+after you fix the provider. A route inside its cooldown is skipped while others are
+available, so a single failing provider does not break the pool.
+
+**The holiday calendar shows "failed" or stays stale.**
+Fetching is best-effort: routing keeps using the cached calendar, or the plain weekday rule
+before the first successful sync. Check network access to jsDelivr (and the
+`raw.githubusercontent.com` fallback) and press **Sync now** in the peak/idle card. Nothing
+about the pool breaks while the calendar is unavailable.

package/docs/installation.zh-CN.md

@@ -0,0 +1,107 @@
+# 安装 dsh-model-pool
+
+`dsh-model-pool` 是一个 DeepSeek Harness bundle：一个 npm 包里同时包含 Host 侧
+（`dsh.bundle.patch` → `index.js` + `lib/`）和浏览器侧（`dsh.client` →
+`client.js`）。没有任何东西需要构建，也没有文件需要手工拷贝 —— 选择与你运行 DSH 方式
+相符的安装路径，重启，插件即可生效。
+
+- 包：[npm 上的 `dsh-model-pool`](https://www.npmjs.com/package/dsh-model-pool)
+  （registry.npmjs.org，当前版本 `0.1.0`，MIT）。
+- 源码：[github.com/BruceZhang1993/dsh-model-pool](https://github.com/BruceZhang1993/dsh-model-pool)。
+- DeepSeek Harness：[github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)。
+
+## 环境要求
+
+| 要求 | 说明 |
+|---|---|
+| DSH | DeepSeek Harness 桌面版或 DSH CLI。插件已在 `0.2.x` Host 世代（`@deepseek-ai/dsh-desktop-runtime` 0.2.1-rc.3）上验证。 |
+| Node.js | **>= 20**（`package.json` 的 `engines`）。 |
+| peer 依赖 | `@deepseek-ai/dsh-llm` 与 `@deepseek-ai/schemastery` 由 Host 提供，无需自行安装。 |
+| 构建工具 | 不需要。没有打包器，也没有运行时依赖 —— 浏览器侧是手写的 `window.__ModuleLoader__` 模块，只 `require('react')`。 |
+
+## DSH 桌面版
+
+1. 打开设置中的**插件管理器**。
+2. 在注册表中搜索 `dsh-model-pool`。
+3. 安装，然后**重启 DSH 桌面版**。
+
+插件管理器从 npm 解析这个包，因此不需要选择路径或 tarball。要安装特定版本时，在同
+一个对话框里选择 `0.1.0` 即可（前提是管理器提供版本选择）。
+
+## CLI profile
+
+`dsh plugin` 把插件装进一个 profile。`web` 是常用的 profile 名；如果你用别的名字，
+替换即可。
+
+```sh
+# latest release
+dsh plugin --profile web add dsh-model-pool
+
+# pin the current release
+dsh plugin --profile web add dsh-model-pool@0.1.0
+```
+
+底层发生的事情：`dsh plugin` 在 profile 目录内委托给 pnpm，因此包会进入该 profile 的
+`node_modules`；同时它会把包加入 profile `package.json` 中的 `dsh.profile.bundles` ——
+正是这个列表让 DSH 在启动时加载该 bundle。**之后重启该 profile**；正在运行的 profile
+不会加载新的 bundle。
+
+## 本地检出
+
+开发时安装目录而不是注册表中的包：
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-model-pool
+```
+
+pnpm 会链接该目录而不是复制它，所以改动在下次重启后就生效 —— 不需要重新发布，也不
+需要 `npm pack`。请使用绝对路径；相对路径会基于当前 shell 目录解析，无法在后续重启
+中继续使用。
+
+如果你希望同一个检出差量同时装到 DSH 的两侧（桌面版和 CLI），请分别安装。
+
+## 验证安装
+
+1. **设置 → 模型池** 存在。它列出每个池内模型及其提供方数量、思考深度、逐路由状态标
+   记，以及策略选择器和峰谷时段卡片。
+2. 输入区的模型选择器里有 **Model Pool** 提供方；它的模型就是池内模型，每个都带思考
+   深度菜单。
+3. 选一个池内模型发送一条消息。输入区停靠栏会显示实际路由，例如
+   `实际路由  workbuddy  deepseek-v4.1-flash  max  DeepSeek V4.1 Flash`。
+4. 可选：池为空或冻结通常意味着当前没有任何提供方公布模型。检查设置 → 模型池里的提
+   供方行，并记住 `cordis.patch.yml` 中的 `include` / `exclude` / `excludeModels`
+   会限制能进入池的内容。
+
+如果 bundle 已安装但页面没有显示它，请先重启 profile 或桌面版 —— Host 在启动时构建
+插件与路由列表。
+
+## 故障排查
+
+**`dsh plugin add` 之后看不到该 bundle。**
+重启 profile。然后检查 profile 的 `package.json`：`dsh-model-pool` 必须出现在
+`dependencies` 中，且 `dsh.profile.bundles` 必须列出它。已安装但未列入
+`dsh.profile.bundles` 的包只是普通的 npm 依赖，不是已加载的 bundle。重新执行一次
+`add` 命令会同时修复这两处。
+
+**插件已安装，但没有 设置 → 模型池 条目，选择器里也没有对应行。**
+重启 DSH，然后直接打开**设置 → 模型池**确认该区块是否存在。如果仍然缺失，说明 Host
+没有加载这个 bundle：确认 `dsh.profile.bundles` 中的条目、确认 Node.js 版本为 20 或更
+高，并检查 Host 是否为插件所针对的 `0.2.x` 世代。
+
+**区块能渲染，但池里没有模型。**
+池内模型来自 DSH 已注册的提供方。确认你的提供方公布了模型，然后检查 `include`、
+`exclude` 和 `excludeModels` 设置 —— 只写了一个提供方的白名单会排除其余所有提供方。
+
+**输入区的模型选择器里没有 Model Pool 行。**
+这条虚拟路由在启动时注册。重启 profile；如果另一个插件替换了模型目录，移除它再对比。
+只有当至少一个具体提供方贡献模型时，池内模型才会出现。
+
+**调用以提供方错误失败。**
+那是池在转发最后一次尝试的失败：所有候选都失败了。设置 → 模型池会显示每条路由的失
+败状态与原因；修好提供方之后用**重置健康状态**清除标记。处于冷却期内的路由在还有其
+他可用路由时会被跳过，因此单个提供方故障不会搞垮整个池。
+
+**节假日日历显示“失败”或一直处于过期状态。**
+获取是尽力而为的：路由会继续使用缓存的日历，而在首次成功同步之前则使用单纯的星期规
+则。检查到 jsDelivr（以及 `raw.githubusercontent.com` 回退）的网络访问，并在峰谷时段
+卡片中按**立即同步**。日历不可用期间，池的其他功能不受影响。

package/icon.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Model Pool">
+  <defs>
+    <linearGradient id="mp-pool-stroke" x1="8" y1="6" x2="56" y2="58" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#4C8DFF"/>
+      <stop offset="1" stop-color="#2FC2A6"/>
+    </linearGradient>
+  </defs>
+  <path d="M32 6 L54.5 19 V45 L32 58 L9.5 45 V19 Z"
+        fill="url(#mp-pool-stroke)" fill-opacity="0.12"
+        stroke="url(#mp-pool-stroke)" stroke-width="3" stroke-linejoin="round"/>
+  <path d="M32 24 L23 42 M32 24 L41 42 M23 42 H41"
+        fill="none" stroke="url(#mp-pool-stroke)" stroke-width="2.2"
+        stroke-linecap="round" stroke-opacity="0.75"/>
+  <circle cx="32" cy="23" r="4.6" fill="url(#mp-pool-stroke)"/>
+  <circle cx="22.5" cy="43" r="4.6" fill="url(#mp-pool-stroke)" fill-opacity="0.85"/>
+  <circle cx="41.5" cy="43" r="4.6" fill="url(#mp-pool-stroke)" fill-opacity="0.7"/>
+</svg>