@morlay/dsh-session-mode 0.0.1-alpha.4 → 0.0.1-alpha.5

package/src/index.ts

@@ -32,6 +32,9 @@ import type { Session, SessionEvent, SessionId } from "@deepseek-ai/dsh-session"
 import type {} from "@deepseek-ai/dsh-session";
 import type { ProjectionDefinition } from "@deepseek-ai/dsh-session-projection";
 import type {} from "@deepseek-ai/dsh-session-projection";
+// Type-only：官方 roster 的会话投影（`agentPreset`）与它的选择事件——选择面归官方 preset，
+// 我们读它的选择、落成自己的会话事实。
+import type {} from "@deepseek-ai/dsh-agent-preset-registry";
 import type { SessionToolScope } from "@morlay/dsh-context-assembler/scope";
 import { z } from "zod";
 import {
@@ -65,7 +68,6 @@ export type {
   ResolvedConfig,
   SessionMode,
   SessionModeModel,
-  SessionModeModels,
   SessionModePersona,
   SessionModeRole,
 } from "./modes.ts";
@@ -91,10 +93,13 @@ declare module "@deepseek-ai/dsh-session/types" {
 declare module "@deepseek-ai/dsh-session-projection/types" {
   interface SessionProjectionStateMap {
     sessionMode: string | null;
+    sessionModeEditable: boolean;
   }
   interface SessionProjectionMap {
     /** 会话当前模式；`null` 表示没选过（用部署默认）。 */
     sessionMode: string | null;
+    /** 会话还能不能换模式：`true` 是选择器，`false` 是只读标签（client 那个 chip 据此变形）。 */
+    sessionModeEditable: boolean;
   }
 }
 
@@ -111,24 +116,65 @@ export const sessionModeProjection = {
   stateVersion: 1,
 } satisfies ProjectionDefinition<"sessionMode", string | null>;
 
+const sessionModeEditableSchema: z.ZodType<boolean> = z.boolean();
+
+/**
+ * 这个会话能不能换模式的投影：空白会话为 `true`，一旦 `turn/start` 落库就永远 `false`（换模式要的是**整段
+ * 历史**的模式一致，所以"开过 turn"之后连正在跑的那个 turn 也算）。
+ *
+ * **判据只有这一处**：服务端 {@link SessionModes.select} 的拒绝与 client chip 的只读形态都读它——以前
+ * client 只能等服务端报错，现在连入口都不给，而两边的结论来自同一份会话事实。
+ */
+export const sessionModeEditableProjection = {
+  key: "sessionModeEditable",
+  stateSchema: sessionModeEditableSchema,
+  init: () => true,
+  apply: (state: boolean, event: SessionEvent) => state && event.type !== "turn/start",
+  wire: { viewSchema: sessionModeEditableSchema, view: (state: boolean) => state },
+  stateVersion: 1,
+} satisfies ProjectionDefinition<"sessionModeEditable", boolean>;
+
 /** 模式清单、默认模式、按会话读取与切换。 */
 export class SessionModes extends Service {
   /** 每个 agent 已经装上的那一份（persona + 默认模型兜底；模式变了就换一份）。 */
   private readonly installs = new WeakMap<Agent, { mode: string; dispose: () => void }>();
 
-  constructor(
-    ctx: Context,
-    public config: ResolvedConfig,
-  ) {
+  /** 装配时的配置快照：`default` / `modes` 读它，改这两项靠 Loader 重挂这一行（已运行会话不自动换定义）。 */
+  readonly config: {
+    default: string;
+    modes: Record<string, SessionMode>;
+  };
+
+  constructor(ctx: Context, config: ResolvedConfig) {
     super(ctx, "sessionModes");
-    // 校验看的是**值**：`models` 在解析后是个稳定引用，`configProblem` 只认普通对象。
-    const problem = configProblem({ ...config, models: config.models.get() });
+    // 校验看的是**值**：字段解析后都是稳定引用，`configProblem` 只认普通对象。
+    // 快照取一份**可变**副本：volatile 的快照是深度只读，而内部按普通配置对象用（写回不走这里，改配置靠重挂）。
+    this.config = {
+      default: config.default.get(),
+      modes: structuredClone(config.modes.get()) as Record<string, SessionMode>,
+    };
+    // 退役的顶层 `models` 还配着值就让装配期报错。
+    const problem = configProblem({ ...this.config, models: config.models });
     if (problem !== undefined) throw new Error(problem);
     ctx.sessionProjections.register(sessionModeProjection);
+    ctx.sessionProjections.register(sessionModeEditableProjection);
     // 会话一建立就装上：这早于它的第一次装配，persona 因此一定在装配之前注册好。
     ctx.on("agent/created", ({ agent }) => {
       this.installFor(agent);
     });
+    // 官方 roster 在空白窗口换 preset 时，把该会话的扩展换成新 preset 那一份：先把它写成我们的会话事实
+    // （`installFor` 读的就是这份事实），再按新模式装一遍。
+    // 只在 preset → 模式的映射唯一时动手：本部署两个模式共享同一份 preset，反查无意义（`modeForPreset`
+    // 返回 `undefined`），选模式不会经过这条监听，模式事实由 `select` 自己落。
+    ctx.on("agent-preset/selected", (sessionId: SessionId, preset: string) => {
+      const mapped = this.modeForPreset(preset);
+      const agent = ctx.agents.get(sessionId);
+      if (mapped === undefined || agent === undefined) return;
+      if (this.ctx.sessionProjections.stateOf(agent.session, "sessionMode") !== mapped) {
+        agent.session.append("session-mode/selected", { sessionMode: mapped });
+      }
+      this.installFor(agent, mapped);
+    });
   }
 
   /** 新会话用它：config 里的 `default`。 */
@@ -198,6 +244,13 @@ export class SessionModes extends Service {
 
   /**
    * 把某个空白会话切到某个模式。
+   *
+   * 模式带着它的 preset（`preset` 决定行清单），所以这里**先把 agent preset 换成模式声明的那个**，再落我们的
+   * 会话事实：否则 preset realm 还是旧那一套的行，而它的注入在我们的开关之外（旧形态 `chat` 挂 `minimal`、
+   * 会话的 preset 却还是 `standard` 时，上游 `agent-instructions` 会照旧把工作区指令注进这个"不要注入"的会话）。
+   *
+   * 目标 preset 与当前挂着的**相同时不切**（本部署两个模式共享同一份 preset，所以切模式通常走不到这一步）：
+   * 换 preset 是一次重挂（卸旧行、装新行），没有变化就没有理由付出这个代价。
    * @param sessionId - 目标会话（必须还没有开过 turn）。
    * @param mode - 目标模式 id。
    * @returns 提交后的模式 id。
@@ -209,17 +262,57 @@ export class SessionModes extends Service {
     }
     const session = this.ctx.sessions.get(sessionId);
     if (session === undefined) throw new Error(`未知的会话 ${sessionId}`);
-    const boundary = this.ctx.sessionProjections.stateOf(session, "turnBoundary");
-    if (boundary !== undefined && (boundary.openTurnStartSeq !== null || boundary.lastTurn > 0)) {
+    // 空白窗口的判据只有一处：{@link sessionModeEditableProjection}。client 那个 chip 读的是同一个投影，
+    // 所以"看起来能选"与"服务端接受"不会脱节。
+    if (this.ctx.sessionProjections.stateOf(session, "sessionModeEditable") === false) {
       throw new Error("这个会话已经开始，模式不能再改；要换模式请新开一个会话。");
     }
-    session.append("session-mode/selected", { sessionMode: mode });
-    // 会话可能已经建好了 agent（空白会话也有）：立刻按新模式重新应用一遍。
     const agent = this.ctx.agents.get(sessionId);
+    const registry = this.presetRegistry();
+    if (agent !== undefined && registry !== undefined && definition.preset.length > 0) {
+      // 官方那条路自己也会查空白窗口（`agent-preset/locked`）。它切完会 emit `agent-preset/selected`，
+      // 下面那个监听据此把模式落成会话事实并装一遍——所以写事实前先比一次投影，同一个值不写第二条。
+      if (this.presetOfAgent(registry, agent) !== definition.preset) {
+        await registry.select(agent, definition.preset);
+      }
+    }
+    if (this.ctx.sessionProjections.stateOf(session, "sessionMode") !== mode) {
+      session.append("session-mode/selected", { sessionMode: mode });
+    }
+    // 会话可能已经建好了 agent（空白会话也有）：立刻按新模式重新应用一遍（与监听那次重复也无妨，幂等）。
     if (agent !== undefined) this.installFor(agent);
     return mode;
   }
 
+  /**
+   * 某个 agent 当前挂着的 preset（registry 的 `composedPreset`）。
+   *
+   * 读不到时返回 `undefined`（按"未知"处理 → 该切就切）：`composedPreset` 是 registry 较新的读面，替身与老
+   * 版本可能没有它；而"没挂任何 preset"（返回值 `undefined`）与"读不到"在这里是同一个结论。
+   */
+  private presetOfAgent(registry: Context["agentPresets"], agent: Agent): string | undefined {
+    const read = (registry as { composedPreset?: (ctx: Context) => string | undefined })
+      .composedPreset;
+    if (typeof read !== "function") return undefined;
+    try {
+      return read.call(registry, agent.ctx);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * 官方 preset registry：行清单与它的选择面住在那一行。不在 `inject` 里点名（headless 部署没有它，
+   * 点名会让本行永不激活），所以按"可能拿不到"读——`ctx.get` 在当前 ctx 没声明那个服务时会抛。
+   */
+  private presetRegistry(): Context["agentPresets"] | undefined {
+    try {
+      return this.ctx.get("agentPresets");
+    } catch {
+      return undefined;
+    }
+  }
+
   /**
    * 把某个活着的 agent 切到某个模式。与 {@link select} 的差别：它不要求空白会话——子代理创建时的继承
    * 走这里，**未来的"指定 mode"入口（模型侧或配置侧）也走这里**（那条接缝还没做）。
@@ -241,15 +334,51 @@ export class SessionModes extends Service {
    * 继承要**写进子会话日志**：它是一条会话事实，冷恢复与 fork 都要靠它重建（{@link modeOf} 只读投影）。
    */
   private resolveModeId(agent: Agent): string {
-    // `undefined` = 这个投影没注册（或还没初始化），与"没选过"（`null`）一样落到默认。
+    // `undefined` = 这个投影没注册（或还没初始化），与"没选过"（`null`）一样落到下一层。
     const selected = this.ctx.sessionProjections.stateOf(agent.session, "sessionMode");
     if (typeof selected === "string") return selected;
+    // 会话级选择归官方 roster：它的 preset 决定这个会话用哪份扩展，我们把结论落成自己的会话事实
+    // （`sessionMode` 是会话级事实的 home：恢复、子代理继承、服务端读取都读它）。
+    const mapped = this.modeForPreset(this.presetOf(agent.session));
+    if (mapped !== undefined) {
+      agent.session.append("session-mode/selected", { sessionMode: mapped });
+      return mapped;
+    }
     const inherited = this.inheritedModeId(agent);
     if (inherited === undefined) return this.defaultId;
     agent.session.append("session-mode/selected", { sessionMode: inherited });
     return inherited;
   }
 
+  /** 官方 roster 选定的 preset（没选过、或 registry 没装时为 `undefined`）。 */
+  private presetOf(session: Session): string | undefined {
+    try {
+      const state = this.ctx.sessionProjections.stateOf(session, "agentPreset");
+      return typeof state === "string" ? state : undefined;
+    } catch {
+      // registry 没装（headless 部署）时这个投影不存在：按"没有选择"处理。
+      return undefined;
+    }
+  }
+
+  /**
+   * 某个 agent preset 对应的模式 id——**只在映射唯一时**回答（几个模式挂同一份 preset 时返回
+   * `undefined`，不反查）。
+   *
+   * 本部署的两个模式共享同一个 preset（`MODE_PRESET_ID`），差异全在会话级收口，所以 preset → 模式的反查在
+   * 这里无意义：模式由**会话事实**决定（`session-mode/selected` 投影 → 子代理继承 → 部署默认），
+   * 官方 roster 选了什么 preset 不改变这个会话是哪个模式。这条反查留给"一对一映射"的部署形态。
+   * @param preset - preset id（`undefined` 表示没选过、或 registry 没装）。
+   * @returns 该 preset 唯一对应的模式 id；没配扩展、或由多个模式共享时 `undefined`。
+   */
+  modeForPreset(preset: string | undefined): string | undefined {
+    if (preset === undefined) return undefined;
+    const owners = Object.keys(this.config.modes).filter(
+      (id) => this.config.modes[id]?.preset === preset,
+    );
+    return owners.length === 1 ? owners[0] : undefined;
+  }
+
   /** 子代理（有 durable 父会话）继承父当前模式；父不在场、或不是子代理时没有可继承的。 */
   private inheritedModeId(agent: Agent): string | undefined {
     const parentId = agent.session.header.parentSession;
@@ -278,18 +407,16 @@ export class SessionModes extends Service {
   }
 
   /**
-   * 模式的默认模型（config 顶层 `models.<模式 id>`）兜底：只在会话**尚无任何模型事实**（没选过模型、也
+   * 模式的默认模型（`modes.<模式 id>.defaultModel`）兜底：只在会话**尚无任何模型事实**（没选过模型、也
    * 还没跑过请求）时接管这一请求的路由；一旦用户选过（投影 `pending`）或会话已经落过 header，就不再插手。
    *
-   * 它是**配置事实**，不写会话事件——重启后仍由 config 决定；设置页里那条会话级选择才是会话事实。
-   *
-   * 模型取自 `config.models`：那是个 volatile 引用，设置页保存时只有**引用里的值**变，这一行不重挂，
-   * 所以每次请求都现场 `.get()`（与 `llm-openai-compatible` 读 `config.providers` 同一种读法）。
+   * 它是**配置事实**，不写会话事件——重启后仍由 config 决定；设置页里那条会话级选择才是会话事实。读的是构造
+   * 时那份模式清单快照：设置页保存会让这一行重挂（`reconcileProfilePatches`），新定义随重挂生效。
    */
   private installDefaultModel(agent: Agent, modeId: string): () => void {
     return agent.ctx.on("agent/request", async (_payload, next): Promise<LlmCallConfig> => {
       const resolved = await next();
-      const model = this.config.models.get()[modeId];
+      const model = this.config.modes[modeId]?.defaultModel;
       if (model === undefined) return resolved;
       // 上游 session-controller 没装（headless）时这个投影不存在，按"没有选择"处理。
       const pending = this.ctx.sessionProjections.stateOf(agent.session, "modelSelection")?.pending;

package/{tool/modes.ts → src/mode-sources.ts}

@@ -1,19 +1,39 @@
 /**
- * 模式定义的真源：`cordis.patch.yml` 里 `session-mode` 行的 `config` 由这里渲染。
+ * 模式定义的真源：`session-mode` 行的 `config` 由 `./rows.ts` 渲染（装配入口在 `packages/bundles/session-mode-profile`）。
  *
  * "自定义"就落在这份数据上——装配层（profile 的用户 patch 层）可以整体改写 `config.modes`，也可以只给
  * 某个模式换提示词或工具白名单，不需要任何插件行。
  *
  * `allowTools` 从 [`@morlay/dsh-agent-toolkit/rows`](../../../dsh-agent-toolkit/src/rows.ts) 的
- * `TOOLKIT_TOOL_NAMES` 派生（工具集与汉化同源）：toolkit 的 bundle 在 profile 平面把工具行装一次，模式
- * 只声明"我这些会话能用哪些"。想改某一个模式的名单，直接在这条源数据里加/减。
+ * `TOOLKIT_TOOL_NAMES` 派生（工具名与汉化同源）：**行清单由本部署自己注册的那份 preset 提供**
+ * （{@link MODE_PRESET_ID}，两个模式共享它），白名单里那份 preset 没有的工具自动跳过。想改某一个模式的名单，
+ * 直接在这条源数据里加/减。
  */
 
 import { TOOLKIT_TOOL_NAMES } from "@morlay/dsh-agent-toolkit/rows";
 
+/**
+ * 本部署自己注册的那份 agent preset 的 id：两个模式共享它（行清单见
+ * `packages/bundles/session-mode-profile`，`config.plugins` 引用 `@morlay/dsh-agent-toolkit/rows` 的
+ * `TOOLKIT_PRESET_ROWS`）。
+ *
+ * 为什么自己注册而不是复用官方 preset：官方 `minimal` 没有 `tool-web`，`chat` 的白名单（提问 + 联网三件）
+ * 收口后一件都不剩；而且官方 preset 自带的上游注入要在我们的开关之外做"让位"，抢 `skill` 面还得把目录 kind
+ * 换掉。行清单归我们之后，两个模式的**差异全在会话级收口**（persona / `allowTools` / 两个开关）。
+ */
+export const MODE_PRESET_ID = "mode-switch";
+
 /** 一个模式的源定义：就是 `session-mode` 行 `config.modes` 里的一项。 */
 export interface ModeSource {
   readonly id: string;
+  /**
+   * 挂哪个 agent preset（它的 `id`）：行清单由那个 preset 提供，这里只写扩展。
+   *
+   * 官方四个 shipped preset 照旧可选（官方 roster 选择面没动），但我们的模式都挂
+   * {@link MODE_PRESET_ID}；两个模式共享同一个 preset 是**有意**的（差异靠会话级收口表达），所以
+   * preset → 模式的反查在这种共享下无意义（见 `SessionModes.modeForPreset`）。
+   */
+  readonly preset: string;
   readonly name: string;
   readonly description: string;
   /** 归谁用：`main`（用户选择器，缺省）、`subagent`（可作子代理 mode 的候选）。 */
@@ -22,9 +42,11 @@ export interface ModeSource {
   readonly allowTools: readonly string[];
   readonly instructions?: boolean;
   readonly runtimeContext?: boolean;
+  /** 这个模式的默认模型（省略就跟全局 `agent-default-model`）。 */
+  readonly defaultModel?: ModeModelSource;
 }
 
-/** 一个模式的默认模型源定义：就是 `session-mode` 行 `config.models[<模式 id>]`。 */
+/** 一个模式的默认模型源定义：`modes.<模式 id>.defaultModel`。 */
 export interface ModeModelSource {
   readonly provider: string;
   readonly model: string;
@@ -49,18 +71,12 @@ const CHAT_PERSONA = {
 /** 新会话用哪个模式（`session-mode` 行的 `config.default`）。 */
 export const DEFAULT_MODE = "coding";
 
-/**
- * 各模式的默认模型（`session-mode` 行 `config.models`：模式 id → 模型）。
- *
- * 当前为空——两个模式都跟着全局 `agent-default-model`。要改某个模式的默认模型就写在这里（键必须是
- * `MODE_SOURCES` 里的 id，装配期校验会拒绝孤儿键）；用户在设置页写的那份由 settings 的用户层叠在它上面。
- */
-export const MODE_MODELS: Readonly<Record<string, ModeModelSource>> = {};
-
-/** 两个模式：编码与对话。 */
+/** 两个模式：编码与对话。**同一个 preset，差异全在会话级收口**。 */
 export const MODE_SOURCES: readonly ModeSource[] = [
   {
     id: "coding",
+    // 完整工具集由我们自己的 preset（`TOOLKIT_PRESET_ROWS`）提供。
+    preset: MODE_PRESET_ID,
     name: "编码模式",
     description: "功能完整的编码 Agent：文件、Shell、检索、联网等工具常驻，其余用法说明按需加载。",
     persona: CODING_PERSONA,
@@ -70,13 +86,15 @@ export const MODE_SOURCES: readonly ModeSource[] = [
   },
   {
     id: "chat",
+    // 同一个 preset：行清单里有联网工具，收口才收得成"提问 + 联网"。
+    preset: MODE_PRESET_ID,
     name: "对话模式",
     description:
       "只做对话：提问与联网（搜索、抓取）三件工具，不注入系统提示词、工作区指令与技能目录。",
     persona: CHAT_PERSONA,
     // 只做用户侧对话：不做子代理的候选（父在 chat 里派发的子代理仍继承 chat，见 README 的"角色"一节）。
     role: ["main"],
-    // 提问与联网三件：工具行由 toolkit 的 bundle 装，这里只收口。
+    // 提问与联网三件：行由 preset 提供，这里只收口（preset 没有的自动跳过）。
     allowTools: ["ask_user_question", "web_search", "web_fetch"],
     // 没有文件与 shell 工具，"能改工作区哪些文件、要不要走审批"对它全是噪音。
     instructions: false,

package/src/modes.ts

@@ -5,6 +5,9 @@
  * 模式不再是 Cordis 子树，而是这份纯数据——本包的插件行只在 `config.modes` 里声明它们，运行期按会话读取
  * 并应用（persona 注册到该 agent 的 scope，工具收口交给 `@morlay/dsh-context-assembler/scope`）。
  *
+ * 行清单（工具 / 命令 / 压缩 / 委派…）来自 `preset` 指的那份 agent preset：本部署自己注册了一份
+ * （`packages/bundles/session-mode-profile` 的 `preset-mode-switch`），两个模式共享它，差异全在会话级收口。
+ *
  * "支持自定义"就是指这份 config：装配层（`cordis.patch.yml` / profile 的用户层）能整体改写 `modes`，
  * 也可以只给某几个模式换提示词或白名单——不需要任何插件行。
  *
@@ -40,7 +43,7 @@ export interface SessionModeModel {
   readonly reasoningEffort?: string;
 }
 
-/** 各模式的默认模型：模式 id → 模型；键必须在 `modes` 里（装配期校验）。 */
+/** 退役的顶层形状：模式 id → 模型（默认模型现在住在各自的模式里）。 */
 export type SessionModeModels = Readonly<Record<string, SessionModeModel>>;
 
 /**
@@ -51,7 +54,17 @@ export type SessionModeModels = Readonly<Record<string, SessionModeModel>>;
  * 不看这里。
  */
 export interface SessionMode {
-  /** 选择器里的展示名。 */
+  /**
+   * 这个模式挂在哪个 **agent preset** 上（官方 `standard` / `ptc` / `minimal` / `cordis`，或本部署自己
+   * 注册的那一份的 `id`，见 `mode-sources.ts` 的 `MODE_PRESET_ID`）。
+   *
+   * preset 决定这个 agent 有哪些行（工具 / 命令 / 压缩 / 委派…），模式只决定"这些行怎么被用"：
+   * `allowTools` 里 preset 没有的工具自动跳过，其余扩展（persona / 注入开关 / 默认模型）照常应用。
+   * **可以共享**（本部署就是两个模式挂同一份 preset，差异全在会话级收口）；共享时 preset → 模式的反查无从下手，
+   * 见 `SessionModes.modeForPreset`。空串表示不挂（只能由 applyTo / 继承使用）。
+   */
+  readonly preset: string;
+  /** 模式的展示名（选择面归官方 roster；这里留着做事实文案）。 */
   readonly name: string;
   /** 一句话说明这个模式干什么；空串表示没写。 */
   readonly description: string;
@@ -74,10 +87,21 @@ export interface SessionMode {
    * ——对话模式没有文件与 shell 工具，"能改工作区哪些文件、要不要走审批"对它全是噪音。
    */
   readonly runtimeContext: boolean;
+  /**
+   * 这个模式的默认模型；省略就跟全局 `agent-default-model`。**可选**：没配的模式在页面上不出现在这一行
+   * （`defaultModel` 是它所在模式的一个可加字段）。
+   */
+  readonly defaultModel?: SessionModeModel;
 }
 
 // 每个字段都带 default：schema 的产物因此没有 `undefined` 键（`exactOptionalPropertyTypes` 下"缺省的键"
 // 会与可选属性对不上），而默认值就是"不遮蔽"的那个语义——persona 的默认是两段空文本。
+/**
+ * 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
+ * （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
+ */
+const localized = (text: { zh: string; en: string }): string => text as unknown as string;
+
 const personaSchema = z.object({
   prefix: z.string().default(""),
   suffix: z.string().default(""),
@@ -88,65 +112,190 @@ const roleSchema = z.union([z.const("main"), z.const("subagent")]);
 
 /** 默认模型的形状与全局 `agent-default-model` 一致；省略 effort 就跟 provider 默认。 */
 const modelSchema = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  reasoningEffort: z.string(),
+  provider: z
+    .string()
+    // 候选来自客户端注册的具名源 `llm-providers`：字段只说"这是选一个"，不关心行 id 与路径。
+    .role("select", { source: "llm-providers" })
+    .description(
+      localized({
+        zh: "服务商 id（部署里注册的任意路由，不论哪个适配器插件注册的）。",
+        en: "Provider id (any route registered in this deployment, whichever adapter plugin supplies it).",
+      }),
+    ),
+  model: z
+    .string()
+    // 具名源 `llm-models` 自己声明依赖 `provider`（换服务商就换清单）。
+    .role("select", { source: "llm-models" })
+    .description(
+      localized({
+        zh: "模型 id。",
+        en: "Model id.",
+      }),
+    ),
+  reasoningEffort: z.string().description(
+    localized({
+      zh: "思考档位；省略就跟服务商自己的默认。",
+      en: "Reasoning effort; unset keeps the provider's own default.",
+    }),
+  ),
 });
 
-/** 本包 config 的**源码形状**：装配层与设置页写的那个形状（`models` 是普通对象，可以整块省略）。 */
+/** 本包 config 的**源码形状**：装配层与设置页写的那个形状。 */
 export interface Config {
   /** 新会话（还没选过模式的会话）用哪个模式。必须是 `modes` 里的一个 id。 */
   readonly default: string;
-  /** 模式清单：id → 定义。顺序即选择器里的顺序（`Object.entries` 的插入序）。 */
+  /** 模式清单：id → 定义（含各自的 `defaultModel`）。顺序即选择器里的顺序（`Object.entries` 的插入序）。 */
   readonly modes: Record<string, SessionMode>;
   /**
-   * 各模式的默认模型：模式 id → 模型。省略的模式跟着全局 `agent-default-model` 走。
-   *
-   * 它是 config 的**顶层 volatile 字段**：设置面（`ctx.configForms` → 我们那张卡片）编辑的就是它。挪进
-   * `modes.<id>` 会让设置面看不见它——`schemastery` 的 `validateVolatileSchema` 把 dict 内部一律当成
-   * blocked，而 settings 只挑得出固定路径上的 volatile 字段。
+   * 各模式默认模型曾经住在这里（模式 id → 模型）。现在住在**每个模式自己的 `defaultModel`** 里，这个字段
+   * 只剩一件事：装配期看见它还配着值就报错，提醒把它挪进对应的模式——否则它会静静地失效。
    */
   readonly models?: SessionModeModels;
 }
 
-/** schema 解析之后的形状：volatile 字段被换成**稳定引用**，读它要过 `.get()`（设置页改的就是同一份）。 */
+/**
+ * schema 解析之后的形状：volatile 字段被换成**稳定引用**，读它要过 `.get()`（设置页改的就是同一份）。
+ *
+ * `default` 与 `modes` 都是 volatile：默认模式与整份模式清单（含各自的 `defaultModel`）都在行配置页上。
+ */
 export interface ResolvedConfig {
-  readonly default: string;
-  readonly modes: Record<string, SessionMode>;
-  /** 各模式的默认模型；一个都没配时是空对象（schema 的 default）。 */
-  readonly models: Volatile<SessionModeModels>;
+  readonly default: Volatile<string>;
+  readonly modes: Volatile<Record<string, SessionMode>>;
+  /** 退役的顶层字段：解析后仍在这儿（普通值，不 volatile），装配期据此发现"还配着值"并报错。 */
+  readonly models: SessionModeModels;
 }
 
 const modeSchema: z<SessionMode> = z.object({
-  name: z.string().required(),
-  description: z.string().default(""),
-  role: z.array(roleSchema).default(["main"]),
+  preset: z
+    .string()
+    .default("")
+    .description(
+      localized({
+        zh: "这个模式挂哪个 agent preset（它的 id，官方或本部署自建的）：行清单由那个 preset 提供，几个模式可以共享同一个；空串表示不挂（只能由 applyTo / 继承使用）。",
+        en: "Which agent preset this mode rides on (its id, shipped or deployment-owned): that preset supplies the row list and several modes may share it; empty means none (usable only through applyTo / inheritance).",
+      }),
+    ),
+  name: z
+    .string()
+    .required()
+    .description(
+      localized({
+        zh: "模式名（事实文案；选择面归官方 roster）。",
+        en: "Mode name (fact copy; the picker belongs to the official roster).",
+      }),
+    ),
+  description: z
+    .string()
+    .default("")
+    .description(
+      localized({
+        zh: "一句话说明。",
+        en: "One-line description.",
+      }),
+    ),
+  role: z
+    .array(roleSchema)
+    .default(["main"])
+    .description(
+      localized({
+        zh: "谁可以用这个模式：`main`（会话选择器里可选）或 `subagent`（子代理继承）。",
+        en: "Who may use this mode: `main` (selectable in sessions) or `subagent` (inherited by subagents).",
+      }),
+    ),
   persona: personaSchema.default({}),
-  allowTools: z.array(z.string()).default([]),
-  instructions: z.boolean().default(true),
-  runtimeContext: z.boolean().default(true),
+  allowTools: z
+    .array(z.string())
+    .default([])
+    .description(
+      localized({
+        zh: "这个会话能用的工具；其余既不进目录，调用也被拒。",
+        en: "Tools this session may use; everything else leaves the catalog and calls are refused.",
+      }),
+    ),
+  instructions: z
+    .boolean()
+    .default(true)
+    .description(
+      localized({
+        zh: "是否要 instruction 类注入（工作区指令、技能目录、用法正文）。",
+        en: "Whether instruction-class injections apply (workspace instructions, skill catalog, guidance).",
+      }),
+    ),
+  runtimeContext: z
+    .boolean()
+    .default(true)
+    .description(
+      localized({
+        zh: "是否要动态快照（文件沙箱策略、审批策略）。",
+        en: "Whether the runtime snapshot applies (sandbox and approval policy).",
+      }),
+    ),
+  /**
+   * 这个模式的默认模型。不标 `volatile`：`modes` 本身就是 volatile，整棵子树都在页面上——再标一层会被
+   * schemastery 拒（`validateVolatileSchema` 不许 volatile 套 volatile）。
+   */
+  defaultModel: modelSchema
+    // `default(null)` 是"没配就没有这个键"：schemastery 对缺省的对象字段会造一个空对象，那样每个模式都会
+    // 凭空多出一行；给了 null 反而让它保持缺失（页面按非必填处理，从候选加成）。
+    // 类型上放行一次：`null` 在这里只是"没有这个键"的写法，schema 的输入形状不接受它。
+    .default(null as unknown as SessionModeModel)
+    .description(
+      localized({
+        zh: "这个模式的默认模型；省略就跟全局默认模型。只在会话还没有模型事实时接管。",
+        en: "Default model for this mode; unset follows the global default. Applies only while a session has no model fact yet.",
+      }),
+    ),
 });
 
 export const Config: z<Config, ResolvedConfig> = z.object({
-  default: z.string().required(),
-  modes: z.dict(modeSchema).required(),
-  models: z.dict(modelSchema).default({}).volatile(),
+  default: z
+    .string()
+    .required()
+    .description(
+      localized({
+        zh: "新会话（还没选过模式的会话）用哪个模式；必须是下面 `modes` 里的一个 id。",
+        en: "Mode a session starts in before anyone picks one; must be an id in `modes`.",
+      }),
+    )
+    .volatile(),
+  modes: z
+    .dict(modeSchema)
+    .required()
+    .description(
+      localized({
+        zh:
+          "模式清单：id → 定义（persona / 允许的工具 / 角色）。改它对**已运行会话**不自动生效——重挂后新建的会话、" +
+          "或重新应用模式的会话才用新定义。",
+        en:
+          "Mode roster: id to definition (persona, allowed tools, role). Edits do not follow into already-running " +
+          "sessions; sessions created after the row is remounted use the new definition.",
+      }),
+    )
+    .volatile(),
+  /**
+   * 退役字段：默认模型住在每个模式自己的 `defaultModel` 里。这里留着是为了**报错**（见 `configProblem`），
+   * 页面上不出现（`hidden()`）。
+   */
+  models: z.dict(modelSchema).default({}).hidden(),
 });
 
-/** 校验只需要看的那几件事：默认模式、每个模式的工具名单与角色、配了的默认模型。 */
+/** 校验只需要看的那几件事：默认模式、每个模式的工具名单与角色、每个模式自己的默认模型。 */
 interface Validated {
   readonly default: string;
   readonly modes: Readonly<
     Record<
       string,
       {
+        /** 空串合法的"不挂"；共享合法（差异由会话级收口表达），所以这里不做任何映射唯一性校验。 */
+        readonly preset?: string;
         readonly allowTools?: readonly string[];
         readonly role?: readonly string[];
+        readonly defaultModel?: { readonly provider?: string; readonly model?: string };
       }
     >
   >;
-  /** 配了的默认模型；省略等于"一个都没配"（源码形状与解析后的形状都能校验）。 */
-  readonly models?: Readonly<Record<string, { readonly provider?: string; readonly model?: string }>>;
+  /** 退役的顶层字段：还配着值就报错（它已经不再生效）。 */
+  readonly models?: Readonly<Record<string, unknown>>;
 }
 
 /** 模式定义里不合法的地方（装配期 fail loud，而不是等到某个会话装配提示词时才发现）。 */
@@ -169,16 +318,28 @@ export function configProblem(config: Validated): string | undefined {
   if (empty.length > 0) {
     return `session-mode: mode(s) ${empty.join(", ")} declare no \`allowTools\`; list the tools instead of leaving it empty`;
   }
-  // `models` 的键是模式 id：写错一个就成了"配了但永远不会生效"的孤儿，装配期就得看见。
-  const unknown = Object.keys(config.models ?? {}).filter((id) => !ids.includes(id));
-  if (unknown.length > 0) {
-    return `session-mode: \`models\` names unknown mode(s) ${unknown.join(", ")}; available are ${ids.join(", ")}`;
+  // `preset` **允许共享**（本部署两个模式挂同一份 preset，差异由会话级收口表达）：共享时 preset → 模式
+  // 的反查无从下手，那件事交给 `SessionModes.modeForPreset` 处理（共享时它返回 `undefined`，不反查）。
+  // 空串是"不挂"，合法；除此之外没有可校验的东西——preset 是否存在由 registry 自己回答。
+  // 退役的顶层字段还配着值：它已经不再生效，别让一份"看着像配过"的配置静静地失效。
+  if (Object.keys(config.models ?? {}).length > 0) {
+    return "session-mode: `models` has moved into each mode's `defaultModel`; move the entries there and drop the top-level `models`";
   }
-  const partial = Object.entries(config.models ?? {})
-    .filter(([, model]) => model.provider === undefined || model.model === undefined || model.provider.length === 0 || model.model.length === 0)
+  // 每个模式自己的默认模型：成对给全（`provider` 与 `model` 都要）。
+  const partial = Object.entries(config.modes)
+    .filter(([, mode]) => {
+      const model = mode.defaultModel;
+      if (model === undefined) return false;
+      return (
+        model.provider === undefined ||
+        model.model === undefined ||
+        model.provider.length === 0 ||
+        model.model.length === 0
+      );
+    })
     .map(([id]) => id);
   if (partial.length > 0) {
-    return `session-mode: mode(s) ${partial.join(", ")} declare \`models\` without both \`provider\` and \`model\``;
+    return `session-mode: mode(s) ${partial.join(", ")} declare \`defaultModel\` without both \`provider\` and \`model\``;
   }
   return undefined;
 }