星罗 (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.

我接下来要做的是节点类型更新 因为我有许多想要添加的设置，但是我不想要走一般的设置面板，它需要有自己特色的设置面板——节点右边的侧边栏就是绝佳的载体，它表示着可编辑的节点属性，那可以构建一个元空间，通过快捷键进入和返回，中心点是星罗本身，聚焦星罗时侧边栏显示其核心设置，元空间里其他不同模块的设置则以设置节点和星罗相连 关系预设可以移动到这里，那么进入退出的快捷键就是`

我在思考其实可以有更小的变动。。 如果不用编辑框呢，用已有的脚本沙盒，但开放修改星罗设置的API，那么元空间的节点可以本身是脚本节点，回车打开设置面板，这个感觉更自洽 甚至不需要特殊的元空间和主空间，直接支持多空间，按`进入“空间”空间，里面每个空间就像节点一样排布 不对，不需要特殊的空间，只需要一种弄个新的节点类型，空间节点，在上面回车是进入其中而不是打开模态板，按`退出一级空间，这直接允许了嵌套 这个设置空间只是预设的一个空间，本质和用户的其它空间没什么区别，用户也可以修改它——虽然用户可能弄坏它，但API还在就能重构 设置每个空间的根节点的脚本节点可以持续运行，那么在设置空间就可以是“星罗”节点监测周边脚本节点的数值变动——

当然还保留原本的节点类型，而如何创建不同类型的节点呢，我们可以用节点标题的扩展名实现，当输入不同的扩展名时，会自动检测并修改节点类型 这需要一个统一的图管理器，架构需要调整，我希望还能像设置预设关系一样设置不同扩展名对应的预设节点——很显然这也可以放在设置空间

Graph表示一个连通分支，内置邻接表和查询邻居等方法，并且维护links和nodes的脏标记，每个连通分支都有一个锚点指向来防止被清理，Graph可能分裂或合并 很显然根据现有的代码，同时只会显示一个连通分支（渲染层很显然只需要对接和渲染一个Graph，就是Focus所在的Graph）

Universe是特殊的Space，管理Space和User，其根节点指向所有Space（作为子空间节点）中的根节点

Universe空间内也有所有的User节点，当用户进入一个Space时，它的Home就指向了对应的Space（当按Home时就回到对应的Space的根节点），User节点其它槽位各自连接向Space和游离Graph，可以在Universe这里可视化观察User的Home、槽位和Focus

User是特殊的节点，管理单个用户的数据/状态，持有slot和focus作为锚点指针(关系)连向几个Graph（很显然一个Graph可能被一个或多个锚点指针指向而有多个锚点），因为这些都可以相互连接，所以它接管相关功能，并且为多人协作构建基础

当Graph被Universe直接指向时，就变成了Space（抛弃之前认为空间可能有多个分支的想法，空间不可能持有不连通的Graph什么的，它本身就是一个Graph分支）其指向的节点就是它的Home，于是与一般的Graph不同的是Space不会被垃圾回收

众所周知，用户可以连接Focus和槽位，此时可能产生Graph合并，若那个槽位对应的分支也有Home节点属于另一个空间，则属于空间之间的连接，不能直接连接。此时连接按照设计应该会构建虫洞，虫洞是不同于一般节点的另一个节点类型，总是成对绑定，在上面按Enter会进行跳转以切换空间

Graph之所以存活是因为被用户指向，用户则与Space相连，Space被Universe指向，由此完美闭环

我在思考，那这样的话，设置怎么办，难道User本身作为一个空间，进入后就是用户自己的设置？ 当User在Universe时是不是Home变成Universe本身了？Universe是不是指向它自己所以不会被回收？ 要不`不再表示跳出子空间，而是指向用户本身的设置，在设置空间再按相当于Back Esc作为跳出子空间，在设置空间按就跳出到Universe 用户在Universe实际上是在选择项目，在Universe按Esc就无反应（） 随后服务器只考虑Universe——也就是图的一致性，而所有物理渲染都由用户自己进行，允许渲染的不同步，那么用户设置里就能包含大量的渲染和物理模拟选项 导入导出则只涉及当前Graph的内容，这样也能导入导出自己的设置

如何避免子空间嵌套造成的不可探知的关系，如果Space内部链接到更多的子空间，应该通过Universe递归查找吗，还是说子空间其实是一种表现方式，实际上是在Universe里创建另一个同级Space，在Universe以关系的形式显示 同时Universe内也能看到Space之间的虫洞连接 创建空的Space后感觉第一个节点就是Home 关于创建子空间，如果选中的子图有多个桥连接怎么办，不如说，如何多选？多选在当前逻辑下要加进来必然是格格不入的，感觉只能允许用单个Graph进行创建，在这之前必须手动一个个断开桥，让其本身成为单独的Graph，只通过虫洞和槽位链接，那它就自然成为Graph了，再将其转换为子空间，这比较符合目前的设计哲学

虫洞和子空间关系都应该在Universe看到，这允许Universe遍历时不用真的进入遍历每个Graph 目前这样必须允许两个节点之间有多个关系，比如两个Space之间可能有多个虫洞 颜色叠加，在鼠标移上去时分开显示

创建子空间不应该是单独的按钮，因为进入子空间有新的根节点往往意味着Home的目标改变了

内置3种连接

• 属于(Enter)，按Tab的默认连接
• 虫洞(W)，将会在出发点和目标点邻居创建成对节点，若两边的邻居已有虫洞则不会重复创建，若目标是根节点则尝试创建子空间关系
• 删除(X or Del)，删除沿途关系

删除虫洞将会成对删除，若删除虫洞后会导致当前Home的Space游离则弹出提示，可以选择将其直接连接到Universe根节点，这确保了所有Graph都通过虫洞或子空间关系在Universe分支内

Graph可以通过虫洞连接到Space而存活 用户可以shift+H来setHome，作为显式改变当前的Home指向，setHome必须在根节点，或者虫洞附近进行，而不能在随便一个节点上进行，因为需要确保setHome后总是能找到Parent，这只能利用已有的（根节点），或者现成的关系（虫洞），这在操作手感上也合适（刚创建虫洞跳转就能setHome为子空间，或者在Graph内连接处想要设其为某个父空间的子空间（至少需要确定是哪个父空间吧）） 若setHome在虫洞附近进行，将设置这个节点为该Graph的根节点，让这个Graph变为子空间，若该Graph是Space则提示是否重设该Space的根节点 [测试：多重继承]允许子空间的根节点有多个父空间，这对应节点附近有多个虫洞的情况，或者通过虫洞连接到已有根节点的情况，此时按Esc则取决于历史栈，如果没有则回退到Universe（如果只有一个源则默认回退到父空间）

剪切板好说啊，你先断开多余链接变成一个单独的Graph，再合并进去就行了，根本不需要多余的设置还能移动多个节点 而且为了防止孤岛，删除虫洞时本身进行联通检查，由于是在Universe进行项目级别检查所以很快，所以根本没有这种情况

Universe的行为也可以解释为，监测子空间内的创建子空间/虫洞，并在本地进行同样的连接——于是Universe和源Graph都成为了子空间的父节点

进行大规模重构是靠不住的，实际上要保持代码运行，我们必须每次只抽离出小的功能，比如设计一个Graph类并实现API接口，为了确定具体接口可能需要检查文档和代码哪些地方可能实际用到了它，事先思考如何替换所有这些用到它的地方，根据理想的调用方式，最终倒回来得到优美的API构成，再是设计类