feat(settings): 侧边栏设置声明式化 — 注册表驱动的开关清单 + 内置支持插头化

- SidebarPrefs 新增 tabsEnabled / viewersEnabled 开放 map（缺省 = 启用）， PrefsSchema 用 z.dict 校验，旧文档零迁移 - TabDescriptor/FileViewerDescriptor 新增声明式设置面：viewer 补 title/icon，两者补 settings.toggles（子代理声明 autoOpenSubagent、终端声明 agentTerminalTools） - 服务新增 isTabEnabled/isViewerEnabled；openTab 拒绝禁用类型、matchFileViewer 跳过禁用 viewer - SideCardSection 重写为注册表驱动清单：侧边栏内容（图标+类型id+开关+嵌套开关） + 文件预览（图标+标题+扩展名+开关），开关持久化 + 乐观提交回滚 - 消费点 gating：+ 菜单过滤、子代理自动展开、agent 终端 reconcile、产出文件拦截（editor 关闭时回落默认行）、新会话 explorer 预置 - 内置 viewer 补 6 个手绘 outline 图标；store 快照携带 prefs 使开关变更即时生效 - 测试：service gating / builtins 声明 / parsePrefs map 校验 / schema 断言 / 新增 SideCardSection renderToString 规格 - 文档：README 设置小节、AGENTS.md 描述符与服务方法、新增设计文档；版本 0.5.0
2026-08-11 14:08:55 +08:00
parent 89d2c65707
commit 89ddf8a9e7
25 changed files with 938 additions and 99 deletions
@@ -39,6 +39,25 @@ describe('built-in tab registrations', () => {
      expect(service.getTab(id)?.single).toBe(true)
    }
  })
+
+  it('the subagent tab declares its auto-open related setting', () => {
+    const { service } = setup()
+    const toggles = service.getTab('subagent')?.settings?.toggles ?? []
+    expect(toggles.map(t => t.key)).toEqual(['autoOpenSubagent'])
+  })
+
+  it('the terminal tab declares the model terminal-tools related setting', () => {
+    const { service } = setup()
+    const toggles = service.getTab('terminal')?.settings?.toggles ?? []
+    expect(toggles.map(t => t.key)).toEqual(['agentTerminalTools'])
+  })
+
+  it('every built-in tab carries the settings-surface icon', () => {
+    const { service } = setup()
+    for (const tab of service.getTabs()) {
+      expect(tab.icon, tab.id).toBeDefined()
+    }
+  })
 })

 describe('built-in file viewer registrations', () => {
@@ -88,6 +107,14 @@ describe('built-in file viewer registrations', () => {
    // claims it before binary-download (-50) is consulted.
    expect(service.matchFileViewer('book.docx', new Uint8Array([0x50, 0x4b, 0x03, 0x04]))?.id).toBe('docx')
  })
+
+  it('every built-in viewer carries the declarative settings surface (title + icon)', () => {
+    const { service } = setup()
+    for (const viewer of service.getFileViewers()) {
+      expect(viewer.title, viewer.id).toBeDefined()
+      expect(viewer.icon, viewer.id).toBeDefined()
+    }
+  })
 })

 describe('built-in disposer', () => {
@@ -48,12 +48,15 @@ describe('dsh-better-sidebar plugin export shape', () => {
    // The terminal tools default OFF (the feature is dormant until the user
    // enables it in the side card settings).
    expect(resolved.agentTerminalTools).toBe(false)
+    // The enable-switch maps resolve to {} (everything on) for old documents.
+    expect(resolved.tabsEnabled).toEqual({})
+    expect(resolved.viewersEnabled).toEqual({})
    // A stored overridden value resolves through (the range contract is
    // enforced by the settings service on write); the new pref keeps its
    // default when the stored document predates it.
    const overridden = (PrefsSchema as unknown as {
      (input: Record<string, unknown> | undefined): Record<string, unknown>
    })({ openByDefault: false, defaultWidthPercent: 45 })
-    expect(overridden).toEqual({ openByDefault: false, defaultWidthPercent: 45, autoOpenSubagent: true, agentTerminalTools: false })
+    expect(overridden).toEqual({ openByDefault: false, defaultWidthPercent: 45, autoOpenSubagent: true, agentTerminalTools: false, tabsEnabled: {}, viewersEnabled: {} })
  })
 })
@@ -77,6 +77,57 @@ describe('BetterSidebar service', () => {
  })
 })

+describe('enable switches (declarative settings)', () => {
+  /** A fresh store + service with one tab and one viewer registered. */
+  const setup = () => {
+    const store = createSidebarStore()
+    const service = createBetterSidebarService(store)
+    service.registerTab({ id: 'explorer', title: 'Explorer', component: () => null })
+    service.registerFileViewer({ id: 'image', exts: ['png'], fetchStrategy: 'mediaUrl', component: () => null })
+    return { store, service }
+  }
+
+  it('an absent map key means enabled (default state)', () => {
+    const { service } = setup()
+    expect(service.isTabEnabled('explorer')).toBe(true)
+    expect(service.isViewerEnabled('image')).toBe(true)
+    // Unknown ids are enabled too (nothing registered → the check is open).
+    expect(service.isTabEnabled('whatever')).toBe(true)
+  })
+
+  it('only an explicit false disables a tab type', () => {
+    const { store, service } = setup()
+    store.setPrefs({ ...store.getPrefs(), tabsEnabled: { explorer: false } })
+    expect(service.isTabEnabled('explorer')).toBe(false)
+    store.setPrefs({ ...store.getPrefs(), tabsEnabled: { explorer: true } })
+    expect(service.isTabEnabled('explorer')).toBe(true)
+  })
+
+  it('openTab refuses a disabled tab type (no tab lands, no createTab)', () => {
+    const { store, service } = setup()
+    store.setPrefs({ ...store.getPrefs(), tabsEnabled: { explorer: false } })
+    store.setSession('s1')
+    service.openTab({ type: 'explorer', title: 'Explorer' })
+    const tabs = allLeaves(store.getSnapshot().state!.splits).flatMap(l => l.tabs)
+    expect(tabs).toHaveLength(0)
+  })
+
+  it('matchFileViewer skips a disabled viewer (files fall through)', () => {
+    const { store, service } = setup()
+    service.registerFileViewer({ id: 'code', exts: [], priority: -100, fetchStrategy: 'fsRead', component: () => null })
+    // image claims .png; disabling it lets the catch-all take over.
+    expect(service.matchFileViewer('photo.png')?.id).toBe('image')
+    store.setPrefs({ ...store.getPrefs(), viewersEnabled: { image: false } })
+    expect(service.matchFileViewer('photo.png')?.id).toBe('code')
+    // Disabling the catch-all too → no viewer at all.
+    store.setPrefs({ ...store.getPrefs(), viewersEnabled: { image: false, code: false } })
+    expect(service.matchFileViewer('photo.png')).toBeUndefined()
+    // Re-enabling restores the image viewer.
+    store.setPrefs({ ...store.getPrefs(), viewersEnabled: {} })
+    expect(service.matchFileViewer('photo.png')?.id).toBe('image')
+  })
+})
+
 describe('matchFileViewer', () => {
  it('matches by extension', () => {
    const store = createSidebarStore()
@@ -0,0 +1,117 @@
+/**
+ * Side card settings section render tests: the section is DECLARATIVE —
+ * every row (icon, title, type id, extensions, enable switch) derives from
+ * the sidebar service's tab/viewer registries instead of hardcoded copy.
+ * These specs pin that derivation with a fake store + a small registry:
+ * registered tabs/viewers appear with their declared icon/title/settings,
+ * disabled states render unchecked, and a disabled tab hides its declared
+ * nested toggles.
+ *
+ * Rendered with renderToString (mount effects — the settings RPC sync — do
+ * not run in SSR; the initial store prefs are the render input).
+ */
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { createElement } from 'react'
+import { createSidebarStore, type SidebarStore } from '../src/client/state.ts'
+import { createBetterSidebarService, type BetterSidebarService } from '../src/client/service.ts'
+import { SideCardSection, type SideCardSectionProps } from '../src/client/SideCardSection.tsx'
+
+/** One tab + one viewer + the subagent-style nested toggle under a tab. */
+function mount(): { store: SidebarStore; service: BetterSidebarService } {
+  const store = createSidebarStore()
+  const service = createBetterSidebarService(store)
+  service.registerTab({
+    id: 'explorer',
+    title: () => 'Explorer',
+    icon: () => createElement('svg', { 'data-icon': 'explorer' }),
+    order: 10,
+    component: () => null,
+  })
+  service.registerTab({
+    id: 'subagent',
+    title: () => 'Subagents',
+    icon: () => createElement('svg', { 'data-icon': 'subagent' }),
+    order: 30,
+    settings: {
+      toggles: [{
+        key: 'autoOpenSubagent',
+        title: () => 'Auto-open Subagents',
+        desc: () => 'Expand on new subagent',
+      }],
+    },
+    component: () => null,
+  })
+  service.registerFileViewer({
+    id: 'image',
+    title: () => 'Image',
+    icon: () => createElement('svg', { 'data-icon': 'image' }),
+    exts: ['png', 'jpg'],
+    fetchStrategy: 'mediaUrl',
+    component: () => null,
+  })
+  return { store, service }
+}
+
+function renderSection(store: SidebarStore, service: BetterSidebarService): string {
+  return renderToString(createElement(
+    SideCardSection,
+    { store, service } as unknown as SideCardSectionProps,
+  ))
+}
+
+describe('SideCardSection declarative inventory', () => {
+  it('renders one row per registered tab: icon + title + type id + switch', () => {
+    const { store, service } = mount()
+    const html = renderSection(store, service)
+    expect(html).toContain('data-icon="explorer"')
+    expect(html).toContain('>Explorer<')
+    // The type id is the row's desc (the declarative "type" surface).
+    expect(html).toContain('>explorer<')
+    expect(html).toContain('data-icon="subagent"')
+    expect(html).toContain('>Subagents<')
+    // Both tabs are enabled by default: their switches render checked.
+    expect(html.match(/type="checkbox"/g)?.length).toBeGreaterThanOrEqual(4)
+  })
+
+  it('renders the declared nested toggle under an enabled tab', () => {
+    const { store, service } = mount()
+    const html = renderSection(store, service)
+    // The subagent tab's declared related setting appears while enabled,
+    // bound to its prefs key (default true → checked).
+    expect(html).toContain('Auto-open Subagents')
+    expect(html).toContain('Expand on new subagent')
+  })
+
+  it('hides the nested toggles while the parent tab is disabled', () => {
+    const { store, service } = mount()
+    store.setPrefs({ ...store.getPrefs(), tabsEnabled: { subagent: false } })
+    const html = renderSection(store, service)
+    // The parent row stays (so the user can re-enable it) but unchecked.
+    expect(html).toContain('>Subagents<')
+    expect(html).not.toContain('Auto-open Subagents')
+  })
+
+  it('renders one row per registered viewer: icon + title + exts + switch', () => {
+    const { store, service } = mount()
+    const html = renderSection(store, service)
+    expect(html).toContain('data-icon="image"')
+    expect(html).toContain('>Image<')
+    // The covered extensions are the row's desc.
+    expect(html).toContain('png · jpg')
+  })
+
+  it('a disabled viewer renders unchecked', () => {
+    const { store, service } = mount()
+    store.setPrefs({ ...store.getPrefs(), viewersEnabled: { image: false } })
+    const html = renderSection(store, service)
+    expect(html).toContain('>Image<')
+  })
+
+  it('a disabled tab renders unchecked (its switch reflects the prefs map)', () => {
+    const { store, service } = mount()
+    store.setPrefs({ ...store.getPrefs(), tabsEnabled: { explorer: false } })
+    const html = renderSection(store, service)
+    expect(html).toContain('>explorer<')
+  })
+})
@@ -502,7 +502,15 @@ describe('side card settings routes', () => {
    const read = await invoke(route, 'settings.get', {})
    expect(read.ok).toBe(true)
    expect(read.value).toEqual({
-      value: { openByDefault: true, defaultWidthPercent: 30, autoOpenSubagent: true, agentTerminalTools: false },
+      value: {
+        openByDefault: true,
+        defaultWidthPercent: 30,
+        autoOpenSubagent: true,
+        agentTerminalTools: false,
+        // The enable-switch maps default to {} (everything on).
+        tabsEnabled: {},
+        viewersEnabled: {},
+      },
      revision: 0,
    })

@@ -829,17 +829,38 @@ describe('side card preferences', () => {

  it('parses a valid value and clamps the percent into the contract range', async () => {
    expect(await loadPrefs(wire({ openByDefault: false, defaultWidthPercent: 80, autoOpenSubagent: false, agentTerminalTools: true })))
-      .toEqual({ openByDefault: false, defaultWidthPercent: 60, autoOpenSubagent: false, agentTerminalTools: true })
+      .toEqual({
+        openByDefault: false,
+        defaultWidthPercent: 60,
+        autoOpenSubagent: false,
+        agentTerminalTools: true,
+        tabsEnabled: {},
+        viewersEnabled: {},
+      })
  })

  it('falls back per-field when a stored field is malformed', async () => {
    expect(await loadPrefs(wire({ openByDefault: 'yes', defaultWidthPercent: 33, autoOpenSubagent: 'no', agentTerminalTools: 'yes' })))
-      .toEqual({ openByDefault: true, defaultWidthPercent: 33, autoOpenSubagent: true, agentTerminalTools: false })
+      .toEqual({
+        openByDefault: true,
+        defaultWidthPercent: 33,
+        autoOpenSubagent: true,
+        agentTerminalTools: false,
+        tabsEnabled: {},
+        viewersEnabled: {},
+      })
  })

  it('defaults autoOpenSubagent to true and agentTerminalTools to false when the stored value is absent or malformed', async () => {
    expect(await loadPrefs(wire({ openByDefault: false, defaultWidthPercent: 40 })))
-      .toEqual({ openByDefault: false, defaultWidthPercent: 40, autoOpenSubagent: true, agentTerminalTools: false })
+      .toEqual({
+        openByDefault: false,
+        defaultWidthPercent: 40,
+        autoOpenSubagent: true,
+        agentTerminalTools: false,
+        tabsEnabled: {},
+        viewersEnabled: {},
+      })
    expect((await loadPrefs(wire({ openByDefault: true, defaultWidthPercent: 40, autoOpenSubagent: 1 }))).autoOpenSubagent)
      .toBe(true)
    // The terminal-tools feature is OFF by default; only an explicit true turns it on.
@@ -851,13 +872,26 @@ describe('side card preferences', () => {
      .toBe(true)
  })

+  it('validates the per-tab / per-viewer enable maps (absent keys mean enabled)', async () => {
+    // A non-object map falls back to {} (everything enabled).
+    expect((await loadPrefs(wire({ tabsEnabled: 'nope' }))).tabsEnabled).toEqual({})
+    expect((await loadPrefs(wire({ viewersEnabled: [1, 2] }))).viewersEnabled).toEqual({})
+    // Non-boolean entries are dropped; boolean entries survive verbatim.
+    const parsed = await loadPrefs(wire({
+      tabsEnabled: { git: false, explorer: true, bad: 'yes' },
+      viewersEnabled: { image: false, code: 1 },
+    }))
+    expect(parsed.tabsEnabled).toEqual({ git: false, explorer: true })
+    expect(parsed.viewersEnabled).toEqual({ image: false })
+  })
+
  it('seeds new-session defaults from the store prefs (open flag + width)', () => {
    const store = createSidebarStore()
    // Node environment: no window → the width falls back to PANEL_DEFAULT,
    // while the open flag still follows the preference.
-    store.setPrefs({ openByDefault: false, defaultWidthPercent: 45, autoOpenSubagent: true, agentTerminalTools: false })
+    store.setPrefs({ openByDefault: false, defaultWidthPercent: 45, autoOpenSubagent: true, agentTerminalTools: false, tabsEnabled: {}, viewersEnabled: {} })
    store.setSession('fresh-session')
-    expect(store.getPrefs()).toEqual({ openByDefault: false, defaultWidthPercent: 45, autoOpenSubagent: true, agentTerminalTools: false })
+    expect(store.getPrefs()).toEqual({ openByDefault: false, defaultWidthPercent: 45, autoOpenSubagent: true, agentTerminalTools: false, tabsEnabled: {}, viewersEnabled: {} })
    const snapshot = store.getSnapshot()
    expect(snapshot.sessionId).toBe('fresh-session')
    expect(snapshot.state?.panelOpen).toBe(false)
@@ -868,6 +902,22 @@ describe('side card preferences', () => {
    expect(openStore.getSnapshot().state?.panelOpen).toBe(true)
  })

+  it('skips the default explorer tab when the explorer type is disabled', () => {
+    const store = createSidebarStore()
+    store.setPrefs({ openByDefault: true, defaultWidthPercent: 30, autoOpenSubagent: true, agentTerminalTools: false, tabsEnabled: { explorer: false }, viewersEnabled: {} })
+    store.setSession('no-explorer')
+    const state = store.getSnapshot().state!
+    const tabs = allLeaves(state.splits).flatMap(leaf => leaf.tabs)
+    expect(tabs).toHaveLength(0)
+    expect(state.splits.kind).toBe('leaf')
+    // Re-enabling seeds the explorer tab again.
+    const openStore = createSidebarStore()
+    openStore.setPrefs({ openByDefault: true, defaultWidthPercent: 30, autoOpenSubagent: true, agentTerminalTools: false, tabsEnabled: {}, viewersEnabled: {} })
+    openStore.setSession('with-explorer')
+    const openTabs = allLeaves(openStore.getSnapshot().state!.splits).flatMap(leaf => leaf.tabs)
+    expect(openTabs.map(tab => tab.type)).toEqual(['explorer'])
+  })
+
  it('derives the default width from the window percent with clamps', () => {
    expect(defaultWidthFor(1440, 30)).toBe(432)
    expect(defaultWidthFor(800, 30)).toBe(280) // the panel floor
@@ -878,6 +928,9 @@ describe('side card preferences', () => {
    expect(makeDefaultState().panelOpen).toBe(true)
    expect(makeDefaultState(400, false).panelOpen).toBe(false)
    expect(makeDefaultState(400, false).width).toBe(400)
+    // The seedExplorer flag controls the default explorer tab.
+    expect(makeDefaultState(400, true, false).splits.kind).toBe('leaf')
+    expect((makeDefaultState(400, true, false).splits as { tabs: unknown[] }).tabs).toHaveLength(0)
  })
 })