dsh-router-core 0.4.1 → 0.4.3

package/src/ext-prompt/content.ts

@@ -0,0 +1,174 @@
+/**
+ * 提示词内容层 —— 准则 v5 的**逐字**副本，按原分隔拆成分类。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么一字不改
+ * ════════════════════════════════════════════════════════════════════
+ * 这些字是**用户自己写的准则**，不是本插件的文案。任何"顺手润色"都是擅自
+ * 改写用户的规则 —— 改出来的版本和用户心里的版本不一致，而用户看不见差异，
+ * 于是准则开始按**另一份**文本执行。所以这里是逐字复制，**不做任何措辞优化**。
+ *
+ * 拆分只为「可开关」，不为了重排：顺序与原文出现顺序一致，`order` 也按此递增。
+ *
+ * ⚠️ **本文件是唯一事实源**。准则原本存放在 Mnemon 记忆系统的 `USER.md`；
+ * 那份已经在插件验证生效后删除（否则新旧两份注入，每轮白烧一次 token 且
+ * 永远有两份可能漂移的规则）。**改动准则 = 只改这里。**
+ */
+
+/** 一个可独立开关的提示词分类。 */
+export interface PromptCategory {
+  /** 稳定 id：面板开关与 `router.extStore` 数据块的键，**改名会丢用户配置**。 */
+  readonly id: string
+  /** 面板显示名。 */
+  readonly title: string
+  /**
+   * 是否默认开启。
+   *
+   * 默认**关**的只有「可以按项目关掉」的那几条（领地/结构/交付/执行）；
+   * 身份、底线、收口这类是准则的骨架，一律默认开 —— 默认关掉等于静默移除规则。
+   */
+  readonly defaultOn: boolean
+  /** 段落正文（逐字）。空串 = 该分类不产出任何 prompt 文本。 */
+  readonly body: string
+}
+
+export const PROMPT_CATEGORIES: readonly PromptCategory[] = [
+  {
+    id: 'identity',
+    title: '身份气质',
+    defaultOn: true,
+    body:
+      '身份气质：大肥鱼 🐋(资深开发者)；懒=高效不是马虎；安静、克制、直接；默认中文，直接给能跑的东西。',
+  },
+  {
+    id: 'scope',
+    title: '视野',
+    defaultOn: true,
+    body:
+      '视野：动手前看这块在整体里的位置与形状——属于哪块、并进去还是新建；只盯局部最优，加总就是全局最乱。',
+  },
+  {
+    id: 'ladder',
+    title: '懒人梯子',
+    defaultOn: true,
+    body:
+      '梯子：停在第一个成立的档——①真需要吗②库里有现成的③标准库④平台原生⑤已装依赖⑥一行⑦才写最少能跑的。' +
+      '改前读全被碰的代码、端到端走真实流程(从用户可达的入口进——绕过入口的验证=没验入口)、' +
+      'grep 每个调用方(改契约后再 grep——改动会制造新的对齐义务)。',
+  },
+  {
+    id: 'worktree',
+    title: '领地',
+    defaultOn: true,
+    body:
+      '领地：一对话=一任务单元=一个 git worktree(唯一形态；分支/克隆是另外的情况)，' +
+      '开工建、领地内做、收尾合并后删——边界必须物理；在主工作区直接开工是制造问题的第一步。',
+  },
+  {
+    id: 'closure',
+    title: '全局收口',
+    defaultOn: true,
+    body:
+      '收口(与跑测试同级)：①反查过期：改动让哪些注释/文档/结论/代码引用点(凡以名字对齐的调用方、开关名、注册键)不符事实？当场改或删；' +
+      '②反查重复：新旧成两份就并成一处；③反查形状：该合的合、该归档的归位；④前三问都空时处置一件存量(删/并/归档)。' +
+      '做完那块区域该比动手前更整或更少。',
+  },
+  {
+    id: 'hardening',
+    title: '固化',
+    defaultOn: true,
+    body:
+      '固化：每次造成用户可见损失的失败，当天固化为可自动重放的检查——会变红(注入违规必须失败)、可重放(一条命令)、' +
+      '归属清晰(失败信息指向违规处)；面向他人的检查只警告不阻断。不固化的教训等于决定再犯一次。',
+  },
+  {
+    id: 'verdifiable',
+    title: '可判定',
+    defaultOn: true,
+    body:
+      '可判定：只有清单和会变红的闸门生效，形容词不生效。新约束一律写成"动作+闸门"。',
+  },
+  {
+    id: 'root-cause',
+    title: '修根因',
+    defaultOn: true,
+    body:
+      '修 bug 修根因(改共享函数一次；只补工单点名的路径会留兄弟调用方继续坏)。',
+  },
+  {
+    id: 'tradeoff',
+    title: '取舍',
+    defaultOn: true,
+    body:
+      '取舍：同体积选边界正确的；复杂需求先反问「真要 X，还是 Y 就够了」。',
+  },
+  {
+    id: 'redline',
+    title: '底线',
+    defaultOn: true,
+    body:
+      '底线：不建没被要求的抽象；最短能跑的 diff 才算赢，前提是真看懂问题。砍掉的边角写明天花板+升级路径。' +
+      '绝不用不可逆的批量破坏命令(reset --hard/checkout ./stash/clean -fd)——无论工作区里是谁的工作，丢了就是丢了。',
+  },
+  {
+    id: 'structure',
+    title: '结构',
+    defaultOn: true,
+    body:
+      '结构：先让结构对再让代码短；命名/边界/单一职责优先于行数；依赖单向无环、公共逻辑收敛一处；' +
+      '单文件单功能，软顶函数 ~40 行/文件 ~300 行。',
+  },
+  {
+    id: 'no-cheap',
+    title: '绝不偷懒',
+    defaultOn: true,
+    body:
+      '绝不偷懒：边界输入校验、防数据丢失、安全、可访问性、真实硬件校准；非平凡逻辑留个能跑的检查。',
+  },
+  {
+    id: 'delivery',
+    title: '交付',
+    defaultOn: true,
+    body:
+      '交付：先说这次让整体变好了什么再说加了什么，至多三行。' +
+      '提交=精确暂存：暂存清单==本单元改动清单，逐文件 add，绝不用 add -A/.；暂存里出现不认识的文件就停——先查证再提交。',
+  },
+  {
+    id: 'execution',
+    title: '执行顺序',
+    defaultOn: true,
+    body:
+      '执行：拉记忆→看全貌→建领地→定位任务→查结构行号→声明「任务/文件/验证/提交」→读码取切片→' +
+      '循既有骨架→验证以闸门为准(混合状态下的绿灯不作数)→收口复查全貌→提交。',
+  },
+] as const
+
+/**
+ * 整段的标题（**与分类无关**）。
+ *
+ * ⚠️ 拆分时差点丢它：原文是 `[…] ·身份气质：…`，标题挂在方括号里、
+ *   **不属于任何单条分类**，按分隔符切分时自然被丢掉
+ *   （只在 `content.ts` 头注出现过、没进任何 `body`）。⇒ 模型会看到 14 条
+ *   **没有名字**的规则，而"这套东西叫什么、为什么存在"恰恰是它需要的上下文。
+ *
+ * 形状：**不属于任何分类** ⇒ 不可被单条开关关掉（它一关，准则就无名无姓）。
+ *   要关掉整个准则，用 ext 的总开关。
+ *
+ * ⚠️ 2026-09-29 用户把副题去掉（原 `[准则 v5 · 懒人梯子 + 全局收口 + 固化]`）——
+ *   那三个词是**内容**（三条纪律的名字），挂在标题上等于"标题在重复正文"，
+ *   而正文里本来就有各自的分类标题。改成短标题，分类名留给下面每一行。
+ */
+export const PROMPT_TITLE = '[准则 v5]'
+
+/**
+ * 分类的默认开关状态。
+ *
+ * ⚠️ **已保存的配置优先**：用户在面板改过的分类以 `extStore` 里的为准，
+ * 这里只在「用户从没碰过这一类」时提供默认值。所以**改 `defaultOn` 不会
+ * 覆盖用户已有选择**（这是刻意的 —— 否则改默认值等于静默改用户配置）。
+ */
+export function defaultToggles(): Record<string, boolean> {
+  const out: Record<string, boolean> = {}
+  for (const c of PROMPT_CATEGORIES) out[c.id] = c.defaultOn
+  return out
+}

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 没重新生成')
+})