dsh-decision-engine 0.5.1 → 0.6.0

package/README.md

@@ -66,6 +66,29 @@ cd ~/.dsh/profiles/desktop && pnpm install
   （笔记、备份）一概不碰。
 - **权限 600**：配置里可能有明文 key，迁移后仍保持只有你可读。
 
+### 数据目录解析规则（跨平台）
+
+数据目录是 **`$DSH_HOME/dsh-decision-engine/`**，`~/.dsh` 只是 `DSH_HOME`
+未设置时的默认值。解析顺序与宿主 `@deepseek-ai/dsh-home-paths` 完全一致：
+
+| 优先级 | 来源 |
+|---|---|
+| 1 | 显式配置的路径（本插件暂无此入口） |
+| 2 | 环境变量 `$DSH_HOME` |
+| 3 | 操作系统家目录下的 `~/.dsh` |
+
+细节（都由 `lib/home-paths.js` 统一处理）：
+
+- **空白值等于未设置**：`DSH_HOME=""` 或纯空白会回退 `~/.dsh`，绝不会把数据
+  目录解析到当前工作目录。
+- **支持波浪号**：`DSH_HOME=~/myhome` 会展开；`~\`（Windows 形式）同样支持。
+- **相对路径会被规范化成绝对路径**，否则落盘位置会随进程工作目录漂移。
+
+**Windows 说明**：`~/.dsh` 里的 `.dsh` 只是**目录名**，不是路径分隔符——
+Windows 允许点开头的目录。真正与平台相关的是分隔符与家目录位置，二者分别由
+`node:path` 与 `node:os` 处理，所以 Windows 上实际路径是
+`C:\Users\<你的用户名>\.dsh\dsh-decision-engine\config.yml`。
+
 ## 配置
 
 ### 插件配置页
@@ -77,14 +100,21 @@ cd ~/.dsh/profiles/desktop && pnpm install
 - 两个开关：`启用守卫`、`真正拦截`
 - **思考模式**下拉：`never` / `auto` / `always`（见下文「省 token 的手段」里的取舍）
 - **模型**下拉（来自当前 provider 的 `/v1/models`，含「自动（服务端默认）」）
-- 一个 **API Key 输入框** + `保存` 按钮
+- 一个 **API Key 输入框**
 - 选 `custom` 时展开四个字段：`Base URL`（必填）、`端点风格`、`附加请求头`、`密钥变量名`
 - 一个 `测试端点` 按钮（回显 provider、实际 POST 的完整地址、HTTP 码、请求 id 与响应体）
 - **决策模型参与点**列表：每个决策点一行，右侧是 `关闭 / 观察 / 生效` 三态
 - `自身 token 预算` 输入框，以及实时的缓存命中率与每个点的 token / 延迟统计
 
-改完点`保存`即写入 `config.yml`，**不需要重启**：监听器常驻注册，provider 与
-模式在每次调用时现读；预算与缓存参数同样是取值函数而非启动期快照。
+**改完即保存，没有「保存」按钮**：开关 / 下拉 / 分段控件点一下就落盘；文本框
+（地址、请求头、预算）停手约 0.7 秒或失焦后落盘；API Key 只在**失焦或回车**
+时落盘（避免把打字途中的半截 key 写进凭据文件）。底部状态行实时显示
+`待保存… / 保存中… / 已保存 / 未保存：原因`，失败时附「重试」。落盘即写入
+`config.yml`，**不需要重启**：监听器常驻注册，provider 与模式在每次调用时现读；
+预算与缓存参数同样是取值函数而非启动期快照。
+
+一个例外：选 `custom` 但 `Base URL` 还没填或不合法时，配置改动会**整体延后**
+（状态行给出原因），地址补全后自动落盘；此时决策点改动不受影响，照常保存。
 
 ## Provider：接任意 system-one 风格服务
 
@@ -170,7 +200,7 @@ content-type: application/json
 | `credentials`（默认） | `~/.dsh/.credentials.yaml` 的 `refs:` 段 | 与其他服务（DeepSeek / ModelScope …）统一托管，插件目录不留明文 |
 | `config` | 插件配置目录下的 `config.yml` | 希望配置自包含、能随目录整体备份或迁移；注意是**明文** |
 
-在设置界面「密钥保存位置」下拉切换，保存后立即按新位置写入；已有的 key 不会被
+在设置界面「密钥保存位置」下拉切换，切换即按新位置写入；已有的 key 不会被
 自动搬家（避免"看不到的地方被改动"），需要时重新粘贴一次即可。
 
 写入 `credentials` 的行为约束：
@@ -187,7 +217,7 @@ content-type: application/json
 
 | 情形 | 表现 |
 |---|---|
-| base URL 非法 / 为空（custom） | 保存直接被拒（HTTP 400 + 具体原因，如「必须以 http:// 或 https:// 开头」），**不会写进 yml** |
+| base URL 非法 / 为空（custom） | 该次落盘直接被拒（HTTP 400 + 具体原因，如「必须以 http:// 或 https:// 开头」），**不会写进 yml**；自动保存会一直挂着「未保存」并允许重试 |
 | 密钥缺失 | 不发请求，`no-key` 降级（记录里带该 provider 的变量名） |
 | 鉴权失败（401/403） | `auth-failed` 降级，提示检查该 provider 的 key 是否有效、是否与地址匹配 |
 | 地址错（404/400） | `http-404` / `http-400` 降级，记录里带 `provider`、`endpoint` 与响应体 |
@@ -393,7 +423,7 @@ pnpm verify            # 前两条一起跑
 | `test/engine.test.js` | 适配器接线、off/observe/enforce 语义、全部降级分支 |
 | `test/providers.test.js` | provider 预设、地址拼接、URL 校验、鉴权与请求构造 |
 | `test/config-file.test.js` | `config.yml` 读写往返：保存后再打开的回显、切换不互相覆盖 |
-| `test/client-ui.test.js` | 设置界面渲染：provider 下拉、custom 字段、错误提示 |
+| `test/client-ui.test.js` | 设置界面渲染与交互：provider 下拉、custom 字段、错误提示、**改动即保存**（无保存按钮、改动自动 PUT /config、API Key 失焦提交） |
 
 `test/providers.test.js` 是 provider 改造的验收用例（不依赖宿主依赖，
 裸仓库可直接跑），覆盖六项硬约束：

package/lib/client.js

@@ -83,7 +83,7 @@ window.__ModuleLoader__.load({
         background: "#fff",
         transition: "transform .15s ease",
       },
-      /** 保存按钮。 */
+      /** 小按钮（获取模型 / 测试端点 / 重试）。 */
       saveBtn: {
         padding: "6px 14px",
         borderRadius: "6px",
@@ -216,13 +216,164 @@ window.__ModuleLoader__.load({
       return data;
     }
 
-    /** 主面板：配置 + 状态 + 一键测试 + 最近决策。 */
+    /**
+     * 自动保存的防抖时长：文本框停手多久之后落盘。
+     *
+     * 太短会把打字过程中的半截值写进 yml（每个字符一次请求），太长则
+     * 「改完立刻关掉面板」会丢改动。700ms 是这两者之间的常见折中。
+     */
+    const AUTOSAVE_DELAY_MS = 700;
+
+    /**
+     * 自定义 base URL 的问题描述，空串表示可用。
+     *
+     * 规则与服务端 `validateProviderPatch` 一致：本地先判，是为了让「打字打到一半
+     * 的非法地址」停在本地（显示红字），而不是每停一下就发一次注定 400 的请求。
+     *
+     * @param rawUrl - 用户填写的地址（未 trim）。
+     * @param provider - 当前 provider；只有 custom 时空地址才是「必填缺失」。
+     */
+    function customUrlProblem(rawUrl, provider) {
+      const url = (rawUrl ?? "").trim();
+      if (url.length === 0) {
+        return provider === "custom" ? "必填：请填写 system-one 风格服务的 base URL" : "";
+      }
+      if (/\s/.test(url)) return "不能包含空格或换行";
+      if (!/^https?:\/\//i.test(url)) return "必须以 http:// 或 https:// 开头";
+      try {
+        const parsed = new URL(url);
+        if (parsed.search.length > 0) return "不要带查询串（? 之后的部分）";
+      } catch {
+        return "不是合法地址（示例：https://api.example.com/v1）";
+      }
+      return "";
+    }
+
+    /**
+     * 待落盘的决策点/预算改动，没有改动时返回 null。
+     *
+     * 与 `/decisions` 的 PUT body 同形（`{ points?, budgetTokens? }`）：
+     * 服务端对空 body 直接 400，所以「没改动就不发」必须由调用方保证。
+     */
+    function pendingDecisions(values, decisions) {
+      const changed = {};
+      for (const [id, mode] of Object.entries(values.pointsDraft ?? {})) {
+        const original = (decisions?.points ?? []).find((item) => item.id === id);
+        if (original !== undefined && original.mode !== mode) changed[id] = mode;
+      }
+      const limit = decisions?.budget?.limit ?? 0;
+      const budget =
+        values.budgetDraft !== null && values.budgetDraft !== undefined && values.budgetDraft !== limit
+          ? values.budgetDraft
+          : null;
+      const hasPoints = Object.keys(changed).length > 0;
+      if (hasPoints !== true && budget === null) return null;
+      const body = {};
+      if (hasPoints === true) body.points = changed;
+      if (budget !== null) body.budgetTokens = budget;
+      return body;
+    }
+
+    /**
+     * 由「当前值」拼出 `/config` 的 PUT patch。
+     *
+     * 与旧版「点保存」时提交的内容逐字一致，只是取值来源从渲染闭包换成了
+     * `valuesRef`（setState 是异步的，自动保存必须读到刚改完的值）。
+     *
+     * @param values - `{ draft, providerDraft, keyInputs, storageDraft }`。
+     * @param keyCommit - 用户明确提交密钥的 provider（失焦/回车），否则 null。
+     */
+    function configPatchOf(values, keyCommit) {
+      const draft = values.draft;
+      const provider = values.providerDraft;
+      const patch = {
+        enabled: draft.enabled === true,
+        mode: draft.mode,
+        // 思考模式总是提交：它是全局项（与 provider 无关），服务端还会再校验一次。
+        thinkMode: draft.thinkMode ?? "never",
+        // 模型字段只写当前 provider 自己那一格（model / systemoneModel /
+        // customModel）。混写会让「切过去再切回来」丢掉原值，也会把
+        // bamboonode 的模型名发给别的服务。
+        ...(provider.provider === "custom"
+          ? { customModel: (provider.customModel ?? "").trim() }
+          : provider.provider === "systemone"
+            ? { systemoneModel: (draft.systemoneModel ?? "").trim() }
+            : { model: (draft.model ?? "").trim() }),
+        provider: provider.provider,
+        customEndpointStyle: provider.customEndpointStyle ?? "auto",
+        // custom 的字段总是带上：用户可能先填地址再切 provider，
+        // 分开提交会让中间状态被当成最终配置。
+        customHeaders: (provider.customHeaders ?? "").trim(),
+        customApiKeyEnv: (provider.customApiKeyEnv ?? "").trim(),
+      };
+      // customBaseUrl 只在**合法**时提交。空串对内置 provider 是合法的
+      //（等于不覆盖），对 custom 则是必填缺失——那种情况整笔延后，见 flush()。
+      // 不合法的值一律不发：服务端会拒，而打字途中的每一次拒绝都是噪音。
+      const url = (provider.customBaseUrl ?? "").trim();
+      if (customUrlProblem(url, provider.provider) === "") patch.customBaseUrl = url;
+      // 保存位置：只在用户改过时才提交，避免每次保存都覆盖。
+      if (values.storageDraft !== null && values.storageDraft !== undefined) {
+        patch.keyStorage = values.storageDraft;
+      }
+      // 密钥：只有用户明确提交（失焦 / 回车）且长度够时才带上。
+      // 否则打字过程中每停一下都会把半截 key 写进凭据文件。
+      if (keyCommit !== null && keyCommit !== undefined) {
+        const raw = (values.keyInputs[keyCommit] ?? "").trim();
+        if (raw.length >= 10) {
+          if (keyCommit === "systemone") patch.systemoneApiKey = raw;
+          else if (keyCommit === "custom") patch.customApiKey = raw;
+          else patch.bamboonodeApiKey = raw;
+        }
+      }
+      return patch;
+    }
+
+    /**
+     * patch 是否真的与服务端当前状态不同。
+     *
+     * 自动保存会频繁调用：不做这个比较，用户改一个决策点也会重写一次
+     * config.yml（白改 mtime、白触发一次热加载）。比较对象是 status 回显，
+     * 也就是「服务端认为的值」——与旧版「保存按钮的可用条件」同一语义。
+     *
+     * @param patch - `configPatchOf` 拼出的 patch。
+     * @param view - `/status` 回显（缺字段时用安全默认）。
+     */
+    function patchDiffersFromServer(patch, view) {
+      const pairs = [
+        ["enabled", view.enabled === true],
+        ["mode", view.mode ?? "shadow"],
+        ["thinkMode", view.thinkMode ?? "never"],
+        ["provider", view.provider ?? "bamboonode"],
+        ["customBaseUrl", view.customBaseUrl ?? ""],
+        ["customEndpointStyle", view.customEndpointStyle ?? "auto"],
+        ["customModel", view.customModel ?? ""],
+        ["model", view.rawModel ?? ""],
+        ["systemoneModel", view.rawSystemoneModel ?? ""],
+        ["customHeaders", view.customHeaders ?? ""],
+        ["customApiKeyEnv", view.customApiKeyEnv ?? ""],
+        ["keyStorage", view.keyStorage ?? "credentials"],
+      ];
+      for (const [key, server] of pairs) {
+        if (Object.hasOwn(patch, key) && String(patch[key] ?? "") !== String(server ?? "")) return true;
+      }
+      // 密钥字段一出现就代表「有新 key 要写」：服务端只回传掩码，没法比较，
+      // 而且重复写同一个 key 是无害的（幂等覆盖）。
+      return ["systemoneApiKey", "bamboonodeApiKey", "customApiKey"].some((key) => Object.hasOwn(patch, key));
+    }
+
     /**
      * 配置页：仿照内置 dsh-rewind-plugin 的卡片布局——
-     * 每行左侧是「标题 + 灰色说明」，右侧是开关；底部一个「保存」按钮。
+     * 每行左侧是「标题 + 灰色说明」，右侧是控件。
+     *
+     * **改完即保存，没有「保存」按钮**：
+     *   - 开关 / 下拉 / 分段控件：点一下就落盘；
+     *   - 文本框（地址、请求头、预算）：停手 `AUTOSAVE_DELAY_MS` 后落盘，失焦立刻落盘；
+     *   - API Key：失焦或回车才落盘（见 `commitKey`）。
+     * 落盘状态显示在底部一行（保存中 / 已保存 / 失败原因 + 重试），
+     * 取代了原来那个按钮。
      *
      * 数据全部走本插件自己的 `/api/decision-engine/*`，**不用** settings 服务
-     *（旧插件死在 `settings.installSection` 上）。保存即改写 config.yml。
+     *（旧插件死在 `settings.installSection` 上）。落盘即改写 config.yml。
      *
      * @param props - 槽位属性；`view === "summary"` 时只渲染一行摘要文本。
      */
@@ -238,7 +389,6 @@ window.__ModuleLoader__.load({
       // 而不是在这里写一份硬编码默认：否则「status 已回来但 useEffect 还没跑」
       // 的那一帧会显示错的值（例如把 custom 显示成 bamboonode）。
       const [draftState, setDraft] = react.useState(null);
-      const [dirty, setDirty] = react.useState(false);
       // provider 草稿：与主配置分开保存，因为 custom 的五个字段是「先填后切」，
       // 混进主 draft 会让「只切 provider」也顺手把没填完的 custom 值写进去。
       const [providerDraftState, setProviderDraft] = react.useState(null);
@@ -255,11 +405,35 @@ window.__ModuleLoader__.load({
       const [pointsDraft, setPointsDraft] = react.useState({});
       const [budgetDraft, setBudgetDraft] = react.useState(null);
 
-      // 用 ref 保存「用户是否有未保存改动」，使 refresh 不因 dirty 变化而重建。
-      // 否则保存时 setDirty(false) → refresh 换新引用 → useEffect 再跑一次，
-      // 与 save 里的 setStatus 竞争，可能用旧值把刚保存的开关覆盖回去（表现为回弹）。
+      // 用 ref 保存「用户是否有未保存改动」，使 refresh 不因状态变化而重建。
+      // 否则落盘时 setDirty(false) → refresh 换新引用 → useEffect 再跑一次，
+      // 与 flush 里的 setStatus 竞争，可能用旧值把刚保存的开关覆盖回去（表现为回弹）。
       const dirtyRef = react.useRef(false);
       const savingRef = react.useRef(false);
+      // 落盘状态：null（无提示）| "saving" | "saved" | { error }。取代原来的保存按钮。
+      const [saveState, setSaveState] = react.useState(null);
+      /**
+       * 待落盘值的唯一真源。
+       *
+       * 不能用渲染闭包里的 `draft`：`setState` 是异步的，一次事件里改完立刻
+       * 发请求时闭包里还是旧值（会把改动存丢）。因此所有控件先同步写这里，
+       * 再 setState 触发重绘；flush 只读这里。
+       */
+      const valuesRef = react.useRef(null);
+      /** 每次改动自增：用来判断「响应回来时用户是否又改过」，避免旧快照覆盖新输入。 */
+      const editSeqRef = react.useRef(0);
+      /** 防抖计时器。 */
+      const timerRef = react.useRef(null);
+      /** 本次待落盘是否要连配置一起写（仅决策点改动时为 false）。 */
+      const pendingRef = react.useRef(null);
+      /**
+       * 明确提交密钥的 provider（失焦 / 回车）。
+       *
+       * 与普通改动分开：密钥不能随防抖自动提交，否则打字途中每停一下都会把
+       * 半截 key 写进凭据文件；这里记下「这一次是用户按下提交」，flush 时
+       * 才把它并进 patch，成功后清空。
+       */
+      const keyCommitRef = react.useRef(null);
 
       const refresh = react.useCallback(async () => {
         // 保存进行中不拉状态，避免用旧快照覆盖刚写入的结果。
@@ -363,7 +537,7 @@ window.__ModuleLoader__.load({
       const draft = draftState ?? {
         enabled: view.enabled === true,
         mode: view.mode ?? "shadow",
-        // 思考模式也走 draft：改完点保存才落盘，与开关语义一致。
+        // 思考模式也走 draft：与其它控件一致，改完即自动落盘。
         thinkMode: view.thinkMode ?? "never",
         model: view.rawModel ?? "",
         systemoneModel: view.rawSystemoneModel ?? "",
@@ -401,148 +575,185 @@ window.__ModuleLoader__.load({
           customApiKeyEnv: next.customApiKeyEnv ?? "",
         });
         setProviderError(next.providerValid === false ? next.providerError ?? "配置不可用" : "");
-        setDirty(false);
         dirtyRef.current = false;
       };
 
+      // 每次渲染把「当前值」同步进 ref：控件在事件里读它，flush 也读它。
+      // 放在渲染期赋值（而不是 useEffect）是必须的——useEffect 在提交之后才跑，
+      // 而事件处理器可能在它之前就读到 ref，那样拿到的还是上一次的值。
+      valuesRef.current = { draft, providerDraft, keyInputs, storageDraft, pointsDraft, budgetDraft };
+
       /**
-       * provider 相关改动是否待保存。
+       * 自动保存引擎。
+       *
+       * 三个动作：
+       *   - `scheduleSave(partial, immediate)`：控件改动后调用。先**同步**并入
+       *     `valuesRef`，再按需立即（开关/下拉）或防抖（文本框）落盘。
+       *   - `flush()`：真正发请求。串行、合并，按需分两次（`/config` + `/decisions`）。
+       *   - `commitKey(provider)`：密钥的「明确提交」（失焦 / 回车）。
        *
-       * 逐字段比较而不是维护一个独立的 dirty 标记：切到 custom 又切回来、
-       * 或者填了字又删掉，都应当回到「无改动」而不是永远亮着保存按钮。
+       * 三条不变量（都是这个界面反复踩过的坑）：
+       *
+       *   1. 同一时刻只有一个请求在飞（`savingRef`）。期间的改动只并入
+       *      `valuesRef`，等这次回来再发——并发保存会让两次快照互相覆盖。
+       *   2. 响应回来时若用户又改过（`editSeqRef` 变了），**不覆盖草稿**，
+       *      只刷新服务端状态。否则「保存中的输入被旧快照冲掉」= 回弹。
+       *   3. 失败不丢输入、也不自动重试：原因写进状态行，等用户改或点重试。
+       *      自动重试一个注定 400 的请求只会刷屏。
        */
-      const providerChanged = (() => {
-        const server = {
-          provider: view.provider ?? "bamboonode",
-          customBaseUrl: view.customBaseUrl ?? "",
-          customEndpointStyle: view.customEndpointStyle ?? "auto",
-          customModel: view.customModel ?? "",
-          customHeaders: view.customHeaders ?? "",
-          customApiKeyEnv: view.customApiKeyEnv ?? "",
-        };
-        const storageChanged = storageDraft !== null && storageDraft !== (view.keyStorage ?? "credentials");
-        const draftChanged = Object.keys(server).some(
-          (key) => (providerDraft[key] ?? "") !== (server[key] ?? ""),
-        );
-        return draftChanged || storageChanged;
-      })();
+      const flushRef = react.useRef(null);
 
-      const save = react.useCallback(
-        async (patch) => {
-          setBusy("save");
-          setMsg(null);
-          savingRef.current = true;
-          try {
-            const next = await call("/config", {
-              method: "PUT",
-              headers: { "content-type": "application/json" },
-              body: JSON.stringify(patch),
-            });
-            applyServerState(next);
-            setMsg({ ok: true, text: "已保存" });
-            if (Object.hasOwn(patch, "apiKey")) setKeyInput("");
-          } catch (error) {
-            // 校验失败（非法 URL / 缺必填）走这里：保留用户已填内容，
-            // 只把原因显示出来——清空表单会让用户重填一遍。
-            setMsg({ ok: false, text: error.message });
-            setProviderError(error.message);
-          } finally {
-            savingRef.current = false;
-            setBusy("");
-          }
-        },
-        [],
-      );
+      /** 同步记录一次改动，并安排落盘（`immediate` 用于离散控件）。 */
+      const scheduleSave = (partial, immediate) => {
+        valuesRef.current = { ...valuesRef.current, ...(partial ?? {}) };
+        editSeqRef.current += 1;
+        dirtyRef.current = true;
+        // 防抖窗口里就先把状态改成「待保存」：否则这一小段时间还挂着上一次的
+        // 「已保存」，用户会以为刚才那一下已经落盘了。
+        setSaveState("pending");
+        if (timerRef.current !== null) {
+          clearTimeout(timerRef.current);
+          timerRef.current = null;
+        }
+        if (immediate === true) {
+          void flushRef.current();
+          return;
+        }
+        // 文本框：停手 AUTOSAVE_DELAY_MS 之后再落盘，避免每敲一个字符一次请求。
+        timerRef.current = setTimeout(() => {
+          timerRef.current = null;
+          void flushRef.current();
+        }, AUTOSAVE_DELAY_MS);
+      };
 
-      // 决策点/预算是否有待保存改动。必须在 saveDecisions 之前算：
-      // useCallback 的依赖数组会在本次渲染立即求值，放到后面会踩 TDZ。
-      const pointsChanged = Object.keys(pointsDraft).some((id) => {
-        const original = (decisions?.points ?? []).find((item) => item.id === id);
-        return original !== undefined && pointsDraft[id] !== original.mode;
-      });
-      const budgetChanged = budgetDraft !== null && budgetDraft !== (decisions?.budget?.limit ?? 0);
-      const decisionsChanged = pointsChanged || budgetChanged;
+      /**
+       * 明确提交密钥（失焦 / 回车）。
+       *
+       * 密钥刻意**不**跟着防抖走：粘贴后停一下就把半截 key 写进凭据文件，
+       * 是比多点一次更糟的体验。这里只记「这一次是用户按下提交」。
+       */
+      const commitKey = (provider) => {
+        const raw = (valuesRef.current.keyInputs[provider] ?? "").trim();
+        // 留空 = 不修改（与旧版一致）；太短的多半是没贴完，不落盘，给一句提示。
+        if (raw.length === 0) return;
+        if (raw.length < 10) {
+          setSaveState({ error: "未保存：密钥太短（至少 10 个字符）" });
+          return;
+        }
+        keyCommitRef.current = provider;
+        editSeqRef.current += 1;
+        dirtyRef.current = true;
+        if (timerRef.current !== null) {
+          clearTimeout(timerRef.current);
+          timerRef.current = null;
+        }
+        void flushRef.current();
+      };
 
       /**
-       * 保存决策点与预算。
+       * 落盘一次。
        *
-       * 走独立的 `/decisions` 而不是复用 `/config`：那两份配置的校验规则不同
-       *（决策点要拒绝未实装的点、预算要 clamp），混在一起容易互相放宽。
+       * 决策点走独立的 `/decisions` 而不是复用 `/config`：那两份配置的校验规则
+       * 不同（决策点要拒绝未实装的点、预算要 clamp），混在一起容易互相放宽。
        */
-      const saveDecisions = react.useCallback(async () => {
-        const body = {};
-        if (pointsChanged) body.points = pointsDraft;
-        if (budgetChanged) body.budgetTokens = budgetDraft;
-        if (Object.keys(body).length === 0) return true;
-        const next = await call("/decisions", {
-          method: "PUT",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify(body),
-        });
-        setDecisions(next);
-        setPointsDraft({});
-        setBudgetDraft(null);
-        return true;
-      }, [pointsChanged, budgetChanged, pointsDraft, budgetDraft]);
+      const flush = async () => {
+        if (savingRef.current === true) return;
+        if (dirtyRef.current !== true) return;
+        const values = valuesRef.current;
+        const seq = editSeqRef.current;
+        const keyCommit = keyCommitRef.current;
+        const decisionsBody = pendingDecisions(values, decisions);
+        // 打字途中的非法地址：整笔延后（服务端必然拒绝，那一次 400 只是噪音）。
+        // 决策点与地址无关，仍然照常落盘——否则改个决策点也会被地址卡住。
+        const urlProblem = customUrlProblem(
+          values.providerDraft.customBaseUrl,
+          values.providerDraft.provider,
+        );
+        const configDeferred = urlProblem.length > 0;
+        if (configDeferred === true && decisionsBody === null) {
+          setSaveState({ error: `配置未保存：${urlProblem}` });
+          return;
+        }
+
+        const patch = configPatchOf(values, keyCommit);
+        // 只要带了 key 就必须写配置：key 不能因为「其它字段没变」被漏掉。
+        const keyWritten = ["systemoneApiKey", "bamboonodeApiKey", "customApiKey"].some((key) =>
+          Object.hasOwn(patch, key),
+        );
+        const configNeeded =
+          configDeferred !== true && (keyWritten === true || patchDiffersFromServer(patch, view) === true);
 
-      /** 一次点击提交两半：主配置 + 决策点。任一失败都要报错，不能静默半保存。 */
-      const saveAll = react.useCallback(async () => {
-        setBusy("save");
-        setMsg(null);
         savingRef.current = true;
+        setSaveState("saving");
+        setMsg(null);
         setProviderError("");
+        /** 失败的到底是哪一半：只有配置那一半才该显示成「provider 配置不可用」。 */
+        let failing = "config";
         try {
-          const patch = {
-            enabled: draft.enabled === true,
-            mode: draft.mode,
-            // 思考模式总是提交：它是全局项（与 provider 无关），
-            // 服务端还会再校验一次合法取值。
-            thinkMode: draft.thinkMode ?? "never",
-            // 模型字段只写当前 provider 自己那一格（model / systemoneModel /
-            // customModel）。混写会让「切过去再切回来」丢掉原值，也会把
-            // bamboonode 的模型名发给别的服务。
-            ...(providerDraft.provider === "custom"
-              ? { customModel: (providerDraft.customModel ?? "").trim() }
-              : providerDraft.provider === "systemone"
-                ? { systemoneModel: (draft.systemoneModel ?? "").trim() }
-                : { model: (draft.model ?? "").trim() }),
-            provider: providerDraft.provider,
-            // custom 的字段**总是**一起提交：用户可能先填地址再切 provider，
-            // 分两次保存会让中间状态被当成最终配置。值为空也照写，
-            // 便于用户清空后立刻纠正（服务端只在 provider=custom 时校验必填）。
-            customBaseUrl: (providerDraft.customBaseUrl ?? "").trim(),
-            customEndpointStyle: providerDraft.customEndpointStyle ?? "auto",
-            customHeaders: (providerDraft.customHeaders ?? "").trim(),
-            customApiKeyEnv: (providerDraft.customApiKeyEnv ?? "").trim(),
-          };
-          // 只提交「当前 provider」那一格：切过去时不会顺手存下别的 provider 的 key。
-          const activeKey = (keyInputs[providerDraft.provider] ?? "").trim();
-          if (activeKey.length >= 10) {
-            if (providerDraft.provider === "systemone") patch.systemoneApiKey = activeKey;
-            else if (providerDraft.provider === "custom") patch.customApiKey = activeKey;
-            else patch.bamboonodeApiKey = activeKey;
+          if (configNeeded === true) {
+            const next = await call("/config", {
+              method: "PUT",
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify(patch),
+            });
+            // 用户又改过：只刷新服务端状态，草稿保留给下一次 flush。
+            if (seq === editSeqRef.current) applyServerState(next);
+            else setStatus(next);
           }
-          // 保存位置：只在用户改过时才提交，避免每次保存都覆盖。
-          if (storageDraft !== null) patch.keyStorage = storageDraft;
-          const next = await call("/config", {
-            method: "PUT",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(patch),
-          });
-          applyServerState(next);
-          if (Object.hasOwn(patch, "systemoneApiKey") || Object.hasOwn(patch, "bamboonodeApiKey") || Object.hasOwn(patch, "customApiKey")) {
-            setKeyInputs({ ...keyInputs, [providerDraft.provider]: "" });
+          failing = "decisions";
+          if (decisionsBody !== null) {
+            const next = await call("/decisions", {
+              method: "PUT",
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify(decisionsBody),
+            });
+            setDecisions(next);
+            // 期间又有改动时不清草稿：那些改动还没落盘，清掉就等于吞了。
+            if (seq === editSeqRef.current) {
+              setPointsDraft({});
+              setBudgetDraft(null);
+            }
+          }
+          if (seq !== editSeqRef.current) {
+            // 期间的改动由 finally 接着发，这里保持「保存中」。
+            setSaveState("saving");
+          } else if (configDeferred === true) {
+            // 决策点存了，配置那一半还欠着（等地址补全）：**保持 dirty**，
+            // 否则地址改好之后没人会再发请求，改动就悄悄丢了。
+            dirtyRef.current = true;
+            setSaveState({ error: `配置未保存：${urlProblem}` });
+          } else {
+            dirtyRef.current = false;
+            if (keyWritten === true) {
+              keyCommitRef.current = null;
+              // 存完就清空输入框：与旧版「粘贴 → 保存 → 框变空」一致，
+              // 也让「已配置」的提示能立刻反映新值。
+              setKeyInputs({ ...values.keyInputs, [keyCommit]: "" });
+            }
+            setSaveState("saved");
           }
-          await saveDecisions();
-          setMsg({ ok: true, text: "已保存" });
         } catch (error) {
-          setMsg({ ok: false, text: error.message });
-          setProviderError(error.message);
+          const text = error instanceof Error ? error.message : String(error);
+          // 校验失败（非法 URL / 请求头格式）走这里：保留用户已填内容，
+          // 只把原因显示出来——清空表单会让用户重填一遍。
+          // dirty 保持 true：失败的那一半（可能是决策点）还没落盘，
+          // 重试按钮与后续编辑都要能把它带上。
+          dirtyRef.current = true;
+          setSaveState({ error: text });
+          if (failing === "config") setProviderError(text);
         } finally {
           savingRef.current = false;
-          setBusy("");
+          // 保存期间用户又改过：立刻再发一次，不等防抖（他已经停手了）。
+          if (dirtyRef.current === true && seq !== editSeqRef.current) void flush();
         }
-      }, [draft, keyInputs, storageDraft, providerDraft, saveDecisions]);
+      };
+      flushRef.current = flush;
+
+      /** 状态行的「重试」：把上一次失败的值原样再发一遍。 */
+      const retrySave = () => {
+        dirtyRef.current = true;
+        void flushRef.current();
+      };
 
       const runTest = react.useCallback(async () => {
         setBusy("test");
@@ -634,8 +845,15 @@ window.__ModuleLoader__.load({
         if (isCustom) setProviderDraft({ ...providerDraft, customModel: value });
         else if (isSystemOne) setDraft({ ...draft, systemoneModel: value });
         else setDraft({ ...draft, model: value });
-        setDirty(true);
-        dirtyRef.current = true;
+        // 下拉是离散控件：选完即存。
+        scheduleSave(
+          isCustom
+            ? { providerDraft: { ...providerDraft, customModel: value } }
+            : isSystemOne
+              ? { draft: { ...draft, systemoneModel: value } }
+              : { draft: { ...draft, model: value } },
+          true,
+        );
       };
 
       /**
@@ -651,23 +869,10 @@ window.__ModuleLoader__.load({
             : "";
 
       /**
-       * 本地预校验：与服务端同规则，只是为了让用户在点保存之前就看到问题。
-       * 服务端仍会独立校验（前端校验不可信），这里只求「早一点提示」。
+       * 本地预校验：与服务端同规则（见模块级 `customUrlProblem`），
+       * 只是为了让用户在落盘之前就看到问题。服务端仍会独立校验（前端校验不可信）。
        */
-      const customUrlError = (() => {
-        if (!isCustom) return "";
-        const raw = (providerDraft.customBaseUrl ?? "").trim();
-        if (raw.length === 0) return "必填：请填写 system-one 风格服务的 base URL";
-        if (/\s/.test(raw)) return "不能包含空格或换行";
-        if (!/^https?:\/\//i.test(raw)) return "必须以 http:// 或 https:// 开头";
-        try {
-          const url = new URL(raw);
-          if (url.search.length > 0) return "不要带查询串（? 之后的部分）";
-        } catch {
-          return "不是合法地址（示例：https://api.example.com/v1）";
-        }
-        return "";
-      })();
+      const customUrlError = isCustom ? customUrlProblem(providerDraft.customBaseUrl, "custom") : "";
 
       /** provider 提示文案：优先用服务端下发的说明，避免前端另写一份。 */
       const providerHint =
@@ -698,8 +903,10 @@ window.__ModuleLoader__.load({
                 // 切换 provider 只改「当前用哪个」，不动其它 provider 已保存的值：
                 // custom 的字段留在 providerDraft 里，切回来还在。
                 setProviderError("");
-                setDirty(true);
-                dirtyRef.current = true;
+                // 下拉是离散控件：选完即存。切到 custom 但地址还没填时，
+                // flush 会整笔延后并提示（见 flush 里的 urlProblem），
+                // 地址补全后自动落盘，不需要再点一次。
+                scheduleSave({ providerDraft: { ...providerDraft, provider: next } }, true);
               },
             },
             ...(catalog.length === 0
@@ -732,8 +939,8 @@ window.__ModuleLoader__.load({
           toggle(draft.enabled === true, () => {
             const next = draft.enabled !== true;
             setDraft({ ...draft, enabled: next });
-            setDirty(true);
-            dirtyRef.current = true;
+            // 开关是离散控件：拨一下就落盘。
+            scheduleSave({ draft: { ...draft, enabled: next } }, true);
           }),
           "enabled",
         ),
@@ -744,8 +951,7 @@ window.__ModuleLoader__.load({
           toggle(draft.mode === "enforce", () => {
             const next = draft.mode === "enforce" ? "shadow" : "enforce";
             setDraft({ ...draft, mode: next });
-            setDirty(true);
-            dirtyRef.current = true;
+            scheduleSave({ draft: { ...draft, mode: next } }, true);
           }),
           "mode",
         ),
@@ -765,9 +971,10 @@ window.__ModuleLoader__.load({
               value: draft.thinkMode ?? "never",
               disabled: busy !== "",
               onChange: (event) => {
-                setDraft({ ...draft, thinkMode: event.target.value });
-                setDirty(true);
-                dirtyRef.current = true;
+                const next = { ...draft, thinkMode: event.target.value };
+                setDraft(next);
+                // 下拉是离散控件：选完即存。
+                scheduleSave({ draft: next }, true);
               },
             },
             // 选项由服务端下发（thinkModes），前端不硬编码取值，避免漂移。
@@ -830,7 +1037,9 @@ window.__ModuleLoader__.load({
           ),
           "model",
         ),
-        // 4) API Key：每个 provider 一格，各自保存各自的 key
+        // 4) API Key：每个 provider 一格，各自保存各自的 key。
+        //    密钥**只**在失焦或回车时落盘（commitKey）：打字途中自动保存会把
+        //    半截 key 写进凭据文件，比多一步确认更危险。
         row(
           `API Key${keyOk ? `（已配置 ${activeKeyStatus?.hint ?? view.keyHint ?? ""}）` : "（未配置）"}`,
           activeKeyStatus !== null
@@ -840,17 +1049,24 @@ window.__ModuleLoader__.load({
               // 混着说会让人去 .credentials.yaml 里找 key。
               ? `存到插件配置 config.yml 的 ${activeKeyStatus.keyField || "显式 key 字段"}（明文）`
               : `存到 .credentials.yaml 的 ${activeKeyStatus.refName}`
-            : "留空则不修改；粘贴新 key 后点保存",
+            : "留空则不修改；粘贴新 key 后失焦或回车即保存",
           h("input", {
             type: "password",
             style: S.input,
             placeholder: keyOk ? "sk-…（留空不改）" : "sk-…",
             value: keyInputs[providerDraft.provider] ?? "",
-            onChange: (event) =>
-              setKeyInputs({ ...keyInputs, [providerDraft.provider]: event.target.value }),
+            onChange: (event) => {
+              const next = { ...keyInputs, [providerDraft.provider]: event.target.value };
+              setKeyInputs(next);
+              // 同步进 ref：commitKey 读的是它。回车可能紧贴最后一次按键，
+              // 等重绘就来不及了。
+              valuesRef.current = { ...valuesRef.current, keyInputs: next };
+            },
+            // 密钥只在「明确提交」时落盘：失焦或回车。
+            onBlur: () => commitKey(providerDraft.provider),
             onKeyDown: (event) => {
               if (event.key !== "Enter") return;
-              if ((keyInputs[providerDraft.provider] ?? "").trim().length >= 10) void saveAll();
+              commitKey(providerDraft.provider);
             },
           }),
           "key",
@@ -869,8 +1085,8 @@ window.__ModuleLoader__.load({
               disabled: busy !== "",
               onChange: (event) => {
                 setStorageDraft(event.target.value);
-                setDirty(true);
-                dirtyRef.current = true;
+                // 下拉是离散控件：选完即存。
+                scheduleSave({ storageDraft: event.target.value }, true);
               },
             },
             h("option", { value: "credentials" }, ".credentials.yaml（默认）"),
@@ -898,11 +1114,13 @@ window.__ModuleLoader__.load({
                   placeholder: "https://api.example.com/v1",
                   value: providerDraft.customBaseUrl ?? "",
                   onChange: (event) => {
-                    setProviderDraft({ ...providerDraft, customBaseUrl: event.target.value });
+                    const next = { ...providerDraft, customBaseUrl: event.target.value };
+                    setProviderDraft(next);
                     setProviderError("");
-                    setDirty(true);
-                    dirtyRef.current = true;
+                    // 文本框：停手防抖落盘（打字途中的非法地址会被 flush 整笔延后）。
+                    scheduleSave({ providerDraft: next });
                   },
+                  onBlur: () => scheduleSave(null, true),
                 }),
                 "custom-url",
               ),
@@ -915,9 +1133,10 @@ window.__ModuleLoader__.load({
                     style: { ...S.input, minWidth: "150px", flex: "none" },
                     value: providerDraft.customEndpointStyle ?? "auto",
                     onChange: (event) => {
-                      setProviderDraft({ ...providerDraft, customEndpointStyle: event.target.value });
-                      setDirty(true);
-                      dirtyRef.current = true;
+                      const next = { ...providerDraft, customEndpointStyle: event.target.value };
+                      setProviderDraft(next);
+                      // 下拉是离散控件：选完即存。
+                      scheduleSave({ providerDraft: next }, true);
                     },
                   },
                   h("option", { value: "auto" }, "auto（自动）"),
@@ -935,10 +1154,11 @@ window.__ModuleLoader__.load({
                   placeholder: "X-Tenant: team-a; X-Trace: dsh",
                   value: providerDraft.customHeaders ?? "",
                   onChange: (event) => {
-                    setProviderDraft({ ...providerDraft, customHeaders: event.target.value });
-                    setDirty(true);
-                    dirtyRef.current = true;
+                    const next = { ...providerDraft, customHeaders: event.target.value };
+                    setProviderDraft(next);
+                    scheduleSave({ providerDraft: next });
                   },
+                  onBlur: () => scheduleSave(null, true),
                 }),
                 "custom-headers",
               ),
@@ -951,10 +1171,11 @@ window.__ModuleLoader__.load({
                   placeholder: "MY_DECISION_API_KEY",
                   value: providerDraft.customApiKeyEnv ?? "",
                   onChange: (event) => {
-                    setProviderDraft({ ...providerDraft, customApiKeyEnv: event.target.value });
-                    setDirty(true);
-                    dirtyRef.current = true;
+                    const next = { ...providerDraft, customApiKeyEnv: event.target.value };
+                    setProviderDraft(next);
+                    scheduleSave({ providerDraft: next });
                   },
+                  onBlur: () => scheduleSave(null, true),
                 }),
                 "custom-env",
               ),
@@ -986,6 +1207,7 @@ window.__ModuleLoader__.load({
               h("div", { style: S.sectionTitle }, "决策模型参与点"),
               ...(decisions.points ?? []).map((point) => {
                 const current = Object.hasOwn(pointsDraft, point.id) ? pointsDraft[point.id] : point.mode;
+                // 点完即存：这个角标只在「请求还在路上」的那一小会儿出现。
                 const changed = Object.hasOwn(pointsDraft, point.id) && pointsDraft[point.id] !== point.mode;
                 const st = point.stats ?? {};
                 // 「可用」与「已挂载」是两件事：点已实装（available），但宿主
@@ -1034,7 +1256,12 @@ window.__ModuleLoader__.load({
                               type: "button",
                               key: mode,
                               disabled: busy !== "",
-                              onClick: () => setPointsDraft({ ...pointsDraft, [point.id]: mode }),
+                              onClick: () => {
+                                const next = { ...pointsDraft, [point.id]: mode };
+                                setPointsDraft(next);
+                                // 三态分段是离散控件：点一下就落盘。
+                                scheduleSave({ pointsDraft: next }, true);
+                              },
                               style: S.segItem(
                                 current === mode,
                                 mode === "enforce"
@@ -1048,7 +1275,7 @@ window.__ModuleLoader__.load({
                           ),
                         ),
                       ),
-                  changed ? h("span", { style: { ...S.badge, borderStyle: "solid", opacity: 0.9 } }, "待保存") : null,
+                  changed ? h("span", { style: { ...S.badge, borderStyle: "solid", opacity: 0.9 } }, "保存中") : null,
                 );
               }),
               // 自身预算：决策模型自己也烧 token，不设上限会变成主要消耗方。
@@ -1073,8 +1300,12 @@ window.__ModuleLoader__.load({
                   defaultValue: decisions.budget?.limit ?? 0,
                   onChange: (event) => {
                     const value = Number(event.target.value);
-                    setBudgetDraft(Number.isFinite(value) ? Math.max(0, Math.floor(value)) : null);
+                    const next = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : null;
+                    setBudgetDraft(next);
+                    // 数字框是文本输入：停手防抖落盘。
+                    scheduleSave({ budgetDraft: next });
                   },
+                  onBlur: () => scheduleSave(null, true),
                 }),
               ),
               // 缓存命中：0 命中说明白名单外的调用每次都真发请求，是主要浪费。
@@ -1085,38 +1316,55 @@ window.__ModuleLoader__.load({
                   `同类复用 ${decisions.cache?.softHits ?? 0} · 命中率 ${Math.round((decisions.cache?.hitRate ?? 0) * 100)}%`,
               ),
             ),
-        // 4) 保存按钮（同时提交开关、provider 与 key）
+        // 4) 自动保存状态行：**没有「保存」按钮**，改动即落盘。
+        //    这一行回答的是「刚才那一下到底存没存」：进行中 / 已存 /
+        //    失败原因（附重试）。原来那个按钮的「保存中…」搬到这里。
         h(
           "div",
-          { style: { display: "flex", gap: "8px", margin: "14px 0 4px" }, key: "actions" },
+          { style: { display: "flex", gap: "8px", alignItems: "center", margin: "14px 0 4px" }, key: "actions" },
+          // 常驻说明：让第一次进来的人知道不需要找保存按钮。
           h(
-            "button",
-            {
-              type: "button",
-              // 保存按钮的可用条件必须包含 providerChanged 与 custom key：
-              // 少一项就会出现「改了 provider 但按钮是灰的」。
-              disabled:
-                busy !== "" ||
-                (dirty !== true &&
-                  (keyInputs[providerDraft.provider] ?? "").trim().length < 10 &&
-                  decisionsChanged !== true &&
-                  providerChanged !== true),
-              onClick: () => void saveAll(),
-              style: {
-                ...S.saveBtn,
-                opacity:
-                  busy !== "" ||
-                  (dirty !== true &&
-                    (keyInputs[providerDraft.provider] ?? "").trim().length < 10 &&
-                    decisionsChanged !== true &&
-                    providerChanged !== true)
-                    ? 0.5
-                    : 1,
-                cursor: busy !== "" ? "default" : "pointer",
-              },
-            },
-            busy === "save" ? "保存中…" : "保存",
+            "span",
+            { style: { ...S.meta, marginTop: 0, flex: 1, opacity: 0.55 } },
+            saveState === "pending"
+              ? "待保存…"
+              : saveState === "saving"
+                ? "保存中…"
+                : saveState === "saved"
+                  ? "已保存（改动即生效，无需点保存）"
+                  : saveState !== null && typeof saveState === "object" && typeof saveState.error === "string"
+                    ? null
+                    : "改动即保存",
           ),
+          // 失败：原因直接给出来，另配「重试」——不能让用户只看到「保存失败」
+          // 而不知道该改什么、能不能再试一次。
+          saveState !== null && typeof saveState === "object" && typeof saveState.error === "string"
+            ? h(
+                "span",
+                {
+                  style: {
+                    ...S.meta,
+                    marginTop: 0,
+                    flex: 1,
+                    color: "#f87171",
+                    opacity: 1,
+                  },
+                },
+                `未保存：${saveState.error}`,
+              )
+            : null,
+          saveState !== null && typeof saveState === "object" && typeof saveState.error === "string"
+            ? h(
+                "button",
+                {
+                  type: "button",
+                  disabled: busy !== "",
+                  onClick: retrySave,
+                  style: { ...S.saveBtn, flexShrink: 0, padding: "6px 10px" },
+                },
+                "重试",
+              )
+            : null,
           h(
             "button",
             {

package/lib/home-paths.js

@@ -0,0 +1,86 @@
+/**
+ * DSH 家目录解析 —— 与宿主 `@deepseek-ai/dsh-home-paths` 保持同一语义。
+ *
+ * 为什么自己实现而不直接依赖宿主那个包：
+ *
+ *   `@deepseek-ai/dsh-home-paths` 是宿主的 peer 依赖，装上它本插件就无法在
+ *   没有 DSH node_modules 的裸仓库里被加载——而本项目刻意保持零运行时依赖
+ *   （`lib/providers.js` 甚至能在裸 Node 下单测）。因此这里复刻它的**行为**，
+ *   而不是引入它的代码。
+ *
+ * 与宿主 `resolveDshHome()` 必须一致的三条规则：
+ *
+ *   1. **优先级**：显式配置 > `$DSH_HOME` > `~/.dsh`
+ *   2. **空白即未设置**：空串或纯空白的 `$DSH_HOME` 当作没有，
+ *      否则空值会把数据目录解析到当前工作目录（宿主的注释专门强调过这点）
+ *   3. **波浪号展开**：`~`、`~/`、`~\` 都按操作系统家目录展开。
+ *      其中 `~\` 是 Windows 形式，宿主为此专门加了这一条
+ *
+ * 另外补上宿主也做、而早期实现漏掉的一步：**规范化成绝对路径**
+ * （`path.resolve`）。相对路径（`DSH_HOME=./home`）若不规范化，实际落盘位置
+ * 会随进程工作目录漂移，表现为「同一个配置有时读得到有时读不到」。
+ *
+ * 跨平台说明：`~/.dsh` 里的 `.dsh` 只是**目录名**，不是路径分隔符，Windows
+ * 完全允许点开头的目录。真正与平台相关的是分隔符与家目录位置，这两件事都由
+ * `node:path` / `node:os` 处理，所以 Windows 上会得到
+ * `C:\Users\<name>\.dsh\...`。
+ *
+ * @module dsh-decision-engine/home-paths
+ */
+
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** 默认的 Harness 家目录名（宿主同名常量）。 */
+export const DSH_HOME_DIR_NAME = ".dsh";
+
+/** 覆盖默认家目录的环境变量（宿主同名常量）。 */
+export const DSH_HOME_ENV = "DSH_HOME";
+
+/**
+ * 展开 `~`、`~/`、`~\` 前缀。
+ *
+ * 只处理「单独的家目录」与「当前用户」两种形式；`~alice/...` 这类命名用户
+ * 形式原样返回——与宿主 `expandHomePath` 的行为一致，避免自作聪明地改坏
+ * 用户写的路径。
+ *
+ * @param path - 可能带波浪号前缀的路径。
+ * @returns 展开后的路径；没有可识别前缀时原样返回。
+ */
+export function expandHomePath(path) {
+  const text = typeof path === "string" ? path : "";
+  if (text === "~") return homedir();
+  if (text.startsWith("~/") || text.startsWith("~\\")) return join(homedir(), text.slice(2));
+  return text;
+}
+
+/**
+ * 解析 DSH 家目录。
+ *
+ * @param options.configured - 显式配置的路径，优先级最高（当前插件没有此入口，
+ *   保留参数是为了与宿主签名一致，便于将来接入 profile 配置）。
+ * @param options.env - 环境变量表，默认 `process.env`；注入便于单测。
+ * @returns 规范化后的绝对路径。
+ */
+export function resolveDshHome(options = {}) {
+  const env = options.env ?? process.env;
+  const raw = env?.[DSH_HOME_ENV];
+  const fromEnv = typeof raw === "string" && raw.trim().length > 0 ? raw : undefined;
+  const configured = typeof options.configured === "string" && options.configured.trim().length > 0
+    ? options.configured
+    : undefined;
+  const chosen = configured ?? fromEnv ?? join(homedir(), DSH_HOME_DIR_NAME);
+  // resolve() 同时完成「展开相对路径」与「消除 . / .. 」，
+  // 保证不同工作目录下得到同一个绝对路径。
+  return resolve(expandHomePath(chosen));
+}
+
+/**
+ * 把若干路径段拼到解析出的家目录上。
+ *
+ * @param segments - 追加的路径段；为空时返回家目录本身。
+ * @returns 绝对路径。
+ */
+export function dshHomePath(...segments) {
+  return join(resolveDshHome(), ...segments);
+}

package/lib/index.js

@@ -5,7 +5,8 @@
  *
  * 1. **零可选 API 依赖**。不调用 `settings.installSection`（该 API 在 DSH 中不存在），
  *    不依赖 `@deepseek-ai/dsh-credentials`、`launchEnvironmentOf`、`dshHomePath`。
- *    密钥走 config → 环境变量两级，路径走 `os.homedir()`。宿主 API 缺失不会炸成静默失效。
+ *    密钥走 config → 环境变量两级，路径走 `home-paths.js`（与宿主同一套规则）。
+ *    宿主 API 缺失不会炸成静默失效。
  *
  * 2. **endpoint 每次请求重新解析**。`classify()` 现读 `cfg` 并重新解析 provider，
  *    改配置立刻对下一次决策生效，无需重启（旧插件在 apply 期把 endpoint 固化进
@@ -23,8 +24,7 @@
 
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 
 import { DecisionCache } from "./decision-cache.js";
@@ -37,6 +37,7 @@ import { mountRoutePoint } from "./adapters/route.js";
 import { mountAgentPoints } from "./adapters/agent.js";
 import { mountCotTranslatePoint } from "./adapters/translate.js";
 import { applyConfigUpdates, parseConfigText } from "./config-file.js";
+import { resolveDshHome } from "./home-paths.js";
 import { applyRefUpdates, listRefNames, pickRefValue } from "./credentials.js";
 import {
   DEFAULT_PROVIDER,
@@ -501,10 +502,9 @@ export function resolveKey(cfg, provider) {
 export function readCredentialFromDsh(ref) {
   const name = typeof ref === "string" ? ref.trim() : "";
   if (name.length === 0) return undefined;
-  const candidates = [join(homedir(), ".dsh", ".credentials.yaml")];
-  if (typeof process.env.DSH_HOME === "string" && process.env.DSH_HOME.length > 0) {
-    candidates.unshift(join(process.env.DSH_HOME, ".credentials.yaml"));
-  }
+  // 读侧与写侧必须用**同一套**规则，否则会出现"存了却读不回"。
+  // 两边都交给 resolveDshHome()，候选只剩一个路径。
+  const candidates = [join(resolveDshHome(), ".credentials.yaml")];
   for (const path of candidates) {
     let raw;
     try {
@@ -527,14 +527,11 @@ export function readCredentialFromDsh(ref) {
  * @returns 凭据文件绝对路径（不保证已存在）。
  */
 export function credentialFilePath() {
-  // DSH_HOME 覆盖优先，其次 ~/.dsh。
-  //
-  // 注意：读取侧（readCredentialFromDsh）与写入侧必须用**同一套**候选，
-  // 否则会出现"保存成功但读不回来"——写到了 A 文件、读的是 B 文件。
+  // 读取侧（readCredentialFromDsh）与写入侧必须用**同一套**规则，否则会
+  // 出现"保存成功但读不回来"——写到了 A 文件、读的是 B 文件。
   // 早先写入侧只认 ~/.dsh，就是在这一步把 key 写进真实家目录的。
-  const home = typeof process.env.DSH_HOME === "string" ? process.env.DSH_HOME.trim() : "";
-  if (home.length > 0) return join(home, ".credentials.yaml");
-  return join(homedir(), ".dsh", ".credentials.yaml");
+  // 现在两侧都从 resolveDshHome() 派生，规则只有一份。
+  return join(resolveDshHome(), ".credentials.yaml");
 }
 
 /**
@@ -617,11 +614,10 @@ const LEGACY_CONFIG_FILE_NAMES = ["startlux.yml"];
  * 与插件源码分离——源码可以 clone 到任意位置，运行期数据只在 DSH 家目录下。
  */
 function defaultTelemetryDir() {
-  // DSH_HOME 优先：它既是"DSH 家目录"的权威来源，也让测试能完全隔离，
-  // 不必碰用户真实数据（HOME 在某些运行环境里不生效）。
-  const home = typeof process.env.DSH_HOME === "string" ? process.env.DSH_HOME.trim() : "";
-  const base = home.length > 0 ? home : join(homedir(), ".dsh");
-  return join(base, DATA_DIR_NAME);
+  // 家目录解析统一走 home-paths.js：优先级、空白值处理、~ 展开与
+  // 绝对路径规范化都与宿主 @deepseek-ai/dsh-home-paths 一致。
+  // 早期各处手写一份 `DSH_HOME || ~/.dsh`，既重复又漏了规范化。
+  return join(resolveDshHome(), DATA_DIR_NAME);
 }
 
 /**
@@ -639,8 +635,7 @@ function defaultTelemetryDir() {
  * 找不到老配置。顺序即优先级：越新的旧位置越靠前。
  */
 function legacyConfigPaths() {
-  const home = typeof process.env.DSH_HOME === "string" ? process.env.DSH_HOME.trim() : "";
-  const base = home.length > 0 ? home : join(homedir(), ".dsh");
+  const base = resolveDshHome();
   return [
     // 上一代数据目录（本项目改名前的正式位置）
     join(base, "dsh-startlux-decision", "startlux.yml"),
@@ -1273,6 +1268,11 @@ export function apply(ctx, config) {
    */
   const persistConfig = async (updates) => {
     const { writeFile } = await import("node:fs/promises");
+    // 先建目录：全新安装时数据目录还不存在，直接 writeFile 会 ENOENT。
+    // 那会造成最糟的一种失败——凭据已经写进去了、配置却写不进去，
+    // 用户只看到一条报错，而 key 其实「存了一半」。
+    // 目录创建必须幂等（recursive），已有目录时是无操作。
+    await mkdir(dirname(ownConfigPath), { recursive: true });
     let lines = [];
     try {
       lines = (await readFile(ownConfigPath, "utf8")).split("\n");
@@ -1345,17 +1345,31 @@ export function apply(ctx, config) {
     const names = Object.keys(credentialWrites);
     if (names.length === 0) return { ok: true, patch: ymlPatch };
 
+    /** 已成功写入的项，带上写入前的值，供上层在后续步骤失败时回滚。 */
+    const applied = [];
     for (const name of names) {
+      // 先记下旧值：万一配置没写成功，要把凭据恢复原状，
+      // 否则会出现「凭据存了、配置没存」的半成功状态。
+      const previous = readCredentialFromDsh(name);
       const result = await writeCredentialToDsh(name, credentialWrites[name]);
       if (!result.ok) {
+        // 本次之前已经写成功的，一并回滚，避免留下半套改动。
+        for (const done of applied) {
+          try {
+            await writeCredentialToDsh(done.refName, done.previous ?? "");
+          } catch {
+            /* 回滚尽力而为，失败也不能再抛 */
+          }
+        }
         return {
           ok: false,
           patch: ymlPatch,
           error: `写入 ~/.dsh/.credentials.yaml 失败（${name}）：${result.error}`,
         };
       }
+      applied.push({ refName: name, previous });
     }
-    return { ok: true, patch: ymlPatch };
+    return { ok: true, patch: ymlPatch, applied };
   };
 
   /** 一次决策的完整记录，写入 telemetry.jsonl 便于事后核对。 */
@@ -1830,7 +1844,28 @@ export function apply(ctx, config) {
           // key 已被写进指定位置的，不能同时再写进 yml（会变成两处明文）。
           const ymlPatch = { ...keyResult.patch };
 
-          await persistConfig(ymlPatch);
+          try {
+            await persistConfig(ymlPatch);
+          } catch (error) {
+            // 配置没写成功，就把已落地的凭据恢复原状：宁可整体失败，
+            // 也不要留下「凭据存了、配置没存」的半套状态——那种状态在
+            // 界面上看起来是保存失败，实际 key 已经悄悄换了。
+            for (const done of keyResult.applied ?? []) {
+              try {
+                await writeCredentialToDsh(done.refName, done.previous ?? "");
+              } catch {
+                /* 回滚尽力而为 */
+              }
+            }
+            return json(
+              {
+                error:
+                  `写入配置文件失败：${error instanceof Error ? error.message : String(error)}` +
+                  (keyResult.applied?.length > 0 ? "（已回滚本次写入的凭据）" : ""),
+              },
+              500,
+            );
+          }
           return json({ ok: true, ...statusPayload() });
         } catch (error) {
           return json({ error: error instanceof Error ? error.message : String(error) }, 500);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-decision-engine",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "dsh-decision-engine: a cheap judgement layer for DeepSeek Harness — all nine decision points (tool authorization, model routing, delegation, compaction, turn continuation, retrieval, skill pick, session title, COT translation) are implemented and individually switchable, and it works against any system-one style API (system one, bamboonode, or a custom base URL).",
   "icon": "./icon.svg",
   "type": "module",