feat(frontend): 第二阶段前端 Agent Trace / 主题包 / Mermaid 能力 #18

2026-09-04T19:51:38+08:00

saint commented

2026-09-04 19:51:38 +08:00

改动内容

Agent Trace 可视化（P0）：新增 traceService，把扁平事件流折叠成树 —— ModelCallStarted 与其 ModelCallCompleted/ModelCallFailed 之间的工具、文本、思考事件挂为子节点，运行级事件（RunStarted/RunCompleted/RunFailed）始终留在顶层。新增 TraceTimeline 组件，支持时间线／树两种视图、耗时与 token 统计、逐事件详情展开、引用点击跳转。
主题包导入（P0）：新增 themePackageService（Web Mock Adapter 实现 Theme Package Host Contract）。ThemesView 增加「已安装／社区主题」两个标签页，含导入、检视结果确认、预览（临时应用后自动还原）、卸载流程。
Mermaid 渲染（P0）：新增 mermaidService（securityLevel: 'strict'）与 MermaidBlock 组件（缩放、错误横幅、防陈旧异步渲染的 render token）。markdown 渲染管线识别 mermaid 代码块并交由服务渲染，DOMPurify 白名单放通 SVG 标签与属性。
Mermaid 主题适配（P1）：MarkdownContent 监听主题变化并重渲染 —— SVG 配色在渲染时烘焙进产物，无法靠 CSS 变量事后调整。
Plugin 命令 / 设置 UI（P1）：PluginsView 增加「概览／命令／设置」标签页（按 Contribution 类型显隐）；新增 PluginSettingsPanel，按 Settings Schema 动态生成表单（string / number / boolean / select）。
命令面板补充「主题管理」「任务列表」两条内置命令。

影响模块

前端 services/：新增 themePackageService、mermaidService、traceService
前端 features/：agent/TraceTimeline.vue（新增）、agent/AgentView.vue、themes/ThemesView.vue、plugins/PluginsView.vue、plugins/PluginSettingsPanel.vue（新增）
前端 components/common/：MermaidBlock.vue（新增）、MarkdownContent.vue、CommandPalette.vue
前端 stores/theme.ts：支持自定义主题与内置主题共存
前端 utils/markdown.ts：渲染管线接入 mermaid
contracts/index.ts：补充 Theme / Mermaid / Trace 相关类型（并清理与队友重复的声明）
新增依赖 mermaid@11.17.2

验证方式

前端 build 通过（pnpm build）
前端测试通过（pnpm test：26 文件 / 113 测试，新增 traceService.spec.ts、themePackageService.spec.ts 共 22 项）
类型检查通过（vue-tsc -b）
后端 pytest 通过（本 PR 不含后端改动）
手动联调通过（Plugin 命令／设置需配合已合入的后端接口再走一轮）

接口或数据变更

无后端接口变更。 本 PR 只消费已在 main 落地的 pluginService 接口。
前端本地存储新增键：installed-themes、installed-themes-css-{theme_id}、active-custom-theme（仅存主题元数据与 CSS，不含任何凭据）。
contracts/index.ts 移除了我上一版重复添加的 PluginHostStatus / PluginCommand / PluginSettingField / PluginSettingsSchema 声明，以队友已合入的版本为准，对外类型不变。

风险与恢复

与 main 上队友成果的整合（rebase 时已处理，请重点看这几处）：
- 命令面板保留队友基于真实后端的实现（when 条件求值、效果白名单、带必填参数的命令跳详情页），我只叠加了两条内置命令。
- 删除了我先前的 pluginContributionService（mock 版），统一改用队友已落地的 pluginService 真实接口，避免两套 service 并存。相应修正了表单以匹配真实契约（options 为 string[]、minimum/maximum 可空、无 placeholder 字段）。
- PluginsView 概览页保留了队友的 PluginMcpPanel，并补回被我改写时丢掉的插件空状态。
安全边界：主题 CSS 拒绝 @import、expression()、javascript:，css_entry 拒绝远程地址与 data:；未通过校验的 CSS 不会注入页面（已有测试覆盖）。Plugin secret 字段只写不读 —— 仅展示 configured 状态，不写入 store、不落 localStorage、不回显明文。
skipLibCheck: true：mermaid 11.17 把 type-fest 泄漏进了发布产物的 .d.ts，却只声明为自身 devDependency，vue-tsc -b 因此报 TS2307。这是 mermaid 的打包问题，skipLibCheck 也是 @vue/tsconfig 的默认值。若不接受此改动，替代方案是显式装一个 type-fest@^4 devDependency。
构建体积：mermaid 使得含 MarkdownContent 的 chunk 增至约 1.5 MB（gzip 约 315 KB），各图表类型已由 mermaid 自身按需分包。如需进一步瘦身，可把 mermaidService 里的 mermaid 改为动态 import，我可以另开一个 PR 处理。
回滚：本 PR 为单个 commit，git revert 即可；新增文件与既有模块耦合面小，主题／Trace／Mermaid 三块可独立回退。

关联 Issue

对应《第二阶段团队分工表》中吉海燕的 P0 全部三项与 P1 的 Mermaid 主题适配、Plugin 命令 UI、Plugin 设置 UI
Closes #

## 改动内容 - **Agent Trace 可视化（P0）**：新增 `traceService`，把扁平事件流折叠成树 —— `ModelCallStarted` 与其 `ModelCallCompleted`/`ModelCallFailed` 之间的工具、文本、思考事件挂为子节点，运行级事件（RunStarted/RunCompleted/RunFailed）始终留在顶层。新增 `TraceTimeline` 组件，支持时间线／树两种视图、耗时与 token 统计、逐事件详情展开、引用点击跳转。 - **主题包导入（P0）**：新增 `themePackageService`（Web Mock Adapter 实现 Theme Package Host Contract）。`ThemesView` 增加「已安装／社区主题」两个标签页，含导入、检视结果确认、预览（临时应用后自动还原）、卸载流程。 - **Mermaid 渲染（P0）**：新增 `mermaidService`（`securityLevel: 'strict'`）与 `MermaidBlock` 组件（缩放、错误横幅、防陈旧异步渲染的 render token）。markdown 渲染管线识别 mermaid 代码块并交由服务渲染，DOMPurify 白名单放通 SVG 标签与属性。 - **Mermaid 主题适配（P1）**：`MarkdownContent` 监听主题变化并重渲染 —— SVG 配色在渲染时烘焙进产物，无法靠 CSS 变量事后调整。 - **Plugin 命令 / 设置 UI（P1）**：`PluginsView` 增加「概览／命令／设置」标签页（按 Contribution 类型显隐）；新增 `PluginSettingsPanel`，按 Settings Schema 动态生成表单（string / number / boolean / select）。 - 命令面板补充「主题管理」「任务列表」两条内置命令。 ## 影响模块 - 前端 `services/`：新增 `themePackageService`、`mermaidService`、`traceService` - 前端 `features/`：`agent/TraceTimeline.vue`（新增）、`agent/AgentView.vue`、`themes/ThemesView.vue`、`plugins/PluginsView.vue`、`plugins/PluginSettingsPanel.vue`（新增） - 前端 `components/common/`：`MermaidBlock.vue`（新增）、`MarkdownContent.vue`、`CommandPalette.vue` - 前端 `stores/theme.ts`：支持自定义主题与内置主题共存 - 前端 `utils/markdown.ts`：渲染管线接入 mermaid - `contracts/index.ts`：补充 Theme / Mermaid / Trace 相关类型（并清理与队友重复的声明） - 新增依赖 `mermaid@11.17.2` ## 验证方式 - [x] 前端 build 通过（`pnpm build`） - [x] 前端测试通过（`pnpm test`：26 文件 / 113 测试，新增 `traceService.spec.ts`、`themePackageService.spec.ts` 共 22 项） - [x] 类型检查通过（`vue-tsc -b`） - [ ] 后端 pytest 通过（本 PR 不含后端改动） - [ ] 手动联调通过（Plugin 命令／设置需配合已合入的后端接口再走一轮） ## 接口或数据变更 - **无后端接口变更。** 本 PR 只消费已在 main 落地的 `pluginService` 接口。 - 前端本地存储新增键：`installed-themes`、`installed-themes-css-{theme_id}`、`active-custom-theme`（仅存主题元数据与 CSS，不含任何凭据）。 - `contracts/index.ts` 移除了我上一版重复添加的 `PluginHostStatus` / `PluginCommand` / `PluginSettingField` / `PluginSettingsSchema` 声明，**以队友已合入的版本为准**，对外类型不变。 ## 风险与恢复 - **与 main 上队友成果的整合**（rebase 时已处理，请重点看这几处）： - 命令面板保留队友基于真实后端的实现（`when` 条件求值、效果白名单、带必填参数的命令跳详情页），我只叠加了两条内置命令。 - 删除了我先前的 `pluginContributionService`（mock 版），统一改用队友已落地的 `pluginService` 真实接口，避免两套 service 并存。相应修正了表单以匹配真实契约（`options` 为 `string[]`、`minimum`/`maximum` 可空、无 `placeholder` 字段）。 - `PluginsView` 概览页保留了队友的 `PluginMcpPanel`，并补回被我改写时丢掉的插件空状态。 - **安全边界**：主题 CSS 拒绝 `@import`、`expression()`、`javascript:`，`css_entry` 拒绝远程地址与 `data:`；未通过校验的 CSS 不会注入页面（已有测试覆盖）。Plugin secret 字段只写不读 —— 仅展示 `configured` 状态，不写入 store、不落 localStorage、不回显明文。 - **`skipLibCheck: true`**：mermaid 11.17 把 `type-fest` 泄漏进了发布产物的 `.d.ts`，却只声明为自身 devDependency，`vue-tsc -b` 因此报 TS2307。这是 mermaid 的打包问题，`skipLibCheck` 也是 `@vue/tsconfig` 的默认值。若不接受此改动，替代方案是显式装一个 `type-fest@^4` devDependency。 - **构建体积**：mermaid 使得含 `MarkdownContent` 的 chunk 增至约 1.5 MB（gzip 约 315 KB），各图表类型已由 mermaid 自身按需分包。如需进一步瘦身，可把 `mermaidService` 里的 mermaid 改为动态 import，我可以另开一个 PR 处理。 - **回滚**：本 PR 为单个 commit，`git revert` 即可；新增文件与既有模块耦合面小，主题／Trace／Mermaid 三块可独立回退。 ## 关联 Issue - 对应《第二阶段团队分工表》中吉海燕的 P0 全部三项与 P1 的 Mermaid 主题适配、Plugin 命令 UI、Plugin 设置 UI - Closes #

saint added 1 commit 2026-09-04 19:51:38 +08:00

feat(frontend): 第二阶段前端 Agent Trace / 主题包 / Mermaid 能力 12869b5e95

实现第二阶段分工表中吉海燕负责的 P0/P1 前端能力。

- Agent Trace 可视化：新增 traceService 将扁平事件流折叠为树
  （ModelCallStarted 区间内的工具/文本事件挂为子节点，运行级事件保持顶层），
  TraceTimeline 支持时间线/树两种视图、耗时统计与引用跳转。
- 主题包：新增 themePackageService（Web Mock Adapter），
  校验 manifest 必填字段与 theme_id 格式，拒绝远程 css_entry；
  CSS 侧拒绝 @import / expression() / javascript:，
  未通过校验的 CSS 不会注入页面。内置主题走 data-theme=light|dark|sepia，
  自定义主题走 data-theme={theme_id} + 独立 style 节点。
  ThemesView 增加“已安装/社区主题”两个标签页与导入、预览、卸载流程。
- Mermaid：新增 mermaidService（securityLevel: strict）与 MermaidBlock，
  markdown 渲染管线识别 mermaid 代码块；MarkdownContent 随亮/暗主题重渲染
  （SVG 配色在渲染时烘焙，无法靠 CSS 变量事后调整）。
- 插件贡献 UI：PluginsView 增加“概览/命令/设置”标签页，
  PluginSettingsPanel 按 Schema 动态生成表单；
  secret 字段只写不读，仅展示 configured 状态，不进 store 也不回显。

与 main 上队友成果的整合（rebase 时处理）：
- 命令面板保留队友基于真实后端的实现（when 条件求值、效果白名单、
  参数命令跳详情页），仅叠加我新增的主题/任务两条内置命令。
- 删除我先前的 pluginContributionService（mock 版），
  统一改用队友已落地的 pluginService 真实接口；
  相应修正表单以匹配真实契约（options 为 string[]、min/max 可空、无 placeholder）。
- 移除 contracts 中与队友重复的 PluginHostStatus / PluginCommand /
  PluginSettingField / PluginSettingsSchema 声明，以队友版本为准。
- PluginsView 概览页保留队友的 PluginMcpPanel，并补回被我改写时丢掉的空状态。

顺带修复：
- 开启 skipLibCheck —— mermaid 11.17 把 type-fest 泄漏进了发布产物的
  .d.ts，但只声明为自身 devDependency，vue-tsc -b 会因此报错。

验证：pnpm test 26 文件 / 113 测试通过（新增 traceService、
themePackageService 两个测试文件共 22 项）；pnpm build 通过。

Kronecker commented

2026-09-04 20:23:58 +08:00

审阅结论：请求修改，暂不合并

审阅版本：12869b5。

本轮发现以下 6 项 P2 问题，需要修复并补充回归测试。

[P2] 主题导入未读取用户提供的 CSS

位置：frontend/src/features/themes/ThemesView.vue:45–49

确认安装时调用 generateThemeCss 生成演示配色，没有读取 manifest.css_entry 对应的文件。入口虽然接受 ZIP/CSS，后续却统一按 YAML 文本解析。

影响：YAML 可以显示安装成功，但实际安装的不是用户主题；ZIP/CSS 无法完成导入。

建议：实现真实包内容读取、校验和安装。尚未支持的格式应明确拒绝，演示入口不能作为已完成的主题导入交付。

[P2] 刷新页面后无法恢复自定义主题

位置：frontend/src/stores/theme.ts:99–105

initTheme 未等待 loadCustomThemes 完成就调用 applyTheme(saved)。此时只有内置主题，自定义主题查找失败；加载完成后也没有重新应用。

补充测试已复现：自定义主题加载成功，但 currentThemeId 仍为 light。

建议：先加载自定义主题，再恢复保存的选择，并为主题不存在的情况提供回退。

[P2] Trace 建树逻辑与真实后端事件顺序不一致

位置：frontend/src/services/traceService.ts:33–50

实现按 ModelCallStarted 与 ModelCallCompleted 之间的时间窗口归属工具事件。但真实后端先发送 ModelCallCompleted，再执行工具，并通过 parent_model_call_id 标明归属。

补充测试使用真实事件顺序后，工具节点全部落在顶层。

建议：使用 model_call_id、parent_model_call_id 和 tool_call_id 关联节点，而不是依赖事件相邻顺序；依据 ToolResult 更新调用状态，避免结束后仍显示 running。

[P2] 树形视图叶子节点无法展开详情

位置：frontend/src/features/agent/TraceTimeline.vue:200–214

点击事件仅允许有 children 的节点展开，但详情区域要求节点没有 children 且已展开，导致叶子详情永远无法显示。

组件测试已复现：点击工具结果叶子节点后没有详情区域。

建议：允许叶子切换详情，并区分父节点的子树展开与自身数据查看。

[P2] 引用点击未接入笔记定位流程

位置：frontend/src/features/agent/AgentView.vue:121

TraceTimeline 会发出 open-citation 事件，但 AgentView 没有监听，也未调用工作区打开笔记和定位 Block 的逻辑。

影响：引用显示为可点击，但点击后不会跳转。

建议：接入现有 Citation 定位流程，补充从 Trace 点击到对应笔记位置的集成测试。

[P2] 新命令页缺少参数输入和实际效果执行

位置：frontend/src/features/plugins/PluginsView.vue:62–79

新增命令页始终发送空 arguments/context，没有根据 parameters 提供必填参数输入；返回的 navigate、refresh 效果也只是显示说明文本，没有执行导航或刷新。

影响：带必填参数的命令无法执行，其他命令可能显示成功但未完成预期界面操作。

建议：复用现有 PluginMcpPanel 的参数表单、when 判断和效果处理流程，避免两个入口行为不一致。

验证情况

现有前端测试：26 个文件、113 项通过。
类型检查与生产构建通过，存在大体积 chunk 警告。
补充测试复现了主题恢复、真实事件建树、叶子详情三个问题。
其余问题已通过调用链核查确认。
与当前 main 无合并冲突。
尚未进行真实浏览器端到端联调。

请修复上述问题并补充回归测试后，再次提交审阅。

## 审阅结论：请求修改，暂不合并审阅版本：`12869b5`。本轮发现以下 6 项 P2 问题，需要修复并补充回归测试。 ### [P2] 主题导入未读取用户提供的 CSS 位置：`frontend/src/features/themes/ThemesView.vue:45–49` 确认安装时调用 generateThemeCss 生成演示配色，没有读取 manifest.css_entry 对应的文件。入口虽然接受 ZIP/CSS，后续却统一按 YAML 文本解析。影响：YAML 可以显示安装成功，但实际安装的不是用户主题；ZIP/CSS 无法完成导入。建议：实现真实包内容读取、校验和安装。尚未支持的格式应明确拒绝，演示入口不能作为已完成的主题导入交付。 ### [P2] 刷新页面后无法恢复自定义主题位置：`frontend/src/stores/theme.ts:99–105` initTheme 未等待 loadCustomThemes 完成就调用 applyTheme(saved)。此时只有内置主题，自定义主题查找失败；加载完成后也没有重新应用。补充测试已复现：自定义主题加载成功，但 currentThemeId 仍为 light。建议：先加载自定义主题，再恢复保存的选择，并为主题不存在的情况提供回退。 ### [P2] Trace 建树逻辑与真实后端事件顺序不一致位置：`frontend/src/services/traceService.ts:33–50` 实现按 ModelCallStarted 与 ModelCallCompleted 之间的时间窗口归属工具事件。但真实后端先发送 ModelCallCompleted，再执行工具，并通过 parent_model_call_id 标明归属。补充测试使用真实事件顺序后，工具节点全部落在顶层。建议：使用 model_call_id、parent_model_call_id 和 tool_call_id 关联节点，而不是依赖事件相邻顺序；依据 ToolResult 更新调用状态，避免结束后仍显示 running。 ### [P2] 树形视图叶子节点无法展开详情位置：`frontend/src/features/agent/TraceTimeline.vue:200–214` 点击事件仅允许有 children 的节点展开，但详情区域要求节点没有 children 且已展开，导致叶子详情永远无法显示。组件测试已复现：点击工具结果叶子节点后没有详情区域。建议：允许叶子切换详情，并区分父节点的子树展开与自身数据查看。 ### [P2] 引用点击未接入笔记定位流程位置：`frontend/src/features/agent/AgentView.vue:121` TraceTimeline 会发出 open-citation 事件，但 AgentView 没有监听，也未调用工作区打开笔记和定位 Block 的逻辑。影响：引用显示为可点击，但点击后不会跳转。建议：接入现有 Citation 定位流程，补充从 Trace 点击到对应笔记位置的集成测试。 ### [P2] 新命令页缺少参数输入和实际效果执行位置：`frontend/src/features/plugins/PluginsView.vue:62–79` 新增命令页始终发送空 arguments/context，没有根据 parameters 提供必填参数输入；返回的 navigate、refresh 效果也只是显示说明文本，没有执行导航或刷新。影响：带必填参数的命令无法执行，其他命令可能显示成功但未完成预期界面操作。建议：复用现有 PluginMcpPanel 的参数表单、when 判断和效果处理流程，避免两个入口行为不一致。 ## 验证情况 - 现有前端测试：26 个文件、113 项通过。 - 类型检查与生产构建通过，存在大体积 chunk 警告。 - 补充测试复现了主题恢复、真实事件建树、叶子详情三个问题。 - 其余问题已通过调用链核查确认。 - 与当前 main 无合并冲突。 - 尚未进行真实浏览器端到端联调。请修复上述问题并补充回归测试后，再次提交审阅。

Kronecker closed this pull request

2026-09-04 20:23:58 +08:00

saint referenced this issue from a commit

2026-09-04 23:28:28 +08:00

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

saint referenced this issue from a commit

2026-09-05 10:04:36 +08:00

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

saint referenced this pull request

2026-09-05 10:08:00 +08:00

feat(frontend): 第二阶段前端审阅修复（Trace 建树 / 主题包 CSS / 引用定位 / 插件命令） #23