188 lines
19 KiB
Markdown
188 lines
19 KiB
Markdown
---
|
||
date: "2026-06-12"
|
||
topic: "frontend-productization"
|
||
---
|
||
|
||
## Summary
|
||
|
||
对 Fischer AgentKit 前端三个核心界面（可视化编排器、监控数据看板、知识库管理）进行产品级重建，补齐后端 API 缺口，引入 ECharts 图表库，使整体达到面向外部用户交付的产品化标准。
|
||
|
||
## Problem Frame
|
||
|
||
Fischer AgentKit 后端能力丰富——ReAct/ReWoo/Reflexion 多种推理引擎、Pipeline 编排与 Saga 补偿、自我进化与 A/B 测试、RAG 多源检索——但前端界面停留在 70% 完成度的内部工具水平。可视化编排器的拖拽放置未完成、并行节点缺失；进化仪表盘用原生 SVG 画折线图，无交互无实时推送；知识库上传后数据回填有 bug、文档管理不完整。对于产品化交付，这些界面需要从"能用"升级到"专业"。
|
||
|
||
同时，后端存在多个 API 缺口：终端 API 完全缺失（前端已实现调用逻辑）、设置 API 缺失、工作流执行历史无法列表查询、KB 文档无法删除和同步、进化仪表盘 WebSocket 推送为空壳。前端重建依赖这些 API 补齐。
|
||
|
||
## Key Decisions
|
||
|
||
**方案 B 关键界面重建而非方案 A 补全修复。** 产品化需要质感提升——修补现有代码无法解决架构层面的问题（API 层重复代码、Ant Design 全量引入、SVG 图表无交互能力）。保留整体架构，对三个核心视图进行重建。
|
||
|
||
**三个模块并行推进。** 产品化交付需要整体一致性，串行推进会导致长时间内部分界面专业、部分界面粗糙。每个模块先做核心功能闭环，再迭代增强。
|
||
|
||
**引入 ECharts 替换原生 SVG。** 进化仪表盘的指标趋势、避坑预警、路径优化等数据可视化需要专业图表库的交互能力（tooltip、缩放、数据点悬停）。ECharts 中文文档完善、功能强大，适合产品化场景。
|
||
|
||
**前后端协同推进。** 前端重建依赖后端 API 补齐，两者需同步推进。后端 API 缺口作为本次需求的一部分纳入。
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### 可视化编排器
|
||
|
||
R1. 拖拽放置功能完整可用——从左侧节点面板拖拽节点到画布，松开鼠标后节点出现在画布对应位置，自动对齐网格
|
||
- **完成标准：** ① 从节点面板拖拽任意类型节点（技能/条件/审批/并行）到画布，松开后节点出现在鼠标释放位置（对齐 15px 网格）；② 拖拽过程中画布显示放置预览指示；③ 拖拽到画布外区域时节点不被创建；④ 连续拖拽 3 个节点到画布，位置均正确无偏移
|
||
|
||
R2. 并行节点拥有自定义 Vue Flow 组件——与技能节点、条件节点、审批节点同级，支持属性编辑（最大并行数），视觉上可区分
|
||
- **完成标准：** ① 并行节点在画布上渲染为绿色自定义组件（与技能蓝/条件橙/审批紫视觉区分）；② 右侧属性面板可编辑"最大并行数"字段；③ 并行节点可正常连线（输入端口和输出端口）；④ 序列化/反序列化后并行节点属性不丢失
|
||
|
||
R3. 条件分支可视化引导——条件节点的"是/否"两个输出端口在画布上有明确标注，连线时自动提示分支方向
|
||
- **完成标准：** ① 条件节点渲染时，两个输出端口分别标注"是"和"否"标签；② 从"是"端口拖出连线时，目标节点自动标记为真分支；③ 从"否"端口拖出连线时，目标节点自动标记为假分支；④ 序列化后 `branch_targets` 正确反映连线关系
|
||
|
||
R4. 撤销/重做支持——编辑操作（添加/删除节点、连线、修改属性）可撤销和重做，快捷键 Ctrl+Z / Ctrl+Shift+Z
|
||
- **完成标准：** ① 添加节点后按 Ctrl+Z，节点从画布消失；② 删除节点后按 Ctrl+Z，节点恢复原位；③ 连线后按 Ctrl+Z，连线消失；④ 修改属性后按 Ctrl+Z，属性恢复原值；⑤ 撤销后按 Ctrl+Shift+Z，操作重做；⑥ 连续操作 5 次后全部撤销再全部重做，画布状态与操作后一致
|
||
|
||
R5. 工作流执行动画——执行中的阶段节点在画布上高亮显示当前状态（运行中/已完成/已失败），通过 WebSocket 实时更新
|
||
- **完成标准：** ① 执行工作流后，当前运行阶段节点显示脉冲动画（运行中）；② 阶段完成后节点变为绿色勾选状态；③ 阶段失败后节点变为红色错误状态；④ 审批节点暂停时显示等待图标；⑤ 状态变化延迟不超过 1 秒（WebSocket 推送）；⑥ 未执行的节点保持默认样式
|
||
|
||
R6. 工作流执行历史列表——后端新增 `GET /workflows/{workflow_id}/executions` 端点，前端展示历史执行记录，支持查看每次执行的阶段结果和状态
|
||
- **完成标准：** ① 后端端点返回指定工作流的执行记录列表（含 execution_id、状态、开始/结束时间）；② 前端工作流详情页展示执行历史表格；③ 点击某条记录可展开查看各阶段结果；④ 空历史时显示空状态提示；⑤ API 返回分页数据，前端支持翻页
|
||
|
||
### 监控与数据看板
|
||
|
||
R7. ECharts 替换原生 SVG 图表——指标趋势图（成功率、平均耗时、重试率）使用 ECharts 折线图，支持 tooltip、数据点悬停高亮、图例切换
|
||
- **完成标准：** ① 指标趋势图使用 ECharts 渲染，不再包含原生 SVG 绘制代码；② 鼠标悬停数据点时显示 tooltip（日期、数值）；③ 点击图例可切换显示/隐藏对应趋势线；④ 时间周期切换（7天/30天/全部）后图表正确刷新；⑤ 图表自适应容器宽度，窗口缩放后自动重绘
|
||
|
||
R8. 进化仪表盘实时 WebSocket 推送——后端在经验记录新增、指标更新、避坑检测等事件中触发 WebSocket 推送，前端接收后自动刷新对应面板
|
||
- **完成标准：** ① 后端 `EvolutionStore` 写操作（新增经验、更新指标、检测避坑）后调用 `_broadcast_event`；② 前端 WebSocket 连接建立后收到 `subscribed` 确认；③ 新经验记录产生后，经验时间线在 2 秒内自动追加新条目；④ 指标更新后，趋势图自动刷新数据；⑤ WebSocket 断开后自动重连（最多 3 次，间隔 5 秒）
|
||
|
||
R9. 经验时间线筛选 bug 修复——`onExperienceFilter` 函数正确传递 outcome 参数，筛选功能实际生效
|
||
- **完成标准：** ① 选择"成功"筛选后，时间线仅显示 outcome 为 success 的记录；② 选择"失败"筛选后，时间线仅显示 outcome 为 failure 的记录；③ 选择"全部"后恢复显示所有记录；④ 切换筛选时 API 请求中 outcome 参数正确传递（非 undefined）
|
||
|
||
R10. 全局概览页——新增仪表盘首页，展示系统级指标：总任务数、Agent 活跃数、LLM 用量统计、质量门禁通过率，作为进入各子面板的入口
|
||
- **完成标准：** ① 概览页展示 4 个摘要卡片（总任务数、Agent 活跃数、LLM 用量、质量通过率），数据来自后端 API；② 每个卡片可点击跳转到对应子面板；③ 页面加载时显示骨架屏/loading 状态；④ 数据为空时显示零值而非空白；⑤ 概览页为进化模块的默认着陆页
|
||
|
||
R11. 用量统计面板——展示 LLM Token 用量趋势（按 Provider/模型分组）、请求成功率、平均响应延迟，支持时间范围选择
|
||
- **完成标准：** ① 展示 Token 用量折线图（按 Provider 分组，不同颜色区分）；② 展示请求成功率百分比和平均响应延迟（ms）；③ 支持时间范围选择（今日/7天/30天）；④ 数据来自 `GET /llm/usage` 端点；⑤ 无数据时显示空状态提示
|
||
|
||
### 知识库管理界面
|
||
|
||
R12. 文档上传数据回填修复——上传成功后使用后端返回的真实 `document_id` 和 `chunks` 数，而非前端伪造的 `Date.now()`
|
||
- **完成标准：** ① 上传文档后，文档列表中显示的 document_id 与后端返回值一致；② 分块数显示后端返回的 chunks 值；③ 上传多个文档后，每个文档的 id 均唯一且来自后端；④ 上传失败时文档不出现在列表中，且显示错误提示
|
||
|
||
R13. 文档列表与删除——后端新增 `GET /kb-management/documents` 和 `DELETE /kb-management/documents/{document_id}` 端点，前端展示已上传文档列表并支持删除
|
||
- **完成标准：** ① 后端 `GET /kb-management/documents` 返回文档列表（含 document_id、filename、chunks、status、created_at）；② 前端文档管理 Tab 展示完整文档列表（文件名、状态、分块数、上传时间）；③ 点击删除按钮后弹出确认对话框，确认后调用 DELETE 端点；④ 删除成功后文档从列表中移除；⑤ 删除失败时显示错误提示，文档保留在列表中
|
||
|
||
R14. 信息源同步触发——后端新增 `POST /kb-management/sources/{source_id}/sync` 端点，前端在信息源详情中提供"立即同步"按钮，显示同步进度
|
||
- **完成标准：** ① 后端端点触发指定信息源的同步操作并返回同步任务状态；② 前端信息源表格中每行有"同步"按钮；③ 点击后按钮变为 loading 状态，同步完成后恢复；④ 同步完成后信息源的"最近同步时间"更新；⑤ 同步失败时按钮恢复，并显示错误提示
|
||
|
||
R15. 信息源配置更新——后端新增 `PUT /kb-management/sources/{source_id}` 端点，前端支持编辑已有信息源的配置
|
||
- **完成标准：** ① 后端端点接受信息源配置更新请求并返回更新后的完整信息源对象；② 前端信息源表格中每行有"编辑"按钮；③ 点击后弹出编辑表单，预填当前配置；④ 保存后信息源列表刷新显示新配置；⑤ 编辑飞书/Confluence/HTTP 类型信息源时，表单字段与新增时一致
|
||
|
||
R16. 检索高级选项——检索测试支持指定信息源范围、调整 top_k 参数、选择检索策略（向量/混合）
|
||
- **完成标准：** ① 检索测试区域新增"高级选项"折叠面板；② 可选择指定信息源（多选下拉框，默认全部）；③ 可调整 top_k 参数（数字输入框，默认 5，范围 1-20）；④ 可选择检索策略（向量/混合，单选）；⑤ 高级选项参数随检索请求一起发送到后端；⑥ 后端 `POST /kb-management/search` 端点接受并处理这些参数
|
||
|
||
### 后端 API 补齐
|
||
|
||
R17. 终端 API 实现——后端新增终端路由模块，提供 `POST /terminal/execute`、`GET /terminal/sessions`、`GET /terminal/sessions/{sessionId}/history`、`WS /terminal/ws` 四个端点，对接已有的 PTYSession 工具
|
||
- **完成标准：** ① `POST /terminal/execute` 接受命令字符串，创建 PTYSession 执行并返回 session_id 和初始输出；② `GET /terminal/sessions` 返回当前活跃终端会话列表；③ `GET /terminal/sessions/{sessionId}/history` 返回指定会话的命令历史；④ `WS /terminal/ws` 支持实时命令输入和输出流；⑤ 命令执行受安全策略约束（白名单或确认机制）；⑥ 前端终端页面可正常执行命令并查看输出
|
||
|
||
R18. 设置 API 实现——后端新增设置路由模块，提供 `GET/PUT /settings/llm`、`GET/PUT /settings/skills`、`GET/PUT /settings/kb`、`GET/PUT /settings/general` 端点，前端 Settings 页面可读写配置
|
||
- **完成标准：** ① `GET /settings/llm` 返回当前 LLM 配置（Provider 列表、默认模型、别名等），不暴露 API Key 明文；② `PUT /settings/llm` 更新 LLM 配置并触发热重载；③ `GET/PUT /settings/skills` 读写技能路径配置；④ `GET/PUT /settings/kb` 读写知识库连接配置；⑤ `GET/PUT /settings/general` 读写通用设置（日志级别、Server 端口等）；⑥ 前端 Settings 页面可展示和修改所有配置项；⑦ 配置修改后无需重启服务即可生效
|
||
|
||
R19. 工作流 Skill 阶段真实执行——工作流执行引擎中 skill 类型阶段调用真实的 Skill 执行，而非返回 `{"dry_run": True}` 模拟数据
|
||
- **完成标准：** ① 工作流执行到 skill 类型阶段时，通过 SkillRegistry 查找并调用对应 Skill；② Skill 执行结果（含输出和元数据）写入 WorkflowExecution 的 stage_results；③ Skill 执行失败时，阶段状态标记为 failed 并记录错误信息；④ 前端工作流执行详情中可查看 Skill 的真实输出；⑤ 不影响 condition/approval/parallel 类型阶段的现有执行逻辑
|
||
|
||
### 技术改进
|
||
|
||
R20. 前端 API 层抽取公共基类——6 个 API 文件的重复 request 函数、错误处理逻辑抽取为共享的 `api/base.ts`，各模块继承使用
|
||
- **完成标准：** ① `api/base.ts` 提供统一的 request 函数（含 baseURL、超时、错误处理）；② 6 个 API 文件（portal/workflow/evolution/kb/skills/terminal）均使用 base.ts 的 request，不再各自独立实现；③ 统一的错误处理：网络错误、401 认证失败、5xx 服务端错误均有对应提示；④ 统一的响应拦截：非 2xx 状态码统一抛出异常；⑤ 现有 API 调用行为不变（回归验证）
|
||
|
||
R21. Ant Design Vue 按需引入——替换 `app.use(Antd)` 全量注册为按需引入，减小打包体积
|
||
- **完成标准：** ① `main.ts` 中移除 `app.use(Antd)` 全量注册；② 配置 `unplugin-vue-components` 和 `unplugin-auto-import` 实现按需引入；③ 所有现有页面渲染和交互行为不变（回归验证）；④ 打包产物中 ant-design-vue 体积较全量引入减少 40% 以上；⑤ 构建无报错、无运行时组件缺失警告
|
||
|
||
R22. ECharts 按需引入——仅引入折线图、柱状图、饼图等使用的图表类型和组件，避免全量打包
|
||
- **完成标准：** ① 使用 ECharts 按需引入 API（`echarts/use` + 所需图表/组件注册）；② 引入的图表类型覆盖：折线图（LineChart）、柱状图（BarChart）、饼图（PieChart）；③ 引入的组件覆盖：TooltipComponent、LegendComponent、GridComponent、DataZoomComponent；④ 打包产物中 echarts 体积较全量引入减少 50% 以上；⑤ 所有图表渲染和交互行为正常
|
||
|
||
---
|
||
|
||
## Key Flows
|
||
|
||
- F1. 拖拽创建工作流节点
|
||
- **Trigger:** 用户从左侧节点面板拖拽节点到画布区域
|
||
- **Actors:** 开发者、运营人员
|
||
- **Steps:** 用户按住节点类型卡片 → 拖动到画布目标位置 → 松开鼠标 → 节点出现在画布对应位置（自动对齐 15px 网格）→ 右侧属性面板自动展示新节点属性表单 → 用户可编辑属性
|
||
- **Covered by:** R1
|
||
|
||
- F2. 工作流执行与实时反馈
|
||
- **Trigger:** 用户点击"执行"按钮并输入变量
|
||
- **Actors:** 开发者、运营人员
|
||
- **Steps:** 用户输入执行变量 → 后端创建执行实例 → WebSocket 推送 `stage_started` 事件 → 对应节点高亮为"运行中" → 阶段完成推送 `stage_completed` → 节点变为"已完成"（失败则标红）→ 审批节点暂停等待人工操作 → 全部完成推送 `execution_completed`
|
||
- **Covered by:** R5, R6, R19
|
||
|
||
- F3. 知识库文档管理闭环
|
||
- **Trigger:** 用户上传文档或管理已有文档
|
||
- **Actors:** 运营人员
|
||
- **Steps:** 用户拖拽上传文档 → 后端处理并返回真实 document_id 和分块数 → 文档列表自动刷新 → 用户可删除文档 → 用户可触发信息源同步 → 同步进度实时显示
|
||
- **Covered by:** R12, R13, R14
|
||
|
||
- F4. 进化仪表盘实时监控
|
||
- **Trigger:** 用户打开进化仪表盘页面
|
||
- **Actors:** 开发者
|
||
- **Steps:** 页面加载获取初始数据 → 建立 WebSocket 连接 → 后端经验记录新增时推送事件 → 经验时间线自动追加新记录 → 指标趋势图自动更新 → 用户可按时间范围/结果筛选
|
||
- **Covered by:** R7, R8, R9
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
**Deferred for later:**
|
||
|
||
- 暗色模式——当前所有样式硬编码白色背景，暗色模式需要设计系统层面的改造，本次不纳入
|
||
- 角色视图切换（开发者/运营人员）——两个角色共享同一界面，通过信息架构和交互引导区分使用路径，不做独立的角色视图
|
||
- Computer Use 页面——仅占位页，功能独立于本次前端升级
|
||
- CI/CD 流水线——项目当前无 CI 配置，独立于前端重建
|
||
- 前端单元测试和 E2E 测试——当前前端零测试覆盖，测试体系建设可作为后续专项
|
||
|
||
**Outside this product's identity:**
|
||
|
||
- 多语言国际化（i18n）——当前用户群体为中文用户，全局已配置中文 locale，暂不需要多语言支持
|
||
- 移动端适配——AgentKit 是桌面端工具，不需要响应式移动端布局
|
||
|
||
---
|
||
|
||
## Dependencies / Assumptions
|
||
|
||
- 后端 API 补齐（R6, R13, R14, R15, R17, R18, R19）是前端重建的前置条件，需前后端协同推进
|
||
- 终端 API（R17）依赖已有的 `PTYSession` 工具（`src/agentkit/tools/pty_session.py`），需将其能力暴露为 HTTP/WebSocket 端点
|
||
- 设置 API（R18）依赖 `agentkit.yaml` 配置文件的热重载机制（`src/agentkit/server/app.py` 中的 `_on_config_change`），需评估 API 写入配置的安全边界
|
||
- 工作流真实执行（R19）需要将 `WorkflowStage` 中 skill 类型阶段的执行逻辑对接到 `SkillRegistry`，当前为 dry-run 模拟
|
||
- 进化仪表盘 WebSocket 推送（R8）需要在 `EvolutionStore` 的写操作中调用 `_broadcast_event`，当前该函数已定义但从未被业务逻辑调用
|
||
- ECharts 和 Ant Design Vue 按需引入（R21, R22）需要 Vite 插件支持（`unplugin-vue-components` 和 `unplugin-auto-import`）
|
||
|
||
---
|
||
|
||
## Outstanding Questions
|
||
|
||
**Resolve Before Planning:**
|
||
|
||
- 终端 API（R17）的安全边界：Shell 命令执行存在安全风险，需确认是否复用 `ShellTool` 的白名单机制，还是采用其他安全策略
|
||
|
||
**Deferred to Planning:**
|
||
|
||
- 全局概览页（R10）的数据聚合方式：是从现有多个端点聚合，还是新增专用概览端点
|
||
- 工作流执行动画（R5）的节点状态样式方案：是在现有节点组件上叠加状态层，还是创建带状态的节点变体
|
||
|
||
---
|
||
|
||
## Sources / Research
|
||
|
||
- 前端项目结构：`src/agentkit/server/frontend/`（Vue 3 + TypeScript + Ant Design Vue 4 + @vue-flow/core）
|
||
- 后端路由注册：`src/agentkit/server/app.py`（14 个路由模块挂载于 `/api/v1`）
|
||
- 工作流 Schema：`src/agentkit/orchestrator/workflow_schema.py`（WorkflowDefinition / WorkflowStage / WorkflowExecution）
|
||
- 工作流路由：`src/agentkit/server/routes/workflows.py`（CRUD + 执行 + WebSocket）
|
||
- 进化仪表盘路由：`src/agentkit/server/routes/evolution_dashboard.py`（四大数据面板 + WebSocket 空壳推送）
|
||
- 知识库管理路由：`src/agentkit/server/routes/kb_management.py`（信息源 CRUD + 文档上传 + 检索）
|
||
- PTYSession 工具：`src/agentkit/tools/pty_session.py`（终端会话管理，终端 API 的底层依赖）
|
||
- 前端终端 API 定义：`src/agentkit/server/frontend/src/api/terminal.ts`（已定义但后端缺失的四个端点）
|
||
- 前端工作流序列化：`src/agentkit/server/frontend/src/views/WorkflowView/workflowSerializer.ts`（Vue Flow 模型与后端 Schema 双向转换）
|