dsh-router-core 0.4.1 → 0.4.3

package/src/ext-prompt/index.ts

@@ -0,0 +1,104 @@
+/**
+ * 分层提示词扩展的 **cordis 行** —— 官方插件页（设置 → 插件 → dsh-router-core）详情页
+ * 原生「包含的组件」里的那一行。
+ *
+ * 壳的形状与 `ext-test` 同款（cordis 身份 + 登记，实现 = `plugin.ts`），
+ * 但**多一件执行面的事**：挂 system prompt 段落。ext-test 不做拦截、只登记；
+ * 本扩展要把准则真注入，所以额外等 `systemPrompt` service 就绪后挂 section。
+ *
+ * **默认开启**（patch 里不带 `disabled`，与三行内置供应商一致）：
+ * 协作准则是每次协作都要的基础设施，不是可选增强。与 `ext-test` 的
+ * `disabled: true` **刻意不同** —— 自检是「想跑才跑」的工具，准则不是；
+ * 让准则默认缺席，会变成「用户不知道它存在 ⇒ 协作按另一套规则执行」。
+ *
+ * 登记时把扩展开关置为开：本扩展**没有独立的运行期开关**，它的开关就是这一行
+ * （宿主管的那个）。不置上的话，用户开了行还要再点一次，两级开关说同一件事。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  currentExts,
+  currentExtStore,
+  type ExtStoreService,
+  type RouterExtService,
+} from '../ext/contract.ts'
+import { createPromptExt, EXT_PROMPT_ID } from './plugin.ts'
+import { mountPromptSection, type SystemPromptFace } from './mount.ts'
+import type { PromptExtData } from './render.ts'
+
+/** cordis 插件身份（配置树里这一行的技术名；显示名走同目录的 locale）。 */
+export const name = 'dsh-router-ext-prompt'
+
+/** `ctx.systemPrompt` 的最小可见面（见 mount.ts）。 */
+function systemPromptOf(sctx: Context): SystemPromptFace | undefined {
+  const c = sctx as unknown as {
+    get?: (k: string) => unknown
+    systemPrompt?: SystemPromptFace
+  }
+  const sp = (c.get?.('systemPrompt') ?? c.systemPrompt) as SystemPromptFace | undefined
+  return sp && typeof sp.section === 'function' ? sp : undefined
+}
+
+/**
+ * 声明本扩展依赖的 service。
+ *
+ * ⚠️⚠️ **必须导出这个数组，且 `apply` 里直接用 `ctx.systemPrompt`**（2026-09-29 修）
+ * ——我原先写成「在 apply 里 `ctx.inject(['systemPrompt'], cb)`」，**准则一直不进
+ * prompt**：面板上卡片、开关、原文全都正常（`GET /router/api/ext` 实测有 14 条
+ * controls），但模型看到的 system prompt 里没有它。
+ *
+ * 根因（本机 cordis 4.0.4 实测）：`ctx.inject(deps, cb)` 的回调**不是同步触发** ——
+ * provide 之后立刻 `inject`，回调要等到下一个异步点才跑。插件的 `apply` 是**同步
+ * 函数**，返回时那次回调还没发生；而真实加载路径不保证之后还有机会去等它，
+ * 于是 `mountPromptSection` 从没被执行 ⇒ **准则一次都没进过 prompt**。
+ *
+ * ⚠️ 我第一版把这个机制写成「要等 `ctx.start()`」——**那是错的**：`start` 根本不在
+ *   Context 的公开面上（原型只有 extend/isolate/intercept）。准确说法是「下一个
+ *   异步点」，具体机制随版本变。**结论不依赖这个细节**，只依赖「apply 里手动
+ *   inject 不可靠」这一事实。
+ *
+ * 正确形状（对照 `dsh-client-ui-deliverables` 等真实使用者）：导出 `inject` 数组，
+ * cordis 看到它就**把整个 apply 推迟到这些 service 就绪之后**再调用 ——
+ * 于是 `ctx.systemPrompt` 一定是活的，`section()` 可以直接调。
+ *
+ * ⚠️ `router.ext` 也要列：那一半（面板登记）此前"碰巧"能用，是因为
+ * `dsh-router` 核心先 provide 了它、`apply` 又跑在它之后。**那是时序上的运气，
+ * 不是保证** —— 一并列进 `inject`，两种 service 都由 cordis 编排。
+ */
+export const inject = ['systemPrompt', 'router.ext', 'router.extStore']
+
+/**
+ * 登记本扩展**并**挂载准则段落。
+ *
+ * 此刻 `ctx.systemPrompt` / `ctx.router.ext` / `ctx.router.extStore` **必定已就绪**
+ * （见上面 `inject` 的注释），所以下面**直接用**，不再做二次判空。
+ */
+export function apply(ctx: Context): void {
+  const table = currentExts(ctx)
+  const store = currentExtStore(ctx)
+
+  // ① 准则段落。`section()` 注册一个**provider 函数**作为 text ——
+  //    每次装配现算，所以改开关立即生效，无需重注册。
+  const dispose = mountPromptSection({
+    getSystemPrompt: () => systemPromptOf(ctx),
+    isEnabled: () => store?.isEnabled(EXT_PROMPT_ID) === true,
+    readData: () => store?.readData<PromptExtData>(EXT_PROMPT_ID),
+  })
+
+  // ② 面板登记。幂等：同一个 id 已在表里就不顶掉别人的登记。
+  if (table !== undefined && table[EXT_PROMPT_ID] === undefined) {
+    table[EXT_PROMPT_ID] = createPromptExt({
+      isSystemPromptReady: () => !!systemPromptOf(ctx),
+      // ⚠️ **store 必须在这时就能拿到**：拿不到的话面板上的分类开关显示可点、
+      //   点了 400 —— 「看起来能用但不能用」比「不显示」更难查。
+      store,
+    })
+    store?.setEnabled(EXT_PROMPT_ID, true)
+    // 核心持有的是**同一个 live 对象**（它 provide 的空表），且 `/ext` 每次请求都
+    // 现读这张表 —— 所以往里 append 就够了，不需要（也不存在）广播事件。
+  }
+
+  ctx.effect(() => () => {
+    dispose()
+    if (table !== undefined) delete table[EXT_PROMPT_ID]
+  })
+}

package/src/ext-prompt/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Layered prompt",
+    "description": "Split the working guidelines into individually switchable categories and inject them into the system prompt; disabled categories contribute no prompt text"
+  }
+}

package/src/ext-prompt/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "分层提示词",
+    "description": "把协作准则拆成可独立开关的分类，注入 system prompt；关闭的分类不产出任何 prompt 文本"
+  }
+}

package/src/ext-prompt/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="16" fill="#17181D"/>
+  <g fill="none" stroke="#EDEDEB" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M18 16h20"/>
+    <path d="M18 27h24"/>
+    <path d="M18 38h24"/>
+    <path d="M18 49h24"/>
+  </g>
+  <g fill="none" stroke="#A7C0A5" stroke-width="3.4" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M9 16.5l2.5 2.5L16 14.5"/>
+    <path d="M9 27.5l2.5 2.5L16 25.5"/>
+    <path d="M9 38.5l2.5 2.5L16 36.5"/>
+  </g>
+</svg>

package/src/ext-prompt/logo.ts

@@ -0,0 +1,18 @@
+/**
+ * 分层提示词扩展的图标 —— **一张深色圆角瓦片**，以本地 base64 内联（离线可用）。
+ *
+ * 为什么这样画：它做的事是「一份可以逐条开关的规则清单」⇒ 图形 = 清单 + 勾选。
+ * 不用齿轮（那是设置）、不用扳手（那是工具）—— 那两样也在同一个面板里，
+ * 混用会让人分不清「改行为」和「改这套规则本身」。
+ *
+ * ⚠️ **单色 + 深底**（与 RTK logo 同款处理）：`.dshr-providerIcon` 只给圆角与
+ * 尺寸、**不给底色**，所以底色必须由本图自带 ⇒ 深浅两套主题下都成立。
+ * 勾选用略暖的绿（`#A7C0A5`）与清单的灰白拉开，暗示"这些可以勾掉"。
+ *
+ * ⚠️ **base64 必须由 `logo.svg` 生成**（`base64 -i logo.svg | tr -d '\n'`）。
+ *   我第一版**手编**了一串 base64，解出来是乱码（`tept-Gradient`、`#17118=D`）——
+ *   而客户端的 `onError` 会把加载失败的图**静默藏掉**、退回默认闪电图标，
+ *   **看起来"正常"、实际图标根本没换**。编造的常量不会报错，这是它最险的地方。
+ */
+export const PROMPT_LOGO_URL =
+  'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI+CiAgPHJlY3Qgd2lkdGg9IjY0IiBoZWlnaHQ9IjY0IiByeD0iMTYiIGZpbGw9IiMxNzE4MUQiLz4KICA8ZyBmaWxsPSJub25lIiBzdHJva2U9IiNFREVERUIiIHN0cm9rZS13aWR0aD0iMyIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj4KICAgIDxwYXRoIGQ9Ik0xOCAxNmgyMCIvPgogICAgPHBhdGggZD0iTTE4IDI3aDI0Ii8+CiAgICA8cGF0aCBkPSJNMTggMzhoMjQiLz4KICAgIDxwYXRoIGQ9Ik0xOCA0OWgyNCIvPgogIDwvZz4KICA8ZyBmaWxsPSJub25lIiBzdHJva2U9IiNBN0MwQTUiIHN0cm9rZS13aWR0aD0iMy40IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTkgMTYuNWwyLjUgMi41TDE2IDE0LjUiLz4KICAgIDxwYXRoIGQ9Ik05IDI3LjVsMi41IDIuNUwxNiAyNS41Ii8+CiAgICA8cGF0aCBkPSJNOSAzOC41bDIuNSAyLjVMMTYgMzYuNSIvPgogIDwvZz4KPC9zdmc+Cg=='

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 不可用 —— 本扩展无处注入' },
+  }
+}