工作区星图 elalamiimed/dsh-connectome

Connectome

一张会呼吸的工作区地图，专为 DeepSeek Harness Web UI 打造 —— 每个文件是一个神经元，每条引用是一条突触，每个文件夹是一片脑区。Connectome 扫描当前工作区 ——代码、文档、PDF、图片、数据、媒体、字体、未分类的二进制文件，一视同仁 —— 用 d3-force 物理引擎把文件与文件夹的关系图画在一张 上，让你追踪任意关联，点一下神经元，就能在 harness 自带的右侧栏预览里打开那个文件。

Connectome 示意图

横幅是画布关系图的示意图，不是截图。

特性

- 一张画布，几百个节点，60 fps。 节点和连线都画进同一张 ，不为每个文件创建 DOM 节点。布局由 d3-force 计算，插件自己的 requestAnimationFrame 循环驱动它，空闲时模拟自动停止。
- 什么文件都能上。 代码、样式、Markdown、PDF、Word/PowerPoint/Excel 文档、图片、字体、数据文件、媒体、未分类的二进制文件，统统变成神经元。每个神经元归入一个粗粒度家族 —— code（圆形）、docs（圆角方块）、data（菱形）、 assets（图片、媒体、字体、压缩包等，圆环）和 other（小圆点）。图例统计各家族的数量，节点提示框显示类型、扩展名和字节大小。
- 文件夹与子文件夹。 目录区域画在关系图背后，是嵌套的轮廓线，按实时布局计算，标注文件夹名；顶栏的文件夹开关控制显示或隐藏。文件夹只表示文件住在哪里，不是力导向节点，所以永远不会挤乱关系布局。
- 关系看得懂。 依赖边在指向的文件一端带箭头：实线表示 import / export … from / 动态 import() / require / CSS @import，虚线表示 HTML 属性、Markdown 链接与图片、CSS url(...) 资源。把鼠标悬停在连线上，能看到两端和关系类型。
- 邻域探查。 悬停节点会高亮它的邻域，并列出直接关联（→ 导入了谁，← 被谁导入），每条都能点，其余用 +N 汇总。想看清两个模块 —— 或者两个「引擎」文件 ——怎么交汇，这招最好用。
- 点击即打开。 点一个神经元，就在 harness 右侧栏的文档预览里打开那个文件（ctx.sidebarRight.openResource，地址形如 dsh-resource://file/session/…）：代码带行号，Markdown、PDF，图片和 Office 文档，全部在 DSH 内完成。缺少预览或选中的会话，会在页脚说明。
- 跟随主题。 画布在运行时从实时的 --dsw-alias- 主题 token 读取颜色，所以切换浅色/深色会重新给图上色。
- 工作区切换、重新扫描、适配、缩放、平移、拖动节点、Esc 关闭。
- 本地优先设计。 无遥测、无网络请求，工作区数据不会离开你的机器。

安装

Connectome 是 DSH 的 bundle 插件：安装后会添加一行 Host（工作区扫描器 + HTTP 路由）和一个懒加载的浏览器模块（画布 UI）。

要求

- DeepSeek Harness 0.2.1-rc.2 或更新版本（桌面版，或带标准 Web bundle 的 dsh web 部署）。
- 只有从源码构建才需要 Node.js 18+；发布版已预构建 client.js。

从 Web UI 安装（推荐）

打开侧边栏的 Plugins 页面，选择 Install，然后输入以下之一：

dsh-connectome # npm (recommended)
github:elalamiimed/dsh-connectome # straight from GitHub

npm 包已上线：npmjs.com/package/dsh-connectome；安装成功后，插件管理器会启用该 bundle。打开侧边栏面板列表的 More 菜单，选择 🧠 Connectome。

从终端安装

DSH 命令行会把包操作转发给配置档；之后在 Plugins 中启用该 bundle（或者继续用上面的 Web UI，它会同时完成这两步）：

dsh plugin --profile desktop add dsh-connectome
or straight from GitHub:
dsh plugin --profile desktop add github:elalamiimed/dsh-connectome

排障 —— dsh-connectome declares no dsh.bundle。 全新的 npm 包在审核期间，npm 可能把它停在 0.0.0-stage 占位版本上，该版本没有声明 bundle。镜像（例如 registry.npmmirror.com）在正式版本发布后可能还会继续提供这个占位版本一段时间，插件管理器的安装前检查就会用这条消息拒绝该包。在安装对话框的 registry 选择器里选 Official npm registry，等镜像同步后重试，或者改用 github: 规格安装。查看某个 registry 当前有什么：

npm view dsh-connectome dist-tags --registry https://registry.npmmirror.com

手动安装 / 开发安装

git clone https://github.com/elalamiimed/dsh-connectome.git
cd dsh-connectome
then install the folder as a bundle in the running profile, e.g. with
plugin_manager install_bundle <absolute-path>, or dsh plugin add link:<absolute-path>

注意：npm 名称 dsh-project-brain 属于另一个无关的 DSH 插件。本项目以 dsh-connectome 发布；GitHub 仓库只在历史记录里还保留着「project brain」这个工作名称。

使用

1. 打开侧边栏面板列表的 More 菜单 → 🧠 Connectome。
2. 对话框会扫描当前工作区，并让图适配视图。左上角的图例统计当前出现的每种文件族。
3. 用顶栏切换工作区（注册了多个工作区时）、开关文件夹轮廓、重新扫描、适配或缩放；拖动背景平移；滚动以指针为中心缩放；拖动节点可拉动它。
4. 悬停节点或连线，查看关系提示。悬停节点还会强调它的文件夹链。点击神经元，在右侧边栏打开该文件。按 Esc 或点 ✕ 按钮关闭对话框。

支持的依赖语法

Host 用小型、无依赖的正则提取链接（裸包名刻意不展开到 node_modules）：

| 文件 | 关系 |
| JS / TS / JSX / TSX / Vue / Svelte | import … from、export … from、动态 import()、require()（任意目标，包括资源） |
| CSS / SCSS / Sass / Less / Stylus | @import、@use、@forward、url(...) 资源（图片、字体） |
| HTML | 、、///// 的 src、、、 |
| Markdown | 相对链接和图片 —— 代码、PDF、图片、任意文件 |
| Python | import x、from . import y |

每个未被忽略的普通文件都会成为一个节点，所以被引用的 PDF、图片、字体或数据文件也会出现在图上，尽管只有文本格式会被解析以找出更多链接。只有相对路径、根相对路径以及 @/ / ~/ 说明符会解析到工作区文件。node_modules、.git、构建产物、缓存和点目录会跳过；lockfile、source map、压缩后的 bundle 和系统垃圾文件（.DS_Store、Thumbs.db、编辑器交换文件）也会排除。

工作原理

Host 部分（index.js）

- POST /connectome/api/graph —— 同源路由，经 ctx.connection.requestRejection(req) 拦截；可选 JSON 请求体 { "root": "<workspace>" }。
- 从已注册的工作区（或当前工作目录）解析工作区根目录，并在硬性上限下扫描：2,000 个文件节点、12,000 个目录项、1,500 个解析文件、每文件读取 512 KiB、8 秒软时间预算。
- 每个未被忽略的普通文件都会成为一个节点，带一个粗略的 kind；文本格式会被解析以找出引用，引用会链接到它解析到的任何已扫描文件。文件夹索引随节点一起返回，以便 Client 绘制目录区域。
- 返回图：

{
"ok": true,
"root": "C:\\path\\workspace",
"roots": [{ "path": "C:\\path\\workspace", "title": "my-project" }],
"nodes": [
{ "id": "src/index.js", "label": "index.js", "ext": ".js", "size": 1234, "dir": "src", "kind": "code" },
{ "id": "src/util.js", "label": "util.js", "ext": ".js", "size": 456, "dir": "src", "kind": "code" },
{ "id": "docs/readme.md", "label": "readme.md", "ext": ".md", "size": 789, "dir": "docs", "kind": "doc" },json
{ "id": "docs/spec.pdf", "label": "spec.pdf", "ext": ".pdf", "size": 48213, "dir": "docs", "kind": "doc" }
],
"links": [
{ "source": "docs/readme.md", "target": "docs/spec.pdf", "kind": "markdown-link" },
{ "source": "src/index.js", "target": "src/util.js", "kind": "import" }
],
"folders": [
{ "id": "docs", "parent": null, "depth": 1, "files": 2, "total": 2 },
{ "id": "src", "parent": null, "depth": 1, "files": 2, "total": 2 }
],
"stats": {
"files": 4,
"folders": 2,
"scanned": 3,
"links": 2,
"truncated": false,
"durationMs": 4,
"kinds": { "code": 2, "doc": 2, "data": 0, "image": 0, "media": 0, "archive": 0, "font": 0, "other": 0 }
}
}

客户端部分（client.source.js → client.js）

- 注册 sidebar.panellist.actions（菜单行）和 shell.overlay（对话框），两者都通过 ctx.slots.inject / ctx.slots.register 完成。
- 每加载一张图，用 simulation.stop() 构建一次 d3 模拟，然后由插件的 requestAnimationFrame 循环驱动它逐帧推进；悬停变化更新 React 状态，但指针移动只修改 transform，并且只在需要时请求帧。
- 把所有实线边合并为一次描边，所有结构边合并为一次虚线描边，所有箭头合并为一次填充，节点形状按族各合并为一次填充，文件夹轮廓合并为一次填充 + 描边。链接命中测试走屏幕空间线段距离计算——不碰 DOM。
- 文件夹/子文件夹轮廓每帧根据节点实时位置重新计算（复杂度为节点数 × 深度，线性），所以区域跟随模拟变化，而不是冻结布局；缩放级别足够大、标签可读时才显示标签，悬停节点的整条文件夹链会高亮。顶部开关只请求重绘。
- 布局以 d3 的 phyllotaxis 螺旋为种子，并用较弱的 forceX/forceY 居中，所以互不相连的文件仍聚在一团，fit-to-view 也不会缩到亚像素小点。
- ResizeObserver 让后备存储与 CSS 尺寸保持一致（DPR 上限为 2）；MutationObserver 在应用主题变化时重新读取主题 token。
- build.mjs 把 d3-force（连同它的 UMD 依赖）内联进 client.js：浏览器模块表没有运行时 npm 解析，所以打包产物必须自包含。vendor/ 锁定 ISC 许可的确切发行版本。
- 点击节点会构造 harness 自己的文件地址（dsh-resource://file/session/<session>/<path>），并调用 ctx.get('sidebarRight').openResource(...)；屏幕上的会话来自 sidebarRight.mounted，回退到 UI Session 适配器。

隐私

Connectome 通过 Host 进程读取工作区，和 DSH 其余部分完全一样。它不向网络发送任何东西：没有分析统计，没有远程 API 调用，不上传文件内容。图响应只在 Host 和你的本地页面之间传递；打开的文件由 DSH 内置预览显示，Connectome 本身从不保留或传输文件内容。

性能
- Canvas 绘制：每个文件族一条路径，每个边族一笔，再加一次文件夹轮廓绘制；只有悬停的邻域才显示标签。
- 模拟在 alphaMin 处停止；一次交互会让它重新启动。
- 开发机上实测的布局开销：300 个节点约 1.1 ms/tick，2,000 个节点约 8 ms/tick；2,000 个节点、约 3,300 条连线的扫描在预热后约半秒跑完。文件夹轮廓每绘制一帧，都要对已布局的节点多做一次线性遍历。
- 大型工作区会被截断，并上报 stats.truncated；对话框会显示「partial scan」标记。

开发

不需要任何开发依赖 —— vendor/ 已提交到仓库，测试只用 Node 内置模块。
bash
node build.mjs # regenerate client.js from client.source.js + vendor/
npm test # scanner + artifact + package/release contract tests
npm run check # node --check on index.js and the generated client
npm pack --dry-run # inspect exactly what npm would publish

只有想用另一份 d3-force 副本重建 client.js 时才需要 npm install：node build.mjs --modules <node_modules dir> 会在 vendor/ 之后到那里查找。
项目结构与评审规则见 CONTRIBUTING.md，维护者发布流程见 PUBLISHING.md。

样式说明

项目级的设计 token 规则要求前端产物使用 --ds- 尺度。本插件是 Harness 的 UI 界面，因此有意把两套体系分开：

- 颜色只取自宿主实时的 --dsw-alias- 主题 token（正因如此，图在浅色和深色模式下都清晰可读）。
- 间距 / 圆角 / 阴影 / 字号使用本地声明的 --ds- token 层（4px 节奏，4/8/12/16/20/24 px 间距，4/8/12/16 px 圆角，阴影尺度，以及 caption/body-sm/body/h3 字号尺度）—— 不使用尺度之外的数值样式。

限制

- 基于正则的解析：@//~/ 之外的别名、tsconfig 路径映射和打包器解析规则都没有建模；裸包名不会成为节点。
- 二进制格式（PDF、图片、Office、媒体）也是节点，在 DSH 文档预览支持时通过它预览；未知后缀会显示预览的不支持提示。二进制文件从不解析，因此不贡献连线。
- 目录区域是根据布局算出的轮廓叠加层，不是力导向节点：文件夹既不排斥也不吸引文件，空文件夹不会出现。
- 大型仓库会触到扫描器上限（见上文），显示部分图；遍历按字母顺序进行，所以一个特别拥挤的文件夹可能吃掉节点预算。
- 图是查看器，不是编辑器：没有重构、搜索或保存布局。

许可证

MIT © 2026 elalamiimed。

随附的 d3 发行版（vendor/）采用 ISC 许可证，Copyright 2010–2021 Mike Bostock；见 vendor/LICENSE-d3.txt。DeepSeek Harness 及其各包是独立项目，各有自己的许可证。