dsh-router-core 0.4.6 → 0.4.7

package/src/ext-prompt/plugin.ts

@@ -16,6 +16,15 @@ import type { ExtStoreService, RouterExt } from '../ext/contract.ts'
 import { PROMPT_CATEGORIES, PROMPT_TITLE } from './content.ts'
 import { PROMPT_LOGO_URL } from './logo.ts'
 import { effectiveText, resolveCategories, resolveEnabledCategories, type PromptExtData } from './render.ts'
+import {
+  OWN_SECTION_NAME,
+  disabledSectionNames,
+  groupLabelOf,
+  sectionControlId,
+  sectionNameOf,
+  sectionTitleOf,
+  type SectionEntry,
+} from './sections.ts'
 
 /** 从对象里去掉某个键（不改原对象）。`writeData` 是整块替换 ⇒ 删一个键要重写。 */
 function omit<T extends Record<string, unknown>>(obj: T, key: string): Partial<T> {
@@ -41,6 +50,15 @@ export const EXT_PROMPT_ID = 'prompt'
 export function createPromptExt(deps: {
   isSystemPromptReady: () => boolean
   store?: ExtStoreService
+  /**
+   * 当前已装配的段落清单（最近一次 `assemble` 的快照，来自 waterfall 缓存）。
+   *
+   * ⚠️ **必选，不给缺省**：缺省成 `() => []` 的话，`index.ts` 忘接这个参数
+   * 就是"段清单恒空"的静默失效（面板无段、过滤不生效，但一切照常跑）——
+   * 让类型红比让它静默强。**空清单是合法值**（还没预热完/宿主一段都没有），
+   * 与"没接线"的区分靠这里不给缺省，不靠运行时猜。
+   */
+  getSections: () => SectionEntry[]
 }): RouterExt {
   const store = deps.store
   /**
@@ -92,7 +110,7 @@ export function createPromptExt(deps: {
       const on = resolveEnabledCategories(true, data)
       // ⚠️ 走 `resolveCategories`（内置 + 自建 + 排序），不是内置常量 ——
       //   否则自建条目与拖动排序**只停在面板上**，不进 prompt。
-      return resolveCategories(data).map((c) => {
+      const categories = resolveCategories(data).map((c) => {
         const t = effectiveText(c.id, data?.text?.[c.id], c)
         return {
           id: c.id,
@@ -109,11 +127,56 @@ export function createPromptExt(deps: {
           custom: c.custom,
           overridden: c.overridden,
           on: on.has(c.id),
+          // ⚠️ 准则**不标 group**：页头 `description` 已经是它的组头（+「添加」按钮），
+          //   再标一组就是同一件事显示两处（反查重复）。无组 = 平铺，行为不变。
         }
       })
+      // ② 宿主段落条目 —— 面板按 `group` 分节；`sortable: false` 不给拖
+      //   （排序落盘不认段 id，拖了也是假交互）；`editable` 缺省 = 只读
+      //   （别人的段我们不提供改写，只开关）。
+      const off = disabledSectionNames(data)
+      const sections = deps.getSections()
+        // 防御过滤：自己的准则段恒不列（清单源已排除，这里再拦一道 ——
+        // 列了它就是"同一件事的第二个开关"，两处状态必然漂移）。
+        .filter((s) => s.name !== OWN_SECTION_NAME)
+        .map((s) => ({
+        id: sectionControlId(s.name),
+        // 标题去掉组前缀（组名给了语境）：组「工具说明」下的 `write`，
+        // 比孤零零的 `tool:write` 好读；完整名放 `detail`（报问题时可指认）。
+        title: sectionTitleOf(s.name),
+        on: !off.has(s.name),
+        detail: s.name,
+        // ⚠️ 空原文要**说清是空的**，不能给空串（2026-10-21 真机实测）：
+        //   `deployment:persona-prefix` / `persona-suffix` 的 provider 在未配置
+        //   人设时返回 ""，面板上就是一条没有正文的行 —— 用户只能盲切。
+        //   这不是"忘了给原文"，是这一段此刻**确实没内容**，说清楚才谈得上判断。
+        body: s.text === '' ? '（此段当前为空）' : s.text,
+        group: groupLabelOf(s.name),
+        sortable: false,
+      }))
+      return [...categories, ...sections]
     },
     setControl: (controlId, on) => {
       if (!store) return false
+      // ---- 段落开关（`sec:` 前缀）：写 `data.sections`，与分类开关分键 ----
+      const secName = sectionNameOf(controlId)
+      if (secName !== null) {
+        // 只认**当前清单里**的段（清单 = 装配事实），且永远不关自己那段
+        // （它已有总开关 + 分类开关，再给一个入口就是同一件事的两个开关）。
+        if (secName === OWN_SECTION_NAME) return false
+        if (!deps.getSections().some((s) => s.name === secName)) return false
+        const data = readData()
+        const sections = { ...(data.sections ?? {}) }
+        if (on) delete sections[secName]
+        else sections[secName] = false
+        const next: PromptExtData = { ...data }
+        // 只存覆盖值（见 `PromptExtData.sections`）：全开时不留空对象键。
+        if (Object.keys(sections).length > 0) next.sections = sections
+        else delete next.sections
+        store.writeData(EXT_PROMPT_ID, next)
+        return true
+      }
+      // ---- 分类开关（原路径）----
       // ⚠️ **只改这一个键，不重写整块**：整块重写会顺手把 data 抽屉里的其它字段
       //   抹掉（`store.test.ts` 有一条「置开关不能把 data 冲掉」的同款纪律）。
       const data = readData()

package/src/ext-prompt/render.test.ts

@@ -143,7 +143,7 @@ test('★ 渲染出来的第一行是整段标题（拆分时差点丢的就是
   // ⚠️ 原文是 `[准则 …] ·身份气质：…`，标题在方括号里、**不属于任何单条分类**
   //   ⇒ 按分隔符切分时天然被丢掉
   //   （它只出现在 content.ts 头注，没进任何 body）。
-  //   丢了的后果：模型看到 14 条**没有名字**的规则，不知道这套东西是什么。
+  //   丢了的后果：模型看到一堆**没有名字**的规则，不知道这套东西是什么。
   const text = renderPromptText(true, undefined)
   assert.ok(text.startsWith(PROMPT_TITLE), `第一行不是标题；开头是：${text.slice(0, 30)}`)
   assert.equal(text.split('\n')[0], PROMPT_TITLE, '标题必须在最前面 —— 它要解释后面的规则')

package/src/ext-prompt/render.ts

@@ -25,7 +25,7 @@ export interface PromptExtData {
   text?: Record<string, PromptCategoryOverride>
   /**
    * 用户自建的准则条目。**与内置的 `PROMPT_CATEGORIES` 分开存** ——
-   * 内置那 14 条是**代码常量**（发版即定），混在一起就会出现"代码里有一条、
+   * 内置条目是**代码常量**（发版即定），混在一起就会出现"代码里有一条、
    * 落盘里又有一条"的归属问题：升级时新加的内置条目会和用户的旧数据打架。
    *
    * 存的是**完整条目**（不是覆盖值）：自建的东西没有"内置版本"可回退。
@@ -34,12 +34,23 @@ export interface PromptExtData {
   /**
    * 展示顺序：`[id, …]`，含内置与自建。
    *
-   * ⚠️ **只存 id 顺序，不重排内置数组本身**：内置 14 条的次序是 `content.ts`
+   * ⚠️ **只存 id 顺序，不重排内置数组本身**：内置条目的次序是 `content.ts`
    *   里的代码顺序，它同时是"准则作为一份文档的阅读顺序"；让用户拖动去改它，
    *   等于让代码顺序随某个用户的操作漂移 —— 别人拿到新版本看到的次序就变了。
    *   落盘只记"这次会话里按什么顺序显示"，代码顺序永远是兜底。
    */
   order?: string[]
+  /**
+   * 段落级开关：`{ [sectionName]: boolean }`，**只存关闭项**（`false` = 关）。
+   *
+   * 缺项 = 开（默认全开）——与 `text` 的"只存覆盖值"同一纪律：宿主的段落随
+   * 宿主/别的插件增删，存全文表就得在升级后逐条对账；只记"用户主动关了谁"
+   * 让新增段落自然落回默认（开），用户的选择不会被静默迁移。
+   *
+   * key 是**段的注册名**（如 `tool:write`），不是控制条 id（`sec:` 前缀是
+   * 传输层编码，落盘用裸名，见 sections.ts）。
+   */
+  sections?: Record<string, boolean>
 }
 
 /** 一条分类上用户改过的字段（只记改了的那些）。 */
@@ -103,7 +114,7 @@ export function resolveEnabledCategories(
  * 渲染成**一个**段落文本（多分类拼一起）。
  *
  * 为什么要拼成一段而不是一段一个：面板开关是"分类"粒度，而 prompt 读起来
- * 是一段连续的准则 —— 分成 14 个 section 会让 KV cache 每个分类各占一段、
+ * 是一段连续的准则 —— 分成多个 section 会让 KV cache 每个分类各占一段、
  * 增删任意一个分类都让其后全部位移。这里**注册一个 section，文本由开关拼装**。
  *
  * @returns 关闭的分类不进结果；全关 ⇒ 空串（上游 `renderPrompt` 会丢弃空段）。
@@ -128,10 +139,10 @@ export function renderCategories(
   //   且只在**至少有一条规则开启**时才出现 —— 全关时整段返回空串被平台丢弃，
   //   留着标题就变成"有一套叫准则 v5 的东西"却一条规则都没有。
   //   标题放在**前面**：它要解释后面这些规则是什么。
-  // ⚠️ **分类之间空一行**（2026-09-29 用户拍板）。单 `\n` 时 15 条规则在窄栏里
-  //   密排成一块，肉眼看不出是 15 条独立的规则 —— 那正是"全都跑成一行"的观感
+  // ⚠️ **分类之间空一行**（2026-09-29 用户拍板）。单 `\n` 时各条规则在窄栏里
+  //   密排成一块，肉眼看不出是各自独立的规则 —— 那正是"全都跑成一行"的观感
   //   来源（实测系统提示词里 `\n` 一直都在，是**排版**问题不是**内容**问题）。
-  //   空行让每条规则成为独立段落。代价是 13 个换行符（~13 token，可忽略），
+  //   空行让每条规则成为独立段落。代价只是分隔换行（十几个 token，可忽略），
   //   且不改变前缀位置 ⇒ KV cache 行为不变。
   // ⚠️ 标题由**显式参数**决定，**不靠 `categories === PROMPT_CATEGORIES` 这种
   //   引用相等**（2026-09-29 实测踩过）：接入自建条目后调用方传的是

package/src/ext-prompt/section-controls.test.ts

@@ -0,0 +1,148 @@
+/**
+ * 段落总控的**接线**判据 —— 三件事必须真的串上，缺一件就静默失效：
+ *   ① 段落进了 `controls`（面板看得见）；
+ *   ② 段开关落盘到 `data.sections`，且**不碰** `categories`（两套开关不串味）；
+ *   ③ `system-prompt/assemble` waterfall 真的把关闭的段删掉了（这是"可开关"
+ *      的唯一真判据 —— 只测 ①② 会漏掉"面板能点、但 prompt 里照旧"）。
+ *
+ * ⚠️ 本文件里"真删段"的验证用**假宿主装配链**：注册一个监听器、手工跑一次
+ *   waterfall（`ctx.waterfall` 真实现来自 cordis），而不是调真 `assemble()`。
+ *   理由：真 `assemble` 需要整套 `dsh-system-prompt` 服务与 scope 环境，
+ *   会把判据变成"宿主内部实现测试"；而本插件的责任边界只是"监听器拿到
+ *   assembly 后返回什么"。监听器的返回形状 = 宿主采信的形状（`return transformed`）。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createPromptExt, EXT_PROMPT_ID } from './plugin.ts'
+import { OWN_SECTION_NAME, SECTION_CONTROL_PREFIX } from './sections.ts'
+import type { PromptExtData } from './render.ts'
+import type { ExtStoreService } from '../ext/contract.ts'
+
+/** 记录写盘的内存 store。 */
+function fakeStore(initial: { enabled?: boolean; data?: PromptExtData } = {}): ExtStoreService & {
+  data: () => PromptExtData | undefined
+  writes: PromptExtData[]
+} {
+  let data = initial.data
+  let enabled = initial.enabled ?? true
+  const writes: PromptExtData[] = []
+  return {
+    isEnabled: () => enabled,
+    // 真实签名带 id（`setEnabled(id, enabled)`）——第一版漏了它，tsc 才报
+    // "string 不能赋给 boolean"。桩的形状必须与契约逐字一致，否则测的是
+    // 一个不存在的接口。
+    setEnabled: (_id: string, v: boolean) => { enabled = v },
+    readData: <T>() => data as T | undefined,
+    writeData: (_id, d) => { data = d as PromptExtData; writes.push(d as PromptExtData) },
+    data: () => data,
+    writes,
+  }
+}
+
+const SAMPLE = [
+  { name: 'harness:identity', text: 'You are an AI agent.' },
+  { name: 'tool:write', text: 'write tool spec' },
+  { name: 'tool:edit', text: 'edit tool spec' },
+]
+
+test('★ 段落以 `sec:` 前缀进 controls，带组名、原文、且不可拖不可编辑', () => {
+  const ext = createPromptExt({
+    isSystemPromptReady: () => true,
+    getSections: () => SAMPLE,
+    store: fakeStore(),
+  })
+  const secRows = (ext.controls ?? []).filter((c) => c.id.startsWith(SECTION_CONTROL_PREFIX))
+  assert.equal(secRows.length, 3, '段落没进 controls ⇒ 面板列不出来')
+  const write = secRows.find((c) => c.id === `${SECTION_CONTROL_PREFIX}tool:write`)!
+  assert.equal(write.title, 'write', '标题应去掉组前缀')
+  assert.equal(write.detail, 'tool:write', '完整段名要能指认（报问题时用）')
+  assert.equal(write.body, 'write tool spec', '没原文 = 用户盲切')
+  assert.equal(write.group, '工具说明')
+  assert.equal(write.on, true, '默认全开')
+  assert.equal(write.sortable, false, '段 id 不在排序落盘范围，可拖就是假交互')
+  assert.notEqual(write.editable, true, '别人的段不给改写入口，只开关')
+})
+
+test('准则分类仍在 controls 前列，且**不带** group（页头已是它的组头）', () => {
+  const ext = createPromptExt({
+    isSystemPromptReady: () => true,
+    getSections: () => SAMPLE,
+    store: fakeStore(),
+  })
+  const rows = ext.controls ?? []
+  const plain = rows.filter((c) => c.group === undefined)
+  assert.ok(plain.length > 0, '准则分类丢了 ⇒ 原功能被新功能挤掉')
+  assert.ok(plain.every((c) => c.editable === true), '准则分类应保持可编辑')
+  assert.equal(rows[0]!.group, undefined, '列表首条应是准则（无组节渲染在最前）')
+})
+
+test('★ 段开关落盘到 data.sections：关 = 存 false，开 = 删键（只存覆盖值）', () => {
+  const store = fakeStore()
+  const ext = createPromptExt({
+    isSystemPromptReady: () => true,
+    getSections: () => SAMPLE,
+    store,
+  })
+  assert.equal(ext.setControl!(`${SECTION_CONTROL_PREFIX}tool:write`, false), true)
+  assert.deepEqual(store.data()?.sections, { 'tool:write': false })
+  // 开回来 ⇒ 键消失（不留 `true`，否则落盘会随用户点击无限膨胀）
+  assert.equal(ext.setControl!(`${SECTION_CONTROL_PREFIX}tool:write`, true), true)
+  assert.equal(store.data()?.sections, undefined, '全开后仍留着 sections 键')
+})
+
+test('★ 段开关不碰分类开关（两套开关各自一个键）', () => {
+  const store = fakeStore({ data: { categories: { identity: false } } })
+  const ext = createPromptExt({
+    isSystemPromptReady: () => true,
+    getSections: () => SAMPLE,
+    store,
+  })
+  ext.setControl!(`${SECTION_CONTROL_PREFIX}tool:write`, false)
+  assert.deepEqual(store.data()?.categories, { identity: false }, '写段开关把分类开关冲掉了')
+  assert.deepEqual(store.data()?.sections, { 'tool:write': false })
+  // 反向：写分类开关不能冲掉段开关
+  ext.setControl!('identity', true)
+  assert.deepEqual(store.data()?.sections, { 'tool:write': false }, '写分类开关把段开关冲掉了')
+})
+
+test('注入：清单外的段 id 拒写（旧数据/手改 ext.json 不该被面板认成有效开关）', () => {
+  const store = fakeStore()
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
+  assert.equal(ext.setControl!(`${SECTION_CONTROL_PREFIX}tool:write`, false), false)
+  assert.equal(store.data(), undefined, '拒了却写了盘')
+})
+
+test('★ 自己的准则段拒绝被当成段落开关（同一件事不能有两个开关）', () => {
+  const store = fakeStore()
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => SAMPLE, store })
+  assert.equal(ext.setControl!(`${SECTION_CONTROL_PREFIX}${OWN_SECTION_NAME}`, false), false)
+  // 即使清单源里混进了它，controls 也不列
+  const ext2 = createPromptExt({
+    isSystemPromptReady: () => true,
+    getSections: () => [{ name: OWN_SECTION_NAME, text: 'guideline' }, ...SAMPLE],
+    store,
+  })
+  const ids = (ext2.controls ?? []).map((c) => c.id)
+  assert.equal(ids.includes(`${SECTION_CONTROL_PREFIX}${OWN_SECTION_NAME}`), false,
+    '准则段被列了 ⇒ 面板上同一件事出现两个开关')
+})
+
+test('段清单为空 ⇒ 不产出段条目（宿主没段/预热没完成时面板不显示空组）', () => {
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store: fakeStore() })
+  assert.equal((ext.controls ?? []).some((c) => c.id.startsWith(SECTION_CONTROL_PREFIX)), false)
+})
+
+test('段条目的 on 反映已存关闭项（面板刷新要看到真实状态）', () => {
+  const ext = createPromptExt({
+    isSystemPromptReady: () => true,
+    getSections: () => SAMPLE,
+    store: fakeStore({ data: { sections: { 'tool:edit': false } } }),
+  })
+  const on = Object.fromEntries((ext.controls ?? []).map((c) => [c.id, c.on]))
+  assert.equal(on[`${SECTION_CONTROL_PREFIX}tool:edit`], false)
+  assert.equal(on[`${SECTION_CONTROL_PREFIX}tool:write`], true)
+})
+
+test('ext id 未漂移（落盘键跟着它，改了用户关段表就全丢）', () => {
+  assert.equal(EXT_PROMPT_ID, 'prompt')
+})

package/src/ext-prompt/section-filter.test.ts

@@ -0,0 +1,140 @@
+/**
+ * `system-prompt/assemble` waterfall 的**真删段**判据。
+ *
+ * ⚠️ 为什么这条闸门非有不可（本仓反复栽过的形状）：面板能列、开关能落盘，
+ * 但"关掉之后模型到底还看不看得到这一段"是**另一件事**。只测前两者会得到一个
+ * 全绿的假象，而线上行为是"关了没用"。本仓同类教训：`docs` 里记的
+ * "apply 里 inject 不可靠 ⇒ 准则一次都没进过 prompt"（面板全正常、prompt 里没有）。
+ *
+ * 做法：用**真 cordis Context**（`ctx.on` + `ctx.waterfall` 真实现）跑一次
+ * 装配链，断言监听器返回的 assembly 里段真的少了。监听器的返回值就是宿主采信
+ * 的结果（宿主 `assemble()` 源码：`const transformed = await this.ctx.waterfall(...)`
+ * 后 `return transformed`），所以这里验的是**我们这一侧的责任边界**。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { OWN_SECTION_NAME, disabledSectionNames, filterSections } from './sections.ts'
+import type { PromptExtData } from './render.ts'
+
+/** 装配出的一条段（宿主形状的最小面）。 */
+interface Assembled {
+  name: string
+  text: string
+}
+
+/**
+ * 按 `index.ts` 里监听器的**同一形状**接一条装配链，返回 waterfall 的结果。
+ *
+ * ⚠️ 刻意复制那 6 行而不是从 `index.ts` 导出一个可测函数：`index.ts` 的
+ * 监听器需要真 `systemPrompt` service 才能注册（它读 `systemPromptOf(ctx)`），
+ * 为它造全套宿主桩会让判据变成"测桩"。这里验的是**逻辑链**：先取 next()、
+ * 再按落盘过滤；复制带来的漂移风险由"两边注释互相指认"兜住。
+ */
+async function runAssembly(
+  ctx: { on: (n: string, f: unknown) => unknown; waterfall: (n: string, ...a: unknown[]) => Promise<unknown> },
+  opts: { enabled: boolean; data?: PromptExtData; sections: Assembled[] },
+): Promise<Assembled[]> {
+  ctx.on('system-prompt/assemble', async (
+    _assembly: unknown,
+    _context: unknown,
+    next: () => Promise<{ sections: Assembled[] }>,
+  ) => {
+    const result = await next()
+    if (!opts.enabled) return result
+    const off = disabledSectionNames(opts.data)
+    if (off.size === 0) return result
+    return { ...result, sections: filterSections(result.sections, off) }
+  })
+  // 真 waterfall：最后一个参数是终态回调（返回 assembly），前面的参数原样透传给监听器
+  // ⚠️ 派发的事件名必须与注册的**逐字相同**：我第一版这里写 'assemble'，
+  //   而上面注册的是 'system-prompt/assemble' ⇒ 监听器根本没被调用，
+  //   断言报"关了却还在"。那种失败**看起来像功能没实现**，实际是判据自己
+  //   接错了线 —— 事件名是字符串、拼错不报错，只让闸门测了个空。
+  const out = await ctx.waterfall(
+    'system-prompt/assemble',
+    { sections: opts.sections },
+    {},
+    async () => ({ sections: opts.sections }),
+  ) as { sections: Assembled[] }
+  return out.sections
+}
+
+const ALL: Assembled[] = [
+  { name: OWN_SECTION_NAME, text: '准则正文' },
+  { name: 'harness:identity', text: 'You are an AI agent.' },
+  { name: 'tool:write', text: 'write spec' },
+  { name: 'tool:edit', text: 'edit spec' },
+]
+
+async function freshCtx() {
+  const { Context } = await import('@deepseek-ai/cordis')
+  const ctx = new Context()
+  return ctx as unknown as {
+    on: (n: string, f: unknown) => unknown
+    waterfall: (n: string, ...a: unknown[]) => Promise<unknown>
+  }
+}
+
+test('★ 关掉的段真的从装配结果里消失（"可开关"的唯一真判据）', async () => {
+  const ctx = await freshCtx()
+  const out = await runAssembly(ctx, {
+    enabled: true,
+    data: { sections: { 'tool:write': false } },
+    sections: ALL,
+  })
+  const names = out.map((s) => s.name)
+  assert.equal(names.includes('tool:write'), false, '关了却还在 ⇒ 面板开关是装饰')
+  assert.equal(names.includes('tool:edit'), true, '没关的被误删 ⇒ 开关粒度错了')
+})
+
+test('★ 准则段永不被 waterfall 删掉（关它走的是总开关/分类开关）', async () => {
+  const ctx = await freshCtx()
+  const out = await runAssembly(ctx, {
+    enabled: true,
+    // 手改 ext.json 把准则段写进关闭项：也不许删
+    data: { sections: { [OWN_SECTION_NAME]: false, 'tool:write': false } },
+    sections: ALL,
+  })
+  const names = out.map((s) => s.name)
+  assert.equal(names.includes(OWN_SECTION_NAME), true, '准则段被删 ⇒ 分类开关全部失效')
+  assert.equal(names.includes('tool:write'), false)
+})
+
+test('★ 总开关关 ⇒ 原样放行（扩展关 = 什么都不做，宿主段落自然注入）', async () => {
+  const ctx = await freshCtx()
+  const out = await runAssembly(ctx, {
+    enabled: false,
+    data: { sections: { 'tool:write': false } },
+    sections: ALL,
+  })
+  assert.deepEqual(out.map((s) => s.name), ALL.map((s) => s.name),
+    '总开关关掉后仍然删段 ⇒ 用户关了扩展但提示词还在被改')
+})
+
+test('全开（落盘无关闭项）⇒ 一个段都不动', async () => {
+  const ctx = await freshCtx()
+  const out = await runAssembly(ctx, { enabled: true, sections: ALL })
+  assert.deepEqual(out.map((s) => s.name), ALL.map((s) => s.name))
+})
+
+test('关闭项全是失效名字 ⇒ 装配结果不受影响（宿主换版本后的旧数据）', async () => {
+  const ctx = await freshCtx()
+  const out = await runAssembly(ctx, {
+    enabled: true,
+    data: { sections: { 'gone:forever': false } },
+    sections: ALL,
+  })
+  assert.deepEqual(out.map((s) => s.name), ALL.map((s) => s.name))
+})
+
+test('多个监听器串联时我们的过滤不被前一个吞掉（waterfall 顺序语义）', async () => {
+  const ctx = await freshCtx()
+  // 先注册一个"什么都不做、原样返回"的旁观者
+  ctx.on('system-prompt/assemble', async (_a: unknown, _c: unknown, next: () => Promise<{ sections: Assembled[] }>) => next())
+  const out = await runAssembly(ctx, {
+    enabled: true,
+    data: { sections: { 'tool:edit': false } },
+    sections: ALL,
+  })
+  assert.equal(out.map((s) => s.name).includes('tool:edit'), false)
+})

package/src/ext-prompt/sections.test.ts

@@ -0,0 +1,123 @@
+/**
+ * 段落总控的**纯逻辑**判据（`sections.ts`）。
+ *
+ * 守三件事，每件都对着一种"静默失效"：
+ *   ① 控制条 id 与段名的**往返**（编码错了 ⇒ 面板点的开关落到别人的段上）；
+ *   ② 过滤**只删该删的**（自己那段恒放行、清单外的旧名字无害跳过）；
+ *   ③ 分组的**归组与次序**（组的先后 = prompt 次序，不能被字母序打乱）。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  OWN_SECTION_NAME,
+  SECTION_CONTROL_PREFIX,
+  createSectionCache,
+  disabledSectionNames,
+  filterSections,
+  groupLabelOf,
+  groupSections,
+  sectionControlId,
+  sectionNameOf,
+  sectionTitleOf,
+} from './sections.ts'
+
+test('控制条 id ↔ 段名往返（`sec:` 是传输层编码，落盘用裸名）', () => {
+  assert.equal(sectionControlId('tool:write'), `${SECTION_CONTROL_PREFIX}tool:write`)
+  assert.equal(sectionNameOf(sectionControlId('tool:write')), 'tool:write')
+  // 含冒号的段名不能被"按第一个冒号切"吃掉后半截
+  assert.equal(sectionNameOf(sectionControlId('mcp:my-server:tools')), 'mcp:my-server:tools')
+})
+
+test('非段条目（准则分类）不被当成段落 —— 否则分类开关会写到 segments 里', () => {
+  assert.equal(sectionNameOf('identity'), null)
+  assert.equal(sectionNameOf('cu-1'), null)
+  assert.equal(sectionNameOf(''), null)
+})
+
+test('★ 只认显式 false：缺项 = 没碰过 = 开（与分类开关同一纪律）', () => {
+  const off = disabledSectionNames({ sections: { 'tool:write': false, 'tool:read': true } })
+  assert.equal(off.has('tool:write'), true)
+  assert.equal(off.has('tool:read'), false, 'true 是"开着"，不该算进关闭集合')
+  assert.equal(disabledSectionNames(undefined).size, 0, '没记录 = 全开')
+  assert.equal(disabledSectionNames({}).size, 0)
+})
+
+test('★ 过滤只删关闭的段，且保持原序', () => {
+  const all = [{ name: 'a' }, { name: 'b' }, { name: 'c' }]
+  assert.deepEqual(filterSections(all, new Set(['b'])).map((s) => s.name), ['a', 'c'])
+  assert.deepEqual(filterSections(all, new Set()).map((s) => s.name), ['a', 'b', 'c'])
+})
+
+test('★ 自己的准则段恒放行（它已有总开关+分类开关，不能再被段开关关一次）', () => {
+  // 即使落盘里被写进了关闭项（手改 ext.json），也不许把它过滤掉
+  const all = [{ name: OWN_SECTION_NAME }, { name: 'tool:write' }]
+  const kept = filterSections(all, new Set([OWN_SECTION_NAME, 'tool:write']))
+  // 准则段必须留下、被关的 tool:write 必须走 —— 两个方向都断言，
+  // 只断"准则段在"的话，过滤器退化成"全都放行"也能过。
+  assert.deepEqual(kept.map((s) => s.name), [OWN_SECTION_NAME],
+    '准则段被过滤 ⇒ 分类开关全部看起来失效')
+})
+
+test('清单外的旧名字无害：宿主换版本后旧关闭项不该报错', () => {
+  assert.doesNotThrow(() => filterSections([{ name: 'a' }], new Set(['gone:forever'])))
+})
+
+test('缓存：自己的段不进清单，且返回值是拷贝（调用方改不动缓存）', () => {
+  const cache = createSectionCache()
+  cache.update([{ name: OWN_SECTION_NAME, text: 'x' }, { name: 'tool:write', text: 'write spec' }])
+  const list = cache.list()
+  assert.deepEqual(list.map((e) => e.name), ['tool:write'], '准则段进了清单 ⇒ 面板多一个重复开关')
+  list[0]!.text = 'mutated'
+  assert.equal(cache.list()[0]!.text, 'write spec', 'list() 返回内部引用 ⇒ 面板改动污染后续读')
+})
+
+test('分组：组的先后 = 首次出现序（不按字母重排）', () => {
+  const groups = groupSections([
+    { name: 'deployment:persona-prefix', text: '' },
+    { name: 'tool:bash', text: '' },
+    { name: 'tool:edit', text: '' },
+    { name: 'plan:policy', text: '' },
+  ])
+  assert.deepEqual(groups.map((g) => g.label), ['部署人设', '工具说明', '计划模式'])
+  assert.deepEqual(groups[1]!.items.map((i) => i.name), ['tool:bash', 'tool:edit'], '组内顺序被改 ⇒ 面板顺序与 prompt 顺序脱钩')
+})
+
+test('★ 分组落名以真宿主实测为准（2026-10-21，9 个段名逐个钉）', () => {
+  // 这组断言直接抄 3081 上真宿主返回的段名 —— 我第一版按"看起来像"的前缀
+  // 脑补过两处（harness / app），真机一看就对不上。
+  const actual: [string, string][] = [
+    ['deployment:persona-prefix', '部署人设'],
+    ['deployment:persona-suffix', '部署人设'],
+    ['tool:pty', '工具说明'],
+    ['tool:session-query', '工具说明'],
+    ['mcp:rea', 'MCP 服务'],
+    ['ui:deliverable-file-references', '界面与交付'],
+    ['mcp-resource-servers', 'MCP 资源'],
+    // ⚠️ 这两个**刻意不并入任何美名组**：`harness:source` 是运行环境说明
+    // （不是开场身份），`app:web-surface` 是 Web GUI 说明（不是"界面与交付"，
+    // 那个组是给 `ui:` 的）。归错组比留真实前缀更误导。
+    ['harness:source', 'harness'],
+    ['app:web-surface', 'app'],
+  ]
+  for (const [name, label] of actual) {
+    assert.equal(groupLabelOf(name), label, `${name} 归组错了`)
+  }
+})
+
+test('已知前缀用中文组名、未知前缀原样、无冒号归「其他」', () => {
+  assert.equal(groupLabelOf('tool:write'), '工具说明')
+  assert.equal(groupLabelOf('plan:policy'), '计划模式')
+  // 宿主新加的段（映射表还没有）：组名原样显示，条目照样能列能开关
+  assert.equal(groupLabelOf('web:surface'), 'web')
+  assert.equal(groupLabelOf('unknown-thing'), '其他')
+})
+
+test('条目标题去掉组前缀（组名已经给了语境）', () => {
+  assert.equal(sectionTitleOf('tool:write'), 'write')
+  assert.equal(sectionTitleOf('mcp:my-server'), 'my-server')
+  assert.equal(sectionTitleOf('mcp-resource-servers'), 'mcp-resource-servers', '无冒号时不能被切成空串')
+})
+
+test('空清单 ⇒ 空分组（不产出空壳组）', () => {
+  assert.deepEqual(groupSections([]), [])
+})