# KnowHub 前端重构设计文档 > **注意**：本文档中的数据库字段和表名引用了旧 schema（JSONB 软关联、tool_table、atomic_capability 等）。新 schema 已迁移到关联表结构，详见 `schema.md`。实施时需按新 schema 调整。 本文档基于 `reference.html` 的视觉风格和交互范式，以及以 **”原子能力 (Capability)”** 为核心的数据库架构，详细规划 KnowHub 前端的重构方案。 ## 核心设计理念 1. **扁平与沉浸式的现代 UI**：采用大圆角卡片、毛玻璃导航、动态阴影、高饱和响应式徽章，带来“现代操作系统”般的体验。 2. **连贯的钻取阅读模式 (SideDrawer)**：摒弃传统的多页面跳转，统一使用右侧滑出式的 `SideDrawer`（侧边抽屉）呈现任何实体的只读和交互详情，保持用户在上下文中的心流。 3. **数据驱动的四象限透视**：以 `需求 - 能力 - 工具 - 知识` 四个维度构建标签页，通过关联表穿透数据孤岛。 --- ## 页面内容结构与详情页 (SideDrawer) 字段级映射设计 前端共划分为五个主要层级（通过顶部 Tab 切换）。每一个 UI 元素严格映射至 `knowhub_db` 核心图谱内的字段结构。 ### 1. Dashboard (全局观测板) **设计目标**：宏观了解系统中能力的沉淀和覆盖情况。 - **页面内容**： - **全景统计图**：总能力集、总需求集、被满足的业务诉求占比、活跃工具覆盖度。 - **需求拓扑图 (Node Tree)**：从顶部类别到底部业务需求的树状图谱，根据节点产生的实际下发热度（如 `requirement_table.source_nodes` 中的 posts 值累加）决定背景热力色深和尺寸。 ### 2. 需求库 (Requirement Library) **设计目标**：展现前端业务需求（`requirement_table`）的落地情况。 - **列表卡片 (Requirement Matrix)**： - **主标题**：取自 `description`。 - **核心指标**：横向展现关联的原子能力个数（遍历 `atomics` 数组的长度）和热度总权重（汇总 `source_nodes` 中所有的帖子数）。 - **满足状态**：Badge 呈现 `status`，如“已满足”、“未满足”。支持点击卡片随时触发 SideDrawer。 - **SideDrawer (需求详情 - `req`)** 排版线框： ```text ========================================================== ✖ (关闭) ==== | | | [BUSINESS REQUIREMENT] (浅色小字) | | 爆款短视频脚本自动化 (超大黑体) | | | | [ 🔴 未满足 ] (巨型状态排版区，可能带有呼吸灯动效) | | | | ------- 匹配分析结果 (Match Result Text) ------------------------ | | "当前语言模型在'口播感'上仍有不足，语气过于生硬，且长文本分镜切 | | 片缺乏镜头语言的训练，需要持续调研更垂直的视频侧面 Agent 框架。" | | (大段具有引用格式的高排版正文) | | | | ------- 调用的链条系统 (Associated Atomics) --------------------- | | | | 🧠 [创意文本自动化] (Cap2) | | | | ------- 数据生成源/痛点来源 (Source Nodes) ---------------------- | | | | 📍 来源于节点: [生活状态] (累计带来 14,895 观测热度) | | | ======================================================================== ``` ### 3. 能力库 (Capability Library) - ⭐️ 系统核心 **设计目标**：原子能力表（`atomic_capability`）的展现和操作大盘。 - **网格卡片 (Capability Cards)** 排版线框： ```text ╭────────────────────────────────────────────────────────╮ │ │ │ [✨ Capability Fully Ready] (状态徽章) [ 🧠 ] │ │ │ │ AI 高精视觉生成 │ │ 基于扩散模型的高保真图像生成与风格迁移能力。 │ │ │ │ ────────── (细分割线) ────────────────────────────── │ │ │ │ 🛠 实现工具: 知识源: │ │ [Midjourney] [SDXL] [📚 2 份知识文件] │ ╰────────────────────────────────────────────────────────╯ ``` - **SideDrawer (能力详情 - `cap`)** 排版线框： ```text ========================================================== ✖ (关闭) ==== | | | [ATOMIC CAPABILITY] (浅色小字) | | AI 高精视觉生成 (超大黑体) | | | | [ 🎯 核心评估标准 (Criterion) ] | | [ "构图准确度 > 90%, 角色特征保持率 > 85%, 出图无变形" ] (高亮区)| | | | ------- 下发工具执行链 (Implements Detail) ---------------------- | | | | ⚙️ Midjourney | | > 通过 /imagine 命令生成图像，效果优秀但不支持中文提示词。 | | | | ⚙️ Stable Diffusion XL | | > 开源生态最丰富的图像生成引擎，支持本地部署，显卡显存需>16G。 | | | | ------- 辐射的需求矩阵 (Requirements) --------------------------- | | | | [⚡ 需求] 生成二次元风格角色封面 | | | | ------- 支撑该能力的知识沉淀 (Source Knowledge) ----------------- | | | | 🔗 [经验] 角色一致性控制方案 (#k1-xxxx) | | 🔗 [工序] SDXL 采样器最优步数实验 (#k3-xxxx) | | | ======================================================================== ``` ### 4. 工具库 (Tool Library) **设计目标**：展示系统中可利用的具集（`tool_table`）。 - **瀑布流 / 扁平卡片 (Tool Card)** 排版线框： ```text ╭────────────────────────────────────────────────────────╮ │ │ │ [ Wrench Icon ] [🟢 可用] (Status) │ │ │ │ Midjourney (标题) [ v6.0 ] (次级标签 version) │ │ │ │ 全球领先的 AI 艺术生成工具，支持高精细节还原。 │ │ │ │ ✨ MATURE 工具成熟率 (Based on case_knowledge) │ │ ■■■■■■■■■■■■■■■■■■■■□□□□□□ 45 案例 │ ╰────────────────────────────────────────────────────────╯ ``` - **SideDrawer (工具详情 - `tool`)** ： - **图谱知识分布 (Knowledge Breakdown)**：将工具的知识关联拆成三张计分卡横排：**工具基础知识** (`tool_knowledge` 长)、**工序执行标准** (`process_knowledge` 长)、**落地实操案例** (`case_knowledge` 长)。 - **详细技术指标**：区块化分别显式输出 `input` 和 `output` 的预设规格。 - **操作向导**：全文区域化呈现 `tutorial`，支持代码与指令的高亮。 - **驱动的能力**：提供 `capabilities` 反向能力关联标签。 - **运维指标**：在卡片边缘呈现 `updated_time` 时间戳转换后的相对时间格式。 ### 5. 知识库 (K-Data Center) **设计目标**：沉淀生产、方法论（`knowledge`）的最佳实践。 - **数据表格视图**： - 列表呈现文章的主旨任务 (`task`)。 - `types` 数组使用多种配色的独立标签进行并排呈现（如：工序/用例/工具/经验/定义/User Profile）。 - 根据 `eval` 字典内的 `score` 字段展示可读带星级的评定结果。 - **SideDrawer (知识详情 - `know`)**： - **评估明细窗 (Eval)**：详细展示 `eval` 内部的四个核心参数键值（`score`、`harmful`、`helpful`、`confidence`）。 - **业务标签系 (Tags)**：遍历解析 `tags` 字典以 KV 徽章组的形式排版。 - **正文区**：宽体排版并呈现大面积 `content`。 - **追溯属性 (Lineage/Source)**：横截面栏位展现创作者所属 `owner`、以及此条目生成的具体分类与端侧来源 (`source.category`, `source.agent_id`)。 - **支撑实体挂载点 (Supports)**：罗列出这条知识最终是在辅助哪个原子能力 (`support_capability` 数组) 抑或是对齐着什么工具 (`tools` 数组)。 --- ## 需增加/完善的后端 API 接口确认 > [!WARNING] > 在目前的 `server.py` 中，主要暴露了关于 Resources 和 Knowledge 的 API 端点。要支撑上述完整的连贯体验，我们必须确保后端能够提供以下核心表的全量及详情查询接口，请用户确认是否已经实现或需要一并在此次迭代中增加： 1. `GET /api/atomic_capabilities` 2. `GET /api/requirements` 3. `GET /api/tools` 4. 数据聚合统计接口，如 `GET /api/dashboard/stats`（或由前端缓存上述列表自行聚合） ## 用户确认点 > [!IMPORTANT] > > 1. **前端框架选择**：因为原本是用 FastAPI 的 Jinja + Vanilla JS 做，而 `reference.html` 是基于 **React + Tailwind**。本次重构您希望使用工程化的 Vite 等完整前端方案，还是像 demo 那样以单文件 HTML + CDN 的极简无构建方式实现？ > 2. **后端 API 是否齐备**：目前 `server.py` 尚未看到 Capabilities、Requirements 等数据的访问路由。是否希望在这轮一并为您用 FastAPI 写好供前端调用的 REST API？