dsh-llm-fallbacks 0.6.1 → 0.6.3

package/README.md

@@ -42,7 +42,7 @@ dsh plugin --profile web add dsh-llm-fallbacks      # web profile (Settings →
 dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui terminal profile
 ```
 
-Same plugin, either front end — the only difference is the `--profile` flag. Pin a version with `@<version>`. A registry install fetches the **built package** (`dist/`), nothing builds on the target machine. Registry / git / local-directory variants, uninstall, and `--dump-config` verification → [docs/install.md](docs/install.md).
+Same plugin, either front end — the only difference is the `--profile` flag. Pin a version with `@<version>`. A registry install fetches the **built package** (`dist/`), nothing builds on the target machine. Registry / git / local-directory variants, uninstall, and `--dump-config` verification → [docs/install.md](docs/install.md). The plugin ships **localized metadata** (title/description for the Plugins-page detail view, English + 简体中文) and an **icon** — both declared in the package (`locale/*.json` + `icon.svg`) and picked up by the host automatically.
 
 ### Configuration surfaces
 
@@ -62,7 +62,6 @@ Add a `fallbacks:` section to the shared settings document (`$DSH_HOME/settings.
 
 ```yaml
 fallbacks:
-  enabled: true            # feature switch — defaults to off (plugin is a no-op otherwise)
   rootChain:               # all-day chain: leading entries = fallback walk, last = Default model (official)
     - anthropic/claude-3-5-sonnet          # walked first
     - deepseek-official/deepseek-flash  # last resort (Flash or Pro)
@@ -91,7 +90,7 @@ fallbacks:
 
 Build the section up in four steps:
 
-**1. Enable the plugin.** `enabled: true` turns the fallback engine on. It defaults to **off** — with no chains configured the plugin is a complete no-op.
+**1. Configure content.** There is **no feature switch** in the section — the plugin intervenes exactly when something is configured: a non-empty `rootChain`, at least one `timeSlots` row, or one declared role. An empty section is a complete no-op, and the Plugins-page row toggle is the master switch (disabling the plugin row stops it entirely).
 
 **2. Set the all-day `rootChain`.** Leading entries are the fallback chain, walked first when a request fails; the **last** entry is the Default model.
 
@@ -103,7 +102,7 @@ Build the section up in four steps:
 
 Full reference (role entities, fallback strategies, rules, selectors, preset roles, time-slot presets) → [docs/configuration.md](docs/configuration.md).
 
-> **Upgrade note (behavior change)**: an existing `fallbacks:` section **without an explicit `enabled` key** resolves to `false` after upgrading — add `enabled: true` to keep the plugin active.
+> **Upgrade note (breaking, behavior change)**: the config-level `enabled` switch is **removed** — a stored section still carrying `enabled: true/false` loads cleanly (the key is ignored and stripped on the next save), but the switch no longer gates anything. If you relied on `enabled: false` to keep the plugin inert, empty the section (or disable the plugin row on the Plugins page) instead.
 
 ### Verify
 
@@ -185,7 +184,7 @@ The durable fix belongs upstream at the migration edges (the frozen V0→V1 edge
 
 - **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**: `rootChain` for the root agent; declared role entities (`roles.list`) referenced by `roles.rules` (or the built-in `inherit`).
-- **Chain as root primary from the picker**: when `enabled` is on, the host model picker (web and TUI alike) shows a virtual `FallbacksChain` / `Auto` row — selecting it uses the configured chain as the root primary (a conforming all-day head is required for the delegation to succeed); selecting a real model keeps fallback-only (see [FallbacksChain in the model picker](#fallbackschain-in-the-model-picker)).
+- **Chain as root primary from the picker**: whenever the plugin has content configured, the host model picker (web and TUI alike) shows a virtual `FallbacksChain` / `Auto` row — selecting it uses the configured chain as the root primary (a conforming all-day head is required for the delegation to succeed); selecting a real model keeps fallback-only (see [FallbacksChain in the model picker](#fallbackschain-in-the-model-picker)).
 - **Time slots**: optional `fallbacks.timeSlots` rows rotate the effective root chain by wall-clock windows in the config-level `tz` timezone (default `Asia/Shanghai`) — four frozen UTC+8 presets (`liang-peak` / `liang-valley` / `glm-peak` / `glm-valley`, windows are code constants, models-only edits) or custom `start`/`end`/`days` windows. The first matching row wins; the all-day row is always last. A slot change applies on the **next** root request and is logged as a **time-slot switch** — a routing seed, never a failure decision: it consumes no cooldown and does not count against `maxSwitchesPerStep`. Failure walks keep the **fallback switch** copy (see [Time-slot presets](#time-slot-presets)).
 - **Dispatch-time role resolution**: on a subagent's first request its role is resolved in three stages — explicit (`agentPreset` matches a declared role id) → deterministic rules (matching either the recorded pair or the served head — see [FallbacksChain in the model picker](#fallbackschain-in-the-model-picker)) → LLM auto-match from the declared role taxonomy (`fallbacks.roleAutoMatch`, default `true`). The resolved role's chain-head model is injected into the first request and recorded via an explicit `role → model` log line (no durable `fallbacks/switch` event is written — issue #52 stop-write); set `roleAutoMatch: false` to disable the LLM auto-match stage (the explicit `agentPreset` stage still applies — with no explicit role this reproduces the previous rules-only behavior). The settings card always renders an **Enable role auto-match** switch (default `true`) to toggle it — the schema default applies even to legacy configs that never declared the key.
 - **Role persona on the child (chain-independent)**: when a subagent's dispatch declares a role this plugin knows (the `**Execute as**: <id>` field of its Assignment), that role's `persona` is installed on the child as its own persona — the role is the child's identity, not only a routing decision, and delivery does not depend on routing: a role with an empty `chain` gets its persona exactly like a chained one (the chain only picks the model). A persona the caller already set is never overwritten; a provider that cannot carry a persona skips it and the dispatch runs natively.
@@ -197,7 +196,7 @@ The durable fix belongs upstream at the migration edges (the frozen V0→V1 edge
 - **Half-open recovery (opt-in)**: `recovery: half-open` makes recovery evidence-driven — an expired cooldown leaves the route half-open for one logged probe instead of restoring the preference; consecutive failures escalate the suppression duration (×2 per failure, capped at 1 h); an observed completion closes the circuit and fully restores the preference. `revertPolicy: 'never'` keeps the mechanism inert; state is session-scoped in-memory (a restart resets). YAML-only — the default `timer` keeps every existing behavior byte-identical (see [docs/configuration.md](docs/configuration.md#recovery-mode-recovery-key)).
 - **Visible behavior**: every switch is recorded in an info-level log line (from/to/role/reason) — no silent model switching. The plugin deliberately writes **no** durable `fallbacks/switch` session events (issue #52: the apply()-time event-type registration was proven ineffective, and a session containing the event refused to load after a dsh restart). Sessions written by older plugin versions that contain such events **cannot** be repaired by an `ignorable` flag — the released session-format migration chain (v0→v1) refuses unknown event types even when marked ignorable — so `pnpm repair:session-logs` reports them (and recovers them only with the opt-in lossy `--drop-legacy-events` — see [Repair existing sessions](#repair-existing-sessions)).
 - **Safety valves**: `maxSwitchesPerStep` caps switches per step and `alwaysModeRetryCap` caps always-mode retries — chain loops cannot amplify latency.
-- **No-config no-op**: with no chains configured the plugin behaves exactly like not being installed (`enabled` is off by default — see [Minimal configuration](#minimal-configuration)).
+- **No-config no-op**: with nothing configured the plugin behaves exactly like not being installed — content presence is the gate (see [Minimal configuration](#minimal-configuration)).
 
 ## dsh-tui profile (terminal)
 
@@ -205,7 +204,7 @@ In a dsh-tui profile the plugin has three operator surfaces, with a strict duty
 
 - **`/fallbacks`** — what happened this session: origin, resolved role, effective chain, recent fallback switches, cooldown status (half-open marker rows when `recovery: half-open` is active). Read-only.
 - **`/fallbacks config`** — what is configured: composed-config readback (trigger codes, root chain, time slots, timezone, roles, role rules, cooldown, revert policy, safety valves, presets, role auto-match). Read-only apart from the one action command **`/fallbacks config revert-seed <role-id>`**, which restores a seeded role's persona to its declared seed default — the web settings card presents seeded personas read-only (no revert affordance), so the command is that action's only surface.
-- **`/settings`** — the edit surface. The plugin registers a **fallbacks** section with full parity to the web settings card: booleans (`enabled`, `roleAutoMatch`) render as toggles, selects (`presets`, `revertPolicy`) as pickers, and numbers (`cooldownMs`, `maxSwitchesPerStep`, `alwaysModeRetryCap`) as numeric inputs; complex structures (`rootChain`, `timeSlots`, `roles.list`, `roles.rules`) are JSON text fields and `triggerCodes` a comma-separated text field. Invalid drafts (bad JSON, non-conforming chains, malformed time-slot rows) block the save — the section never corrupts the config.
+- **`/settings`** — the edit surface. The plugin registers a **fallbacks** section with full parity to the web settings card: booleans (`roleAutoMatch`) render as toggles, selects (`presets`, `revertPolicy`) as pickers, and numbers (`cooldownMs`, `maxSwitchesPerStep`, `alwaysModeRetryCap`) as numeric inputs; complex structures (`rootChain`, `timeSlots`, `roles.list`, `roles.rules`) are JSON text fields and `triggerCodes` a comma-separated text field. Invalid drafts (bad JSON, non-conforming chains, malformed time-slot rows) block the save — the section never corrupts the config.
 
 **Requirements**: the `/settings` fallbacks section needs **dsh-tui ≥ v0.8.5** (commit `c51661f` or later on `main`; the settings seam shipped in v0.8.0, the groups shape + validation in v0.8.5). On an older dsh-tui the section is absent, and file editing remains the only TUI edit surface.
 
@@ -213,7 +212,7 @@ File editing still works everywhere: the shared `$DSH_HOME/settings.yaml` (`fall
 
 ## FallbacksChain in the model picker
 
-When `enabled: true`, the plugin registers a virtual provider, **FallbacksChain**, with a single catalog row: **Auto**. The web profile and dsh-tui both see the row: they share the same adapter catalog, so the row needs no settings-page wiring or host patch (it is independent of the `/settings` fallbacks section, which edits configuration rather than the picker catalog). The row is visible whenever the plugin is enabled — a legacy or empty all-day chain does NOT hide it (the delegate just refuses to serve it).
+Whenever the plugin has content configured (a non-empty `rootChain`, at least one `timeSlots` row, or one declared role), it registers a virtual provider, **FallbacksChain**, with a single catalog row: **Auto**. The web profile and dsh-tui both see the row: they share the same adapter catalog, so the row needs no settings-page wiring or host patch (it is independent of the `/settings` fallbacks section, which edits configuration rather than the picker catalog). A legacy or empty all-day chain does NOT hide the row as long as other content is configured (the delegate just refuses to serve it); with nothing configured there is no row.
 
 Selecting **FallbacksChain / Auto** uses the configured chain as the root **primary**: the request stays on the virtual pair and the adapter's thin delegate dispatches the effective chain's first exact `provider/model` at request time, so the fallback engine degrades from that head as usual. Serving the selection unchanged (instead of rewriting the route to the head) is also what keeps the host's model-change notice quiet: the recorded route equals the session selection, so the notice appears once on a genuine selection change rather than being re-armed on every step. Selecting any real catalog model keeps the v0.2.2 fallback-only behavior — the session model is primary and the chain engages only after it fails.
 
@@ -223,8 +222,8 @@ Notes:
 
 - **Picker label**: the row's catalog `name` (what the composer trigger shows) is live — `Auto: DeepSeek Flash[Liang Peak]` / `Auto: DeepSeek Flash[all-day]` (catalog display name, not the model id); the id stays `Auto`. Bare `Auto` if the all-day tail is not conforming. Refresh by reopening the picker.
 - **Thin delegate on every origin**: the row is served by the same `stream()` delegate for the root agent and for a subagent session that inherits the selection — subagent role resolution and injection keep their semantics apart from one deliberate widening: dispatch-time rule matching accepts **either** the recorded pair or the served head (a superset of the previous matching, so a rule keyed on the real head keeps matching), and the virtual row is never a second routing engine. A subagent that inherits the selection still routes through the chain head.
-- **Conformance gate on the tail**: a successful delegation requires the all-day chain to be **tail-conforming** — its last entry must be exactly one official model (`deepseek-official/deepseek-flash` or `deepseek-official/deepseek-v4-pro`, the card's Default model panel); leading entries (Default fallback chain) are walked first. Disabling the plugin hides the row again (slot-row/chain edits never churn registration).
-- **Stale selection**: if the row disappears (plugin disabled) while `FallbacksChain / Auto` is selected, the session keeps showing it as the current model with `routable: false` — pick a real model from the catalog to continue (host-native catalog semantics).
+- **Conformance gate on the tail**: a successful delegation requires the all-day chain to be **tail-conforming** — its last entry must be exactly one official model (`deepseek-official/deepseek-flash` or `deepseek-official/deepseek-v4-pro`, the card's Default model panel); leading entries (Default fallback chain) are walked first. Deactivating the plugin (the Plugins-page row switch, or clearing all configured content) hides the row again (slot-row/chain edits never churn registration).
+- **Stale selection**: if the row disappears (plugin deactivated) while `FallbacksChain / Auto` is selected, the session keeps showing it as the current model with `routable: false` — pick a real model from the catalog to continue (host-native catalog semantics).
 - **Capabilities and retry policy follow the head**: the row's model metadata (context window, modalities, reasoning) mirrors the current effective head, and `providerRetryPolicy` returns **that head's** policy — so a user's `llm-deepseek.retryPolicy` applies on this route too, not the permissive default. The host captures the policy once at registration, so a later policy edit or a slot-driven head-provider rotation shows up only after the plugin re-registers. Retry events are keyed by the virtual provider — the route the runtime actually sees. Full semantics → [docs/configuration.md](docs/configuration.md).
 
 ## Time-slot presets
@@ -235,7 +234,7 @@ Time slots are introduced in the [featured overview](#time-slots) above; this se
 - **Presets** (frozen, not user-editable): `liang-peak` = Monday–Friday 09:00–12:00 **and** 14:00–18:00; `liang-valley` = every other UTC+8 time; `glm-peak` = Monday–Friday 14:00–18:00; `glm-valley` = every other time. One preset id = one row; the card picker never offers a duplicate.
 - **Custom rows**: `start` / `end` (`HH:mm`, may wrap midnight) + optional `days` (0=Sunday…6=Saturday; omitted/empty = every day) + models.
 - **Next-request apply**: a slot boundary crossing never preempts an in-flight step — the new row takes effect on the next root request. Rotation is mount-only: info log + card/`/fallbacks` status line, no durable switch event.
-- **Settings card**: the Main agent section groups Time slots (extra rows — add preset / add custom / remove / reorder by buttons or **drag**; preset rows show a read-only window summary and edit models only; custom rows carry an editable name; the **timezone picker** lives here and **locks to Asia/Shanghai while any preset row exists**, since preset windows are frozen UTC+8 constants), Default fallback chain (walked first when no slot matches) and Default model (the official Flash | Pro last-resort fallback). Rows are collapsible to name + first model. There is no `timeSlots.enabled` master switch (adding a row is the opt-in) and no `rootMode` control.
+- **Flat settings card** (the official Plugins-page form language): the card is always open — no collapsible chrome and no feature switch — and one footer **Save/Discard** pair writes the whole validated draft. The Main agent section groups Time slots (extra rows — add preset / add custom / remove / reorder by buttons or **drag**; preset rows show a read-only window summary and edit models only; custom rows carry an editable name; the **timezone picker** lives here and **locks to Asia/Shanghai while any preset row exists**, since preset windows are frozen UTC+8 constants), Default fallback chain (walked first when no slot matches) and Default model (the official Flash | Pro last-resort fallback). Rows are collapsible to name + first model (content disclosure). There is no `timeSlots.enabled` master switch (adding a row is the opt-in) and no `rootMode` control.
 
 ## Preset roles
 
@@ -244,6 +243,15 @@ The plugin ships **5 bundled generic subagent roles** out of the box — `review
 - **Switch**: `fallbacks.presets` — `'bundled'` (default) declares the preset roles on apply; `'none'` disables the automatic declaration (already-materialized rows stay).
 - Full semantics (upgrade behavior, conflict handling, library reuse of `presetRoles`) → [docs/configuration.md](docs/configuration.md).
 
+## Agent presets (plugin composition)
+
+Agent **presets** are a dsh feature for composing plugins — they are declarative child-plugin lists a user can apply as a set, and they carry **no** model fields of their own. The fallbacks plugin needs no preset-specific configuration: because a preset composes plugins, the fallback applies **wherever the plugin's row is mounted** — a preset that includes the `dsh-llm-fallbacks` row gives that preset's sessions the same chains and roles configured for the plugin.
+
+Two composition caveats:
+
+- **A user preset override replaces the entire child list** (no merge): a preset that omits the fallbacks row silently unmounts the plugin for sessions using that preset. Restate every plugin row you want to keep.
+- **Preset-scoped chain configs are possible by mounting the row inside a preset**: the plugin row's `config:` overrides in a preset composition produce a chain configuration that applies to that preset's sessions only (patch rows replace the whole `config`, so restate every field).
+
 ## Fallback triggers (`triggerCodes`)
 
 `fallbacks.triggerCodes` is a plain list of dsh failure codes, and **any** code the harness can report is accepted — not only the three defaults (`AUTH` / `QUOTA` / `RATE_LIMIT`). A failure whose code is not listed passes straight through to llm-retry or to the original error, exactly as if the plugin were not installed. Retryable failures (5xx / `TRANSPORT` / `TIMEOUT` / `EMPTY_RESPONSE`) need no extra entries: llm-retry backs them off first and the failure enters the chain decision the same way once that budget is exhausted.
@@ -254,7 +262,6 @@ A request larger than the model's context window is reported as `CONTEXT_WINDOW_
 
 ```yaml
 fallbacks:
-  enabled: true
   triggerCodes:
     - AUTH
     - QUOTA

package/README.zh-CN.md

@@ -42,7 +42,7 @@ dsh plugin --profile web add dsh-llm-fallbacks      # web profile（设置 → F
 dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile
 ```
 
-同一个插件、两个前端——区别只在 `--profile` 参数。钉版本：加 `@<version>`。registry 安装拉取的是**已构建产物**（`dist/`），目标机无需构建。registry / git / 本地目录变体、卸载与 `--dump-config` 验证 → [docs/install.md](docs/install.md)。
+同一个插件、两个前端——区别只在 `--profile` 参数。钉版本：加 `@<version>`。registry 安装拉取的是**已构建产物**（`dist/`），目标机无需构建。registry / git / 本地目录变体、卸载与 `--dump-config` 验证 → [docs/install.md](docs/install.md)。插件自带**本地化元数据**（插件页详情视图的标题/描述，英文 + 简体中文）与**图标**——均以包内声明（`locale/*.json` + `icon.svg`）交由宿主自动读取。
 
 ### 配置界面
 
@@ -62,7 +62,6 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile
 
 ```yaml
 fallbacks:
-  enabled: true            # 功能开关——默认关闭（否则插件完全 no-op）
   rootChain:               # 全时段链：前面的条目 = 降级路径，最后一项 = 默认模型（官方模型）
     - anthropic/claude-3-5-sonnet          # 先走
     - deepseek-official/deepseek-flash  # 最后一档（Flash 或 Pro）
@@ -91,7 +90,7 @@ fallbacks:
 
 按四个步骤逐步构建：
 
-**1. 启用插件。** `enabled: true` 打开降级引擎。默认**关闭（`false`）**——未配置任何链时插件完全 no-op。
+**1. 配置内容。** 本分节**没有功能开关**——只要配置了内容（非空 `rootChain`、至少一条 `timeSlots` 行、或一个已声明角色），插件即介入；空分节完全 no-op。插件页的行开关是总开关（停用插件行即完全停止）。
 
 **2. 配置全时段 `rootChain`。** 前面的条目是降级链，请求失败时先走；**最后**一项是默认模型。
 
@@ -103,7 +102,7 @@ fallbacks:
 
 完整参考（角色实体、fallback 策略、规则、selector、预设角色、分时槽预设）→ [docs/configuration.md](docs/configuration.md)。
 
-> **升级提示（行为变更）**：已有 `fallbacks:` 配置若**未显式写 `enabled` 键**，升级后解析为 `false`——请补上 `enabled: true` 以保持插件继续生效。
+> **升级提示（破坏性变更）**：配置级 `enabled` 开关已**移除**——存量配置仍携带 `enabled: true/false` 时可正常加载（该键被忽略，下次保存时剥离），但不再起任何门控作用。如果你靠 `enabled: false` 保持插件惰性，请改为清空分节（或在插件页停用该行）。
 
 ### 验证
 
@@ -185,7 +184,7 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 
 - **root / subagent 自动降级**：任意 agent 在模型故障下按链切换到下一个可用 provider/model，无需手动换模型。
 - **两块制配置**：`rootChain` 管 root 代理；声明式角色实体（`roles.list`）供 `roles.rules` 引用（或内置 `inherit`）。
-- **选择器里把链当主模型**：`enabled` 开启时，宿主模型选择器（web 与 TUI 一致）出现虚拟 `FallbacksChain` / `Auto` 行——选中它即以配置的链作为 root 主模型（需要 all-day 链头合规才能成功委托）；选真实模型则保持 fallback-only（见 [模型选择器中的 FallbacksChain](#模型选择器中的-fallbackschain)）。
+- **选择器里把链当主模型**：只要插件配置了内容，宿主模型选择器（web 与 TUI 一致）即出现虚拟 `FallbacksChain` / `Auto` 行——选中它即以配置的链作为 root 主模型（需要 all-day 链头合规才能成功委托）；选真实模型则保持 fallback-only（见 [模型选择器中的 FallbacksChain](#模型选择器中的-fallbackschain)）。
 - **峰谷无忧（分时切换）**：可选的 `fallbacks.timeSlots` 行按墙钟窗口（配置级 `tz` 时区，默认 `Asia/Shanghai`）轮换 root 生效链——四个冻结的 UTC+8 预设（`liang-peak` / `liang-valley` / `glm-peak` / `glm-valley`，窗口为代码常量、仅模型链可编辑），或自定义 `start`/`end`/`days` 窗口。第一条命中的行生效；全时段行固定最后。时段切换在**下一个** root 请求生效，日志记为**分时切换**——路由种子而非失败决策：不消耗冷却、不计入 `maxSwitchesPerStep`。失败降级保留**降级切换**文案（见 [分时槽预设（分时切换）](#分时槽预设分时切换)）。
 - **派发时角色解析**：在 subagent 的首次请求上，其角色按三个阶段解析——显式（`agentPreset` 匹配已声明角色 id）→ 确定性规则（匹配记录 pair 或实际服务的链头——见 [模型选择器中的 FallbacksChain](#模型选择器中的-fallbackschain)）→ LLM 自动匹配（从已声明角色体系中选择，`fallbacks.roleAutoMatch` 默认 `true`）。解析出的角色的链头模型注入首次请求，并以显式 `role → model` 日志行记录（不写 durable `fallbacks/switch` 事件——issue #52 停写）；设 `roleAutoMatch: false` 仅关闭 LLM 自动匹配阶段（显式 `agentPreset` 阶段仍生效——无显式角色时即复现原有仅规则行为）。设置卡总是渲染「启用角色自动匹配」开关（默认 `true`）以切换之——即使是从未声明过该键的旧配置，schema 默认值同样生效。
 - **角色人格注入到子代理（与链无关）**：当 subagent 的派发声明了本插件已知的角色（Assignment 的 `**Execute as**: <id>` 字段）时，该角色的 `persona` 会安装为子代理自身的人格——角色就是子代理的身份，而不只是路由决策；注入与路由无关：`chain` 为空的角色与带链角色的人格注入完全一致（链只负责选模型）。调用方已设置的人格永不覆盖；宿主 provider 无法承载人格时跳过注入，派发照常原生运行。
@@ -197,7 +196,7 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 - **半开恢复（可选）**：`recovery: half-open` 让恢复以证据驱动——冷却到期后路由进入 **half-open**，以一次记录探针（logged probe）放行，而不是直接恢复首选；连续失败使抑制时长按 **×2** 逐次升级、**1 小时**封顶；观察到完成即闭合回路、完全恢复首选。`revertPolicy: 'never'` 使该机制完全失效；状态为会话级内存态（重启即重置）。仅 YAML 配置——默认 `timer` 保持所有既有行为逐字节一致（见 [docs/configuration.md](docs/configuration.md#recovery-mode-recovery-key)）。
 - **行为可见**：每次切换以 info 级日志行（from/to/role/reason）记录——无静默换模型。插件**刻意不写** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的事件类型注册被证伪无效，含该事件的会话在 dsh 重启后拒绝加载）。由旧版插件写入、含此类事件的会话**无法**通过 `ignorable` 标记修复——已发布的 session-format 迁移链（v0→v1）即使事件带 `ignorable` 也拒绝未知事件类型——因此 `pnpm repair:session-logs` 会报告此类日志（只有显式 opt-in 的有损 `--drop-legacy-events` 才会恢复它们——见 [修复已有会话](#修复已有会话)）。
 - **安全阀**：`maxSwitchesPerStep` 限制每 step 切换次数、`alwaysModeRetryCap` 限制 always 模式重试——链循环不会放大延迟。
-- **无配置回归（no-op）**：未配置任何链时行为与未安装插件完全一致——`enabled` 默认关闭（见 [最小配置](#最小配置)）。
+- **无配置回归（no-op）**：未配置任何内容时行为与未安装插件完全一致——内容在否即门控（见 [最小配置](#最小配置)）。
 
 ## dsh-tui profile（终端）
 
@@ -205,7 +204,7 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 
 - **`/fallbacks`** —— 本次会话发生了什么：来源、解析角色、生效链、最近降级切换、冷却状态（`recovery: half-open` 生效时显示 half-open 标记行）。只读。
 - **`/fallbacks config`** —— 配置了什么：组合配置回读（触发码、根链、分时槽、时区、角色、角色规则、冷却、回主策略、安全阀、预置、角色自动匹配）。除唯一的动作命令 **`/fallbacks config revert-seed <role-id>`** 外只读——该命令把某个 seed 角色的 persona 还原为已声明的默认（Web 设置卡将 seed 角色的 persona 呈现为只读、不提供还原入口，此命令是该动作的唯一入口）。
-- **`/settings`** —— 编辑界面。插件注册 **fallbacks** 区块，与 **Web 设置卡完全一致**：布尔（`enabled`、`roleAutoMatch`）渲染为开关、下拉（`presets`、`revertPolicy`）为选择器、数值（`cooldownMs`、`maxSwitchesPerStep`、`alwaysModeRetryCap`）为数字输入；复杂结构（`rootChain`、`timeSlots`、`roles.list`、`roles.rules`）为 JSON 文本字段，`triggerCodes` 为逗号分隔文本字段。非法草稿（JSON 解析失败、链尾不合规、分时行畸形）会阻止保存——区块绝不写入损坏配置。
+- **`/settings`** —— 编辑界面。插件注册 **fallbacks** 区块，与 **Web 设置卡完全一致**：布尔（`roleAutoMatch`）渲染为开关、下拉（`presets`、`revertPolicy`）为选择器、数值（`cooldownMs`、`maxSwitchesPerStep`、`alwaysModeRetryCap`）为数字输入；复杂结构（`rootChain`、`timeSlots`、`roles.list`、`roles.rules`）为 JSON 文本字段，`triggerCodes` 为逗号分隔文本字段。非法草稿（JSON 解析失败、链尾不合规、分时行畸形）会阻止保存——区块绝不写入损坏配置。
 
 **版本要求**：`/settings` 的 fallbacks 区块需要 **dsh-tui ≥ v0.8.5**（`main` 上 commit `c51661f` 及以后；settings seam 于 v0.8.0 引入，groups 结构与校验于 v0.8.5 引入）。更旧的 dsh-tui 没有该区块，文件编辑仍是 TUI 唯一编辑面。
 
@@ -213,7 +212,7 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 
 ## 模型选择器中的 FallbacksChain
 
-当 `enabled: true` 时，插件注册一个虚拟 provider **FallbacksChain**，目录中只有一行：**Auto**。web profile 与 dsh-tui 都能看到这一行：两者共享同一个 adapter catalog，无需设置页接线或宿主补丁（它与 `/settings` 的 fallbacks 区块相互独立——区块编辑的是配置，不是选择器目录）。该行只要插件启用就可见——遗留多模型或空的 all-day 链**不会**隐藏它（只是委托会拒绝服务）。
+只要插件配置了内容（非空 `rootChain`、至少一条 `timeSlots` 行、或一个已声明角色），它就注册一个虚拟 provider **FallbacksChain**，目录中只有一行：**Auto**。web profile 与 dsh-tui 都能看到这一行：两者共享同一个 adapter catalog，无需设置页接线或宿主补丁（它与 `/settings` 的 fallbacks 区块相互独立——区块编辑的是配置，不是选择器目录）。只要其它内容仍在，遗留多模型或空的 all-day 链**不会**隐藏它（只是委托会拒绝服务）；无任何内容时则没有这一行。
 
 选择 **FallbacksChain / Auto** = 把配置的链作为 root **主模型**：请求保留在虚拟对上，由 adapter 的薄委托在请求时刻派发到生效链的第一个精确 `provider/model`，失败后由降级引擎从该链头照常沿链切换。之所以让选择原样下发（而不是把路由改写成链头），也正是为了不让宿主的模型变更提示被反复触发：落盘的路由与会话选择一致，因此该提示只在**选择真的发生变化**时出现一次，而不再每一步重新注入。选择任何真实目录模型则保持 v0.2.2 的 fallback-only 行为——会话模型为主，链只在它失败后介入。
 
@@ -223,8 +222,8 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 
 - **选择器文案**：目录行的 `name`（composer 触发器显示）是动态的——`Auto: DeepSeek Flash[Liang Peak]` / `Auto: DeepSeek Flash[all-day]`（用 catalog 显示名，不是 model id）；id 仍是 `Auto`。all-day 尾巴不合规则只显示 `Auto`。重新打开选择器即可刷新。
 - **全来源同一个薄委托**：root 代理与继承了该选择的 subagent 会话由同一个 `stream()` 薄委托服务——subagent 的角色解析与注入语义不变，只有一处刻意的放宽：派发时规则匹配接受**记录 pair 或实际服务的链头**（此前匹配的超集，因此以真实链头为键的规则仍能命中），虚拟行绝不是第二个路由引擎。继承了该选择的 subagent 仍经链头路由。
-- **链尾合规门槛**：委托成功要求 all-day 链**尾巴合规**——最后一项必须是恰好一个官方模型（`deepseek-official/deepseek-flash` 或 `deepseek-official/deepseek-v4-pro`，即设置卡的「默认模型」面板）；前面的默认降级链先走。禁用插件后该行隐藏（slot/链编辑不会触发注册抖动）。
-- **过期选择**：行消失（插件禁用）而会话仍选中 `FallbacksChain / Auto` 时，会话继续把它显示为当前模型，但 `routable: false`——从目录选一个真实模型即可继续（宿主原生目录语义）。
+- **链尾合规门槛**：委托成功要求 all-day 链**尾巴合规**——最后一项必须是恰好一个官方模型（`deepseek-official/deepseek-flash` 或 `deepseek-official/deepseek-v4-pro`，即设置卡的「默认模型」面板）；前面的默认降级链先走。停用插件（插件页行开关，或清空全部已配置内容）后该行隐藏（slot/链编辑不会触发注册抖动）。
+- **过期选择**：行消失（插件停用）而会话仍选中 `FallbacksChain / Auto` 时，会话继续把它显示为当前模型，但 `routable: false`——从目录选一个真实模型即可继续（宿主原生目录语义）。
 - **能力与重试策略跟随链头**：该行的模型元数据（上下文窗口、模态、推理）镜像当前生效链头，`providerRetryPolicy` 返回**该链头的**策略——因此用户配置的 `llm-deepseek.retryPolicy` 在这条路由上同样生效，不再退回宽松默认。宿主在注册时一次性捕获该策略，因此之后修改策略、或分时槽导致链头 provider 轮换，都只有在插件重新注册后才会反映。重试事件按虚拟 provider 记账——即运行时实际看到的路由。完整语义 → [docs/configuration.md](docs/configuration.md)。
 
 ## 分时槽预设（分时切换）
@@ -235,7 +234,7 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 - **预设**（冻结，不可编辑窗口）：`liang-peak` = 周一至周五 09:00–12:00 **与** 14:00–18:00；`liang-valley` = 其它所有 UTC+8 时间；`glm-peak` = 周一至周五 14:00–18:00；`glm-valley` = 其余时间。一个预设 id 对应一行；设置卡的选择器不会重复提供已添加的预设。
 - **自定义行**：`start` / `end`（`HH:mm`，可跨午夜）+ 可选 `days`（0=周日…6=周六；缺省/空 = 每天）+ 模型。
 - **下一请求生效**：时段边界跨越绝不打断进行中的 step——新行在下一个 root 请求生效。轮换仅挂载生效：info 日志 + 设置卡/`/fallbacks` 状态行，无 durable 切换事件。
-- **设置卡**：主代理区块下分三块——**分时槽设置**（额外行：添加预设 / 添加自定义 / 删除 / 按钮或**拖拽**排序；预设行只读展示窗口摘要、仅可编辑模型链；自定义行带可编辑名称；**时区选择器**在此区块内，只要存在预设行就**锁定 Asia/Shanghai**——预设窗口是冻结的 UTC+8 常量）、**默认降级链**（all-day 链，可配置的 provider/model 选择器列表）与**默认模型**（官方 Flash | Pro 二选一链头）。行可折叠为「名称 + 首个模型」。没有 `timeSlots.enabled` 总开关（添加行即开启），也没有 `rootMode` 控件。
+- **平铺设置卡**（官方插件页表单语言）：卡片始终展开——无可折叠外壳、无功能开关——由唯一的底部 **保存/放弃** 按钮对写入整份通过校验的草稿。主代理区块下分三块——**分时槽设置**（额外行：添加预设 / 添加自定义 / 删除 / 按钮或**拖拽**排序；预设行只读展示窗口摘要、仅可编辑模型链；自定义行带可编辑名称；**时区选择器**在此区块内，只要存在预设行就**锁定 Asia/Shanghai**——预设窗口是冻结的 UTC+8 常量）、**默认降级链**（all-day 链，可配置的 provider/model 选择器列表）与**默认模型**（官方 Flash | Pro 二选一链头）。行可折叠为「名称 + 首个模型」（内容级折叠）。没有 `timeSlots.enabled` 总开关（添加行即开启），也没有 `rootMode` 控件。
 
 ## 预设角色（Preset roles）
 
@@ -244,6 +243,15 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 - **开关**：`fallbacks.presets`——`'bundled'`（默认）在 apply 时声明预设角色；`'none'` 关闭自动声明（已物化行保留）。
 - 完整语义（升级行为、冲突处理、`presetRoles` 库复用）→ [docs/configuration.md](docs/configuration.md)。
 
+## Agent 预设（插件组合）
+
+Agent **preset** 是 dsh 的插件组合机制——一份声明式的子插件行清单，用户可整组启用；preset 本身**不携带任何模型字段**。本插件无需 preset 专属配置：preset 组合的是插件，因此 fallback 生效于**插件行被挂载的每一处**——包含 `dsh-llm-fallbacks` 行的 preset，其会话即享有同一套链与角色配置。
+
+两条组合注意事项：
+
+- **用户 preset 覆盖会整体替换子插件清单**（无合并）：遗漏了 fallbacks 行的 preset 会在使用该 preset 的会话中静默卸载本插件。想保留的插件行都要重新写全。
+- **preset 级链配置可通过把插件行挂进 preset 实现**：preset 组合中插件行的 `config:` 覆盖会形成仅作用于该 preset 会话的链配置（patch 行整体替换 `config`，字段要写全）。
+
 ## 降级触发码（`triggerCodes`）
 
 `fallbacks.triggerCodes` 是一份 dsh 失败码列表，**任何**宿主可上报的失败码都被接受——不限于三个默认值（`AUTH` / `QUOTA` / `RATE_LIMIT`）。未列出的失败码原样透传给 llm-retry 或原始错误，与未安装插件完全一致。可重试型失败（5xx / `TRANSPORT` / `TIMEOUT` / `EMPTY_RESPONSE`）无需额外条目：llm-retry 先行退避，预算耗尽后同样进入链决策。
@@ -254,7 +262,6 @@ pnpm repair:session-logs -- --drop-legacy-events --apply --backup  # 此处必
 
 ```yaml
 fallbacks:
-  enabled: true
   triggerCodes:
     - AUTH
     - QUOTA

package/dist/client/FallbacksCard.d.ts

@@ -6,77 +6,78 @@
  * registration order); owner props are empty and all data flows
  * through {@link FallbacksSettingsController}.
  *
- * The card chrome replicates the upstream `PluginCard` contract (self-drawn:
- * the upstream client value face exports no reusable card): a collapsible
- * `<li>` whose header is a button stacking the plugin name over its
- * description, with a dirty "unsaved" pill and a rotating chevron
- * (`IconChevronDownOutlineMedium` from ui-primitives — a CLIENT_EXTERNALS value
- * import), `aria-expanded`/`aria-label` like the upstream header; a divider
- * under the header; then the form content. PR #62 UX round 2: the card
- * footer is gone — each big section (主代理 / 子代理 / 高级选项) carries its
- * own Save/Discard actions beside its heading (高级选项: inside the expanded
- * body) and its own validation / save-error surface. PR #62 UX round 3:
- * each section's Save writes ONLY that section's fields — 主代理 owns
- * rootChain / timeSlots / tz (+ the card-level `enabled`), 子代理 owns
- * roles, 高级选项 owns the advanced scalars; the patch spreads the last
- * ACCEPTED config for every other section, so a 主代理 Save can never
- * ride along an unsaved 子代理 edit (and vice versa) — and validation /
- * the dirty gate apply per section too (a bad role id never blocks 主代理,
- * and only the saved section's Discard reverts that section's edits).
- * Save/discard disabled terms: save = `!sectionDirty || saving ||
- * !writable`, discard = `!sectionDirty || saving` (KD-U1). Disclosure is
- * card-local state:
- * which card a user has open is a reading gesture, and staged edits outlive
- * collapsing — the pill rides the header (upstream rationale).
+ * FLAT rebuild (plan fallbacks-web-ux-alignment T3, the advisor PR #98
+ * pattern): the collapsible card chrome is gone — no header button, no
+ * rotating chevron, no dirty "unsaved" pill, no card-local open state, no
+ * bordered `<li>` box. The page already renders the plugin title/description
+ * above the card (the `locale/*.json` meta files the host resolves per UI
+ * language), so the notices, the form, and the section actions directly
+ * beneath it in the official flat settings-form language (reference §3):
+ * fields at
+ * 12px vertical padding with 0.5px hairline separators, 34px inputs on the
+ * 0.5px l4 border, per-section Discard + Save pairs on the section
+ * headings. The card is ALWAYS open —
+ * nothing needs card-level disclosure state; the degraded /
+ * error / read-only / migration notices render flat atop the form (the
+ * unavailable notice stays always-visible per KD-G5 — the documented
+ * divergence from the advisor, whose unavailable card renders nothing: the
+ * fallbacks skeleton stays the USABLE last-known form and saves are
+ * attempted).
  *
- * The form body is the two-block editing surface (spec §8): the `enabled`
- * checkbox row, the 6 top-level scalar fields (trigger codes / revert
- * policy / three numeric fields), the `rootChain` block (block 1 — the
- * root agent's single chain, no key input), and the roles block (block 2 —
- * declared role entity cards from `roles.list` plus the rule rows from
- * `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, 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-
- * to-defaults affordance is GONE from the card (PR #62 UX round 3) — the
- * gateway RPC `fallbacks/reset` and the store `resetToDefaults()` stay as
- * host APIs (store/gateway tests unchanged), only the card UI was removed.
+ * The config-level `enabled` switch is REMOVED (T2, breaking): there is no
+ * checkbox row and no `enabled.off` hiding — all fields render
+ * unconditionally; the Plugins-page row toggle is the master switch and the
+ * runtime gates read content presence (`isFallbackActive`).
  *
- * The page-only chrome is gone (720px column wrapper, title/intro banners,
- * page-bottom status block): the AC-7 read-only status (derived effective
- * model + recent-switch summary) is folded into the card body, and the
- * plugin-config section owns the column width.
+ * PER-SECTION Save/Discard return beside each section heading (plan
+ * fallbacks-card-section-ux, the maintainer's live-host feedback reversing
+ * the flat plan's one-document model): the scroll-to-save cost of ONE
+ * bottom Save outweighed it. Each section's Save writes ONLY that section's
+ * fields (patch = the last ACCEPTED config with the section's fields
+ * replaced — the ride-along protection, PR #62 UX round 3), gated by that
+ * section's dirty term and validation bucket only (KD-U1: save =
+ * `!sectionDirty || saving || !writable`, discard = `!sectionDirty ||
+ * saving`; Save additionally carries `!writable` — W-1, qc2 fix wave: the
+ * dirty-implies-writable assumption does not hold for this in-place-draft
+ * store). Violations render live under their OWNING section heading, and a
+ * store write failure renders under the section whose Save was last
+ * clicked (`lastSaveSection`). Discard is kept — our staged edits survive
+ * refresh, the advisor's documented divergence from the official
+ * no-discard form — a pure client-side revert of THAT section's editors to
+ * the last accepted config.
  *
- * Degraded/error/loading states keep the same card chrome (KD-U3): the
- * header always renders title+description+chevron, and the body carries the
- * config-channel notice or the load error. A card that cannot reach the
- * `fallbacks/get` gateway channel (`ready && !present`) keeps the USABLE
- * skeleton — the form stays writable and saves are attempted (KD-G5) — with
- * the `unavailable` notice ALWAYS visible (derived open — the header cannot
- * collapse it away), while a healthy card is collapsed until the user
- * expands it (AC-1, the documented divergence from upstream whose
- * unavailable card renders nothing). A hard load failure (`status ===
- * 'error'`) also forces the body open with an error notice and — when the
- * form is inert (`!writable`, i.e. the load never landed) — a Retry button;
- * a save failure keeps the editable form so the Save action itself is the
- * retry. PR #62 UX round 2: the single `state.error` surface is split by
- * origin — a LOAD failure keeps the card-top notice (with Retry when
- * inert), while a WRITE failure renders under the section whose Save was
- * last clicked (`lastSaveSection`), unlike the advisor's separate
- * apply-failure hints.
+ * The form body is the two-block editing surface (spec §8): the 6 top-level
+ * scalar fields (trigger codes / revert policy / three numeric fields), the
+ * `rootChain` block (block 1 — the root agent's single chain, no key input),
+ * and the roles block (block 2 — declared role entity cards from
+ * `roles.list` plus the rule rows from `roles.rules`, whose role field is a
+ * dropdown bound to the declared ids + the built-in `inherit`, same-page
+ * live). Row-level disclosures that are CONTENT keep their expand/collapse:
+ * the time-slot row cards and the role entity cards (with the seeded
+ * persona briefs) stay collapsible — a read-only view forces them open so
+ * the configs stay reachable. The 主代理 / 子代理 / 高级选项 group labels
+ * are semantic `<h2>` headings (T1); 高级选项 is a content-level disclosure
+ * collapsed by default (T3 — same expand/collapse contract as the rows, a
+ * read-only view forces it open).
  *
- * The degraded derivation is latched in the card (the store stays untouched):
- * `present` only ever changes inside the store's `accept()`, so the settled
- * `ready` read is authoritative, and a card-local latch carries that value
- * through refresh/save windows (`loading`/`saving`) so the notice body can
- * never collapse mid-refresh (the advisor's latched `degraded` field,
- * implemented without a store change); on a first mount the latch is false,
- * so the healthy card starts (and stays) collapsed through its first load.
+ * Validation: id format/reserved word/duplicates, undeclared rule role
+ * references, illegal selectors, and a role with no chain entries (no model
+ * config) block the write (the Save disabled gate) with per-section banners
+ * + inline red borders / hints (never touching the store error path); a
+ * non-empty `state.legacyKeys` renders the migration banner at the top.
+ * The reset-to-defaults affordance is GONE from the card (PR #62 UX
+ * round 3) — the gateway RPC `fallbacks/reset` and the store
+ * `resetToDefaults()` stay as host APIs, only the card UI was removed.
+ *
+ * The AC-7 read-only status block (recent-switch summary, D-5) stays at the
+ * bottom, flat.
+ *
+ * Presentation is ui-primitives-free (T4, advisor parity + reference §4
+ * risk): Button/Tooltip and the five icon imports are replaced by
+ * self-drawn styled elements — inline SVG icons (plus / trash / chevron /
+ * grip) and the CSS `data-tip` tooltip bubble (the card's existing
+ * icon-button pattern); every color resolves through a `--dsw-alias-*`
+ * token so the card adapts to the light/dark theme.
  */
 import type { ReactNode } from 'react';
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
@@ -93,10 +94,9 @@ export interface FallbacksCardInjected {
 /** Props delivered by the slot outlet: runtime share + locale seat + inject face. */
 export type FallbacksCardProps = PropsRuntime<'plugins.bundle.config'> & PropsLocale<'fallbacks'> & InjectFace<FallbacksCardInjected>;
 /**
- * Render the Fallbacks settings card inside the plugin-config section,
- * replicating the upstream PluginCard chrome (KD-U1). The body carries the
- * existing form content unchanged plus the folded-in status block and the
- * footer actions (Discard / Reset / Save).
+ * Render the Fallbacks settings card inside the plugin-config section —
+ * flat: the notices, the form, and the section action pairs directly under
+ * the page's plugin title/description, with no chrome of our own.
  * @param props - slot-delivered injected dependencies and the synthesized t seat.
  * @returns the card.
  */

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

@@ -56,7 +56,7 @@ export interface FallbacksSwitchSnapshot extends FallbacksSwitchEventData {
  * live route probe.
  */
 export type EffectiveModelView = 
-/** ① `enabled: false` or an empty rootChain. */
+/** ① An inactive config (nothing configured) or an empty rootChain. */
 {
     kind: 'unavailable';
 }
@@ -225,10 +225,11 @@ export declare function classifyModel(provider: string, raw: string, catalog: Ca
  */
 export declare function extractRecentSwitches(entries: readonly SessionEventLikeEntry[], limit?: number): FallbacksSwitchSnapshot[];
 /**
- * Derive the "current effective model" (spec §2.5 D-6): ① disabled / empty
- * rootChain → unavailable; ② a recent switch exists → the latest one's `to`;
- * ③ otherwise → the config's primary target. A **display value** — never a
- * live route probe.
+ * Derive the "current effective model" (spec §2.5 D-6): ① inactive (nothing
+ * configured — the removed `enabled` switch re-keyed to `isFallbackActive`)
+ * / empty rootChain → unavailable; ② a recent switch exists → the latest
+ * one's `to`; ③ otherwise → the config's primary target. A **display
+ * value** — never a live route probe.
  *
  * INTENTIONAL D-6 CONTRACT RETENTION: after the AC-2 trim (plan
  * fallbacks-settings-visibility Task 2) the settings card's status block no