@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/skills/llm-wiki-skill/docs/design/oriental-atlas/README.md

@@ -0,0 +1,10 @@
+# Oriental Atlas Design Reference
+
+This directory contains the approved design baseline for the graph HTML refactor.
+
+- `oriental-editorial-atlas.html`: approved prototype to match visually and structurally
+- `design-brief.md`: product and interaction brief
+- `DESIGN.md`: visual system and component guidance
+- `reviews/result-review.md`: prototype review notes and responsive findings
+
+Implementation work should treat this directory as the local source of truth. Design workspace copies are not implementation branch contracts unless they are synchronized here.

package/skills/llm-wiki-skill/docs/design/oriental-atlas/design-brief.md

@@ -0,0 +1,170 @@
+# 设计 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 包，不直接修改图谱代码。
+- 用户希望先看到多稿探索，再选定最终实现方向。
+- 图谱功能结构基本保留，重设计重点是视觉系统、层级、首屏氛围和组件状态。
+- 设计应默认支持中文知识库，但英文标签也不能崩坏。