Qavor：一个能跑、能观测、能扩展的开源 AI Agent 工作台

为什么需要一个 Qavor

你大概也经历过这几件事：

调通一个大模型对话很快，但真要让它连上你自己的文档、调一个外部 API、再串成多步任务，代码就开始失控------认证、上下文、流式、重试、工具调度，全是坑。
用现成的低代码平台能搭出 demo，但要改一个检索策略、加一个私有工具、看清楚 Agent 到底调了哪一步，平台反而成了天花板。
自己从零搭一套 Agent 运行时，光是"异步队列 + 流式推送 + 链路追踪"这三件事，就能耗掉一个周末还不一定稳。

Qavor 想做的是：给你一套已经能跑起来的、结构清晰的全栈 Agent 底座。你不需要从轮子造起，也不必被某个封闭平台的边界卡住------模型、知识库、工具、Skill、MCP 都在里面，而且每一步执行都能在界面上看见。

Qavor 是什么

一句话：Qavor 是面向开发者的 AI Agent 构建、扩展、运行与观测平台。

它既不是单纯的聊天界面，也不是一堆散落的脚手架。你能在同一个项目里：

接入多家大模型（OpenAI 兼容协议统一抽象），按 ID 绑定给不同 Agent 和知识库；
用可视化界面编排 Agent，挂载工具、MCP Server 和 Skill；
建 RAG 知识库，把文档解析、分块、向量化、混合检索、重排串成流水线；
在对话里流式运行 Agent，并实时查看它的思考、工具调用和完整执行链路（Trace）；
把任务丢进异步队列，断线可恢复、可取消、可继续。

当前采用单实例管理员模式，适合团队内部开发、Agent 原型验证，以及 AI 应用基础设施的学习与研究。

核心能力

1. 真·Agent 编排，不是聊天壳子

基于 CloudWeGo Eino 的 Agent 运行时，支持子智能体（Subagent）、审批中断（Approval）、工具错误恢复、运行中向用户追问（AskUser）。对话支持流式输出、请求排队、取消、继续和引导（steer），后台任务通过断点（CheckPoint）持久化，断线后还能恢复。

场景：你让 Agent「先查知识库，再调用内部接口核对库存，最后生成报告」------它能一步步跑完，而不是只回一句文本。

Agent 对话页:流式输出与工具调用过程实时可见

2. 知识库 RAG：混合检索 + 重排

文档上传后进入流水线：MinIO 存原文件 → Redis Stream 解析队列 → Python 解析（含 RapidOCR 图片识别）→ 分块（默认 800 tokens / 重叠 100，支持层级与 FAQ 预设）→ Embedding → 写入 pgvector。

问答时走混合检索 ：向量召回（pgvector）+ 关键词召回（pg_trgm / ILIKE），用 RRF 融合 ，再经 Rerank 重排 ，最后按相似度阈值过滤、组装 Prompt、交 LLM 生成回答。TopK、阈值、RRF 权重都可在知识库或全局 rag-settings 中调。

场景：把公司 Wiki、产品手册、FAQ 喂进去，做成内部问答机器人；检索质量不够时，直接调参数，不用改代码。

知识库文档管理:上传、解析状态、分块与入库一目了然

3. 全链路可观测：Agent 在你眼前思考

这是 Qavor 最不一样的地方。通过 Eino 全局回调采集 LLM / Tool / Retriever / Agent 节点调用，落库成 Trace 记录与 Span，前端提供 Trace 列表与详情视图，按 parent_span_id 组装成调用树。

你不再靠「猜」排查问题------哪一步慢、哪个工具报错、检索召回了什么片段，都摊在界面上。还内置 RAG 评估：上传或自动生成数据集，后台跑 P@10、R@10、MRR、NDCG@10、MAP@10 指标，用数据说话而不是靠感觉。

链路追踪详情:LLM / 工具 / 检索节点逐级展开，调用链清晰可见

链路追踪列表:按时间浏览每一次运行的执行记录

4. 工具生态：MCP + Skill + 内置工具

内置工具 ：query_kb（知识库检索）、web_search（Tavily/Brave 联网搜索）、calculator、current_time、ask_user 等，统一走 tool.Registry 注册表。
MCP：管理 stdio / SSE 两种传输的 MCP Server，支持测试连接、刷新工具、启停工具，按 Agent 配置白名单预热。
Skill ：从文件系统加载 SKILL.md + 脚本，支持依赖校验、动态激活、导入导出，还能从 GitHub 远程仓库拉取；运行时经 SkillsMiddleware 暴露为工具。

场景：你的 Agent 今天要查数据库、明天要发 Webhook，挂上对应 MCP 或 Skill 即可，工具调用全程被 Trace 记录。

工具与扩展:内置工具、MCP Server 与 Skill 统一管理

5. 记忆系统：短期 + 长期

短期记忆：Redis 存消息缓冲与会话状态，结合 LLM 摘要，随会话生命周期裁剪。
长期记忆 ：LLM 从对话中抽取用户画像 / 偏好 / 决策 / 项目事实，存入 long_term_memories 表，下次对话注入 System Prompt。
上下文管理器：组合历史消息 + 短期 + 长期记忆，按上下文窗口（MaxTokens 32768 / ReserveTokens 4096）裁剪后注入。

场景：Agent 记得「用户是后端工程师、偏好 Go、正在做 RAG 项目」，后续对话不用反复交代背景。

6. 异步执行与实时流式

对话和 Agent Run 走 Redis Stream 队列 + Worker 池，长任务不阻塞 HTTP；执行进度经 Redis Pub/Sub 事件总线，通过 SSE 实时推到前端。SSE 带心跳、并发限制（每用户 5 连接）和空闲清理。

7. 知识导图

基于知识库文件用 LLM 生成思维导图，并支持 diff 查看------快速把握一份大文档的结构。

8. 数据总览

仪表盘汇总 Agent、知识库、工具调用与活跃情况，系统运行状态一眼可见（见本文明首「数据总览」配图）。

技术栈

层次	技术
后端语言	Go 1.25.5
HTTP 服务	Gin 1.12.0
Agent 框架	CloudWeGo Eino
ORM	GORM 1.31.2
前端	Vue 3.5+、Vite 8、Pinia 3
UI 与可视化	Ant Design Vue、ECharts、G6、Sigma.js
主数据库	PostgreSQL + pgvector
队列与运行状态	Redis Streams
对象存储	MinIO
文档解析（可选）	Python、Docling、RapidOCR、PyMuPDF
日志	Zap + Lumberjack

模型接入

模型接入是第一步，Qavor 提供统一的模型管理界面，维护供应商、连接参数与能力，并支持远程拉取模型列表与连接测试。

模型管理:统一维护供应商、连接参数与模型能力，按 ID 绑定给 Agent 与知识库

架构一览

#mermaid-svg-Fs8Lm9cXrkjcSiW0{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .error-icon{fill:#552222;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .marker.cross{stroke:#333333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 p{margin:0;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .cluster-label text{fill:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .cluster-label span{color:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .cluster-label span p{background-color:transparent;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .label text,#mermaid-svg-Fs8Lm9cXrkjcSiW0 span{fill:#333;color:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node rect,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node circle,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node ellipse,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node polygon,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .rough-node .label text,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node .label text,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .image-shape .label,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .icon-shape .label{text-anchor:middle;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .rough-node .label,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node .label,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .image-shape .label,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .icon-shape .label{text-align:center;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node.clickable{cursor:pointer;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .arrowheadPath{fill:#333333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .cluster text{fill:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .cluster span{color:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 rect.text{fill:none;stroke-width:0;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .icon-shape,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .icon-shape p,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .icon-shape .label rect,#mermaid-svg-Fs8Lm9cXrkjcSiW0 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Fs8Lm9cXrkjcSiW0 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} HTTP / SSE
Web UI

Vue 3 + Vite
API Server

Gin
单实例认证
Agent Runtime

CloudWeGo Eino
RAG / 知识库
Tools / MCP / Skills
Trace / Dashboard
Redis

Run Queue / Streams
PostgreSQL
PostgreSQL

pgvector
Redis

文档任务队列
MinIO

文件与解析产物
Python Parser

Docling / RapidOCR
MCP Servers

后端以 internal/app/app.go 统一装配，业务按 API → Service → Repository 分层；Agent、RAG、队列、Skill、MCP、Trace 各自保留独立运行模块。完整目录与数据流见 docs/ARCHITECTURE.md。

谁适合用 Qavor

想做 AI 应用的开发者：需要一套能本地跑、能改、能观测的 Agent 底座，而不是黑盒平台。
研究 RAG / Agent 可观测性的同学：内置混合检索、重排与 Trace，适合做实验和写案例分析。
小团队内部工具：搭客服知识库、文档问答、自动化工作流，单实例部署够用。
学习全栈 AI 工程的读者：Go 后端 + Vue 前端 + 向量库 + 队列 + 链路追踪，一个项目看全栈实践。

30 秒快速开始

bash 复制代码

# 1. 获取代码
git clone git@github.com:6moran/Qavor.git
cd Qavor

# 2. 准备配置（PostgreSQL 需先启用 pgvector 与 pg_trgm）
cp configs/config.yaml.example configs/config.yaml
cp .env.example .env
#   填入 POSTGRES_* / REDIS_* / MINIO_* / 管理员账号 / JWT_SECRET

# 3. 启动后端（默认 :8080）
go run ./cmd/server

# 4. 启动前端（默认 :5173）
cd frontend && pnpm install && pnpm dev

打开 http://localhost:5173，用配置的管理员账号登录，先配模型、建 Agent、建知识库，再到对话页验证。完整步骤见 README.md。

登录页:单实例管理员模式，本地一键起

想参与进来

Qavor 仍在活跃迭代（RAG 优化、Trace 体验、CI/CD、OCR 引擎配置等都在路上）。无论你是想提 Issue、修 Bug、补文档，还是贡献一个 Skill / MCP 接入示例，都欢迎：

提 Issue 反馈问题或想法
提交 PR（建议先开 Issue 对齐方向）
在 Discussions 里分享你的使用场景

许可证

Qavor 采用 Apache License 2.0（Apache-2.0） 开源协议。你可以自由使用、修改、分发本项目代码，

包括商业用途，须遵循许可证条款（保留版权与许可证声明、注明变更、包含 NOTICE 等）。

完整条款见仓库根目录 LICENSE 文件。

链接

仓库：https://github.com/6moran/Qavor
架构设计：docs/ARCHITECTURE.md
模型接入指南：docs/model_integration_guide.md
完整 README：README.md