dsh-router-core 0.4.5 → 0.4.7

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

@@ -20,7 +20,7 @@ import { PROMPT_CATEGORIES, PROMPT_TITLE } from './content.ts'
 import type { RouterExtService } from '../ext/contract.ts'
 
 test('扩展器带上面板要用的身份', () => {
-  const ext = createPromptExt({ isSystemPromptReady: () => true })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [] })
   assert.equal(ext.id, EXT_PROMPT_ID)
   assert.equal(ext.name, '分层提示词')
   assert.equal(ext.source, 'builtin', '随核心分发必须标 builtin，否则插件页会重复列它')
@@ -34,7 +34,7 @@ test('★ `description` 是整段标题（不是自我介绍，也不内插分
   //   ③ 现在又要求**顶部显示标题** ⇒ 改成「等于 PROMPT_TITLE」。
   //   两次反复的共同教训：**默认值/文案该是什么由用户拍板，判据只负责让改动可见**，
   //   所以断言跟着改、并在注释里留着反复，免得下一个人以为是"又改坏了"。
-  const ext = createPromptExt({ isSystemPromptReady: () => true })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [] })
   assert.equal(ext.description, PROMPT_TITLE, '详情页顶部要显示的就是整段标题')
   // ⚠️ 尤其**不许**内插 `${PROMPT_CATEGORIES.length}`：加减分类后文案不跟着变，
   //   就是同一件事的两个来源（「反查重复」）。
@@ -53,7 +53,7 @@ test('★ 插件页那一行的说明仍然在（来自 locale，不是 descript
 })
 
 test('注入：systemPrompt 不可用 ⇒ 报 not ready（不能静默不生效）', () => {
-  const ext = createPromptExt({ isSystemPromptReady: () => false })
+  const ext = createPromptExt({ isSystemPromptReady: () => false, getSections: () => [] })
   const st = ext.getState()
   assert.equal(st.ready, false, '无处注入却报就绪 = 卡片亮着、准则没进 prompt')
   assert.ok((st.detail ?? '').length > 0, '不报还不说原因 = 面板上无从判断')
@@ -102,17 +102,27 @@ test('★ 那一行默认关闭（与 ext-test 同款）', () => {
  *   真 cordis 会如实复现时序（本机 4.0.4 实测：provide 后 inject 不触发，
  *   start() 之后才触发）。
  */
-async function realCtx(opts: { enabled?: boolean; data?: unknown } = {}) {
+async function realCtx(opts: { enabled?: boolean; data?: unknown; assembled?: { name: string; text: string }[] } = {}) {
   const { Context } = await import('@deepseek-ai/cordis')
   const table: RouterExtService = {}
   const sections: { name: string; order: number; text: string | (() => string) }[] = []
+  const assembled = opts.assembled ?? []
+  let assembleCalls = 0
   const ctx = new Context()
   ctx.provide('systemPrompt', {
     section: (s: { name: string; order: number; text: string | (() => string) }) => {
       sections.push(s)
       return () => {}
     },
-    getSectionOrder: () => 100,
+    // ⚠️ 这里曾经有个 `getSectionOrder: () => 100` 的桩：没人调用它（`mount.ts`
+    //   自己定 order），而 100 已经不是本插件的段落 order（2026-10-21 改为 -2000
+    //   放到最前）⇒ 留着就是一句与事实不符的注脚，删掉。
+    // 段落总控的预热/清单源（apply 里 `void sp.assemble()`）；返回值直接决定
+    // 面板清单，测试用 `assembled` 注入。
+    assemble: async () => {
+      assembleCalls++
+      return { sections: assembled.map((s) => ({ ...s })) }
+    },
   })
   ctx.provide('router.ext', table)
   ctx.provide('router.extStore', {
@@ -121,7 +131,7 @@ async function realCtx(opts: { enabled?: boolean; data?: unknown } = {}) {
     readData: () => opts.data,
     writeData: () => {},
   })
-  return { ctx, table, sections }
+  return { ctx, table, sections, getAssembleCalls: () => assembleCalls }
 }
 
 test('apply 把扩展登记进 router.ext 表（这张表就是「卡片出现」的唯一依据）', async () => {
@@ -163,14 +173,14 @@ test('注入：用户关掉某分类 ⇒ 该分类不进 prompt（可开关的
 
 // ── 面板编辑文本（2026-09-29）────────────────────────────────
 test('★ 每条都标 editable，面板才知道该不该给「修改」按钮', () => {
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store: fakeStore({ categories: {} }) })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store: fakeStore({ categories: {} }) })
   for (const c of ext.controls ?? []) assert.equal(c.editable, true, `${c.id} 没标 editable`)
   assert.equal(typeof ext.setControlText, 'function', '没有 setControlText ⇒ 面板点了必然 400')
 })
 
 test('★ 编辑后 controls 立刻反映新标题/新正文（每次读都重算）', () => {
   const store = fakeStore({ categories: {}, text: { identity: { title: '我是谁', body: '我是一个测试。' } } })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   const c = (ext.controls ?? []).find((x) => x.id === 'identity')!
   assert.equal(c.title, '我是谁')
   assert.equal(c.body, '我是一个测试。')
@@ -182,7 +192,7 @@ test('★ controls 不是快照：改完之后**再读一次**要看到新值',
   //   旧标题**（用户看到"保存了又变回去"）。而我当时注释写着"现算不缓存"。
   //   ⇒ 判据必须**跨两次读**才抓得住（只读一次的写法抓不到）。
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   const before = (ext.controls ?? []).find((x) => x.id === 'ladder')!
   assert.equal(before.title, '懒人梯子')
   ext.setControlText?.('ladder', { title: '我的梯子' })
@@ -192,7 +202,7 @@ test('★ controls 不是快照：改完之后**再读一次**要看到新值',
 
 test('setControlText 只写覆盖值，且不碰 categories（同块的另一种数据）', () => {
   const store = fakeStore({ categories: { identity: false }, keep: 'me' })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.setControlText?.('identity', { title: '新标题' }), true)
   const after = store.readData<Record<string, unknown>>('')
   assert.deepEqual(after?.categories, { identity: false }, '改标题把开关状态冲掉了')
@@ -207,7 +217,7 @@ test('★ 改一条**不碰其它条**的覆盖（整块重写 text 会静默丢
     categories: {},
     text: { identity: { title: 'A' }, scope: { body: 'B' } },
   })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   ext.setControlText?.('ladder', { body: '新内容' })
   assert.deepEqual(store.readData<Record<string, unknown>>('')?.text, {
     identity: { title: 'A' },
@@ -218,7 +228,7 @@ test('★ 改一条**不碰其它条**的覆盖（整块重写 text 会静默丢
 
 test('改同一条的第二个字段 ⇒ 第一个字段仍在（部分更新，不是替换）', () => {
   const store = fakeStore({ categories: {}, text: { identity: { title: 'A' } } })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   ext.setControlText?.('identity', { body: 'B' })
   assert.deepEqual(store.readData<Record<string, unknown>>('')?.text, {
     identity: { title: 'A', body: 'B' },
@@ -227,7 +237,7 @@ test('改同一条的第二个字段 ⇒ 第一个字段仍在（部分更新，
 
 test('注入：空标题/空正文返回 false（不写盘）', () => {
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   for (const bad of [{ title: '  ' }, { title: '' }, { body: '' }]) {
     assert.equal(ext.setControlText?.('identity', bad), false, `空串被接受了：${JSON.stringify(bad)}`)
   }
@@ -236,7 +246,7 @@ test('注入：空标题/空正文返回 false（不写盘）', () => {
 
 test('注入：未知 controlId 返回 false', () => {
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.setControlText?.('__evil__', { title: 'x' }), false)
 })
 
@@ -262,7 +272,7 @@ test('★ controls 走合成列表：自建条目出现、标 custom、内置标
     custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }],
     text: { ladder: { body: '改过的' } },
   })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   const list = ext.controls ?? []
   assert.equal(list.length, PROMPT_CATEGORIES.length + 1, '自建条目没出现')
   assert.equal(list.find((c) => c.id === 'cu-1')?.custom, true)
@@ -272,7 +282,7 @@ test('★ controls 走合成列表：自建条目出现、标 custom、内置标
 
 test('★ 新增自建条目 ⇒ 返回新 id，且落盘（id 不撞内置）', () => {
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   const id = ext.addCustomControl?.('我的准则', '做完了就收。')
   assert.ok(id !== null && typeof id === 'string', '没返回新 id')
   assert.notEqual(id, 'identity', '新 id 撞上了内置条目')
@@ -281,7 +291,7 @@ test('★ 新增自建条目 ⇒ 返回新 id，且落盘（id 不撞内置）',
 
 test('注入：空标题/空正文新增 ⇒ 返回 null（不写盘）', () => {
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.addCustomControl?.('  ', 'x'), null)
   assert.equal(ext.addCustomControl?.('x', ''), null)
   assert.equal(store.readData<Record<string, unknown>>('')?.custom, undefined, '失败的写入留下痕迹')
@@ -294,7 +304,7 @@ test('★ 删除只允许自定义：内置条目被拒、自建条目删掉并
     order: ['cu-1', 'ladder'],
     custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }],
   })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.removeCustomControl?.('identity'), false, '内置条目不该被删（它是代码的一部分）')
   assert.equal(ext.removeCustomControl?.('ladder'), false, '不存在的条目应被拒')
   assert.equal(ext.removeCustomControl?.('cu-1'), true)
@@ -306,7 +316,7 @@ test('★ 删除只允许自定义：内置条目被拒、自建条目删掉并
 
 test('★ 还原：只对被改过的内置条目成功，且回到内置文本', () => {
   const store = fakeStore({ categories: {}, text: { ladder: { body: '改过的' } } })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.resetControlText?.('identity'), false, '没改过的内置条目不该「可还原」')
   assert.equal(ext.resetControlText?.('cu-1'), false, '自建条目没有「内置版本」可回退')
   assert.equal(ext.resetControlText?.('ladder'), true)
@@ -318,7 +328,7 @@ test('★ 还原：只对被改过的内置条目成功，且回到内置文本'
 
 test('★ 排序：只存 id，且过滤掉不存在的 id（脏数据不留幽灵）', () => {
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.setControlOrder?.(['__ghost__', 'ladder', 'ladder']), true)
   assert.deepEqual(store.readData<Record<string, unknown>>('')?.order, ['ladder'], '幽灵/重复 id 没被过滤')
 })
@@ -330,7 +340,7 @@ test('★ 没有 data 记录时也能写（"没改过" ≠ "不能写"）', () =
   //   当成"存储不可用"直接拒 ⇒ 「添加准则」永远报 `title and body are required`
   //   ——而 title/body 明明都传了，报错还指向错误的字段，排查成本极高。
   const store = fakeStore(undefined) // **没有 data**
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   const id = ext.addCustomControl?.('我的准则', '做完就收。')
   assert.ok(id !== null, '初始状态下添加失败（真实用户第一次用就是这个状态）')
   assert.equal((ext.controls ?? []).some((c) => c.id === id), true, '写盘了但 controls 里没有')
@@ -338,7 +348,7 @@ test('★ 没有 data 记录时也能写（"没改过" ≠ "不能写"）', () =
 
 test('★ 四个写入口在"无 data"时都可用（不只是 add）', () => {
   const store = fakeStore(undefined)
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.setControl?.('ladder', false), true, '开关在初始状态下不可用')
   assert.equal(ext.setControlText?.('ladder', { body: 'x' }), true, '改文本在初始状态下不可用')
   assert.equal(ext.setControlOrder?.(['ladder']), true, '排序在初始状态下不可用')
@@ -350,7 +360,7 @@ test('★ 还原：改过 ⇒ true（且覆盖被清掉）；没改过 ⇒ false
   //   而代码是对的。**假 store 比被守的东西更宽容 = 判据无效**（第三次栽在这）。
   //   ⇒ 假 store 必须**真的读回自己写的东西**：`fakeStore` 的 `box` 已在做。
   const store = fakeStore({ categories: {} })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.resetControlText?.('identity'), false, '没改过的却说可还原')
   ext.setControlText?.('ladder', { body: '改过的' })
   assert.equal(ext.resetControlText?.('ladder'), true, '改过的却还原不了')
@@ -360,7 +370,7 @@ test('★ 还原：改过 ⇒ true（且覆盖被清掉）；没改过 ⇒ false
 // ── op 成功必须回整张表（2026-09-30）───────────────────────
 test('★ 契约层：controls 上带 custom 标记（面板据此决定给删除还是还原）', () => {
   const store = fakeStore({ categories: {}, custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }] })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   const mine = (ext.controls ?? []).find((c) => c.id === 'cu-1')
   const builtin = (ext.controls ?? []).find((c) => c.id === 'identity')
   assert.equal(mine?.custom, true, '自建条目没标 custom ⇒ 面板给"还原"而不是"删除"')
@@ -375,7 +385,7 @@ test('★ 自建条目的开关可切（判据要用合成列表，不能只用
   //   ⇒ 用户看到「自定义的开关控制报错」。而它**在 controls 列表里显示着** ——
   //   列表用 `resolveCategories`、写入判据用 `PROMPT_CATEGORIES`，两处来源不一致。
   const store = fakeStore({ categories: {}, custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }] })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal((ext.controls ?? []).some((c) => c.id === 'cu-1'), true, '列表里没有它')
   assert.equal(ext.setControl?.('cu-1', false), true, '列表里有、却切不了')
   assert.equal(store.readData<Record<string, unknown>>('')?.categories && (store.readData<{ categories: Record<string, boolean> }>('')?.categories?.['cu-1']), false, '开关没落盘')
@@ -383,14 +393,14 @@ test('★ 自建条目的开关可切（判据要用合成列表，不能只用
 
 test('★ 自建条目的文本可改（同一处来源不一致）', () => {
   const store = fakeStore({ categories: {}, custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }] })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.setControlText?.('cu-1', { title: '新标题' }), true, '自建条目改不了标题')
   assert.equal((ext.controls ?? []).find((c) => c.id === 'cu-1')?.title, '新标题')
 })
 
 test('还原仍然只允许内置条目（自建没有「内置版本」可回退）', () => {
   const store = fakeStore({ categories: {}, custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }] })
-  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [], store })
   assert.equal(ext.resetControlText?.('cu-1'), false, '自建条目不该能被「还原」')
 })
 
@@ -418,7 +428,7 @@ test('★ 图标能被真实渲染（base64 必须解得出合法 SVG）', () =>
 })
 
 test('图标挂在 ext 上（不设的话面板退回默认闪电）', () => {
-  const ext = createPromptExt({ isSystemPromptReady: () => true })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, getSections: () => [] })
   assert.equal(ext.icon, PROMPT_LOGO_URL)
 })
 

package/src/ext-prompt/index.ts

@@ -15,6 +15,14 @@
  * （宿主管的那个）。不置上的话，用户开了行还要再点一次，两级开关说同一件事。
  */
 import type { Context } from '@deepseek-ai/cordis'
+// ⚠️ **只为一个目的而 import type**：让 cordis 的 `Events` 增强
+//   （`system-prompt/assemble` / `system-prompt/change`）进入本文件所在的编译单元。
+//   不 import 的话，`ctx.on('system-prompt/assemble', …)` 的参数不是
+//   `keyof Events` ⇒ **声明构建（tsconfig.build.json，host 半边）直接报错**，
+//   而主 tsconfig 因为 include 了 `assembly.test.ts`（它 import 了同一个包）
+//   恰好把增强带进来 ⇒ `tsc --noEmit` 全绿、`npm run build` 才红。
+//   这类"两种配置下结论不同"的坑，靠显式依赖修，不靠碰巧。
+import type {} from '@deepseek-ai/dsh-system-prompt'
 import {
   currentExts,
   currentExtStore,
@@ -24,6 +32,7 @@ import {
 import { createPromptExt, EXT_PROMPT_ID } from './plugin.ts'
 import { mountPromptSection, type SystemPromptFace } from './mount.ts'
 import type { PromptExtData } from './render.ts'
+import { createSectionCache, disabledSectionNames, filterSections } from './sections.ts'
 
 /** cordis 插件身份（配置树里这一行的技术名；显示名走同目录的 locale）。 */
 export const name = 'dsh-router-ext-prompt'
@@ -76,7 +85,7 @@ export function apply(ctx: Context): void {
   const table = currentExts(ctx)
   const store = currentExtStore(ctx)
 
-  // ① 准则段落。`section()` 注册一个**provider 函数**作为 text ——
+  // ① 准则段落。`section()` 注册一个 **provider 函数**作为 text ——
   //    每次装配现算，所以改开关立即生效，无需重注册。
   const dispose = mountPromptSection({
     getSystemPrompt: () => systemPromptOf(ctx),
@@ -84,13 +93,50 @@ export function apply(ctx: Context): void {
     readData: () => store?.readData<PromptExtData>(EXT_PROMPT_ID),
   })
 
-  // ② 面板登记。幂等：同一个 id 已在表里就不顶掉别人的登记。
+  // ② 段落总控：挂 `system-prompt/assemble` waterfall —— 每轮装配时
+  //    ⑴ 先把**未过滤的全量段落**喂给清单缓存（面板的事实源，在过滤前取 ⇒
+  //    关掉的段仍列在面板上，不会"关了就消失、开不回来"）；
+  //    ⑵ 再按落盘的关段表删掉关闭的段（宿主以监听器返回值为权威结果
+  //    —— `assemble()` 的 `return transformed`，删掉的段不会被恢复）。
+  //
+  //    ⚠️ 总开关关 ⇒ 原样放行：扩展关 = 本扩展什么都不做，宿主段落恢复
+  //    自然注入（与准则段"关总开关 ⇒ 段文本空 ⇒ 整段被丢"同一语义）。
+  //    ⚠️ 监听器注册在**无 scope 标签**的 ctx 上，而派发走
+  //    `scopeTarget`（dsh-scope）：无标签监听器收一切 scope 的装配
+  //    —— 这正是宿主"全局注册、参与所有 agent 装配"的通道，与准则
+  //    section 进 prompt 同一条 scope 规则。
+  const cache = createSectionCache()
+  let disposeAssemble: (() => boolean) | undefined
+  let disposeChange: (() => boolean) | undefined
+  const sp = systemPromptOf(ctx)
+  if (sp) {
+    disposeAssemble = ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      const result = await next()
+      cache.update(result.sections)
+      if (store?.isEnabled(EXT_PROMPT_ID) !== true) return result
+      const off = disabledSectionNames(store.readData<PromptExtData>(EXT_PROMPT_ID))
+      if (off.size === 0) return result
+      return { ...result, sections: filterSections(result.sections, off) }
+    })
+    // 段在**没有新装配时**增删（插件开关变化等）⇒ 面板清单不会自己更新，
+    // 主动跑一次 assemble 刷新（它会再走上面的 waterfall ⇒ 缓存唯一写入点）。
+    disposeChange = ctx.on('system-prompt/change', () => {
+      void sp.assemble().catch(() => { /* 预热失败不致命：下次装配自然补上 */ })
+    })
+    // 预热：一次对话都还没发生时，面板也要有清单（无 scope 的 global 近似）。
+    void sp.assemble().catch(() => { /* 同上 */ })
+  }
+
+  // ③ 面板登记。幂等：同一个 id 已在表里就不顶掉别人的登记。
   if (table !== undefined && table[EXT_PROMPT_ID] === undefined) {
     table[EXT_PROMPT_ID] = createPromptExt({
       isSystemPromptReady: () => !!systemPromptOf(ctx),
       // ⚠️ **store 必须在这时就能拿到**：拿不到的话面板上的分类开关显示可点、
       //   点了 400 —— 「看起来能用但不能用」比「不显示」更难查。
       store,
+      // 段清单来自 waterfall 缓存（若 ② 没挂上 ⇒ 空清单 ⇒ 段组不显示，
+      // 但不许这里给缺省 —— 见 createPromptExt 的 deps 注释）。
+      getSections: () => cache.list(),
     })
     store?.setEnabled(EXT_PROMPT_ID, true)
     // 核心持有的是**同一个 live 对象**（它 provide 的空表），且 `/ext` 每次请求都
@@ -99,6 +145,8 @@ export function apply(ctx: Context): void {
 
   ctx.effect(() => () => {
     dispose()
+    disposeAssemble?.()
+    disposeChange?.()
     if (table !== undefined) delete table[EXT_PROMPT_ID]
   })
 }

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

@@ -7,7 +7,7 @@
  */
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { mountPromptSection, PROMPT_SECTION_NAME } from './mount.ts'
+import { mountPromptSection, PROMPT_SECTION_NAME, OFFICIAL_LOWEST_SECTION_ORDER } from './mount.ts'
 import { EXT_PROMPT_ID } from './plugin.ts'
 
 /** 记录注册内容的假 systemPrompt。 */
@@ -25,6 +25,11 @@ function fakeSystemPrompt() {
         disposals++
       }
     },
+    // 本文件测的是注册契约，不碰装配；给最小合法实现满足 `SystemPromptFace`
+    //（段清单与过滤的单测在 sections.test.ts / ext-prompt.test.ts）。
+    async assemble() {
+      return { sections: [] }
+    },
   }
 }
 
@@ -35,6 +40,18 @@ test('注册恰好一个段落，名字稳定', () => {
   assert.equal(sp.registered[0]!.name, PROMPT_SECTION_NAME)
 })
 
+test('★ 段落 order 排在官方最低槽之前（2026-10-21 用户点名：准则放最前）', () => {
+  // 判据不写"是最小的"（谁将来再往前挪就误伤），写成**必须低于官方第一方最低槽**：
+  // 第一方开场白 `harness:identity` 在 -1000，别的部署可能没关它。
+  const sp = fakeSystemPrompt()
+  mountPromptSection({ getSystemPrompt: () => sp, isEnabled: () => true, readData: () => undefined })
+  const order = sp.registered[0]!.order
+  assert.ok(
+    order < OFFICIAL_LOWEST_SECTION_ORDER,
+    `order=${order} 未低于官方最低槽 ${OFFICIAL_LOWEST_SECTION_ORDER} ⇒ 准则排不到最前`,
+  )
+})
+
 test('⚠️ text 必须是 provider 函数而不是静态字符串（否则改开关不生效）', () => {
   const sp = fakeSystemPrompt()
   mountPromptSection({ getSystemPrompt: () => sp, isEnabled: () => true, readData: () => undefined })

package/src/ext-prompt/mount.ts

@@ -20,21 +20,36 @@ import { renderPromptText, type PromptExtData } from './render.ts'
 /** `ctx.systemPrompt` 的最小可见面。 */
 export interface SystemPromptFace {
   section(section: { name: string; order: number; text: string | (() => string) }): () => void
-  getSectionOrder?(name: string): number
+  /**
+   * 段落总控用（`index.ts` 的 waterfall 预热）：宿主 `SystemPrompt.assemble()`。
+   * 只声明用得到的最小形状 —— 返回的 `sections` 已按 order/name 排好序。
+   */
+  assemble(context?: Record<string, unknown>): Promise<{ sections: { name: string; text: string }[] }>
 }
 
 /** 段落名（**稳定**）：改名会让已注册的作用域 section 与旧名并存。 */
 export const PROMPT_SECTION_NAME = 'dsh-router-ext-prompt:guideline'
 
 /**
- * 段落 order：100。
+ * 段落 order：**-2000 = 全场最前**（2026-10-21 用户点名「把准则放到最前」）。
+ *
+ * 官方分配的槽位（`dsh-system-prompt` 的 `SECTION_ORDERS`）最低一档是
+ * `HARNESS_IDENTITY: -1000`（第一方开场白 `You are an AI agent powered by
+ * DeepSeek Harness.`），其后才是 `DEPLOYMENT_PERSONA_PREFIX: 0`、`PLAN_POLICY: 500`
+ * … `HARNESS_SOURCE: 10000`。
  *
- * 官方分配的槽位（`dsh-system-prompt` 的 `SECTION_ORDERS`）：
- * `PERSONA_PREFIX: 0` · `PLAN_POLICY: 500` · `TEAM_POLICY: 600` …·
- * 取 100 = 紧随 persona、远早于任何工具段 ⇒ 准则出现在身份之后、工具说明之前，
- * 与用户看到的记忆快照位置一致。
+ * 取 **-2000**（低于官方最低槽 1000）而不是「正好 -1000」：
+ *   - 撞在 -1000 上要靠**段名的字母序**决胜（`comparePromptSections` 是
+ *     `order` 再按 `name`）—— 那是实现细节，改段名就翻盘，不作为位置依据；
+ *   - 第一方那行在本部署被 `includeHarnessIdentity: false` 关掉了，但**别的
+ *     部署可能还开着** ⇒ 准则仍须排在它前面，不能假设它不存在。
+ *
+ * ⚠️ `order` 只要求有限数（`Number.isFinite`），负数合法。
  */
-const SECTION_ORDER = 100
+const SECTION_ORDER = -2000
+
+/** 官方 `SECTION_ORDERS` 里最低的那档（第一方开场白），测试用它当"最前"的判据。 */
+export const OFFICIAL_LOWEST_SECTION_ORDER = -1000
 
 export interface MountPromptDeps {
   /** 取 `ctx.systemPrompt`（可能尚未就绪 ⇒ undefined）。 */

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 实测踩过）：接入自建条目后调用方传的是