fischer-agentkit/2026-06-12-023-feat-frontend-productization-plan.md at 2296d0b2093725243e1d0e2df4ddb50e2952b632

30 KiB

Raw Blame History

date	status	origin	type
2026-06-12	active	docs/brainstorms/2026-06-12-frontend-productization-requirements.md	feat

Summary

对 Fischer AgentKit 前端三个核心界面（可视化编排器、监控数据看板、知识库管理）进行产品级重建，补齐后端 API 缺口（终端、设置、工作流执行历史、KB 文档管理），引入 ECharts 图表库，抽取前端 API 公共基类，实现 Ant Design Vue 和 ECharts 按需引入，使整体达到面向外部用户交付的产品化标准。

Problem Frame

AgentKit 后端能力丰富但前端停留在 70% 完成度的内部工具水平。可视化编排器拖拽放置未完成、并行节点缺失；进化仪表盘用原生 SVG 画折线图无交互无实时推送；知识库上传数据回填有 bug、文档管理不完整。后端存在多个 API 缺口（终端、设置、执行历史、KB 文档管理），前端重建依赖这些 API 补齐。产品化交付需要前后端协同推进，三个模块并行达到可交付水平。

Requirements Traceability

R-ID	需求摘要	覆盖单元
R1	拖拽放置功能完整可用	U1
R2	并行节点自定义组件	U1
R3	条件分支可视化引导	U1
R4	撤销/重做支持	U2
R5	工作流执行动画	U3
R6	工作流执行历史列表	U4
R7	ECharts 替换原生 SVG	U5
R8	进化仪表盘实时推送	U6
R9	经验时间线筛选修复	U5
R10	全局概览页	U7
R11	用量统计面板	U7
R12	文档上传数据回填修复	U8
R13	文档列表与删除	U9
R14	信息源同步触发	U9
R15	信息源配置更新	U9
R16	检索高级选项	U9
R17	终端 API 实现	U10
R18	设置 API 实现	U11
R19	工作流 Skill 真实执行	U4
R20	前端 API 公共基类	U12
R21	Ant Design Vue 按需引入	U12
R22	ECharts 按需引入	U12

Key Technical Decisions

KTD1. 终端 API 安全策略：白名单 + 用户确认 + 可加入白名单。 复用 ShellTool 的 _SAFE_COMMAND_PREFIXES 和 _is_dangerous() 检测逻辑。白名单内命令直接执行；非白名单命令通过 WebSocket 推送确认请求，用户确认后执行，确认时可选择将命令加入白名单。白名单存储在服务端内存中（与 ShellTool 一致），不持久化到配置文件。

KTD2. 工作流执行引擎改造：Skill 阶段接入 SkillRegistry。 在 _execute_workflow 的 skill 类型分支中，通过 app.state.skill_registry 查找并执行对应 Skill，将结果写入 stage_results。Parallel 阶段使用 asyncio.gather() 并行执行子阶段。Condition 阶段增加分支跳过逻辑（不满足条件的下游阶段标记为 skipped）。

KTD3. ECharts 按需引入策略。 使用 ECharts 5.x 的 tree-shakable API（echarts/use + 手动注册所需图表类型和组件），配合 Vite 的自然 tree-shaking。不引入全量 echarts 包。需引入：LineChart、BarChart、PieChart、TooltipComponent、LegendComponent、GridComponent、DataZoomComponent。

KTD4. 前端 API 层统一：class 风格基类。 将 6 个 API 文件统一为 class 风格（与现有 ApiClient、WorkflowApiClient、EvolutionApiClient 一致），提取公共 request<T>() 方法到 BaseApiClient，各模块继承并指定 baseUrl。WebSocket 创建逻辑也统一到基类。

KTD5. 撤销/重做实现：命令模式 + 栈。 使用命令模式（Command Pattern）封装画布编辑操作（AddNode、DeleteNode、AddEdge、DeleteEdge、UpdateProperty），维护 undo/redo 两个栈。每次操作执行时压入 undo 栈并清空 redo 栈，撤销时从 undo 弹出执行 inverse 并压入 redo，重做反之。

KTD6. 进化仪表盘 WebSocket 推送激活。 在 evolution_dashboard.py 的 REST 端点中，写操作完成后调用 _broadcast_event()。前端在 EvolutionView 挂载时建立 WebSocket 连接，按频道订阅（experiences/metrics/pitfalls/optimizations），收到推送后调用对应 store 方法刷新数据。

High-Level Technical Design

flowchart TB
    subgraph Frontend["前端 (Vue 3 + TypeScript)"]
        WF[工作流编排器] --> WFStore[WorkflowStore]
        EV[进化仪表盘] --> EVStore[EvolutionStore]
        KB[知识库管理] --> KBStore[KnowledgeStore]
        TM[终端] --> TMStore[TerminalStore]
        ST[设置] --> STStore[SettingsStore]

        WFStore --> API[BaseApiClient]
        EVStore --> API
        KBStore --> API
        TMStore --> API
        STStore --> API

        API --> HTTP[REST API]
        API --> WS[WebSocket]
    end

    subgraph Backend["后端 (FastAPI)"]
        HTTP --> WFRoutes[Workflow Routes]
        HTTP --> EVDRoutes[Evolution Dashboard Routes]
        HTTP --> KBRoutes[KB Management Routes]
        HTTP --> TMRoutes[Terminal Routes]
        HTTP --> STRoutes[Settings Routes]

        WS --> WFWS[Workflow WS]
        WS --> EVWS[Evolution WS]
        WS --> TMWS[Terminal WS]

        WFRoutes --> WFEngine[Workflow Execution Engine]
        TMRoutes --> PTY[PTYSession]
        TMRoutes --> Security[ShellTool 白名单]
        STRoutes --> Config[Config Hot Reload]
        WFEngine --> SkillReg[SkillRegistry]
    end

Implementation Units

U1. 工作流编排器核心修复

Goal: 修复拖拽放置、添加并行节点组件、实现条件分支可视化引导，使编排器基本可用

Requirements: R1, R2, R3

Dependencies: 无

Files:

src/agentkit/server/frontend/src/components/workflow/FlowCanvas.vue -- 修复 onDrop，添加节点到画布
src/agentkit/server/frontend/src/components/workflow/NodePalette.vue -- 无需修改（拖拽发起端已正常）
src/agentkit/server/frontend/src/components/workflow/ParallelNode.vue -- 新建并行节点自定义组件
src/agentkit/server/frontend/src/components/workflow/ConditionNode.vue -- 修改条件节点，添加"是/否"端口标签
src/agentkit/server/frontend/src/stores/workflow.ts -- addNode 支持 parallel 类型，条件分支端口映射
src/agentkit/server/frontend/src/views/WorkflowView.vue -- 注册 parallel 节点类型，监听 drop 事件

Approach:

修复 FlowCanvas.vue 的 onDrop：调用 store.addNode(nodeType, position) 将节点添加到画布，位置对齐 15px 网格
新建 ParallelNode.vue：绿色主题自定义组件，显示并行图标和最大并行数，包含输入端口和输出端口
在 FlowCanvas.vue 的 nodeTypes 中注册 parallel: ParallelNode
修改 ConditionNode.vue：两个输出端口分别标注"是"和"否"标签，使用 Handle 组件的 id 和 position 属性区分
修改 workflowSerializer.ts：序列化时将条件节点的边映射到 branch_targets（true/false），反序列化时还原

Patterns to follow: 现有 SkillNode.vue、ConditionNode.vue、ApprovalNode.vue 的组件结构

Test scenarios:

拖拽技能节点到画布，节点出现在正确位置且对齐网格
拖拽并行节点到画布，渲染为绿色自定义组件
拖拽条件节点到画布，"是/否"端口标签可见
从条件节点"是"端口连线到目标节点，序列化后 branch_targets 包含 true 分支
拖拽到画布外区域，节点不被创建
连续拖拽 3 个不同类型节点，位置均正确

Verification: 前端 dev server 启动后，在工作流页面可拖拽创建所有 4 种节点，条件节点端口标注正确，序列化/反序列化后属性不丢失

U2. 工作流撤销/重做

Goal: 实现画布编辑操作的撤销/重做功能

Requirements: R4

Dependencies: U1

Files:

src/agentkit/server/frontend/src/stores/workflow.ts -- 添加 undo/redo 栈和命令执行逻辑
src/agentkit/server/frontend/src/components/workflow/FlowCanvas.vue -- 注册 Ctrl+Z / Ctrl+Shift+Z 快捷键
src/agentkit/server/frontend/src/components/workflow/PropertyPanel.vue -- 属性修改操作入栈

Approach:

定义 Command 接口：{ execute(), undo() }
实现 AddNodeCommand、DeleteNodeCommand、AddEdgeCommand、DeleteEdgeCommand、UpdatePropertyCommand
WorkflowStore 增加 undoStack: Command[] 和 redoStack: Command[]
每次操作执行时创建 Command 压入 undoStack，清空 redoStack
undo() 从 undoStack 弹出执行 command.undo()，压入 redoStack
redo() 从 redoStack 弹出执行 command.execute()，压入 undoStack
FlowCanvas 注册 onKeyDown 监听 Ctrl+Z / Ctrl+Shift+Z

Patterns to follow: Vue Flow 官方示例中的 undo/redo 实现

Test scenarios:

添加节点后 Ctrl+Z，节点从画布消失
删除节点后 Ctrl+Z，节点恢复原位
连线后 Ctrl+Z，连线消失
修改属性后 Ctrl+Z，属性恢复原值
撤销后 Ctrl+Shift+Z，操作重做
连续 5 次操作后全部撤销再全部重做，画布状态一致

Verification: 在工作流编辑器中执行各种操作后，Ctrl+Z/Ctrl+Shift+Z 可正确撤销/重做

U3. 工作流执行动画

Goal: 工作流执行时画布节点实时显示状态动画

Requirements: R5

Dependencies: U1

Files:

src/agentkit/server/frontend/src/stores/workflow.ts -- 接入 WebSocket，更新节点状态
src/agentkit/server/frontend/src/components/workflow/FlowCanvas.vue -- 根据节点状态渲染动画样式
src/agentkit/server/frontend/src/components/workflow/SkillNode.vue -- 添加状态样式（运行中脉冲、完成绿色、失败红色）
src/agentkit/server/frontend/src/components/workflow/ConditionNode.vue -- 添加状态样式
src/agentkit/server/frontend/src/components/workflow/ApprovalNode.vue -- 添加等待图标样式
src/agentkit/server/frontend/src/components/workflow/ParallelNode.vue -- 添加状态样式

Approach:

WorkflowStore 建立 WebSocket 连接（复用 createWorkflowWebSocket），订阅执行事件
收到 stage_started 事件时，更新对应节点的 data.status = 'running'
收到 stage_completed 事件时，更新 data.status = 'completed'
收到 stage_failed 事件时，更新 data.status = 'failed'
收到 approval_required 事件时，更新 data.status = 'waiting_approval'
各节点组件根据 data.status 渲染不同样式：running 脉冲动画、completed 绿色勾选、failed 红色错误、waiting_approval 等待图标
替换当前的轮询机制为 WebSocket 推送

Patterns to follow: 现有 WorkflowApi 的 createWorkflowWebSocket 方法

Test scenarios:

执行工作流后，当前阶段节点显示脉冲动画
阶段完成后节点变为绿色勾选
阶段失败后节点变为红色错误
审批节点暂停时显示等待图标
未执行节点保持默认样式
WebSocket 断开后自动重连

Verification: 执行工作流时，画布节点实时反映执行状态，延迟不超过 1 秒

U4. 工作流执行历史与 Skill 真实执行

Goal: 后端新增执行历史 API，工作流 Skill 阶段调用真实 Skill 执行

Requirements: R6, R19

Dependencies: U3

Files:

src/agentkit/server/routes/workflows.py -- 新增执行历史端点，改造 skill/parallel 阶段执行逻辑
src/agentkit/orchestrator/workflow_schema.py -- WorkflowStore 增加按 workflow_id 查询执行记录方法
src/agentkit/server/frontend/src/api/workflow.ts -- 新增 listExecutions 方法
src/agentkit/server/frontend/src/stores/workflow.ts -- 加载执行历史
src/agentkit/server/frontend/src/views/WorkflowView.vue -- 执行历史表格展示
tests/unit/server/test_workflow_routes.py -- 新增测试

Approach:

WorkflowStore 新增 list_executions(workflow_id) 方法，从内存存储中过滤
后端新增 GET /workflows/{workflow_id}/executions 端点，返回分页执行记录
改造 _execute_workflow 中 skill 类型分支：通过 app.state.skill_registry 查找 Skill，调用 skill.execute() 或通过 AgentPool 分发任务
改造 parallel 类型分支：使用 asyncio.gather() 并行执行子阶段
前端新增执行历史面板，展示表格（execution_id、状态、开始/结束时间），支持展开查看阶段结果

Patterns to follow: 现有 test_workflow_routes.py 的 fixture 和测试组织模式

Test scenarios:

GET /workflows/{id}/executions 返回指定工作流的执行记录列表
Skill 阶段执行返回真实输出而非 dry_run 模拟数据
Skill 执行失败时阶段状态标记为 failed
Parallel 阶段并行执行子阶段
前端执行历史表格正确展示记录
空历史时显示空状态提示

Verification: 执行包含 skill 阶段的工作流后，执行历史中可查看真实 Skill 输出

U5. ECharts 图表替换与筛选修复

Goal: 用 ECharts 替换原生 SVG 图表，修复经验时间线筛选 bug

Requirements: R7, R9

Dependencies: U12（ECharts 按需引入需先完成）

Files:

src/agentkit/server/frontend/src/components/evolution/MetricsChart.vue -- 用 ECharts 重写
src/agentkit/server/frontend/src/views/EvolutionView.vue -- 修复 onExperienceFilter
src/agentkit/server/frontend/src/utils/echarts.ts -- 新建 ECharts 按需引入配置

Approach:

新建 utils/echarts.ts：按需注册 LineChart、BarChart、PieChart、TooltipComponent、LegendComponent、GridComponent、DataZoomComponent，导出 use 函数
重写 MetricsChart.vue：使用 ECharts 折线图，配置 tooltip、legend、dataZoom，自适应容器宽度（ResizeObserver）
修复 EvolutionView.vue 的 onExperienceFilter：正确传递 outcome 参数（store.loadExperiences(outcome || undefined)），同时修正 loadExperiences 的参数语义（从 taskType 改为 outcome）
删除原生 SVG 绘制代码

Patterns to follow: ECharts 5.x 按需引入官方文档

Test scenarios:

指标趋势图使用 ECharts 渲染，无原生 SVG 代码残留
鼠标悬停数据点显示 tooltip
点击图例切换显示/隐藏趋势线
时间周期切换后图表正确刷新
图表自适应容器宽度
选择"成功"筛选后仅显示 success 记录
选择"失败"筛选后仅显示 failure 记录

Verification: 进化仪表盘页面图表交互正常，筛选功能生效

U6. 进化仪表盘实时 WebSocket 推送

Goal: 激活后端 WebSocket 推送，前端接收后自动刷新面板

Requirements: R8

Dependencies: U5

Files:

src/agentkit/server/routes/evolution_dashboard.py -- 在写操作后调用 _broadcast_event
src/agentkit/server/frontend/src/stores/evolution.ts -- 建立 WebSocket 连接，处理推送事件
src/agentkit/server/frontend/src/views/EvolutionView.vue -- 挂载时连接 WebSocket，卸载时断开
tests/unit/server/test_evolution_dashboard.py -- 新增 WebSocket 推送测试

Approach:

后端：在 POST /evolution/trigger、经验记录新增、指标更新等写操作完成后调用 _broadcast_event(connections, event_type, data)
前端 EvolutionStore：增加 connectWebSocket() 和 disconnectWebSocket() 方法
WebSocket 消息处理：收到 experience_added 刷新经验时间线，收到 metrics_updated 刷新趋势图，收到 pitfall_detected 刷新避坑预警
EvolutionView onMounted 时调用 connectWebSocket()，onUnmounted 时调用 disconnectWebSocket()
断线重连：最多 3 次，间隔 5 秒

Patterns to follow: 现有 workflow WebSocket 连接模式（createWorkflowWebSocket）

Test scenarios:

WebSocket 连接建立后收到 subscribed 确认
新经验记录产生后，经验时间线在 2 秒内自动追加
指标更新后趋势图自动刷新
WebSocket 断开后自动重连（最多 3 次）
页面卸载时 WebSocket 正确断开

Verification: 打开进化仪表盘，触发进化操作后页面自动刷新

U7. 全局概览页与用量统计面板

Goal: 新增进化模块首页概览和 LLM 用量统计面板

Requirements: R10, R11

Dependencies: U5

Files:

src/agentkit/server/frontend/src/views/EvolutionView.vue -- 重构为带子路由的布局
src/agentkit/server/frontend/src/components/evolution/DashboardOverview.vue -- 新建概览页
src/agentkit/server/frontend/src/components/evolution/UsagePanel.vue -- 新建用量统计面板
src/agentkit/server/frontend/src/router/index.ts -- 添加进化子路由
src/agentkit/server/frontend/src/api/evolution.ts -- 新增用量统计 API 调用

Approach:

重构 EvolutionView 为容器布局：左侧导航（概览/经验/指标/避坑/路径优化/用量统计），右侧内容区
新建 DashboardOverview.vue：4 个摘要卡片（总任务数、Agent 活跃数、LLM 用量、质量通过率），数据从 /metrics 和 /health 端点聚合
新建 UsagePanel.vue：ECharts 折线图展示 Token 用量趋势（按 Provider 分组），摘要卡片展示请求成功率和平均延迟，时间范围选择器
路由：/evolution 默认跳转到 /evolution/overview

Patterns to follow: 现有 EvolutionView 的面板布局模式

Test scenarios:

概览页展示 4 个摘要卡片，数据来自后端 API
每个卡片可点击跳转到对应子面板
页面加载时显示 loading 状态
数据为空时显示零值
用量统计折线图按 Provider 分组显示
时间范围切换后图表刷新
无数据时显示空状态提示

Verification: 访问 /evolution 默认显示概览页，各卡片数据正确，可跳转到子面板

U8. 知识库上传数据回填修复

Goal: 修复文档上传后使用后端返回的真实数据

Requirements: R12

Dependencies: 无

Files:

src/agentkit/server/frontend/src/components/kb/DocumentUpload.vue -- 使用后端返回值
src/agentkit/server/frontend/src/stores/knowledge.ts -- uploadDocument 返回后端数据

Approach:

修改 uploadDocument store 方法：返回后端响应数据（document_id、chunks、status）
修改 DocumentUpload.vue 的 handleUpload 回调：使用后端返回的 document_id 和 chunks 替换 Date.now() 伪造值
上传失败时不将文档添加到列表，显示错误提示

Patterns to follow: 现有上传流程的 FormData + custom-request 模式

Test scenarios:

上传文档后列表显示后端返回的真实 document_id
分块数显示后端返回的 chunks 值
上传多个文档后每个 id 唯一
上传失败时文档不出现在列表中

Verification: 上传文档后列表数据与后端返回值一致

U9. 知识库文档管理与检索增强

Goal: 补齐后端 KB 文档管理 API，前端实现文档列表/删除、信息源同步/更新、检索高级选项

Requirements: R13, R14, R15, R16

Dependencies: U8

Files:

src/agentkit/server/routes/kb_management.py -- 新增文档列表/删除/同步/更新端点，检索支持高级参数
src/agentkit/server/frontend/src/api/kb.ts -- 新增 API 调用方法
src/agentkit/server/frontend/src/components/kb/DocumentUpload.vue -- 文档列表和删除功能
src/agentkit/server/frontend/src/components/kb/SourceConfig.vue -- 同步按钮和编辑功能
src/agentkit/server/frontend/src/components/kb/SearchTest.vue -- 高级选项折叠面板
tests/unit/server/test_kb_management.py -- 新增测试

Approach:

后端新增 GET /kb-management/documents：返回文档列表（从 _source_store.list_documents() 暴露）
后端新增 DELETE /kb-management/documents/{document_id}：从存储中删除文档
后端新增 POST /kb-management/sources/{source_id}/sync：触发外部源同步（飞书/Confluence），返回同步状态
后端新增 PUT /kb-management/sources/{source_id}：更新信息源配置
后端 POST /kb-management/search 增加 source_ids、top_k、strategy 参数
前端 DocumentUpload：加载文档列表，删除按钮带确认弹窗
前端 SourceConfig：每行添加"同步"和"编辑"按钮
前端 SearchTest：新增"高级选项"折叠面板（信息源多选、top_k 输入、策略选择）

Patterns to follow: 现有 kb_management.py 的路由和存储模式

Test scenarios:

GET /kb-management/documents 返回文档列表
DELETE /kb-management/documents/{id} 删除成功后文档不存在
POST /kb-management/sources/{id}/sync 触发同步并返回状态
PUT /kb-management/sources/{id} 更新配置后返回新对象
检索请求带 source_ids/top_k/strategy 参数时后端正确处理
前端文档列表正确展示，删除后列表刷新
同步按钮 loading 状态正确
高级选项参数随检索请求发送

Verification: 知识库页面可完整管理文档和信息源，检索支持高级选项

U10. 终端 API 实现

Goal: 后端新增终端路由模块，对接 PTYSession，前端终端页面可用

Requirements: R17

Dependencies: 无

Files:

src/agentkit/server/routes/terminal.py -- 新建终端路由模块
src/agentkit/server/app.py -- 注册终端路由
src/agentkit/server/frontend/src/api/terminal.ts -- 适配新 API
src/agentkit/server/frontend/src/stores/terminal.ts -- 对接 WebSocket
src/agentkit/server/frontend/src/views/TerminalView.vue -- 集成 xterm.js
tests/unit/server/test_terminal_routes.py -- 新建测试

Approach:

新建 routes/terminal.py，实现 4 个端点：
- POST /terminal/execute：创建 PTYSession 执行命令，白名单检查，非白名单命令返回需确认状态
- GET /terminal/sessions：返回活跃会话列表
- GET /terminal/sessions/{session_id}/history：返回命令历史
- WS /terminal/ws：实时命令输入/输出流，非白名单命令推送确认请求，用户确认后执行，确认时可选择加入白名单
安全策略：复用 ShellTool 的 _is_dangerous() 检测逻辑，白名单内命令直接执行，非白名单通过 WebSocket 推送确认请求
白名单管理：服务端内存维护可扩展白名单（用户确认时选择加入的命令），不持久化
前端集成 xterm.js（需新增依赖），通过 WebSocket 连接实现交互式终端

Patterns to follow: 现有 routes/chat.py 的 WebSocket 端点模式；tools/shell.py 的白名单机制

Test scenarios:

POST /terminal/execute 执行白名单命令返回输出
POST /terminal/execute 非白名单命令返回需确认状态
WebSocket 连接后可交互式执行命令
非白名单命令推送确认请求，确认后执行
确认时选择加入白名单后，后续相同命令直接执行
GET /terminal/sessions 返回活跃会话列表
GET /terminal/sessions/{id}/history 返回命令历史

Verification: 前端终端页面可执行命令、查看输出、确认非白名单命令

U11. 设置 API 实现

Goal: 后端新增设置路由模块，前端 Settings 页面可读写配置

Requirements: R18

Dependencies: 无

Files:

src/agentkit/server/routes/settings.py -- 新建设置路由模块
src/agentkit/server/app.py -- 注册设置路由
src/agentkit/server/frontend/src/api/settings.ts -- 新建设置 API
src/agentkit/server/frontend/src/stores/settings.ts -- 对接 API
src/agentkit/server/frontend/src/views/SettingsView.vue -- 对接真实 API
tests/unit/server/test_settings_routes.py -- 新建测试

Approach:

新建 routes/settings.py，实现 4 组端点：
- GET/PUT /settings/llm：读写 LLM 配置（Provider 列表、默认模型、别名），GET 不暴露 API Key 明文
- GET/PUT /settings/skills：读写技能路径配置
- GET/PUT /settings/kb：读写知识库连接配置
- GET/PUT /settings/general：读写通用设置（日志级别、Server 端口等）
PUT 操作触发配置热重载（复用 _on_config_change 机制）
前端 SettingsView 对接真实 API，替换当前内存数据

Patterns to follow: 现有 app.py 的 _on_config_change 热重载机制

Test scenarios:

GET /settings/llm 返回 LLM 配置，API Key 被脱敏
PUT /settings/llm 更新配置后触发热重载
GET/PUT /settings/skills 读写技能路径
GET/PUT /settings/kb 读写知识库配置
GET/PUT /settings/general 读写通用设置
前端 Settings 页面可展示和修改配置
配置修改后无需重启服务即生效

Verification: 前端 Settings 页面可读写所有配置项，修改后立即生效

U12. 前端基础设施改进

Goal: 抽取 API 公共基类，实现 Ant Design Vue 和 ECharts 按需引入

Requirements: R20, R21, R22

Dependencies: 无（应最先实施，其他单元依赖其产出）

Files:

src/agentkit/server/frontend/src/api/base.ts -- 新建 API 基类
src/agentkit/server/frontend/src/api/client.ts -- 继承基类
src/agentkit/server/frontend/src/api/workflow.ts -- 继承基类
src/agentkit/server/frontend/src/api/evolution.ts -- 继承基类
src/agentkit/server/frontend/src/api/kb.ts -- 重构为 class 风格继承基类
src/agentkit/server/frontend/src/api/terminal.ts -- 重构为 class 风格继承基类
src/agentkit/server/frontend/src/api/skills.ts -- 重构为 class 风格继承基类
src/agentkit/server/frontend/vite.config.ts -- 添加 unplugin 插件
src/agentkit/server/frontend/package.json -- 新增依赖
src/agentkit/server/frontend/src/main.ts -- 移除 app.use(Antd)

Approach:

新建 api/base.ts：BaseApiClient 类，包含 request<T>(method, path, options) 方法（统一 baseURL、超时、错误处理、响应拦截）和 createWebSocket(path) 方法
6 个 API 文件重构为继承 BaseApiClient，指定各自的 baseUrl
安装 unplugin-vue-components 和 unplugin-auto-import，配置 Vite 插件实现 Ant Design Vue 按需引入
main.ts 移除 app.use(Antd) 全量注册
安装 echarts，按需引入配置（在 U5 的 utils/echarts.ts 中完成）

Patterns to follow: 现有 ApiClient、WorkflowApiClient、EvolutionApiClient 的 class 风格

Test scenarios:

BaseApiClient 的 request 方法统一处理错误和响应
6 个 API 模块均使用基类，无独立 request 函数
现有页面渲染和交互行为不变（回归验证）
构建无报错、无运行时组件缺失警告
ant-design-vue 打包体积较全量引入减少 40% 以上

Verification: npm run build 成功，所有现有页面功能正常

Scope Boundaries

In scope: 22 条需求（R1-R22），涵盖可视化编排器、监控数据看板、知识库管理、后端 API 补齐、技术改进

Deferred to follow-up work:

暗色模式——需设计系统层面改造
角色视图切换——通过信息架构区分，不做独立视图
Computer Use 页面——功能独立
CI/CD 流水线——独立于前端重建
前端单元测试和 E2E 测试——后续专项
xterm.js 终端模拟器集成——U10 实现后端 API 和 WebSocket，前端终端交互式体验可后续增强

Open Questions

Deferred to implementation:

全局概览页（R10）数据聚合方式：从现有多个端点聚合还是新增专用概览端点——实现时根据性能需求决定
工作流执行动画（R5）节点状态样式方案：在现有组件上叠加状态层还是创建带状态变体——实现时根据组件复杂度决定
工作流 Skill 真实执行（R19）的变量传递机制：上游 stage_results 如何传递给下游 Skill inputs——实现时根据 Skill 接口设计

Risks & Dependencies

风险	影响	缓解措施
ECharts 按需引入配置复杂，可能遗漏组件导致运行时错误	图表渲染失败	先全量引入验证功能，再逐步切换为按需引入
工作流执行引擎改造影响现有 approval/condition 逻辑	现有功能回归	改造时保持现有分支不变，仅修改 skill/parallel 分支，增加集成测试
终端 API 安全策略绕过风险	安全漏洞	复用 ShellTool 成熟的白名单机制，链式操作符一律视为危险
前端 API 层重构导致现有调用行为变化	页面功能回归	逐模块迁移，每个模块迁移后回归验证
后端 KB 文档管理当前为纯内存存储，重启丢失	数据丢失	本次不解决持久化问题，但在 API 文档中标注此限制

System-Wide Impact

前端构建流程变化：新增 unplugin 插件和 ECharts 依赖，npm install 和 npm run build 行为变化
后端路由注册变化：新增 terminal 和 settings 两个路由模块，app.py 需更新
前端 API 层架构变化：6 个 API 文件重构为 class 继承模式，所有 store 的 API 调用方式变化
工作流执行引擎行为变化：Skill 阶段从 dry-run 变为真实执行，可能影响执行时间和错误处理

Sources & Research

需求文档：docs/brainstorms/2026-06-12-frontend-productization-requirements.md
前端构建配置：src/agentkit/server/frontend/vite.config.ts、package.json
工作流编辑器：src/agentkit/server/frontend/src/components/workflow/FlowCanvas.vue（拖拽断裂点在第 96-110 行）
进化仪表盘：src/agentkit/server/frontend/src/components/evolution/MetricsChart.vue（原生 SVG 实现）
筛选 bug：src/agentkit/server/frontend/src/views/EvolutionView.vue（第 55-57 行）
后端工作流执行：src/agentkit/server/routes/workflows.py（skill/parallel dry-run 在第 378-387 行）
后端进化推送：src/agentkit/server/routes/evolution_dashboard.py（_broadcast_event 未被调用）
后端 KB 管理：src/agentkit/server/routes/kb_management.py（文档列表/删除/同步端点缺失）
PTYSession：src/agentkit/tools/pty_session.py
ShellTool 白名单：src/agentkit/tools/shell.py（_SAFE_COMMAND_PREFIXES 和 _is_dangerous()）
配置热重载：src/agentkit/server/app.py（_on_config_change 第 242-336 行）
现有测试模式：tests/unit/server/test_workflow_routes.py、test_evolution_dashboard.py、test_kb_management.py

30 KiB Raw Blame History Unescape Escape

Summary

Problem Frame

Requirements Traceability

Key Technical Decisions

High-Level Technical Design

Implementation Units

U1. 工作流编排器核心修复

U2. 工作流撤销/重做

U3. 工作流执行动画

U4. 工作流执行历史与 Skill 真实执行

U5. ECharts 图表替换与筛选修复

U6. 进化仪表盘实时 WebSocket 推送

U7. 全局概览页与用量统计面板

U8. 知识库上传数据回填修复

U9. 知识库文档管理与检索增强

U10. 终端 API 实现

U11. 设置 API 实现

U12. 前端基础设施改进

Scope Boundaries

Open Questions

Risks & Dependencies

System-Wide Impact

Sources & Research

30 KiB

Raw Blame History