# 设计 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 1. 顶部品牌区：显示知识库标题、图谱定位、GitHub/项目入口和关键状态摘要。 2. 左侧导航：社区、聚焦、搜索、学习队列、推荐起点保持清楚，视觉上像文献索引或编辑目录。 3. 中央图谱画布：作为视觉主角，加入山水地形线、星图层次、纸面/雾层背景，但不能遮挡节点和边。 4. 图谱节点：实体、主题、来源三类节点要有清楚区分；长标签安全截断，hover/focus/selected 状态明确。 5. 图谱边：置信度和关系强度要可读；弱关系不应产生视觉噪声。 6. 右侧详情抽屉：像札记、批注卡或档案页，包含摘要、来源、相邻节点、学习笔记和操作。 7. 二级信息：小地图、洞察、图例、相邻节点可以折叠或弱化，但入口必须明确。 8. 空/加载/错误状态：本地 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 包，不直接修改图谱代码。 - 用户希望先看到多稿探索，再选定最终实现方向。 - 图谱功能结构基本保留，重设计重点是视觉系统、层级、首屏氛围和组件状态。 - 设计应默认支持中文知识库，但英文标签也不能崩坏。