dsh-router-core 0.4.2 → 0.4.4

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

@@ -0,0 +1,95 @@
+/**
+ * 挂载层单测 —— 用假 `ctx.systemPrompt` 验证注册契约。
+ *
+ * 重点是**注入违规必须失败**：
+ *   - 注册了静态字符串（改开关不生效）⇒ 必须被抓到；
+ *   - 卸载不清理 ⇒ 必须被抓到。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mountPromptSection, PROMPT_SECTION_NAME } from './mount.ts'
+import { EXT_PROMPT_ID } from './plugin.ts'
+
+/** 记录注册内容的假 systemPrompt。 */
+function fakeSystemPrompt() {
+  const registered: { name: string; order: number; text: string | (() => string) }[] = []
+  let disposals = 0
+  return {
+    registered,
+    get disposalCount() {
+      return disposals
+    },
+    section(s: { name: string; order: number; text: string | (() => string) }) {
+      registered.push(s)
+      return () => {
+        disposals++
+      }
+    },
+  }
+}
+
+test('注册恰好一个段落，名字稳定', () => {
+  const sp = fakeSystemPrompt()
+  mountPromptSection({ getSystemPrompt: () => sp, isEnabled: () => true, readData: () => undefined })
+  assert.equal(sp.registered.length, 1)
+  assert.equal(sp.registered[0]!.name, PROMPT_SECTION_NAME)
+})
+
+test('⚠️ text 必须是 provider 函数而不是静态字符串（否则改开关不生效）', () => {
+  const sp = fakeSystemPrompt()
+  mountPromptSection({ getSystemPrompt: () => sp, isEnabled: () => true, readData: () => undefined })
+  const t = sp.registered[0]!.text
+  assert.equal(typeof t, 'function', 'text 是静态字符串 ⇒ 分类开关永远不生效')
+})
+
+test('注入违规：静态 text ⇒ 断言会红（证明这条守卫抓得住）', () => {
+  // 反向证明：造一个"静态 text"的假 systemPrompt 看看会发生什么
+  const sp = fakeSystemPrompt()
+  let on = true
+  mountPromptSection({
+    getSystemPrompt: () => sp,
+    isEnabled: () => on,
+    readData: () => undefined,
+  })
+  // 第一次求值
+  const first = (sp.registered[0]!.text as () => string)()
+  assert.ok(first.includes('大肥鱼'), '总开关开时应有准则')
+  // 改开关后再求值 —— 若 text 是静态的，这里会拿到同一个字符串
+  on = false
+  const second = (sp.registered[0]!.text as () => string)()
+  assert.equal(second, '', 'provider 形式下改开关必须立刻反映')
+})
+
+test('开关关闭 ⇒ provider 返回空串（上游据此丢弃该段）', () => {
+  const sp = fakeSystemPrompt()
+  mountPromptSection({ getSystemPrompt: () => sp, isEnabled: () => false, readData: () => undefined })
+  assert.equal((sp.registered[0]!.text as () => string)(), '')
+})
+
+test('卸载会调用 disposer（不留孤儿段落）', () => {
+  const sp = fakeSystemPrompt()
+  const unmount = mountPromptSection({
+    getSystemPrompt: () => sp,
+    isEnabled: () => true,
+    readData: () => undefined,
+  })
+  assert.equal(sp.disposalCount, 0)
+  unmount()
+  assert.equal(sp.disposalCount, 1, '卸载没清理 ⇒ 段落泄漏，插件重载会叠加')
+})
+
+test('systemPrompt 不可用 ⇒ 不注册、卸载是 no-op、且不抛', () => {
+  let unmount: () => void = () => {}
+  assert.doesNotThrow(() => {
+    unmount = mountPromptSection({
+      getSystemPrompt: () => undefined,
+      isEnabled: () => true,
+      readData: () => undefined,
+    })
+  })
+  assert.doesNotThrow(() => unmount())
+})
+
+test('ext id 稳定（改名会丢用户已存的开关配置）', () => {
+  assert.equal(EXT_PROMPT_ID, 'prompt')
+})

package/src/ext-prompt/mount.ts

@@ -0,0 +1,79 @@
+/**
+ * 挂载层 —— 把准则注册成 `ctx.systemPrompt` 的**一个**段落。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么只注册一段，而不是 14 段
+ * ════════════════════════════════════════════════════════════════════
+ * 面板开关的粒度是「分类」，但 prompt 读起来应该是一段连续的准则。分成 14 段
+ * 会让 KV cache 每个分类各占一段，且**增删任意一个分类都让它之后的全部分位**。
+ * 一段 + 拼装 ⇒ 分类增删只改这一段内部，段的位置与前缀稳定。
+ *
+ * ⚠️ **空串即关闭，这是平台原生语义**（`renderPrompt` 的注释原文：
+ * "drop empty sections"）⇒ "可开关"不需要任何自造机制：本函数返回 `''`，
+ * 上游就把整段丢掉。**不要自己实现"删段落"的逻辑**，那会和平台重复且会漂移。
+ *
+ * ⚠️ 文本用 provider 函数（`(context) => string`）而不是静态字符串：
+ *   分类开关随时可改，静态文本**注册那一刻就定死了**，改开关不生效。
+ */
+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
+}
+
+/** 段落名（**稳定**）：改名会让已注册的作用域 section 与旧名并存。 */
+export const PROMPT_SECTION_NAME = 'dsh-router-ext-prompt:guideline'
+
+/**
+ * 段落 order：100。
+ *
+ * 官方分配的槽位（`dsh-system-prompt` 的 `SECTION_ORDERS`）：
+ * `PERSONA_PREFIX: 0` · `PLAN_POLICY: 500` · `TEAM_POLICY: 600` …·
+ * 取 100 = 紧随 persona、远早于任何工具段 ⇒ 准则出现在身份之后、工具说明之前，
+ * 与用户看到的记忆快照位置一致。
+ */
+const SECTION_ORDER = 100
+
+export interface MountPromptDeps {
+  /** 取 `ctx.systemPrompt`（可能尚未就绪 ⇒ undefined）。 */
+  getSystemPrompt: () => SystemPromptFace | undefined
+  /** 总开关（问核心 `router.extStore`）。 */
+  isEnabled: () => boolean
+  /**
+   * 读本扩展的数据块（分类开关）。
+   *
+   * 落盘 JSON 不可信 ⇒ 返回值**不保证**是合法 `PromptExtData`，
+   * `renderPromptText` 负责容错（见 render.test.ts 的注入用例）。
+   */
+  readData: () => PromptExtData | undefined
+}
+
+/**
+ * 挂载准则段落。返回卸载函数。
+ *
+ * ⚠️ `systemPrompt` 尚不可用时**不挂**（返回 no-op 清理），并由 `ext.getState()`
+ *   报 `ready: false` 让面板红字显示。**不做轮询重试** —— 显式"没就绪"好过
+ *   半开的注入：后者会让准则随机时有时无，而用户看不出为什么。
+ *   `index.ts` 用 `ctx.inject(['systemPrompt'])` 保证挂载时机，本函数只管挂。
+ */
+export function mountPromptSection(deps: MountPromptDeps): () => void {
+  const sp = deps.getSystemPrompt()
+  if (!sp) return () => {}
+
+  const dispose = sp.section({
+    name: PROMPT_SECTION_NAME,
+    order: SECTION_ORDER,
+    // ⚠️ provider 每次装配都现算 ⇒ 改开关**立即生效**，无需重注册。
+    text: () => renderCurrent(deps),
+  })
+  return () => {
+    dispose()
+  }
+}
+
+/** 算出当前应注入的文本（薄壳：真逻辑在 render.ts，可单测）。 */
+function renderCurrent(deps: MountPromptDeps): string {
+  return renderPromptText(deps.isEnabled(), deps.readData())
+}

package/src/ext-prompt/plugin.ts

@@ -0,0 +1,223 @@
+/**
+ * 分层提示词扩展（`router.ext` 侧的实现）—— 声明与状态都在这里。
+ *
+ * 与 `ext-test`（插件自检）同款：**不挂任何监听、不改写任何东西**，
+ * 唯一作用是让用户在官方插件页里看到一张卡片、能开关它，并把协作准则
+ * 注册成一段 system prompt。
+ *
+ * 与 `rtk` / `jev` 那类扩展的区别要写清楚：那两家挂 `tools/execute`
+ * 改写**工具调用**；本扩展只往 **system prompt** 加一段。名字同族是因为
+ * 都在 `router.ext` 这张表里，拦截面不重叠。
+ *
+ * 复用 `router.ext` 通道只为拿到**发现 + 开关**两件事（见 ext-test 的同款说明），
+ * 真正的注入在 `mount.ts`。
+ */
+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'
+
+/** 从对象里去掉某个键（不改原对象）。`writeData` 是整块替换 ⇒ 删一个键要重写。 */
+function omit<T extends Record<string, unknown>>(obj: T, key: string): Partial<T> {
+  const out = { ...obj } as Record<string, unknown>
+  delete out[key]
+  return out as Partial<T>
+}
+
+/** 扩展开关表里的注册键。 */
+export const EXT_PROMPT_ID = 'prompt'
+
+/**
+ * 构造这个扩展器。
+ *
+ * `getState()` 报**唯一的真实就绪条件**：`ctx.systemPrompt` 不可用时无处注入
+ * （section 是唯一的注入通道），此时必须红字报出，而不是静默不生效 ——
+ * 判据能变红比"看起来一直开着"有用。
+ *
+ * @param deps.store - `router.extStore`（读写分类开关的落盘数据块）。缺省时
+ *   `controls` 报全部默认、`setControl` 恒 false —— 那样面板显示可点但点了
+ *   没反应，**比不显示更坏**。
+ */
+export function createPromptExt(deps: {
+  isSystemPromptReady: () => boolean
+  store?: ExtStoreService
+}): RouterExt {
+  const store = deps.store
+  /**
+   * 读落盘数据。**没有记录时返回空对象而不是 undefined**。
+   *
+   * ⚠️ 2026-09-30 实测修的真 bug：`<dataDir>/ext.json` 里 `prompt` 只有
+   * `{enabled:true}`（**用户没改过任何东西** ⇒ 没有 `data` 键），
+   * 而我原先把 `data === undefined` 当成"存储不可用"直接 `return null/false`
+   * ⇒ 「添加准则」永远报 `title and body are required`，
+   * 而 title/body 明明都传了 —— 报错信息还指向错误的字段，排查成本极高。
+   *
+   * ⇒ 「没记录」与「记录为空」**必须同义**：都当作"从空白开始"。
+   * 真正该拒的是 **store 本身不存在**（扩展没挂上），那个在下面单独判。
+   */
+  const readData = (): PromptExtData => store?.readData<PromptExtData>(EXT_PROMPT_ID) ?? {}
+  return {
+    id: EXT_PROMPT_ID,
+    name: '分层提示词',
+    // 图标（面板卡片 / 详情页头部的 44px 圆角位）。SVG base64 内联 ⇒ 离线可用、
+    // 不依赖外链、不受 CSP 的 img-src 限制。源文件在 `logo.svg`，base64 由它生成。
+    icon: PROMPT_LOGO_URL,
+    description: PROMPT_TITLE,
+    // ⚠️ `description` = 整段的**标题**（不是一句自我介绍）。2026-09-29 两次调整：
+    //   先是删掉它（详情页逐条列清单，「拆成 14 个分类」是纯冗余）；
+    //   后又加回来、但只放**标题** `[准则 v5]`，并让详情页把它渲染在**最上面** ——
+    //   逐条清单之前先说清「这是什么」，比任何自我介绍都直接。
+    //   ⚠️ **不再内插分类数量**（`${PROMPT_CATEGORIES.length}` 会与真实数量漂移）。
+    //
+    //   插件页「包含的组件」那一行仍然有**另一句**说明（来自 `locale/zh.json`，
+    //   宿主读的）—— 两者不是同一处，别混：那一行回答「不开它行不行」，
+    //   这里回答「它是什么」。
+    //
+    // 随核心分发 -> 插件页的原生「包含的组件」里有它一行，自绘节里不再重复列。
+    source: 'builtin' as const,
+    // ⚠️ 每次 `controls` 被读都现算（不缓存）：用户在面板点一下立刻要看到新状态，
+    //   而核心每次 GET /ext 都重新取一次。缓存会显示"点了没反应"。
+    /**
+     * ⚠️ **用 getter，每次读都重算**（2026-09-29 实测修的 bug）。
+     *   原来写的是 `PROMPT_CATEGORIES.map(...)` —— 那个 map 在
+     *   `createPromptExt()` 调用时就跑完了，是个**快照**。于是编辑落盘后：
+     *   prompt 变了（渲染层每次现算），但面板再读 `controls` 拿到的还是**旧标题**
+     *   ⇒ 用户看到「保存了、又变回去了」。而我当时的注释还写着"现算不缓存"——
+     *   **注释与事实不符，比没注释更坏**。
+     *
+     * getter 让「面板显示的」与「prompt 里的」永远来自同一次 `readData()`。
+     */
+    get controls() {
+      const data = readData()
+      const on = resolveEnabledCategories(true, data)
+      // ⚠️ 走 `resolveCategories`（内置 + 自建 + 排序），不是内置常量 ——
+      //   否则自建条目与拖动排序**只停在面板上**，不进 prompt。
+      return resolveCategories(data).map((c) => {
+        const t = effectiveText(c.id, data?.text?.[c.id], c)
+        return {
+          id: c.id,
+          title: t.title,
+          // ⚠️ **带上原文**：不给出原文的话用户是在**盲切** —— 只看到「结构」「交付」
+          //   这样的名字，不知道这一条到底写了什么，也无从判断该不该关掉它。
+          //   「看内容 → 决定开关」这个动作必须能一处完成。
+          body: t.body,
+          editable: true,
+          // ⚠️ **显式布尔，不靠缺省**：面板要靠 `custom === true` 决定
+          //   给「删除」还是「还原」，`undefined`（字段缺失）会让"内置"变成
+          //   "不知道是哪种" ⇒ 落到错误的按钮上（2026-09-30 实测现象）。
+          // `custom` ⇒ 可删（自建）；`overridden` ⇒ 「还原」可点（改过内置）。
+          custom: c.custom,
+          overridden: c.overridden,
+          on: on.has(c.id),
+        }
+      })
+    },
+    setControl: (controlId, on) => {
+      if (!store) return false
+      // ⚠️ **只改这一个键，不重写整块**：整块重写会顺手把 data 抽屉里的其它字段
+      //   抹掉（`store.test.ts` 有一条「置开关不能把 data 冲掉」的同款纪律）。
+      const data = readData()
+      // ⚠️ 用**合成列表**（内置 + 自建）而不是 `PROMPT_CATEGORIES`：
+      //   自建条目的 id 根本不在内置常量里 ⇒ 切它的开关恒被拒，
+      //   报 `unknown controlId`（2026-09-30 实测：用户看到"自定义的开关控制报错"）。
+      const known = resolveCategories(data).some((c) => c.id === controlId)
+      if (!known) return false
+      store.writeData(EXT_PROMPT_ID, { ...data, categories: { ...data.categories, [controlId]: on } })
+      return true
+    },
+    // ⚠️ **只存覆盖值，不存全文**（见 PromptExtData.text）：没改过的分类不出现在
+    //   落盘里 ⇒ 内置内容仍是唯一事实源，升级内置文案时它们会跟着更新。
+    //   存全文的话，用户改一个字就永久冻结整段，之后内置更新对它们完全失效。
+    setControlText: (controlId, patch) => {
+      if (!store) return false
+      const data = readData()
+      // ⚠️ 用**合成列表**（内置 + 自建）而不是 `PROMPT_CATEGORIES`：
+      //   自建条目的 id 根本不在内置常量里 ⇒ 切它的开关恒被拒，
+      //   报 `unknown controlId`（2026-09-30 实测：用户看到"自定义的开关控制报错"）。
+      const known = resolveCategories(data).some((c) => c.id === controlId)
+      if (!known) return false
+      // ⚠️ **空串直接拒绝**（返回 false ⇒ 核心回 400）：空标题会让这一行没名字，
+      //   空正文会让规则凭空消失 —— 两者都像"被关了"而不是"被改坏了"。
+      if (patch.title !== undefined && patch.title.trim() === '') return false
+      if (patch.body !== undefined && patch.body.trim() === '') return false
+      // ⚠️ **只并这一个键**：writeData 是整块替换，漏一个键就是丢一份数据
+      //   （`store.test.ts` 有同款纪律：置开关不能把 data 冲掉）。
+      const prev = data.text?.[controlId] ?? {}
+      store.writeData(EXT_PROMPT_ID, {
+        ...data,
+        text: { ...data.text, [controlId]: { ...prev, ...patch } },
+      })
+      return true
+    },
+    /** 改顺序（拖动）。落盘 id 列表；未知/重复 id 由 `resolveCategories` 兜住。 */
+    setControlOrder: (ids) => {
+      if (!store) return false
+      const data = readData()
+      const known = new Set(resolveCategories(data).map((c) => c.id))
+      // ⚠️ 只接受**当前存在**的 id：脏数据（手改 ext.json / 别的扩展写的）会
+      //   让顺序里出现幽灵条目，而渲染时会静默忽略它 ⇒ 面板上「存了但没生效」。
+      const next = [...new Set(ids)].filter((id) => known.has(id))
+      store.writeData(EXT_PROMPT_ID, { ...data, order: next })
+      return true
+    },
+    /** 新增一条自定义准则。id 由**扩展**生成（`cu-<n>`），避免前端编 id 撞内置。 */
+    addCustomControl: (title, body) => {
+      if (!store) return null
+      if (typeof title !== 'string' || title.trim() === '') return null
+      if (typeof body !== 'string' || body.trim() === '') return null
+      const data = readData()
+      const custom = Array.isArray(data.custom) ? [...data.custom] : []
+      // ⚠️ **id 必须避开内置**：撞了会让两条同 id，`resolveCategories` 的
+      //   `byId` Map 只留一条 ⇒ 另一条凭空消失（且不报错）。
+      const used = new Set([...PROMPT_CATEGORIES.map((c) => c.id), ...custom.map((c) => c.id)])
+      let n = custom.length + 1
+      while (used.has(`cu-${n}`)) n++
+      const id = `cu-${n}`
+      custom.push({ id, title: title.trim(), body: body.trim(), defaultOn: true })
+      store.writeData(EXT_PROMPT_ID, { ...data, custom })
+      return id // ⚠️ 返回新 id：面板据此高亮/滚到新条目
+    },
+    /**
+     * 删一条 —— **只允许自定义**。
+     *
+     * ⚠️ 内置条目返回 false（→ 核心回 400）：它是**代码的一部分**，
+     *   删掉就意味着下一次发版它又回来了；用户对内置的处置手段是**关开关**
+     *   与**还原文本**，不是删除。
+     */
+    removeCustomControl: (controlId) => {
+      if (!store) return false
+      const data = readData()
+      const custom = Array.isArray(data.custom) ? data.custom : []
+      if (!custom.some((c) => c.id === controlId)) return false
+      store.writeData(EXT_PROMPT_ID, {
+        ...data,
+        custom: custom.filter((c) => c.id !== controlId),
+        // 顺带清掉它的开关与覆盖，否则留下孤儿数据
+        ...(data.categories ? { categories: omit(data.categories, controlId) } : {}),
+        ...(data.text ? { text: omit(data.text, controlId) } : {}),
+        ...(data.order ? { order: data.order.filter((id) => id !== controlId) } : {}),
+      })
+      return true
+    },
+    /**
+     * 还原一条的文本（丢掉覆盖，回到内置）。
+     *
+     * ⚠️ 自定义条目返回 false —— 它**没有"内置版本"**可回退；
+     *   它的对应手段是「删除」。
+     */
+    resetControlText: (controlId) => {
+      if (!store) return false
+      const data = readData()
+      // ⚠️ 这里**刻意只用内置常量**：还原的语义是"回到内置内容"，
+      //   自建条目**没有内置版本**可回退（它的对应手段是删除）。
+      if (!PROMPT_CATEGORIES.some((c) => c.id === controlId)) return false
+      if (data.text?.[controlId] === undefined) return false // 没改过，无需写盘
+      store.writeData(EXT_PROMPT_ID, { ...data, text: omit(data.text, controlId) })
+      return true
+    },
+    getState: () =>
+      deps.isSystemPromptReady()
+        ? { ready: true }
+        : { ready: false, detail: 'ctx.systemPrompt 不可用 —— 本扩展无处注入' },
+  }
+}

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)
+})