星罗 (Stars) - Knowledge Graph for VSCode & Web

本项目使用 AI 辅助生成

Stars 是一款键盘优先、沉浸式、可视化的知识探索与构建环境。它将复杂的概念体系呈现为一个可自由遨游的二维图谱。Stars 不仅作为 VS Code 扩展 集成在你的开发工作流中，还提供一个 独立的 Web 版本，旨在为用户提供极致的思维连贯性、深度的学习体验以及对知识结构更精细的掌控。

🚀 如何使用

VS Code 扩展

1. 打开图谱：
   • 打开一个工作区文件夹（重要，用于保存 .stars.json 数据）。
   • 在命令面板 (F1) 中，运行 Stars: Open Knowledge Graph 命令。

图谱将在新的 Webview 面板中打开，你可以立即开始构建你的知识网络。

独立 Web 版本

1. 在线体验：打开你的浏览器，访问 stars.sch246.com。
2. 下载文件：从 GitHub 获取**源代码**，在本地用任意现代浏览器打开。

网页加载后，你就可以直接在浏览器中体验 Stars。所有数据将存储在你的浏览器本地。

✨ 核心特性

• 多平台可用：
  • VS Code 扩展：深度集成于 VS Code 环境，利用工作区根目录进行数据持久化，与你的项目文件紧密关联。
  • 独立 Web 版本：可在任何现代浏览器中访问，数据存储在浏览器本地存储 (localStorage)，提供便捷的在线体验。
  • 在线体验地址：stars.sch246.com
• 键盘/鼠标优先的沉浸式交互：通过直观的快捷键（方向键、数字键等）和鼠标（侧键、右键）在知识图谱中“飞行”和操作，最大程度减少鼠标依赖，保持思维流畅。
• 国际化支持 (i18n)：
  • VS Code 版：界面文本支持中文和英文，并会自动根据运行环境的语言设置进行切换，提供更友好的多语言用户体验。
  • Web 版：仅支持中文界面。
• 优化：内容自动防抖保存：编辑节点标签、摘要或内容时，数据会自动以防抖方式保存到本地。
  • VS Code 版本：数据持久化到工作区根目录的 .stars.json 文件。
  • Web 版本：数据持久化到浏览器 localStorage。
• 实时文件同步（VS Code 版）：VS Code 扩展会监听 .stars.json 文件的外部修改（例如，通过 Git 操作或手动编辑），并在检测到变化时自动更新图谱，确保数据同步。
• 动态可视化的知识宇宙：D3 力导向布局，节点与链接以平滑的渐变出现/消失，镜头平滑跟随并支持自由旋转。
• 上下文感知的可见性：只显示聚焦节点、其直接邻居、当前悬浮节点（及其邻居）、当前预览节点（及其邻居），以及视野层级内的节点与链接，避免信息过载。
• 自定义预设链接：内置默认关系类型，并支持通过编辑器增删改查自定义预设链接。预设链接可设置标签 (label)、值 (value) 和颜色。链接以线性渐变表示方向与语义。
• 连通性保障：任何删除/覆盖等可能导致节点与“主网络”失联的操作，都会在模拟后给出警告与确认，保护你的知识网络。
• 槽位系统 (Slots)：4 个快速切换槽位，支持交换与覆盖存入，HUD 中以小型圆形节点呈现。
• 数据导入/导出：一键导出/导入 JSON，便于备份与跨平台迁移。
• 侧边栏拖动调整：侧边栏宽度可自由拖动调整，适应不同屏幕和工作流偏好。
• 智能拖拽：鼠标左键按住节点时，对该节点持续施加物理吸引力，引导其向鼠标位置移动；松开后节点回归力导向布局，而非直接固定位置，提供更自然的交互体验。点击与拖拽通过时间和位移阈值智能区分，避免误操作。

💡 知识结构

节点 (Nodes)

• 核心实体：每个节点代表一个概念，拥有唯一 UUID、可编辑的标签、摘要与正文（Markdown/HTML）。
• 动态位置与颜色：D3 力导向自动优化布局，可通过鼠标物理拖拽影响布局；每个节点可独立设置颜色。
• 新建节点颜色：自动分配亮度高、鲜艳的随机色；默认“Origin”节点为白色（#FFFFFF，不可删除）。

链接 (Links)

• 有向关系：以 source → target 表达方向。
• 类型系统：支持自定义预设类型（可设置标签、值、颜色），也可输入任意文本作为自定义类型。预设类型通过数字键快速选择。
• 可视化：以线性渐变表示方向与语义（预设类型为亮色，自定义/非焦点默认为灰阶）。
• 覆盖逻辑：若链接已存在（无论方向），会直接覆盖其类型和方向（默认由源节点指向目标节点）。

🌌 可视化与物理

• 动态视野：视野层级可调（1–7），自动微调缩放以确保层级内节点可见；HUD 显示当前层级与可见节点数。
• 力导向模拟范围：始终对聚焦节点周围 7 层内的节点/链接进行计算，切换焦点或层级时更稳定，减少突变。
• 摄像机：视图平滑跟随聚焦节点；自由旋转以阻尼动画过渡；所有节点与链接文本在旋转时保持水平，便于阅读。
• 出入场动画：节点/链接以约 0.4s 渐变变更透明度，保证视觉连续性。
• 正文模态框优化：模态框支持 Markdown 渲染和 代码高亮；模态框背景半透明并覆盖整个屏幕，内容主体在屏幕中央显示。

🎮 操作指南

键盘

• Tab：快速创建并连接节点。
  • 使用默认关系(第一个预设)新建关联节点。适合快速构建思维链。
  • 若当前处于连线模式，优先使用选择的关系。
• L：进入连线模式。
  1. 选择连接类型（Enter 默认， 1-9 选择预设，Space 自定义，D/Delete 断开）。
  2. 按 Esc 或点击空白处可取消连线。
  3. 进入连线模式后移动，将会在移动路径上建立/覆盖/断开关系。
• N：新建独立节点并跳转。
  • 连线模式下使用相当于建立关联节点。
• Delete / D：删除当前焦点。
• Space：编辑节点。
• Enter：查看/运行节点；按 Esc 或点击背景关闭。
• ↑ ↓ ← → 或 / ?：按屏幕方向选择最近邻居并导航。
• H：回到“Origin”，并重置视图旋转至 0。
• B：回到上一个有效节点。
• , .：预览邻居摘要和关系；旋转预览节点至正上方。
  • 预览中按 ↑ 或 /：跳转到预览节点。
• < >：旋转视图。
• = -：调整视野层级（1–7）。
• 1–4：焦点与对应槽位交换（若槽位为空则存入焦点）。
• Shift+1–4 （! @ # $）：焦点覆盖对应槽位。
• I：切换按键提示的显示。
• `：打开/关闭“预设关系编辑器”；按 Esc 或点击空白处关闭。
• Esc：取消或关闭。

鼠标

• 双击: 在鼠标位置快速创建并连接节点。
• 中键拖动节点: 在节点之间编辑关系
• 中键拖动: 移动视图
• 前侧键：进入连线模式。
• 右键连线：删除该连线。
• 右键节点：删除该节点。
• 左键焦点：查看/运行节点；按 Esc 或点击背景关闭。
• 左键节点：跳转到该节点。
• 后侧键：回到上一个有效节点。
• 悬浮于节点: 预览摘要和关系。
• 滚轮：缩放视图。
• 左键槽位：焦点与该槽位交换（若槽位为空则存入焦点）。
• Shift+左键槽位：焦点覆盖该槽位。
• 右键槽位：清空该槽位。
• 左键拖拽节点：对节点持续施加指向鼠标的物理吸引力。
• 点击空白处：取消或关闭。

交互约束

• 所有鼠标交互严格限于当前可见且透明度 alpha > 0.5 的节点，过渡期间不会误触。

🔬 高级功能：节点内脚本运行

• 交互式内容：节点正文（Markdown/HTML）中允许嵌入 <script> 标签，其内容将在模态框显示时运行。
• 沙箱环境：脚本运行在一个相对隔离的环境中，避免直接污染主应用。
• 运行时 API：脚本可以通过全局 Runtime 对象访问特定的 API：
  • Runtime.$ / Runtime.$$：用于查询脚本所在节点内容 DOM 的元素。
  • Runtime.node：提供当前节点的 UUID、标签、颜色等元数据。
  • Runtime.storage：提供节点专属的本地存储（基于 localStorage），支持 set, get, remove, clear 方法，数据以节点 UUID 为前缀隔离。
  • Runtime.onMount(callback)：当脚本被加载并运行后执行的回调。
  • Runtime.onUnmount(callback)：当模态框关闭时执行的清理回调，用于移除事件监听器、停止动画等，防止内存泄漏。

---

⚠️ 安全警告：

尽管脚本运行在相对隔离的环境中，但直接执行用户提供的代码始终存在风险。请勿运行您不信任的脚本，尤其是在导入他人数据时。本项目是本地运行且数据存储在本地，但恶意脚本仍可能修改您的本地存储数据，或进行其他本地操作。您需自行承担运行脚本的风险。

🛡️ 连通性保障

• 主网络定义：由 Origin 节点和所有非空槽位节点及其可达节点组成。
• 预判模拟：删除节点/链接、覆盖槽位、关键导航前，先模拟操作后的连通性。
• 警告与确认：若将导致节点与主网络失联，给出节点数量与样例名称提示，用户可选择继续（会清理失联节点）或取消。
• 历史与槽位清理：删除节点后清理其在历史与槽位中的引用，保持系统一致性。

💾 数据持久化与导入/导出

• VS Code 版本：数据自动保存到你工作区根目录下的 .stars.json 文件中。
• Web 版本：数据自动保存到**浏览器本地存储 (localStorage)**中。
• 导入/导出：一键导出/导入 JSON，便于备份与跨平台迁移（例如，将 Web 版本数据导入到 VS Code 项目，反之亦然）。提供“重置系统”按钮清空数据。

📸 截图 / 演示

🤝 贡献

本项目目前不接受外部代码贡献或功能请求。感谢理解。

许可证

MIT License.