fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-12-frontend-product...

19 KiB
Raw Blame History

date topic
2026-06-12 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 双向转换）