# KnowHub 前端重构设计文档
本文档基于 `reference.html` 的视觉风格和交互交互范式，以及 `knowhub_db/README.md` 中以 **“原子能力 (Atomic Capability)”** 为核心的全新数据库架构，详细规划 KnowHub 前端的重构方案。
## 核心设计理念
1. **扁平与沉浸式的现代 UI**：采用大圆角卡片、毛玻璃导航、动态阴影、高饱和响应式徽章，带来“现代操作系统”般的体验。
2. **连贯的钻取阅读模式 (SideDrawer)**：摒弃传统的多页面跳转，统一使用右侧滑出式的 `SideDrawer`（侧边抽屉）呈现任何实体的只读和交互详情，保持用户在上下文中的心流。
3. **数据驱动的四象限透视**：以 `需求 - 能力 - 工具 - 知识` 四个维度构建标签页，相互通过软关联（JSONB ID 数组）穿透数据孤岛。
---
## 页面内容结构与详情页 (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？