fix(frontend): 修复 PR #18 审阅问题并补充回归测试

审阅意见逐项修复：

1. 主题包安装丢弃用户 CSS
   inspectThemePackage 之前只解析 YAML 清单，ThemesView 安装时另外
   生成一套硬编码调色板，用户提供的 CSS 被整份丢掉。现在定义单文件
   格式（YAML 清单 + `---` + CSS），parseThemePackage 取出真实 CSS
   并原样安装；CSS 安全校验提前到预览阶段；按内容识别并拒绝 ZIP。

2. 主题恢复竞态导致页面无 data-theme
   initTheme 之前没有 await loadCustomThemes，自定义主题还没进
   allThemes，applyTheme 找不到主题直接 return。现在先同步落一个
   内置主题兜底（不写 localStorage，避免冲掉用户存的自定义主题 id），
   加载完成后再切到真正保存的那个；主题失效或列表加载失败时回退并
   通过 themeLoadWarning 告知用户，不再静默。

3. Trace 建树依赖事件相邻顺序
   后端真实顺序是 ModelCallStarted → ModelCallCompleted → Usage →
   ToolCall/ToolResult，工具在模型调用完成后才执行且并发跑，相邻性
   不可用。改为按 model_call_id / parent_model_call_id / tool_call_id
   关联；ToolResult 回填 ToolCall 的状态与耗时，结束后不再显示
   running；SSE 断点恢复的孤立事件退回顶层而不是丢弃。

4. Trace 叶子节点无法查看数据
   行的 click 是 `children.length && toggleExpand`，而详情 v-if 又
   要求 `children.length === 0`，两个条件互斥。拆成 expandedNodes
   与 detailNodes 两个状态集合；展开箭头改为独立按钮，行支持键盘
   与 aria-expanded；引用节点补「定位」按钮。同时修正 Usage 卡片
   字段（后端只发累计 token_usage）。

5. 引用定位逻辑三处重复且各自有缺陷
   抽出 navigateToCitation（依赖注入，可独立测试）+ useCitationNavigation。
   调用顺序固化：必须先 await loadFile 再 highlightBlock，否则
   editor store 的 loadFile 末尾会把高亮清掉；loadFile 失败时不跳转。
   AgentView / ChatView / AppShell 统一走这一处。

6. 插件命令 UI 重复实现
   抽出 PluginCommandPanel 复用 PluginMcpPanel 的 schema 驱动表单，
   删除 PluginsView 里的劣化副本。effect 现在真的执行 navigate /
   refresh（此前只拼成文本显示）；补上必填校验与布尔字段初始值，
   修正「显示否但不提交该键」的不一致。

补充回归测试 64 项（相关 spec 由 25 项增至 89 项），并对 2、3、4 三项
缺陷做了变异验证：把修复回退成原写法后对应测试确实失败。
涉及 traceService / theme store / themePackageService / pluginCommandForm /
useCitationNavigation / TraceTimeline，其中后三个为新增文件。

vue-tsc -b、vitest（32 文件 182 项）、vite build 全部通过。

frontend/src/stores/theme.spec.ts

@@ -1,8 +1,41 @@
 // @vitest-environment happy-dom
-import { beforeEach, describe, expect, it } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
 import { nextTick } from 'vue'
+import type { InstalledTheme } from '@/contracts'
 import { useThemeStore } from './theme'
+import * as themePkg from '@/services/themePackageService'
+
+vi.mock('@/services/themePackageService', () => ({
+  listInstalledThemes: vi.fn(async () => []),
+  inspectThemePackage: vi.fn(),
+  installTheme: vi.fn(),
+  uninstallTheme: vi.fn(),
+  installCommunityTheme: vi.fn(),
+}))
+
+const listInstalledThemes = vi.mocked(themePkg.listInstalledThemes)
+
+function customTheme(themeId: string, isDark = false): InstalledTheme {
+  return {
+    theme_id: themeId,
+    name: themeId,
+    version: '1.0.0',
+    author: '社区',
+    is_dark: isDark,
+    builtin: false,
+    enabled: true,
+    manifest: {
+      theme_id: themeId,
+      name: themeId,
+      version: '1.0.0',
+      author: '社区',
+      min_app_version: '0.1.0',
+      is_dark: isDark,
+      css_entry: 'theme.css',
+    },
+  }
+}
 
 beforeEach(() => {
   localStorage.clear()
@@ -13,6 +46,8 @@ beforeEach(() => {
     configurable: true,
     value: () => ({ matches: false }),
   })
+  listInstalledThemes.mockReset()
+  listInstalledThemes.mockResolvedValue([])
 })
 
 describe('代码块主题偏好', () => {
@@ -38,10 +73,106 @@ describe('代码块主题偏好', () => {
   it('恢复持久化的代码块主题偏好', async () => {
     localStorage.setItem('editor-appearance', JSON.stringify({ codeBlockTheme: 'github-dark' }))
     const store = useThemeStore()
-    store.initTheme()
+    await store.initTheme()
     await nextTick()
 
     expect(store.codeBlockTheme).toBe('github-dark')
     expect(document.documentElement.dataset.codeTheme).toBe('github-dark')
   })
 })
+
+describe('initTheme 恢复已保存主题', () => {
+  it('等自定义主题加载完成后再恢复，不会停在没有 data-theme 的裸状态', async () => {
+    // 回归：之前这里是 `void loadCustomThemes()` 没有 await，
+    // applyTheme('ocean') 在主题列表到达前找不到主题直接 return，
+    // 页面上一个 data-theme 都没有。
+    localStorage.setItem('theme', 'ocean')
+    listInstalledThemes.mockResolvedValue([customTheme('ocean', true)])
+
+    const store = useThemeStore()
+    await store.initTheme()
+
+    expect(document.documentElement.getAttribute('data-theme')).toBe('ocean')
+    expect(store.currentThemeId).toBe('ocean')
+    expect(store.themeLoadWarning).toBeNull()
+  })
+
+  it('首屏先同步落内置主题兜底，且不覆盖保存的自定义主题 id', async () => {
+    localStorage.setItem('theme', 'ocean')
+    let resolveList: (themes: InstalledTheme[]) => void = () => {}
+    listInstalledThemes.mockReturnValue(
+      new Promise<InstalledTheme[]>((resolve) => { resolveList = resolve }),
+    )
+
+    const store = useThemeStore()
+    const pending = store.initTheme()
+
+    // 接口还没回来：页面已经有兜底主题，不是裸的
+    expect(document.documentElement.getAttribute('data-theme')).toBe('light')
+    // 兜底不能把用户存的主题 id 冲掉，否则刷新后自定义主题就丢了
+    expect(localStorage.getItem('theme')).toBe('ocean')
+
+    resolveList([customTheme('ocean', true)])
+    await pending
+
+    expect(document.documentElement.getAttribute('data-theme')).toBe('ocean')
+  })
+
+  it('保存的主题已被卸载时回退到默认主题并给出提示', async () => {
+    localStorage.setItem('theme', 'removed-theme')
+    listInstalledThemes.mockResolvedValue([])
+
+    const store = useThemeStore()
+    await store.initTheme()
+
+    expect(document.documentElement.getAttribute('data-theme')).toBe('light')
+    expect(store.currentThemeId).toBe('light')
+    expect(store.themeLoadWarning).toContain('removed-theme')
+    // 失效记录要清掉，避免每次启动都报一遍
+    expect(localStorage.getItem('theme')).toBe('light')
+  })
+
+  it('主题列表加载失败时提示用户，而不是静默只剩内置主题', async () => {
+    localStorage.setItem('theme', 'dark')
+    listInstalledThemes.mockRejectedValue(new Error('网络不可用'))
+
+    const store = useThemeStore()
+    await store.initTheme()
+
+    expect(store.themeLoadWarning).toBe('自定义主题加载失败：网络不可用')
+    // 内置主题仍然要正常恢复
+    expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
+  })
+
+  it('没有保存过主题时按系统偏好选择', async () => {
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      value: () => ({ matches: true }),
+    })
+
+    const store = useThemeStore()
+    await store.initTheme()
+
+    expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
+    expect(localStorage.getItem('theme')).toBe('dark')
+  })
+})
+
+describe('applyTheme 返回值', () => {
+  it('主题不存在时返回 false 且不改动 data-theme', () => {
+    const store = useThemeStore()
+    store.applyTheme('light')
+
+    expect(store.applyTheme('not-installed')).toBe(false)
+    expect(document.documentElement.getAttribute('data-theme')).toBe('light')
+    expect(store.currentThemeId).toBe('light')
+  })
+
+  it('persist: false 时不写 localStorage', () => {
+    const store = useThemeStore()
+    expect(store.applyTheme('sepia', { persist: false })).toBe(true)
+
+    expect(document.documentElement.getAttribute('data-theme')).toBe('sepia')
+    expect(localStorage.getItem('theme')).toBeNull()
+  })
+})

frontend/src/stores/theme.ts

@@ -47,6 +47,8 @@ export const useThemeStore = defineStore('theme', () => {
   const codeBlockTheme = ref<CodeBlockThemePreference>('auto')
   const isImporting = ref(false)
   const importError = ref<string | null>(null)
+  // 主题恢复阶段的提示（保存的主题已卸载、主题列表加载失败等），与导入错误分开。
+  const themeLoadWarning = ref<string | null>(null)
   const pendingInspection = ref<ThemePackageInspection | null>(null)
   let appearanceHydrated = false
 
@@ -66,9 +68,10 @@ export const useThemeStore = defineStore('theme', () => {
     return currentTheme.value?.code_theme ?? (isDark.value ? 'github-dark' : 'github-light')
   })
 
-  function applyTheme(themeId: string) {
+  /** 应用主题；返回 false 表示该主题当前不存在（未安装或还没加载完）。 */
+  function applyTheme(themeId: string, options: { persist?: boolean } = {}): boolean {
     const theme = allThemes.value.find((t) => t.theme_id === themeId)
-    if (!theme) return
+    if (!theme) return false
     currentThemeId.value = themeId
     const root = document.documentElement
     if (theme.builtin) {
@@ -82,10 +85,28 @@ export const useThemeStore = defineStore('theme', () => {
     } else {
       root.setAttribute('data-theme', themeId)
     }
-    localStorage.setItem('theme', themeId)
+    if (options.persist !== false) localStorage.setItem('theme', themeId)
+    return true
   }
 
-  function initTheme() {
+  function isBuiltinThemeId(themeId: string): boolean {
+    return builtinThemes.some((t) => t.theme_id === themeId)
+  }
+
+  function systemThemeId(): string {
+    return window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  }
+
+  /**
+   * 恢复外观与主题。
+   *
+   * 自定义主题要等 listInstalledThemes 回来才存在于 allThemes 里，
+   * 所以恢复已保存主题必须在 loadCustomThemes 之后 —— 否则 applyTheme
+   * 找不到主题直接 return，页面会停在没有 data-theme 的裸状态。
+   * 首屏也不能干等接口：先同步落一个内置主题兜底（不写 localStorage，
+   * 以免把用户存的自定义主题 id 冲掉），加载完成后再切到真正保存的那个。
+   */
+  async function initTheme(): Promise<void> {
     const savedAppearance = localStorage.getItem('editor-appearance')
     if (savedAppearance) {
       try {
@@ -96,16 +117,25 @@ export const useThemeStore = defineStore('theme', () => {
         if (isCodeBlockThemePreference(value.codeBlockTheme)) codeBlockTheme.value = value.codeBlockTheme
       } catch { localStorage.removeItem('editor-appearance') }
     }
-    void loadCustomThemes()
-    const saved = localStorage.getItem('theme')
     appearanceHydrated = true
     persistAppearance()
-    if (saved) {
-      applyTheme(saved)
+
+    const saved = localStorage.getItem('theme')
+    const fallback = systemThemeId()
+    applyTheme(saved && isBuiltinThemeId(saved) ? saved : fallback, { persist: false })
+
+    await loadCustomThemes()
+
+    if (!saved) {
+      applyTheme(fallback)
       return
     }
-    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
-    applyTheme(prefersDark ? 'dark' : 'light')
+    if (applyTheme(saved)) return
+
+    // 保存的主题已被卸载，或主题列表加载失败：回退并清掉失效记录。
+    themeLoadWarning.value = `主题「${saved}」已不可用，已回退到默认主题。`
+    localStorage.removeItem('theme')
+    applyTheme(fallback)
   }
 
   async function loadCustomThemes() {
@@ -122,7 +152,13 @@ export const useThemeStore = defineStore('theme', () => {
         author: t.author,
         code_theme: t.code_theme,
       }))]
-    } catch { /* keep builtin only */ }
+      themeLoadWarning.value = null
+    } catch (error) {
+      // 只保留内置主题，但要让用户知道自定义主题这次没加载上。
+      themeLoadWarning.value = error instanceof Error
+        ? `自定义主题加载失败：${error.message}`
+        : '自定义主题加载失败。'
+    }
   }
 
   function toggleTheme() {
@@ -272,6 +308,7 @@ export const useThemeStore = defineStore('theme', () => {
     resolvedCodeBlockTheme,
     isImporting,
     importError,
+    themeLoadWarning,
     pendingInspection,
     allThemes,
     applyTheme,

frontend/src/stores/workspace.ts

@@ -62,6 +62,12 @@ export const useWorkspaceStore = defineStore('workspace', () => {
     recentVaults.value = await workspaceService.getRecentVaults()
   }
 
+  /** 重新拉取文件树。插件命令返回 refresh:workspace 时需要。 */
+  async function refreshFileTree() {
+    if (!hasVault.value) return
+    fileTree.value = await workspaceService.getFileTree()
+  }
+
   async function openVault(path: string) {
     isLoading.value = true
     try {
@@ -161,6 +167,7 @@ export const useWorkspaceStore = defineStore('workspace', () => {
     closeFile,
     setActiveFile,
     loadRecentVaults,
+    refreshFileTree,
     openVault,
     createVault,
     addFileToTree,