LambdAgent PaaS 本地管理网页 — 产品需求文档

文档版本: 1.0
日期: 2026-05-19
面向读者: 产品 / 开发团队

一、背景与目标

1.1 背景

LambdAgent PaaS 目前的使用方式以命令行（CLI）和 YAML 文件为主：

安装需要执行 ./setup.sh、配置 .env 文件
创建智能体需要手写 YAML 配置
运行智能体通过 agentpaas run ag_xxx "输入" 等命令

这套流程对有编程背景的用户友好，但非计算机专业的使用者面临明显门槛：不会用终端、不懂 YAML 格式、不知道如何管理 API Key。

1.2 目标

提供一个本地运行的 Web 管理界面，让非技术用户能够：

一键完成平台安装与配置（无需接触终端）
通过表单可视化创建/编辑智能体（无需编写 YAML）
通过对话框直接使用智能体（无需命令行）
查看运行历史、费用与系统状态（透明可观测）

1.3 范围

包含: 本地单机部署下的 Web UI（后端接入现有 agentpaas REST API）
不包含: 云端 SaaS、多用户协作、移动端 App

二、目标用户

用户类型	描述	典型需求
领域专家	医疗、法律、金融等专业人员，会使用电脑但不懂编程	快速创建垂直领域问答智能体、上传知识库
企业内部用户	行政、运营、销售，需要在内网使用 AI 助理	开箱即用的对话界面，不需要了解底层
科研人员	有一定技术背景，但希望聚焦业务而非运维	可视化配置 + 查看执行轨迹
学生/课堂使用	初学者，跟随教程进行实验	安装向导引导 + 简单的智能体 Demo

三、用户旅程概览

首次使用
  └─→ 安装向导（3步）
        ├─ 环境检测（Python/Docker）
        ├─ 选择 LLM 提供商 + 填写 API Key
        └─ 一键启动服务 → 进入主界面

日常使用
  ├─ 仪表盘：系统状态 + 最近运行
  ├─ 智能体管理：创建 / 编辑 / 删除
  │   └─ 实例管理：一个模板，多个领域实例
  ├─ 对话界面：选择智能体，发消息，看回复
  └─ 历史 & 费用：查看过往运行与 Token 消耗

四、功能模块需求

4.1 安装向导（首次启动）

触发条件: 本地服务从未配置（无 ~/.agentpaas/config.json 或服务未启动时打开 UI）

步骤 1 — 环境检测

自动检测并显示：Python 版本（≥3.10？）、Docker 是否可用
提供两种安装路径选择：Python 模式 / Docker 模式
若环境不满足，给出具体修复提示（含安装链接）

步骤 2 — 配置 LLM 提供商

卡片式展示支持的提供商：
- 无需 API Key: Claude Code（Max Plan）、Ollama 本地
- 需要 API Key: 阿里云 DashScope（通义千问）、Anthropic、DeepSeek、OpenAI、智谱、Moonshot
每个提供商显示：名称、简介、费用说明
选中后弹出 API Key 填写框，有格式校验（如 sk- 前缀）
填写后自动测试连通性，显示成功/失败

步骤 3 — 启动服务

执行 agentpaas serve 启动后端（展示进度条 + 日志）
成功后跳转到主界面
提供"保存配置并跳过测试"的快速选项

4.2 主仪表盘

路由: /dashboard
对应后端: GET /api/v1/status、GET /api/v1/metrics

显示内容

区块	内容
服务状态	后端是否在线、版本号
智能体概览	总数、活跃数、本周新增
今日运行	运行次数、成功率、平均耗时
Token 消耗	今日/本月输入+输出 Token（折线图）
最近运行	最近 5 次运行的智能体名称、输入摘要、状态、时间
提供商状态	已配置的 LLM 提供商连通性指示灯

4.3 智能体管理

路由: /agents
对应后端: GET/POST/PUT/DELETE /api/v1/agents

4.3.1 智能体列表

卡片/表格双视图切换
每张卡片显示：名称、描述、模型提供商、标签、最近运行时间
支持按名称搜索、按标签筛选
快捷操作：直接对话、编辑、删除

4.3.2 创建智能体（向导式，替代 YAML）

"基础设置"标签页

名称（必填）
描述
标签（多选输入）
环境（生产/测试）

"模型配置"标签页

提供商下拉（仅展示已配置的）
模型名称下拉（根据提供商动态加载可选模型）
Temperature 滑块（0.0 – 1.0）
最大 Token 数（数字输入）

"智能体类型"标签页

类型单选：
- 对话助手（ConversationLam）— 保持完整会话历史
- ReAct 智能体（Loop）— 工具调用 + 多步推理
- 流水线（Compose）— 多智能体串联
- 多智能体群聊（GroupChat）— 多角色讨论
按选择类型展示对应配置项（如 ReAct 的 maxSteps、GroupChat 的角色列表）

"系统提示词"标签页

富文本编辑器输入 systemPrompt
内置模板选择（通用助手、文档问答、代码审查、数据分析）
字符数实时统计

"工具与知识库"标签页（选填）

MCP 工具：填写服务器 URL，点击"发现工具"自动列出可选工具
RAG 知识库：上传文档（PDF/TXT/DOCX），自动建索引
本地工具：搜索/终止/用户自定义脚本

"高级设置"标签页（可收起）

执行引擎：递归模式 / CEK Machine（CEK 有成本监控和循环检测）
内存策略：无 / 本地滚动窗口（可设大小）
沙箱：关闭 / 宽松 / 严格
运行时最大并发数

预览与保存

点击"预览配置"：展示等价的 YAML（面向进阶用户，只读）
点击"保存"：调用 POST /api/v1/agents 创建
支持"保存并立即对话"

4.3.3 编辑智能体（已实现）

路由: /agents/:agentId/edit
对应后端: GET /api/v1/agents/{id}、PUT /api/v1/agents/{id}

入口: 智能体列表页每张卡片右上角的设置（⚙）按钮

表单结构（6 个标签页，与从模版导入一致）:

标签页	字段
基本设置	名称、描述、智能体类型、工作目录（agent_dir）
模型配置	提供商、模型、Temperature、Max Tokens、Base URL
行为配置	最大步数、工具超时、思考超时
记忆 & 运行时	记忆开关/大小/TTL、执行引擎、费用上限
工具列表	mcp.localTools 可编辑标签列表
系统提示词	systemPrompt 多行文本

工作目录（agent_dir）字段说明:

绑定到 agentexample/ 下的某个智能体目录（如 agentexample/research67）
绑定后执行时自动创建 workspace/run_* 子目录，工具写入的文件保存于此
未绑定时不创建 workspace，生成的文件无法通过 UI 下载

保存行为:

后端自动递增版本号（current_version + 1），配置不变时不创建新版本
agent_dir 变更同步写入 agents 表（不受版本控制，立即生效）
保存成功后跳转到该智能体的对话界面（/chat/:agentId），新配置立即生效

4.3.5 从模版导入（已实现）

路由: /agents/import
对应后端: GET /api/v1/templates、GET /api/v1/templates/{id}

背景: 项目 agentexample/ 目录下存放着多个预置智能体模版（YAML 配置），用户可以以此为基础快速创建实例，无需从头填写每项配置。

两步流程:

第一步 — 选择模版

后端扫描 agentexample/ 下各子目录的 agent-config.yml / orchestrator.yml，返回模版列表
前端以 4 列卡片网格展示所有模版
每张卡片显示：名称、描述摘要（最多 2 行）、提供商色标（anthropic=紫、dashscope=蓝、openai=绿、ollama=灰）、模型名、工具标签（闪电图标）、记忆标签（数据库图标）
选中的卡片高亮（蓝色边框 + 对勾）
选中后自动加载模版完整配置（GET /api/v1/templates/{id}）

第二步 — 自定义配置（3 个标签页）

标签页	字段	来源
基本设置	智能体名称（必填）	用户输入
模型配置	提供商下拉、模型下拉、Temperature、Max Tokens	模版预填，可修改
系统提示词	systemPrompt 多行文本框	模版预填，可修改

模型配置中，提供商切换时模型列表动态更新（MODEL_MAP 内置各提供商可选模型）
点击"导入并创建"：以模版配置为基础，合并用户修改，调用 POST /api/v1/agents 创建
创建成功后自动跳转至该智能体的对话界面 /chat/{agent_id}

后端模版发现规则:

首先查找 {CWD}/agentexample/，若不存在则逐级向上查找（最多 6 层）
每个子目录若包含 agent-config.yml 或 orchestrator.yml 则识别为一个模版
返回的 summary 字段：id（目录名）、name、description、type、provider、model、has_tools、has_memory

入口: 智能体列表页（/agents）右上角"从模版导入"按钮

4.3.4 实例管理（高级功能）

概念说明提示框: "一个智能体模板可以为不同领域（如航运、金融）创建独立实例，每个实例有独立知识库，互不干扰。"

在智能体详情页新增"实例"子页
展示该模板下的所有实例列表（对应 instance_dir）
新建实例：选择模板、填写实例名、选择知识库目录
每个实例可以独立发起对话

4.4 对话界面

路由: /chat/:agentId（或 /chat/:agentId/instance/:instanceId）
对应后端: POST /api/v1/agents/{agent_id}/run（流式）

布局

┌─────────────────────────────────────────┐
│  [智能体名称]  [模型]  [会话设置]         │  顶部栏
├──────┬──────────────────────────────────┤
│ 历史 │                                  │
│ 会话 │         消息区域                  │
│ 侧边 │   (用户消息 / 智能体回复气泡)      │
│      │                                  │
│      ├──────────────────────────────────┤
│      │  [文本输入框]    [发送]  [停止]   │  输入区
└──────┴──────────────────────────────────┘

功能点

流式输出: 后端 SSE 流逐字显示回复（/run 流式模式）
思考步骤展示: ReAct 智能体的工具调用过程折叠展示（点击展开）
停止生成: 用户可随时终止
会话持久化: 当前浏览器标签页内保持多轮对话历史（ConversationLam 模式下自动携带历史）
新建会话 / 清空历史
输入建议: 为每个智能体配置 3–5 条示例问题，首次打开展示
文件上传: 可上传文件作为 RAG 输入（若智能体启用了 RAG）
复制回复 / 点赞点踩（记录到 trace）

4.5 运行历史

路由: /runs
对应后端: GET /api/v1/agents/{agent_id}/runs、GET /api/v1/traces/{run_id}

列表页

筛选：按智能体、按时间范围、按状态（成功/失败/超时）
列：运行 ID、智能体名称、输入摘要、状态、耗时、Token 消耗、时间
分页

详情页（Trace 查看器）

输入 / 输出完整文本展示
执行轨迹树: 以时间线 + 树形结构展示 Beta-reduction 步骤
- 每个节点：构造名（Lam/Loop/Tool 等）、耗时、Token 数
- 工具调用节点：展示调用参数和返回值
- CEK 引擎：展示每步成本累积
成本明细：输入 Token × 单价 + 输出 Token × 单价
一键"以相同输入重新运行"

4.6 提供商与 API Key 管理

路由: /settings/providers
对应后端: agentpaas provider 相关 CLI（封装为 API）

已配置提供商卡片：名称、状态灯（可用/不可用）、已配置模型列表
添加提供商：选择类型 → 填写 API Key → 测试连通性 → 保存
支持 Ollama 特殊配置（本地地址、已下载模型列表）
Claude Code Max Plan 一键启用（无 Key，检测本地 Claude Code 安装）
API Key 显示为脱敏格式（sk-xxx...xxx），支持显示/隐藏切换
删除提供商（有确认弹窗，提示受影响的智能体数量）

4.7 费用与用量监控

路由: /settings/usage
对应后端: GET /api/v1/billing/usage、GET /api/v1/metrics

时间范围选择（今日 / 本周 / 本月 / 自定义）
折线图：Token 消耗趋势（分输入/输出）
柱状图：各智能体用量占比
明细表：按时间、智能体、提供商分组
费用估算：Token 数 × 各提供商单价（内置价格表，可手动修改）
用量预警：设置 Token 上限，超过时在界面显示警告

4.8 系统设置

路由: /settings

设置项	说明
服务端口	修改本地 API 服务端口（默认 8000）
主题	亮色 / 暗色
语言	中文 / English
数据目录	本地数据库 & 工作区存储路径
导出配置	将所有智能体配置导出为 ZIP（含 YAML）
导入配置	从 ZIP 批量导入智能体
备份与恢复	手动备份 `agentpaas.db`
日志查看	内嵌展示最近 500 行服务日志（支持过滤）

4.9 对话持久化与历史恢复（已实现）

路由: /chat/:agentId
对应后端: GET /api/v1/agents/{agent_id}/runs

背景: 流式对话端点 /run/stream 原先不写数据库，刷新页面后对话历史丢失。

修复方案:

在 /run/stream 执行前 INSERT INTO runs（状态 running）
执行成功后 UPDATE 写入 output、steps、workspace_path、Token 用量
执行失败后 UPDATE 写入 error 和 status=failed
前端 Chat 页面通过 GET /agents/{id}/runs 在首次加载时还原历史对话气泡
每次 done 事件后调用 queryClient.invalidateQueries(['runs', agentId]) 保持缓存新鲜

数据流: 用户发消息 → SSE 流式推送 → done 事件 → DB 更新 → 下次打开自动还原

4.10 工作区文件浏览与下载

路由: /chat/:agentId（工作区面板内嵌于对话界面）
对应后端: GET /api/v1/agents/{agent_id}/runs/{run_id}/workspace、GET /api/v1/agents/{agent_id}/runs/{run_id}/workspace/{file_path}

背景: 智能体（尤其是 research67、data67、pptagent67）执行后会在 workspace/run_*/ 目录生成文件，但原先没有任何界面可以查看或下载这些文件。

功能点:

后端（agents.py 新增）:

GET /{agent_id}/runs/{run_id}/workspace — 递归列出 workspace 目录下所有文件，返回 [{name, path(相对路径), size, modified}]
GET /{agent_id}/runs/{run_id}/workspace/{file_path:path} — 下载指定文件，含路径穿越防护（os.path.realpath 校验必须在 workspace 目录内）

前端（Chat 页面）:

智能体回复气泡下方，若该次运行有 workspace 文件，显示"📁 工作区文件（N 个）"折叠面板
展开后列出文件名、大小；点击文件名触发带鉴权的 fetch + Blob 下载

安全: 只允许下载已认证 tenant 所拥有 run 的 workspace 文件；服务端校验路径在 workspace 目录内。

4.11 智能体记忆管理界面

路由: /chat/:agentId（记忆面板内嵌于对话界面右侧）
对应后端: GET /api/v1/agents/{agent_id}/memory、DELETE /api/v1/agents/{agent_id}/memory/{key}

背景: 智能体通过 MemoryStore/MemoryRecall 工具写入 ~/.lambdagent/memory.db，但没有界面可以查看或管理。用户无法知道智能体"记住了什么"，也无法清除错误记忆。

功能点:

后端（agents.py 新增）:

GET /{agent_id}/memory — 列出该智能体的所有有效记忆（source = agent_id，过滤过期条目），返回 key、content、tier（working/episodic/semantic）、tags、created_at
DELETE /{agent_id}/memory/{key} — 删除指定记忆条目

前端（Chat 页面）:

对话页头部新增"🧠 记忆"按钮
点击后在右侧展开记忆面板（宽度约 320px，覆盖消息区域右侧）
每条记忆显示：Tier 标签（semantic=蓝/episodic=黄/working=灰）、内容摘要（最多 3 行）、标签 chips、创建时间
点击删除图标删除该条记忆，乐观更新列表
若无记忆，显示空状态提示

4.12 知识体管理

路由: /knowledge、/knowledge/:kbId
对应后端: GET/POST/PUT/DELETE /api/v1/knowledge（新增）
关联脚本: agentexample/qaagent67lambda/scripts/（app.py、build_index.py、wiki_compile.py、search_unified.py、graph_engine.py 等）

背景

现有 QA 智能体（qaagent67lambda、qaagent67、qaagent67lite）已有完整的离线处理流水线：

extract_pdfs.py / extract_docs.py — 批量提取 PDF / DOCX 为纯文本
build_index.py / build_vector_index.py — 构建 BM25 / 向量检索索引
wiki_compile.py — LLM 逐文档理解 → 生成 sources/、entities/、topics/ 三级 Wiki 页面
graph_engine.py — 从 Wiki relations.json 构建实体关系图谱（BFS N跳遍历）
search_unified.py — LambdaRAG v3 四路检索融合（BM25 + 向量 + 图谱 + Wiki）

这些脚本的路径（/home/67/knowledge/maritime/）目前通过 instance.yml 配置，但缺乏 Web 管理界面。本需求将其封装为可通过 Web UI 配置和触发的「知识体」。

4.12.0 参考实现分析（现有服务器部署）

以下分析基于对 http://qa.lambdagent.cn:8080（海事法规）和 http://qa.lambdagent.cn:8084（投标文件）两个在线服务的调研，以及对本地源码的全面阅读（2026-05-27）。

服务器代码位置（qa.lambdagent.cn）：

文件	说明
`/home/67/qademo/app.py`	主应用（本地源：`agentexample/qaagent67lambda/scripts/app.py`）
`/home/67/qademo/deploy_domain.sh`	一键部署新领域的 shell 脚本
`/home/67/qademo/instance.yml.template`	新领域配置模板
`/home/67/knowledge/maritime/`	海事 KB（8080）：1326 文档，BM25+向量+图谱+Wiki
`/home/67/knowledge/clean/`	投标 KB（8084）：49 文档，1527 chunks
`/home/67/knowledge/{domain}/instance.yml`	各领域配置覆盖层

运行方式：每个领域独立 Docker 容器（maritime-qa、clean-qa 等），deploy_domain.sh {domain} 一键启动。

架构优势（Web UI 需保留并集成）：

优势	实现位置	说明
LambdaRAG 四路检索融合	`search_unified.py`	意图分类（6类：fact/process/person/compare/temporal/data）→ 实体提取 → BM25+向量+图谱+Wiki 并行检索 → RRF 融合 → 槽位填充 → 富文本上下文
意图自适应权重	`config.py` weight_profiles	按检测到的意图类型自动切换融合权重（如 temporal 查询 BM25 权重=1.0，compare 查询向量权重=0.8）
Corrective RAG	`search_unified.py` P1-1	检索质量评分不足时自动改写查询并重试，减少无关结果
实体关系图谱	`graph_engine.py`	从 wiki/relations.json 构建邻接表，BFS N跳遍历扩展实体上下文
三层 Wiki 体系	`wiki_compile.py`	sources/（逐文档摘要）/ entities/（命名实体）/ topics/（主题聚合）/ analyses/（即席编译）
A/B 对比面板	`app.py` HTML	5 种检索策略同屏对比（Lite / LambdaRAG / Wiki Only / BM25 Baseline / Direct LLM）
Wiki/RAG 浏览器	`/wiki`、`/rag` 路由	内置知识库内容检视页，可浏览 wiki 页面和搜索原始 chunks
反馈日志	`feedback/query_log.jsonl`	自动记录每次检索的意图、实体、策略，以及 missing_queries 检索盲区
实例配置体系	`instance.yml` + `config.py`	无需改代码即可通过 YAML 新增领域（路径/模型/权重/UI文案全部可配）

现有实现的缺口（Web UI 需弥补）：

#	缺口	问题描述	对应 UI 需求
G1	无文件摄入 UI	建库需 SSH 上传文件 + CLI 运行脚本	4.12.1 目录浏览器 + 一键加入
G2	无索引健康监控	不知索引是否最新、有多少文档失败	4.12.2 状态指示器 + 失败文件列表
G3	Wiki 编译无可视化	`wiki_compile.py` 进度只有终端日志	4.12.3 实时进度 + 断点续传控制
G4	Wiki 内部检索质量差	用字符频率（`sum(1 for c in q_chars ...)`）代替 BM25/向量匹配	4.12.2 补充：wiki 搜索改用 BM25 全文检索
G5	5路并行浪费算力	每次查询触发 5 个完整 LLM 调用，即使用户只看 2 个面板	4.12.4 搜索测试：懒加载/按需触发各模式
G6	无流式输出	答案完整生成后才推送（2s 轮询），体验延迟高	4.12.4 搜索测试：接入 SSE 流式输出
G7	对话历史是 JSON 文件	无搜索、无用户隔离、重启丢失、线程写入竞争	4.12.4 历史：写入 agentpaas.db
G8	无检索权重可视化调优	instance.yml 手写权重，无法实时观测效果	4.12.4 新增：权重滑块 + 实时效果对比
G9	无增量文档更新	新增文档需全量重建索引（BM25 重扫全库）	4.12.2 增量更新 Job
G10	无评测集成	`generate_questions.py`/`analyze_results.py` 存在但未接入 UI	Phase 4 评估面板
G11	Analyses 目录无管理	即席编译的 wiki analyses/ 无限积累，无去重/归档	4.12.3 Wiki 目录 → analyses 管理子面板
G12	领域创建需手工	新领域需 SSH + 编辑 instance.yml + 运行脚本	4.12.1 新建知识体向导（GUI 版 deploy_domain.sh）

4.12.1 知识体列表页（`/knowledge`）

布局： 卡片网格，每张卡片代表一个知识体。

每张卡片显示： | 字段 | 说明 | |------|------| | 名称 | 用户自定义，如"航运规范"、"法律合同" | | 根目录 | 本地文件夹路径（如 /data/maritime） | | 文档数量 | 已加入的文件数 | | 索引状态 | 未索引 / BM25 已就绪 / 向量已就绪 / Wiki 已生成 | | 最近更新 | 上次构建时间 |

操作：

新建知识体（右上角按钮）→ 弹窗填写名称 + 根目录路径
进入详情（点击卡片）
删除（卡片菜单）

4.12.2 知识体详情页（`/knowledge/:kbId`）

详情页分为四个子标签：文件管理 / 索引构建 / Wiki 目录 / 搜索测试

标签 1 — 文件管理

目录浏览器：

以树形/列表展示根目录下的所有文件（递归）
支持的格式：PDF、TXT、DOCX、MD、HTML、CSV
每个文件显示：文件名、大小、修改时间、加入状态（已加入 ✅ / 未加入）
全选 / 按格式批量选择（如"全选 PDF"）

文件操作：

加入知识体 — 将选中文件登记到知识体（写入后端 DB，暂不解析）
移除 — 从知识体中取消登记（不删除原始文件）
一键加入全部 — 将根目录下所有支持格式的文件批量加入

文件解析流程（加入时触发）：

PDF 文件 → 调用 extract_pdfs.py 逻辑提取纯文本，存入 processed/ 子目录
TXT/MD/DOCX/HTML → 直接读取文本，存入 processed/
解析进度以进度条实时展示（SSE 流）

标签 2 — 索引构建

展示三种索引的构建状态与操作：

索引类型	说明	对应脚本
BM25 关键词索引	轻量、无需 GPU，适合精确关键词检索	`build_index.py`
向量语义索引	需要嵌入模型，支持语义搜索	`build_vector_index.py`
图谱索引	实体-关系图，支持关联推理	`graph_engine.py`

每种索引的操作面板：

状态指示器：未构建 / 构建中（带进度）/ 已就绪（文档数、构建时间）
构建按钮 — 触发后台 Job，SSE 实时推送进度日志
重建按钮（已就绪时显示）— 全量重新构建
增量更新 — 只处理新加入的文件

构建日志：

展示最近一次构建的实时/历史日志（INFO: 处理 128/1326 ...）
错误文件高亮显示（带原始报错）

标签 3 — Wiki 目录

Wiki 是什么： 由 LLM 逐文档阅读后自动生成的结构化知识页面，分四层（wiki_compile.py 输出）：

sources/ — 每个原始文档的摘要页（1文档 = 1 页）
entities/ — 抽取出的实体（人名、公司、术语、地名等）及其关系
topics/ — 主题聚合页（将多篇文档的相关内容汇总）
analyses/ — 即席编译生成的临时知识页（查询时按需生成，参见现有 wiki_answer() 逻辑）

Wiki 构建面板：

配置项： | 配置 | 说明 | |------|------| | LLM 提供商 | 选择用于 Wiki 编译的模型（建议 32B+ 或 Claude） | | 编译模式 | 增量（仅处理未编译文档）/ 全量重建 | | 并发数 | 同时处理的文档数（1–8） | | 断点续传 | 默认开启，中断后从 .compile_progress.json 继续（wiki_compile.py 内置支持） |

操作：

开始编译 — 触发后台 Job，对应 wiki_compile.py 逻辑
暂停 / 恢复 — 利用 wiki_compile.py 的 .compile_progress.json 断点机制
进度条：已完成 / 总文档数，预计剩余时间

Wiki 内容浏览器：

左侧树：index.md / sources/ / entities/ / topics/（显示每类页面数量统计）
右侧：Markdown 渲染预览
搜索框（修复 G4）：对 wiki 页面内容进行 BM25 全文检索（不再使用字符频率匹配），结果按相关度排序
每个页面显示"来源文档"反向链接

Analyses 管理子面板（修复 G11）：

列出 analyses/ 下所有即席编译页，显示：文件名（来源查询）、大小、创建时间
操作：归档（移入 topics/）、删除、批量清理（删除 30天前的条目）
显示"去重提示"：内容相似度 >80% 的 analyses 页高亮，建议合并

标签 4 — 搜索测试

提供交互式搜索界面，用于验证知识体质量（参考现有 app.py 的 A/B 对比面板，弥补其 G5/G6/G8 缺口）：

搜索配置：

检索策略：下拉单选（BM25 / 向量语义 / 混合 Rerank / Wiki 全文 / LambdaRAG 四路融合）
- 选择 LambdaRAG 时，显示意图分类结果（检测到的 query type）和每路检索命中数
Top-K 结果数（1–20）
相关性阈值滑块

A/B 对比模式（参考现有 demo，修复 G5）：

切换"对比模式"：页面分为左右两列，各自独立选择检索策略
按需加载：只触发用户选中面板的检索，不后台并行运行所有 5 路（修复 G5 算力浪费）
结果并排展示，便于直观对比不同策略的答案质量

检索权重可视化调优（修复 G8）：

LambdaRAG 模式下展开"权重配置"折叠面板：
- 4 个滑块：BM25 / 向量 / 图谱 / Wiki（各 0.0–1.0）
- 预设方案快速切换：按意图类型（fact / compare / temporal 等）加载推荐权重
- 修改权重后实时重新排序当前结果（前端 RRF 重算，无需再次检索）
"保存为默认"：将当前权重写入知识体配置（更新 instance.yml 等效配置）

流式问答测试（修复 G6）：

输入问题 → 点击"问答测试" → SSE 流式展示 LLM 答案（逐字输出，无需等待完整生成）
答案下方展示引用的 chunks 列表（来源文件 + 相关度分数）

搜索结果展示： 每条 chunk 结果显示：

文档来源（文件名 + 页码/段落）
相关度分数 + 所属检索路径（BM25/向量/图谱/Wiki 哪路命中）
匹配片段，关键词高亮
展开查看原文按钮

历史记录（修复 G7）：

搜索历史写入 agentpaas.db，按知识体隔离，支持搜索和导出
显示最近 100 条（带意图类型、检索耗时、命中文档数）

与智能体联动：

"在智能体中测试"按钮 — 将当前知识体绑定到选定的 QA 智能体，跳转至对话界面

4.12.3 智能体 ↔ 知识体绑定

在智能体编辑页（4.3.3）的"工具与知识库"标签页中：

新增"知识体"下拉选择框，列出所有已建索引的知识体
选中后自动填充 mcp.localTools 中的 KBSearch、KBCreate、KBAdd 工具
并将知识体路径写入智能体配置（kb_dir 字段）

4.12.4 后端 API（新增）

方法	路径	说明
`GET`	`/api/v1/knowledge`	列出所有知识体（含索引状态摘要）
`POST`	`/api/v1/knowledge`	创建知识体（name, root_dir）
`PUT`	`/api/v1/knowledge/:kbId`	更新知识体配置（含检索权重）
`DELETE`	`/api/v1/knowledge/:kbId`	删除知识体
`GET`	`/api/v1/knowledge/:kbId/files`	列出根目录文件树（含加入状态）
`POST`	`/api/v1/knowledge/:kbId/files`	加入文件（触发文本提取）
`DELETE`	`/api/v1/knowledge/:kbId/files/:fileId`	从知识体移除文件（不删原文）
`POST`	`/api/v1/knowledge/:kbId/index`	触发索引构建 Job（type: bm25/vector/graph，mode: full/incremental）
`POST`	`/api/v1/knowledge/:kbId/wiki`	触发 Wiki 编译 Job（mode: incremental/rebuild）
`PUT`	`/api/v1/knowledge/:kbId/wiki/pause`	暂停/恢复 Wiki 编译（写 `.compile_progress.json` 停止标志）
`GET`	`/api/v1/knowledge/:kbId/wiki/tree`	获取 Wiki 文件树（sources/entities/topics/analyses 分组）
`GET`	`/api/v1/knowledge/:kbId/wiki/:path`	获取单个 Wiki 页面内容（Markdown）
`DELETE`	`/api/v1/knowledge/:kbId/wiki/analyses/:name`	删除 analyses/ 下指定即席编译页
`POST`	`/api/v1/knowledge/:kbId/search`	在线搜索测试（返回 chunks + 意图分类 + 各路命中数）
`GET`	`/api/v1/knowledge/:kbId/search/stream`	SSE 流式问答测试（LLM 逐字输出，修复 G6）
`GET`	`/api/v1/knowledge/:kbId/jobs`	查询 Job 状态（索引/Wiki 构建进度 + 失败文件列表）
`GET`	`/api/v1/knowledge/:kbId/feedback`	获取反馈日志（query_log + missing_queries，修复 G10 前期准备）

Job 进度通过 SSE（/api/v1/jobs/{job_id}/stream）实时推送，格式：data: {"progress": 128, "total": 1326, "current_file": "xxx.pdf", "errors": []}。

4.12.5 QA 智能体脚本整合说明

agentexample/qaagent67lambda/scripts/ 中各脚本的对应关系：

脚本	对应 UI 功能	整合方式
`extract_docs.py`	文件管理 → 加入知识体（PDF/DOCX/HTML）	封装为 `kb_service.extract_file(path)`
`build_index.py`	索引构建 → BM25（全量/增量）	封装为 `kb_service.build_bm25(kb_id, mode)`
`build_vector_index.py`	索引构建 → 向量（bge-m3）	封装为 `kb_service.build_vector(kb_id, mode)`
`graph_engine.py`	索引构建 → 图谱（entity relation graph）	封装为 `kb_service.build_graph(kb_id)`
`wiki_compile.py`	Wiki 目录 → 编译（断点续传）	封装为 `kb_service.compile_wiki(kb_id, cfg)`
`search_unified.py`	搜索测试 → LambdaRAG 四路融合	封装为 `kb_service.search_lambda(kb_id, query, weights)`
`search_engine.py`	搜索测试 → BM25 Baseline	被 `search_unified` 调用，也可独立调用
`search_engine_v2.py`	搜索测试 → 向量语义	被 `search_unified` 调用
`config.py`	知识体配置读取	适配器：Web UI 传入 `kb_id`，`config.py` 从 DB 加载路径
`rebuild_index.py`	索引构建 → 全量重建	封装为 `kb_service.rebuild(kb_id)`
`generate_questions.py`	Phase 4：自动生成测试问题集	`kb_service.generate_eval_set(kb_id)`
`analyze_results.py`	Phase 4：评估检索质量报告	`kb_service.analyze_quality(kb_id, eval_set)`

路径动态化（弥补硬编码缺口）： 现有脚本通过 config.py 的 Config 类统一读取路径，Web UI 后端只需在调用前设置 INSTANCE_CONFIG 环境变量（或直接传参），即可让所有脚本使用 DB 中记录的知识体路径，无需修改脚本本身。

五、非功能需求

5.1 本地化部署

UI 作为静态前端，跟随 agentpaas serve 一起启动（内嵌到 FastAPI 的 / 路由）
无需单独安装 Node.js 运行时（构建产物打包为静态文件）
访问地址：http://localhost:8000

5.2 响应性能

页面首次加载 < 2s（本地服务）
对话流式输出首字节 < 500ms

5.3 浏览器兼容

Chrome 100+、Edge 100+、Safari 16+（本地使用场景无需兼容旧版）

5.4 无障碍

关键操作有键盘快捷键（Ctrl+Enter 发送，Esc 停止生成）
错误信息使用中文友好提示，避免暴露技术栈错误

5.5 安全

本地服务默认只监听 127.0.0.1（不对外网暴露）
API Key 不写入前端状态，通过后端 ~/.agentpaas/providers.json 存储
提供"局域网共享模式"选项（需用户主动启用，显示风险提示）

六、技术方案建议

层	建议	理由
前端框架	React 18 + Vite	生态成熟，打包为静态 HTML/JS/CSS
UI 组件库	shadcn/ui + Tailwind	无运行时依赖，bundle 小，支持暗色模式
状态管理	Zustand	轻量，适合中小型应用
流式输出	EventSource（SSE）	接入现有 agentpaas 流式 API
图表	Recharts	React 原生，bundle 合理
后端静态服务	FastAPI `StaticFiles` 挂载 `dist/` 目录	零新增依赖，一个端口服务全部内容
构建集成	`pyproject.toml` 脚本，`pip install` 时触发前端构建	对 Python 用户透明，一行安装

目录结构（建议）

lambdagentpaas/
├── agentpaas/
│   ├── api/
│   │   └── app.py        ← 挂载 /ui 静态文件 + /api 路由
│   └── ...
├── webui/                ← 前端源码
│   ├── src/
│   │   ├── pages/        ← dashboard, agents, chat, runs, settings
│   │   ├── components/   ← AgentCard, ChatBubble, TraceTree 等
│   │   └── api/          ← 封装 fetch 调用 agentpaas REST API
│   ├── package.json
│   └── vite.config.ts
└── webui-dist/           ← 构建产物（git ignore，pip install 时生成）

七、分阶段交付计划

Phase 1 — MVP（可用核心）

安装向导（环境检测 + 提供商配置 + 启动）
智能体列表 + 简单创建表单（对话助手类型）
对话界面（流式输出）
提供商管理页

交付标准: 非技术用户能从零完成"安装 → 创建助手 → 对话"全流程，无需接触终端

Phase 2 — 完整功能

完整的智能体类型支持（ReAct、流水线、群聊）
工具与知识库配置（RAG 上传）
运行历史 + Trace 查看器
费用与用量监控

Phase 3 — 进阶体验

实例管理（一个模板多个域）
配置导入/导出
版本历史 + 回滚
暗色模式 + 多语言

Phase 4 — 知识体管理

知识体列表 + 创建（设置根目录、文件加入）
BM25 / 向量索引构建（整合 qaagent67 脚本）
Wiki 目录编译（整合 wiki_compile.py）
搜索测试界面 + 智能体绑定
QA 脚本硬编码路径修复，统一由 kb_dir 配置驱动

八、开放问题（待决策）

问题	选项	建议
对话历史存储在哪里？	浏览器 localStorage / agentpaas.db	存 DB，跨标签可查
是否支持多用户本地使用？	单用户 / 简单密码保护	Phase 1 单用户，后续加密码锁
YAML 预览是否可编辑？	只读 / 可编辑	Phase 1 只读，防止格式错误困扰新手
前端构建是否内嵌发布包？	每次 pip install 构建 / 预构建产物提交	提交预构建产物，简化安装流程

WEB_UI_REQUIREMENTS.md 36 KB Trvalý odkaz Historie Surový