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/services/pluginCommandForm.spec.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  applyCommandEffect,
+  cleanArguments,
+  coerceArgument,
+  commandFields,
+  EFFECT_ROUTES,
+  initialArguments,
+  missingRequiredFields,
+} from './pluginCommandForm'
+import type { PluginCommand, PluginCommandEffect } from '@/contracts'
+
+function command(parameters: Record<string, unknown>): PluginCommand {
+  return {
+    command_id: 'demo.run',
+    plugin_id: 'demo',
+    title: '示例命令',
+    description: '',
+    locations: [],
+    when: [],
+    parameters,
+    enabled: true,
+  }
+}
+
+/** 后端只接受 type=object 的 JSON Schema（contributions.py 显式拒绝其他形态）。 */
+const schema = command({
+  type: 'object',
+  properties: {
+    path: { type: 'string', title: '笔记路径', description: '相对于库根目录' },
+    count: { type: 'integer', default: 3 },
+    recursive: { type: 'boolean' },
+    mode: { type: 'string', enum: ['fast', 'full'] },
+  },
+  required: ['path', 'mode'],
+})
+
+describe('commandFields', () => {
+  it('摊平 properties 并标记 required', () => {
+    const fields = commandFields(schema)
+
+    expect(fields.map((f) => f.key)).toEqual(['path', 'count', 'recursive', 'mode'])
+    expect(fields[0]).toMatchObject({ title: '笔记路径', type: 'string', required: true })
+    expect(fields[1]).toMatchObject({ type: 'integer', required: false, default: 3 })
+    expect(fields[3].enum).toEqual(['fast', 'full'])
+  })
+
+  it('没有 title 时用字段名兜底，没有 type 时按 string 处理', () => {
+    const fields = commandFields(command({ type: 'object', properties: { raw: {} } }))
+
+    expect(fields[0]).toMatchObject({ key: 'raw', title: 'raw', type: 'string', required: false })
+  })
+
+  it('parameters 为空或形态异常时返回空数组而不是抛错', () => {
+    expect(commandFields(command({}))).toEqual([])
+    expect(commandFields(command({ type: 'object' }))).toEqual([])
+    // properties 被写成数组等非法形态时按空处理
+    expect(commandFields(command({ type: 'object', properties: ['nope'] as unknown as Record<string, unknown> }))).toEqual([])
+  })
+})
+
+describe('initialArguments', () => {
+  it('布尔字段显式初始化为 false，保证 UI 显示与提交值一致', () => {
+    // 回归：之前布尔下拉框显示「否」，但参数对象里没有这个键，
+    // 用户没手动切换过就会漏发这个参数。
+    const args = initialArguments(schema)
+
+    expect(args.recursive).toBe(false)
+    expect('recursive' in args).toBe(true)
+  })
+
+  it('有 default 的字段用 default，没有的不塞键', () => {
+    const args = initialArguments(schema)
+
+    expect(args.count).toBe(3)
+    expect('path' in args).toBe(false)
+    expect('mode' in args).toBe(false)
+  })
+
+  it('布尔字段的 default 优先于 false', () => {
+    const args = initialArguments(
+      command({ type: 'object', properties: { flag: { type: 'boolean', default: true } } }),
+    )
+
+    expect(args.flag).toBe(true)
+  })
+})
+
+describe('coerceArgument', () => {
+  const field = (type: string) => ({ key: 'k', title: 'k', type, required: false })
+
+  it('布尔只认字符串 "true"', () => {
+    expect(coerceArgument(field('boolean'), 'true')).toBe(true)
+    expect(coerceArgument(field('boolean'), 'false')).toBe(false)
+  })
+
+  it('数字字段转成 number，空串与非法输入转成 undefined', () => {
+    expect(coerceArgument(field('integer'), '42')).toBe(42)
+    expect(coerceArgument(field('number'), '1.5')).toBe(1.5)
+    expect(coerceArgument(field('number'), '')).toBeUndefined()
+    expect(coerceArgument(field('number'), 'abc')).toBeUndefined()
+  })
+
+  it('字符串原样保留（含空格）', () => {
+    expect(coerceArgument(field('string'), ' notes/a.md ')).toBe(' notes/a.md ')
+  })
+})
+
+describe('missingRequiredFields', () => {
+  it('列出未填的必填字段', () => {
+    const missing = missingRequiredFields(schema, initialArguments(schema))
+
+    expect(missing.map((f) => f.key)).toEqual(['path', 'mode'])
+  })
+
+  it('空白字符串算没填', () => {
+    const missing = missingRequiredFields(schema, { path: '   ', mode: 'fast' })
+
+    expect(missing.map((f) => f.key)).toEqual(['path'])
+  })
+
+  it('布尔 false 是合法值，不算缺失', () => {
+    const boolSchema = command({
+      type: 'object',
+      properties: { flag: { type: 'boolean' } },
+      required: ['flag'],
+    })
+
+    expect(missingRequiredFields(boolSchema, { flag: false })).toEqual([])
+  })
+
+  it('全部填好时返回空数组', () => {
+    expect(missingRequiredFields(schema, { path: 'a.md', mode: 'fast' })).toEqual([])
+  })
+})
+
+describe('cleanArguments', () => {
+  it('丢掉 undefined 的键，保留 false / 0 / 空串', () => {
+    const cleaned = cleanArguments({ a: undefined, b: false, c: 0, d: '', e: null })
+
+    expect(cleaned).toEqual({ b: false, c: 0, d: '', e: null })
+    expect('a' in cleaned).toBe(false)
+  })
+})
+
+describe('applyCommandEffect', () => {
+  function handlers() {
+    return { navigate: vi.fn(), refresh: vi.fn(), notify: vi.fn() }
+  }
+
+  it('navigate 真的触发跳转，而不是只提示一句话', async () => {
+    // 回归：之前只把 effect 拼成描述文本显示，命令等于没生效。
+    const h = handlers()
+    await applyCommandEffect({ type: 'navigate', payload: { route: 'workspace' } }, h)
+
+    expect(h.navigate).toHaveBeenCalledWith('/workspace')
+    expect(h.notify).not.toHaveBeenCalled()
+  })
+
+  it('每个白名单路由都能解析出路径', async () => {
+    for (const route of Object.keys(EFFECT_ROUTES)) {
+      const h = handlers()
+      await applyCommandEffect(
+        { type: 'navigate', payload: { route } } as PluginCommandEffect,
+        h,
+      )
+      expect(h.navigate).toHaveBeenCalledWith(EFFECT_ROUTES[route])
+    }
+  })
+
+  it('未知路由只提示不跳转，避免 router.push(undefined)', async () => {
+    const h = handlers()
+    await applyCommandEffect(
+      { type: 'navigate', payload: { route: 'nope' } } as unknown as PluginCommandEffect,
+      h,
+    )
+
+    expect(h.navigate).not.toHaveBeenCalled()
+    expect(h.notify.mock.calls[0][0]).toContain('nope')
+  })
+
+  it('refresh 真的触发对应 scope 的刷新', async () => {
+    const h = handlers()
+    await applyCommandEffect({ type: 'refresh', payload: { scope: 'workspace' } }, h)
+
+    expect(h.refresh).toHaveBeenCalledWith('workspace')
+  })
+
+  it('等待异步 refresh 完成后才返回', async () => {
+    const h = handlers()
+    let done = false
+    h.refresh.mockImplementation(async () => {
+      await Promise.resolve()
+      done = true
+    })
+
+    await applyCommandEffect({ type: 'refresh', payload: { scope: 'commands' } }, h)
+
+    expect(done).toBe(true)
+  })
+
+  it('notification 原样透出插件消息', async () => {
+    const h = handlers()
+    await applyCommandEffect(
+      { type: 'notification', payload: { level: 'info', message: '索引已重建' } },
+      h,
+    )
+
+    expect(h.notify).toHaveBeenCalledWith('索引已重建')
+  })
+
+  it('job 提示任务 id', async () => {
+    const h = handlers()
+    await applyCommandEffect({ type: 'job', payload: { job_id: 'job_7' } }, h)
+
+    expect(h.notify.mock.calls[0][0]).toContain('job_7')
+  })
+
+  it('none 或未知 type 按「已完成」处理，不猜测语义', async () => {
+    const h = handlers()
+    await applyCommandEffect({ type: 'none', payload: {} }, h)
+
+    expect(h.notify).toHaveBeenCalledWith('命令执行完成。')
+    expect(h.navigate).not.toHaveBeenCalled()
+    expect(h.refresh).not.toHaveBeenCalled()
+  })
+})

frontend/src/services/pluginCommandForm.ts

@@ -0,0 +1,152 @@
+import type { PluginCommand, PluginCommandEffect } from '@/contracts'
+
+/** 命令参数的 JSON Schema 字段定义（后端用 Draft 2020-12 校验）。 */
+export interface CommandField {
+  key: string
+  title: string
+  type: string
+  required: boolean
+  enum?: string[]
+  default?: unknown
+  description?: string
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {}
+}
+
+/**
+ * 把命令的 parameters（object schema）摊平成表单字段。
+ *
+ * 后端只接受 type=object 的 schema（contributions.py 里显式拒绝其他形态），
+ * 所以这里只处理 properties + required 两个键，嵌套对象按文本输入兜底。
+ */
+export function commandFields(command: PluginCommand): CommandField[] {
+  const schema = asRecord(command.parameters)
+  const properties = asRecord(schema.properties)
+  const requiredKeys = Array.isArray(schema.required) ? schema.required.map(String) : []
+
+  return Object.entries(properties).map(([key, rawDefinition]) => {
+    const definition = asRecord(rawDefinition)
+    return {
+      key,
+      title: typeof definition.title === 'string' && definition.title ? definition.title : key,
+      type: typeof definition.type === 'string' ? definition.type : 'string',
+      required: requiredKeys.includes(key),
+      enum: Array.isArray(definition.enum) ? definition.enum.map(String) : undefined,
+      default: definition.default,
+      description: typeof definition.description === 'string' ? definition.description : undefined,
+    }
+  })
+}
+
+/**
+ * 表单初始值。
+ *
+ * 布尔字段必须显式给 false —— 下拉框默认显示「否」，如果参数对象里
+ * 没有这个键，用户看到的和实际提交的就不一致。
+ */
+export function initialArguments(command: PluginCommand): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const field of commandFields(command)) {
+    if (field.default !== undefined) result[field.key] = field.default
+    else if (field.type === 'boolean') result[field.key] = false
+  }
+  return result
+}
+
+/** 按字段类型把输入框的字符串转成 schema 期望的类型。 */
+export function coerceArgument(field: CommandField, raw: string): unknown {
+  if (field.type === 'boolean') return raw === 'true'
+  if (field.type === 'number' || field.type === 'integer') {
+    if (raw.trim() === '') return undefined
+    const parsed = Number(raw)
+    return Number.isNaN(parsed) ? undefined : parsed
+  }
+  return raw
+}
+
+function isBlank(value: unknown): boolean {
+  if (value === undefined || value === null) return true
+  return typeof value === 'string' && value.trim() === ''
+}
+
+/**
+ * 找出还没填的必填字段。
+ *
+ * 后端会用 JSON Schema 再校验一次，这里做前置检查只为了别让用户
+ * 提交一次才知道少填了什么。布尔的 false 是合法值，不算缺失。
+ */
+export function missingRequiredFields(
+  command: PluginCommand,
+  args: Record<string, unknown>,
+): CommandField[] {
+  return commandFields(command).filter((field) => field.required && isBlank(args[field.key]))
+}
+
+/** undefined 的键不该出现在请求体里。 */
+export function cleanArguments(args: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(args)) {
+    if (value !== undefined) result[key] = value
+  }
+  return result
+}
+
+/** navigate effect 的路由白名单，与 router/index.ts 的路径一一对应。 */
+export const EFFECT_ROUTES: Record<string, string> = {
+  'vault-entry': '/',
+  workspace: '/workspace',
+  search: '/search',
+  chat: '/chat',
+  agent: '/agent/runs',
+  tasks: '/tasks',
+  skills: '/extensions/skills',
+  plugins: '/extensions/plugins',
+  themes: '/themes',
+  settings: '/settings',
+}
+
+export interface EffectHandlers {
+  navigate: (path: string) => Promise<unknown> | unknown
+  refresh: (scope: 'workspace' | 'commands' | 'settings' | 'plugins') => Promise<unknown> | unknown
+  notify: (message: string) => void
+}
+
+/**
+ * 执行命令返回的 effect。
+ *
+ * navigate / refresh 必须真的发生 —— 之前这里只是把 effect 拼成一句话
+ * 显示给用户，命令等于没生效。未知 type 一律按「已完成」处理，
+ * 不猜测语义。
+ */
+export async function applyCommandEffect(
+  effect: PluginCommandEffect,
+  handlers: EffectHandlers,
+): Promise<void> {
+  switch (effect.type) {
+    case 'notification':
+      handlers.notify(effect.payload.message)
+      return
+    case 'navigate': {
+      const path = EFFECT_ROUTES[effect.payload.route]
+      if (!path) {
+        handlers.notify(`命令请求跳转到未知路由「${effect.payload.route}」，已忽略。`)
+        return
+      }
+      await handlers.navigate(path)
+      return
+    }
+    case 'refresh':
+      await handlers.refresh(effect.payload.scope)
+      handlers.notify('相关数据已刷新。')
+      return
+    case 'job':
+      handlers.notify(`已创建后台任务：${effect.payload.job_id}`)
+      return
+    default:
+      handlers.notify('命令执行完成。')
+  }
+}

frontend/src/services/themePackageService.ts

@@ -66,18 +66,6 @@ function validateCssSafety(css: string): string[] {
   return warnings
 }
 
-function buildCssVarsFromManifest(manifest: ThemeManifest, rawValues: Record<string, string>): string {
-  const lines: string[] = []
-  lines.push(`[data-theme="${manifest.theme_id}"] {`)
-  for (const [key, value] of Object.entries(rawValues)) {
-    if (key.startsWith('--')) {
-      lines.push(`  ${key}: ${value};`)
-    }
-  }
-  lines.push('}')
-  return lines.join('\n')
-}
-
 function applyThemeCss(themeId: string, css: string) {
   let styleEl = document.getElementById(`theme-style-${themeId}`) as HTMLStyleElement | null
   if (!styleEl) {
@@ -116,27 +104,61 @@ function inspectYamlContent(yamlText: string): ThemeManifest {
   return manifest
 }
 
+/**
+ * 主题包是单文件文本格式：YAML 清单 + 一行 `---` + 主题 CSS。
+ *
+ *   theme_id: my-theme
+ *   name: My Theme
+ *   ...
+ *   ---
+ *   [data-theme="my-theme"] { --color-... }
+ *
+ * 浏览器端没有解压能力，所以不支持 ZIP —— 与其把二进制当文本解析出
+ * 一堆乱码再报「清单无效」，不如直接告诉用户格式不支持。
+ */
+export function parseThemePackage(packageData: string): { manifestText: string; css: string } {
+  if (looksLikeZip(packageData)) {
+    throw new Error(
+      'THEME_PACKAGE_UNSUPPORTED_FORMAT: 暂不支持 ZIP 主题包，请提供「YAML 清单 + --- + CSS」的单文件主题。',
+    )
+  }
+
+  const lines = packageData.split(/\r?\n/)
+  const separatorIndex = lines.findIndex((line) => line.trim() === '---')
+  if (separatorIndex < 0) {
+    throw new Error(
+      'THEME_PACKAGE_INVALID: 主题包缺少 `---` 分隔行，无法区分清单与 CSS。',
+    )
+  }
+
+  const manifestText = lines.slice(0, separatorIndex).join('\n')
+  const css = lines.slice(separatorIndex + 1).join('\n').trim()
+  if (!css) {
+    throw new Error('THEME_CSS_INVALID: 主题包内没有 CSS 内容。')
+  }
+  return { manifestText, css }
+}
+
+/** ZIP 的魔数是 PK\x03\x04；base64 形式（readAsDataURL）开头是 UEsDB。 */
+function looksLikeZip(data: string): boolean {
+  if (data.startsWith('PK')) return true
+  return /^data:.*;base64,UEsDB/.test(data) || data.startsWith('UEsDB')
+}
+
 export async function selectThemePackage(): Promise<string | null> {
   return new Promise((resolve) => {
     const input = document.createElement('input')
     input.type = 'file'
-    input.accept = '.zip,.yaml,.yml,.css'
+    // 只接受能在浏览器里解析的单文件主题；ZIP 需要 Host 端解压，暂不支持。
+    input.accept = '.yaml,.yml,.theme'
     input.multiple = false
     input.onchange = () => {
       const file = input.files?.[0]
       if (!file) { resolve(null); return }
       const reader = new FileReader()
-      reader.onload = () => {
-        resolve(reader.result as string)
-      }
+      reader.onload = () => resolve(reader.result as string)
       reader.onerror = () => resolve(null)
-      if (file.name.endsWith('.yaml') || file.name.endsWith('.yml')) {
-        reader.readAsText(file)
-      } else if (file.name.endsWith('.css')) {
-        reader.readAsText(file)
-      } else {
-        reader.readAsDataURL(file)
-      }
+      reader.readAsText(file)
     }
     input.oncancel = () => resolve(null)
     input.click()
@@ -146,10 +168,13 @@ export async function selectThemePackage(): Promise<string | null> {
 export async function inspectThemePackage(packageData: string): Promise<ThemePackageInspection> {
   const package_id = `theme_pkg_${Date.now()}`
   try {
-    const manifest = inspectYamlContent(packageData)
-    const warnings: string[] = []
-    if (manifest.css_entry && manifest.css_entry.includes('theme.css')) {
-      // 示意：Web Mock 假设 CSS 入口存在，真实 Host 会检查包内文件
+    const { manifestText, css } = parseThemePackage(packageData)
+    const manifest = inspectYamlContent(manifestText)
+    // CSS 的安全校验放在这里，不合规的包在「预览」阶段就该被拒，
+    // 而不是等到用户点安装。
+    const warnings = validateCssSafety(css)
+    if (!css.includes(`[data-theme="${manifest.theme_id}"]`)) {
+      warnings.push(`CSS 未包含 [data-theme="${manifest.theme_id}"] 选择器，主题可能不会生效。`)
     }
     return {
       package_id,
@@ -157,6 +182,7 @@ export async function inspectThemePackage(packageData: string): Promise<ThemePac
       preview_url: '',
       warnings,
       compatible: true,
+      css,
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : '未知错误'
@@ -168,6 +194,7 @@ export async function inspectThemePackage(packageData: string): Promise<ThemePac
       warnings: [message],
       compatible: false,
       error_code,
+      css: '',
     }
   }
 }
@@ -176,6 +203,8 @@ export async function installTheme(
   manifest: ThemeManifest,
   cssContent: string,
 ): Promise<InstalledTheme> {
+  // validateCssSafety 会对 @import / expression() / javascript: 抛错，
+  // 必须在 applyThemeCss 之前调用 —— 未校验的 CSS 一律不许进入页面。
   const warnings = validateCssSafety(cssContent)
   if (warnings.length > 0) {
     console.warn('[theme] CSS validation warnings:', warnings)

frontend/src/services/traceService.spec.ts

@@ -12,54 +12,129 @@ function event(
   return { event: type, sequence: ++sequence, run_id: 'run-1', data, timestamp }
 }
 
+/**
+ * 后端真实的事件顺序（backend/app/agent/runtime.py）：
+ *   ModelCallStarted → ModelCallCompleted → Usage → ToolCall → ToolResult
+ * 工具在模型调用「完成之后」才执行，而且多个工具并发跑（asyncio.gather +
+ * Semaphore），事件会交错到达。所以建树只能靠 id 关联，不能靠相邻顺序。
+ */
 describe('buildTraceNodes', () => {
-  it('把模型调用期间的事件挂到该模型调用之下', () => {
+  it('工具事件按 parent_model_call_id 归属，即使出现在 ModelCallCompleted 之后', () => {
     const nodes = buildTraceNodes([
       event('RunStarted'),
-      event('ModelCallStarted', { model: 'mock-1' }),
-      event('ToolCall', { name: 'read_note' }),
-      event('ToolResult', { success: true }),
-      event('ModelCallCompleted', { duration_ms: 1200 }),
+      event('ModelCallStarted', { model_call_id: 'mc-1', model: 'mock-1', provider_id: 'mock' }),
+      event('ModelCallCompleted', { model_call_id: 'mc-1', duration_ms: 1200, finish_reason: 'tool_calls' }),
+      event('Usage', { token_usage: 320 }),
+      event('ToolCall', { tool_call_id: 'tc-1', name: 'read_note', parent_model_call_id: 'mc-1' }),
+      event('ToolResult', { tool_call_id: 'tc-1', name: 'read_note', success: true, duration_ms: 40, parent_model_call_id: 'mc-1' }),
       event('RunCompleted'),
     ])
 
-    // 顶层只剩：运行开始、模型调用、运行完成
-    expect(nodes).toHaveLength(3)
+    // 顶层：运行开始、模型调用、Usage、运行完成。工具挂在模型调用下面。
+    expect(nodes.map((n) => n.type)).toEqual(['run', 'model_call', 'usage', 'complete'])
+
     const modelCall = nodes[1]
-    expect(modelCall.type).toBe('model_call')
     expect(modelCall.status).toBe('completed')
     expect(modelCall.duration_ms).toBe(1200)
-    expect(modelCall.children.map((c) => c.type)).toEqual(['tool_call', 'tool_result'])
+    expect(modelCall.children.map((c) => c.type)).toEqual(['tool_call'])
   })
 
-  it('模型调用失败时标记为 error', () => {
+  it('ToolResult 回填对应 ToolCall 的状态，结束后不再显示 running', () => {
     const nodes = buildTraceNodes([
-      event('ModelCallStarted', { model: 'mock-1' }),
-      event('ModelCallFailed', { error_code: 'PROVIDER_TIMEOUT' }),
+      event('ModelCallStarted', { model_call_id: 'mc-2' }),
+      event('ModelCallCompleted', { model_call_id: 'mc-2' }),
+      event('ToolCall', { tool_call_id: 'tc-2', name: 'read_note', parent_model_call_id: 'mc-2' }),
+      event('ToolResult', { tool_call_id: 'tc-2', name: 'read_note', success: true, duration_ms: 55, parent_model_call_id: 'mc-2' }),
+    ])
+
+    const toolCall = nodes[0].children[0]
+    expect(toolCall.type).toBe('tool_call')
+    expect(toolCall.status).toBe('completed')
+    expect(toolCall.duration_ms).toBe(55)
+    // 结果数据合并进调用节点，展开详情时能看到 output。
+    expect((toolCall.data.result as Record<string, unknown>).success).toBe(true)
+  })
+
+  it('工具失败时把 ToolCall 标记为 error 并带上 error_code', () => {
+    const nodes = buildTraceNodes([
+      event('ModelCallStarted', { model_call_id: 'mc-3' }),
+      event('ToolCall', { tool_call_id: 'tc-3', name: 'write_note', parent_model_call_id: 'mc-3' }),
+      event('ToolResult', { tool_call_id: 'tc-3', name: 'write_note', success: false, error_code: 'TOOL_DENIED', parent_model_call_id: 'mc-3' }),
+    ])
+
+    const toolCall = nodes[0].children[0]
+    expect(toolCall.status).toBe('error')
+    expect(toolCall.subtitle).toContain('TOOL_DENIED')
+  })
+
+  it('并发工具交错到达时各自归属到正确的模型调用', () => {
+    const nodes = buildTraceNodes([
+      event('ModelCallStarted', { model_call_id: 'mc-a' }),
+      event('ModelCallCompleted', { model_call_id: 'mc-a' }),
+      event('ToolCall', { tool_call_id: 'a1', name: 'toolA1', parent_model_call_id: 'mc-a' }),
+      event('ToolCall', { tool_call_id: 'a2', name: 'toolA2', parent_model_call_id: 'mc-a' }),
+      event('ModelCallStarted', { model_call_id: 'mc-b' }),
+      event('ModelCallCompleted', { model_call_id: 'mc-b' }),
+      event('ToolCall', { tool_call_id: 'b1', name: 'toolB1', parent_model_call_id: 'mc-b' }),
+      // 第一个模型调用的工具结果比第二轮的工具调用还晚到
+      event('ToolResult', { tool_call_id: 'a2', name: 'toolA2', success: true, parent_model_call_id: 'mc-a' }),
+      event('ToolResult', { tool_call_id: 'a1', name: 'toolA1', success: true, parent_model_call_id: 'mc-a' }),
+      event('ToolResult', { tool_call_id: 'b1', name: 'toolB1', success: true, parent_model_call_id: 'mc-b' }),
+    ])
+
+    const [callA, callB] = nodes.filter((n) => n.type === 'model_call')
+    expect(callA.children.map((c) => c.title)).toEqual(['工具调用：toolA1', '工具调用：toolA2'])
+    expect(callB.children.map((c) => c.title)).toEqual(['工具调用：toolB1'])
+    expect(callA.children.every((c) => c.status === 'completed')).toBe(true)
+  })
+
+  it('模型调用失败时标记为 error 并附带 error_code', () => {
+    const nodes = buildTraceNodes([
+      event('ModelCallStarted', { model_call_id: 'mc-4', model: 'mock-1' }),
+      event('ModelCallFailed', { model_call_id: 'mc-4', error_code: 'PROVIDER_TIMEOUT', duration_ms: 900 }),
     ])
 
     expect(nodes).toHaveLength(1)
     expect(nodes[0].status).toBe('error')
+    expect(nodes[0].duration_ms).toBe(900)
+    expect(nodes[0].subtitle).toContain('PROVIDER_TIMEOUT')
+  })
+
+  it('PermissionRequired 不带父 id，留在顶层', () => {
+    const nodes = buildTraceNodes([
+      event('ModelCallStarted', { model_call_id: 'mc-5' }),
+      event('PermissionRequired', { request_id: 'r1', permission: 'notes.write' }),
+    ])
+
+    expect(nodes.map((n) => n.type)).toEqual(['model_call', 'permission'])
+    expect(nodes[1].status).toBe('pending')
   })
 
   it('运行级事件始终留在顶层，不会被模型调用吞掉', () => {
     const nodes = buildTraceNodes([
-      event('ModelCallStarted', { model: 'mock-1' }),
+      event('ModelCallStarted', { model_call_id: 'mc-6' }),
       event('RunFailed', { error_code: 'RUN_TIMEOUT' }),
     ])
 
     expect(nodes.map((n) => n.type)).toEqual(['model_call', 'error'])
   })
 
-  it('模型调用之外的事件保持在顶层', () => {
+  it('SSE 断点恢复只拿到后半段时，孤立事件退回顶层而不是被丢弃', () => {
+    // 没有 ModelCallStarted，也没有对应的 ToolCall
     const nodes = buildTraceNodes([
-      event('RunStarted'),
-      event('ToolCall', { name: 'search' }),
-      event('RunCompleted'),
+      event('ModelCallCompleted', { model_call_id: 'mc-lost', duration_ms: 10 }),
+      event('ToolResult', { tool_call_id: 'tc-lost', name: 'read_note', success: false, error_code: 'TOOL_FAILED' }),
     ])
 
-    expect(nodes).toHaveLength(3)
-    expect(nodes.every((n) => n.children.length === 0)).toBe(true)
+    expect(nodes).toHaveLength(2)
+    expect(nodes[0].type).toBe('model_call')
+    // 落单的失败结果不能显示成 completed
+    expect(nodes[1].status).toBe('error')
+  })
+
+  it('Usage 副标题读后端真实字段 token_usage', () => {
+    const nodes = buildTraceNodes([event('Usage', { token_usage: 1234 })])
+    expect(nodes[0].subtitle).toBe('1234 tokens')
   })
 
   it('空事件列表返回空树', () => {

frontend/src/services/traceService.ts

@@ -1,74 +1,121 @@
 import type { AgentEvent, TraceNode, TraceNodeType } from '@/contracts'
 
+/**
+ * 把扁平事件流折叠成调用树。
+ *
+ * 归属关系一律走 id，不依赖事件相邻顺序 —— 后端的真实顺序是
+ * ModelCallStarted → ModelCallCompleted → Usage → ToolCall/ToolResult，
+ * 工具在模型调用「完成」之后才执行，并且多个工具是并发跑的
+ * （runtime.py 里 asyncio.gather + Semaphore），事件会交错到达。
+ * 因此工具事件用 data.parent_model_call_id 找父节点，
+ * ToolResult 用 data.tool_call_id 回填对应 ToolCall 的状态。
+ */
 export function buildTraceNodes(events: AgentEvent[]): TraceNode[] {
-  const nodes: TraceNode[] = []
-  let currentModelCallId: string | null = null
+  const roots: TraceNode[] = []
+  /** model_call_id -> 模型调用节点 */
+  const modelCalls = new Map<string, TraceNode>()
+  /** tool_call_id -> 工具调用节点，供 ToolResult 回填状态 */
+  const toolCalls = new Map<string, TraceNode>()
 
   for (const event of events) {
-    const type = mapEventType(event.event)
-    const id = `seq-${event.sequence}`
-    const title = getNodeTitle(event)
-    const subtitle = getNodeSubtitle(event)
-    const status = getNodeStatus(event)
-
     const node: TraceNode = {
-      id,
+      id: `seq-${event.sequence}`,
       sequence: event.sequence,
-      type,
-      title,
-      subtitle,
-      status,
+      type: mapEventType(event.event),
+      title: getNodeTitle(event),
+      subtitle: getNodeSubtitle(event),
+      status: getNodeStatus(event),
       data: event.data,
       timestamp: event.timestamp,
       children: [],
     }
+    const modelCallId = asId(event.data.model_call_id)
+    const parentModelCallId = asId(event.data.parent_model_call_id)
+    const toolCallId = asId(event.data.tool_call_id)
 
-    if (event.event === 'ModelCallStarted') {
-      currentModelCallId = id
-      node.children = []
-      nodes.push(node)
-      continue
-    }
-
-    if (event.event === 'ModelCallCompleted' || event.event === 'ModelCallFailed') {
-      if (currentModelCallId) {
-        const modelCall = findNodeById(nodes, currentModelCallId)
-        if (modelCall) {
-          modelCall.status = event.event === 'ModelCallCompleted' ? 'completed' : 'error'
-          if (event.data.duration_ms != null) {
-            modelCall.duration_ms = event.data.duration_ms as number
-          }
-          if (event.data.finish_reason) {
-            modelCall.subtitle = `${modelCall.subtitle ?? ''} · ${String(event.data.finish_reason)}`
-          }
-        }
-        currentModelCallId = null
+    switch (event.event) {
+      case 'ModelCallStarted': {
+        if (modelCallId) modelCalls.set(modelCallId, node)
+        roots.push(node)
+        continue
       }
-      continue
-    }
 
-    if (currentModelCallId && type !== 'run' && type !== 'complete' && type !== 'error') {
-      const parent = findNodeById(nodes, currentModelCallId)
-      if (parent) {
-        node.parent_id = currentModelCallId
-        parent.children.push(node)
+      // 完成/失败事件不单独成节点，只更新对应模型调用的状态。
+      case 'ModelCallCompleted':
+      case 'ModelCallFailed': {
+        const target = modelCallId ? modelCalls.get(modelCallId) : undefined
+        if (!target) {
+          // 找不到配对的 Started（例如 SSE 断点恢复后只拿到后半段），保留为顶层节点。
+          roots.push(node)
+          continue
+        }
+        target.status = event.event === 'ModelCallCompleted' ? 'completed' : 'error'
+        const duration = asNumber(event.data.duration_ms)
+        if (duration != null) target.duration_ms = duration
+        const extra = event.event === 'ModelCallCompleted'
+          ? asText(event.data.finish_reason)
+          : asText(event.data.error_code)
+        if (extra) target.subtitle = target.subtitle ? `${target.subtitle} · ${extra}` : extra
+        continue
+      }
+
+      // ToolResult 只回填对应 ToolCall，避免工具结束后仍显示 running。
+      case 'ToolResult': {
+        const target = toolCallId ? toolCalls.get(toolCallId) : undefined
+        if (!target) {
+          attach(node, parentModelCallId, modelCalls, roots)
+          continue
+        }
+        target.status = event.data.success === false ? 'error' : 'completed'
+        const duration = asNumber(event.data.duration_ms)
+        if (duration != null) target.duration_ms = duration
+        const detail = event.data.success === false
+          ? asText(event.data.error_code) ?? '失败'
+          : undefined
+        if (detail) target.subtitle = target.subtitle ? `${target.subtitle} · ${detail}` : detail
+        // 结果数据合并到调用节点，展开详情时才能看到 output。
+        target.data = { ...target.data, result: event.data }
+        continue
+      }
+
+      case 'ToolCall': {
+        if (toolCallId) toolCalls.set(toolCallId, node)
+        attach(node, parentModelCallId, modelCalls, roots)
+        continue
+      }
+
+      default: {
+        attach(node, parentModelCallId, modelCalls, roots)
         continue
       }
     }
-
-    nodes.push(node)
   }
 
-  return nodes
+  return roots
 }
 
-function findNodeById(nodes: TraceNode[], id: string): TraceNode | null {
-  for (const node of nodes) {
-    if (node.id === id) return node
-    const found = findNodeById(node.children, id)
-    if (found) return found
+/** 有已知父模型调用就挂进去，否则留在顶层。 */
+function attach(
+  node: TraceNode,
+  parentModelCallId: string | null,
+  modelCalls: Map<string, TraceNode>,
+  roots: TraceNode[],
+) {
+  const parent = parentModelCallId ? modelCalls.get(parentModelCallId) : undefined
+  if (parent) {
+    node.parent_id = parent.id
+    parent.children.push(node)
+    return
   }
-  return null
+  roots.push(node)
+}
+
+function asId(value: unknown): string | null {
+  return typeof value === 'string' && value !== '' ? value : null
+}
+
+function asText(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined
 }
 
 function mapEventType(eventType: AgentEvent['event']): TraceNodeType {
@@ -132,12 +179,12 @@ function getNodeSubtitle(event: AgentEvent): string | undefined {
     case 'Citation':
       return data.heading_path ? String(data.heading_path) : undefined
     case 'Usage': {
-      // total_tokens 优先；缺失时回退到 input+output 之和。
-      const total = asNumber(data.total_tokens)
-      if (total != null) return `${total} tokens`
+      // 后端发的是累计 token_usage（runtime.py），其余字段仅作兼容回退。
+      const usage = asNumber(data.token_usage) ?? asNumber(data.total_tokens)
+      if (usage != null) return `${usage} tokens`
       const input = asNumber(data.input_tokens)
       const output = asNumber(data.output_tokens)
-      if (input == null && output == null) return '- tokens'
+      if (input == null && output == null) return undefined
       return `${(input ?? 0) + (output ?? 0)} tokens`
     }
     case 'PermissionRequired':
@@ -154,14 +201,19 @@ function getNodeStatus(event: AgentEvent): TraceNode['status'] {
     case 'RunFailed':
     case 'ModelCallFailed':
       return 'error'
+    case 'ToolResult':
+      // 只在 ToolResult 没配上 ToolCall 时（SSE 断点恢复）才成为独立节点，
+      // 那时也要按 success 显示，不能一律算成功。
+      return event.data.success === false ? 'error' : 'completed'
     case 'RunCompleted':
     case 'RunCancelled':
     case 'ModelCallCompleted':
-    case 'ToolResult':
     case 'Usage':
     case 'PermissionResolved':
       return 'completed'
     case 'ToolCall':
+      // 后端的 ToolCall 事件不带 status，起始一律 running，
+      // 由后到的 ToolResult 回填最终状态。
       if (event.data.status === 'completed') return 'completed'
       if (event.data.status === 'error') return 'error'
       return 'running'