dsh-llm-fallbacks 0.1.2 → 0.1.4

package/README.md

@@ -6,6 +6,7 @@
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
 ![dsh](https://img.shields.io/badge/dsh-DeepSeek%20Harness%20compatible-4B32C3.svg)
+[![dshfind](https://dshfind.com/api/badge/omdsh-dev/dsh-llm-fallbacks?lang=en)](https://dshfind.com/zh/plugins/omdsh-dev/dsh-llm-fallbacks?ref=badge)
 
 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.
 
@@ -18,7 +19,7 @@ dsh plugin --profile web add dsh-llm-fallbacks   # pin a version with @<version>
 ## Features
 
 - **Automatic fallback for root and subagents**: any agent switches down the chain to the next available provider/model on model failure — no manual model switching.
-- **Two-block config**: block 1 `rootChain` — the root agent's single fallback chain (empty = root does not fall back); block 2 declared roles — `roles.list` role entities (id/label/description/chain/fallback) that `roles.rules` reference by id (or the built-in `inherit`); no rule match → `inherit` → `rootChain`.
+- **Two-block config**: block 1 `rootChain` — the root agent's single fallback chain (empty = root does not fall back); block 2 declared roles — `roles.list` role entities (id/persona/chain/fallback) that `roles.rules` reference by id (or the built-in `inherit`); no rule match → `inherit` → `rootChain`.
 - **Entry syntax**: chain entries are `provider/model` (exact switch) or `provider/*` (keep the failed model id, switch provider only) — the old chain-key namespace (provider/model keys, role-name keys) is gone.
 - **Cooldown and revert**: models that were switched away from / failed are not re-selected during the cooldown period; `revertPolicy: cooldown-expiry` automatically returns to the primary model when the cooldown expires, while `never` does not return within the session.
 - **Visible behavior**: every switch appends a persisted session event `fallbacks/switch` (from/to/role/reason), alongside info-level logs (candidate attempt order and skip reasons) and the read-only status block on the Settings → 插件配置 → Fallbacks card — no silent model switching.
@@ -35,7 +36,7 @@ dsh plugin --profile web add dsh-llm-fallbacks   # pin a version with @<version>
 
 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.
+> **Release status**: published as `dsh-llm-fallbacks@0.1.3` (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)
 
@@ -85,8 +86,7 @@ fallbacks:
   roles:                   # block 2: declare roles first, then let rules reference them
     list:
       - id: reviewer       # role entity: unique id (/^[a-z0-9-]{1,32}$/); "inherit" is reserved
-        label: Reviewer
-        description: Code-review subagents
+        persona: Code-review subagents
         chain:
           - openai/gpt-4o-mini
         fallback: inherit-root   # default: role chain, then append rootChain
@@ -95,7 +95,7 @@ fallbacks:
         role: reviewer
 ```
 
-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)).
+Roles are declared entities: `roles.list` holds role cards (id/persona + 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).
 

package/README.zh-CN.md

@@ -6,6 +6,7 @@
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
 ![dsh](https://img.shields.io/badge/dsh-DeepSeek%20Harness%20compatible-4B32C3.svg)
+[![dshfind](https://dshfind.com/api/badge/omdsh-dev/dsh-llm-fallbacks?lang=en)](https://dshfind.com/zh/plugins/omdsh-dev/dsh-llm-fallbacks?ref=badge)
 
 dsh（DeepSeek Harness）的自动模型降级插件：当 root agent 或 subagent 的模型请求持续失败（重试耗尽、权限、配额超限、限流 429）时，按角色/模型 fallback 链自动切换 provider/model，当前 step/turn 在目标模型上继续完成——任务不因模型问题中断。
 
@@ -18,7 +19,7 @@ dsh plugin --profile web add dsh-llm-fallbacks   # 钉版本：加 @<version>
 ## 能力一览
 
 - **root / subagent 自动降级**：任意 agent 在模型故障下按链切换到下一个可用 provider/model，无需手动换模型。
-- **两块制配置**：块 1 `rootChain`——root 主代理唯一降级链（空 = root 不降级）；块 2 声明式角色——`roles.list` 角色实体（id/label/description/chain/fallback）供 `roles.rules` 按 id 引用（或内置 `inherit`）；未命中规则 → `inherit` → `rootChain`。
+- **两块制配置**：块 1 `rootChain`——root 主代理唯一降级链（空 = root 不降级）；块 2 声明式角色——`roles.list` 角色实体（id/persona/chain/fallback）供 `roles.rules` 按 id 引用（或内置 `inherit`）；未命中规则 → `inherit` → `rootChain`。
 - **条目语法**：链条目为 `provider/model`（精确切换）或 `provider/*`（保留失败模型 id 仅换 provider）——旧链键命名空间（provider/model 键、角色名键）已删除。
 - **冷却与回主**：被切离/失败的模型在冷却期内不再入选；`revertPolicy: cooldown-expiry` 冷却到期后自动回主模型，`never` 会话内不回。
 - **行为可见**：每次切换追加持久化会话事件 `fallbacks/switch`（from/to/role/reason），配合 info 级日志（候选尝试顺序与跳过原因）与设置 → 插件配置 → Fallbacks 卡片上的只读状态块，无静默换模型。
@@ -35,7 +36,7 @@ dsh plugin --profile web add dsh-llm-fallbacks   # 钉版本：加 @<version>
 
 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 发布。
+> **发布状态**：已发布 `dsh-llm-fallbacks@0.1.3`（latest）。首次发布用一次性 `NODE_AUTH_TOKEN` bootstrap；Trusted Publishing 后续配置为无 token 发布。
 
 ### registry 包安装（npm / pnpm）
 
@@ -83,8 +84,7 @@ fallbacks:
   roles:                 # 块 2：先声明角色，再让规则引用
     list:
       - id: reviewer     # 角色实体：id 唯一（/^[a-z0-9-]{1,32}$/）；inherit 为保留字
-        label: 审查者
-        description: 代码审查子代理
+        persona: 代码审查子代理
         chain:
           - openai/gpt-4o-mini
         fallback: inherit-root   # 默认：角色链后追加 rootChain
@@ -93,7 +93,7 @@ fallbacks:
         role: reviewer
 ```
 
-角色是声明式实体：`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)）。
+角色是声明式实体：`roles.list` 存放角色卡（id/persona + 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)。
 

package/dist/client/fallbacks-store.d.ts

@@ -210,8 +210,7 @@ export declare function rowsToRootChain(rows: readonly RootChainRow[]): string[]
  */
 export interface RoleRow {
     id: string;
-    label: string;
-    description: string;
+    persona: string;
     selectors: ChainSelectorRow[];
     fallback: FallbackStrategy;
 }
@@ -263,7 +262,14 @@ export declare class FallbacksSettingsController {
     private readonly rpc;
     /** Snapshot consumed by the section through `useSyncExternalStore`. */
     readonly store: SnapshotStore<FallbacksSettingsState>;
-    private generation;
+    /** Read guard: a newer load() supersedes an older one's publish. */
+    private readGeneration;
+    /**
+     * Write guard: save()/resetToDefaults() completions ALWAYS publish unless
+     * dispose() invalidated them — an overlapping read must never discard a
+     * successful write's accept() (audit F1).
+     */
+    private writeGeneration;
     private catalogGeneration;
     private switchesGeneration;
     /** Every settings namespace from the last describe, keyed by ns — the configured-provider join's other input. */