dsh-router-core 0.4.2 → 0.4.3

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

@@ -0,0 +1,432 @@
+/**
+ * 分层提示词扩展（`router.ext` 侧）测试 —— 锁住四件事：
+ *   1. 登记进 `router.ext` 表，带上可显示的身份（名字/说明/就绪）；
+ *   2. **幂等**：同一个 id 已在表里就不顶掉别人的登记；
+ *   3. `source: 'builtin'`（随核心分发 ⇒ 插件页的原生行，自绘节不重复列）；
+ *   4. **准则段落真的挂上了** —— ext-test 没有这一条，本扩展多做执行面，必须验。
+ *
+ * 为什么第 4 条不可省：扩展的「卡片出现与否」取决于它在不在这张表里，而**准则
+ * 有没有进 prompt** 取决于段落挂没挂 —— 两者是**不同的失效**，都静默且都不报错。
+ * 只测登记会漏掉「卡片亮着、准则没进 prompt」这个最难查的情况。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { createPromptExt, EXT_PROMPT_ID } from './plugin.ts'
+import { PROMPT_LOGO_URL } from './logo.ts'
+import { apply, name as CORDIS_NAME, inject as CORDIS_INJECT } from './index.ts'
+import { PROMPT_SECTION_NAME } from './mount.ts'
+import { PROMPT_CATEGORIES, PROMPT_TITLE } from './content.ts'
+import type { RouterExtService } from '../ext/contract.ts'
+
+test('扩展器带上面板要用的身份', () => {
+  const ext = createPromptExt({ isSystemPromptReady: () => true })
+  assert.equal(ext.id, EXT_PROMPT_ID)
+  assert.equal(ext.name, '分层提示词')
+  assert.equal(ext.source, 'builtin', '随核心分发必须标 builtin，否则插件页会重复列它')
+})
+
+test('★ `description` 是整段标题（不是自我介绍，也不内插分类数）', () => {
+  // ⚠️ 这条断言**换了两次内容**，值得留档（2026-09-29）：
+  //   ① 最初写的是「没有说明，插件页那一行就没有副标题」——**前提是错的**，
+  //      那一行的副标题来自 `locale/*.json`，与 `description` 无关；
+  //   ② 改成「`description` 必须是 undefined」（当时用户嫌「拆成 14 个分类」冗余）；
+  //   ③ 现在又要求**顶部显示标题** ⇒ 改成「等于 PROMPT_TITLE」。
+  //   两次反复的共同教训：**默认值/文案该是什么由用户拍板，判据只负责让改动可见**，
+  //   所以断言跟着改、并在注释里留着反复，免得下一个人以为是"又改坏了"。
+  const ext = createPromptExt({ isSystemPromptReady: () => true })
+  assert.equal(ext.description, PROMPT_TITLE, '详情页顶部要显示的就是整段标题')
+  // ⚠️ 尤其**不许**内插 `${PROMPT_CATEGORIES.length}`：加减分类后文案不跟着变，
+  //   就是同一件事的两个来源（「反查重复」）。
+  assert.doesNotMatch(String(ext.description), /\d+\s*个/,
+    'description 里内插了分类数量 ⇒ 加减分类后会与真实数量漂移')
+})
+
+test('★ 插件页那一行的说明仍然在（来自 locale，不是 description）', () => {
+  // 「删 description」不等于「把说明也删了」：宿主读的是 locale 资源。
+  // 只写 host 半边的话，这一行会**没有副标题** —— 而不打开就不知道它是干什么的。
+  const locale = JSON.parse(
+    readFileSync(new URL('./locale/zh.json', import.meta.url), 'utf8'),
+  ) as { meta?: { title?: string; description?: string } }
+  assert.ok((locale.meta?.title ?? '').length > 0, 'locale 缺 title')
+  assert.ok((locale.meta?.description ?? '').length > 0, '插件页那一行没有副标题')
+})
+
+test('注入：systemPrompt 不可用 ⇒ 报 not ready（不能静默不生效）', () => {
+  const ext = createPromptExt({ isSystemPromptReady: () => false })
+  const st = ext.getState()
+  assert.equal(st.ready, false, '无处注入却报就绪 = 卡片亮着、准则没进 prompt')
+  assert.ok((st.detail ?? '').length > 0, '不报还不说原因 = 面板上无从判断')
+})
+
+test('cordis 身份与 patch 里声明的 id 逐字相同（否则 loader 认不出这一行）', () => {
+  assert.equal(CORDIS_NAME, 'dsh-router-ext-prompt')
+})
+
+test('★ patch 里真的声明了这一行，且 id/name 逐字对得上', () => {
+  // ⚠️ **必须真读 patch 文件**：只断言自己的常量的话，patch 写错了照样全绿
+  //    —— 判据不碰被它守的东西，等于没守。
+  //    症状会非常隐蔽：构建通过、测试通过、装上后插件页**没有这一行**。
+  const patch = readFileSync(new URL('../../cordis.patch.yml', import.meta.url), 'utf8')
+  const block = patch.match(
+    new RegExp(`- id: ${CORDIS_NAME}\\s*\\n\\s*name: '([^']+)'(\\s*\\n\\s*(disabled:.*)?)?\\n`),
+  )
+  assert.ok(block, `cordis.patch.yml 里没有 id=${CORDIS_NAME} 的行`)
+  assert.equal(block![1], 'dsh-router-core/ext-prompt', 'patch 的 name 必须是能解析的子路径说明符')
+})
+
+test('★ 那一行默认关闭（与 ext-test 同款）', () => {
+  // `disabled: true` = 行默认关 ⇒ loader 不 import ⇒ 扩展不进 `router.ext` 表 ⇒
+  // 卡片不出现、准则不进 prompt。
+  //
+  // ⚠️ **这里来回改过一次**（2026-09-29）：先按"准则是基础设施"改成默认开启，
+  //   又改回默认关闭。**用户对默认值的取舍优先于我的判断** —— 判据跟着改，
+  //   不是反过来。注释里留着这次反复，是为了让下一个人知道它**曾经**是默认开、
+  //   以及为什么现在不是（不是"忘了改回来"）。
+  const patch = readFileSync(new URL('../../cordis.patch.yml', import.meta.url), 'utf8')
+  const block = patch.match(
+    new RegExp(`- id: ${CORDIS_NAME}[^]*?\\n(\\s*name: '([^']+)'\\n([^\\n]*))`),
+  )
+  assert.ok(block, 'patch 里找不到这一行')
+  assert.match(block![3] ?? '', /disabled:\s*true/,
+    '这一行不带 disabled: true ⇒ 装上就自动注入准则（与用户当前拍板相反）')
+})
+
+/**
+ * 真 cordis 夹具 —— **不用假 ctx**（2026-09-29 换掉）。
+ *
+ * ⚠️ 上一版的假 ctx `inject` 会**立即**回调 apply 里注册的回调。那恰好把真正的
+ *   bug 掩盖掉了：`ctx.inject(deps, cb)` 对已就绪的 service 其实要等
+ *   `ctx.start()` 之后才回调，所以旧实现里准则一次都没挂上，而假 ctx 全绿。
+ *   ⇒ 判据的替身比被守的东西更宽容 = 判据无效。
+ *   真 cordis 会如实复现时序（本机 4.0.4 实测：provide 后 inject 不触发，
+ *   start() 之后才触发）。
+ */
+async function realCtx(opts: { enabled?: boolean; data?: unknown } = {}) {
+  const { Context } = await import('@deepseek-ai/cordis')
+  const table: RouterExtService = {}
+  const sections: { name: string; order: number; text: string | (() => string) }[] = []
+  const ctx = new Context()
+  ctx.provide('systemPrompt', {
+    section: (s: { name: string; order: number; text: string | (() => string) }) => {
+      sections.push(s)
+      return () => {}
+    },
+    getSectionOrder: () => 100,
+  })
+  ctx.provide('router.ext', table)
+  ctx.provide('router.extStore', {
+    isEnabled: () => opts.enabled ?? true,
+    setEnabled: () => {},
+    readData: () => opts.data,
+    writeData: () => {},
+  })
+  return { ctx, table, sections }
+}
+
+test('apply 把扩展登记进 router.ext 表（这张表就是「卡片出现」的唯一依据）', async () => {
+  const { ctx, table } = await realCtx()
+  apply(ctx as unknown as Parameters<typeof apply>[0])
+  assert.equal(table[EXT_PROMPT_ID]?.name, '分层提示词')
+})
+
+test('幂等：同一个 id 已在表里时不顶掉别人的登记', async () => {
+  const { ctx, table } = await realCtx()
+  apply(ctx as unknown as Parameters<typeof apply>[0])
+  const first = table[EXT_PROMPT_ID]
+  apply(ctx as unknown as Parameters<typeof apply>[0])
+  assert.equal(table[EXT_PROMPT_ID], first, '重复登记不该换成一个新对象')
+})
+
+test('★ apply 把准则挂成了 system prompt 段落（ext-test 没这层，必须单独验）', async () => {
+  const { ctx, sections } = await realCtx()
+  apply(ctx as unknown as Parameters<typeof apply>[0])
+  assert.equal(sections.length, 1, '准则没挂上 = 卡片亮着但 prompt 里没有准则')
+  assert.equal(sections[0]!.name, PROMPT_SECTION_NAME)
+  assert.equal(typeof sections[0]!.text, 'function', '静态文本 ⇒ 分类开关永远不生效')
+})
+
+test('注入：总开关关时段落文本为空（平台据此丢弃该段）', async () => {
+  const { ctx, sections } = await realCtx({ enabled: false })
+  apply(ctx as unknown as Parameters<typeof apply>[0])
+  const text = (sections[0]!.text as () => string)()
+  assert.equal(text, '', '总开关关时必须返回空串，而不是注入一段空白')
+})
+
+test('注入：用户关掉某分类 ⇒ 该分类不进 prompt（可开关的正向判据）', async () => {
+  const { ctx, sections } = await realCtx({ enabled: true, data: { categories: { identity: false } } })
+  apply(ctx as unknown as Parameters<typeof apply>[0])
+  const text = (sections[0]!.text as () => string)()
+  assert.equal(text.includes('大肥鱼'), false, 'identity 关了就不该出现')
+  assert.ok(text.includes('视野'), '其他分类照常')
+})
+
+// ── 面板编辑文本（2026-09-29）────────────────────────────────
+test('★ 每条都标 editable，面板才知道该不该给「修改」按钮', () => {
+  const ext = createPromptExt({ isSystemPromptReady: () => true, 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 c = (ext.controls ?? []).find((x) => x.id === 'identity')!
+  assert.equal(c.title, '我是谁')
+  assert.equal(c.body, '我是一个测试。')
+})
+
+test('★ controls 不是快照：改完之后**再读一次**要看到新值', () => {
+  // ⚠️ 2026-09-29 实测踩的 bug：`controls: CATEGORIES.map(...)` 那个 map 在
+  //   `createPromptExt()` 时就跑完了 ⇒ 编辑落盘后 prompt 变了、**面板拿到的还是
+  //   旧标题**（用户看到"保存了又变回去"）。而我当时注释写着"现算不缓存"。
+  //   ⇒ 判据必须**跨两次读**才抓得住（只读一次的写法抓不到）。
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const before = (ext.controls ?? []).find((x) => x.id === 'ladder')!
+  assert.equal(before.title, '懒人梯子')
+  ext.setControlText?.('ladder', { title: '我的梯子' })
+  const after = (ext.controls ?? []).find((x) => x.id === 'ladder')!
+  assert.equal(after.title, '我的梯子', 'controls 是快照 ⇒ 面板刷新后编辑内容会「变回去」')
+})
+
+test('setControlText 只写覆盖值，且不碰 categories（同块的另一种数据）', () => {
+  const store = fakeStore({ categories: { identity: false }, keep: 'me' })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.setControlText?.('identity', { title: '新标题' }), true)
+  const after = store.readData<Record<string, unknown>>('')
+  assert.deepEqual(after?.categories, { identity: false }, '改标题把开关状态冲掉了')
+  assert.equal(after?.keep, 'me', '把 data 抽屉里别的字段抹了')
+  assert.deepEqual(after?.text, { identity: { title: '新标题' } }, '只该存改过的字段')
+})
+
+test('★ 改一条**不碰其它条**的覆盖（整块重写 text 会静默丢别人的）', () => {
+  // ⚠️ 注入验证过：`text: { [id]: patch }` 这种写法**全绿** —— 它的破坏
+  //   只在"用户改过两条以上"时显形，而单人单条测试看不出来。
+  const store = fakeStore({
+    categories: {},
+    text: { identity: { title: 'A' }, scope: { body: 'B' } },
+  })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  ext.setControlText?.('ladder', { body: '新内容' })
+  assert.deepEqual(store.readData<Record<string, unknown>>('')?.text, {
+    identity: { title: 'A' },
+    scope: { body: 'B' },
+    ladder: { body: '新内容' },
+  }, '改一条把别人覆盖的抹了')
+})
+
+test('改同一条的第二个字段 ⇒ 第一个字段仍在（部分更新，不是替换）', () => {
+  const store = fakeStore({ categories: {}, text: { identity: { title: 'A' } } })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  ext.setControlText?.('identity', { body: 'B' })
+  assert.deepEqual(store.readData<Record<string, unknown>>('')?.text, {
+    identity: { title: 'A', body: 'B' },
+  })
+})
+
+test('注入：空标题/空正文返回 false（不写盘）', () => {
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  for (const bad of [{ title: '  ' }, { title: '' }, { body: '' }]) {
+    assert.equal(ext.setControlText?.('identity', bad), false, `空串被接受了：${JSON.stringify(bad)}`)
+  }
+  assert.equal(store.readData<Record<string, unknown>>('')?.text, undefined, '失败的写入留下了痕迹')
+})
+
+test('注入：未知 controlId 返回 false', () => {
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.setControlText?.('__evil__', { title: 'x' }), false)
+})
+
+/**
+ * 假 store：**整块替换**语义，与真实的 `ExtStore.writeData` 一致
+ * （`this.byId[id] = { …, data: value }`）。合并的替身会让「只改一个键」与
+ * 「整块重写」观测上完全一样 ⇒ 注入违规时测试照样全绿（2026-09-29 栽过）。
+ */
+function fakeStore(initial: Record<string, unknown> | undefined) {
+  const box = { data: initial }
+  return {
+    isEnabled: () => true,
+    setEnabled: () => {},
+    readData: <T,>(_id: string) => box.data as T | undefined,
+    writeData: (_id: string, value: unknown) => { box.data = value as Record<string, unknown> },
+  } as unknown as import('../ext/contract.ts').ExtStoreService
+}
+
+// ── 排序 / 自建 / 还原 / 删除（2026-09-29）──────────────────
+test('★ controls 走合成列表：自建条目出现、标 custom、内置标 overridden', () => {
+  const store = fakeStore({
+    categories: {},
+    custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }],
+    text: { ladder: { body: '改过的' } },
+  })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const list = ext.controls ?? []
+  assert.equal(list.length, PROMPT_CATEGORIES.length + 1, '自建条目没出现')
+  assert.equal(list.find((c) => c.id === 'cu-1')?.custom, true)
+  assert.equal(list.find((c) => c.id === 'ladder')?.overridden, true, '改过的内置条目要标 overridden（还原按钮可点）')
+  assert.equal(list.find((c) => c.id === 'identity')?.overridden, false, '没改过的不该标（还原按钮置灰）')
+})
+
+test('★ 新增自建条目 ⇒ 返回新 id，且落盘（id 不撞内置）', () => {
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const id = ext.addCustomControl?.('我的准则', '做完了就收。')
+  assert.ok(id !== null && typeof id === 'string', '没返回新 id')
+  assert.notEqual(id, 'identity', '新 id 撞上了内置条目')
+  assert.equal((ext.controls ?? []).some((c) => c.id === id), true, '落盘后没出现在 controls 里')
+})
+
+test('注入：空标题/空正文新增 ⇒ 返回 null（不写盘）', () => {
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.addCustomControl?.('  ', 'x'), null)
+  assert.equal(ext.addCustomControl?.('x', ''), null)
+  assert.equal(store.readData<Record<string, unknown>>('')?.custom, undefined, '失败的写入留下痕迹')
+})
+
+test('★ 删除只允许自定义：内置条目被拒、自建条目删掉并清干净关联数据', () => {
+  const store = fakeStore({
+    categories: { 'cu-1': true, identity: false },
+    text: { 'cu-1': { body: 'x' } },
+    order: ['cu-1', 'ladder'],
+    custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }],
+  })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.removeCustomControl?.('identity'), false, '内置条目不该被删（它是代码的一部分）')
+  assert.equal(ext.removeCustomControl?.('ladder'), false, '不存在的条目应被拒')
+  assert.equal(ext.removeCustomControl?.('cu-1'), true)
+  const after = store.readData<Record<string, unknown>>('') ?? {}
+  assert.deepEqual(after.custom, [], '自建条目没删掉')
+  assert.deepEqual(after.categories, { identity: false }, '删一条把别的开关状态弄丢了')
+  assert.deepEqual(after.order, ['ladder'], 'order 里留了幽灵 id')
+})
+
+test('★ 还原：只对被改过的内置条目成功，且回到内置文本', () => {
+  const store = fakeStore({ categories: {}, text: { ladder: { body: '改过的' } } })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.resetControlText?.('identity'), false, '没改过的内置条目不该「可还原」')
+  assert.equal(ext.resetControlText?.('cu-1'), false, '自建条目没有「内置版本」可回退')
+  assert.equal(ext.resetControlText?.('ladder'), true)
+  // ⚠️ 必须用 `deepEqual`：`assert.equal` 比的是**引用**，对象永远不等 ——
+  //   我第一版就写成这样，判据一直红而代码是对的。
+  assert.deepEqual(store.readData<Record<string, unknown>>('')?.text, {}, '覆盖没被丢掉')
+  assert.equal((ext.controls ?? []).find((c) => c.id === 'ladder')?.overridden, false)
+})
+
+test('★ 排序：只存 id，且过滤掉不存在的 id（脏数据不留幽灵）', () => {
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.setControlOrder?.(['__ghost__', 'ladder', 'ladder']), true)
+  assert.deepEqual(store.readData<Record<string, unknown>>('')?.order, ['ladder'], '幽灵/重复 id 没被过滤')
+})
+
+// ── 真实初始状态：`ext.json` 里只有 `{enabled:true}`，没有 `data` ──
+test('★ 没有 data 记录时也能写（"没改过" ≠ "不能写"）', () => {
+  // ⚠️ 这是 2026-09-30 实测的真 bug：`ext.json` 里 `prompt` 只有 `{enabled:true}`
+  //   （用户没改过任何东西 ⇒ 没有 `data` 键），而我把 `readData()` 返回 undefined
+  //   当成"存储不可用"直接拒 ⇒ 「添加准则」永远报 `title and body are required`
+  //   ——而 title/body 明明都传了，报错还指向错误的字段，排查成本极高。
+  const store = fakeStore(undefined) // **没有 data**
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  const id = ext.addCustomControl?.('我的准则', '做完就收。')
+  assert.ok(id !== null, '初始状态下添加失败（真实用户第一次用就是这个状态）')
+  assert.equal((ext.controls ?? []).some((c) => c.id === id), true, '写盘了但 controls 里没有')
+})
+
+test('★ 四个写入口在"无 data"时都可用（不只是 add）', () => {
+  const store = fakeStore(undefined)
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.setControl?.('ladder', false), true, '开关在初始状态下不可用')
+  assert.equal(ext.setControlText?.('ladder', { body: 'x' }), true, '改文本在初始状态下不可用')
+  assert.equal(ext.setControlOrder?.(['ladder']), true, '排序在初始状态下不可用')
+})
+
+test('★ 还原：改过 ⇒ true（且覆盖被清掉）；没改过 ⇒ false', () => {
+  // ⚠️ 这个用例第一版**测不出来**：我的假 store 把 `readData: () => undefined`
+  //   写死了，于是 setControlText 写进去的东西**读不回来**，还原永远失败 ——
+  //   而代码是对的。**假 store 比被守的东西更宽容 = 判据无效**（第三次栽在这）。
+  //   ⇒ 假 store 必须**真的读回自己写的东西**：`fakeStore` 的 `box` 已在做。
+  const store = fakeStore({ categories: {} })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, store })
+  assert.equal(ext.resetControlText?.('identity'), false, '没改过的却说可还原')
+  ext.setControlText?.('ladder', { body: '改过的' })
+  assert.equal(ext.resetControlText?.('ladder'), true, '改过的却还原不了')
+  assert.deepEqual(store.readData<Record<string, unknown>>('')?.text, {}, '覆盖没被清掉')
+})
+
+// ── 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 mine = (ext.controls ?? []).find((c) => c.id === 'cu-1')
+  const builtin = (ext.controls ?? []).find((c) => c.id === 'identity')
+  assert.equal(mine?.custom, true, '自建条目没标 custom ⇒ 面板给"还原"而不是"删除"')
+  assert.equal(builtin?.custom, false, '内置条目不该标 custom')
+  assert.notEqual(mine?.custom, undefined, 'custom 必须**显式**为 false，缺省与"未传"无法区分')
+})
+
+// ── 自建条目的写入口（2026-09-30 实测的「自定义开关报错」）──
+test('★ 自建条目的开关可切（判据要用合成列表，不能只用内置常量）', () => {
+  // ⚠️ 真实 bug：改动前 `setControl` 用 `PROMPT_CATEGORIES.some(...)` 判存在性，
+  //   而自建条目的 id 不在内置常量里 ⇒ **恒被拒**，报 `unknown controlId`
+  //   ⇒ 用户看到「自定义的开关控制报错」。而它**在 controls 列表里显示着** ——
+  //   列表用 `resolveCategories`、写入判据用 `PROMPT_CATEGORIES`，两处来源不一致。
+  const store = fakeStore({ categories: {}, custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }] })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, 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, '开关没落盘')
+})
+
+test('★ 自建条目的文本可改（同一处来源不一致）', () => {
+  const store = fakeStore({ categories: {}, custom: [{ id: 'cu-1', title: '我的', defaultOn: true, body: 'B' }] })
+  const ext = createPromptExt({ isSystemPromptReady: () => true, 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 })
+  assert.equal(ext.resetControlText?.('cu-1'), false, '自建条目不该能被「还原」')
+})
+
+// ── 图标（2026-09-30）────────────────────────────────────────
+test('★ 图标能被真实渲染（base64 必须解得出合法 SVG）', () => {
+  // ⚠️ 为什么需要这条：我第一版**手编**了一串 base64，解出来是乱码
+  //   （`tept-Gradient`、`#17118=D`…）。而客户端的 `onError` 会把加载失败的图
+  //   **静默藏掉**、退回默认闪电图标 ⇒ 页面"看起来正常"，图标却根本没换 ——
+  //   **编造的常量不会报错，这是它最险的地方**。
+  // ⇒ 判据钉住"能往返成 `<svg` 开头的合法文档"。
+  assert.ok(PROMPT_LOGO_URL.startsWith('data:image/svg+xml;base64,'), '必须是内联 data URI（离线可用）')
+  const decoded = Buffer.from(PROMPT_LOGO_URL.split(',')[1] ?? '', 'base64').toString('utf8')
+  assert.ok(decoded.trimStart().startsWith('<svg'), 'base64 解不出 SVG')
+  assert.ok(decoded.includes('</svg>'), 'SVG 没闭合')
+  // 属性引号必须成对：手编最容易在这里错（如我第一版那个 `fill="#17118=D"` ——
+  // 少一个引号，后面整段被当成属性值）。
+  // ⚠️ 检测的是**引号总数为偶数**，不是"引号后跟属性名" —— 属性之间本来就该有
+  // 空格（`width="64" height="64"`），我第一版正则把合法的也判成错位了。
+  assert.equal((decoded.match(/"/g) ?? []).length % 2, 0, 'SVG 属性引号不成对（手编 base64 的典型症状）')
+  assert.doesNotMatch(decoded, /tept|#17118=D/, '出现了已知的编造残留')
+  // ⚠️ 只检查"解得出 `<svg`"**不够**：`<svg></svg>` 语法完全合法、却什么都没画 ——
+  //   注入验证时它就是从这条判据下面溜过去的。⇒ 还要有**实际图元**。
+  assert.match(decoded, /<(rect|path|circle|g|line|polyline|polygon)\b/,
+    'SVG 里没有任何图元 —— 合法但画不出东西（空壳图标等于没换）')
+})
+
+test('图标挂在 ext 上（不设的话面板退回默认闪电）', () => {
+  const ext = createPromptExt({ isSystemPromptReady: () => true })
+  assert.equal(ext.icon, PROMPT_LOGO_URL)
+})
+
+test('logo.svg 源文件与 base64 一致（改了图忘了重生成就会漂）', () => {
+  // 源文件是唯一可编辑的形态；base64 是它的派生物。两者不一致 = 有人改了 svg
+  // 却没重新生成 ⇒ 面板显示的还是旧图，而且**没有任何报错**。
+  const src = readFileSync(new URL('./logo.svg', import.meta.url), 'utf8')
+  const decoded = Buffer.from(PROMPT_LOGO_URL.split(',')[1] ?? '', 'base64').toString('utf8')
+  const norm = (s: string): string => s.replace(/\s+/g, ' ').trim()
+  assert.equal(norm(decoded), norm(src), 'logo.svg 改了但 base64 没重新生成')
+})

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=='