dsh-prompt-customizer 0.4.0 → 0.4.2

package/cordis.patch.yml

@@ -1,9 +1,9 @@
-# dsh-prompt-customizer bundle patch: inserts the dual-face plugin row into
-# the web profile roster. Applied as a profile bundle layer (the
-# `dsh.bundle.patch` manifest field). The node half (exports ".") runs in the
-# host process (settings namespace, prompt/tool filtering, inventory route);
-# the `dsh.client` declaration in package.json loads the browser half
-# (exports "./client", served at /plugins/prompt-customizer/client.js).
-- insert:
-    - id: prompt-customizer
+# dsh-prompt-customizer bundle patch: inserts the dual-face plugin row into
+# the web profile roster. Applied as a profile bundle layer (the
+# `dsh.bundle.patch` manifest field). The node half (exports ".") runs in the
+# host process (settings namespace, prompt/tool filtering, inventory route);
+# the `dsh.client` declaration in package.json loads the browser half
+# (exports "./client", served at /plugins/prompt-customizer/client.js).
+- insert:
+    - id: prompt-customizer
       name: 'dsh-prompt-customizer'

package/lib/catalog.js

@@ -1,131 +1,131 @@
-/**
- * 「本系统全部提示词 / 全部工具」的累积登记表 —— `catalog.yaml`。
- *
- * 段与工具都挂在各 agent 预设自己的 scope 里，要看到某个预设独有的名字必须先
- * 挂载它（`standingKeyFor` 组装整棵插件树，单个可慢到十几秒）。清单面板要的却是
- * 「不随编辑目标切换、只增不减」的全景，所以这里不做全量预热，而是懒式累积：
- * 每次为任一 scope 构建清单 / 预览，就把这次真正看到的段与工具并进登记表 ——
- * 同名后见到者赢，新名追加，绝不因为切换预设而变少。
- *
- * 文件只是派生缓存：删掉它会随浏览重新长出来，不含任何用户配置。因此登记表只存
- * 身份与内容（段名 / 顺序 / 文本，工具名 / 描述），**不存**屏蔽、替换、隐藏这类
- * 按作用域计算的标记 —— 那些永远在响应时按当前生效配置现算。
- */
-
-import path from 'node:path'
-import { createConfigStore } from './store.js'
-
-/** 只取已定义字段，避免 `{...旧, ...新}` 用 undefined 把旧值抹成空洞。 */
-function definedFields(item) {
-  const patch = {}
-  for (const [key, value] of Object.entries(item)) {
-    if (value !== undefined) patch[key] = value
-  }
-  return patch
-}
-
-function isName(value) {
-  return typeof value === 'string' && value.length > 0
-}
-
-/**
- * 把一次所见并进已有名单：同名覆盖（后见到者赢，保持原有位置），新名追加。
- * `orderOf` 给缺少 order 的新条目补一个稳定下标（工具池不需要）。
- * 返回 `{ list, changed }` —— changed 为 false 时调用方可以不落盘。
- */
-export function mergeSighting(prev, sighting, orderOf = null) {
-  const list = (Array.isArray(prev) ? prev : []).map((item) => ({ ...item }))
-  const index = new Map(list.map((item, i) => [item?.name, i]))
-  let changed = false
-  for (const raw of Array.isArray(sighting) ? sighting : []) {
-    if (raw === null || typeof raw !== 'object' || !isName(raw.name)) continue
-    const at = index.get(raw.name)
-    if (at === undefined) {
-      const next = { ...raw }
-      if (orderOf !== null && next.order === undefined) next.order = orderOf(list, next)
-      index.set(raw.name, list.length)
-      list.push(next)
-      changed = true
-      continue
-    }
-    const patch = definedFields(raw)
-    const merged = { ...list[at], ...patch }
-    if (JSON.stringify(merged) === JSON.stringify(list[at])) continue
-    list[at] = merged
-    changed = true
-  }
-  return { list, changed }
-}
-
-/** 创建一个累积登记表。`dir` 与配置文件同目录；读不到 / 坏文件一律从空开始。 */
-export function createCatalog({ dir, file, warn } = {}) {
-  const target = file ?? path.join(dir ?? '.', 'catalog.yaml')
-  const store = createConfigStore({
-    file: target,
-    warn,
-    header: '# dsh-prompt-customizer 段 / 工具累积登记表（派生缓存，非配置）。\n'
-      + '# 由面板浏览各 agent 预设时自动累积；删掉本文件会随下次浏览重新长出来。\n',
-  })
-
-  /** 归一化磁盘内容：只认数组里的具名条目，段保留 order / text。 */
-  const normalize = (raw, kind) => {
-    const list = Array.isArray(raw) ? raw : []
-    if (kind === 'sections') {
-      return list
-        .filter((x) => x !== null && typeof x === 'object' && isName(x.name))
-        .map((x) => ({ name: x.name, order: typeof x.order === 'number' ? x.order : undefined, text: typeof x.text === 'string' ? x.text : '' }))
-        .map((x) => (x.order === undefined ? { name: x.name, text: x.text } : { name: x.name, order: x.order, text: x.text }))
-    }
-    return list
-      .filter((x) => x !== null && typeof x === 'object' && isName(x.name))
-      .map((x) => ({ name: x.name, description: typeof x.description === 'string' ? x.description : '' }))
-  }
-
-  const load = () => {
-    let doc
-    try { doc = store.readResolved() ?? {} } catch { doc = {} }
-    return {
-      sections: normalize(doc.sections, 'sections'),
-      tools: normalize(doc.tools, 'tools'),
-    }
-  }
-
-  let state = load()
-
-  return {
-    /** 当前并集（按登记顺序；调用方自己现算标记与排序）。 */
-    read() {
-      return { sections: state.sections.map((x) => ({ ...x })), tools: state.tools.map((x) => ({ ...x })) }
-    },
-
-    /**
-     * 并进一次所见。段的 order 只在所见提供时才更新（预览路径没有 order，
-     * 不该把已知顺序打乱）；新段用「当前最大 order + 1」落位，保持追加在尾部。
-     */
-    observe({ sections = [], tools = [] } = {}) {
-      // 与 config.yaml 同构的语义：外部编辑 / 删除即时生效（store 是 mtime 懒
-      // 加载的，这里取一次最新状态再合并）。否则删掉本文件后，内存里的旧池子
-      // 会在下次请求被原样写回来，「删掉随浏览重建」就成了假话。
-      state = load()
-      let changed = false
-      const nextOrder = (list) => {
-        let max = -1
-        for (const item of list) if (typeof item.order === 'number' && item.order > max) max = item.order
-        return max + 1
-      }
-      const mergedSections = mergeSighting(state.sections, sections, (list) => nextOrder(list))
-      if (mergedSections.changed) { state.sections = mergedSections.list; changed = true }
-      const mergedTools = mergeSighting(state.tools, tools)
-      if (mergedTools.changed) { state.tools = mergedTools.list; changed = true }
-      if (!changed) return false
-      // 落盘失败只影响缓存持久性，绝不让清单 / 预览请求失败。
-      try { store.writeSection(state) } catch (error) {
-        try { warn?.(`prompt-customizer: catalog.yaml 写入失败（本次仅内存累积）：${String(error && error.message ? error.message : error)}`) } catch { /* logger 缺席 */ }
-      }
-      return true
-    },
-
-    /** 测试 / 排查用：重新从磁盘读一次。 */
-    reload() { state = load(); return state },
-  }
-}
+/**
+ * 「本系统全部提示词 / 全部工具」的累积登记表 —— `catalog.yaml`。
+ *
+ * 段与工具都挂在各 agent 预设自己的 scope 里，要看到某个预设独有的名字必须先
+ * 挂载它（`standingKeyFor` 组装整棵插件树，单个可慢到十几秒）。清单面板要的却是
+ * 「不随编辑目标切换、只增不减」的全景，所以这里不做全量预热，而是懒式累积：
+ * 每次为任一 scope 构建清单 / 预览，就把这次真正看到的段与工具并进登记表 ——
+ * 同名后见到者赢，新名追加，绝不因为切换预设而变少。
+ *
+ * 文件只是派生缓存：删掉它会随浏览重新长出来，不含任何用户配置。因此登记表只存
+ * 身份与内容（段名 / 顺序 / 文本，工具名 / 描述），**不存**屏蔽、替换、隐藏这类
+ * 按作用域计算的标记 —— 那些永远在响应时按当前生效配置现算。
+ */
+
+import path from 'node:path'
+import { createConfigStore } from './store.js'
+
+/** 只取已定义字段，避免 `{...旧, ...新}` 用 undefined 把旧值抹成空洞。 */
+function definedFields(item) {
+  const patch = {}
+  for (const [key, value] of Object.entries(item)) {
+    if (value !== undefined) patch[key] = value
+  }
+  return patch
+}
+
+function isName(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+/**
+ * 把一次所见并进已有名单：同名覆盖（后见到者赢，保持原有位置），新名追加。
+ * `orderOf` 给缺少 order 的新条目补一个稳定下标（工具池不需要）。
+ * 返回 `{ list, changed }` —— changed 为 false 时调用方可以不落盘。
+ */
+export function mergeSighting(prev, sighting, orderOf = null) {
+  const list = (Array.isArray(prev) ? prev : []).map((item) => ({ ...item }))
+  const index = new Map(list.map((item, i) => [item?.name, i]))
+  let changed = false
+  for (const raw of Array.isArray(sighting) ? sighting : []) {
+    if (raw === null || typeof raw !== 'object' || !isName(raw.name)) continue
+    const at = index.get(raw.name)
+    if (at === undefined) {
+      const next = { ...raw }
+      if (orderOf !== null && next.order === undefined) next.order = orderOf(list, next)
+      index.set(raw.name, list.length)
+      list.push(next)
+      changed = true
+      continue
+    }
+    const patch = definedFields(raw)
+    const merged = { ...list[at], ...patch }
+    if (JSON.stringify(merged) === JSON.stringify(list[at])) continue
+    list[at] = merged
+    changed = true
+  }
+  return { list, changed }
+}
+
+/** 创建一个累积登记表。`dir` 与配置文件同目录；读不到 / 坏文件一律从空开始。 */
+export function createCatalog({ dir, file, warn } = {}) {
+  const target = file ?? path.join(dir ?? '.', 'catalog.yaml')
+  const store = createConfigStore({
+    file: target,
+    warn,
+    header: '# dsh-prompt-customizer 段 / 工具累积登记表（派生缓存，非配置）。\n'
+      + '# 由面板浏览各 agent 预设时自动累积；删掉本文件会随下次浏览重新长出来。\n',
+  })
+
+  /** 归一化磁盘内容：只认数组里的具名条目，段保留 order / text。 */
+  const normalize = (raw, kind) => {
+    const list = Array.isArray(raw) ? raw : []
+    if (kind === 'sections') {
+      return list
+        .filter((x) => x !== null && typeof x === 'object' && isName(x.name))
+        .map((x) => ({ name: x.name, order: typeof x.order === 'number' ? x.order : undefined, text: typeof x.text === 'string' ? x.text : '' }))
+        .map((x) => (x.order === undefined ? { name: x.name, text: x.text } : { name: x.name, order: x.order, text: x.text }))
+    }
+    return list
+      .filter((x) => x !== null && typeof x === 'object' && isName(x.name))
+      .map((x) => ({ name: x.name, description: typeof x.description === 'string' ? x.description : '' }))
+  }
+
+  const load = () => {
+    let doc
+    try { doc = store.readResolved() ?? {} } catch { doc = {} }
+    return {
+      sections: normalize(doc.sections, 'sections'),
+      tools: normalize(doc.tools, 'tools'),
+    }
+  }
+
+  let state = load()
+
+  return {
+    /** 当前并集（按登记顺序；调用方自己现算标记与排序）。 */
+    read() {
+      return { sections: state.sections.map((x) => ({ ...x })), tools: state.tools.map((x) => ({ ...x })) }
+    },
+
+    /**
+     * 并进一次所见。段的 order 只在所见提供时才更新（预览路径没有 order，
+     * 不该把已知顺序打乱）；新段用「当前最大 order + 1」落位，保持追加在尾部。
+     */
+    observe({ sections = [], tools = [] } = {}) {
+      // 与 config.yaml 同构的语义：外部编辑 / 删除即时生效（store 是 mtime 懒
+      // 加载的，这里取一次最新状态再合并）。否则删掉本文件后，内存里的旧池子
+      // 会在下次请求被原样写回来，「删掉随浏览重建」就成了假话。
+      state = load()
+      let changed = false
+      const nextOrder = (list) => {
+        let max = -1
+        for (const item of list) if (typeof item.order === 'number' && item.order > max) max = item.order
+        return max + 1
+      }
+      const mergedSections = mergeSighting(state.sections, sections, (list) => nextOrder(list))
+      if (mergedSections.changed) { state.sections = mergedSections.list; changed = true }
+      const mergedTools = mergeSighting(state.tools, tools)
+      if (mergedTools.changed) { state.tools = mergedTools.list; changed = true }
+      if (!changed) return false
+      // 落盘失败只影响缓存持久性，绝不让清单 / 预览请求失败。
+      try { store.writeSection(state) } catch (error) {
+        try { warn?.(`prompt-customizer: catalog.yaml 写入失败（本次仅内存累积）：${String(error && error.message ? error.message : error)}`) } catch { /* logger 缺席 */ }
+      }
+      return true
+    },
+
+    /** 测试 / 排查用：重新从磁盘读一次。 */
+    reload() { state = load(); return state },
+  }
+}

package/lib/effective.js

@@ -1,158 +1,161 @@
-/**
- * 字段级 override 合并（方案 A）+ 阶段过滤（方案 C）。
- *
- * 合并语义：override 中**存在的字段整体接管**全局默认；空缺的字段回落
- * 全局。replace / inject / tools 沿用「非空才接管」（空对象 / 空列表视同
- * 未设置）；三份段屏蔽名单（sections / sectionsBootstrap / sectionsCompaction）
- * 例外 —— **空数组 = 显式接管为空**（用户在该预设下解除全部屏蔽，绝不能
- * 回落全局把屏蔽「复活」；客户端 editView 的 `??` 语义与此一致）。
- */
-
-/** 非空数组才视为有效覆盖值（inject 用；屏蔽名单不适用，见上）。 */
-function hasList(value) {
-  return Array.isArray(value) && value.length > 0
-}
-
-/** 非空对象（至少一个键）才视为有效覆盖值。 */
-function hasDict(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0
-}
-
-/** 工具配置整体是否携带至少一条有效规则（含 bootstrap / compaction 目录，
- *  exclude 或 add 任一非空即算）。 */
-function hasTools(tools) {
-  if (tools === null || typeof tools !== 'object') return false
-  return hasList(tools.exclude) || hasList(tools.add) || hasTools(tools.bootstrap) || hasTools(tools.compaction)
-}
-
-/**
- * 字段级合并出一份生效配置。replace / inject / tools 看非空；三份段屏蔽
- * 名单看「字段是否存在」（空数组 = 显式接管为空，不回落全局）。
- */
-export function mergeConfig(globalCfg, ovr) {
-  const g = globalCfg ?? {}
-  return {
-    sections: Array.isArray(ovr?.sections) ? ovr.sections : (g.sections ?? []),
-    sectionsBootstrap: Array.isArray(ovr?.sectionsBootstrap) ? ovr.sectionsBootstrap : (g.sectionsBootstrap ?? []),
-    sectionsCompaction: Array.isArray(ovr?.sectionsCompaction) ? ovr.sectionsCompaction : (g.sectionsCompaction ?? []),
-    replace: hasDict(ovr?.replace) ? ovr.replace : (g.replace ?? {}),
-    inject: hasList(ovr?.inject) ? ovr.inject : (g.inject ?? []),
-    tools: hasTools(ovr?.tools) ? ovr.tools : (g.tools ?? {}),
-  }
-}
-
-/**
- * 选出当前阶段生效的注入段：常驻期注入（`always`）始终注入；其余注入按
- * 阶段模式匹配 —— bootstrap（未晋级）→ `bootstrap`，active（已晋级）→
- * `active`，compact（压缩后仍未晋级）→ `compaction`。每个阶段的注入集
- * 互相独立（各自的 order 空间），用于「每阶段独立名单 + 虚拟 order」。
- * 传入 `status`（promotion.status() 结果 `{ promoted, boundary }`），
- * 不再沿用旧的布尔 promoted（旧的 compaction 窗口被硬塞进 bootstrap 期，
- * 无法独立排序）。
- */
-export function filterInjectByPhase(injectList, status) {
-  const mode = status.promoted ? 'active' : status.boundary >= 0 ? 'compaction' : 'bootstrap'
-  return (injectList ?? []).filter((item) => {
-    const phase = item.phase === 'bootstrap' || item.phase === 'active' || item.phase === 'compaction' ? item.phase : 'always'
-    return phase === 'always' || phase === mode
-  })
-}
-
-/**
- * 选出当前阶段生效的工具过滤配置（三态）：三个阶段**各用自己那份名单，互不
- * 继承** —— 已晋级 → 静态 `exclude`，未晋级 → `bootstrap.exclude`，压缩后仍未
- * 晋级 → `compaction.exclude`；空名单就表示「该阶段什么都不隐藏」。
- *
- * 早期版本让阶段名单在为空时回落静态字段，看起来省了一份重复配置，实际是拿
- * 走了阶段独立性：界面按三个阶段分别勾选，而引导期的勾选状态既反映不了静态
- * 名单里已隐藏的工具（显示成"可见"、模型其实看不见），往引导期名单里加一项又
- * 会让整个静态名单在该阶段失效（其它工具的隐藏一起蒸发）。
- * `status` 是 promotion.status() 的结果 `{ promoted, boundary }`。
- */
-export function pickToolsFilter(toolsCfg, status) {
-  if (!status.promoted) {
-    if (status.boundary >= 0) {
-      return { exclude: toolsCfg?.compaction?.exclude ?? [], add: toolsCfg?.compaction?.add ?? [] }
-    }
-    return { exclude: toolsCfg?.bootstrap?.exclude ?? [], add: toolsCfg?.bootstrap?.add ?? [] }
-  }
-  return { exclude: toolsCfg?.exclude ?? [], add: toolsCfg?.add ?? [] }
-}
-
-/**
- * 黑名单过滤（装配钩子与 inventory 共用）：把 `exclude` 里的工具从目录里拿掉。
- *
- * 刻意不支持「白名单 / 封闭式允许清单」：include 一旦生效就让 exclude 完全失效，
- * 而且它会把目录冻结在点名的几个上 —— 别的插件以后新增的工具一律看不见。「只留
- * 这几个」用 exclude 反选即可，无需第二套语义。
- *
- * 「把被裁掉但注册表里仍有的工具加回该阶段」是另一条独立通道（`add` 名单），由
- * 装配钩子在过滤**之后**从注册表查回 schema 追加 —— 见 lib/index.js，不在这里。
- */
-export function applyToolFilter(tools, { exclude }) {
-  const excludeSet = new Set(exclude ?? [])
-  if (excludeSet.size > 0) return tools.filter((tool) => !excludeSet.has(tool.name))
-  return tools
-}
-
-/**
- * 每阶段独立段屏蔽（与工具目录三态对称）：压缩受控期在「压缩后仍未晋级」
- * 时生效且优先于引导期；引导期在未晋级时生效；否则回落常驻期（全局
- * `sections`，列表为空表示不启用阶段化）。返回该阶段额外屏蔽的段名。
- */
-export function pickSectionsForStatus(config, status) {
-  const compaction = config?.sectionsCompaction
-  const bootstrap = config?.sectionsBootstrap
-  if (!status.promoted && status.boundary >= 0 && Array.isArray(compaction) && compaction.length > 0) return compaction
-  if (!status.promoted && Array.isArray(bootstrap) && bootstrap.length > 0) return bootstrap
-  return []
-}
-
-/**
- * 段级策略：屏蔽 → 替换 → 注入 → 排序，作用于任意来源的基础段列表。
- *
- * 瀑布流装配与 assemble 强制覆盖（forceSections）共用同一份实现 —— 输入
- * `baseSections` 可以是瀑布流里其它插件过滤后的段，也可以是注册表
- * `layers.merge()` 的原始段定义。后一种输入就是「以本插件为准」的关键：
- * 预设插件的阶段裁段与宿主的 complete 整段接管都发生在瀑布流内/后，
- * 而强制覆盖在方法边界用这份原始定义重建 sections，前两者再无机会改写。
- * 条目只需 { name, text }；order 在映射时按数组序补上（与注册表顺序一致），
- * 保证稳定排序，与注入段的虚拟 order 空间一致。
- */
-export function applySectionPolicy(baseSections, cfg, status) {
-  const denied = new Set([...(cfg.sections ?? []), ...pickSectionsForStatus(cfg, status)])
-  const replace = cfg.replace ?? {}
-  const injectList = filterInjectByPhase(cfg.inject, status)
-  let sections = baseSections
-    .filter((section) => !denied.has(section.name))
-    .map((section, i) =>
-      Object.hasOwn(replace, section.name) ? { ...section, order: i, text: replace[section.name] } : { ...section, order: i },
-    )
-  for (const item of injectList) {
-    // 被屏蔽的段直接跳过 —— 上面已经把它们过滤掉了。
-    if (denied.has(item.name)) continue
-    const index = sections.findIndex((section) => section.name === item.name)
-    if (index >= 0) {
-      // 已存在的段：覆盖 order 来控制拼接顺序。文本按「本阶段注入文本 → 该
-      // 段当前文本」取（后者可能已被全局 replace 改过）—— injectList 已经按
-      // 阶段筛过，所以带 phase 的文本只作用在本阶段，三个阶段各改各的；全局
-      // replace 字典是跨阶段的（旧语义），只在没有阶段文本时生效。
-      sections[index] = {
-        ...sections[index],
-        text: item.text ? item.text : sections[index].text,
-        order: item.order,
-      }
-    } else if (item.custom === true || Object.hasOwn(replace, item.name) || item.text) {
-      // 装配里没有这个名字：只有「本插件自撰的 custom 段」「被替换的段」
-      // 「自带文本的注入段」才允许新建条目。只带 order 的空文本系统名必须
-      // 跳过 —— 它通常来自快照里混进的别的预设独有段名（并集池会带回来），
-      // 新建就变成一条空白幽灵段，实打实进最终提示词。
-      sections.push({ name: item.name, order: item.order, text: item.text || replace[item.name] })
-    }
-  }
-  // 虚拟 order 排序：order 缺省按 0，稳定排序保持系统段原始相对顺序；
-  // 注入段携带各自的 order（120+ 落在系统段之后，或被重排到任意断点），
-  // 以 order 升序决定注入顺序 —— 与「每阶段独立名单」配合即每阶段独立序。
-  sections.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
-  return sections
-}
+/**
+ * 字段级 override 合并（方案 A）+ 阶段过滤（方案 C）。
+ *
+ * 合并语义：override 中**存在的字段整体接管**全局默认；空缺的字段回落
+ * 全局。replace / inject / tools 沿用「非空才接管」（空对象 / 空列表视同
+ * 未设置）；三份段屏蔽名单（sections / sectionsBootstrap / sectionsCompaction）
+ * 例外 —— **空数组 = 显式接管为空**（用户在该预设下解除全部屏蔽，绝不能
+ * 回落全局把屏蔽「复活」；客户端 editView 的 `??` 语义与此一致）。
+ */
+
+/** 非空数组才视为有效覆盖值（inject 用；屏蔽名单不适用，见上）。 */
+function hasList(value) {
+  return Array.isArray(value) && value.length > 0
+}
+
+/** 非空对象（至少一个键）才视为有效覆盖值。 */
+function hasDict(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0
+}
+
+/** 工具配置整体是否携带至少一条有效规则（含 bootstrap / compaction 目录，
+ *  exclude 或 add 任一非空即算）。 */
+function hasTools(tools) {
+  if (tools === null || typeof tools !== 'object') return false
+  return hasList(tools.exclude) || hasList(tools.add) || hasTools(tools.bootstrap) || hasTools(tools.compaction)
+}
+
+/**
+ * 字段级合并出一份生效配置。replace / inject / tools 看非空；三份段屏蔽
+ * 名单看「字段是否存在」（空数组 = 显式接管为空，不回落全局）。
+ */
+export function mergeConfig(globalCfg, ovr) {
+  const g = globalCfg ?? {}
+  return {
+    sections: Array.isArray(ovr?.sections) ? ovr.sections : (g.sections ?? []),
+    sectionsBootstrap: Array.isArray(ovr?.sectionsBootstrap) ? ovr.sectionsBootstrap : (g.sectionsBootstrap ?? []),
+    sectionsCompaction: Array.isArray(ovr?.sectionsCompaction) ? ovr.sectionsCompaction : (g.sectionsCompaction ?? []),
+    replace: hasDict(ovr?.replace) ? ovr.replace : (g.replace ?? {}),
+    inject: hasList(ovr?.inject) ? ovr.inject : (g.inject ?? []),
+    tools: hasTools(ovr?.tools) ? ovr.tools : (g.tools ?? {}),
+  }
+}
+
+/**
+ * 选出当前阶段生效的注入段：常驻期注入（`always`）始终注入；其余注入按
+ * 阶段模式匹配 —— bootstrap（未晋级）→ `bootstrap`，active（已晋级）→
+ * `active`，compact（压缩后仍未晋级）→ `compaction`。每个阶段的注入集
+ * 互相独立（各自的 order 空间），用于「每阶段独立名单 + 虚拟 order」。
+ * 传入 `status`（promotion.status() 结果 `{ promoted, boundary }`），
+ * 不再沿用旧的布尔 promoted（旧的 compaction 窗口被硬塞进 bootstrap 期，
+ * 无法独立排序）。
+ */
+export function filterInjectByPhase(injectList, status) {
+  const mode = status.promoted ? 'active' : status.boundary >= 0 ? 'compaction' : 'bootstrap'
+  return (injectList ?? []).filter((item) => {
+    const phase = item.phase === 'bootstrap' || item.phase === 'active' || item.phase === 'compaction' ? item.phase : 'always'
+    return phase === 'always' || phase === mode
+  })
+}
+
+/**
+ * 选出当前阶段生效的工具过滤配置（三态）：三个阶段**各用自己那份名单，互不
+ * 继承** —— 已晋级 → 静态 `exclude`，未晋级 → `bootstrap.exclude`，压缩后仍未
+ * 晋级 → `compaction.exclude`；空名单就表示「该阶段什么都不隐藏」。
+ *
+ * 早期版本让阶段名单在为空时回落静态字段，看起来省了一份重复配置，实际是拿
+ * 走了阶段独立性：界面按三个阶段分别勾选，而引导期的勾选状态既反映不了静态
+ * 名单里已隐藏的工具（显示成"可见"、模型其实看不见），往引导期名单里加一项又
+ * 会让整个静态名单在该阶段失效（其它工具的隐藏一起蒸发）。
+ * `status` 是 promotion.status() 的结果 `{ promoted, boundary }`。
+ */
+export function pickToolsFilter(toolsCfg, status) {
+  if (!status.promoted) {
+    if (status.boundary >= 0) {
+      return { exclude: toolsCfg?.compaction?.exclude ?? [], add: toolsCfg?.compaction?.add ?? [] }
+    }
+    return { exclude: toolsCfg?.bootstrap?.exclude ?? [], add: toolsCfg?.bootstrap?.add ?? [] }
+  }
+  return { exclude: toolsCfg?.exclude ?? [], add: toolsCfg?.add ?? [] }
+}
+
+/**
+ * 黑名单过滤（装配钩子与 inventory 共用）：把 `exclude` 里的工具从目录里拿掉。
+ *
+ * 刻意不支持「白名单 / 封闭式允许清单」：include 一旦生效就让 exclude 完全失效，
+ * 而且它会把目录冻结在点名的几个上 —— 别的插件以后新增的工具一律看不见。「只留
+ * 这几个」用 exclude 反选即可，无需第二套语义。
+ *
+ * 「把被裁掉但注册表里仍有的工具加回该阶段」是另一条独立通道（`add` 名单），由
+ * 装配钩子在过滤**之后**从注册表查回 schema 追加 —— 见 lib/index.js，不在这里。
+ */
+export function applyToolFilter(tools, { exclude }) {
+  const excludeSet = new Set(exclude ?? [])
+  if (excludeSet.size > 0) return tools.filter((tool) => !excludeSet.has(tool.name))
+  return tools
+}
+
+/**
+ * 每阶段独立段屏蔽（与工具目录三态对称）：压缩受控期在「压缩后仍未晋级」
+ * 时生效且优先于引导期；引导期在未晋级时生效；否则常驻期。三态互不继承：
+ * 每个状态只返回自己那份名单（常驻期 = `sections`，引导期 = `sectionsBootstrap`，
+ * 压缩受控期 = `sectionsCompaction`），一个阶段的屏蔽绝不波及另一个阶段。
+ * 返回该阶段生效的屏蔽段名（完整名单）。
+ */
+export function pickSectionsForStatus(config, status) {
+  const resident = config?.sections
+  const compaction = config?.sectionsCompaction
+  const bootstrap = config?.sectionsBootstrap
+  if (!status.promoted && status.boundary >= 0) return Array.isArray(compaction) ? compaction : []
+  if (!status.promoted) return Array.isArray(bootstrap) ? bootstrap : []
+  return Array.isArray(resident) ? resident : []
+}
+
+/**
+ * 段级策略：屏蔽 → 替换 → 注入 → 排序，作用于任意来源的基础段列表。
+ *
+ * 瀑布流装配与 assemble 强制覆盖（forceSections）共用同一份实现 —— 输入
+ * `baseSections` 可以是瀑布流里其它插件过滤后的段，也可以是注册表
+ * `layers.merge()` 的原始段定义。后一种输入就是「以本插件为准」的关键：
+ * 预设插件的阶段裁段与宿主的 complete 整段接管都发生在瀑布流内/后，
+ * 而强制覆盖在方法边界用这份原始定义重建 sections，前两者再无机会改写。
+ * 条目只需 { name, text }；order 在映射时按数组序补上（与注册表顺序一致），
+ * 保证稳定排序，与注入段的虚拟 order 空间一致。
+ */
+export function applySectionPolicy(baseSections, cfg, status) {
+  const denied = new Set(pickSectionsForStatus(cfg, status))
+  const replace = cfg.replace ?? {}
+  const injectList = filterInjectByPhase(cfg.inject, status)
+  let sections = baseSections
+    .filter((section) => !denied.has(section.name))
+    .map((section, i) =>
+      Object.hasOwn(replace, section.name) ? { ...section, order: i, text: replace[section.name] } : { ...section, order: i },
+    )
+  for (const item of injectList) {
+    // 被屏蔽的段直接跳过 —— 上面已经把它们过滤掉了。
+    if (denied.has(item.name)) continue
+    const index = sections.findIndex((section) => section.name === item.name)
+    if (index >= 0) {
+      // 已存在的段：覆盖 order 来控制拼接顺序。文本按「本阶段注入文本 → 该
+      // 段当前文本」取（后者可能已被全局 replace 改过）—— injectList 已经按
+      // 阶段筛过，所以带 phase 的文本只作用在本阶段，三个阶段各改各的；全局
+      // replace 字典是跨阶段的（旧语义），只在没有阶段文本时生效。
+      sections[index] = {
+        ...sections[index],
+        text: item.text ? item.text : sections[index].text,
+        order: item.order,
+      }
+    } else if (item.custom === true || Object.hasOwn(replace, item.name) || item.text) {
+      // 装配里没有这个名字：只有「本插件自撰的 custom 段」「被替换的段」
+      // 「自带文本的注入段」才允许新建条目。只带 order 的空文本系统名必须
+      // 跳过 —— 它通常来自快照里混进的别的预设独有段名（并集池会带回来），
+      // 新建就变成一条空白幽灵段，实打实进最终提示词。
+      sections.push({ name: item.name, order: item.order, text: item.text || replace[item.name] })
+    }
+  }
+  // 虚拟 order 排序：order 缺省按 0，稳定排序保持系统段原始相对顺序；
+  // 注入段携带各自的 order（120+ 落在系统段之后，或被重排到任意断点），
+  // 以 order 升序决定注入顺序 —— 与「每阶段独立名单」配合即每阶段独立序。
+  sections.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  return sections
+}