知识库分层树

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 核心价值

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 + 折叠箭头）
       │                   首屏限 300 节点，超出显示「展开更多」按钮
       └─ 卡片「混合检索」：输入 + 「检索」；结果（score + 来源徽标 + 标题 + node_path + 内容 + URI）

各板块职责：

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

4. 交互元素详解

4.1 文档列表

4.2 创建文档

4.3 文档大纲与检索

• 文档大纲树：节点类型徽标（文档=蓝、章节=绿、块=灰），标题悬浮显示 uri；行尾 #ord · Ntk（序号 · token 数）；有子节点的行可点 ▸/▾ 折叠/展开（默认展开）。空态「请先在左侧选择文档。」或「该文档无分层树（旧扁平文档或索引未完成）。可在旧版「知识库」页查看分块，或更新内容触发重建。」。
  • 渲染节流（2026-09-13 补）：首屏仅渲染前 300 个节点，超出部分显示「展开更多（已渲染 x / y 个节点）」按钮，单次递增 300 行；折叠/展开只在本地按展开态重新展平（不再重复请求 outline 端点），以此降低超大文档的 DOM 创建与渲染开销。纯前端渲染层节流，不改变数据契约（outline 端点仍一次返回完整嵌套树）。
• 混合检索：输入查询词（跨新旧两表）点「检索」，结果卡片展示 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 端点表

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. 已知缺陷与边界

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