从零开始做一个AI Agent（十四）前端工作台：资料管理、Agent 任务、Trace、历史和健康状态

从零开始做一个 AI Agent：以 Java Web RAG 学习助手为例

🎯本文是一套面向技术博客专栏的完整教程。它不是只讲概念，而是以当前项目为真实案例，从一个最小后端 API 出发，逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。

🎯用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引；用户提交学习任务后，Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用，并把执行过程展示给前端。

第 14 篇：前端工作台：资料管理、Agent 任务、Trace、历史和健康状态

14.1 前端工程结构

text 复制代码

frontend/
  index.html
  package.json
  vite.config.ts
  src/
    main.ts
    App.vue
    styles.css
    types.ts
    services/api.ts

14.2 Vite 代理

frontend/vite.config.ts 配置：

ts 复制代码

server: {
  proxy: {
    '/api': {
      target: 'http://127.0.0.1:8000',
      changeOrigin: true,
    },
  },
}

这样前端可以直接请求：

text 复制代码

/api/documents
/api/agent/run

不需要在业务代码里写死后端地址。

14.3 main.ts

前端入口：

text 复制代码

创建 Vue 应用
注册 Element Plus
加载全局样式
挂载 App.vue

14.4 TypeScript 类型

文件：

text 复制代码

frontend/src/types.ts

主要类型：

text 复制代码

DocumentRead
ChunkRead
CitationRead
ChatAskRequest
ChatAskResponse
AgentRunRequest
AgentPlanStep
AgentStep
AgentVerification
AgentSuitability
AgentToolCall
AgentRunResponse
AgentTool
AgentRunListItem

这些类型要和后端 Pydantic Schema 保持一致。当前文件中 ChunkRead 有重复定义，后续可以清理为单一定义，避免维护成本。

14.5 API 客户端

文件：

text 复制代码

frontend/src/services/api.ts

统一请求函数 apiFetch 处理：

text 复制代码

默认 GET
JSON Content-Type
FormData 上传不手动设置 Content-Type
非 2xx 抛 Error
204 返回 undefined

封装的 API：

text 复制代码

fetchDocuments
uploadDocument
deleteDocument
askQuestion
createAgentRun
fetchAgentTools
fetchAgentRuns
fetchDocumentChunks
reindexDocument
fetchHealth
fetchAgentRunDetail

14.6 App.vue 状态设计

核心状态：

text 复制代码

activeView
documents
runs
tools
selectedRun
selectedDocument
selectedChunks
healthStatus
chatForm
agentForm
chatResponse
agentResponse

视图：

text 复制代码

documents
chat
agent
history

14.7 资料管理页

功能：

text 复制代码

显示 LLM / embedding / vector-store 健康状态
上传资料
查看资料列表
查看 indexed / failed / processing 状态
打开 chunks 抽屉
触发 reindex
删除资料

Chunks 抽屉展示：

text 复制代码

chunk id
source_path
source_title
chunk_type
embedding_status
embedding_model
embedding_error
metadata_json
content

这对调试知识库非常重要。

14.8 Chat 页

功能：

text 复制代码

选择问题类型
输入问题
调用 /api/chat/ask
展示 answer
展示 citations
保留 session_id

它是学生友好的入口，但底层已经走 Agent run。

14.9 Agent 任务页

功能：

text 复制代码

选择 task_type
设置 top_k
设置 max_steps
输入 task
调用 /api/agent/run
展示 answer
展示 plan
展示 steps
展示 tool_calls
展示 citations
展示 verification
展示 memory

这是整个项目最核心的工作台。

14.10 Trace 调试视图

前端展示两类 Trace：

text 复制代码

steps：Agent 做了哪些动作
tool_calls：每个工具怎么调用、输入是什么、输出摘要是什么

并通过 helper 函数解释：

text 复制代码

toolReason
toolImpact
stepImpact
verificationReview

这让非后端开发者也能理解 Agent 的执行过程。

14.11 History 页

功能：

text 复制代码

展示历史 Agent runs
按创建时间倒序
打开 run 详情
展示 answer、steps、tool_calls、memory

这让 Agent 不再是"一次性调用"，而是可回放、可审计的执行系统。

14.12 样式设计

文件：

text 复制代码

frontend/src/styles.css

核心布局：

text 复制代码

app-shell
sidebar
main
topbar
workspace
panel
two-column
trace-box
json-block
health-grid

这个前端更像一个操作台，而不是营销页。对 Agent 项目来说，调试和可观测性比装饰更重要。

本系列总目录

1. 项目总览：从普通问答到课程学习 Agent
2. 技术栈和工程结构：FastAPI、Vue、SQLite、RAG、Agent Harness
3. 后端基础设施：配置、数据库、模型和 Schema
4. 资料上传：文件存储、文档记录和重建索引
5. 文档解析：PDF、Word、PPT、Markdown、代码文件如何进入系统
6. 文本切块：chunk、metadata、语义类型和 embedding 状态
7. 检索系统：关键词检索、向量检索、query rewrite 和 rerank
8. LLM 与 Embedding Provider：stub、OpenAI-compatible API 和本地模型接入
9. Chat 问答入口：兼容普通问答，同时接入 Agent 主链路
10. Agent Harness：一次 Agent run 的生命周期
11. Planner、Executor 与 Tool Registry：Agent 如何规划和调用工具
12. Agent 校验、安全边界与资料不足处理
13. Agent 记忆：短期上下文、长期学习画像和推荐下一步
14. 前端工作台：资料管理、Agent 任务、Trace、历史和健康状态
15. 测试、局限和演进：从教学项目走向生产级 Agent SaaS
16. 技术细节复现
17. 附录一：SQLite与SQLAlchemy
18. 附录二：接入大模型
19. 附录三：配置ollama本地大模型/deepseek线上大模型
20. 附录四：Agent Harness API详解
21. 附录五：Agent 工具注册表详解
22. 附录六：工程化 Agent思维
23. 附录七：安装embedding模型详解
24. 附录八：本项目为啥不用LangChain
25. 附录九：UI界面详解
26. 附录十：整体核心流程详解
27. 附录十一：项目中的相关注解
28. 附录十二：手把手带你运行项目