dsh-llm-fallbacks 0.3.1 → 0.3.3

package/README.md

@@ -6,12 +6,12 @@
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
 ![dsh tui](https://img.shields.io/badge/dsh%20tui-compatible-4B32C3.svg)
-![dsh](https://img.shields.io/badge/DSH-0.1.0--rc.8-4B32C3.svg)
+![dsh](https://img.shields.io/badge/DSH-0.1.1--rc.1-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.
 
-Works in both dsh front ends: the **web** profile (Settings → Plugins → Fallbacks card) and the **dsh-tui** terminal profile (`/fallbacks` + `/fallbacks config`).
+Works in both dsh front ends: the **web** profile (Settings → Plugins → Fallbacks card) and the **dsh-tui** terminal profile (`/fallbacks` session diagnostics, `/fallbacks config` readback, and the `/settings` fallbacks section for editing).
 
 ## Time slots
 
@@ -57,18 +57,30 @@ pnpm repair:fallbacks-switch-logs -- --apply --backup     # mark legacy events i
 
 The script scans `~/.dsh/sessions` by default (override with `--root <dir>`), marks legacy `fallbacks/switch` events `ignorable: true` so the host read path accepts the session again, and keeps a `<file>.bak` per repaired log. `--apply` requires `--backup` and must run with dsh stopped. From 0.2.2 on, the plugin stops writing durable switch events, so no new sessions need repair.
 
+### Configuration surfaces
+
+The plugin's settings live in a shared `fallbacks:` namespace, editable from three surfaces:
+
+| Surface | What it is | Notes |
+|---|---|---|
+| **Web settings card** | Settings → Plugins → Fallbacks | Full GUI editor for the `fallbacks:` namespace; writes the shared settings document |
+| **`$DSH_HOME/settings.yaml`** | `fallbacks:` section in the dsh settings document | The shared source of truth — the same file the web card writes; readable and editable everywhere, including scripted setups |
+| **TUI `/settings`** | fallbacks section in the dsh-tui settings screen | dsh-tui ≥ v0.8.5; native fields for simple keys, JSON text fields for complex structures (see [dsh-tui profile (terminal)](#dsh-tui-profile-terminal)) |
+
+Pick the surface that matches your front end: web users get the card, terminal users get `/settings`, and the YAML file works everywhere. (`/fallbacks` and `/fallbacks config` are diagnostics — read-only views, not edit surfaces.)
+
 ### Minimal configuration
 
-Add a `fallbacks:` section to the dsh settings document (default `$DSH_HOME/settings.yaml`):
+Add a `fallbacks:` section to the shared settings document (`$DSH_HOME/settings.yaml` — see [Configuration surfaces](#configuration-surfaces)):
 
 ```yaml
 fallbacks:
-  enabled: true            # feature switch; defaults to false — set explicitly to enable
-  rootChain:               # all-day chain: LAST entry is Default model (official V4);
-    - anthropic/claude-3-5-sonnet          # leading entries = Default fallback chain (walked first)
-    - deepseek-official/deepseek-v4-flash  # last = Flash XOR Pro last-resort fallback
+  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 V4)
+    - anthropic/claude-3-5-sonnet          # walked first
+    - deepseek-official/deepseek-v4-flash  # last resort (Flash or Pro)
   timeSlots:               # optional: rotate the effective root chain by wall-clock windows
-    - kind: preset         # frozen UTC+8 windows; only the model chain is editable (locks tz to Asia/Shanghai)
+    - kind: preset         # frozen UTC+8 window; only the chain is editable
       preset: liang-peak   # 09:00–12:00 and 14:00–18:00, every day
       chain:
         - anthropic/claude-3-5-sonnet
@@ -79,24 +91,36 @@ fallbacks:
       days: [1, 5]         # optional; omitted/empty = every day (0=Sunday…6=Saturday)
       chain:
         - openai/gpt-4o
-  roles:                   # block 2: declare role entities first, then let rules reference them
+  roles:                   # optional: declare role entities, then reference them from rules
     list:
-      - id: reviewer       # unique id (/^[a-z0-9-]{1,32}$/); "inherit" is reserved
+      - id: reviewer       # unique id; "inherit" is reserved
         persona: Code-review subagents
         chain:
           - openai/gpt-4o-mini
-        fallback: inherit-root   # default: role chain, then append rootChain
+        fallback: inherit-root   # role chain first, then the inherited rootChain
     rules:                 # subagent-only: rules never match root requests
-      - role: reviewer     # all subagents → reviewer role (own chain + inherited root)
+      - role: reviewer     # all subagents → the reviewer role
 ```
 
-No rule match (or a root request) → the built-in `inherit` → `rootChain`. `enabled` defaults to **off** — with no chains configured the plugin is a complete no-op. The all-day `rootChain` must END with exactly one official V4 model (`deepseek-official/deepseek-v4-flash` or `deepseek-official/deepseek-v4-pro`) — the settings card and gateway reject any other tail on save (a legacy non-official-tail chain warns at startup and keeps working as a fallback-only walk, but cannot be saved as-is). Full reference (role entities, fallback strategies, rules, selectors, preset roles, time-slot presets) → [docs/configuration.md](docs/configuration.md).
+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.
+
+**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.
+
+> **Conformance**: the last entry must be exactly one official V4 model — `deepseek-official/deepseek-v4-flash` XOR `deepseek-official/deepseek-v4-pro`. The settings card and gateway reject any other tail on save; a legacy non-official tail warns at startup and keeps working as a fallback-only walk, but cannot be saved as-is.
+
+**3. Add `timeSlots` (optional).** Rows rotate the effective root chain by wall-clock windows. Preset rows use frozen UTC+8 windows (only their chain is editable; while a preset row exists, `tz` locks to `Asia/Shanghai`); custom rows take `start`/`end` (may wrap midnight) and an optional `days` list. The first row whose window contains the current moment wins; no match → the all-day `rootChain`. Rotation is a routing seed — it applies on the next root request and consumes no cooldown (see [Time slots](#time-slots)).
+
+**4. Add `roles` (optional).** Declare role entities in `roles.list` (id, persona, chain, optional `fallback` policy), then map subagents to them with `roles.rules`. Rules never match root requests — with no rule match (or on a root request) the built-in `inherit` role applies and appends the `rootChain`.
+
+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.
 
 ### Verify
 
-Save and restart the session, then type `/fallbacks` — the read-only in-session diagnostics (origin, resolved role, chain, recent `fallbacks/switch` events, cooldown status). The plugin no longer writes durable `fallbacks/switch` session events (issue #52 — the apply()-time registration was proven ineffective), so new switches show up in the info logs, not in the recent-switch surfaces; sessions written by older plugin versions that contain `fallbacks/switch` events are repaired with `scripts/repair-fallbacks-switch-logs.ts`, which marks legacy events ignorable so those sessions load again (see the Features note below). In a dsh-tui profile, `/fallbacks config` additionally reads back the composed configuration (the TUI has no settings page — config is file-only; see [docs/configuration.md](docs/configuration.md)).
+Save the config and restart the session, then type `/fallbacks` — the read-only in-session diagnostics (origin, resolved role, chain, recent fallback switches, cooldown status). In a dsh-tui profile, `/fallbacks config` reads back the composed configuration; see [dsh-tui profile (terminal)](#dsh-tui-profile-terminal).
 
 ## Features
 
@@ -108,11 +132,23 @@ Save and restart the session, then type `/fallbacks` — the read-only in-sessio
 - **Cooldown and revert**: failed / switched-away models are not re-selected during cooldown; `revertPolicy: cooldown-expiry` returns to the primary model automatically.
 - **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 are repaired by `scripts/repair-fallbacks-switch-logs.ts`, which marks legacy events ignorable so affected sessions load again.
 - **Safety valves**: `maxSwitchesPerStep` caps switches per step and `alwaysModeRetryCap` caps always-mode retries — chain loops cannot amplify latency.
-- **No-config no-op**: `enabled` defaults to off; with no chains configured the plugin behaves exactly like not being installed.
+- **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)).
+
+## dsh-tui profile (terminal)
+
+In a dsh-tui profile the plugin has three operator surfaces, with a strict duty split:
+
+- **`/fallbacks`** — what happened this session: origin, resolved role, effective chain, recent fallback switches, cooldown status. 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 (a web-card action the settings seam cannot express).
+- **`/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.
+
+**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.
+
+File editing still works everywhere: the shared `$DSH_HOME/settings.yaml` (`fallbacks:` section — the same file the web card writes) for global settings, or the profile patch `~/.dsh/profiles/dsh-tui/cordis.patch.yml` (`config:` overrides on the plugin row) for dsh-tui-specific values. A patch row **replaces** the targeted row's whole `config` — restate every field you want to keep (schema defaults fill the rest).
 
 ## 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 no TUI settings page or host patch is involved. The row is visible whenever the plugin is enabled — a legacy or empty all-day chain does NOT hide it (the override just refuses to fire).
+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 override just refuses to fire).
 
 Selecting **FallbacksChain / Auto** uses the configured chain as the root **primary**: root requests route to the effective chain's first exact `provider/model` at request time, and the fallback engine degrades from that head as usual. 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.
 

package/README.zh-CN.md

@@ -6,12 +6,12 @@
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
 ![dsh tui](https://img.shields.io/badge/dsh%20tui-compatible-4B32C3.svg)
-![dsh](https://img.shields.io/badge/DSH-0.1.0--rc.8-4B32C3.svg)
+![dsh](https://img.shields.io/badge/DSH-0.1.1--rc.1-4B32C3.svg)
 [![dshfind](https://dshfind.com/api/badge/omdsh-dev/dsh-llm-fallbacks?lang=zh)](https://dshfind.com/zh/plugins/omdsh-dev/dsh-llm-fallbacks?ref=badge)
 
 dsh（DeepSeek Harness）的自动模型降级插件：当 root agent 或 subagent 的模型请求持续失败（重试耗尽、权限、配额超限、限流 429）时，按角色/模型 fallback 链自动切换 provider/model，当前 step/turn 在目标模型上继续完成——任务不因模型问题中断。
 
-两个 dsh 前端均可用：**web** profile（设置 → 插件配置 → Fallbacks 卡片）与 **dsh-tui** 终端 profile（`/fallbacks` + `/fallbacks config`）。
+两个 dsh 前端均可用：**web** profile（设置 → 插件配置 → Fallbacks 卡片）与 **dsh-tui** 终端 profile（`/fallbacks` 会话诊断、`/fallbacks config` 回读，以及 `/settings` 中的 fallbacks 区块用于编辑）。
 
 ## 峰谷无忧
 
@@ -57,46 +57,70 @@ pnpm repair:fallbacks-switch-logs -- --apply --backup     # 给旧事件打 igno
 
 脚本默认扫描 `~/.dsh/sessions`（可用 `--root <dir>` 覆盖），把遗留 `fallbacks/switch` 事件标记为 `ignorable: true`，宿主读路径即可重新接受该会话；每个被修复的日志保留一份 `<file>.bak`。`--apply` 必须搭配 `--backup`，且须在 dsh 停止时运行。从 0.2.2 起插件不再写 durable 切换事件，新会话无需修复。
 
+### 配置界面
+
+插件的设置存在于共享的 `fallbacks:` 命名空间中，可通过三个界面编辑：
+
+| 界面 | 是什么 | 说明 |
+|---|---|---|
+| **Web 设置卡** | 设置 → 插件配置 → Fallbacks | `fallbacks:` 命名空间的完整 GUI 编辑器；写入共享设置文档 |
+| **`$DSH_HOME/settings.yaml`** | dsh 设置文档中的 `fallbacks:` 分节 | 共享的事实源——与 Web 卡写入的是同一个文件；任何场景（包括脚本化配置）都可读写 |
+| **TUI `/settings`** | dsh-tui 设置界面中的 fallbacks 区块 | 需要 dsh-tui ≥ v0.8.5；简单键用原生字段，复杂结构用 JSON 文本字段（见 [dsh-tui profile（终端）](#dsh-tui-profile终端)） |
+
+按你的前端选择入口：web 用户用设置卡，终端用户用 `/settings`，YAML 文件处处可用。（`/fallbacks` 与 `/fallbacks config` 是诊断命令——只读视图，不是编辑入口。）
+
 ### 最小配置
 
-在 dsh 的设置文档（默认 `$DSH_HOME/settings.yaml`）中添加 `fallbacks:` 分节：
+在共享设置文档（`$DSH_HOME/settings.yaml`——见 [配置界面](#配置界面)）中添加 `fallbacks:` 分节：
 
 ```yaml
 fallbacks:
-  enabled: true          # 功能级开关；默认关闭（false），需显式打开后生效
-  rootChain:             # 全时段链：最后一项是默认模型（官方 V4）
-    - anthropic/claude-3-5-sonnet          # 前面是默认降级链（先走）
-    - deepseek-official/deepseek-v4-flash  # 最后一档：Flash 或 Pro
-  timeSlots:             # 可选：按墙钟时段轮换 root 生效链
-    - kind: preset       # 冻结的 UTC+8 窗口；仅模型链可编辑（锁定 tz 为 Asia/Shanghai）
-      preset: liang-peak # 09:00–12:00 与 14:00–18:00，每天
+  enabled: true            # 功能开关——默认关闭（否则插件完全 no-op）
+  rootChain:               # 全时段链：前面的条目 = 降级路径，最后一项 = 默认模型（官方 V4）
+    - anthropic/claude-3-5-sonnet          # 先走
+    - deepseek-official/deepseek-v4-flash  # 最后一档（Flash 或 Pro）
+  timeSlots:               # 可选：按墙钟窗口轮换生效 root 链
+    - kind: preset         # 冻结的 UTC+8 窗口；仅链可编辑
+      preset: liang-peak   # 每天 09:00–12:00 与 14:00–18:00
       chain:
         - anthropic/claude-3-5-sonnet
-    - kind: custom       # 自定义窗口（可跨午夜）
-      name: evening      # 可选显示名称
+    - kind: custom         # 自定义窗口（可跨午夜）
+      name: evening        # 可选显示名称
       start: '22:00'
       end: '02:00'
-      days: [1, 5]       # 可选；缺省/空 = 每天（0=周日…6=周六）
+      days: [1, 5]         # 可选；缺省/空 = 每天（0=周日…6=周六）
       chain:
         - openai/gpt-4o
-  roles:                 # 块 2：先声明角色，再让规则引用
+  roles:                   # 可选：先声明角色实体，再由规则引用
     list:
-      - id: reviewer     # 角色实体：id 唯一（/^[a-z0-9-]{1,32}$/）；inherit 为保留字
+      - id: reviewer       # 唯一 id；"inherit" 为保留字
         persona: 代码审查子代理
         chain:
           - openai/gpt-4o-mini
-        fallback: inherit-root   # 默认：角色链后追加 rootChain
-    rules:               # 仅对子代理生效：规则不匹配 root 请求
-      - role: reviewer   # 所有 subagent → reviewer 角色（自身链 + 继承 root）
+        fallback: inherit-root   # 先走角色链，再追加继承的 rootChain
+    rules:                 # 仅对子代理生效：规则不匹配 root 请求
+      - role: reviewer     # 所有 subagent → reviewer 角色
 ```
 
-未命中规则（或 root 请求）→ 内置 `inherit` → `rootChain`。`enabled` **默认关闭（`false`）**——未配置任何链时插件完全 no-op。全时段 `rootChain` 的**最后一项**必须恰好是一个官方 V4 模型（`deepseek-official/deepseek-v4-flash` 或 `deepseek-official/deepseek-v4-pro`）——设置卡与 gateway 在保存时拒绝其它尾巴（遗留非合规尾巴启动时告警并继续按 fallback-only 走原链，但无法原样保存）。完整参考（角色实体、fallback 策略、规则、selector、预设角色、分时槽预设）→ [docs/configuration.md](docs/configuration.md)。
+按四个步骤逐步构建：
+
+**1. 启用插件。** `enabled: true` 打开降级引擎。默认**关闭（`false`）**——未配置任何链时插件完全 no-op。
+
+**2. 配置全时段 `rootChain`。** 前面的条目是降级链，请求失败时先走；**最后**一项是默认模型。
+
+> **链尾合规**：最后一项必须是恰好一个官方 V4 模型——`deepseek-official/deepseek-v4-flash` 或 `deepseek-official/deepseek-v4-pro`（二选一）。设置卡与 gateway 在保存时拒绝其它尾巴；遗留的非合规尾巴启动时告警并继续按 fallback-only 走原链，但无法原样保存。
+
+**3. 添加 `timeSlots`（可选）。** 各行按墙钟窗口轮换生效 root 链。预设行使用冻结的 UTC+8 窗口（仅链可编辑；存在预设行时 `tz` 锁定 `Asia/Shanghai`）；自定义行使用 `start`/`end`（可跨午夜）与可选的 `days` 列表。第一个窗口包含当前时刻的行生效；无行命中 → 全时段 `rootChain`。分时切换是路由种子——在下一个 root 请求生效、不消耗冷却（见 [峰谷无忧](#峰谷无忧)）。
+
+**4. 添加 `roles`（可选）。** 在 `roles.list` 中声明角色实体（id、persona、chain、可选的 `fallback` 策略），再用 `roles.rules` 把 subagent 映射到角色。规则绝不匹配 root 请求——未命中规则（或 root 请求）时由内置 `inherit` 角色兜底，追加 `rootChain`。
+
+完整参考（角色实体、fallback 策略、规则、selector、预设角色、分时槽预设）→ [docs/configuration.md](docs/configuration.md)。
 
 > **升级提示（行为变更）**：已有 `fallbacks:` 配置若**未显式写 `enabled` 键**，升级后解析为 `false`——请补上 `enabled: true` 以保持插件继续生效。
 
 ### 验证
 
-保存并重启会话后，键入 `/fallbacks`——只读的会话内诊断（来源、解析角色、链、最近的 `fallbacks/switch` 事件、冷却状态）。插件**不再写入** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的注册被证伪无效），因此新切换只出现在 info 日志中，不再出现在 recent-switch 展示面；由旧版插件写入、含 `fallbacks/switch` 事件的会话，可用 `scripts/repair-fallbacks-switch-logs.ts` 修复——脚本把旧事件标记为 ignorable，会话即可重新加载（见下方「能力一览」说明）。在 dsh-tui profile 中，`/fallbacks config` 额外回读组合配置（TUI 无设置页——配置仅文件，见 [docs/configuration.md](docs/configuration.md)）。
+保存配置并重启会话，然后键入 `/fallbacks`——只读的会话内诊断（来源、解析角色、链、最近降级切换、冷却状态）。在 dsh-tui profile 中，`/fallbacks config` 回读组合配置；见 [dsh-tui profile（终端）](#dsh-tui-profile终端)。
 
 ## 能力一览
 
@@ -108,11 +132,23 @@ fallbacks:
 - **冷却与回主**：被切离/失败的模型在冷却期内不再入选；`revertPolicy: cooldown-expiry` 冷却到期后自动回主模型。
 - **行为可见**：每次切换以 info 级日志行（from/to/role/reason）记录——无静默换模型。插件**刻意不写** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的事件类型注册被证伪无效，含该事件的会话在 dsh 重启后拒绝加载）。由旧版插件写入、含此类事件的会话由 `scripts/repair-fallbacks-switch-logs.ts` 修复——旧事件被标记 ignorable 后，受影响会话可重新加载。
 - **安全阀**：`maxSwitchesPerStep` 限制每 step 切换次数、`alwaysModeRetryCap` 限制 always 模式重试——链循环不会放大延迟。
-- **无配置回归（no-op）**：`enabled` 默认关闭；未配置任何链时行为与未安装插件完全一致。
+- **无配置回归（no-op）**：未配置任何链时行为与未安装插件完全一致——`enabled` 默认关闭（见 [最小配置](#最小配置)）。
+
+## dsh-tui profile（终端）
+
+在 dsh-tui profile 中，插件有三个操作面——职责严格区分：
+
+- **`/fallbacks`** —— 本次会话发生了什么：来源、解析角色、生效链、最近降级切换、冷却状态。只读。
+- **`/fallbacks config`** —— 配置了什么：组合配置回读（触发码、根链、分时槽、时区、角色、角色规则、冷却、回主策略、安全阀、预置、角色自动匹配）。除唯一的动作命令 **`/fallbacks config revert-seed <role-id>`** 外只读——该命令把某个 seed 角色的 persona 还原为已声明的默认（设置 seam 无法表达 Web 卡的这类动作能力）。
+- **`/settings`** —— 编辑界面。插件注册 **fallbacks** 区块，与 **Web 设置卡完全一致**：布尔（`enabled`、`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 唯一编辑面。
+
+文件编辑在任意情况下仍然可用：全局设置写共享的 `$DSH_HOME/settings.yaml`（`fallbacks:` 分节——与 Web 卡写的是同一个文件）；dsh-tui 专属覆盖写 profile patch `~/.dsh/profiles/dsh-tui/cordis.patch.yml`（插件行上的 `config:` 覆盖）。注意：patch 行会**整体替换**目标行的整个 `config`——想保留的字段都要写全（schema 默认值补齐其余）。
 
 ## 模型选择器中的 FallbacksChain
 
-当 `enabled: true` 时，插件注册一个虚拟 provider **FallbacksChain**，目录中只有一行：**Auto**。web profile 与 dsh-tui 都能看到这一行：两者共享同一个 adapter catalog，无需 TUI 设置页或宿主补丁。该行只要插件启用就可见——遗留多模型或空的 all-day 链**不会**隐藏它（只是覆盖不会生效）。
+当 `enabled: true` 时，插件注册一个虚拟 provider **FallbacksChain**，目录中只有一行：**Auto**。web profile 与 dsh-tui 都能看到这一行：两者共享同一个 adapter catalog，无需设置页接线或宿主补丁（它与 `/settings` 的 fallbacks 区块相互独立——区块编辑的是配置，不是选择器目录）。该行只要插件启用就可见——遗留多模型或空的 all-day 链**不会**隐藏它（只是覆盖不会生效）。
 
 选择 **FallbacksChain / Auto** = 把配置的链作为 root **主模型**：root 请求路由到请求时刻生效链的第一个精确 `provider/model`，失败后由降级引擎从该链头照常沿链切换。选择任何真实目录模型则保持 v0.2.2 的 fallback-only 行为——会话模型为主，链只在它失败后介入。
 

package/dist/client/index.d.ts

@@ -12,8 +12,10 @@
  *   `/api/fallbacks/get|set|reset`), while `settings.describe` (writable +
  *   namespace directory) and the provider/model catalog stay on
  *   `connection.api` (see `fallbacks-store.ts`).
- * - Registers the `settings.plugin.item` card `key: 'fallbacks'` (the rc.7
- *   keyed slot — no `id`/`order`) with a business-only inject face
+ * - Registers the `settings.plugin.item` card `key: 'fallbacks'` with a
+ *   matching `id: 'fallbacks'` (the rc.7 keyed slot — no `order`; the id
+ *   keeps the card mountable on hosts that still declare the slot as a list,
+ *   which requires `options.id`) with a business-only inject face
  *   ({@link FallbacksSettingsController} + the snapshot-selector hook); the
  *   old Settings-nav section registration is removed — deleting the section
  *   registration deletes the nav entry.

package/dist/client/index.js

@@ -180,7 +180,8 @@ window.__ModuleLoader__.load({
 		* Parse a chain key or entry selector.
 		*
 		* Accepts `provider/model` and `provider/*`; throws {@link SelectorError}
-		* on anything else (missing separator, empty parts, extra separators).
+		* on anything else (missing separator, empty parts, wildcard inside the
+		* model segment).
 		*/
 		function parseSelector(input) {
 			if (typeof input !== "string") throw new SelectorError(`invalid selector ${String(input)}: expected "provider/model" or "provider/*"`);
@@ -190,7 +191,7 @@ window.__ModuleLoader__.load({
 			const provider = trimmed.slice(0, slash).trim();
 			const modelPart = trimmed.slice(slash + 1).trim();
 			if (!provider || !modelPart) throw new SelectorError(`invalid selector "${input}": empty provider or model`);
-			if (modelPart.includes("/")) throw new SelectorError(`invalid selector "${input}": unexpected extra separator`);
+			if (modelPart !== "*" && modelPart.includes("*")) throw new SelectorError(`invalid selector "${input}": unexpected wildcard in model`);
 			return {
 				provider,
 				model: modelPart === "*" ? void 0 : modelPart,
@@ -4385,15 +4386,17 @@ window.__ModuleLoader__.load({
 				};
 			}, "llm-fallbacks: pushed invalidations");
 			ctx.slots.inject("settings.plugin.item", function* () {
-				yield ctx.slots.register({
+				const cardOptions = {
 					name: "settings.plugin.item",
 					key: "fallbacks",
+					id: "fallbacks",
 					locale: NS,
 					inject: () => ({
 						controller,
 						useSnapshot
 					})
-				}, FallbacksCard);
+				};
+				yield ctx.slots.register(cardOptions, FallbacksCard);
 			});
 			ctx.slots.inject("settings.general.item", function* () {
 				yield ctx.slots.register({

package/dist/commands.d.ts

@@ -11,12 +11,17 @@
  * the command is silently absent when no command registry is composed (no
  * top-level inject pollution — advisor T1 fix).
  *
- * The handler is **read-only**: it never mutates fallback state (no cooldown
- * reset, no pending-switch writes). zh/en copy lives in this file — the
- * client half's `src/client/locales.ts` is a separate client-side dictionary.
- * The host carries no per-session locale signal (the `locale` service is
- * client-side), so the wiring picks a deterministic default (`zh`, this
- * repo's primary language); both dictionaries are unit-tested.
+ * The bare diagnostic and the config readback are **read-only**: they never
+ * mutate fallback state (no cooldown reset, no pending-switch writes). The
+ * `config revert-seed <role-id>` subcommand is the one write action (plan
+ * fallbacks-tui-settings Task 2, AC-3): it delegates to the controller's
+ * `revertSeed` (wired to the seeds service) and prints the outcome — a
+ * web-card action capability the settings seam cannot express. zh/en copy
+ * lives in this file — the client half's `src/client/locales.ts` is a
+ * separate client-side dictionary. The host carries no per-session locale
+ * signal (the `locale` service is client-side), so the wiring picks a
+ * deterministic default (`zh`, this repo's primary language); both
+ * dictionaries are unit-tested.
  *
  * @module dsh-llm-fallbacks/commands
  */
@@ -24,7 +29,8 @@ import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
 import { type FallbacksRole } from './config.ts';
 import type { Origin } from './roles.ts';
 import type { FallbacksSwitchEventData } from './events.ts';
-import type { SlotRowConfig } from './time-slots.ts';
+import type { SeedRevertFailReason } from './seeds.ts';
+import { type SlotRowConfig } from './time-slots.ts';
 /** How many recent `fallbacks/switch` events `/fallbacks` shows (newest first). */
 export declare const RECENT_SWITCHES_LIMIT = 5;
 /** Minimal command registry surface (satisfied by the dsh `CommandService`). */
@@ -90,15 +96,40 @@ export interface FallbacksCommandSnapshot {
  * entities carry id/persona/chain/fallback (NO per-role `model`;
  * `provider`/`model` live on `roles.rules`), so the readback line is id +
  * chain count, never a rules dump.
+ *
+ * Enriched readback (plan fallbacks-tui-settings Task 2, AC-4): timeSlots /
+ * tz / roles.rules join the summary so TUI operators can verify `/settings`
+ * edits. One summarized time-slot row: preset rows carry `{ preset,
+ * chainCount }` (windows are frozen code constants in {@link PRESETS} and
+ * never stored on the row — the render resolves the window text from
+ * PRESETS); custom rows carry `{ start, end, chainCount }`. Rules rows carry
+ * `{ provider, model, role }` — an omitted provider/model (wildcard match at
+ * runtime) is summarized as `''` and rendered as `*`.
  */
 export interface FallbacksConfigSummary {
     readonly enabled: boolean;
     readonly triggerCodes: readonly string[];
     readonly rootChain: readonly string[];
+    /** Summarized time-slot rows (preset rows carry `preset`, custom rows carry `start`/`end`; both may carry a day mask). */
+    readonly timeSlots: readonly {
+        preset?: string;
+        start?: string;
+        end?: string;
+        days?: readonly number[];
+        chainCount: number;
+    }[];
+    /** Config-level timezone for slot matching (default `Asia/Shanghai`). */
+    readonly tz: string;
     readonly roles: readonly {
         id: string;
         chainCount: number;
     }[];
+    /** Summarized role rules: provider/model patterns → declared role (or the built-in `'inherit'`). */
+    readonly rules: readonly {
+        provider: string;
+        model: string;
+        role: string;
+    }[];
     readonly cooldownMs: number;
     readonly revertPolicy: string;
     readonly maxSwitchesPerStep: number;
@@ -122,6 +153,23 @@ export interface FallbacksCommandController {
      * same live config source the runtime reads. Never mutates state.
      */
     getConfig(): FallbacksConfigSummary;
+    /**
+     * Revert one role's persona to its CURRENT declared seed default (AC-3).
+     * Surfaces the outcome as VALUES, not copy (qc1 F-003 / qc2 F-006 / qc3
+     * F-003): `ok: true` when reverted; `ok: false` with the
+     * {@link SeedRevertFailReason} code explaining why not (not a seeded role
+     * / role row absent). The command handler localizes the code per its
+     * registration locale — the controller never pre-localizes. A
+     * settings-write failure propagates loudly as a rejected promise (the
+     * same contract as the seeds service — never swallowed into an
+     * `ok: false`); the handler maps it to a structured error. Implemented by
+     * the wiring against the per-apply seed manager
+     * (`seeds.revert(roleId, seedsIo)`), not the typert gateway.
+     */
+    revertSeed(roleId: string): Promise<{
+        ok: boolean;
+        reason?: SeedRevertFailReason;
+    }>;
 }
 /** zh/en dictionaries for the `/fallbacks` output. */
 export declare const FALLBACKS_COMMAND_LOCALES: {
@@ -129,7 +177,8 @@ export declare const FALLBACKS_COMMAND_LOCALES: {
         readonly title: "当前会话 fallback 诊断（只读）";
         readonly description: "查看当前会话的降级链、最近降级切换与冷却状态（只读）";
         readonly usageConfig: "查看组合后的 fallbacks 配置（设置回读）";
-        readonly usage: "  /fallbacks config   查看组合后的 fallbacks 配置（设置回读）";
+        readonly usageRevertSeed: "将角色的 persona 还原为已声明的 Seed 默认";
+        readonly usage: "  /fallbacks config   查看组合后的 fallbacks 配置（设置回读）\n  /fallbacks config revert-seed <role-id>   将角色的 persona 还原为已声明的 Seed 默认";
         readonly origin: "会话来源";
         readonly role: "角色";
         readonly chain: "链";
@@ -153,22 +202,37 @@ export declare const FALLBACKS_COMMAND_LOCALES: {
         readonly configTriggerCodes: "触发码";
         readonly configRootChain: "根链";
         readonly configEmpty: "（空）";
+        readonly configTimeSlots: "分时槽";
+        readonly configSlotPresetItem: "{preset}（chain: {n}, window {window}）";
+        readonly configSlotPresetBare: "{preset}（chain: {n}）";
+        readonly configSlotCustomItem: "custom {start}-{end}（chain: {n}）";
+        readonly configTz: "时区";
         readonly configRoles: "角色";
         readonly configRoleItem: "{id}（chain: {n}）";
+        readonly configRules: "角色规则";
         readonly configCooldown: "冷却";
         readonly configRevert: "回主策略";
         readonly configMaxSwitches: "单步最大切换";
         readonly configAlwaysCap: "always 上限";
         readonly configPresets: "预置";
         readonly configRoleAutoMatch: "角色自动匹配";
-        readonly configEdit: "编辑：~/.dsh/profiles/<profile>/cordis.patch.yml（插件行）或 $DSH_HOME/settings.yaml（fallbacks: 分节）";
-        readonly configEditHint: "TUI 无法修改配置——只能编辑文件";
+        readonly configEdit: "编辑：/settings（TUI 设置界面）或 ~/.dsh/profiles/<profile>/cordis.patch.yml（插件行）/ $DSH_HOME/settings.yaml（fallbacks: 分节）";
+        readonly configEditHint: "TUI 通过 /settings 修改配置；文件编辑仍然可用";
+        readonly revertSeedOk: "角色 {id} 已还原为 Seed 默认";
+        readonly revertSeedFail: "角色 {id} 未还原（{reason}）";
+        readonly revertSeedError: "角色 {id} 还原失败（设置写入失败）";
+        readonly revertSeedReason: {
+            readonly 'not-seeded': "未声明种子";
+            readonly 'row-absent': "角色行不存在";
+            readonly 'settings-unavailable': "设置通道不可用";
+        };
     };
     readonly en: {
         readonly title: "Session fallback diagnostics (read-only)";
         readonly description: "Inspect fallback chain, recent fallback switches, and cooldown for this session (read-only)";
         readonly usageConfig: "show the composed fallbacks config (settings readback)";
-        readonly usage: "  /fallbacks config   show the composed fallbacks config (settings readback)";
+        readonly usageRevertSeed: "revert a role's persona to its declared seed default";
+        readonly usage: "  /fallbacks config   show the composed fallbacks config (settings readback)\n  /fallbacks config revert-seed <role-id>   revert a role's persona to its declared seed default";
         readonly origin: "Session origin";
         readonly role: "Role";
         readonly chain: "Chain";
@@ -192,29 +256,53 @@ export declare const FALLBACKS_COMMAND_LOCALES: {
         readonly configTriggerCodes: "Trigger codes";
         readonly configRootChain: "Root chain";
         readonly configEmpty: "(empty)";
+        readonly configTimeSlots: "Time slots";
+        readonly configSlotPresetItem: "{preset} (chain: {n}, window {window})";
+        readonly configSlotPresetBare: "{preset} (chain: {n})";
+        readonly configSlotCustomItem: "custom {start}-{end} (chain: {n})";
+        readonly configTz: "TZ";
         readonly configRoles: "Roles";
         readonly configRoleItem: "{id} (chain: {n})";
+        readonly configRules: "Rules";
         readonly configCooldown: "Cooldown";
         readonly configRevert: "Revert";
         readonly configMaxSwitches: "Max switches/step";
         readonly configAlwaysCap: "Always-mode cap";
         readonly configPresets: "Presets";
         readonly configRoleAutoMatch: "Auto-match";
-        readonly configEdit: "Edit: ~/.dsh/profiles/<profile>/cordis.patch.yml (plugin row) or $DSH_HOME/settings.yaml (fallbacks: section)";
-        readonly configEditHint: "TUI cannot change config — edit files only";
+        readonly configEdit: "Edit: /settings (TUI settings screen) or ~/.dsh/profiles/<profile>/cordis.patch.yml (plugin row) / $DSH_HOME/settings.yaml (fallbacks: section)";
+        readonly configEditHint: "TUI edits config via /settings; file editing still works";
+        readonly revertSeedOk: "role {id} reverted to its seed default";
+        readonly revertSeedFail: "role {id} not reverted ({reason})";
+        readonly revertSeedError: "role {id} revert failed (settings write failed)";
+        readonly revertSeedReason: {
+            readonly 'not-seeded': "not a seeded role";
+            readonly 'row-absent': "role row absent";
+            readonly 'settings-unavailable': "settings channel unavailable";
+        };
     };
 };
 /** A locale id supported by {@link FALLBACKS_COMMAND_LOCALES}. */
 export type FallbacksCommandLocale = keyof typeof FALLBACKS_COMMAND_LOCALES;
-/** The `/fallbacks` subcommands: `'config'` (composed-config readback) or
- * `''` (the bare session snapshot). */
-export type FallbacksSubcommand = '' | 'config';
+/** The `/fallbacks` subcommands: `'config'` (composed-config readback),
+ * `'revert-seed'` (persona revert action, requires a role id), or `''` (the
+ * bare session snapshot). */
+export type FallbacksSubcommand = '' | 'config' | 'revert-seed';
+/** One parsed subcommand invocation: the kind plus the optional role id
+ * carried by `revert-seed`. */
+export interface FallbacksSubcommandParse {
+    readonly kind: FallbacksSubcommand;
+    /** The role id argument of `revert-seed` (present iff `kind === 'revert-seed'`). */
+    readonly arg?: string;
+}
 /**
  * Map an invocation's rawInput to a subcommand: trimmed `'config'` →
- * `'config'`; everything else (incl. empty) → `''` (bare snapshot). Lenient
- * by design — unknown input keeps today's bare behavior, never errors.
+ * `{ kind: 'config' }`; `'config revert-seed <id>'` → `{ kind: 'revert-seed',
+ * arg: id }`; everything else (incl. empty, a missing id, or an unknown
+ * subcommand under `config`) → `{ kind: '' }` (bare snapshot). Lenient by
+ * design — unknown input keeps today's bare behavior, never errors.
  */
-export declare function parseFallbacksSubcommand(rawInput: string): FallbacksSubcommand;
+export declare function parseFallbacksSubcommand(rawInput: string): FallbacksSubcommandParse;
 /**
  * The newest `limit` `fallbacks/switch` events from a session's raw event
  * log, newest first. Unknown event shapes and malformed `fallbacks/switch`
@@ -248,18 +336,23 @@ export declare function resolveChainForDiagnostic(roles: readonly FallbacksRole[
     readonly inherit: boolean;
 };
 /**
- * Cap for long list lines in the composed-config readback: beyond this many
- * items a line truncates with `…` (the `Roles:` count always stays the FULL
- * count). Same sanity scale as {@link RECENT_SWITCHES_LIMIT}.
+ * Cap for the composed-config readback's LIST lines — Trigger codes, Root
+ * chain, Time slots, Roles, and Rules (qc2 Task-2 Minor): beyond this many
+ * items a line truncates with `…` while its leading count always stays the
+ * FULL count. Same sanity scale as {@link RECENT_SWITCHES_LIMIT}.
  */
 export declare const FALLBACKS_CONFIG_LIST_CAP = 5;
 /**
  * Render the `/fallbacks config` surface (plan fallbacks-tui-client T2,
- * AC-2): the composed `fallbacks` namespace as the runtime reads it + file-only
- * edit hints (TUI has no write surface). The FIRST LINE marks the
- * composed-config readback — distinct from the diagnostic title and never
- * merged into {@link fallbacksCommandText} (two operator surfaces, product
- * lock). Locale defaults to `zh` (the command default); en dictionary tested.
+ * AC-2 + fallbacks-tui-settings Task 2 AC-4): the composed `fallbacks`
+ * namespace as the runtime reads it — enriched with the time-slot rows
+ * (preset rows resolve their frozen window from {@link PRESETS}), the
+ * config timezone, and the role rules — plus edit hints pointing at the
+ * `/settings` TUI edit surface while keeping the file-edit documentation.
+ * The FIRST LINE marks the composed-config readback — distinct from the
+ * diagnostic title and never merged into {@link fallbacksCommandText} (two
+ * operator surfaces, product lock). Locale defaults to `zh` (the command
+ * default); en dictionary tested.
  */
 export declare function fallbacksConfigText(summary: FallbacksConfigSummary, locale?: FallbacksCommandLocale): string;
 /**

package/dist/gateway.d.ts

@@ -214,6 +214,23 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      */
     private seedsIo;
 }
+/**
+ * Reject a patch the `Config` schema cannot express: non-object input, unknown
+ * top-level keys (schemastery merges them silently — the settings service
+ * would accept them), and schema type violations — plus the Task 3 semantic
+ * guards the permissive schema deliberately does not carry: nested `roles`
+ * keys, `timeSlots` row shapes (unknown preset ids, duplicate presets, preset
+ * rows carrying windows, non-`HH:mm` custom bounds, out-of-range days, empty
+ * chains), and the all-day `rootChain` head conformance.
+ *
+ * Exported (plan fallbacks-tui-settings Task 1): the TUI settings section's
+ * JSON-field `parse` mirrors the gateway save rules through this single
+ * validator (it internally routes `timeSlots` → {@link validateTimeSlotsPatch}),
+ * so an invalid draft blocks the TUI save exactly like a rejected gateway
+ * patch. No shared-module extraction — the two-keyword diff is the minimal
+ * change.
+ */
+export declare function validateConfigPatch(patch: unknown): void;
 /**
  * The explicit typert contribution for the `fallbacks` gateway endpoints —
  * registered via `ctx.typert.register(...)` (see `apply` in `src/index.ts`).