dsh-router-core 0.4.1 → 0.4.3

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

@@ -0,0 +1,256 @@
+/**
+ * 纯逻辑单测 —— 分类开关的语义。
+ *
+ * 纪律：每条"注入违规必须失败"的用例都在这里。判据不靠自述，靠**注入反例**：
+ * 下面 `注入` 系列就是把已知坏输入喂进去、断言它**不会**被当成正常处理。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  resolveEnabledCategories,
+  renderCategories,
+  renderPromptText,
+  resolveCategories,
+  knownCategoryIds,
+  type PromptExtData,
+} from './render.ts'
+import { PROMPT_CATEGORIES, PROMPT_TITLE, defaultToggles } from './content.ts'
+
+// ── 分类表本身 ────────────────────────────────────────────────
+test('分类 id 唯一（重名会让开关互相覆盖）', () => {
+  const ids = PROMPT_CATEGORIES.map((c) => c.id)
+  assert.equal(new Set(ids).size, ids.length, `重复 id：${ids.join(',')}`)
+})
+
+test('每个分类正文非空（空正文 = 该分类注入了但什么都不说）', () => {
+  for (const c of PROMPT_CATEGORIES) {
+    assert.ok(c.body.trim().length > 0, `${c.id} 正文为空`)
+  }
+})
+
+test('默认开关全覆盖，且默认开的分类占多数（准则骨架不能默认关）', () => {
+  const t = defaultToggles()
+  for (const id of knownCategoryIds()) assert.equal(typeof t[id], 'boolean')
+  const on = PROMPT_CATEGORIES.filter((c) => c.defaultOn).length
+  assert.ok(on >= PROMPT_CATEGORIES.length / 2, `默认开只有 ${on}/${PROMPT_CATEGORIES.length}`)
+})
+
+// ── 开关解析 ──────────────────────────────────────────────────
+test('总开关关 ⇒ 一条都不渲染（不是"空段落"，是完全没有）', () => {
+  const on = resolveEnabledCategories(false, undefined)
+  assert.equal(on.size, 0)
+  assert.equal(renderPromptText(false, undefined), '')
+})
+
+test('总开关开、无数据 ⇒ 走 defaultOn', () => {
+  const on = resolveEnabledCategories(true, undefined)
+  for (const c of PROMPT_CATEGORIES) {
+    assert.equal(on.has(c.id), c.defaultOn, `${c.id} 解析与 defaultOn 不符`)
+  }
+})
+
+test('用户显式关掉某分类 ⇒ 该分类不渲染（这是"可开关"的正向判据）', () => {
+  const data: PromptExtData = { categories: { identity: false } }
+  const on = resolveEnabledCategories(true, data)
+  assert.equal(on.has('identity'), false)
+  assert.equal(renderPromptText(true, data).includes('大肥鱼'), false)
+})
+
+test('用户显式开某分类 ⇒ 该分类渲染（默认关的分类也能被打开）', () => {
+  const data: PromptExtData = { categories: { identity: true } }
+  assert.equal(renderPromptText(true, data).includes('大肥鱼'), true)
+})
+
+test('false 与 undefined 语义不同：显式 false 不被 defaultOn 覆盖', () => {
+  // identity 默认开；用户显式关掉后，仍必须是关的
+  const on = resolveEnabledCategories(true, { categories: { identity: false } })
+  assert.equal(on.has('identity'), false, '显式 false 被 defaultOn 覆盖 = 用户选择被静默丢弃')
+})
+
+// ── 注入违规：坏输入不得被静默接受 ────────────────────────────
+test('注入：categories 不是对象 ⇒ 当作没配，不炸不吞（total crash 是不合格行为）', () => {
+  for (const bad of [null, 'x', 42, [] as unknown]) {
+    const data = { categories: bad } as unknown as PromptExtData
+    // 直接调用：真抛了测试自然失败，不需要 doesNotThrow 再包一层。
+    const text = renderPromptText(true, data)
+    // 非法数据 ⇒ 回落到默认值，且仍然产出文本（不能因为数据坏就丢掉整个准则）
+    assert.ok(text.length > 0, `categories=${JSON.stringify(bad)} 导致准则整体消失`)
+  }
+})
+
+test('注入：未知分类 id 被忽略，不进渲染（防止脏数据塞进 prompt）', () => {
+  const data: PromptExtData = {
+    categories: { identity: true, __evil__: true, '../../etc/passwd': true },
+  }
+  const on = resolveEnabledCategories(true, data)
+  assert.equal(on.has('__evil__'), false)
+  assert.equal(on.has('../../etc/passwd'), false)
+  const text = renderPromptText(true, data)
+  assert.equal(text.includes('__evil__'), false)
+  assert.equal(text.includes('passwd'), false)
+})
+
+test('注入：非布尔真值（"false" 字符串）不当作 true（否则用户写了字符串=静默反转选择）', () => {
+  // 注意：TS 类型上这是非法的，但落盘 JSON 不可信 —— 判据必须在运行时守住
+  const data = { categories: { identity: 'false' as unknown as boolean } }
+  const on = resolveEnabledCategories(true, data)
+  // 'false' 既非 undefined 也非 true ⇒ 不进 enabled（保守：不猜）
+  assert.equal(on.has('identity'), false, '字符串 "false" 被当成开启 = 用户选择被反转')
+})
+
+// ── 渲染 ──────────────────────────────────────────────────────
+test('渲染：每个开启的分类正文都出现一次', () => {
+  const text = renderPromptText(true, undefined)
+  for (const c of PROMPT_CATEGORIES) {
+    if (!c.defaultOn) continue
+    const n = text.split(c.body).length - 1
+    assert.equal(n, 1, `${c.id} 出现 ${n} 次（期望 1）`)
+  }
+})
+
+test('渲染：顺序与分类表一致（准则是有先后的执行流程）', () => {
+  const text = renderPromptText(true, undefined)
+  const positions = PROMPT_CATEGORIES
+    .filter((c) => c.defaultOn)
+    .map((c) => text.indexOf(c.body))
+  for (let i = 1; i < positions.length; i++) {
+    assert.ok(
+      positions[i]! > positions[i - 1]!,
+      `第 ${i} 个分类位置 ${positions[i]} 未排在第 ${i - 1} 个 ${positions[i - 1]} 之后`,
+    )
+  }
+})
+
+test('渲染：全关 ⇒ 空串（空串会让上游丢弃该段，不是"注入一段空白"）', () => {
+  const off: Record<string, boolean> = {}
+  for (const id of knownCategoryIds()) off[id] = false
+  assert.equal(renderPromptText(true, { categories: off }), '')
+})
+
+test('注入：renderCategories 传外部分类表时只渲染其中启用的（可扩展性）', () => {
+  const custom = [
+    { id: 'x', title: 'X', defaultOn: true, body: 'X-BODY' },
+    { id: 'y', title: 'Y', defaultOn: true, body: 'Y-BODY' },
+  ]
+  // ⚠️ `withTitle = false` 必须**显式**传：原先靠「传的不是 PROMPT_CATEGORIES
+  //   那个对象」来隐式决定加不加标题（`categories === PROMPT_CATEGORIES`）。
+  //   接入自建条目后调用方传的是合成列表，那个判定恒假 ⇒ 标题静默消失。
+  const out = renderCategories(new Set(['y']), custom, undefined, false)
+  assert.equal(out, 'Y-BODY')
+})
+
+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, '标题必须在最前面 —— 它要解释后面的规则')
+})
+
+test('全关时标题也不出现（不能有一套叫准则 v5 的东西却一条规则都没有）', () => {
+  const off: Record<string, boolean> = {}
+  for (const id of knownCategoryIds()) off[id] = false
+  const text = renderPromptText(true, { categories: off })
+  assert.equal(text, '', '只剩标题 = 一套空准则，比没有更糟')
+})
+
+// ── 面板编辑文本（2026-09-29）────────────────────────────────
+test('★ 改过的正文真的进 prompt（不是只改了显示）', () => {
+  // ⚠️ 这是"编辑"这件事的**全部意义所在**：漏了这一步，面板改了字、prompt
+  //   里还是旧的，而用户会以为成功了 —— 最坏的"看起来成功"。
+  const data: PromptExtData = { text: { ladder: { body: '梯子：只走第一档。' } } }
+  const text = renderPromptText(true, data)
+  assert.ok(text.includes('梯子：只走第一档。'), '编辑后的正文没进 prompt')
+  assert.equal(text.includes('停在第一个成立的档'), false, '旧的正文还在')
+})
+
+test('改过的标题不影响正文（两个字段各管各的）', () => {
+  const data: PromptExtData = { text: { identity: { title: '我是谁' } } }
+  const text = renderPromptText(true, data)
+  assert.ok(text.includes('大肥鱼'), '只改标题不该动正文')
+})
+
+test('注入：空串覆盖被忽略（不能把一条规则"变成空的"）', () => {
+  const data: PromptExtData = { text: { ladder: { body: '' } } }
+  const text = renderPromptText(true, data)
+  assert.ok(text.includes('停在第一个成立的档'), '空串把这条规则清空了 —— 看起来像被关了')
+})
+
+test('未改过的分类不出现在 text 里（内置内容仍是唯一事实源）', () => {
+  // 只存覆盖值：用户改一个字就永久冻结整段是反效果，内置更新要能继续生效
+  const data: PromptExtData = { text: { identity: { body: '我是谁。' } } }
+  const text = renderPromptText(true, data)
+  assert.ok(text.includes('停在第一个成立的档'), '只改了一条，其余应仍跟内置走')
+})
+
+test('注入：text 不是对象时不炸（脏数据不该让整段准则消失）', () => {
+  for (const bad of ['x', 42, []] as unknown[]) {
+    const data = { text: bad } as unknown as PromptExtData
+    const text = renderPromptText(true, data)
+    assert.ok(text.includes('停在第一个成立的档'), `text=${JSON.stringify(bad)} 把准则弄没了`)
+  }
+})
+
+// ── 排序 / 自建 / 还原（2026-09-29）─────────────────────────
+test('★ 自建条目真的进 prompt（不是只出现在面板上）', () => {
+  const data: PromptExtData = { custom: [{ id: 'my-1', title: '我的准则', defaultOn: true, body: '我的准则：做完就修。' }] }
+  const text = renderPromptText(true, data)
+  assert.ok(text.includes('我的准则：做完就修。'), '自建条目没进 prompt')
+  assert.ok(text.indexOf('我的准则') > text.indexOf('执行：'), '自建条目应排在内置之后')
+})
+
+test('★ 拖动排序真的改变 prompt 里的顺序', () => {
+  const ids = PROMPT_CATEGORIES.map((c) => c.id)
+  const flipped = [...ids].reverse()
+  const text = renderPromptText(true, { order: flipped })
+  assert.ok(
+    text.indexOf('执行：') < text.indexOf('身份气质：'),
+    '倒序后 prompt 里顺序没变 ⇒ 拖动只改了面板',
+  )
+})
+
+test('★ 还原（删掉覆盖）后回到内置文本', () => {
+  const edited = renderPromptText(true, { text: { ladder: { body: '改过的' } } })
+  assert.ok(edited.includes('改过的'))
+  const restored = renderPromptText(true, {}) // 还原 = data.text 里没有该键
+  assert.ok(!restored.includes('改过的'))
+  assert.ok(restored.includes('停在第一个成立的档'))
+})
+
+test('注入：order 里的未知 id 被忽略，不影响其它条目', () => {
+  const text = renderPromptText(true, { order: ['__nope__', 'ladder', 'identity'] })
+  assert.ok(text.includes('停在第一个成立的档'), '合法条目被脏 id 连累掉了')
+  assert.equal(text.includes('__nope__'), false)
+})
+
+test('注入：order 漏掉的条目补在后面（丢一条 ≠ 它消失）', () => {
+  const text = renderPromptText(true, { order: ['ladder'] })
+  // ⚠️ 只查**默认开启**的那些：万一将来加进默认关的分类（如某天新增的实验项），
+  //   它本就不该出现在 prompt 里，否则这条判据会把它误判成"被 order 吞了"。
+  //   （这条判据第一次红就是因为假设了"全部开启"—— 比被守的逻辑宽；
+  //    当年的例子是 `ocr` 那条分类，它 2026-09-30 已整条移出内置，见 git 历史。）
+  for (const c of PROMPT_CATEGORIES) {
+    if (!c.defaultOn) continue
+    assert.ok(text.includes(c.body.slice(0, 8)), `${c.id} 在 order 里缺席就消失了`)
+  }
+})
+
+test('注入：脏的 custom 条目（空 id / 空正文）被过滤', () => {
+  const data = { custom: [
+    { id: '', title: 'x', defaultOn: true, body: '空 id' },
+    { id: 'ok', title: 'y', defaultOn: true, body: '' },
+    { id: 'good', title: 'z', defaultOn: true, body: '好的' },
+  ] } as unknown as PromptExtData
+  const text = renderPromptText(true, data)
+  assert.ok(text.includes('好的'), '合法自建条目被脏数据连累')
+  assert.equal(text.includes('空 id'), false)
+})
+
+test('resolveCategories：内置在前、自建在后（代码顺序不被用户拖动改写）', () => {
+  const list = resolveCategories({ custom: [{ id: 'c1', title: 'C', defaultOn: true, body: 'B' }] })
+  assert.equal(list[list.length - 1]?.id, 'c1', '自建条目应排在最后')
+  assert.equal(list[0]?.custom, false)
+  assert.equal(list[list.length - 1]?.custom, true)
+})

package/src/ext-prompt/render.ts

@@ -0,0 +1,216 @@
+/**
+ * 纯逻辑层 —— 分类开关的读取、校验与 prompt 文本渲染。
+ *
+ * 为什么单独成文件：**不 import cordis / 任何 DSH 包**，所以能被 `node --test`
+ * 直接跑。DSH 侧的注册/挂载（ext.ts / inject.ts）只是薄壳；所有会出错的判断
+ * 都在这里，且这里能注入违规用例证明它们会变红。
+ */
+import { PROMPT_CATEGORIES, PROMPT_TITLE, type PromptCategory } from './content.ts'
+
+/** 落盘在 `router.extStore` 数据块里的形状。 */
+export interface PromptExtData {
+  /** 分类开关：`{ [categoryId]: boolean }`。缺项走 `defaultOn`。 */
+  categories?: Record<string, boolean>
+  /**
+   * 用户在面板里改过的文本：`{ [categoryId]: { title?, body? } }`。
+   *
+   * ⚠️ **与 `categories` 分开两个键**：开关是"开不开"、文本是"写成什么样"。
+   *   挤在一个键里，改标题会顺手碰到开关状态（`writeData` 是**整块替换**，
+   *   少一个键就是少一份数据）。
+   *
+   * ⚠️ **只存覆盖值，不存全文**：没改过的分类不出现在这里 ⇒ 内置内容仍是唯一
+   *   事实源，升级内置文案时没改过的那几条会跟着更新。存全文 = 用户改一个字
+   *   就永久冻结了整段，之后内置更新对它们完全失效。
+   */
+  text?: Record<string, PromptCategoryOverride>
+  /**
+   * 用户自建的准则条目。**与内置的 `PROMPT_CATEGORIES` 分开存** ——
+   * 内置那 14 条是**代码常量**（发版即定），混在一起就会出现"代码里有一条、
+   * 落盘里又有一条"的归属问题：升级时新加的内置条目会和用户的旧数据打架。
+   *
+   * 存的是**完整条目**（不是覆盖值）：自建的东西没有"内置版本"可回退。
+   */
+  custom?: PromptCategory[]
+  /**
+   * 展示顺序：`[id, …]`，含内置与自建。
+   *
+   * ⚠️ **只存 id 顺序，不重排内置数组本身**：内置 14 条的次序是 `content.ts`
+   *   里的代码顺序，它同时是"准则作为一份文档的阅读顺序"；让用户拖动去改它，
+   *   等于让代码顺序随某个用户的操作漂移 —— 别人拿到新版本看到的次序就变了。
+   *   落盘只记"这次会话里按什么顺序显示"，代码顺序永远是兜底。
+   */
+  order?: string[]
+}
+
+/** 一条分类上用户改过的字段（只记改了的那些）。 */
+export interface PromptCategoryOverride {
+  title?: string
+  body?: string
+}
+
+/** 解出某分类**生效用**的文本：用户覆盖优先，否则用内置的。 */
+export function effectiveText(
+  id: string,
+  override: PromptCategoryOverride | undefined,
+  base: PromptCategory,
+): { title: string; body: string } {
+  return {
+    // ⚠️ 空串是**非法**覆盖（写入端已挡），万一脏数据进来了也不能让它把
+    //   分类"变成空的" —— 那会让那条规则凭空消失，看起来像被关了。
+    title: override?.title !== undefined && override.title !== '' ? override.title : base.title,
+    body: override?.body !== undefined && override.body !== '' ? override.body : base.body,
+  }
+}
+
+/** 分类 id 的全集（校验用）。 */
+export function knownCategoryIds(): string[] {
+  return PROMPT_CATEGORIES.map((c) => c.id)
+}
+
+/**
+ * 解出「哪些分类要渲染」。
+ *
+ * 三层语义，**顺序不可换**：
+ *   ① 总开关关 ⇒ 一条都不渲染（不是"渲染但没内容"——那样面板显示已开启、实际无效果）；
+ *   ② 数据块里显式写了的分类，用**用户存的值**（含显式 `false`）；
+ *   ③ 没写过的分类，用 `defaultOn`。
+ *
+ * ⚠️ 为什么 ② 要区别于「没写」：`false` 与 `undefined` 语义完全不同 ——
+ * 前者是用户主动关掉，后者是"没碰过"。把两者当同一件事，用户第一次关掉某分类
+ * 后升级插件、新增同名分类，那条就永远是关的（用户没要求过）。
+ */
+export function resolveEnabledCategories(
+  masterOn: boolean,
+  data: PromptExtData | undefined,
+): Set<string> {
+  const out = new Set<string>()
+  if (!masterOn) return out
+  const saved = data?.categories
+  // ⚠️ 遍历的是**合成后的列表**（内置 + 自建），不是内置常量 ——
+  //   否则自建条目的开关永远算不出来（它不在 PROMPT_CATEGORIES 里）。
+  for (const c of resolveCategories(data)) {
+    const v = saved ? saved[c.id] : undefined
+    if (v === undefined) {
+      if (c.defaultOn) out.add(c.id)
+    } else if (v === true) {
+      out.add(c.id)
+    }
+  }
+  return out
+}
+
+/**
+ * 渲染成**一个**段落文本（多分类拼一起）。
+ *
+ * 为什么要拼成一段而不是一段一个：面板开关是"分类"粒度，而 prompt 读起来
+ * 是一段连续的准则 —— 分成 14 个 section 会让 KV cache 每个分类各占一段、
+ * 增删任意一个分类都让其后全部位移。这里**注册一个 section，文本由开关拼装**。
+ *
+ * @returns 关闭的分类不进结果；全关 ⇒ 空串（上游 `renderPrompt` 会丢弃空段）。
+ */
+export function renderCategories(
+  enabled: ReadonlySet<string>,
+  categories: readonly PromptCategory[] = PROMPT_CATEGORIES,
+  overrides?: PromptExtData['text'],
+  /** 有没有加整段标题。默认 true；传**外部分类表**时传 false（见下方注释）。 */
+  withTitle = true,
+): string {
+  const lines: string[] = []
+  for (const c of categories) {
+    if (!enabled.has(c.id)) continue
+    // ⚠️ **这里用覆盖后的 body** —— 面板改的内容必须真的进 prompt。
+    //   漏了这一行，编辑就只是改了**显示**（用户会以为改了却没生效，
+    //   而 prompt 里还是旧的 ⇒ 最坏的一种"看起来成功了"）。
+    //   自建条目没有覆盖（`text` 里不会有它的键），`effectiveText` 走原值。
+    lines.push(effectiveText(c.id, overrides?.[c.id], c).body)
+  }
+  // ⚠️ **标题放在最后 join 之前**：它不属于任何分类（见 PROMPT_TITLE 的注释），
+  //   且只在**至少有一条规则开启**时才出现 —— 全关时整段返回空串被平台丢弃，
+  //   留着标题就变成"有一套叫准则 v5 的东西"却一条规则都没有。
+  //   标题放在**前面**：它要解释后面这些规则是什么。
+  // ⚠️ **分类之间空一行**（2026-09-29 用户拍板）。单 `\n` 时 15 条规则在窄栏里
+  //   密排成一块，肉眼看不出是 15 条独立的规则 —— 那正是"全都跑成一行"的观感
+  //   来源（实测系统提示词里 `\n` 一直都在，是**排版**问题不是**内容**问题）。
+  //   空行让每条规则成为独立段落。代价是 13 个换行符（~13 token，可忽略），
+  //   且不改变前缀位置 ⇒ KV cache 行为不变。
+  // ⚠️ 标题由**显式参数**决定，**不靠 `categories === PROMPT_CATEGORIES` 这种
+  //   引用相等**（2026-09-29 实测踩过）：接入自建条目后调用方传的是
+  //   `resolveCategories(data)` 合成列表，引用永远不相等 ⇒ 标题静默消失
+  //   （测试当场抓到）。「是不是默认那张表」是个**语义问题**，不该由
+  //   「是不是同一个对象」这种实现细节决定。
+  if (lines.length === 0) return ''
+  return withTitle ? [PROMPT_TITLE, ...lines].join('\n\n') : lines.join('\n\n')
+}
+
+/**
+ * 渲染当前应注入的完整 prompt 文本（总开关 + 分类开关都算进去）。
+ *
+ * 总开关关 ⇒ 空串，让上游 `renderPrompt` 丢弃该段 —— **不是**注入一段空白。
+ */
+export function renderPromptText(masterOn: boolean, data: PromptExtData | undefined): string {
+  if (!masterOn) return ''
+  // ⚠️ 传入 `resolveCategories(data)`（含自建 + 排序）而不是常量
+  //   `PROMPT_CATEGORIES` —— 否则拖动排序和自建条目都只停在面板上，不进 prompt。
+  return renderCategories(
+    resolveEnabledCategories(masterOn, data),
+    resolveCategories(data),
+    data?.text,
+    true, // 合成列表也是本扩展的条目集，照样加标题
+  )
+}
+
+/**
+ * 合成后的**一条**准则条目：内置或自建，已应用标题/正文覆盖。
+ * `builtin` 用来决定按钮（内置没有「删除」，只有「还原」）。
+ */
+export interface ResolvedCategory extends PromptCategory {
+  /** 自建（用户加的）——可删除；内置的不可删除。 */
+  readonly custom: boolean
+  /** 文本被用户改过（决定「还原」按钮是否可点）。 */
+  readonly overridden: boolean
+}
+
+/**
+ * 内置 + 自建 + 排序 ⇒ 有序的最终条目列表。
+ *
+ * ⚠️ 三条规则（顺序不可换）：
+ *  1. **内置在前、自建在后**，除非 `order` 显式给了别的次序。代码顺序是
+ *     "准则作为一份文档的阅读顺序"，不该被用户拖动改掉（见 `PromptExtData.order`）。
+ *  2. `order` 里**不认识的 id 一律忽略**，落盘不可信（手改的 ext.json、上一版的残渣）。
+ *  3. `order` **没提到的条目按原序补在后面** —— 丢了某条 ≠ 它消失了。
+ */
+export function resolveCategories(data: PromptExtData | undefined): ResolvedCategory[] {
+  const custom = Array.isArray(data?.custom) ? data.custom : []
+  // 自建条目也要过滤：脏数据里的空 id / 空正文会让渲染产出空白段落。
+  const validCustom = custom.filter(
+    (c) => !!c && typeof c.id === 'string' && c.id !== '' && typeof c.body === 'string' && c.body !== '',
+  )
+  const base: ResolvedCategory[] = [
+    ...PROMPT_CATEGORIES.map((c) => ({
+      ...c,
+      custom: false,
+      overridden: data?.text?.[c.id] !== undefined,
+    })),
+    ...validCustom.map((c) => ({
+      ...c,
+      title: c.title,
+      defaultOn: c.defaultOn !== false,
+      custom: true,
+      overridden: false, // 自建条目没有"内置版本"，改了就回不去
+    })),
+  ]
+  const order = Array.isArray(data?.order) ? data.order : []
+  if (order.length === 0) return base
+  const byId = new Map(base.map((c) => [c.id, c]))
+  const out: ResolvedCategory[] = []
+  for (const id of order) {
+    const hit = byId.get(id)
+    if (hit === undefined) continue // 规则 2
+    out.push(hit)
+    byId.delete(id)
+  }
+  for (const c of base) {
+    if (byId.has(c.id)) out.push(c) // 规则 3
+  }
+  return out
+}

package/src/ext-prompt/row.json

@@ -0,0 +1,5 @@
+{
+  "name": "dsh-router-core-ext-prompt",
+  "type": "module",
+  "description": "分层提示词扩展（随 dsh-router 核心分发）"
+}

package/src/ext-route.test.ts

@@ -0,0 +1,78 @@
+/**
+ * `/router/api/ext` 路由的**出口判据**。
+ *
+ * ⚠️ 为什么需要它（2026-09-30 实测的「扩展一直加载中、然后卡死」）：
+ *   我重构 op 分支时以为「成功路径统一落到末尾响应」，把 GET 的
+ *   `writeJson(res, 200, {ok:true, enhancers:list})` 删了 —— 结果**没有任何地方
+ *   写响应** ⇒ 请求永不结束 ⇒ 面板一直转圈。
+ *
+ *   ⚠️ **它躲过了全部现有闸门**：typecheck 通过（`writeJson` 少调一次不是类型错误）、
+ *   387 条单测全绿（没有一条从 HTTP 入口打过这个路由）、build 通过。
+ *   典型的「绕过入口的验证 = 没验入口」—— 判据全在函数级，缺一条**路由级**的。
+ *
+ * 做法：不启真服务器，直接读源码断言**每个 return 之前都有出口**这种形状 ——
+ * 太脆。改为**结构判据**：GET 与 PATCH 两条成功路径都必须能走到 `writeJson`。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+
+const src = readFileSync(new URL('./index.ts', import.meta.url), 'utf8')
+
+/** 取出 `/ext` 路由的整段源码。 */
+function extRouteBody(): string {
+  const start = src.indexOf('route(`${ROUTER_API_BASE}/ext`')
+  assert.ok(start > 0, '找不到 /ext 路由')
+  // 到下一个 `route(` 之前
+  const next = src.indexOf('\n  route(', start + 10)
+  return src.slice(start, next > 0 ? next : start + 4000)
+}
+
+test('★ /ext 路由必须有 GET 的响应出口（少写一次 = 请求永不结束）', () => {
+  const body = extRouteBody()
+  const writes = body.match(/writeJson\(res, 2\d\d/g) ?? []
+  assert.ok(writes.length >= 1,
+    '/ext 路由里一处 writeJson 都没有 ⇒ 请求永不返回（面板一直"加载中"）')
+  // GET 成功路径：算完 list 之后必须写出
+  const listLine = body.indexOf('const list: ExtInfo[]')
+  assert.ok(listLine > 0, '找不到 GET 的 list 计算')
+  const after = body.slice(listLine)
+  // ⚠️ 窗口取 600 而非 200：出口上方有 5 行注释，窗口太窄会**误判成缺失**
+  //   （我第一版 200 就红了，而代码是好的 —— 又一次「判据比被守的东西严」）。
+  assert.match(after.slice(0, 600), /writeJson\(res,\s*200/,
+    'GET 算完 list 之后没有 writeJson ⇒ 响应不出口')
+})
+
+test('★ op 成功路径也必须带 enhancers（客户端靠它刷新）', () => {
+  const body = extRouteBody()
+  // op 块里那处：两侧都带 enhancers
+  const opWrites = body.match(/writeJson\(res,\s*200,\s*addedId[^)]*enhancers/g) ?? []
+  assert.ok(opWrites.length >= 1, 'op 成功没有回 enhancers ⇒ 增删改后界面停在旧状态')
+})
+
+test('注入：删掉 GET 的 writeJson ⇒ 本判据会红', () => {
+  // 反向自检：把出口拿掉，上面那条必须不成立。
+  const stripped = extRouteBody().replace(
+    /writeJson\(res,\s*200,\s*\{\s*ok:\s*true,\s*enhancers:\s*list\s*\}\)/,
+    '/* removed */',
+  )
+  const after = stripped.slice(stripped.indexOf('const list: ExtInfo[]'))
+  assert.doesNotMatch(after.slice(0, 600), /writeJson\(res,\s*200/,
+    '注入没生效：这个替换匹配不上（判据会静默全绿）')
+})
+
+// ── 源码目录的野文件（2026-09-30 实测：`.bak` 被提交进仓）────────
+test('★ src 下不许有备份/临时文件（它们会被 `git add -A` 顺手带进仓）', () => {
+  // ⚠️ 实测经过：我用 `sed -i.bak` 做注入验证，备份文件 `content.ts.bak`
+  //   **被 `git add src/ext-prompt/` 带进了提交**。
+  //   它没被任何代码引用（`.bak` 后缀），所以**测试、typecheck、build 全绿** ——
+  //   典型的「产物看起来对、仓里却多了一份东西」。
+  //   而且它危险在：下一个人看到 `content.ts.bak` 会以为是**第二份内容**，
+  //   正是准则里「反查重复：新旧成两份」要防的。
+  //
+  // `check-publish` 只管「patch / exports / files 白名单 / 源码清单」的一致性，
+  // **不管源码目录里的野文件** ⇒ 这里补上。
+  const junk = [...readdirSync(new URL('.', import.meta.url), { recursive: true } as never) as string[]]
+    .filter((f) => /\.(bak|orig|rej|tmp|swp)$/.test(f) || /~$/.test(f))
+  assert.deepEqual(junk, [], `源码目录里有临时/备份文件：${junk.join(', ')}`)
+})