dsh-oh-my-terminal 0.2.5 → 0.2.6

package/CLAUDE.md

@@ -53,34 +53,43 @@ pnpm exec tsx --test tests/unit/*.test.ts
 
 ```
 src/
-├── index.ts                # 宿主半入口（cordis 插件壳 + settings 集成 + 会话生命周期 + loadPty 懒加载）
+├── index.ts                # 宿主半入口（cordis 插件壳 + settings 集成 + 会话生命周期 + loadPty 懒加载 + prepareProfiles/settleProfiles 配置表落定）
 ├── routes.ts               # HTTP 路由处理器工厂（createRouteHandler + 辅助函数）
 ├── ws-handler.ts           # WebSocket 处理器工厂（createWsHandlers + WebServer 类型导出）
-├── client.tsx              # 浏览器半入口（TerminalPanel 组合壳 + 插件注册 + injectStyles 调用）
+├── client.tsx              # 浏览器半入口（TerminalPanel 组合壳 + 插件注册 + shortcuts 命令注册 + injectStyles 调用）
 ├── client/
 │   ├── types.ts            # 共享类型定义（TerminalInstance, TerminalGroup, TerminalState, TerminalAction, API 响应）
-│   ├── hooks.ts            # 自定义 Hooks（terminalReducer + useTerminalState + useConfig + usePanelHeight + usePanelGeometry + useTerminalTabs）
+│   ├── hooks.ts            # 兼容壳（re-export terminal/ 子模块，保持对外接口不变）
 │   ├── term-pane.tsx       # TermPane 组件（xterm + WebSocket + resize）+ RestartButton 组件
 │   ├── styles.ts           # CSS 样式常量（PANEL_CSS）+ Campbell 暗色主题 + xterm 调优常量 + injectStyles()
 │   ├── dropdown.tsx        # +号旁下拉菜单组件（新建/拆分/按种类新建）
 │   ├── side-list.tsx       # 右侧终端列表面板（树形前缀 + 右键重命名 + useMemo 缓存）
+│   ├── shortcut-bridge.ts  # shortcuts 服务接入信号桥（命令注册状态 + 面板切换回调，软探测兼容旧宿主）
 │   ├── terminal/
-│   │   └── use-tabs.ts     # 终端标签页状态管理（useTerminalTabs Hook：newTab/splitTerminal/closeTerminal/renameTerminal）
+│   │   ├── reducer.ts          # 终端状态 reducer（terminalReducer 纯函数 + createInitialState）
+│   │   ├── use-terminal-state.ts # 终端状态管理 Hook（useTerminalState：useReducer 封装 + 启动恢复）
+│   │   ├── use-panel-geometry.ts # 面板几何与高度管理（usePanelGeometry + usePanelHeight：拖拽调高 + localStorage + 对话列几何测量）
+│   │   └── use-tabs.ts         # 终端标签页状态管理（useTerminalTabs + useConfig：newTab/splitTerminal/closeTerminal/renameTerminal + 配置拉取）
 │   ├── settings/
 │   │   ├── types.ts        # 设置页面类型定义（SettingsPageProps、ConfigWithProfiles）
 │   │   ├── store.ts        # 设置页面状态管理（useSettingsState Hook）
-│   │   └── card.tsx        # 设置卡片组件（SettingsCard）
+│   │   ├── card.tsx        # 设置卡片组件（SettingsCard）
+│   │   ├── profile-table.tsx # 终端配置表格组件（TerminalProfile[] CRUD UI：inline 编辑/新增/删除/origin 约束）
+│   │   ├── api.ts          # Settings Bridge HTTP 客户端（封装与宿主半 Settings Bridge 的 HTTP 交互）
+│   │   └── styles.ts       # 配置表单样式模块（injectSettingsStyles + CSS 自定义属性主题自适应）
 │   ├── icons.tsx           # SVG 图标组件集合（10 个纯函数）
 │   └── clipboard.ts        # 剪贴板纯函数（Async Clipboard API + legacy 双层降级）
 ├── terminal/
-│   ├── index.ts            # 终端模块统一导出（kinds/detect/resolve/store）
+│   ├── index.ts            # 终端模块统一导出（kinds/detect/resolve/store + settleProfileTable）
 │   ├── kinds.ts            # 终端种类定义（TerminalKind 联合类型 + KIND_SPECS 平台映射表）
 │   ├── detect.ts           # 终端探测（resolveCommand/detectGitBash/detectTerminalProfiles）
 │   ├── resolve.ts          # 配置解析（resolveProfile：TerminalProfile → node-pty spawn 参数）
-│   └── store.ts            # 配置表校验（validateAdd/validateUpdate/validateDelete/addProfile/updateProfile/deleteProfile）
+│   └── store.ts            # 配置表校验（validateAdd/validateUpdate/validateDelete/addProfile/updateProfile/deleteProfile + settleProfileTable 落盘决策）
 ├── settings/
-│   ├── namespace.ts        # Settings 命名空间定义（SettingsNamespace）
-│   └── bridge.ts           # Settings 桥接层（prepareProfiles：配置表与探测结果合并）
+│   ├── index.ts            # settings bridge 模块入口（registerSettingsIntegration + registerSettingsNamespace + SettingsChannel 读写通道 + volatile 解包）
+│   ├── namespace.ts        # Settings 命名空间定义（SettingsNamespace + SETTINGS_NS 常量）
+│   ├── bridge.ts           # Settings 桥接路由工厂（createSettingsBridgeRoutes：describe + mutate 路由，SettingsLike 最小接口）
+│   └── patch.ts            # JSON Patch 操作类型与构造函数（op:'set' 路径数组形式，零额外依赖）
 ├── persistence.ts          # 会话持久化层（SessionStore：日志落盘/清理、元数据读写、启动恢复）
 ├── platform.ts             # 平台适配层（PlatformAdapter 接口 + POSIX/Windows 适配器 + 默认 shell 探测）
 ├── constants.ts            # 协议/尺寸/快捷键/环境变量/文件名常量
@@ -96,10 +105,11 @@ src/
   index.ts → routes.ts → terminal/, settings/, constants.ts, platform.ts, persistence.ts, server-command.ts, logger.ts
   index.ts → ws-handler.ts → constants.ts, persistence.ts
   index.ts → terminal/, settings/, constants.ts, platform.ts, persistence.ts, logger.ts
-  settings/bridge.ts → terminal/detect.ts, terminal/kinds.ts, logger.ts
+  settings/index.ts → settings/bridge.ts, settings/namespace.ts, settings/patch.ts
+  settings/bridge.ts → settings/namespace.ts, settings/patch.ts
   terminal/detect.ts → terminal/kinds.ts
   terminal/resolve.ts → terminal/kinds.ts, platform.ts
-  terminal/store.ts → terminal/kinds.ts
+  terminal/store.ts → terminal/kinds.ts, terminal/detect.ts
   platform.ts → terminal/detect.ts（复用 resolveCommand）
   persistence.ts → constants.ts, logger.ts
 
@@ -107,11 +117,17 @@ src/
   client.tsx → client/types.ts, client/icons.tsx, client/clipboard.ts,
                client/dropdown.tsx, client/side-list.tsx, client/hooks.ts,
                client/styles.ts, client/term-pane.tsx, client/settings/,
-               client/terminal/, logger.ts
-  client/hooks.ts → client/types.ts, shortcut.ts, logger.ts
-  client/terminal/use-tabs.ts → client/types.ts, logger.ts
-  client/settings/card.tsx → client/settings/types.ts, client/settings/store.ts, client/icons.tsx
+               client/shortcut-bridge.ts, logger.ts
+  client/hooks.ts → client/terminal/*（re-export 兼容壳：reducer/use-terminal-state/use-panel-geometry/use-tabs）
+  client/shortcut-bridge.ts → client/types.ts, constants.ts, logger.ts
+  client/terminal/reducer.ts → client/types.ts, logger.ts
+  client/terminal/use-terminal-state.ts → client/terminal/reducer.ts, client/types.ts, logger.ts
+  client/terminal/use-panel-geometry.ts → client/types.ts, constants.ts, logger.ts
+  client/terminal/use-tabs.ts → client/types.ts, shortcut.ts, client/shortcut-bridge.ts, constants.ts, logger.ts
+  client/settings/card.tsx → client/settings/types.ts, client/settings/api.ts, client/settings/store.ts, client/settings/profile-table.tsx, client/icons.tsx
   client/settings/store.ts → client/settings/types.ts
+  client/settings/profile-table.tsx → client/settings/types.ts, client/settings/api.ts
+  client/settings/api.ts → client/settings/types.ts
   client/dropdown.tsx → client/types.ts, client/icons.tsx
   client/side-list.tsx → client/types.ts, client/icons.tsx
   client/term-pane.tsx → client/types.ts, client/clipboard.ts, client/icons.tsx, client/styles.ts
@@ -135,7 +151,9 @@ src/
 | `path` | 可执行文件路径。留空则按 `type` 在 `$PATH` 中解析 |
 | `origin` | `auto`（启动探测）/ `user`（手动新增）。`auto` 项不可删除、path 不可改，但可改名 |
 
-**启动流程**：`prepareProfiles()` 在 apply 时跑一次 `$PATH` 探测（`detectTerminalProfiles()`），与已保存的配置表合并（`mergeProfiles()`：已保存项全保留，探测到的新 type/path 补进去）。首次运行（配置表为空）时把结果写回配置。
+**启动流程**（两阶段，读写同通道）：`detectTerminalProfiles()` 在 apply 时跑一次 `$PATH` 探测（`where`/`which` 子进程调用有成本，只跑一次并缓存）；`prepareProfiles()` 读 volatile 配置初值与探测结果合并（`mergeProfiles()`：已保存项全保留，探测到的新 type/path 补进去）产出初值，routes 立即可用；settings 服务就绪后 `settleProfiles()` 经 `SettingsChannel`（`registerSettingsNamespace` 的 `onReady` 回调交出，read/update 同一命名空间）读回持久层已保存表，重算合并结果并 `cachedProfiles.splice(...)` 就地刷新（保持数组身份，routes/bridge 闭包引用同步生效）。首跑（持久层读回为空）时把探测结果落盘，读回非空时绝不写回（用户改过的 name/手动新增项原样保留）。
+
+**读写同通道**：必须读写走同一 settings 通道（owner scope → 服务级 get → describe 扫描，逐能力探测）。旧实现读 cordis loader 的 volatile 引用、写 settings user 层，两通道互不可见导致读回恒空、每次启动判首跑并覆盖用户配置。volatile 字段的稳定引用（cosmokit `Symbol.for('cosmokit.volatile.write')`）需在通道内解包为标量，否则 JSON 序列化后只剩 `{}`、字符串字段永远"读不到"。
 
 **路径解析**：`resolveProfile()` 把 `TerminalProfile` 转成 node-pty 的 `{ file, args }`。**Windows 上 node-pty 不做 PATH/PATHEXT 查找**，裸命令名（`pwsh`、`cmd`）会直接以 `File not found: ` 失败，必须给完整路径——`resolveCommand()` 用 `where`/`which` 解析，并过滤 `WindowsApps` 下的 App Execution Alias 占位符（0 字节重解析点，spawn 必失败）。
 

package/README.md

@@ -1,6 +1,6 @@
 # dsh-oh-my-terminal
 
-[![version](https://img.shields.io/badge/version-0.2.4-blue)](package.json)
+[![version](https://img.shields.io/badge/version-0.2.6-blue)](package.json)
 [![license](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
 [![node](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.0.0-brightgreen)](package.json)
 

package/README.zh.md

@@ -1,6 +1,6 @@
 # dsh-oh-my-terminal
 
-[![version](https://img.shields.io/badge/version-0.2.4-blue)](package.json)
+[![version](https://img.shields.io/badge/version-0.2.6-blue)](package.json)
 [![license](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
 [![node](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.0.0-brightgreen)](package.json)
 

package/lib/index.js

@@ -636,6 +636,11 @@ function mergeProfiles(saved, detected) {
   }
   return result;
 }
+function settleProfileTable(saved, detected) {
+  const merged = mergeProfiles(saved, detected);
+  const persistPayload = saved.length === 0 && merged.length > 0 ? JSON.stringify(merged) : null;
+  return { merged, persistPayload };
+}
 
 // src/routes.ts
 import { readFileSync as readFileSync2 } from "node:fs";
@@ -1014,7 +1019,31 @@ function createSettingsBridgeRoutes(settings, namespace, runtimeProfiles) {
 }
 
 // src/settings/index.ts
-function registerSettingsNamespace(ctx, schema) {
+var VOLATILE_WRITE = /* @__PURE__ */ Symbol.for("cosmokit.volatile.write");
+function isVolatileRef(value) {
+  return typeof value === "object" && value !== null && VOLATILE_WRITE in value && typeof value.get === "function";
+}
+function readNamespaceValue(facade, owner) {
+  const candidates = [];
+  if (typeof owner?.get === "function") {
+    candidates.push(owner.get());
+  } else {
+    if (typeof facade.get === "function") candidates.push(facade.get(SETTINGS_NS));
+    if (typeof facade.describe === "function") {
+      const descriptor = facade.describe().find((d) => d.ns === SETTINGS_NS);
+      if (descriptor !== void 0) candidates.push(descriptor.value);
+    }
+  }
+  for (const value of candidates) {
+    if (value !== null && typeof value === "object") {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [key, isVolatileRef(item) ? item.get() : item])
+      );
+    }
+  }
+  return void 0;
+}
+function registerSettingsNamespace(ctx, schema, onReady) {
   ctx.inject(["settings"], (sctx) => {
     const facade = sctx.settings;
     if (typeof facade.configure === "function") {
@@ -1024,14 +1053,25 @@ function registerSettingsNamespace(ctx, schema) {
         return typeof cleanup === "function" ? cleanup : () => void 0;
       });
     }
+    let owner;
     if (typeof facade.register === "function") {
       try {
-        facade.register(SETTINGS_NS, schema);
+        owner = facade.register(SETTINGS_NS, schema);
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         if (!message.includes("already registered")) throw error;
       }
     }
+    if (onReady !== void 0) {
+      onReady({
+        read: () => readNamespaceValue(facade, owner),
+        update: (patch) => {
+          if (typeof owner?.update === "function") return owner.update(patch);
+          if (typeof facade.update === "function") return facade.update(SETTINGS_NS, patch);
+          return Promise.reject(new Error("settings \u670D\u52A1\u4E0D\u63D0\u4F9B update\uFF0C\u914D\u7F6E\u65E0\u6CD5\u843D\u76D8"));
+        }
+      });
+    }
   });
 }
 function registerSettingsIntegration(ctx, schema, runtimeProfiles) {
@@ -1122,8 +1162,8 @@ function apply(ctx, config) {
      * 终端配置表（已合并探测结果的完整列表）。
      *
      * 启动时由 prepareProfiles() 求值一次并缓存——探测涉及多次 where/which
-     * 子进程调用，不适合每次 /config 请求都重跑。配置热更新时由
-     * rebuildProfiles() 重建。
+     * 子进程调用，不适合每次 /config 请求都重跑。settings 就绪后由
+     * settleProfiles() 按持久层读回值重算并就地刷新。
      */
     get profiles() {
       return cachedProfiles;
@@ -1150,25 +1190,32 @@ function apply(ctx, config) {
   }
   function prepareProfiles() {
     const saved = parseProfiles(config.terminalProfiles.get());
-    const detected = detectTerminalProfiles();
-    const merged = mergeProfiles(saved, detected);
-    if (saved.length === 0 && merged.length > 0) {
-      const payload = JSON.stringify(merged);
-      ctx.inject(["settings"], (sctx) => {
-        const settings = sctx.settings;
-        if (typeof settings.update !== "function") return;
-        void settings.update(SETTINGS_NS, { terminalProfiles: payload }).then(() => {
+    return mergeProfiles(saved, detectedProfiles);
+  }
+  function settleProfiles(channel) {
+    const persisted = channel.read()?.terminalProfiles;
+    const raw = typeof persisted === "string" ? persisted : config.terminalProfiles.get();
+    const saved = parseProfiles(raw);
+    const { merged, persistPayload } = settleProfileTable(saved, detectedProfiles);
+    if (persistPayload !== null) {
+      const persist = async () => {
+        try {
+          await channel.update({ terminalProfiles: persistPayload });
           log3.info(`\u7EC8\u7AEF\u914D\u7F6E\u8868\u5DF2\u521D\u59CB\u5316\uFF1A\u63A2\u6D4B\u5230 ${merged.length} \u4E2A\u7EC8\u7AEF`);
-        }).catch((error) => {
+        } catch (error) {
           const msg = error instanceof Error ? error.message : String(error);
           log3.warn(`\u7EC8\u7AEF\u914D\u7F6E\u8868\u5199\u5165\u5931\u8D25\uFF0C\u4EC5\u672C\u6B21\u8FD0\u884C\u6709\u6548\uFF1A${msg}`);
-        });
-      });
+        }
+      };
+      void persist();
+    } else if (saved.length > 0) {
+      log3.info(`\u7EC8\u7AEF\u914D\u7F6E\u8868\u5DF2\u8BFB\u56DE\uFF1A\u6301\u4E45\u5C42 ${saved.length} \u9879\uFF0C\u5408\u5E76\u63A2\u6D4B\u540E ${merged.length} \u9879`);
     }
-    return merged;
+    cachedProfiles.splice(0, cachedProfiles.length, ...merged);
   }
-  registerSettingsNamespace(ctx, Config);
+  const detectedProfiles = detectTerminalProfiles();
   const cachedProfiles = prepareProfiles();
+  registerSettingsNamespace(ctx, Config, settleProfiles);
   const sessions = /* @__PURE__ */ new Map();
   const upgradeDisposers = /* @__PURE__ */ new Map();
   const DATA_DIR = process.env[ENV_DATA_DIR] ?? pathJoin3(process.env.DSH_HOME ?? pathJoin3(homedir2(), ".dsh"), "plugin-data", "terminal");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-oh-my-terminal",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "DSH Web GUI 底部终端面板插件——node-pty 驱动的多标签交互式终端（Windows ConPTY / POSIX openpty）",
   "type": "module",
   "license": "Apache-2.0",

package/src/index.ts

@@ -61,9 +61,10 @@ import { createWsHandlers } from './ws-handler.js';
 import { createRouteHandler } from './routes.js';
 import type { CreateSessionOptions } from './routes.js';
 import { makeId, getSessionCounter, resolveSpawn, resolveSessionCwd } from './routes.js';
-import { registerSettingsIntegration, registerSettingsNamespace, SETTINGS_NS } from './settings/index.js';
+import { registerSettingsIntegration, registerSettingsNamespace } from './settings/index.js';
+import type { SettingsChannel } from './settings/index.js';
 import type { TerminalProfile } from './terminal/index.js';
-import { detectTerminalProfiles, mergeProfiles } from './terminal/index.js';
+import { detectTerminalProfiles, mergeProfiles, settleProfileTable } from './terminal/index.js';
 
 const log = createLogger('terminal-host');
 
@@ -252,8 +253,8 @@ export function apply(ctx: Context, config: Config): void {
      * 终端配置表（已合并探测结果的完整列表）。
      *
      * 启动时由 prepareProfiles() 求值一次并缓存——探测涉及多次 where/which
-     * 子进程调用，不适合每次 /config 请求都重跑。配置热更新时由
-     * rebuildProfiles() 重建。
+     * 子进程调用，不适合每次 /config 请求都重跑。settings 就绪后由
+     * settleProfiles() 按持久层读回值重算并就地刷新。
      */
     get profiles(): readonly TerminalProfile[] {
       return cachedProfiles;
@@ -297,46 +298,65 @@ export function apply(ctx: Context, config: Config): void {
   }
 
   /**
-   * 启动时求值一次配置表并缓存。
+   * 启动时求值一次配置表并缓存（快路径）。
    *
-   * 若配置项为空（首次安装），把探测结果写回配置——这样用户对自动探测项改的
-   * 名字能跨重启保留，且下次启动不必再全量探测。
-   *
-   * 写入走 settings 服务的 update(ns, patch)：Volatile 引用是只读视图，没有
-   * setter。settings 服务在 apply 时未必就绪，所以用 ctx.inject 子级延迟注册；
-   * 写失败（只读 profile / 无 settings 服务）只记警告，不阻断插件启动。
+   * volatile 配置通道这里读不到已保存表也没关系——结果只是初值，settings
+   * 就绪后 settleProfiles() 会按持久层读回值重算并就地刷新。
    */
   function prepareProfiles(): TerminalProfile[] {
     const saved = parseProfiles(config.terminalProfiles.get());
-    const detected = detectTerminalProfiles();
-    const merged = mergeProfiles(saved, detected);
-
-    // 首次运行：把探测结果落盘，后续启动只补增量
-    if (saved.length === 0 && merged.length > 0) {
-      const payload = JSON.stringify(merged);
-      ctx.inject(['settings'], (sctx) => {
-        const settings = sctx.settings as { update?: (ns: string, patch: object) => Promise<void> };
-        if (typeof settings.update !== 'function') return;
-        // 命名空间必须与 settings 集成注册的 SETTINGS_NS 逐字一致——
-        // 此前误用包名派生串（PKG_NAME 去前缀 = 'oh-my-terminal'），与注册的
-        // 'terminal-panel' 对不上，首次落盘恒报「namespace not registered」
-        void settings.update(SETTINGS_NS, { terminalProfiles: payload })
-          .then(() => { log.info(`终端配置表已初始化：探测到 ${merged.length} 个终端`); })
-          .catch((error: unknown) => {
-            const msg = error instanceof Error ? error.message : String(error);
-            log.warn(`终端配置表写入失败，仅本次运行有效：${msg}`);
-          });
-      });
+    return mergeProfiles(saved, detectedProfiles);
+  }
+
+  /**
+   * settings 就绪后按持久层落定配置表：读回已保存表 → 合并探测结果 → 仅首跑
+   * 落盘 → 就地刷新缓存。
+   *
+   * 读写必须走同一通道（settings user 层）：旧实现在 apply 期读 volatile 配置、
+   * 却把首跑结果写进 settings user 层，两个通道互不可见，saved 恒为空——每次
+   * 启动都判首跑，重新生成配置 id 并覆盖用户改过的 name。就地刷新（splice 保持
+   * 数组身份）让 routes、settings bridge 与 runtimeSettings.profiles 持有的引用
+   * 同步生效。
+   *
+   * @param channel - settings 命名空间读写通道（settings/index.ts 逐能力探测）
+   */
+  function settleProfiles(channel: SettingsChannel): void {
+    const persisted = channel.read()?.terminalProfiles;
+    // 通道值非字符串（宿主异常形态，如未解包的 volatile 引用）时回落 volatile
+    // 配置读；空串是合法的"用户清空配置表"，不再回落
+    const raw = typeof persisted === 'string' ? persisted : config.terminalProfiles.get();
+    const saved = parseProfiles(raw);
+    const { merged, persistPayload } = settleProfileTable(saved, detectedProfiles);
+
+    // 首跑落盘：异步写回，失败只降级警告（只读 profile /老宿主不阻断启动）
+    if (persistPayload !== null) {
+      const persist = async (): Promise<void> => {
+        try {
+          // 命名空间必须与 settings 集成注册的 SETTINGS_NS 逐字一致——
+          // 此前误用包名派生串（PKG_NAME 去前缀 = 'oh-my-terminal'），与注册的
+          // 'terminal-panel' 对不上，首次落盘恒报「namespace not registered」
+          await channel.update({ terminalProfiles: persistPayload });
+          log.info(`终端配置表已初始化：探测到 ${merged.length} 个终端`);
+        } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error);
+          log.warn(`终端配置表写入失败，仅本次运行有效：${msg}`);
+        }
+      };
+      void persist();
+    } else if (saved.length > 0) {
+      log.info(`终端配置表已读回：持久层 ${saved.length} 项，合并探测后 ${merged.length} 项`);
     }
-    return merged;
+
+    cachedProfiles.splice(0, cachedProfiles.length, ...merged);
   }
 
-  /** 启动时求值的终端配置表（探测 + 合并结果） */
-  // 命名空间注册必须先于 prepareProfiles 的首跑写回（时序竞态：写回早于注册会
-  // 报「namespace is not registered」）——故在此提前注册，settings/index.ts
-  // 内部保留幂等兜底
-  registerSettingsNamespace(ctx, Config);
+  /** 启动时探测结果（只探测一次：where/which 子进程调用有成本） */
+  const detectedProfiles = detectTerminalProfiles();
+  /** 启动时求值的终端配置表（初值；settings 就绪后由 settleProfiles 就地刷新） */
   const cachedProfiles: TerminalProfile[] = prepareProfiles();
+  // 命名空间注册与首跑落盘/读回落定同回调内先注册后读写，天然有序——
+  // 写回早于注册会报「namespace is not registered」（时序竞态）
+  registerSettingsNamespace(ctx, Config, settleProfiles);
 
   /** id -> 会话记录 */
   const sessions = new Map<string, SessionRecord>();

package/src/settings/index.ts

@@ -23,6 +23,104 @@ export { createSettingsBridgeRoutes } from './bridge.js';
 
 // —— 插件集成辅助函数 ——
 
+/**
+ * settings 命名空间读写通道（{@link registerSettingsNamespace} 就绪回调的入参）。
+ *
+ * 读走命名空间的解析值（schema 默认 → base → user 层合并），与 update 写入的
+ * user 层同源可见——首跑落盘写进去的值下次启动能从这里读回来。volatile 字段
+ * 的稳定引用已在通道内解包为标量，调用方按普通配置值使用。不同宿主的
+ * settings 服务暴露面不同，read/update 内部逐能力探测：read 探测不到返回
+ * undefined（调用方按"读不到"降级），update 探测不到时返回 rejected promise
+ * （调用方按写失败降级）。
+ */
+export interface SettingsChannel {
+  /** 读取本命名空间的解析值（volatile 字段已解包）；宿主能力不足时返回 undefined */
+  read(): Record<string, unknown> | undefined;
+  /** 合并写入本命名空间的 user 层 */
+  update(patch: Record<string, unknown>): Promise<void>;
+}
+
+/** settings 服务注册命名空间返回的 owner 能力面（按需探测，不同宿主缺项） */
+interface SettingsOwnerScope {
+  /** 读取本命名空间解析值 */
+  get?: () => unknown;
+  /** 合并写入本命名空间 user 层 */
+  update?: (patch: Record<string, unknown>) => Promise<void>;
+}
+
+/** settings 服务能力面（不同宿主版本暴露面不同，逐能力探测） */
+interface SettingsFacade {
+  /** 新宿主可选能力：关闭自动写回；旧宿主（0.1.5 系）无此方法 */
+  configure?: (options: { auto: boolean }, fiber?: unknown) => void;
+  /**
+   * 注册命名空间 schema；重复注册抛 "already registered"。
+   * 可选——宿主 SettingsForms 靠 cordis loader entries 发现命名空间，
+   * 不一定提供此方法（如 0.1.7-rc.1 的 SettingsForms 无 register）。
+   */
+  register?: (ns: string, schema: unknown) => unknown;
+  /** 服务级读取命名空间解析值（register 缺失时的读回通道） */
+  get?: (ns: string) => unknown;
+  /** 服务级命名空间快照列表（register 与 get 都缺失时的兜底读回通道） */
+  describe?: () => Array<{ ns: string; value: unknown }>;
+  /** 服务级合并写入（owner scope 缺失时的落盘通道） */
+  update?: (ns: string, patch: Record<string, unknown>) => Promise<void>;
+}
+
+/** cosmokit volatile 引用的跨包识别符（与 cosmokit isVolatile 同一 Symbol.for 键，跨 ESM/CJS 副本一致） */
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write');
+
+/**
+ * 判断值是否为 schemastery volatile 字段的解析产物（cosmokit 稳定引用）。
+ *
+ * `.volatile()` 字段的解析结果是 `createVolatile(...)` 引用对象而非标量本身
+ * （JSON 序列化后只剩 `{}`）；把引用当标量读会让字符串字段永远"读不到"。
+ *
+ * @param value - 待判断的值
+ * @returns 值是稳定引用（可 `.get()` 取当前值）时 true
+ */
+function isVolatileRef(value: unknown): value is { get(): unknown } {
+  return typeof value === 'object' && value !== null
+    && VOLATILE_WRITE in value
+    && typeof (value as { get?: unknown }).get === 'function';
+}
+
+/**
+ * 逐能力探测读取命名空间解析值。
+ *
+ * 优先 owner scope（注册即所得），其次服务级 get，最后 describe 扫描——
+ * 三条通道读到的都是同一份解析值，差别只在宿主暴露面。返回前把 volatile
+ * 字段的稳定引用解包成标量，调用方拿到的就是普通配置值。全部探测不到时
+ * 返回 undefined，调用方按"读不到"降级，不伪造空配置。
+ *
+ * @param facade - settings 服务实例
+ * @param owner - register 返回的 owner scope（未注册成功时为 undefined）
+ * @returns 命名空间解析值对象（volatile 字段已解包）；读不到时 undefined
+ */
+function readNamespaceValue(
+  facade: SettingsFacade,
+  owner: SettingsOwnerScope | undefined,
+): Record<string, unknown> | undefined {
+  const candidates: unknown[] = [];
+  if (typeof owner?.get === 'function') {
+    candidates.push(owner.get());
+  } else {
+    if (typeof facade.get === 'function') candidates.push(facade.get(SETTINGS_NS));
+    if (typeof facade.describe === 'function') {
+      const descriptor = facade.describe().find((d) => d.ns === SETTINGS_NS);
+      if (descriptor !== undefined) candidates.push(descriptor.value);
+    }
+  }
+  for (const value of candidates) {
+    if (value !== null && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>)
+          .map(([key, item]) => [key, isVolatileRef(item) ? item.get() : item]),
+      );
+    }
+  }
+  return undefined;
+}
+
 /**
  * 注册 settings 集成（在插件主入口调用）
  *
@@ -54,21 +152,17 @@ export { createSettingsBridgeRoutes } from './bridge.js';
  *
  * @param ctx - cordis 上下文
  * @param schema - 插件 Config 的 schemastery schema
+ * @param onReady - settings 就绪回调，在命名空间注册（或确认宿主无 register）
+ *   之后同步触发，入参是同命名空间的读写通道——首跑落盘/读回落定用它保证
+ *   读写同一通道，避免 apply 期读 volatile、写 settings 的通道错位
  */
-export function registerSettingsNamespace(ctx: Context, schema: unknown): void {
+export function registerSettingsNamespace(
+  ctx: Context,
+  schema: unknown,
+  onReady?: (channel: SettingsChannel) => void,
+): void {
   // 注册命名空间 +（可选）关闭自动模式——软探测，服务不存在时不激活
   ctx.inject(['settings'], (sctx) => {
-    /** settings 服务能力面（不同宿主版本暴露面不同，逐能力探测） */
-    interface SettingsFacade {
-      /** 新宿主可选能力：关闭自动写回；旧宿主（0.1.5 系）无此方法 */
-      configure?: (options: { auto: boolean }, fiber?: unknown) => void;
-      /**
-       * 注册命名空间 schema；重复注册抛 "already registered"。
-       * 可选——宿主 SettingsForms 靠 cordis loader entries 发现命名空间，
-       * 不一定提供此方法（如 0.1.7-rc.1 的 SettingsForms 无 register）。
-       */
-      register?: (ns: string, schema: unknown) => unknown;
-    }
     const facade = sctx.settings as unknown as SettingsFacade;
 
     // configure 仅在宿主提供时调用——0.1.5 系宿主的 settings 服务没有该方法，
@@ -92,14 +186,27 @@ export function registerSettingsNamespace(ctx: Context, schema: unknown): void {
     // （0.1.7-rc.1 的 SettingsForms 无此方法）。方法不存在时跳过，不抛 TypeError；
     // 方法存在时重复注册（热重载、重复 apply）抛 "already registered"，作为幂等
     // 情形吞掉；其余注册失败（如存储段损坏）如实上抛，不把失败包装成成功。
+    let owner: SettingsOwnerScope | undefined;
     if (typeof facade.register === 'function') {
       try {
-        facade.register(SETTINGS_NS, schema);
+        owner = facade.register(SETTINGS_NS, schema) as SettingsOwnerScope | undefined;
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         if (!message.includes('already registered')) throw error;
       }
     }
+
+    // 就绪回调在注册之后触发：回调内的任何读写都能看到已注册的命名空间
+    if (onReady !== undefined) {
+      onReady({
+        read: () => readNamespaceValue(facade, owner),
+        update: (patch) => {
+          if (typeof owner?.update === 'function') return owner.update(patch);
+          if (typeof facade.update === 'function') return facade.update(SETTINGS_NS, patch);
+          return Promise.reject(new Error('settings 服务不提供 update，配置无法落盘'));
+        },
+      });
+    }
   });
 }
 

package/src/terminal/index.ts

@@ -41,4 +41,5 @@ export {
   validateUpdatePath,
   updatePath,
   mergeProfiles,
+  settleProfileTable,
 } from './store.js';

package/src/terminal/store.ts

@@ -266,3 +266,23 @@ export function mergeProfiles(
 
   return result;
 }
+
+/**
+ * 配置表持久层落定：合并探测结果，并决定是否需要首跑落盘。
+ *
+ * 落盘只在持久层读回为空且探测有结果时发生（首跑安装）。读回非空说明持久层
+ * 已有配置表，用户改过的 name、手动新增的项都存在里面，任何写回都会覆盖它们，
+ * 因此一律不写——这也是"值跨重启保留"的唯一保障。
+ *
+ * @param saved - 持久层读回的配置表（读不到按空表传入）
+ * @param detected - 启动时探测到的配置表
+ * @returns merged 合并后的配置表；persistPayload 首跑落盘的 JSON 串，无需落盘时为 null
+ */
+export function settleProfileTable(
+  saved: TerminalProfile[],
+  detected: TerminalProfile[],
+): { merged: TerminalProfile[]; persistPayload: string | null } {
+  const merged = mergeProfiles(saved, detected);
+  const persistPayload = saved.length === 0 && merged.length > 0 ? JSON.stringify(merged) : null;
+  return { merged, persistPayload };
+}

package/tests/unit/profile-settle.test.ts

@@ -0,0 +1,74 @@
+/**
+ * @file 配置表持久层落定单元测试
+ * @description 回归锁定 settleProfileTable 的合并与落盘决策语义：
+ *              读回非空时绝不写回（用户改过的 name/手动新增项必须原样保留，
+ *              任何写回都会覆盖它们）；仅首跑（读回为空且探测有结果）产出落盘
+ *              载荷；合并语义与 mergeProfiles 一致（已保存项全保留，探测到的
+ *              新 type/path 补进去，type+path 双匹配视为同一项）。
+ *
+ *              曾因读写通道错位（apply 期读 volatile 配置、写 settings user 层）
+ *              导致 saved 恒为空，每次启动都判首跑并覆盖用户配置——本组用例
+ *              锁住"读回非空不落盘"这条保命语义。
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type { TerminalProfile } from '../../src/terminal/detect.js';
+import { settleProfileTable } from '../../src/terminal/store.js';
+
+/** 构造一个自动探测项（origin 固定 auto，id 按入参钉死便于断言） */
+function detectedProfile(id: string, type: TerminalProfile['type'], path: string): TerminalProfile {
+  return { id, type, name: type, path, origin: 'auto' };
+}
+
+describe('settleProfileTable', () => {
+  it('首跑（读回为空）产出落盘载荷，内容与合并结果一致', () => {
+    const detected = [detectedProfile('t-pwsh-1111', 'pwsh', 'C:\\pwsh.exe')];
+    const { merged, persistPayload } = settleProfileTable([], detected);
+    assert.equal(merged.length, 1);
+    assert.notEqual(persistPayload, null);
+    assert.deepEqual(JSON.parse(persistPayload ?? '[]'), merged);
+  });
+
+  it('读回非空时不落盘，用户改过的 name 原样保留', () => {
+    const saved: TerminalProfile[] = [
+      { id: 't-pwsh-8bd5', type: 'pwsh', name: '我的主力终端', path: 'C:\\pwsh.exe', origin: 'auto' },
+    ];
+    const detected = [detectedProfile('t-pwsh-2222', 'pwsh', 'C:\\pwsh.exe')];
+    const { merged, persistPayload } = settleProfileTable(saved, detected);
+    assert.equal(persistPayload, null);
+    assert.equal(merged.length, 1);
+    assert.equal(merged[0]?.id, 't-pwsh-8bd5');
+    assert.equal(merged[0]?.name, '我的主力终端');
+  });
+
+  it('读回非空时探测到的新终端补进末尾，不覆盖既有项', () => {
+    const saved: TerminalProfile[] = [
+      { id: 't-pwsh-8bd5', type: 'pwsh', name: '我的主力终端', path: 'C:\\pwsh.exe', origin: 'auto' },
+    ];
+    const detected = [
+      detectedProfile('t-pwsh-2222', 'pwsh', 'C:\\pwsh.exe'),
+      detectedProfile('t-cmd-3333', 'cmd', 'C:\\Windows\\System32\\cmd.exe'),
+    ];
+    const { merged, persistPayload } = settleProfileTable(saved, detected);
+    assert.equal(persistPayload, null);
+    assert.equal(merged.length, 2);
+    assert.equal(merged[0]?.name, '我的主力终端');
+    assert.equal(merged[1]?.type, 'cmd');
+  });
+
+  it('type 相同但 path 不同视为不同项（用户可能装了两个同类型终端）', () => {
+    const saved: TerminalProfile[] = [
+      { id: 't-bash-aaaa', type: 'bash', name: '旧 bash', path: 'C:\\old\\bash.exe', origin: 'user' },
+    ];
+    const detected = [detectedProfile('t-bash-bbbb', 'bash', 'C:\\new\\bash.exe')];
+    const { merged } = settleProfileTable(saved, detected);
+    assert.equal(merged.length, 2);
+  });
+
+  it('读回与探测都为空时不落盘（没有内容可写）', () => {
+    const { merged, persistPayload } = settleProfileTable([], []);
+    assert.equal(merged.length, 0);
+    assert.equal(persistPayload, null);
+  });
+});

package/tests/unit/settings-integration.test.ts

@@ -14,7 +14,8 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import type { Context } from '@deepseek-ai/cordis';
-import { registerSettingsIntegration, SETTINGS_NS } from '../../src/settings/index.js';
+import { registerSettingsIntegration, registerSettingsNamespace, SETTINGS_NS } from '../../src/settings/index.js';
+import type { SettingsChannel } from '../../src/settings/index.js';
 
 /** register 调用记录 */
 interface RegisterCall {
@@ -130,3 +131,128 @@ describe('settings 集成注册', () => {
     assert.equal(registerCalls.length, 0);
   });
 });
+
+describe('settings 命名空间读写通道', () => {
+  /** 捕获 onReady 交出的通道（inject 在假上下文里同步回调，调用后即可断言） */
+  function captureChannel(settings: unknown): SettingsChannel | undefined {
+    let channel: SettingsChannel | undefined;
+    registerSettingsNamespace(makeFakeContext(settings), { marker: 'x' }, (c) => {
+      channel = c;
+    });
+    return channel;
+  }
+
+  it('注册成功后通道走 owner scope 读写', async () => {
+    const updates: Array<Record<string, unknown>> = [];
+    const settings = {
+      register: (): unknown => ({
+        get: (): unknown => ({ terminalProfiles: '[{"id":"t-a"}]' }),
+        update: async (patch: Record<string, unknown>): Promise<void> => {
+          updates.push(patch);
+        },
+      }),
+    };
+    const channel = captureChannel(settings);
+    assert.notEqual(channel, undefined);
+    assert.deepEqual(channel?.read(), { terminalProfiles: '[{"id":"t-a"}]' });
+    await channel?.update({ terminalProfiles: '[]' });
+    assert.deepEqual(updates, [{ terminalProfiles: '[]' }]);
+  });
+
+  it('register 缺失时回落服务级 get 与 update', async () => {
+    const updates: Array<{ ns: string; patch: Record<string, unknown> }> = [];
+    const settings = {
+      get: (ns: string): unknown =>
+        ns === SETTINGS_NS ? { terminalProfiles: '[{"id":"t-b"}]' } : undefined,
+      update: async (ns: string, patch: Record<string, unknown>): Promise<void> => {
+        updates.push({ ns, patch });
+      },
+    };
+    const channel = captureChannel(settings);
+    assert.deepEqual(channel?.read(), { terminalProfiles: '[{"id":"t-b"}]' });
+    await channel?.update({ terminalProfiles: '[]' });
+    assert.deepEqual(updates, [{ ns: SETTINGS_NS, patch: { terminalProfiles: '[]' } }]);
+  });
+
+  it('get 缺失时回落 describe 扫描', () => {
+    const settings = {
+      describe: (): unknown => [{ ns: SETTINGS_NS, value: { terminalProfiles: '[{"id":"t-c"}]' } }],
+    };
+    const channel = captureChannel(settings);
+    assert.deepEqual(channel?.read(), { terminalProfiles: '[{"id":"t-c"}]' });
+  });
+
+  it('already registered 时通道仍就绪并走服务级读', () => {
+    const settings = {
+      register: (): unknown => {
+        throw new Error('settings namespace "terminal-panel" is already registered');
+      },
+      get: (): unknown => ({ terminalProfiles: '[{"id":"t-d"}]' }),
+    };
+    const channel = captureChannel(settings);
+    assert.deepEqual(channel?.read(), { terminalProfiles: '[{"id":"t-d"}]' });
+  });
+
+  it('三条读通道都拿不到对象时 read 返回 undefined，不伪造空配置', () => {
+    const settings = {
+      register: (): unknown => ({ get: (): unknown => undefined }),
+    };
+    const channel = captureChannel(settings);
+    assert.equal(channel?.read(), undefined);
+  });
+
+  it('update 三条通道都缺失时返回 rejected promise（调用方按写失败降级）', async () => {
+    const channel = captureChannel({ register: (): unknown => ({}) });
+    await assert.rejects(
+      async () => channel?.update({ terminalProfiles: '[]' }),
+      /无法落盘/u,
+    );
+  });
+
+  /** 构造 schemastery volatile 字段的解析产物形态（cosmokit 稳定引用） */
+  function volatileRef(value: unknown): unknown {
+    return Object.freeze({
+      get: (): unknown => value,
+      [Symbol.for('cosmokit.volatile.write')]: (): void => undefined,
+    });
+  }
+
+  it('volatile 字段的稳定引用在通道内解包为标量（回归：解包缺失致读回恒空、每轮判首跑）', () => {
+    const settings = {
+      register: (): unknown => ({
+        get: (): unknown => ({
+          terminalProfiles: volatileRef('[{"id":"t-a"}]'),
+          fontFamily: volatileRef(''),
+          fontSize: volatileRef(12.5),
+        }),
+      }),
+    };
+    const channel = captureChannel(settings);
+    assert.deepEqual(channel?.read(), {
+      terminalProfiles: '[{"id":"t-a"}]',
+      fontFamily: '',
+      fontSize: 12.5,
+    });
+  });
+
+  it('describe 兜底路径同样解包 volatile 引用', () => {
+    const settings = {
+      describe: (): unknown => [{
+        ns: SETTINGS_NS,
+        value: { terminalProfiles: volatileRef('[{"id":"t-b"}]') },
+      }],
+    };
+    const channel = captureChannel(settings);
+    assert.deepEqual(channel?.read(), { terminalProfiles: '[{"id":"t-b"}]' });
+  });
+
+  it('普通值原样透传，不被误判为引用', () => {
+    const settings = {
+      register: (): unknown => ({
+        get: (): unknown => ({ terminalProfiles: '[{"id":"t-c"}]' }),
+      }),
+    };
+    const channel = captureChannel(settings);
+    assert.deepEqual(channel?.read(), { terminalProfiles: '[{"id":"t-c"}]' });
+  });
+});