dsh-custom-mode 1.10.0 → 1.11.1

package/composition.mjs

@@ -30,12 +30,16 @@ import { join } from 'node:path'
 // 本模块只消费它 —— 合成与排版手术仍然全部发生在这里。
 import {
   baseCompositionPath,
+  BASE_MODE_IDS,
+  BaseCompositionUnavailableError,
   readBaseCompositionText,
   setShippedPresetsDir,
   shippedPresetsDir,
+  UNION_MODE_ID,
 } from './base-composition.mjs'
 
 export { baseCompositionPath, setShippedPresetsDir, shippedPresetsDir } from './base-composition.mjs'
+export { BASE_MODE_IDS, UNION_MODE_ID } from './base-composition.mjs'
 export {
   BaseCompositionUnavailableError,
   isBaseCompositionUnavailable,
@@ -50,16 +54,27 @@ export {
  */
 
 /**
- * Base modes a user may build on.
+ * Base modes a user may build on — the picker's own list, in order.
+ *
+ * The first four are the **shipped** modes (`BASE_MODE_IDS`); a fifth is synthesised here
+ * ({@link UNION_MODE_ID}), so "which rows can I switch at all" stops being decided by whichever single
+ * shipped mode the user happened to pick.
  *
- * `custom` is deliberately absent: it is this feature's own output, and offering
- * it as a base would let a preset recursively include itself.
+ * `custom` is still deliberately absent, and for the same reason as before: it is this feature's own
+ * output, and a base mode by that name would make a preset recursively include itself. The union mode
+ * sidesteps that by being a **different id** (`all`) whose text is built from the four *shipped* modes —
+ * it never asks the host for the user's own preset.
  */
 export const BASE_MODES = [
   { id: 'standard', label: '标准模式', note: '完整编码能力：Shell、文件、检索、技能、计划、目标、子代理、工作流' },
   { id: 'ptc', label: 'PTC 模式', note: '在标准模式基础上启用 PTC 工具呈现（tool-presentation）' },
   { id: 'minimal', label: '极简模式', note: '只有 Shell 与终端，共 7 行；没有文件、检索、技能、子代理' },
   { id: 'cordis', label: 'Cordis 模式', note: '标准模式 + 读写运行时的 Cordis 工具集，可让 agent 自己改 harness' },
+  {
+    id: UNION_MODE_ID,
+    label: '自定义模式',
+    note: '不继承任何单一原生模式：以标准模式的全套行为底，补上只有 PTC / 极简 / 创造模式才有的行，全部都能逐行开关',
+  },
 ]
 
 /**
@@ -117,6 +132,50 @@ export const ROW_META = {
   'persistent-pwsh': { label: '持久 pwsh' },
 }
 
+/**
+ * 出厂行里的**互斥组**：同一份组成里同时启用，会让挂载方把整个预设判为 **broken**，
+ * 而 broken 的预设被从**所有**选择器里静默丢掉 —— 设置页却照常工作（本仓记录过两次的最阴的一种失败）。
+ *
+ * 实测依据（2026-10-01，dsh `0.2.0-rc.2`）：把并集组成真的写进 `.agent-presets/custom/agent.cordis.yml`
+ * 再启动，然后读实例自己的 `/api/custom-mode`：
+ *
+ *     broken = "persistent-bash (@deepseek-ai/dsh-tool-bash-persistent):
+ *               tool \"bash\" is already registered in this scope"
+ *
+ * 两套壳注册的工具名相同（`bash` / `pwsh`），所以它们是**二选一**，不是叠加。极简模式里不冲突，
+ * 只是因为它**没有**标准那一套。逐行开关本身表达不了"二选一"，所以互斥必须在这里显式声明。
+ *
+ * 同一轮实测的对照（每行都是"写组成 → 真启动 → 读 broken"）：
+ *
+ * | 组成 | broken |
+ * | --- | --- |
+ * | 并集原样 | ✗（上面那条） |
+ * | 只关掉 `persistent-shell` | ✓ null |
+ * | 只关掉 `tool-bash` + `tool-pwsh` | ✓ null |
+ * | 把 `persistent-shell` 整组删掉 | ✓ null |
+ * | 删掉 `tool-presentation` / `tool-cordis`（两个附加行） | ✗ 仍 broken ⇒ 附加行无罪 |
+ *
+ * ★ 这条表**必须被维护**：上游调整行时它就是唯一的真相。`composition.test.mjs` 会断言表里每个 id
+ * 都真的出现在某份出厂组成里 —— 上游把它删了，CI 就红，而不是让这里静默失效。
+ */
+export const EXCLUSIVE_ROW_SETS = [
+  {
+    id: 'shell',
+    sides: [
+      { label: '标准壳', rows: ['tool-bash', 'tool-pwsh'] },
+      { label: '持久终端壳', rows: ['persistent-shell'] },
+    ],
+    /**
+     * 并集模式里默认关掉哪一侧。
+     *
+     * 必须**显式关**，不能指望"取那位模式的出厂默认"：`persistent-shell` 在极简模式里出厂就是**启用**的
+     * （那正是极简模式的全部内容），所以照搬出厂状态合出来的并集是**非法**的。实测：`overrides: {}`
+     * 保存并集模式，写完之后不重启，roster 里立刻就是 `broken`。
+     */
+    unionDefaultOff: ['persistent-shell'],
+  },
+]
+
 /** 出厂组成的路径与解析链都在 base-composition.mjs（下面按名字再导出，调用点不必分支）。 */
 
 /**
@@ -126,27 +185,145 @@ export const ROW_META = {
  * directory → packaged `dsh-web-app` patch — lives in base-composition.mjs, so every route can be
  * tested on its own and the failure carries a `code` instead of a bare message.
  *
+ * {@link UNION_MODE_ID} is the one mode with no route: it is synthesised here (see
+ * {@link unionCompositionText}), so this function stays the single entry point every caller uses and no
+ * caller has to know which modes ship a file.
+ *
  * @param {string} modeId - one of {@link BASE_MODES}.
  * @returns {string} the entry-list YAML of that base mode.
  * @throws {BaseCompositionUnavailableError} when no route yields text (callers degrade, see index.mjs).
  */
 export function readBaseComposition(modeId) {
+  if (modeId === UNION_MODE_ID) return unionCompositionText()
   return readBaseCompositionText(modeId).text
 }
 
+/**
+ * The union of the four shipped compositions — the text behind {@link UNION_MODE_ID}.
+ *
+ * ## Why this exists
+ *
+ * The row list used to be whatever the *single* shipped mode the user picked happened to contain, and a
+ * switch can only rewrite rows the base text already has — so a row declared by one mode and not by the
+ * chosen one was not "hidden in the UI", it was **unreachable through the composer**. Measured on
+ * `0.2.0-rc.2`: `standard` / `ptc` / `cordis` each declare 33 rows and `minimal` declares 7, but their
+ * union is 40. Picking `standard` therefore leaves `tool-presentation` (only in ptc), the whole
+ * `persistent-shell` group (only in minimal) and `tool-cordis` (only in cordis) permanently unswitchable.
+ *
+ * ## How it is built
+ *
+ * Text surgery, exactly like the rest of this module: the four shipped texts are split at the TOP level and
+ * concatenated, skipping a row id that is already present. A group therefore travels **whole** — children,
+ * its `isolate` realm, its comments and its `!!js` conditions included. That is the only way a service row
+ * can be carried into this mode without inventing a realm for it, and inventing one is not cosmetic:
+ * `dsh-agent-presets` rejects a service row that has none, and the platform then drops the entire preset
+ * from every picker.
+ *
+ * Only top-level ids are compared. Children ride along inside their group, so a nested id can never be
+ * half-merged; if two modes both declare a group, the group is taken from whichever mode wins below, and
+ * its children come with it.
+ *
+ * ## Which mode wins
+ *
+ * First writer, in `BASE_MODE_IDS` order (`standard` → `ptc` → `minimal` → `cordis`). The order is not
+ * cosmetic: `standard` is the mode this product's own preset is derived from, so a row declared in more
+ * than one mode keeps **standard's text and standard's shipped default**. The visible consequence is
+ * deliberate — `tool-plugin-manager` ships disabled in `standard` and enabled in `cordis`, and the union
+ * keeps it disabled (the user turns it on per assistant if they want it). The alternative rule, "enabled
+ * if any mode enables it", would silently arm the model's plugin manager in a mode the user never chose.
+ *
+ * ## Nothing is cached
+ *
+ * The four source texts are not stable for the lifetime of a process: the tests swap
+ * `DSH_SHIPPED_PRESETS_DIR` between cases, and the host may re-declare a preset on any registry sync. A
+ * cache here would be a stale answer that looks authoritative. Four extra reads per call is the honest
+ * price, and this is not a hot path.
+ *
+ * ## One source failing is fatal, not skipped
+ *
+ * A union that quietly dropped `minimal` when that one route broke would still render, still look complete,
+ * and be missing the rows the user was told they could switch — precisely the silent lie this module's
+ * typed failure exists to prevent. So a failure propagates as {@link BaseCompositionUnavailableError} with
+ * the failing mode named, and the page degrades honestly: the prompt stays editable while the base mode and
+ * the switches are marked unavailable.
+ *
+ * @returns {string} entry-list YAML: the union, behind a banner recording where each part came from.
+ * @throws {BaseCompositionUnavailableError} when any shipped mode cannot be read.
+ */
+function unionCompositionText() {
+  const seen = new Set()
+  const parts = []
+  const sources = []
+  for (const modeId of BASE_MODE_IDS) {
+    let resolved
+    try {
+      resolved = readBaseCompositionText(modeId)
+    } catch (error) {
+      // 逐条记下**是哪一位**读不到，再抛类型化失败 —— 页面据此说出具体原因，而不是笼统的"取不到"。
+      throw new BaseCompositionUnavailableError(UNION_MODE_ID, [
+        ...sources.map((each) => each.modeId + '：可用（' + each.source + '）'),
+        modeId + '：' + String((error && error.message) || error),
+      ])
+    }
+    sources.push({ modeId, source: resolved.source })
+    for (const segment of splitSegments(resolved.text, true).segments) {
+      if (seen.has(segment.id)) continue
+      seen.add(segment.id)
+      parts.push(segment.text)
+    }
+  }
+  if (parts.length === 0) {
+    throw new BaseCompositionUnavailableError(UNION_MODE_ID, ['四个出厂模式都没有任何行'])
+  }
+  const banner = [
+    '# 本段是四个出厂组成的并集（' + BASE_MODE_IDS.join(' → ') + '）。',
+    '# 同一行在多个模式里都有时，取**先出现的那个模式**的原文与出厂默认（顺序即上面这一行）。',
+    '# 分组是整体搬运的，isolate realm 与 !!js 平台条件因此原样保留。',
+    ...sources.map((each) => '#   ' + each.modeId + ' ← ' + each.source),
+    '',
+  ].join('\n')
+  // 分段自带尾换行、拼接时不加分隔符（splitSegments 的不变量），所以这里同样用 '' 连接。
+  const merged = banner + parts.join('')
+  // ★ 同名工具的两套壳不能同时启用（见 EXCLUSIVE_ROW_SETS 的实测）：并集把"另一侧"**显式关掉**，
+  //   让默认组成是合法的。不关的后果实测过 —— 预设判 broken、从所有选择器里消失，而设置页全绿。
+  const off = EXCLUSIVE_ROW_SETS.flatMap((set) => set.unionDefaultOff)
+  return off.length === 0 ? merged : disableRowsInPlace(merged, off)
+}
+
 /**
  * Whether a segment line declares a row id at the expected indentation.
  *
- * Nested group rows are indented four spaces in the shipped compositions, so a
- * top-level row is recognised only at column 0 and a nested one only at that
- * exact depth. Deeper indentation never carries a row id.
+ * A top-level row is recognised only at column 0. A nested row is recognised at **the indentation
+ * that level actually uses** (`indent`), not at a hard-coded depth — see {@link nestedIndent} for
+ * why that distinction is load-bearing.
  */
-function rowIdAt(line, topLevel) {
-  const pattern = topLevel ? /^- id: (.+?)\s*$/ : /^ {4}- id: (.+?)\s*$/
+function rowIdAt(line, topLevel, indent) {
+  const pattern = topLevel ? /^- id: (.+?)\s*$/ : new RegExp(`^ {${String(indent)}}- id: (.+?)\\s*$`)
   const match = pattern.exec(line)
   return match === null ? undefined : match[1].replace(/^['"]|['"]$/g, '')
 }
 
+/**
+ * The indentation a nested level actually uses, measured from its first row line.
+ *
+ * The shipped compositions indent nested rows by four spaces, and this module used to hard-code
+ * that. **YAML does not require it** — any consistent indentation is legal. Measured
+ * (`probes/probe-fuzz.mjs` T): on a file indented by two spaces, every child of a group became
+ * **invisible in the page and impossible to toggle**, while the lines were still in the file. The
+ * user sees rows they cannot reach; the file keeps rows the page denies exist.
+ *
+ * Measuring costs one pass over the level's lines and removes the assumption.
+ */
+function nestedIndent(lines) {
+  for (const line of lines) {
+    const match = /^( +)- id: /.exec(line)
+    if (match !== null) return match[1].length
+  }
+  // No nested row in this level at all: the value is never used (nothing matches), so return the
+  // shipped shape rather than inventing one.
+  return 4
+}
+
 /**
  * Split composition text into a leading preamble plus one segment per row.
  *
@@ -163,9 +340,10 @@ function rowIdAt(line, topLevel) {
  */
 function splitSegments(text, topLevel) {
   const lines = text.split('\n')
+  const indent = topLevel ? 0 : nestedIndent(lines)
   const starts = []
   for (let i = 0; i < lines.length; i += 1) {
-    const id = rowIdAt(lines[i], topLevel)
+    const id = rowIdAt(lines[i], topLevel, indent)
     if (id !== undefined) starts.push({ index: i, id })
   }
   if (starts.length === 0) return { lead: text, segments: [] }
@@ -257,24 +435,31 @@ function setDisabled(segmentText, disabled) {
   const indent = ownKeyIndent(segmentText)
   const own = disabledLineAt(indent)
   const index = lines.findIndex((line) => own.test(line))
+  // ★ 行尾必须跟着输入走。
+  //
+  // `lines` 来自 `split('\n')`，所以 CRLF 文件里每一行的末尾都还带着 `\r`。这个函数**替换**
+  // 或**插入**的行如果只以 `\n` 结尾，就会在文件里留下一个**裸 LF** —— 整个文件从此混行尾，
+  // 下一个读它的工具会看到不一致的内容（实测 `probes/probe-fuzz.mjs` R：266 个 CRLF 里混进 1 个裸 LF）。
+  // 同样的理由适用于下面两处替换：原行的 `\r` 会随替换一起丢掉。
+  const carriage = segmentText.includes('\r\n') ? '\r' : ''
   if (index !== -1) {
     const shipped = lines[index].trim().replace(/^disabled:\s*/, '')
     if (disabled) {
-      lines[index] = `${' '.repeat(indent)}disabled: true`
+      lines[index] = `${' '.repeat(indent)}disabled: true${carriage}`
     } else if (shipped.startsWith('!!js') && evalDisabledExpression(shipped) !== true) {
       // 显式打开，但出厂那行是平台表达式、且它在本机求值就是"开"：这不是覆盖，而是**撤销覆盖** ——
       // 保持出厂表达式原样，这一行就回到"跟随平台"。（原先这里删掉整行，结果是文件既不是出厂原样、
       // 也不是显式覆盖，页面却显示"未拨过" —— 文件与显示同时失真。）
       return segmentText
     } else {
-      lines[index] = `${' '.repeat(indent)}disabled: false`
+      lines[index] = `${' '.repeat(indent)}disabled: false${carriage}`
     }
     return lines.join('\n')
   }
   if (!disabled) return segmentText
   const nameIndex = lines.findIndex((line) => new RegExp(`^ {${String(indent)}}name:\\s`).test(line))
   if (nameIndex === -1) return segmentText
-  lines.splice(nameIndex + 1, 0, `${' '.repeat(indent)}disabled: true`)
+  lines.splice(nameIndex + 1, 0, `${' '.repeat(indent)}disabled: true${carriage}`)
   return lines.join('\n')
 }
 
@@ -424,12 +609,26 @@ export function collectRows(text) {
  * @param {boolean} topLevel - level selector for {@link splitSegments}.
  * @param {Map<string, boolean>} overrides - explicit per-row states.
  * @param {boolean} nested - whether this call rewrites a group's contents.
+ * @param {boolean} replacePersona - whether the persona row may be replaced wholesale.
+ * @param {Set<string>} consumed - ids already applied at this call site; see below.
  * @returns {string} the rewritten level.
  */
-function applyLevel(text, topLevel, overrides, nested, replacePersona = true) {
+function applyLevel(text, topLevel, overrides, nested, replacePersona = true, consumed = new Set()) {
   const { lead, segments } = splitSegments(text, topLevel)
   if (segments.length === 0) return text
   const rendered = segments.map((segment) => {
+    // ★ 一个 id 只作用于**第一个**匹配的行。
+    //
+    // 组成文件里出现重复 id 时（手写、或两次手术叠加），旧实现按 id 查 `overrides`，
+    // 于是两个同 id 的行**一起被改**。实测（`probes/probe-fuzz.mjs` S）：3 行
+    // （alpha, alpha, beta）里关掉 alpha 会关掉**两处** —— 用户拨的是一个开关，
+    // 文件里被改的是两处。那不是"多改了一点"，是**改了他没指的那一行**。
+    //
+    // 取第一个匹配（页面渲染的也是第一处），其余同 id 行保持原样。
+    // `consumed` 跨层共享：分组内的子行与外层同名时同理，只有第一处被改。
+    const state = consumed.has(segment.id) ? undefined : overrides.get(segment.id)
+    if (state !== undefined) consumed.add(segment.id)
+
     // The persona row is always replaced by this feature's own reader row: the
     // shipped one is a static-string persona whose text cannot be edited, so
     // keeping it would silently disable the editable prompt.
@@ -437,27 +636,32 @@ function applyLevel(text, topLevel, overrides, nested, replacePersona = true) {
     // 但"按本线修复"是**就地**手术，它必须连 persona 段里的注释都原样保留 ——
     // 之前这里无条件替换，导致每次修复都会丢注释 / 或多复制一行身份注释（外部评审实测）。
     if (!nested && segment.id === 'persona' && replacePersona === true) {
-      return setDisabled(PERSONA_ROW, overrides.get('persona'))
+      return setDisabled(PERSONA_ROW, state)
     }
     let body = segment.text
     if (nested) {
       // Nested rows: rewrite only the row's own `disabled`, never recurse.
-      return setDisabled(body, overrides.get(segment.id))
+      return setDisabled(body, state)
     }
     const isGroup = /^\s*group:\s*true\s*$/m.test(body)
     if (isGroup) {
       const children = splitSegments(body, false).segments
       if (children.length > 0) {
         // Rewrite the group's nested block, then the group's own `disabled`.
-        const cut = body.indexOf(`\n    - id: ${children[0].id}`)
+        //
+        // 缩进**用量出来的**，不是写死的 4 —— 同 {@link nestedIndent} 的理由：
+        // 写死时，缩进不是 4 格的合法组成文件里 `cut` 恒为 -1，整个分组的子行**一次都不会被重写**，
+        // 而函数照样返回一份"看起来改过了"的文本。
+        const pad = ' '.repeat(nestedIndent(body.split('\n')))
+        const cut = body.indexOf(`\n${pad}- id: ${children[0].id}`)
         if (cut !== -1) {
           const head = body.slice(0, cut + 1)
           const tail = body.slice(cut + 1)
-          body = head + applyLevel(tail, false, overrides, true)
+          body = head + applyLevel(tail, false, overrides, true, true, consumed)
         }
       }
     }
-    return setDisabled(body, overrides.get(segment.id))
+    return setDisabled(body, state)
   })
   // Empty join: each segment already carries the newline that followed it, so
   // `lead + rendered.join('')` reproduces the input byte-for-byte.
@@ -794,3 +998,77 @@ export function overridesOf(text, modeId) {
 export function extraRowIds() {
   return EXTRA_ROWS.map((extra) => extra.id)
 }
+
+/**
+ * 把一组开关调到**每组互斥里只剩一侧启用** —— 保存路径上的「自动互斥」。
+ *
+ * 为什么必须做这一步（实测 2026-10-01，`0.2.0-rc.2`）：两套壳注册同名工具，同时启用会让挂载方把整个
+ * 预设判为 **broken**，而 broken 的预设被从所有选择器里静默丢掉 —— 设置页却全绿。用户可以容忍开关
+ * 自己动一下，不能容忍模式凭空消失，所以这里替他做掉那一步，而不是事后报错。
+ *
+ * 判定的是**生效状态**（显式开关优先，否则取该基础模式的出厂态），不是"请求里带了什么"：
+ * 用户没碰过的行也该参与互斥判断。
+ *
+ * 保留哪一侧，按这个次序：
+ *  1. 这一次**被显式打开**的那一侧 —— 用户要的就是它（正常情况就落在这里）；
+ *  2. 同一次请求里显式打开了多侧（或都没显式开）⇒ 退回避让 `unionDefaultOff` 的那一侧。
+ *
+ * 只把**当前确实启用着**的行写成 `false`。给本来就关着的行写一遍，会在 `overridesOf` 里变成一条
+ * 用户从未做过的"改动"，历史和往返都会说谎。
+ *
+ * @param {string} modeId - one of {@link BASE_MODES}.
+ * @param {Map<string, boolean>} overrides - `rowId → enabled`，会被当作不可变输入。
+ * @returns {{overrides: Map<string, boolean>, moved: string[]}} 调整后的开关，以及被自动关掉的行 id。
+ * @throws {BaseCompositionUnavailableError} 取不到出厂组成时（调用方走既有的降级路径）。
+ */
+export function applyRowExclusivity(modeId, overrides) {
+  const rows = flattenRowObjects(collectRows(readBaseComposition(modeId)))
+  const effective = (id) => {
+    if (overrides.has(id)) return overrides.get(id) === true
+    const row = rows.get(id)
+    return row === undefined ? false : row.disabled !== true
+  }
+  const next = new Map(overrides)
+  const moved = []
+  for (const set of EXCLUSIVE_ROW_SETS) {
+    const live = set.sides.filter((side) => side.rows.some((id) => effective(id)))
+    if (live.length <= 1) continue
+    const explicit = live.filter((side) => side.rows.some((id) => overrides.get(id) === true))
+    const keep =
+      explicit.length === 1
+        ? explicit[0]
+        : live.find((side) => side.rows.some((id) => set.unionDefaultOff.includes(id)) === false) ?? live[0]
+    for (const side of live) {
+      if (side === keep) continue
+      for (const id of side.rows) {
+        if (effective(id)) {
+          next.set(id, false)
+          moved.push(id)
+        }
+      }
+    }
+  }
+  return { overrides: next, moved }
+}
+
+/**
+ * 一份**已经写在磁盘上**的组成有没有踩着互斥（两条路同时启用）。
+ *
+ * 保存路径已经自动避让了，所以这条只可能由三种情况命中：手工编辑、直接调 HTTP API、或者上一次是用
+ * 本插件之外的什么东西写的。它们的共同后果都是**模式从选择器里静默消失**，所以必须被点名而不是沉默。
+ *
+ * @param {string} text - an installed composition.
+ * @returns {string[]} 同时启用了多侧的互斥组 id。
+ */
+export function exclusiveSetsActive(text) {
+  const rows = flattenRowObjects(collectRows(text))
+  return EXCLUSIVE_ROW_SETS.filter((set) => {
+    const on = set.sides.filter((side) =>
+      side.rows.some((id) => {
+        const row = rows.get(id)
+        return row !== undefined && row.disabled !== true
+      }),
+    )
+    return on.length > 1
+  }).map((set) => set.id)
+}

package/index.mjs

@@ -52,9 +52,12 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { PROMPT_PATH, COMPOSITION_PATH, ROUTE_PATH, PRESET_DIR } from './paths.mjs'
 import {
+  applyRowExclusivity,
+  BASE_MODE_IDS,
   BASE_MODES,
   collectRows,
   disableRowsInPlace,
+  exclusiveSetsActive,
   isBaseCompositionUnavailable,
   modeOf,
   overridesOf,
@@ -280,9 +283,39 @@ export function configWarnings(text, prompt, meta) {
   if (find('custom-prompt-tool')?.disabled === true) warnings.push('toolOff')
   if (typeof meta?.description !== 'string' || meta.description.trim() === '') warnings.push('noDescription')
   if (typeof meta?.name !== 'string' || meta.name.trim() === '') warnings.push('noName')
+  // 两条互斥的路同时开着 ⇒ 平台会把整个模式判 broken 并**从所有选择器里静默丢弃**。
+  // 保存路径已经会自动避让（见 applyRowExclusivity），所以走到这里只可能是手工编辑、直接调 HTTP API，
+  // 或者上一次是别的工具写的 —— 三种都该被点名（"配置了却不生效"是本页明面上的承诺）。
+  if (exclusiveSetsActive(text).length > 0) warnings.push('exclusiveRowsActive')
   return warnings
 }
 
+/**
+ * 从宿主给的那条 `broken` 里抠出**行 id**。
+ *
+ * 平台把"这个预设为什么起不来"写成一行行 `<rowId> (<module>): <reason>`，例如
+ *
+ *     workflow-worker-thread (@deepseek-ai/dsh-workflow-worker-thread): never started
+ *     tool-workflow (@deepseek-ai/dsh-tool-workflow): waiting for workflowEngine
+ *
+ * 这是**唯一**能知道"是哪一行害的"的来源：`unresolvableRows()` 只答"模块装没装"，答不了
+ * "上游服务等不到"。实测（2026-10-01，官方桌面端 0.2.0-rc.2）：关掉那个装不上的引擎行之后
+ * `unresolvable` 变空、页面**全绿**，而预设**仍然 broken**（依赖引擎的两个工具在等它）——
+ * 于是用户再也走不到可用状态，模式一直不出现。见 docs/MEASUREMENTS.md §34。
+ *
+ * @param {unknown} message - the roster row's `broken` string.
+ * @returns {string[]} row ids, de-duplicated, in the order they appear.
+ */
+export function brokenRowIds(message) {
+  if (typeof message !== 'string') return []
+  const ids = []
+  for (const line of message.split('\n')) {
+    const match = /^\s*([A-Za-z0-9][A-Za-z0-9_-]*)\s+\(/.exec(line)
+    if (match !== null) ids.push(match[1])
+  }
+  return [...new Set(ids)]
+}
+
 export function readState(rows, id, options = {}) {
   const directory = assistantDir(rows, id)
   if (directory === undefined) return unknownAssistant(id)
@@ -319,6 +352,15 @@ export function readState(rows, id, options = {}) {
     if (!isBaseCompositionUnavailable(error)) throw error
     baseUnavailable = { code: error.code, params: { mode, detail: describe(error) } }
   }
+  // 宿主给的那条 broken（若这条线上有）。**必须在 return 之前算**：warnings 要用它。
+  const selfRow = Array.isArray(rows) ? rows.find((item) => item !== null && typeof item === 'object' && item.id === id) : undefined
+  const hostBroken = typeof selfRow?.broken === 'string' ? selfRow.broken.trim() : ''
+  const unresolvable = unresolvableRows(text)
+  const knownUnresolvable = new Set(unresolvable.map((row) => row.id))
+  const hostBrokenIds = brokenRowIds(hostBroken)
+  // 宿主说坏了，而我们**解释不了**（不是"模块装不上"）—— 那就要单独点名，否则页面全绿、
+  // 模式却在选择器里不出现。抠不出行 id 时（宿主换了措辞）也照样点名：宁可笼统，不可沉默。
+  const unexplainedBroken = hostBroken !== '' && (hostBrokenIds.length === 0 || hostBrokenIds.some((rowId) => knownUnresolvable.has(rowId) === false))
   return {
     ok: true,
     id,
@@ -342,7 +384,10 @@ export function readState(rows, id, options = {}) {
     history: listHistory(directory),
     // 本插件版本 + 本机装的那条 dsh 线上无法解析的行（页面据此显示版本与"按本线修复"）。
     version: PLUGIN_VERSION,
-    unresolvable: unresolvableRows(text),
+    unresolvable,
+    // 宿主自己给的「这个预设为什么起不来」原文。它比 `unresolvable` 宽：除了"模块装不上"，
+    // 还包括"上游服务等不到"这类**装配期**失败。页面据此点名，而不是在坏着的时候显示全绿。
+    broken: hostBroken === '' ? null : hostBroken,
     // 「配置了却不生效」的告警码（文案在页面侧按语言渲染）。
     warnings: [
       ...configWarnings(text, prompt.ok === true ? prompt.text : '', meta),
@@ -350,7 +395,11 @@ export function readState(rows, id, options = {}) {
       // 诚实地把它变成页面上的告警，而不是只留在 console.error 里。
       ...(existsSync(join(directory, 'approval-gate-missing')) ? ['approvalGateMissing'] : []),
       // 本线无法解析的启用行 = 平台会把整个预设判为 broken 并从选择器里丢掉（曾经的 P0）。
-      ...(unresolvableRows(text).length > 0 ? ['unresolvableRows'] : []),
+      ...(unresolvable.length > 0 ? ['unresolvableRows'] : []),
+      // ★ 宿主报了 broken，而**我们自己的检查解释不了**（不是"模块装不上"，而是"服务等不到"之类）。
+      //   不点名的话，页面上 `unresolvable` 空、告警空 —— 一切看起来正常，而模式**根本没出现在
+      //   选择器里**。这正是本仓记录过两次的那种"静默失败"，只是换了个触发面。
+      ...(unexplainedBroken ? ['presetBroken'] : []),
       // 出厂组成取不到：提示词能改，基础模式与插件开关不能。
       ...(baseUnavailable === null ? [] : ['baseCompositionUnavailable']),
     ],
@@ -488,6 +537,20 @@ export function saveState(rows, input) {
     }
   }
 
+  // ★ 自动互斥（见 applyRowExclusivity 的实测依据）：两套壳注册同名工具，同时启用会让平台把整个模式
+  //   判 broken，并**从所有选择器里静默丢掉** —— 设置页却全绿。开关自己动一下用户能接受，模式凭空
+  //   消失不能，所以这里替他做掉那一步，并在响应里如实说出被关掉的是哪几行。
+  //   取不到出厂组成时会抛：交给下面同一条降级路径，不额外编一套错误。
+  let autoOff = []
+  try {
+    const adjusted = applyRowExclusivity(mode, overrides)
+    autoOff = adjusted.moved
+    overrides.clear()
+    for (const [rowId, enabled] of adjusted.overrides) overrides.set(rowId, enabled)
+  } catch (error) {
+    if (!isBaseCompositionUnavailable(error)) throw error
+  }
+
   let composition
   try {
     composition = renderComposition(mode, overrides, { modeName: effectiveName, assistantId: id })
@@ -551,13 +614,27 @@ export function saveState(rows, input) {
     /* 审计记录失败不影响保存本身 */
   }
 
+  const displayName = effectiveName === '' ? id : effectiveName
+  if (autoOff.length > 0) {
+    return {
+      ok: true,
+      id,
+      mode,
+      code: 'savedWithExclusiveRows',
+      // `rows` 用行 id：页面自己按 `row.<id>.label` 渲染，英文界面不会因为这条掉回中文。
+      params: { name: displayName, mode, rows: autoOff.join(', ') },
+      note:
+        '已保存（' + displayName + '，基础模式 ' + mode + '）。这两套壳注册同名工具、不能同时启用 —— ' +
+        '已自动关掉：' + autoOff.join('、') + '。新建会话即生效，当前会话保持原配置。',
+    }
+  }
   return {
     ok: true,
     id,
     mode,
     code: 'saved',
-    params: { name: effectiveName === '' ? id : effectiveName, mode },
-    note: '已保存（' + (name === '' ? id : name) + '，基础模式 ' + mode + '）。新建会话即生效，当前会话保持原配置。',
+    params: { name: displayName, mode },
+    note: '已保存（' + displayName + '，基础模式 ' + mode + '）。新建会话即生效，当前会话保持原配置。',
   }
 }
 
@@ -627,10 +704,28 @@ export function createAssistant(rows, input, templateDir = packagedPresetDir())
     }
     const sourceMode = modeOf(text)
     const sourcePrompt = readPrompt(fromDir)
+    // 与上面组成文件**同一条纪律**：源提示词读不出来时返回类型化错误，不要静默用空串。
+    //
+    // 实测（`probes/probe-io.mjs` N）：旧代码写 `sourcePrompt.ok === true ? sourcePrompt.text : ''`，
+    // 于是一次复制会返回 `ok / duplicated`，而新助手的 `prompt.md` 长度是 **0** ——
+    // 用户以为自己复制出了一个助手，实际拿到的是**空的系统提示词**，而源里那份提示词还好端端躺着。
+    // 保存路径有 `promptEmpty` 这道闸，复制路径没有；这个不对称就是缺陷本身。
+    //
+    // `readPrompt` 的失败形状已经是带 code 的类型化错误（页面按词典渲染），所以直接透传。
+    if (sourcePrompt.ok !== true) return sourcePrompt
+    // 复制走的是"照抄源助手的开关再重渲染"，所以源里若踩着互斥，抄过来还是踩 —— 与保存路径同一条
+    // 自动避让（见 applyRowExclusivity）。不这么做的话，从这里能造出一个**必然 broken** 的新助手，
+    // 而 broken 的模式会被静默丢掉。取不到出厂组成时保持原样：渲染那一步会走既有的降级/自检。
+    let sourceOverrides = overridesOf(text, sourceMode)
+    try {
+      sourceOverrides = Object.fromEntries(applyRowExclusivity(sourceMode, new Map(Object.entries(sourceOverrides))).overrides)
+    } catch (error) {
+      if (!isBaseCompositionUnavailable(error)) throw error
+    }
     source = {
       mode: sourceMode,
-      overrides: overridesOf(text, sourceMode),
-      prompt: sourcePrompt.ok === true ? sourcePrompt.text : '',
+      overrides: sourceOverrides,
+      prompt: sourcePrompt.text,
       description: readPresetMeta(fromDir).description,
     }
   }
@@ -709,9 +804,30 @@ export function repairComposition(rows, input) {
   const file = compositionFile(directory)
   if (!existsSync(file)) return { ok: false, code: 'compositionMissing', params: { path: file }, error: '找不到组成文件：' + file }
   const text = readFileSync(file, 'utf8')
-  const bad = unresolvableRows(text)
+  // 两类"这一行在本机起不来"，必须**都**关掉：
+  //  ① 模块装不上 —— 我们自己在 node_modules 里查得出来（`unresolvableRows`）；
+  //  ② 装配期失败（"服务等不到"之类）—— 只有宿主知道，写在它给的 `broken` 里。
+  // 只修 ① 会留下一个**页面全绿、预设却仍然 broken**的状态（桌面端实测，见 brokenRowIds 的注释）：
+  // `unresolvable` 变空 ⇒ 告警消失 ⇒ 用户以为修好了，而模式始终没出现在选择器里。
+  const selfRow = Array.isArray(rows) ? rows.find((item) => item !== null && typeof item === 'object' && item.id === id) : undefined
+  // 只关**这份文本里真的有**的行：宿主报的可能是别处的行，而 `disableRowsInPlace` 对不存在的 id
+  // 是无操作 —— 计数会因此说谎（说关了 3 个其实只关了 1 个）。
+  const present = new Set()
+  const collectIds = (list) => {
+    for (const row of list) {
+      present.add(row.id)
+      if (Array.isArray(row.children)) collectIds(row.children)
+    }
+  }
+  try {
+    collectIds(collectRows(text))
+  } catch {
+    /* 文本解析不了就只按 unresolvableRows 走（它自己会兜底） */
+  }
+  const wanted = [...new Set([...unresolvableRows(text).map((row) => row.id), ...brokenRowIds(selfRow?.broken)])]
+  const bad = wanted.map((rowId) => ({ id: rowId })).filter((row) => present.has(row.id))
   if (bad.length === 0) {
-    return { ok: true, id, code: 'repairNotNeeded', note: '这个助手在本机没有无法解析的行，无需修复。' }
+    return { ok: true, id, code: 'repairNotNeeded', note: '这个助手在本机没有起不来的行，无需修复。' }
   }
   // **就地**关闭那几行，不重渲染：重渲染会顺手丢掉 base 之外的自有行，而用户的数据不该被这样动。
   const rendered = disableRowsInPlace(text, bad.map((row) => row.id))
@@ -729,7 +845,7 @@ export function repairComposition(rows, input) {
     // 草稿，否则下一次保存会按草稿重渲染，把刚才的修复原样撤销（issue #8 实测：
     // 修复写进了磁盘，但草稿里那几行仍是启用的，于是保存后 ghost 行又回来了）。
     params: { count: bad.length, ids, repairedIds: bad.map((row) => row.id) },
-    note: '已按本机这条 dsh 线关闭 ' + String(bad.length) + ' 个无法解析的行（' + ids + '）。现在这个模式能重新出现在选择器里。',
+    note: '已按本机这条 dsh 线关闭 ' + String(bad.length) + ' 个起不来的行（' + ids + '）。现在这个模式能重新出现在选择器里。',
   }
 }
 
@@ -984,7 +1100,9 @@ export function apply(ctx) {
       // 降级路径。两种情况都不阻塞下面的注册表同步 —— 模式可用优先于设置页完整。
       if (declarative !== null) {
         try {
-          const bases = await declarative.fetchBaseCompositions(BASE_MODES.map((mode) => mode.id))
+          // 只问**出厂那四位**：并集模式（BASE_MODES 的第五项）在宿主那里没有文档，
+          // 拿它去 readDocument 只会每次都换来一条"取不到"的错误日志，把真正的故障淹没掉。
+          const bases = await declarative.fetchBaseCompositions(BASE_MODE_IDS)
           setBaseCompositions(bases.fetched)
           if (bases.fetched.size > 0) {
             console.log(