知识库管理 · LightAIP · frontend-intro-v5

1. 页面概览

1.1 是什么

知识库管理页面（KnowledgeBasePage.vue，约 1266 行）是 LightAIP 的知识文档管理入口，也是 NLQ 智能查数与 RAG 检索的知识底座。页面围绕「目录 → 文档 → 知识块」组织知识：左侧目录树负责分类，中部文档表格管理文档（新建/编辑/删除/版本），底部「知识检索」区对已入库文档做混合检索并高亮命中片段。

目录树：支持多级目录，点击目录过滤文档列表，可新建子目录（名称/上级目录/描述）。
文档管理：支持 text / markdown / html 三种格式，保存时后端自动切分并向量化；可打标签、分页检索、版本管理（回滚）。
知识检索：POST /knowledge/search 混合检索，返回 title、score、目录、版本与高亮片段。
防御式取值：后端未就绪时优雅提示不白屏（loading + alert 错误提示）。

1.2 核心价值

能力	说明
目录分类	多级目录树，点击过滤文档列表
多格式文档	text/markdown/html 直接粘贴，保存即切分向量化
版本管理	每次编辑版本 +1，可查看历史并一键回滚
标签浏览	聚合标签（`GET /knowledge/tags` 服务端全量聚合）；点击后为客户端全量筛选（逐页 100 条拉取全部文档后本地按标签过滤，带进度/取消/上限）
混合检索	语义 + 关键词融合，命中片段高亮

1.3 一句话总结

知识库管理页是 AIP 的知识文档「仓库」：目录管分类、文档管内容、版本管迭代，检索区让知识立即可被 NLQ 查数召回。

2. 访问入口

2.1 路由与菜单

路由路径：/knowledge，路由名 KnowledgeBase，meta.title 为「知识库管理」，requiresAuth: true（注册于 action/web/src/router/index.js 的 Action 栏目子路由）。
菜单入口：Action 栏目左侧边栏「知识库管理」（ActionLayout.vue 第 2 项，位于「数据源管理」之后）。
源码文件：action/web/src/views/KnowledgeBasePage.vue。

2.2 认证与权限

路由级 requiresAuth: true，未登录访问跳 /login。
API 级：经 action/web/src/api/aipClient.js 自动附带 aip_token Bearer；401 时清理 token 并跳登录页。
权限要求：普通登录用户即可访问（页面注释「/knowledge，普通登录用户可访问」），接口挂在 AIP protected 组。

2.3 端口与 API 前缀

端口：18080（AIP 后端）。API 前缀：/aip-api/v1（Vite 开发代理到 18080 并重写为 /api/v1）。

3. 界面布局

知识库管理（页头 + 「刷新」按钮）
└─ 操作结果提示条（alert，右上角「关闭」）
└─ 主体双栏网格（280px + 1fr）
   ├─ 左：目录卡片
   │   ├─ 「全部目录」+ 目录树（缩进多级，点击过滤）
   │   └─ 「+ 新建目录」→ 表单（名称 */上级目录/描述 + 「创建目录」）
   └─ 右：文档列表卡片
       ├─ 工具栏：搜索标题/内容关键字 + 「检索」+「新建文档」
       ├─ 标签行（聚合标签 chip + 「清除过滤」；点选后黄条提示切换为「客户端全量筛选」进度/结果口径）
       ├─ 表格：标题/格式/状态/版本/标签/目录/操作（详情/编辑/版本/删除）
       └─ 分页：「上一页」第 N / M 页「下一页」（客户端全量筛选态下隐藏）
└─ 知识检索卡片
   ├─ 检索输入（placeholder 如：2024年各产品销量...）+ 「检索」
   └─ 结果列表：标题 + score + 目录 + 版本 + 高亮片段

各板块职责：

目录卡片：展示目录树并作为文档过滤条件；内嵌新建目录表单。
文档列表卡片：文档 CRUD、检索、分页与标签浏览的主区域。
知识检索卡片：对全量知识做混合检索，验证入库效果。

4. 交互元素详解

4.1 目录区

控件	含义	操作效果	后端调用
「全部目录」	根过滤项	清空目录过滤，重载文档列表第 1 页	GET /knowledge/documents
目录树项	各目录节点（缩进展示层级）	点击选中过滤该目录下文档	GET /knowledge/documents?directory_id=
按钮「+ 新建目录」/「收起」	展开/收起新建目录表单	切换表单显隐	—
输入「名称 *」	目录名称	必填	POST /knowledge/directories
下拉「上级目录」	父目录选择	空为根目录；下拉按缩进展示	同上（parent_id）
输入「描述」	目录用途说明	选填	同上
按钮「创建目录」	提交建目录	成功后提示「目录"xxx"创建成功」并刷新目录树	POST /knowledge/directories

4.2 文档列表区

控件	含义	操作效果	后端调用
检索输入	标题/内容关键字	回车或点「检索」回到第 1 页重查	GET /knowledge/documents?keyword=
按钮「新建文档」	打开新建弹窗	重置表单（格式默认 text）	—
标签 chip	聚合标签	点击触发客户端全量筛选（逐页 `page_size=100` 拉取全部文档后本地过滤，带进度/取消/上限）；再次点击取消过滤	`GET /knowledge/documents?page=&page_size=100`（循环，带当前 keyword/directory_id）
行内「详情」	打开详情弹窗	展示格式/状态/版本/目录/知识块数/内容/时间	GET /knowledge/documents/:id
行内「编辑」	打开编辑弹窗	预填标题/格式/目录/标签/内容	GET 详情 + PUT /knowledge/documents/:id
行内「版本」	打开版本管理弹窗	版本表 + 「回滚」	GET /knowledge/documents/:id/versions
行内「删除」	删除文档	confirm 确认后删除并刷新	DELETE /knowledge/documents/:id
分页「上一页」「下一页」	翻页	第 N / M 页指示；客户端全量筛选态下隐藏（命中集一次性全展示，分页不再作用其上，避免「第 N/M 页」误导）	GET /knowledge/documents?page=

4.3 弹窗

新建/编辑文档弹窗：标题 *、格式下拉（text（纯文本）/markdown/html）、所属目录下拉、标签（逗号分隔，如 销售,季度,汇总）、内容 * 大框（placeholder「输入文档内容，保存后将被切分并向量化用于检索...」）。提交按钮新建为「创建」、编辑为「保存（版本+1）」。
文档详情弹窗：只读展示格式、状态徽标、版本、目录、知识块数（chunk_count）、标题、标签、内容、创建/更新时间。
版本管理弹窗：版本表格（版本/变更说明/更新时间/操作），选中行可看「vN 内容预览」；当前版本按钮显示「当前版本」，历史版本可「回滚」。

4.4 知识检索区

输入 query 点「检索」（top_k=10），结果卡片展示标题、score（4 位小数）、目录、版本与高亮片段（命中关键字 <mark> 高亮）；空结果显示「未检索到相关内容。」。

5. 后端关联

5.1 API 客户端

本页使用 action/web/src/api/aipClient.js（baseURL /aip-api/v1、timeout 30s、aip_token Bearer、401 跳登录），页面直接调用，无独立 API 文件。

5.2 端点表

方法	路径（前缀 /aip-api/v1）	请求体	用途
GET	/knowledge/directories	—	目录列表（兼容嵌套 children / 扁平 + parent_id）
POST	/knowledge/directories	`{name, parent_id?, description?}`	创建目录
GET	/knowledge/documents	`page, page_size, keyword?, directory_id?`	文档列表（分页）
POST	/knowledge/documents	`{title, format, content, tags?, directory_id?}`	创建文档（返回 chunk_count）
GET	/knowledge/documents/:id	—	文档详情（含 chunk_count）
PUT	/knowledge/documents/:id	`{title, format, content, tags?, directory_id?}`	更新文档（版本 +1）
DELETE	/knowledge/documents/:id	—	删除文档
GET	/knowledge/documents/:id/versions	—	版本列表
POST	/knowledge/documents/:id/versions/:v/restore	—	回滚到指定版本
POST	/knowledge/search	`{query, top_k}`	混合检索
GET	/knowledge/tags	—	聚合标签列表

5.3 关键机制

保存即切分向量化：新建文档成功后后端返回 chunk_count，页面提示「文档"xxx"创建成功，切分为 N 个知识块」；文档内容保存后会被切分并向量化，供检索与 NLQ 召回。
版本机制：编辑保存走 PUT /knowledge/documents/:id，每次保存版本 +1（按钮文案「保存（版本+1）」）；回滚走 POST .../versions/:v/restore，回滚后该版本成为当前版本。
状态机：文档状态经 STATUS_TEXT 映射展示（ready→就绪、processing→处理中、embedding→向量化中、chunking→切分中、failed→失败等），前端按状态着色徽标。
防御式兼容：unwrap/normalizeDocs/normalizeDirs 兼容 {code, data} 与直接 {key...} 两种响应结构，后端字段变化不白屏。

6. 权限与安全

认证：aip_token JWT，401 自动清理并跳登录页（登录页内不重复跳）。
权限范围：接口挂在 AIP protected 组，任意已登录用户可管理目录与文档；无 RLS/CLS 细分。
写操作防护：删除文档与版本回滚均有 confirm 二次确认；提交中按钮禁用；检索片段先 escapeHtml 再高亮替换，防 XSS 注入。

7. 常见问题与排错

7.1 文档列表提示「暂无文档（后端可能未就绪）。」

现象：中部文档区一直空，出现该空态文案。原因：GET /knowledge/documents 请求失败（后端未启动、token 过期 401 或路由未注册）。处理：确认 18080 AIP 后端已启动；打开 Network 面板看接口状态码；401 则重新登录。

7.2 点「检索」提示「请输入检索内容」

现象：知识检索区输入为空点检索，红条提示。原因：searchQuery.trim() 为空，前端校验拦截，未发起请求。处理：输入至少一个非空格字符后重试；确认没有误输入全角空格。

7.3 编辑保存后版本没有 +1

现象：编辑文档保存提示「已保存（版本 +1）」，但列表版本号未变。原因：内容实际未变化时后端可能不产生新版本；或表单未正确回填导致提交了相同内容。处理：修改内容后再保存；在「版本」弹窗确认版本历史是否有新增记录。

7.4 检索结果显示 HTML 乱码

现象：检索片段渲染异常或被注入。原因：理论上不会——highlightSnippet 先 escapeHtml 转义再高亮替换。处理：若出现异常，检查是否有旧缓存页面；刷新页面重新检索。

8. 已知缺陷与边界

项目	说明
标签为客户端全量筛选（现实边界）	后端列表接口 `GET /knowledge/documents` 无 tag 参数，按标签过滤无法在服务端完成；页面改为点选标签后按 `page_size=100`（后端钳制上限）逐页拉取全部文档，再在客户端本地过滤。带进度、可取消（取消回退为「仅当前页过滤」并保留作用范围提示）、有拉取上限（20 页 / 2000 条，触顶终止并提示结果可能不完整）；筛选就绪后命中集一次性全展示，分页条隐藏（2026-09-14 修正：此前分页条仍显示「第 N/M 页」且页码可点，但不作用于命中集，构成误导）
版本回滚不保留变更说明	回滚后 `change_note` 无自动补充
大文档保存偏慢	切分 + 向量化在保存请求内完成，大文档等待时间变长
检索 top_k 固定 10	知识检索区无 top_k 调节入口
后端未就绪的降级提示	目录/文档/标签任一加载失败仅 alert 提示，不阻塞其他区域

注：标签筛选历经两次演进——2026-09-06 先以页面黄条明示「仅过滤当前页已加载结果、非全量筛选」消除误导；2026-09-13 改为客户端全量筛选（逐页 100 条拉取 + 本地过滤 + 进度/取消/上限保护），后端列表接口仍无 tag 参数。

相邻页面：数据源管理 · 知识库分层树 · 实体关系抽取 · 元数据语义标注