知识库分层树 · LightAIP · frontend-intro-v5

1. 页面概览

1.1 是什么

知识库分层树页面（KnowledgeTreePage.vue，V5 Stage 2 B2-5）是知识库「多格式解析 + 分层摘要树」能力的前端入口。与旧版扁平视图（KnowledgeBasePage.vue）并存：新文档写入 kdoc_nodes 三层树（document → section → chunk），本页展示该树并提供混合检索（结果带 node_path 标题链与来源标注）。

文档列表：左侧列出文档，支持按标题过滤，展示格式徽标与版本/更新时间。
创建文档：text/markdown/html 直接粘贴；pdf/docx 文件上传（前端转 base64）；markdown 的 #/##/### 标题生成分层章节。
文档大纲：选中文档后展示「文档 → 章节 → 块」树，节点带类型徽标、序号与 token 数，可折叠。
混合检索：语义 + 关键词融合、跨新旧两表，结果展示 score、来源（分层树/旧表）、标题链 node_path 与 URI。

1.2 核心价值

能力	说明
多格式创建	text / markdown / html / pdf / docx 五种格式
分层大纲树	document → section → chunk 三层，缩进可折叠
标题链检索	检索结果附 node_path 标题链，定位到章节
来源诚实标注	命中区分「分层树」与旧「块表」来源

1.3 一句话总结

知识库分层树页是知识文档的「大纲视图」：多格式解析入库、三层树展示结构、检索带回标题链，让知识不再是一堆平铺的块。

2. 访问入口

2.1 路由与菜单

路由路径：/knowledge-tree，路由名 KnowledgeTree，meta.title 为「知识库分层树」，requiresAuth: true。
菜单入口：Action 栏目左侧边栏「知识库分层树」（ActionLayout.vue 第 4 项）。
源码文件：action/web/src/views/KnowledgeTreePage.vue。

2.2 认证与权限

路由级 requiresAuth: true，未登录访问跳 /login。
API 级：经 action/web/src/api/knowledgeTreeApi.js → aipClient.js 附带 aip_token Bearer；401 跳登录。
权限要求：普通登录用户可访问；接口挂在 AIP protected 组（/knowledge 前缀，同知识库）。

2.3 端口与 API 前缀

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

3. 界面布局

知识库 · 分层摘要树（页头 + 「刷新」）
└─ 操作结果提示条
└─ 两栏网格（左 280~380px + 右 1fr）
   ├─ 左列
   │   ├─ 卡片「文档列表」：按标题过滤 + 「过滤」；文档项（格式徽标 + 标题 + vN · 时间）
   │   └─ 卡片「创建文档」：标题 / 格式下拉 / 标签 /（内容 textarea 或 文件上传）+ 「创建文档」
   └─ 右列
       ├─ 卡片「文档大纲」：树（文档/章节/块徽标 + 标题 + #ord · Ntk + 折叠箭头）
       └─ 卡片「混合检索」：输入 + 「检索」；结果（score + 来源徽标 + 标题 + node_path + 内容 + URI）

各板块职责：

文档列表：选择要查看/创建的文档，支持关键字过滤。
创建文档：按格式差异展示「内容」textarea 或「文件」上传，创建成功提示节点数与块数。
文档大纲：选中文档后展示三层树，节点默认展开、可折叠。
混合检索：对知识库全量（含旧表）检索，展示标题链与来源。

4. 交互元素详解

4.1 文档列表

控件	含义	操作效果	后端调用
输入「按标题过滤」+ 按钮「过滤」	按标题关键字过滤文档	回车或点「过滤」重载列表	GET /knowledge/documents?keyword=
文档项	单篇文档（格式徽标 + 标题 + vN · 更新时间）	点击选中并加载大纲与详情	GET /knowledge/documents/:id、GET .../outline
按钮「刷新」	重载文档列表	选中文档时同时刷新大纲	同上

4.2 创建文档

控件	含义	操作效果	后端调用
输入「标题」	文档标题	必填（否则「创建文档」按钮禁用）	POST /knowledge/documents
下拉「格式」	文档格式	TEXT / MARKDOWN / HTML / PDF / DOCX（大写）	同上（format）
输入「标签」	逗号分隔标签	placeholder「逗号分隔，如：销售,口径」	同上（tags 数组）
文本域「内容」	text/markdown/html 内容	markdown 的 `#/##/###` 生成分层章节	同上（content）
文件选择器	pdf/docx 文件	前端 `FileReader` 转 base64（去 data URL 前缀）	同上（content=base64）
按钮「创建文档」/「创建并索引中...」	提交创建	成功提示「创建成功：N 个树节点 / M 个块」；PDF 降级解析附注「（PDF 降级解析）」	POST /knowledge/documents（timeout 120s）

4.3 文档大纲与检索

文档大纲树：节点类型徽标（文档=蓝、章节=绿、块=灰），标题悬浮显示 uri；行尾 #ord · Ntk（序号 · token 数）；有子节点的行可点 ▸/▾ 折叠/展开（默认展开）。空态「请先在左侧选择文档。」或「该文档无分层树（旧扁平文档或索引未完成）。可在旧版「知识库」页查看分块，或更新内容触发重建。」。
混合检索：输入查询词（跨新旧两表）点「检索」，结果卡片展示 score（3 位小数）、来源徽标（src-tree 分层树 / src-blocks 旧表）、标题、node_path 标题链（如 产品概述/定价）、内容与 uri。

5. 后端关联

5.1 API 客户端

本页使用 action/web/src/api/knowledgeTreeApi.js，复用 aipClient（baseURL /aip-api/v1）。unwrap 统一解析 {code, message, data}；createDocument 对 pdf/docx 内部转 base64；sourceLabel 将 tree/blocks 映射为「分层树」「旧表」。

5.2 端点表

方法	路径（前缀 /aip-api/v1）	请求体	用途
GET	/knowledge/documents	`keyword?`	文档列表
GET	/knowledge/documents/:id	—	文档详情（含 nodes 与旧表 chunks）
GET	/knowledge/documents/:id/outline	—	文档大纲树（document → section → chunk）
POST	/knowledge/documents	`{title, format, content, tags, directory_id?}`	创建文档（pdf/docx content=base64）
POST	/knowledge/search	`{query, top_k}`	混合检索（结果含 node_path 与来源）
GET	/knowledge/directories	—	目录列表（供 createDocument 可选目录）
GET	/knowledge/tags	—	标签列表
DELETE	/knowledge/documents/:id	—	删除文档（软删归档）

5.3 关键机制

分层树结构：kdoc_nodes 表（document/section/chunk 三种 node_type）通过 parent_id 组织；创建时 markdown 的 #/##/### 标题生成 section，段落生成 chunk；其余格式按行/标签建块。仅 chunk 级生成向量（section/document 摘要本批不做 LLM 摘要）。
PDF 降级解析：PDF 解析失败时回退纯文本近似提取，创建响应 parser 含 degraded，页面提示「（PDF 降级解析）」。
双表检索：Search 同时查分层树（kdoc_nodes）与旧块表（blocks）合并去重，结果带 source（tree/blocks）与 node_path 标题链；旧扁平文档（无树）仍可被检索。
超时放大：创建大文档（含解析 + 建树 + 向量化）超时放大到 120 秒；解析与建树在创建请求内同步完成。

6. 权限与安全

认证：aip_token JWT；401 清理并跳登录。
权限范围：接口挂 AIP protected 组，任意已登录用户可创建/查看文档；无对象级 RLS。
写操作防护：创建时前端校验标题与内容/文件（createReady）；文件内容经 base64 传输，上传类型受 accept 约束（pdf/.docx）。

7. 常见问题与排错

7.1 选中文档大纲提示「该文档无分层树」

现象：文档大纲为空态「该文档无分层树（旧扁平文档或索引未完成）。」。原因：该文档是分层树上线前创建的旧扁平文档，未写入 kdoc_nodes；或索引未完成。处理：在旧版「知识库」页查看其分块，或在「创建文档」重新编辑内容触发重建。

7.2 上传 PDF 创建成功但提示「PDF 降级解析」

现象：创建提示带「（PDF 降级解析）」。原因：后端 PDF 解析失败，回退纯文本近似提取（parser=pdf-degraded）。处理：属降级路径而非错误，树结构与向量索引仍会生成；若内容结构缺失严重，改用 markdown 文本创建。

7.3 创建文档按钮一直禁用

现象：「创建文档」按钮灰色无法点击。原因：createReady 为 false——标题为空，或文本格式内容为空，或二进制格式未选择文件。处理：补全标题 +（文本内容或选择 pdf/docx 文件）后再试。

7.4 检索结果只有旧表来源

现象：检索命中全标「旧表」（src-blocks），无「分层树」。原因：当前文档都是旧扁平文档（无 kdoc_nodes），或新文档尚未建树成功。处理：用「创建文档」重建内容；确认创建成功提示中有「N 个树节点」。

8. 已知缺陷与边界

项目	说明
section/document 无 LLM 摘要	B2-5 刻意不做摘要，仅建结构树与 chunk 向量
PDF 解析可能降级	依赖纯 Go 库，复杂版式会回退文本近似提取
旧扁平文档无树	存量文档不自动重建树，需编辑内容触发
大纲一次性展平	折叠通过前端重建 rows 实现，超大文档渲染开销偏大
无删除/版本入口	本页只管查看与创建，删除/版本管理在「知识库管理」页

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