dsh-router-core 0.4.6 → 0.4.7

package/src/client/router.css

@@ -3360,6 +3360,25 @@ html[data-dsh-router-active]:not([data-dsh-taskboard-active]):not(
     list-style: none;
 }
 
+/* 分组标题行 —— `ExtControl.group` 的渲染落点，插在 `.dshr-compRows` 里
+   的非交互 <li>（无拖把/开关，不可点）。与 `compTitle` 的区别：那是详情页
+   主标题（页头），这是**组**名（次要色 + 小字号）。左右 14px 对齐
+   `.dshr-compRow` 的行内缩，组名与行文字左缘一致。 */
+.dshr-extGroupTitle {
+    margin: 14px 0 2px;
+    padding: 0 14px;
+    color: var(--dsw-alias-label-tertiary);
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 18px;
+    list-style: none;
+}
+
+/* 全部分组的扩展：首个渲染节点就是组标题，去掉上边距避免顶双空。 */
+.dshr-extGroupTitle:first-child {
+    margin-top: 0;
+}
+
 .dshr-compRow {
     display: flex;
     align-items: center;
@@ -3489,7 +3508,7 @@ html[data-dsh-router-active]:not([data-dsh-taskboard-active]):not(
     overflow-wrap: anywhere;
     /* 保留换行：子开关的**原文**是这个类的另一个用法（2026-09-29 合并进来），
        它是多行段落。状态文案都是单行，所以这条对它们没有副作用。
-       ⇒ 原来的 `.dshr-compRowBody` 整块删掉：14 条规则的正文不需要左边框 +
+       ⇒ 原来的 `.dshr-compRowBody` 整块删掉：各条规则的正文不需要左边框 +
        缩进那种「引用块」的额外装饰（用户要求），层级只靠颜色就够。 */
     white-space: pre-wrap;
 }

package/src/ext/contract.ts

@@ -68,7 +68,7 @@ export interface RouterExt {
    * 扩展自带的**子开关**（可选；不声明 = 只有总开关）。
    *
    * 为什么需要：有些扩展的「开/关」不是一件事而是**几件独立的事** —— 例如分层
-   * 提示词有 14 个准则分类，每条都该能单独关。硬塞进一个总开关 = 要么全给、
+   * 提示词的准则分类，每条都该能单独关。硬塞进一个总开关 = 要么全给、
    * 要么全不给。
    *
    * ⚠️ **与总开关的关系**：子开关是**叠加**在总开关之上的，总开关关 ⇒ 全部子开关
@@ -179,6 +179,25 @@ export interface ExtControl {
   readonly custom?: boolean
   /** 文本被用户改过（决定「还原」按钮是否可点）。 */
   readonly overridden?: boolean
+  /**
+   * 分组名（可选；缺省 = 无组）—— 面板按它把控制条**分节**渲染，组间插一条
+   * 组标题行，组内顺序照旧。**无组的条目照旧平铺** ⇒ 没用这个字段的扩展
+   * （ext-test 等）面板行为一个像素都不变。
+   *
+   * 为什么要有：一条扩展同时管两类东西时（分层提示词 = 准则分类 + 宿主段落），
+   * 平铺成一长列会让"哪条是准则、哪条是宿主的段"无从分辨 —— 分组是**归属
+   * 信息**，不是样式。
+   */
+  readonly group?: string
+  /**
+   * 这一条参与拖动排序（可选；缺省 = 参与，保持既有行为）。
+   *
+   * 为什么需要显式关掉：排序落盘只认扩展自己的条目 id（`setControlOrder`
+   * 过滤未知 id）—— 宿主段落的 id 不在其中，拖它只会被静默丢弃 ⇒ 看起来能拖、
+   * 松手弹回，是假交互。**由扩展逐条声明**，与 `editable` 同一理由：能力在
+   * 实现方手里，由它说哪条有。
+   */
+  readonly sortable?: boolean
 }
 
 /** 面板/API 用的一条扩展器信息 = 核心存的开关 + 插件报的运行时事实。 */

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

@@ -18,6 +18,7 @@ import { SystemPrompt, renderPrompt, type PromptAssembly } from '@deepseek-ai/ds
 import { mountPromptSection, PROMPT_SECTION_NAME } from './mount.ts'
 import { renderPromptText } from './render.ts'
 import { PROMPT_CATEGORIES } from './content.ts'
+import { createSectionCache, disabledSectionNames, filterSections } from './sections.ts'
 
 /** 起一个真 systemPrompt 并挂上本扩展。 */
 async function assemble(
@@ -77,3 +78,65 @@ test('装配结果与 renderPromptText 的内容一致（渲染逻辑只有一
   const expected = renderPromptText(true, undefined)
   assert.ok(text.includes(expected), '装配结果里找不到 renderPromptText 的输出 ⇒ 两处实现漂移了')
 })
+
+// ── 段落总控：真宿主装配链上的"关了就没了"（2026-10-21）──────────
+/**
+ * ⚠️ 这里才是段落总控的**终局判据**。前面 `section-filter.test.ts` 验的是
+ * "监听器按规则返回了什么"，而"宿主真把那个返回值当成最终装配"是**另一件事**
+ * —— 宿主源码里 waterfall 之后还有 complete-section 恢复、runtime-context
+ * 抑制等收尾，任何一处改动都可能让我们删的段回来。只有跑真 `assemble()`
+ * 才能钉住。
+ */
+async function assembleWithSections(
+  opts: { masterOn?: boolean; data?: unknown },
+): Promise<{ names: string[]; text: string; dispose: () => void }> {
+  const ctx = new Context()
+  new SystemPrompt(ctx, { includeHarnessIdentity: true, personaPrefix: 'PERSONA-PREFIX-SENTINEL' })
+  let enabled = true
+  const cache = createSectionCache()
+  // 与 index.ts 的监听器**同一形状**：先 next()、喂清单、再按落盘过滤
+  const offAssemble = ctx.on('system-prompt/assemble', async (assembly, _c, next) => {
+    const result = await next()
+    cache.update(result.sections)
+    if ((opts.masterOn ?? enabled) !== true) return result
+    const off = disabledSectionNames(opts.data as never)
+    if (off.size === 0) return result
+    return { ...result, sections: filterSections(result.sections, off) }
+  })
+  // 本扩展自己的准则段（带正文哨兵，便于断言它没被段开关删掉）
+  const dispose = mountPromptSection({
+    getSystemPrompt: () => ctx.systemPrompt,
+    isEnabled: () => true,
+    readData: () => undefined,
+  })
+  await new Promise((r) => setTimeout(r, 10))
+  const a = await ctx.systemPrompt.assemble({})
+  return {
+    names: a.sections.map((s) => s.name),
+    text: renderPrompt(a),
+    dispose: () => { offAssemble(); dispose(); void ctx },
+  }
+}
+
+test('★ 真装配链：关掉某段落 ⇒ 它真的不在最终 prompt 里', async () => {
+  const on = await assembleWithSections({})
+  // 宿主自带的段（关掉 includeHarnessIdentity 也仍在表里的话更好，但优先用我们自己的）
+  assert.ok(on.names.includes(PROMPT_SECTION_NAME), `准则段不在装配里：${on.names.join(', ')}`)
+  const target = on.names.find((n) => n === 'deployment:persona-prefix')
+  assert.ok(target !== undefined, `找不到宿主 persona 段，实际段名：${on.names.join(', ')}`)
+  on.dispose()
+
+  const off = await assembleWithSections({ data: { sections: { [target]: false } } })
+  assert.equal(off.names.includes(target), false, `真装配链里 ${target} 关了却还在`)
+  assert.equal(off.text.includes('PERSONA-PREFIX-SENTINEL'), false, '段没了但正文还在 ⇒ 过滤没生效')
+  // 反向：别的段与准则不能陪葬
+  assert.ok(off.names.includes(PROMPT_SECTION_NAME), '关别人的段时把准则段一起删了')
+  off.dispose()
+})
+
+test('★ 真装配链：总开关关 ⇒ 一个段都不动（扩展关 = 不干预宿主）', async () => {
+  const r = await assembleWithSections({ masterOn: false, data: { sections: { 'deployment:persona-prefix': false } } })
+  assert.ok(r.names.includes('deployment:persona-prefix'), '总开关关掉后仍在过滤 ⇒ 关了还生效')
+  assert.ok(r.text.includes('PERSONA-PREFIX-SENTINEL'), '总开关关掉后 persona 正文不见了')
+  r.dispose()
+})

package/src/ext-prompt/content.ts

@@ -20,6 +20,12 @@
  *      —— 它没有终止条件，每次收口都必然能再找出一件存量，等于无限循环。
  *   ② 固化：由"每次用户可见损失都必须固化"降级为"只对数据丢失/安全这类真损失
  *      补检查"，并删掉「不固化的教训等于决定再犯一次」这句无界义务。
+ *
+ * ⚠️ 2026-10-17 用户点名的两处改动：
+ *   ① **删掉「固化」分类**（整条移除，id `hardening` 不复存在）。用户已存的
+ *      `categories`/`text`/`order` 里残留的 `hardening` 键无须迁移 ——
+ *      `resolveCategories` 规则 2 会忽略不认识的 id。
+ *   ② 身份气质：「默认中文」→「回复、思考过程必须使用中文」。
  */
 
 /** 一个可独立开关的提示词分类。 */
@@ -45,7 +51,7 @@ export const PROMPT_CATEGORIES: readonly PromptCategory[] = [
     title: '身份气质',
     defaultOn: true,
     body:
-      '身份气质：大肥鱼 🐋(资深开发者)；懒=高效不是马虎；安静、克制、直接；默认中文，直接给能跑的东西。',
+      '身份气质：大肥鱼 🐋(资深开发者)；懒=高效不是马虎；安静、克制、直接；回复、思考过程必须使用中文，直接给能跑的东西。',
   },
   {
     id: 'scope',
@@ -80,14 +86,6 @@ export const PROMPT_CATEGORIES: readonly PromptCategory[] = [
       '②反查重复：新旧成两份就并成一处；③反查形状：该合的合、该归档的归位。' +
       '做完那块区域该比动手前更整或更少。',
   },
-  {
-    id: 'hardening',
-    title: '固化',
-    defaultOn: true,
-    body:
-      '固化：只对数据丢失/安全这类真损失补检查——会变红(注入违规必须失败)、可重放(一条命令)、' +
-      '归属清晰(失败信息指向违规处)；普通 bug 修好即止，不额外造闸门。',
-  },
   {
     id: 'verdifiable',
     title: '可判定',
@@ -155,7 +153,7 @@ export const PROMPT_CATEGORIES: readonly PromptCategory[] = [
  *
  * ⚠️ 拆分时差点丢它：原文是 `[…] ·身份气质：…`，标题挂在方括号里、
  *   **不属于任何单条分类**，按分隔符切分时自然被丢掉
- *   （只在 `content.ts` 头注出现过、没进任何 `body`）。⇒ 模型会看到 14 条
+ *   （只在 `content.ts` 头注出现过、没进任何 `body`）。⇒ 模型会看到一堆
  *   **没有名字**的规则，而"这套东西叫什么、为什么存在"恰恰是它需要的上下文。
  *
  * 形状：**不属于任何分类** ⇒ 不可被单条开关关掉（它一关，准则就无名无姓）。

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）。 */