dsh-router-core 0.4.5 → 0.4.7

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([]), [])
+})

package/src/ext-prompt/sections.ts

@@ -0,0 +1,193 @@
+/**
+ * 系统提示词**段落级**总控的纯逻辑与清单缓存 —— 把整体系统提示词拆成
+ * 每一段（`harness:identity`、`tool:write`、`plan:policy` …），面板分组列出、
+ * 逐段开关，关掉的段在装配时被过滤掉（`index.ts` 的 waterfall）。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 清单从哪来：`assemble()` 的真实产物，不写死宿主段名表
+ * ════════════════════════════════════════════════════════════════════
+ * 段名只有个别是宿主导出常量（`harness:identity`、`deployment:persona-*`），
+ * 其余（`tool:*`、`mcp:*`、第三方插件段）都埋在各自插件里 —— 写死清单必然漂移。
+ * 装配 waterfall（`system-prompt/assemble`）每轮都携带**全量已排序段落**，
+ * 顺路缓存一份就是面板的事实源；apply 时预热一次 assemble，没开始对话也有清单。
+ *
+ * ⚠️ 清单是**最近一次装配的快照**（近似）：`assemble()` 不带 scope 时只含
+ * global 段，真实对话是 agent scope；且多会话并发时缓存归"最后一次装配"。
+ * 面板展示可接受，**开关判定不受影响** —— 过滤按段名，名字缺席时无害跳过。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 开关的生效面：waterfall 删段，不碰别人的注册
+ * ════════════════════════════════════════════════════════════════════
+ * 宿主没有"禁用别人的段"的 API。两条路里选了 waterfall：`assemble()` 的
+ * 监听器返回值是权威结果（宿主源码 `return transformed`，complete 段除外），
+ * 删掉的段不会被恢复。同名覆盖（scoped section 返回 `''`）只适合"顶掉某一个
+ * 已知名字"，对同层自己注册的段还会 throw —— 删段才是对全部段通用的开关。
+ */
+import type { PromptExtData } from './render.ts'
+
+/** 面板控制条 id 的段前缀（**传输层编码**；落盘用裸段名，不带前缀）。 */
+export const SECTION_CONTROL_PREFIX = 'sec:'
+
+/**
+ * 自己的准则段：**不进清单、不被过滤**。
+ *
+ * 它已有独立的开关体系（扩展总开关 + 14 个分类开关）——再列一条"段开关"
+ * 就是同一件事的第二个开关，两边状态会漂移；过滤它还会让分类开关看起来
+ * 失效（段没了，分类怎么切都看不到效果）。
+ */
+export const OWN_SECTION_NAME = 'dsh-router-ext-prompt:guideline'
+
+/**
+ * 段名前缀 → 面板分组名。**未知前缀原样当组名**（不硬编全部前缀）：
+ * 宿主还会加新段（`web:`、`structured:`…），映射漏了顶多组名不雅，
+ * 条目照常列出照常开关 —— 映射表漂移不允许变成"段消失"。
+ */
+/**
+ * 段名前缀 → 面板分组名。
+ *
+ * ⚠️ 键是**段名的第一段**（冒号前），不是"看起来像"的前缀。2026-10-21 实测
+ * 真宿主（3081，23 条 controls / 9 段）纠正过两处脑补：
+ *   - `harness:source`（运行时上下文里 Harness 检出的位置）第一段是 `harness`，
+ *     按前缀映射会被并入「开场身份」—— 而它不是身份，是运行环境说明；
+ *   - `app:web-surface`（Web GUI 说明）第一段是 `app`，与"界面与交付"无关。
+ * 所以 `harness` 刻意**不映射**：`harness:identity` 是身份、`harness:source` 不是，
+ * 靠第一段分不开 —— 让它们各自留下真实前缀（`harness` / `app`）比归错组诚实。
+ * `ui:` 才是界面与交付那一组（`ui:deliverable-file-references`）。
+ *
+ * 映射漏了或故意不映射的前缀，组名**原样显示前缀**、条目照常能列能开关 ——
+ * 映射表漂移不允许变成"段消失"。
+ */
+const GROUP_LABELS: Record<string, string> = {
+  deployment: '部署人设',
+  plan: '计划模式',
+  team: '团队',
+  tool: '工具说明',
+  mcp: 'MCP 服务',
+  context: '运行上下文',
+  ui: '界面与交付',
+}
+
+/**
+ * 无冒号段名的映射（宿主有几个段名整名不带冒号）。
+ *
+ * `harness:identity` 才是开场身份，它带冒号走前缀表；这里只收无冒号的整名。
+ */
+const WHOLE_NAME_LABELS: Record<string, string> = {
+  'mcp-resource-servers': 'MCP 资源',
+}
+
+/** 一条已装配的段（面板清单用）。 */
+export interface SectionEntry {
+  /** 段注册名（稳定；也是开关的落盘键）。 */
+  name: string
+  /** 面板副行显示的原文（装配时 provider 现算的结果，**未做 `{{变量}}` 插值**）。 */
+  text: string
+}
+
+/** `controlId`（`sec:…`）→ 段名；非段条目返回 null。 */
+export function sectionNameOf(controlId: string): string | null {
+  return controlId.startsWith(SECTION_CONTROL_PREFIX) ? controlId.slice(SECTION_CONTROL_PREFIX.length) : null
+}
+
+/** 段名 → 面板控制条 id。 */
+export function sectionControlId(name: string): string {
+  return SECTION_CONTROL_PREFIX + name
+}
+
+/**
+ * 段名的分组名。
+ *
+ * 查表顺序：**整名**（无冒号段名，如 `mcp-resource-servers`）→ **第一段前缀**
+ * （`tool:write` → `tool`）。两级都查不到 ⇒ 有冒号时用第一段原样当组名、
+ * 无冒号归「其他」。
+ */
+export function groupLabelOf(name: string): string {
+  const whole = WHOLE_NAME_LABELS[name]
+  if (whole !== undefined) return whole
+  const i = name.indexOf(':')
+  if (i < 0) return '其他'
+  const head = name.slice(0, i)
+  return GROUP_LABELS[head] ?? head
+}
+
+/** 面板条目标题：去掉组前缀的部分（`tool:write` → `write`；无冒号 = 全名）。 */
+export function sectionTitleOf(name: string): string {
+  const i = name.indexOf(':')
+  return i >= 0 ? name.slice(i + 1) : name
+}
+
+/**
+ * 当前被关掉的段名集合。**只认显式 `false`** —— 缺项是"没碰过"（默认开），
+ * 与 `resolveEnabledCategories` 对 `undefined` 的处置同一纪律。
+ */
+export function disabledSectionNames(data: PromptExtData | undefined): Set<string> {
+  const out = new Set<string>()
+  const saved = data?.sections
+  if (!saved) return out
+  for (const [name, on] of Object.entries(saved)) if (on === false) out.add(name)
+  return out
+}
+
+/**
+ * 过滤掉关闭的段（保序）。自己那段**恒放行**（理由见 `OWN_SECTION_NAME`）。
+ *
+ * ⚠️ 名字不在清单里的关闭项静默跳过：宿主段随版本增删，旧数据里的名字
+ * 失效是正常生命周期，报错只会把面板变成红字噪音。
+ */
+export function filterSections<T extends { name: string }>(sections: readonly T[], off: ReadonlySet<string>): T[] {
+  // ⚠️ 条件是 `===` **或** 没被关 —— 我第一版写成 `!== OWN && !off.has(...)`，
+  //   把"是自己的段"当成了排除条件：结果是**准则段每次都被删掉**，而
+  //   tool:write 这些反倒留着。方向写反不会抛错，只会让面板看起来全开、
+  //   prompt 里准则凭空消失（本条判据就是靠两个方向同时断言抓出来的）。
+  return sections.filter((s) => s.name === OWN_SECTION_NAME || !off.has(s.name))
+}
+
+/**
+ * 段清单缓存：waterfall 监听器是**唯一写入者**（装配路径顺路喂），
+ * 面板 controls getter 只读。分组与排序都在读取端做 —— 缓存保持
+ * 装配原序（`assemble` 已按 order/name 排好），组的次序自然等于 prompt 次序。
+ */
+export function createSectionCache(): {
+  /** 用一次装配结果刷新（整表替换；自己的段不进清单）。 */
+  update: (sections: readonly { name: string; text: string }[]) => void
+  /** 当前清单（拷贝，防调用方改缓存内部）。 */
+  list: () => SectionEntry[]
+} {
+  let entries: SectionEntry[] = []
+  return {
+    update(sections) {
+      entries = sections
+        .filter((s) => s.name !== OWN_SECTION_NAME)
+        .map((s) => ({ name: s.name, text: s.text }))
+    },
+    list() {
+      return entries.map((e) => ({ ...e }))
+    },
+  }
+}
+
+/** 一个分组（组名 + 组内条目，组内保持清单序）。 */
+export interface SectionGroup {
+  label: string
+  items: SectionEntry[]
+}
+
+/**
+ * 按段名前缀分组；**组的先后 = 首次出现序**（清单已按 prompt 序 ⇒ 组序即
+ * 段落在 prompt 里的先后）——不按字母重排，面板顺序与模型看到的顺序一致。
+ */
+export function groupSections(list: readonly SectionEntry[]): SectionGroup[] {
+  const out: SectionGroup[] = []
+  const byLabel = new Map<string, SectionGroup>()
+  for (const item of list) {
+    const label = groupLabelOf(item.name)
+    let g = byLabel.get(label)
+    if (!g) {
+      g = { label, items: [] }
+      byLabel.set(label, g)
+      out.push(g)
+    }
+    g.items.push(item)
+  }
+  return out
+}

package/src/ext-route.test.ts

@@ -76,3 +76,19 @@ test('★ src 下不许有备份/临时文件（它们会被 `git add -A` 顺手
     .filter((f) => /\.(bak|orig|rej|tmp|swp)$/.test(f) || /~$/.test(f))
   assert.deepEqual(junk, [], `源码目录里有临时/备份文件：${junk.join(', ')}`)
 })
+
+// ── controls 序列化白名单（2026-10-21 段落总控）──────────────────
+test('★ controls 透传 group / sortable（白名单漏字段 ⇒ 面板分组永远不生效）', () => {
+  // ⚠️ 这里存在一个**只在入口才暴露**的失效：`GET /ext` 用 `.map()` 逐字段
+  //   重建 controls（白名单），扩展在 `controls` 里给了 `group`，但白名单
+  //   不认它 ⇒ 字段被静默丢掉。而单测（直接读扩展对象的 `.controls`）**全绿**：
+  //   扩展那头确实给了。两端都"对"，中间少一环 —— 只能在这里守。
+  //
+  // 判据用源码形状而非启服务器：与本文件既有做法一致（理由见文件头）。
+  const mapLine = src.split('\n').find((l) => l.includes('.map((c) => ({ id: c.id, title: c.title' ))
+  assert.ok(mapLine !== undefined, '找不到 controls 的序列化 map（形状变了 ⇒ 本判据要跟着改）')
+  assert.match(mapLine, /\.\.\.\(c\.group !== undefined \? \{ group: c\.group \}/,
+    'controls 序列化没透传 group ⇒ 段落分组在面板上永远不出现')
+  assert.match(mapLine, /\.\.\.\(c\.sortable !== undefined \? \{ sortable: c\.sortable \}/,
+    'controls 序列化没透传 sortable ⇒ 段落行仍可拖（假交互）')
+})