# 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 管理界面**，让非技术用户能够：
1. **一键完成平台安装与配置**（无需接触终端）
2. **通过表单可视化创建/编辑智能体**（无需编写 YAML）
3. **通过对话框直接使用智能体**（无需命令行）
4. **查看运行历史、费用与系统状态**（透明可观测）

### 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，暂不解析）
- **移除** — 从知识体中取消登记（不删除原始文件）
- **一键加入全部** — 将根目录下所有支持格式的文件批量加入

**文件解析流程（加入时触发）：**
1. PDF 文件 → 调用 `extract_pdfs.py` 逻辑提取纯文本，存入 `processed/` 子目录
2. TXT/MD/DOCX/HTML → 直接读取文本，存入 `processed/`
3. 解析进度以进度条实时展示（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（可用核心）
1. 安装向导（环境检测 + 提供商配置 + 启动）
2. 智能体列表 + 简单创建表单（对话助手类型）
3. 对话界面（流式输出）
4. 提供商管理页

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

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

### Phase 3 — 进阶体验
9. 实例管理（一个模板多个域）
10. 配置导入/导出
11. 版本历史 + 回滚
12. 暗色模式 + 多语言

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

---

## 八、开放问题（待决策）

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