9.2 KiB
9.2 KiB
设计 Brief：llm-wiki 知识图谱 HTML 重设计
Project overview
llm-wiki 是一个把碎片化信息整理成可持续维护知识库的本地工具。当前知识图谱 HTML 已具备搜索、过滤、边权重、洞察面板、社区聚类、学习驾驶舱等功能，但视觉上仍显得像 demo。目标是为知识图谱生成一套可复用的重设计 brief，让后续 AI 设计工具或人工实现能产出更高级、更有识别度的图谱界面。
Brief diagnosis
- 初始分数：42/100。
- 初始等级：Weak brief。
- 主要风险：只说“不像 demo”会导致下游工具生成泛化科技 UI、空洞发光图、或只换皮不改善产品质感。
- 已补齐信息：第一印象、视觉方向、保留程度、输出边界和最终策略已确认。
- 当前状态：可以稳定进入设计生成阶段，但仍建议先出 2-3 个视觉稿，不直接锁定最终实现。
Target audience
- 主要用户：正在使用 llm-wiki 的个人学习者、研究者、内容整理者，希望在本地知识库里探索概念、实体、主题和来源关系。
- 次要用户：在 README、演示 GIF 或 GitHub 页面上第一次看到 llm-wiki 的潜在安装者。
- 使用场景：用户双击本地 HTML，在浏览器中离线探索知识图谱；也可能通过截图/GIF 判断这个项目是否值得安装。
- 痛点：现有界面功能足够多，但视觉记忆点弱，容易被看成临时 demo 或开发者测试页。
Business goal
让知识图谱成为 llm-wiki 的旗舰展示面：第一眼建立“这是成熟、用心、有审美的知识产品”的信任感，同时不牺牲真实使用效率。
Design goal
将当前“水彩卡片风”升级为“东方编辑部 × 数字山水”的高级知识地图：既有东方中文编辑感、文献馆气质和朱砂批注细节，也让中央图谱具备山水/星图式舞台感。
Core message
这不是一次性的可视化 demo，而是一张可以长期阅读、探索和维护的个人知识舆图。
Supporting points:
- 图谱是知识库的入口，不只是装饰。
- 节点、边、置信度、社区和学习队列都要有清楚的信息角色。
- 东方感来自排版、留白、批注、纸面层次和地图隐喻，不来自堆砌传统纹样。
Required structure
- 顶部品牌区：显示知识库标题、图谱定位、GitHub/项目入口和关键状态摘要。
- 左侧导航：社区、聚焦、搜索、学习队列、推荐起点保持清楚，视觉上像文献索引或编辑目录。
- 中央图谱画布：作为视觉主角，加入山水地形线、星图层次、纸面/雾层背景，但不能遮挡节点和边。
- 图谱节点：实体、主题、来源三类节点要有清楚区分；长标签安全截断，hover/focus/selected 状态明确。
- 图谱边：置信度和关系强度要可读；弱关系不应产生视觉噪声。
- 右侧详情抽屉：像札记、批注卡或档案页，包含摘要、来源、相邻节点、学习笔记和操作。
- 二级信息：小地图、洞察、图例、相邻节点可以折叠或弱化，但入口必须明确。
- 空/加载/错误状态：本地 HTML 需要清楚解释数据为空、脚本加载中、资源失败等状态。
Visual direction
选定策略：东方编辑部 × 数字山水。
Tone keywords:
- 高级产品感
- 中文编辑部
- 文献馆
- 知识舆图
- 朱砂批注
- 数字山水
- 克制发光
- 可长期阅读
Differentiators:
- 使用“地图册/档案馆/编辑批注”的系统隐喻，而不是普通 dashboard 卡片。
- 中央图谱具备舞台感，但控制面板仍保持产品可用性。
- 视觉细节优先服务信息结构：社区像地貌层，边像路径，节点像地名/索引条目，详情像札记。
Avoid:
- 泛化 AI 蓝紫渐变。
- 过度玻璃拟态。
- 卡片随机堆叠。
- 装饰性中国风纹样。
- 游戏化星图 UI。
- 复制任何现成品牌、字体、图标或产品界面。
Strategy options
A. 东方编辑部 Knowledge Atlas
最稳的产品方向。保留工具效率，用编辑部、文献馆、批注、索引和知识地图构建高级感。
B. 数字山水 Knowledge Constellation
最有记忆点的视觉方向。用山水等高线、雾层、星图节点和克制发光让首屏摆脱 demo 感。
C. 现代文献馆 Research Library
最耐用的长期使用方向。强调检索、阅读、低疲劳和文档产品质感。
D. 东方编辑部 × 数字山水
本 brief 采用的最终方向。用 A 的产品骨架承载功能，用 B 的首屏氛围提升记忆点。
Brand context
- 品牌名：llm-wiki。
- 已有定位：更适合国内用户的 K 神知识库，把碎片化信息变成持续积累、互相链接的知识库。
- 现有视觉资产：README 中已有图谱 GIF 和预览图；图谱模板已有纸感、水彩、手绘字体方向，但需要升级。
- 品牌语气：温暖、清楚、可信、略有中文编辑感；不要卖弄术语。
DESIGN.md reference
使用本 brief 包内的 DESIGN.md 作为视觉系统。主参考方向是 enterprise_data_workspace，因为它最适合有搜索、过滤、状态、面板和元数据的工作台；辅助吸收 premium_visual_showcase 的克制展示机制，用于中央图谱首屏氛围。
Asset list
- 真实数据：由现有图谱 JSON 注入，节点包含实体、主题、来源、社区、边权重和置信度。
- 现有前端能力：D3 图谱、rough.js、marked、DOMPurify、搜索、筛选、抽屉、学习队列、小地图和洞察。
- 可用文字资产：知识库标题、节点标签、来源摘要、关系名称、置信度标签。
- 不应假设：真实 logo、商业客户 logo、外部插画、外部图片、付费字体。
Interaction requirements
- 搜索输入、社区筛选、聚焦、学习队列、推荐起点必须保持可见或容易发现。
- 节点 default、hover、focus、selected、disabled/unavailable 状态要区分清楚。
- 节点必须遵守三层视觉语法：普通节点像地图地名，重要节点像索引签条，选中节点像朱砂批注；密集图谱不能把所有节点都渲染成完整卡片。
- 小地图必须像地图册方位图：当前视口使用朱砂细框，选中节点使用印点，整体低对比，不抢中央画布。
- 学习队列必须像书签条或札记条，长标题可读，不回到横向 chip。
- 首次打开必须保持全局图和推荐起点预览，不自动选中推荐起点；用户点击后才进入选中阅读态。
- 详情抽屉打开/关闭不能让主画布跳动到不可控；13 寸屏上仍能阅读。
- 键盘可访问：搜索、列表项、节点、关闭按钮、主要操作要有可见 focus。
- reduced motion 下保留可读状态变化，关闭不必要漂浮、发光或雾层动效。
- 移动端可降级为“列表/详情优先，图谱可横向或缩略探索”，不要强行塞满三栏。
Constraints
- 平台：单文件或自包含本地 HTML，双击即可使用。
- 技术栈：延续当前 vanilla HTML/CSS/JS + D3 结构；设计稿不能要求引入大型前端框架。
- 资源：避免新增外部图片、外部字体或网络依赖；字体使用系统中文 serif/sans fallback。
- 响应式：优先 13 寸笔记本和桌面浏览器，兼顾平板/窄屏降级。
- 可访问性：文字对比度要足够，交互目标至少 44px，状态不能只靠颜色。
- 性能：背景纹理、发光、地形线和动效不能拖慢大图谱渲染。
Forbidden directions
- 不做“炫酷但不可用”的暗色星图。
- 不做通用 SaaS 卡片 dashboard。
- 不做只换颜色的水彩皮肤。
- 不堆龙纹、祥云、印章、毛笔字等表面中国风。
- 不复制 Notion、Linear、Apple、Aesop、The New York Times 或任何具体品牌。
- 不新增无法离线运行的依赖。
Success criteria
- 首屏 10 秒内能看出这是成熟知识产品，不是 demo。
- 首屏 10 秒内能看懂“从这里开始”，但页面没有替用户自动进入选中阅读态。
- 截图/GIF 具有明确识别度：东方编辑部、知识地图、朱砂批注、数字山水层次。
- 设计验收不只检查按钮和功能存在，也检查节点、小地图、学习队列、右侧札记和首次打开是否保住东方编辑部 × 数字山水身份。
- 日常使用中搜索、筛选、节点阅读、详情查看不被装饰干扰。
- 13 寸屏上三栏结构不拥挤；窄屏有清楚降级。
- 空、加载、错误、无结果和资源失败状态都有设计。
- 后续实现能主要通过现有 HTML/CSS/JS 模板落地，不需要重写整个应用。
Open questions
- 最终是否要保留当前“水彩”命名，还是改成“atlas / editorial / shanshui”等新风格名称？
- 后续实现时，是否接受为图谱模板增加一个新的 visual variant，而不是覆盖现有 wash 风格？
- 是否需要额外为 README 生成一张新的静态预览图或 GIF？
Assumptions
- 本次只生成 brief 包，不直接修改图谱代码。
- 用户希望先看到多稿探索，再选定最终实现方向。
- 图谱功能结构基本保留，重设计重点是视觉系统、层级、首屏氛围和组件状态。
- 设计应默认支持中文知识库，但英文标签也不能崩坏。