dsh-model-reasoning-defaults 0.0.3 → 0.0.4

package/README.md

@@ -9,6 +9,9 @@
 
 - **仓库**：<https://github.com/xht-code/dsh-model-reasoning-defaults>
 
+> [!IMPORTANT]
+> 本版本（0.0.4+）面向 **DSH 0.1.7-alpha.2 及以上的设置体系**：设置项由 profile entry 的 `Config` schema 派生，可编辑字段必须声明为 `volatile`，写回落在 profile patch。旧版宿主（0.1.6 及以前）请使用 0.0.3。
+
 ## 安装 / 更新
 
 安装插件到指定的 DSH profile：
@@ -34,10 +37,10 @@ dsh plugin --profile web remove dsh-model-reasoning-defaults
 ## 核心特性
 
 - **多层级灵活路由**：支持从具体模型、Provider 通配到全局兜底的 6 级优先级匹配机制。
-- **设置页可视化编辑**：在 Web 设置页「推理等级默认」中直接增删路由并选择等级，保存即时生效（带修订号并发保护）。
+- **设置页可视化编辑**：在 Web 设置页「推理等级默认」中直接增删路由并选择等级。路由表存放在插件自身的配置项里并声明为 `volatile`，宿主原地更新引用而不重载插件，保存后对新请求立即生效（带修订号并发保护）。
 - **全入口统一注入**：无缝覆盖 Agent 主循环（`agent/request`）、直接调用（`llm.stream`）以及预准备入口（`prepareCall` / `resolveCallConfig`）。
 - **对象安全与不可变性保证**：采用非破坏性浅复制机制，安全处理 `Object.freeze` 深冻结请求，原请求对象与未命中的配置始终保持只读与纯净。
-- **跨副本的 Loop 边界识别**：不依赖 `@deepseek-ai/dsh-llm` 副本私有的 `WeakSet`，而按公开请求契约识别同时具备 `sessionId` 与顶层冻结状态的 Loop 请求，避免宿主与插件解析到不同模块副本时误复制请求。
+- **宿主标识直读**：loop 请求识别直接使用 DSH 导出的 `isAgentLoopRequest`（基于宿主 `markAgentLoopRequest` 进程标识），不维护自建登记表，跨模块副本与热重载天然一致。
 - **无缝热重载（Hot-Reload Safe）**：基于 `RuntimePatchState` 管理多 Fiber 状态，配置变更即时生效，仅在最后一个插件 Fiber 卸载时还原原始方法，杜绝方法悬挂。
 
 ---
@@ -65,59 +68,32 @@ dsh plugin --profile web remove dsh-model-reasoning-defaults
 
 ### 方式 1：在 Web 设置页中直接编辑（推荐）
 
-打开 Web 端 **设置 →「推理等级默认」**，即可增删路由行并从下拉框选择推理等级，保存后对新请求**即时生效**（无需重启或重载）。数据存储在本插件注册的 `model-reasoning-defaults` 设置命名空间（落盘于 `settings.yaml`），经宿主统一 settings API 写入：
+打开 Web 端 **设置 →「推理等级默认」**，即可增删路由行并从下拉框选择推理等级，保存后对新请求**即时生效**（无需重启或重载）。设置页经宿主统一 settings Remote 把改动写回插件自身的配置项（profile patch 中 id 为 `model-reasoning-defaults` 的 entry）：
 
 ```yaml
-# settings.yaml（设置页保存后的落盘结果）
-model-reasoning-defaults:
-  defaults:
-    "deepseek-official:*": high
-    "*": medium
+# ~/.dsh/profiles/<profile>/cordis.patch.yml（设置页保存后的落盘结果）
+- id: model-reasoning-defaults
+  name: dsh-model-reasoning-defaults
+  config:
+    defaults:
+      "deepseek-official:*": high
+      "*": medium
 ```
 
 > [!NOTE]
+> - 写入按路径寻址（对 `defaults.<路由键>` 设值或删除），因此删除路由会真正落盘，也不会碰到同一 entry 里的结构化字段。
 > - 路由键支持全部六级写法；等级下拉框为已知集合（off/minimal/low/medium/high/xhigh/max），也接受手工输入其它值。
-> - 编辑器带修订号保护：两个标签页同时编辑时，后保存的一方会被拒绝而不是静默覆盖。
+> - 编辑器带修订号保护：两个标签页同时编辑时，后保存的一方会被拒绝并刷新到最新版本，而不是静默覆盖。
 > - 面板内嵌匹配语义说明（六级优先级次序与生效优先级），输入路由键时可参考已配置的 Provider/Model 建议。
+> - 面板展示的是**解析后**的生效路由表（组合层 + 用户层）。如果某个键是由 **bundle 组合层**（而非 profile 用户层）提供的，宿主会把删除改写成"写回该层原值"，删除这类键需要改动提供它的那一层；本插件自带 bundle 不提供 `defaults`，按方式 2 / 方式 3 在用户层声明的键不受影响。
 
-### 方式 2：直接在 DSH 模型设置中声明（零侵入）
-
-在 DSH 设置服务（宿主通常从 `$DSH_HOME/settings.yaml` 装载）中，插件会自动读取 `llm-pi-ai` 与 `llm-deepseek` 命名空间里已声明的思考等级，无需单独配置插件项：
-
-```yaml
-# settings.yaml
-llm-pi-ai:
-  providers:
-    my-gateway:
-      apiKeyEnv: GATEWAY_API_KEY
-      baseURL: https://gateway.example/v1
-      # 1. Provider 级默认思考等级（llm-pi-ai 原生字段）
-      reasoning: medium
-      models:
-        # 2. 模型级默认思考等级（本插件扩展读取的字段，见下方说明）
-        - id: deepseek-reasoner
-          reasoning: high
-        - id: deepseek-chat
-          reasoning: low
-
-    # 3. 官方目录 Provider：在 modelOverrides 中为具体模型指定默认思考等级
-    #    （同为扩展读取字段）
-    anthropic:
-      apiKeyEnv: ANTHROPIC_API_KEY
-      modelOverrides:
-        claude-3-7-sonnet:
-          reasoning: high
-
-llm-deepseek:
-  # 4. DeepSeek 官方 Provider 默认思考等级（原生字段，映射到 deepseek-official 路由）
-  reasoningEffort: high
-```
-
-> [!IMPORTANT]
-> - 上例第 2、3 处的模型级 `reasoning` 是**本插件扩展读取的约定字段**：`llm-pi-ai` 的 schema 在模型层声明的原生字段是 `reasoningEfforts`（"可选等级集合 + 线格式映射"的能力声明，语义是模型**能选什么**），并非默认值选择（模型**默认选什么**）；本插件读取的 `reasoning` 依赖其设置解析对未声明键的透传行为。若上游收紧解析策略，这部分提取会静默失效（届时请改用方式 3 / 方式 4 显式声明）。另注意：注入的默认等级若不在目标模型 `reasoningEfforts` 声明集合内，会被适配器拒绝。
-> - 每个来源只认单一规范字段：`llm-pi-ai` 用 `reasoning`，`llm-deepseek` 用 `reasoningEffort`，两者不可混写。
+> [!NOTE]
+> **Provider 级默认值由 DSH 各 Provider 原生处理，本插件不再重复读取。**
+> `llm-pi-ai` 的 `providers.<id>.reasoning` 与 `llm-deepseek` 的 `reasoningEffort`
+> 在请求未显式携带 `reasoningEffort` 时由适配器自行应用，与本插件注入的结果等价；
+> 需要**模型级**或**跨 Provider** 的默认值时，请用下面的方式 2 / 方式 3 写进本插件的路由表。
 
-### 方式 3：在插件配置中按 Provider/Model 结构声明
+### 方式 2：在插件配置中按 Provider/Model 结构声明
 
 插件的配置通过 loader 补丁体系按 entry id 定位。在用户补丁层（如 `~/.dsh/profiles/<profile>/cordis.patch.yml`）按同一 id 覆盖 `config`：
 
@@ -142,7 +118,7 @@ llm-deepseek:
       another-gateway: low
 ```
 
-### 方式 4：扁平路由映射字典
+### 方式 3：扁平路由映射字典
 
 直接使用扁平的 `defaults` 路由字典，与结构化形式是同等的配置入口：
 
@@ -158,13 +134,14 @@ llm-deepseek:
 ```
 
 > [!TIP]
-> 各配置形式可以自由组合，归一化到同一张路由表后统一检索。命中由上表的**键特异性**全局裁决，与配置来自哪个文件无关；来源仅在**同一路由键**冲突时按以下优先级覆盖（高 → 低）：
+> 各配置形式可以自由组合，归一化到同一张路由表后统一检索。命中由上表的**键特异性**全局裁决（例如精确键 `my-gateway:deepseek-reasoner` 胜过 Provider 通配键 `my-gateway:*`），与配置写在哪个文件无关。整条链路对同一个请求的生效优先级（高 → 低）：
 >
-> 1. 插件 cordis 配置（patch 层 `defaults` 显式路由键 > 结构化 `providers`/`models` 项）
-> 2. 设置页 UI（`model-reasoning-defaults` 命名空间，方式 1）
-> 3. 设置服务自动提取项（`llm-pi-ai` / `llm-deepseek` 原生字段，方式 2）
+> 1. 请求自带的 `reasoningEffort`（插件绝不覆盖）
+> 2. 本插件路由表：`defaults` 显式路由键（设置页写入或 patch 层声明）> 结构化 `providers`/`models` 项
+> 3. Provider 原生默认值（`llm-pi-ai` 的 `reasoning`、`llm-deepseek` 的 `reasoningEffort`）
+> 4. Provider 内建兜底（如 `llm-deepseek` 的 `high`／`thinking: disabled` 时的 `off`）
 >
-> 例如设置服务给出精确键 `my-gateway:deepseek-reasoner: high`、插件仅配通配键 `providers.my-gateway = medium` 时，精确键胜出（得 `high`）。
+> 因此插件路由表可以精确覆盖某个模型，而不必改动 Provider 自身的默认值。
 
 ---
 
@@ -180,7 +157,7 @@ llm-deepseek:
   【Agent Loop 请求】                                   【手写 / 辅助请求】
   (agent/request Waterfall)                             (llm.stream / prepareCall)
          │                                                     │
- 注入默认 reasoningEffort                          sessionId + 冻结边界判定
+  注入默认 reasoningEffort                          isAgentLoopRequest 判定
   到调用配置种子（loop 随后据此构建完整                     │
   请求并深冻结、打宿主进程标识）              ┌─────────────┴─────────────┐
          │                                       ▼                           ▼
@@ -197,27 +174,29 @@ llm-deepseek:
 
 ### 1. Agent 主循环请求处理
 - 注册全局 `agent/request` waterfall 监听器。此阶段操作的是调用配置种子，完整请求对象尚未构建；插件按路由计算默认等级并注入 `reasoningEffort`。
-- loop 随后将该配置连同派生消息组装为完整请求，写入 `sessionId`、深冻结并打上宿主 `markAgentLoopRequest` 进程标识。
-- 请求进入 `llm.stream` 入口时，入口包装按公开的 `sessionId + Object.freeze` 契约识别 loop 请求，**直接按原引用透传**。不读取模块副本私有的 `isAgentLoopRequest` 标识，避免宿主与插件加载不同 `dsh-llm` 副本时误复制请求。
+- loop 随后将该配置连同派生消息组装为完整请求，深冻结并打上宿主 `markAgentLoopRequest` 进程标识。
+- 请求进入 `llm.stream` 入口时，入口包装用宿主导出的 `isAgentLoopRequest` 识别 loop 请求，**直接按原引用透传**——浅复制会丢失该进程标识，导致 compaction 与请求观察者把会话请求误判为手写一次性请求。
 
 ### 2. 手写及辅助调用处理
 - 直接调用 `llm.stream(options)` 时，入口包装在 waterfall **开始前**执行拦截。
-- 对不带该 Loop 边界契约的请求（包括带 `purpose: 'compaction'` 的辅助请求），通过浅复制补齐 `reasoningEffort` 后再进入下游链路。
+- 对不带 loop 标识的请求（包括带 `purpose: 'compaction'` 的辅助请求），通过浅复制补齐 `reasoningEffort` 后再进入下游链路。
 
 ### 3. 配置准备与解析入口
 - 同步拦截 `llm.prepareCall` 与 `llm.resolveCallConfig`，在预计算阶段统一应用相同的路由查找规则，并完整透传 `AbortSignal`。
 
 ### 4. 共享状态与热重载安全
-- LLM 方法包装层内部维护 `RuntimePatchState`，通过 `defaults: Map<symbol, ReasoningDefaults>` 跟踪每个活跃 Fiber 的配置版本。
-- 插件重新加载时，新 Fiber 创建的配置层会立即生效并覆盖旧配置；旧 Fiber 卸载时仅移除自身 token，只有当所有 Fiber 都卸载时才彻底还原原始 LLM 方法。
+- LLM 方法包装层内部维护 `RuntimePatchState`，通过 `sources: Map<symbol, RouteTableSource>` 跟踪每个活跃 Fiber 的路由表来源（结构化字段快照 + `defaults` 的 volatile 引用）。
+- 插件重新加载时，新 Fiber 的路由表来源会立即生效并覆盖旧来源；旧 Fiber 卸载时仅移除自身 token，只有当所有 Fiber 都卸载时才彻底还原原始 LLM 方法。
+- 设置页保存只改动 `defaults`（volatile 字段），宿主原地更新其引用而不重载插件；插件在每次请求时读取当下快照，所以空路由表也照常安装包装层——否则运行期新增的路由要等宿主重启才会生效。
 
 ---
 
 ## 客户端支持
 
 本插件包含 Web 客户端扩展（`src/client/index.ts`）：
-- 注册到 DSH 设置页槽位 `settings.section`（「推理等级默认」面板）：增删路由行、从已知等级集合下拉选择，保存写入本插件的 `model-reasoning-defaults` 设置命名空间。
-- 数据经宿主统一 settings Remote（`remote.settings.describe` / `replace`）实时读取渲染；保存携带 `expectedRevision` 修订号，并发编辑时由宿主裁决而非静默覆盖。保存走 `replace`（整段替换）而非 `update`（merge patch）：merge 语义下省略键不表达删除，删除的路由会被存储层原样保留。
+- 注册到 DSH 设置页槽位 `settings.section`（「推理等级默认」面板）：增删路由行、从已知等级集合下拉选择，保存写入本插件配置项（entry id `model-reasoning-defaults`）的 `defaults` 字段。
+- 数据经宿主统一 settings Remote（`remote.settings.describe` / `mutate`）读取渲染；保存携带 `expectedRevision` 修订号，并发编辑时由宿主裁决而非静默覆盖。写入使用**路径寻址操作**（对 `defaults.<路由键>` 设值或删除）：merge 语义下省略键不表达删除，只有 `unset` 才能把删除落盘，同时不触碰同一 entry 里的结构化字段。
+- 保存撞上修订号冲突时保留本地编辑并刷新到宿主最新版本，提示用户再次保存覆盖。
 - 路由键输入带建议弹层（来自 `llm-pi-ai` / `llm-deepseek` 已配置的 Provider/Model），面板内展示匹配语义与生效优先级说明。
 
 ---
@@ -271,7 +250,7 @@ dsh plugin --profile web remove dsh-model-reasoning-defaults
 ## 注意事项与设计说明
 
 1. **推理等级有效性校验时机**：
-   配置阶段仅校验字符串非空，具体推理等级（如 `low` / `medium` / `high`）是否被目标模型支持，由 DSH 底层适配器在实际发起请求时校验（未支持将抛出 `UNSUPPORTED_REASONING_EFFORT`）。插件会在激活时与设置提取过程中对照已知等级集合（`off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`）提示可疑取值，但不阻断注入，以便上游新增等级时无需同步升级本插件。
+   配置阶段仅校验字符串非空，具体推理等级（如 `low` / `medium` / `high`）是否被目标模型支持，由 DSH 底层适配器在实际发起请求时校验（未支持将抛出 `UNSUPPORTED_REASONING_EFFORT`）。插件会在激活时、以及读取运行期写入的路由表时对照已知等级集合（`off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`）提示可疑取值（同一问题只告警一次），但不阻断注入，以便上游新增等级时无需同步升级本插件。
 2. **会话持久化影响**：
    由插件注入的默认值经 `llm.prepareCall` 后将作为显式参数写入请求头。在长会话进行中若热更新修改了配置规则，已创建的历史请求头不会被回溯修改。
 3. **发布与打包约束**：

package/cordis.patch.yml

@@ -1,6 +1,7 @@
 # bundle patch 层：向 profile 插入本插件入口行。
-# 启用时在用户层按同一 entry id 覆盖整个 config（include 补丁体系按 id 定位），
-# config 支持结构化 providers/models、扁平 defaults 字典或两者混用：
+# 该 entry 的 config 既可由设置页写入，也可在用户层按同一 entry id 覆盖
+# （include 补丁体系按 id 定位）；config 支持结构化 providers/models、
+# 扁平 defaults 字典或两者混用：
 #
 # - id: model-reasoning-defaults
 #   config:
@@ -14,7 +15,9 @@
 #       o3-mini: high
 #     reasoningEffort: low
 #
-#     # 扁平路由映射字典（与结构化产生同键时覆盖结构化项）
+#     # 扁平路由映射字典（与结构化产生同键时覆盖结构化项）。
+#     # 设置页只编辑这一段：它声明为 volatile，宿主原地更新引用，
+#     # 保存后无需重载插件即可对新请求生效。
 #     defaults:
 #       "my-gateway:deepseek-reasoner": high
 #       "my-gateway:*": medium

package/lib/client.js

@@ -6,17 +6,94 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react = require("react");
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		//#region src/client/route-table.ts
+		/** 路由表在配置项中的字段名：操作路径的前缀。 */
+		const DEFAULTS_FIELD = "defaults";
+		/**
+		* 把路由字典展开成按键排序的可编辑行。
+		*
+		* @param defaults - 路由字典。
+		* @returns 稳定排序的行列表。
+		*/
+		function rowsOf(defaults) {
+			return Object.entries(defaults).map(([key, effort]) => ({
+				key,
+				effort
+			})).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+		}
+		/**
+		* 把存储中"外部新增"的路由键并入当前编辑行，用于冲突后的重试保存。
+		*
+		* 只补 `latest` 相对 `previous` 新增的键：差异语义是"行里没有即删除"，补进来的
+		* 外部新增键可避免重试时顺手删掉它们；而用户自己删掉或改名的键本来就在
+		* `previous` 里，绝不能再补回来——补回来等于把删除意图覆盖成"键仍在行中"，
+		* 用户会发现该路由怎么都删不掉，重命名也会退化成"新增"。
+		*
+		* @param rows - 当前编辑的行。
+		* @param previous - 发起本次保存所用的基线，即用户编辑所依据的键集。
+		* @param latest - 宿主当前生效的路由表。
+		* @returns 合并后的行列表，按键排序（空键行是待填写的残渣，排在末尾）。
+		*/
+		function mergeStoredRows(rows, previous, latest) {
+			const known = new Set(rows.map((row) => row.key.trim()).filter((key) => key.length > 0));
+			const appended = Object.entries(latest).filter(([key]) => !Object.hasOwn(previous, key) && !known.has(key)).map(([key, effort]) => ({
+				key,
+				effort
+			}));
+			return [...rows, ...appended].sort((a, b) => {
+				const left = a.key.trim();
+				const right = b.key.trim();
+				if (left.length === 0) return right.length === 0 ? 0 : 1;
+				if (right.length === 0) return -1;
+				return left < right ? -1 : left > right ? 1 : 0;
+			});
+		}
+		/**
+		* 把编辑后的行集合与存储基线做差异，折叠成路径寻址的写入操作。
+		*
+		* 只写差异而不是整段覆盖：宿主按路径写入，删除路由才能落盘（省略键不表达删除），
+		* 同时不动同一配置项里的结构化字段。
+		*
+		* @param baseline - 存储中当前生效的路由表。
+		* @param rows - 当前编辑的行。
+		* @returns 写入操作列表；路由键重复时返回错误消息。
+		*/
+		function buildRouteOps(baseline, rows) {
+			const next = Object.create(null);
+			for (const row of rows) {
+				const key = row.key.trim();
+				if (key.length === 0) continue;
+				if (Object.hasOwn(next, key)) return { error: "存在重复路由键：" + key };
+				next[key] = row.effort;
+			}
+			const ops = [];
+			for (const [key, effort] of Object.entries(next)) if (baseline[key] !== effort) ops.push({
+				op: "set",
+				path: [DEFAULTS_FIELD, key],
+				value: effort
+			});
+			for (const key of Object.keys(baseline)) if (!Object.hasOwn(next, key)) ops.push({
+				op: "unset",
+				path: [DEFAULTS_FIELD, key]
+			});
+			return ops;
+		}
+		//#endregion
 		//#region src/client/index.ts
 		/**
 		* dsh-model-reasoning-defaults 的客户端半体。
 		*
-		* - 设置页 section：编辑本插件设置命名空间中的扁平路由表，经宿主统一的
-		*   settings API 写入。Host 每次请求实时读取该层，保存即生效。
+		* - 设置页 section：编辑本插件配置项（profile patch 中 id 为
+		*   model-reasoning-defaults 的 `defaults` 字段）里的扁平路由表，经宿主统一的
+		*   settings Remote 写入。Host 每次请求实时读取该 volatile 字段，保存即生效。
 		*
 		* 控件一律使用官方 @deepseek-ai/dsh-client-ui-primitives（平台基线模块，
 		* 宿主模块表直接应答），与设置壳视觉一致。
 		*/
-		/** 本插件的设置命名空间，与 Host 侧 UI_DEFAULTS_NAMESPACE 一致。 */
+		/**
+		* 本插件的设置命名空间。宿主侧的命名空间就是配置项 id——插件自带 bundle patch
+		* 插入的那条 loader entry 的 id（见仓库根目录 cordis.patch.yml），不是插件名。
+		*/
 		const SETTINGS_NS = "model-reasoning-defaults";
 		/** 已知推理等级集合（与 Host 侧 KNOWN_REASONING_EFFORTS 保持一致）。 */
 		const KNOWN_EFFORTS = [
@@ -45,13 +122,24 @@ window.__ModuleLoader__.load({
 		function findOwnNamespace(namespaces) {
 			const own = namespaces.find((entry) => entry.ns === SETTINGS_NS);
 			if (own === void 0) return void 0;
-			const section = own.value;
 			return {
-				defaults: section !== null && typeof section === "object" && section.defaults !== void 0 && typeof section.defaults === "object" ? { ...section.defaults } : {},
+				defaults: defaultsOf(own.value),
 				revision: own.revision
 			};
 		}
 		/**
+		* 从命名空间解析值中取出路由字典。
+		*
+		* @param value - 命名空间视图的解析值。
+		* @returns 路由字典副本；形状不符时为空对象。
+		*/
+		function defaultsOf(value) {
+			const section = value;
+			if (section === null || typeof section !== "object") return {};
+			const defaults = section.defaults;
+			return defaults !== void 0 && typeof defaults === "object" ? { ...defaults } : {};
+		}
+		/**
 		* 从 describe 应答中收集已知 provider 与 provider:model 路由键，作为输入建议。
 		*
 		* @param namespaces - describe 应答携带的命名空间视图列表。
@@ -166,40 +254,13 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		/**
-		* 把路由字典展开成按键排序的可编辑行。
-		*
-		* @param defaults - 路由字典。
-		* @returns 稳定排序的行列表。
-		*/
-		function rowsOf(defaults) {
-			return Object.entries(defaults).map(([key, effort]) => ({
-				key,
-				effort
-			})).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
-		}
-		/**
-		* 校验待保存的行集合并折叠回路由字典。
-		*
-		* @param rows - 当前编辑的行。
-		* @returns 校验通过时返回字典；失败时返回错误消息。
-		*/
-		function collapseRows(rows) {
-			const result = {};
-			for (const row of rows) {
-				const key = row.key.trim();
-				if (key.length === 0) continue;
-				if (key in result) return { error: "存在重复路由键：" + key };
-				result[key] = row.effort;
-			}
-			return result;
-		}
-		/**
 		* 设置页「推理等级默认」编辑面板。
 		*
 		* 数据流：挂载时 describe 读一次（拿路由表、修订号、只读标记与建议键）；
-		* 保存时带 expectedRevision 做 update，陈旧编辑会被宿主拒绝而不是静默覆盖。
-		* 外部改动（另一标签页、手工编辑 yaml）在本组件重新挂载时可见——设置壳每次
-		* 打开都重新挂载 section，无需订阅失效事件。
+		* 保存时把编辑差异作为路径操作连同 expectedRevision 发出，陈旧编辑会被宿主
+		* 拒绝而不是静默覆盖——撞上冲突时保留本地编辑并刷新修订号，用户再保存一次
+		* 即可覆盖。外部改动（另一标签页、手工编辑 profile patch）在本组件重新挂载时
+		* 可见——设置壳每次打开都重新挂载 section，无需订阅失效事件。
 		*
 		* @param props - 无属主属性（close 由壳持有，本面板不离开设置页）。
 		* @returns 面板节点树。
@@ -213,7 +274,10 @@ window.__ModuleLoader__.load({
 			const [suggestions, setSuggestions] = (0, react.useState)([]);
 			const [openMenuIndex, setOpenMenuIndex] = (0, react.useState)(null);
 			const [suggestIndex, setSuggestIndex] = (0, react.useState)(null);
-			const revisionRef = (0, react.useState)(() => ({ revision: 0 }))[0];
+			const store = (0, react.useState)(() => ({
+				defaults: {},
+				revision: 0
+			}))[0];
 			(0, react.useEffect)(() => {
 				let cancelled = false;
 				const load = async () => {
@@ -238,12 +302,13 @@ window.__ModuleLoader__.load({
 							setPhase("unavailable");
 							setFeedback({
 								kind: "error",
-								text: "Host 未注册 " + SETTINGS_NS + " 命名空间，请确认插件已启用并刷新页面"
+								text: "Host 未提供 " + SETTINGS_NS + " 配置项，请确认插件已启用并刷新页面"
 							});
 							return;
 						}
+						store.defaults = own.defaults;
+						store.revision = own.revision;
 						setRows(rowsOf(own.defaults));
-						revisionRef.revision = own.revision;
 						setWritable(response.value.writable);
 						setSuggestions(collectSuggestions(response.value.namespaces));
 						setPhase("ready");
@@ -261,37 +326,64 @@ window.__ModuleLoader__.load({
 				return () => {
 					cancelled = true;
 				};
-			}, [revisionRef]);
+			}, [store]);
 			const save = async () => {
 				const api = currentApi;
 				if (api === void 0 || saving) return;
-				const collapsed = collapseRows(rows);
-				if ("error" in collapsed) {
+				const ops = buildRouteOps(store.defaults, rows);
+				if ("error" in ops) {
 					setFeedback({
 						kind: "error",
-						text: collapsed.error
+						text: ops.error
+					});
+					return;
+				}
+				if (ops.length === 0) {
+					setFeedback({
+						kind: "ok",
+						text: "没有需要保存的改动"
 					});
 					return;
 				}
 				setSaving(true);
 				setFeedback(void 0);
 				try {
-					const response = await api.replace(SETTINGS_NS, { defaults: collapsed }, revisionRef.revision);
+					const response = await api.mutate(SETTINGS_NS, ops, store.revision);
 					if (!response.ok) {
+						if (response.error.code === "settings/conflict") {
+							const latest = await api.describe();
+							const own = latest.ok ? findOwnNamespace(latest.value.namespaces) : void 0;
+							if (own === void 0) {
+								setFeedback({
+									kind: "error",
+									text: "配置已被其它页面或文件修改，且重新读取失败" + (latest.ok ? "（Host 未提供 " + SETTINGS_NS + " 配置项）" : "：" + latest.error.message) + "；请关闭并重新打开设置页后再试。"
+								});
+								return;
+							}
+							const previous = store.defaults;
+							store.defaults = own.defaults;
+							store.revision = own.revision;
+							setRows((current) => mergeStoredRows(current, previous, own.defaults));
+							setOpenMenuIndex(null);
+							setSuggestIndex(null);
+							setFeedback({
+								kind: "error",
+								text: "配置已被其它页面或文件修改，已刷新最新版本；请再次保存以覆盖。"
+							});
+							return;
+						}
 						setFeedback({
 							kind: "error",
 							text: response.error.message
 						});
 						return;
 					}
-					const reread = await api.describe();
-					if (reread.ok) {
-						const own = findOwnNamespace(reread.value.namespaces);
-						if (own !== void 0) {
-							setRows(rowsOf(own.defaults));
-							revisionRef.revision = own.revision;
-						}
-					}
+					const stored = defaultsOf(response.value.value);
+					store.defaults = stored;
+					store.revision = response.value.revision;
+					setRows(rowsOf(stored));
+					setOpenMenuIndex(null);
+					setSuggestIndex(null);
 					setFeedback({
 						kind: "ok",
 						text: "已保存，对新请求即时生效"
@@ -317,7 +409,7 @@ window.__ModuleLoader__.load({
 			if (!writable) children.push((0, react.createElement)("p", {
 				key: "readonly",
 				style: mutedStyle
-			}, "当前设置文档为只读，修改需在 Host 侧完成。"));
+			}, "当前 profile 不接受写入，修改需在 Host 侧完成。"));
 			for (let index = 0; index < rows.length; index += 1) {
 				const row = rows[index];
 				const menuOpen = openMenuIndex === index;
@@ -399,12 +491,12 @@ window.__ModuleLoader__.load({
 						onClick: () => {
 							setOpenMenuIndex(menuOpen ? null : index);
 						}
-					}, row.effort, (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14))
+					}, row.effort, (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutlineRegular, { size: 14 }))
 				}), (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.Button, {
 					key: "remove",
 					variant: "ghost",
 					size: "sm",
-					icon: (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.IconTrashOutline16),
+					icon: (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.IconTrashOutlineRegular),
 					"aria-label": "删除路由 " + row.key,
 					title: "删除该路由",
 					onClick: () => {
@@ -420,7 +512,7 @@ window.__ModuleLoader__.load({
 			}, (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.Button, {
 				variant: "outline",
 				size: "sm",
-				icon: (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.IconPlusOutline16),
+				icon: (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.IconPlusOutlineRegular),
 				onClick: () => setRows([...rows, {
 					key: "",
 					effort: "medium"
@@ -428,7 +520,7 @@ window.__ModuleLoader__.load({
 			}, "添加路由"), (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.Button, {
 				variant: "primary",
 				size: "sm",
-				disabled: saving || !writable || rows.length === 0,
+				disabled: saving || !writable,
 				onClick: () => {
 					save();
 				}
@@ -436,7 +528,7 @@ window.__ModuleLoader__.load({
 			children.push((0, react.createElement)("p", {
 				key: "hint",
 				style: hintStyle
-			}, "已知等级：" + KNOWN_EFFORTS.join(" / ") + "。生效优先级：patch 层插件配置 > 此处 > Host 各 Provider 已声明的思考等级。路由键支持 * 通配，聚焦输入框可查看已配置 Provider/Model 的建议。"));
+			}, "已知等级：" + KNOWN_EFFORTS.join(" / ") + "。路由表写入本插件的 profile 配置项，仅覆盖未显式指定 reasoningEffort 的请求。路由键支持 * 通配，聚焦输入框可查看已配置 Provider/Model 的建议。"));
 			if (feedback !== void 0) children.push((0, react.createElement)("p", {
 				key: "feedback",
 				style: { ...feedback.kind === "error" ? errorStyle : okStyle }