dsh-llm-fallbacks 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -9,10 +9,10 @@
 
 Automatic provider/model fallback chains for dsh (DeepSeek Harness): when an agent's LLM requests keep failing — retries exhausted, auth errors, quota exceeded, rate limiting (429) — the plugin switches provider/model along the fallback chain for the current role, and the current step/turn continues on the target model: tasks are not interrupted by model problems.
 
-Install with a single command (pnpm ≥ 10 needs one build-allow step — see [Install](#install)):
+Install with a single command (see [Install](#install)):
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit with #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # pin a version with @<version>
 ```
 
 ## Features
@@ -27,13 +27,31 @@ dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit
 
 ## Install
 
-### One-line git install
+### One-line install
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit with #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # pin a version with @<version>
 ```
 
-A git install fetches **sources, not built artifacts**, so the bundle builds itself on install (`prepare` self-build). The plugin is **mount-only**: it never modifies the dsh source tree, and no patch / postinstall step exists — dsh upgrades never require re-patching. pnpm ≥ 10 blocks a git dependency's `prepare` by default: the first `add` fails with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, and pnpm prints the exact package key. Allow the build in the profile's `pnpm-workspace.yaml` (`onlyBuiltDependencies: [dsh-llm-fallbacks]`, or run `dsh plugin --profile web approve-builds`), then re-run the `add`. Treat that allowance as permission to execute the package's code on your machine at install time, and pin a commit (`github:btspoony/dsh-llm-fallbacks#<sha>`) so a later push cannot silently change what runs. The full URL form works equivalently: `dsh plugin --profile web add https://github.com/btspoony/dsh-llm-fallbacks.git`.
+A registry install fetches the **built package** (`dist/`) — nothing is built on the target machine. The plugin is **mount-only**: it never modifies the dsh source tree, and no patch / postinstall step exists — dsh upgrades never require re-patching. Versioning follows npm dist-tags (`latest` by default); pin an exact version with `dsh plugin --profile web add dsh-llm-fallbacks@<version>`.
+
+> **Release status**: published as `dsh-llm-fallbacks@0.1.0-alpha.2` (latest). The first publish used a one-time `NODE_AUTH_TOKEN` bootstrap secret; Trusted Publishing is configured afterwards for tokenless releases.
+
+### Registry package (npm / pnpm)
+
+```sh
+npm install dsh-llm-fallbacks   # or: pnpm add dsh-llm-fallbacks
+```
+
+> Release process → [docs/release.md](docs/release.md).
+
+### Git install (works today)
+
+```sh
+dsh plugin --profile web add github:omdsh-dev/dsh-llm-fallbacks   # pin a commit with #<sha>
+```
+
+A git install fetches **sources, not built artifacts** — the bundle builds itself on install (`prepare` self-build), so the target machine needs node + pnpm. pnpm ≥ 10 blocks a git dependency's `prepare` by default (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`); allow the build in the profile's `pnpm-workspace.yaml` and re-run the `add` (details in [docs/install.md](docs/install.md)).
 
 ### Local directory install (recommended for development / verification)
 
@@ -77,7 +95,7 @@ fallbacks:
         role: reviewer
 ```
 
-Roles are declared entities: `roles.list` holds role cards (id/label/description + optional chain/fallback), and `roles.rules` match origin/provider/model in order to a declared role id or the built-in `inherit` (first match wins) — **no rule match → `inherit` → `rootChain`**. A declared role is only ever hit when a rule references it. The legacy chain-key namespace and role-default field are gone (migration table: [docs/configuration.md](docs/configuration.md)).
+Roles are declared entities: `roles.list` holds role cards (id/label/description + chain/fallback), and `roles.rules` match origin/provider/model in order to a declared role id or the built-in `inherit` (first match wins) — **no rule match → `inherit` → `rootChain`**. A declared role is only ever hit when a rule references it. A role without a chain is meaningless — the settings card blocks saving it and the host warns at startup; give every declared role a chain, or point its rules at the built-in `inherit`. (A hand-written YAML role with a missing/empty chain is not fatal: with `fallback: inherit-root` (the default) an empty chain still falls back to `rootChain`; with `fallback: none` an empty chain leaves no candidates and the request passes through untouched — either way it is only a startup warn.) The legacy chain-key namespace and role-default field are gone (migration table: [docs/configuration.md](docs/configuration.md)).
 
 Save and restart the web session for the changes to take effect. The feature switch `fallbacks.enabled` **defaults to off (`false`)** — the plugin only engages once it is turned on; `triggerCodes` defaults to `AUTH` / `QUOTA` / `RATE_LIMIT`; and with **no `rootChain`/role chains configured the behavior is identical to not having the plugin installed**. More examples (role entities, fallback strategies, rules referencing `inherit`) → [docs/configuration.md](docs/configuration.md).
 
@@ -103,7 +121,7 @@ The plugin installs as a **pure mount** — it never modifies the dsh source tre
   the Fallbacks card on the Settings → 插件配置 page, and settings read/write/reset
   go through the plugin's own gateway channel (`/api/fallbacks/get|set|reset`).
 - **No patches, no auto-apply step**: there are no dsh-body patch files and no install
-  lifecycle step that applies one. A one-line git install works as-is.
+  lifecycle step that applies one. A one-line registry install works as-is.
 - **dsh upgrades never require re-patching**: a dsh upgrade that resets the source
   tree changes nothing for this plugin — it keeps working without any re-apply step.
 - **Stale leftover patches are harmless**: the plugin never depends on a patch
@@ -111,12 +129,23 @@ The plugin installs as a **pure mount** — it never modifies the dsh source tre
   was removed), so a previously patched dsh tree can be left as-is or manually
   reverted — neither is required.
 
+## Developer consumption
+
+Beyond the dsh plugin mount, `dsh-llm-fallbacks` exposes a programmable consumer surface — both faces share the same function implementations (single point of truth, no copied logic):
+
+- **Library API**: import the runtime functions and types from the package root — `import { resolveRole, resolveChain, validateFallbacksConfig } from 'dsh-llm-fallbacks'`.
+- **Named cordis service**: while the plugin is applied, `ctx.get('llm-fallbacks')` returns a pure-function service (`{ name, version, resolveRole, resolveChain, validateFallbacksConfig, detectLegacyKeys }`); after the plugin is disposed it is `undefined`. Runtime state stays observable via `fallbacks/switch` events, not through the service.
+
+Full contract (export inventory, minimal examples, lifecycle, typing) → [docs/consumer-api.md](docs/consumer-api.md).
+
 ## Documentation
 
 | Doc | Content |
 |---|---|
-| [docs/install.md](docs/install.md) | profile install / git install / uninstall / `--dump-config` verification |
+| [docs/install.md](docs/install.md) | profile install / registry install / uninstall / `--dump-config` verification |
+| [docs/release.md](docs/release.md) | release process: Trusted Publishing setup, Release prep SOP, fragment format, rollback |
 | [docs/configuration.md](docs/configuration.md) | full `fallbacks` namespace reference, selector syntax, example YAML, plugin-config card usage, behavior notes |
+| [docs/consumer-api.md](docs/consumer-api.md) | developer consumption contract: export inventory, minimal examples, lifecycle, typing |
 | [docs/verification.md](docs/verification.md) | verification records (test matrix, bundle layer order, runtime contracts, QA gate script) |
 
 ## License

package/README.zh-CN.md

@@ -9,10 +9,10 @@
 
 dsh（DeepSeek Harness）的自动模型降级插件：当 root agent 或 subagent 的模型请求持续失败（重试耗尽、权限、配额超限、限流 429）时，按角色/模型 fallback 链自动切换 provider/model，当前 step/turn 在目标模型上继续完成——任务不因模型问题中断。
 
-一句话安装（pnpm ≥ 10 需一次构建放行，见 [安装](#安装)）：
+一句话安装（见 [安装](#安装)）：
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # 钉版本：加 @<version>
 ```
 
 ## 能力一览
@@ -27,13 +27,31 @@ dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：
 
 ## 安装
 
-### 一句话 git 安装
+### 一句话安装
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # 钉版本：加 @<version>
 ```
 
-git 安装拉取的是**源码而非构建产物**，安装时由包自行构建（`prepare` 自构建）。插件为**纯挂载**：对 dsh 源码树零修改，无任何补丁 / postinstall 步骤——dsh 升级无需重打。pnpm ≥ 10 默认不执行 git 依赖的 `prepare`：第一次 `add` 会失败并打印 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，同时给出精确的包 key。在该 profile 的 `pnpm-workspace.yaml` 中放行构建（`onlyBuiltDependencies: [dsh-llm-fallbacks]`，或运行 `dsh plugin --profile web approve-builds`），然后重跑 `add`。请把这次放行当作它本来的样子：允许该包代码在安装期于你的机器上执行——建议钉 commit（`github:btspoony/dsh-llm-fallbacks#<sha>`），防止后续 push 悄悄改变实际运行的代码。完整 URL 形式等价：`dsh plugin --profile web add https://github.com/btspoony/dsh-llm-fallbacks.git`。
+registry 安装拉取的是**已构建产物**（`dist/`），目标机无需构建。插件为**纯挂载**：对 dsh 源码树零修改，无任何补丁 / postinstall 步骤——dsh 升级无需重打。版本跟随 npm dist-tag（默认 `latest`）；钉精确版本：`dsh plugin --profile web add dsh-llm-fallbacks@<version>`。
+
+> **发布状态**：已发布 `dsh-llm-fallbacks@0.1.0-alpha.2`（latest）。首次发布用一次性 `NODE_AUTH_TOKEN` bootstrap；Trusted Publishing 后续配置为无 token 发布。
+
+### registry 包安装（npm / pnpm）
+
+```sh
+npm install dsh-llm-fallbacks   # 或：pnpm add dsh-llm-fallbacks
+```
+
+> 发布流程见 [docs/release.md](docs/release.md)。
+
+### git 安装（当前可用）
+
+```sh
+dsh plugin --profile web add github:omdsh-dev/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+```
+
+git 安装拉取的是**源码而非构建产物**——安装时由 `prepare` 自构建，目标机需要 node 与 pnpm。pnpm ≥ 10 默认拦截 git 依赖的 `prepare`（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`）；在 profile 的 `pnpm-workspace.yaml` 中放行构建后重跑 `add`（详见 [docs/install.md](docs/install.md)）。
 
 ### 本地目录安装（开发/验证推荐）
 
@@ -75,7 +93,7 @@ fallbacks:
         role: reviewer
 ```
 
-角色是声明式实体：`roles.list` 存放角色卡（id/label/description + 可选 chain/fallback），`roles.rules` 按 origin/provider/model 顺序匹配到**已声明角色 id 或内置 `inherit`**（首个命中即停）——**未命中 → `inherit` → `rootChain`**。只声明不写规则的角色永不命中。旧链键命名空间与角色兜底字段已删除（迁移表见 [docs/configuration.md](docs/configuration.md)）。
+角色是声明式实体：`roles.list` 存放角色卡（id/label/description + chain/fallback），`roles.rules` 按 origin/provider/model 顺序匹配到**已声明角色 id 或内置 `inherit`**（首个命中即停）——**未命中 → `inherit` → `rootChain`**。只声明不写规则的角色永不命中。角色无 chain 无意义——设置卡拦截保存、启动时告警；请为每个声明角色配置 chain，或让规则直接引用内置 `inherit`。（手写 YAML 角色链缺省/为空不致命：`fallback: inherit-root`（默认）时空链仍按防御语义回退 `rootChain`；`fallback: none` 时空链无候选 → no-op 透传；两种情况都仅启动告警。）旧链键命名空间与角色兜底字段已删除（迁移表见 [docs/configuration.md](docs/configuration.md)）。
 
 保存并重启 web 会话后生效。功能级开关 `fallbacks.enabled` **默认关闭（`false`）**——打开开关后插件才会介入；`triggerCodes` 默认覆盖 `AUTH` / `QUOTA` / `RATE_LIMIT`；**未配置任何 `rootChain`/角色链时行为与未安装插件完全一致**。更多示例（角色实体、fallback 策略、引用 `inherit` 的规则）见 [docs/configuration.md](docs/configuration.md)。
 
@@ -101,17 +119,28 @@ fallbacks:
   Fallbacks 卡片，设置读写/重置
   走插件自有 gateway 通道（`/api/fallbacks/get|set|reset`）。
 - **无补丁、无自动打补丁**：没有 dsh 本体 patch 文件，也没有任何安装期 apply 步骤；
-  一句话 git 安装即可用。
+  一句话 registry 安装即可用。
 - **dsh 升级永不需重打**：dsh 升级重置源码树对本插件无影响——无需任何重打步骤。
 - **残留旧补丁无害**：插件不依赖任何补丁导出（角色解析 rules-only；model-selection
   标记协调已移除）——已打过旧补丁的 dsh 树可原样保留或手动回滚，均非必需。
 
+## 开发者消费面
+
+除插件挂载外，`dsh-llm-fallbacks` 还暴露可编程消费面——两个入口共享同一函数实现（单点真相，无复制逻辑）：
+
+- **库 API**：从包根直接 import 运行时函数与类型——`import { resolveRole, resolveChain, validateFallbacksConfig } from 'dsh-llm-fallbacks'`。
+- **具名 cordis service**：插件 apply 期间 `ctx.get('llm-fallbacks')` 返回纯函数服务（`{ name, version, resolveRole, resolveChain, validateFallbacksConfig, detectLegacyKeys }`），插件 dispose 后为 `undefined`。运行态（冷却、最近切换）请读 `fallbacks/switch` 事件，不走服务对象。
+
+完整契约（导出清单、最小示例、生命周期、类型说明）见 [docs/consumer-api.md](docs/consumer-api.md)。
+
 ## 文档
 
 | 文档 | 内容 |
 |---|---|
-| [docs/install.md](docs/install.md) | profile 安装 / git 安装 / 卸载 / `--dump-config` 验证 |
+| [docs/install.md](docs/install.md) | profile 安装 / registry 安装 / 卸载 / `--dump-config` 验证 |
+| [docs/release.md](docs/release.md) | 发布流程：Trusted Publishing 前置、Release prep SOP、fragment 格式、回滚 |
 | [docs/configuration.md](docs/configuration.md) | `fallbacks` 命名空间全字段、selector 语法、示例 YAML、插件配置卡使用、行为说明 |
+| [docs/consumer-api.md](docs/consumer-api.md) | 开发者消费契约：导出清单、最小示例、生命周期、类型说明 |
 | [docs/verification.md](docs/verification.md) | 验证记录（测试矩阵、bundle 层序、运行契约、QA gate 剧本） |
 
 ## 许可

package/dist/client/ConversationFallbackSwitch.d.ts

@@ -74,13 +74,13 @@ export type ConversationFallbackSwitchProps = PropsRuntime<'conversation.chat.no
  * Render one fallback switch as a compact system-style transcript line.
  *
  * Geometry follows the upstream chat system rows (the compaction boundary
- * notice: dim title + separator + ellipsized summary — `chat/MessageItem
- * .module.css:38-122`); every color resolves through a `--dsw-alias-*`
- * token. A reason outside the current union renders raw (forward-compatible
+ * notice: warning-toned title + separator + ellipsized summary —
+ * `chat/MessageItem .module.css:38-122`); every color resolves through a
+ * `--dsw-alias-*` token. A reason outside the current union renders raw (forward-compatible
  * durable log, same rule as the card/general row summaries). A malformed or
  * partial payload (version skew) degrades to the title-only line instead of
- * throwing during interpolation — the transcript slot stays visible with a
- * truthful "a switch happened" notice and no summary details.
+ * throwing during interpolation — the transcript slot stays visible with the
+ * warning-toned "model downgraded" title (T1 copy) and no summary details.
  * @param props - composed keyed seat props.
  * @returns the switch line element tree.
  */

package/dist/client/FallbacksCard.d.ts

@@ -26,8 +26,9 @@
  * `roles.rules`, whose role field is a dropdown bound to the declared ids
  * + the built-in `inherit`, same-page live). Saving runs `validateDraft`
  * first — id format/reserved word/duplicates, undeclared rule role
- * references, and illegal selectors block the write with a validation
- * banner + inline red borders (never touching the store error path); a
+ * references, illegal selectors, and a role with no chain entries (no
+ * model config) block the write with a validation banner + inline red
+ * borders / hints (never touching the store error path); a
  * non-empty `state.legacyKeys` renders the migration banner at the top of
  * the card body. The row editors keep their filled editorCard surface
  * inside the card, with `--dsw-alias-*` tokens throughout. The reset-