Skip to content
dsh marketplace

dsh-neuro-previewer

Verified

@brainpilot/dsh-neuro-previewer · v0.1.0 · MIT · Web UI

A read-only neuroscience data preview plugin for DeepSeek Harness (DSH)

Install

dsh plugin add @brainpilot/dsh-neuro-previewer

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

NeuroPreviewer

npm version license DSH plugin

English | 简体中文

直接在 DeepSeek Harness 中预览神经科学数据。

NeuroPreviewer 是一个面向 DeepSeek Harness（DSH） 的神经科学数据预览插件。 它以 DSH bundle 和 Web client extension 的形式安装，并非独立查看器。模型通过只读的 neuro_preview 工具检查本地数据，DSH Web 客户端则使用专用卡片呈现预览结果。

@brainpilot/dsh-neuro-previewer · GitHub · MIT License

兼容性： 0.1.0 版本面向 DeepSeek Harness 0.1.0-rc.6。DSH 仍处于开发者预览阶段，后续可能引入不兼容的接口变更。

为什么选择 NeuroPreviewer？

NeuroPreviewer 让 DSH 智能体能够安全、轻量地了解神经科学文件的基本信息，而不必把完整数据集发送到浏览器。Host 插件通过 DSH 文件系统接口读取并校验文件，在明确的资源上限内生成二维预览，再返回结构化元数据和适合 Web 显示的灰度图像。

当前版本优先保证可复现性、明确的资源限制，以及 Web 客户端不可用时仍然有效的文本输出。

当前能力

能力 状态 说明
NIfTI-1 单文件 .nii ✅ 校验 sizeof_hdr=348 与 n+1 magic
3D MRI ✅ axial、coronal、sagittal 三个切面
4D fMRI ✅ 可指定零基 volume
数值类型 ✅ uint8/int8/int16/uint16/int32/uint32/float32/float64
强度处理 ✅ 应用 scl_slope/scl_inter，使用 2%–98% 分位窗
大小端 ✅ little-endian 与 big-endian
DSH Web 预览卡片 ✅ Canvas 灰度图、维度、类型、切面和强度范围
.nii.gz、NIfTI-2 计划中 已准备真实样本，尚未实现解压与解析
BIDS 元数据、CSV/TSV 计划中 已准备真实 BIDS sidecar 和 events 文件
EDF/EDF+、BrainVision、EEGLAB 计划中 已准备真实 EEG/PSG 样本，Adapter 待实现
NWB、FIF 计划中 计划通过可选 Python Worker 支持

当前渲染遵循 voxel 存储顺序，尚未根据 qform/sform 重新排列解剖方向。NeuroPreviewer 适用于科研数据检查和开发测试，不能用于临床判读或诊断。

快速开始

环境要求

  • Node.js ^22.19.0 或 >=24.0.0
  • npm 与 pnpm
  • DeepSeek Harness 0.1.0-rc.6

从 npm 安装

dsh plugin --profile web add @brainpilot/[email protected]
dsh --profile web --dump-config
dsh --profile web

从源码构建并安装

git clone https://github.com/NeuroAIHub/NeuroPreviewer.git
cd NeuroPreviewer
npm install
npm run check

dsh plugin --profile web add "$(pwd)"
dsh --profile web --dump-config
dsh --profile web

导出的配置中应当包含：

- id: neuro-previewer
  name: '@brainpilot/dsh-neuro-previewer'
  config:
    maxFileBytes: 268435456
    maxSlicePixels: 4194304

使用 neuro_preview

工具调用示例：

{
  "path": "/absolute/path/to/image.nii",
  "axis": "axial",
  "index": 48,
  "volume": 0
}
参数 必需 默认值 说明
path 是 — DSH 文件系统可访问的 .nii 文件路径
axis 否 axial axial、coronal 或 sagittal
index 否 中央切片 零基切片序号
volume 否 0 4D 数据的零基 volume 序号

即使没有 Web extension，工具仍会返回文本摘要，包括维度、体素大小、数据类型、切片位置、强度范围和警告。

使用真实神经科学数据测试

真实数据会下载到已被 Git 忽略的 test-data/real/，不会进入代码仓库或 npm 包。所有下载文件都会通过 scripts/real-data.sha256 校验。

下载完整语料库（约 190 MiB）并执行真实数据冒烟测试：

npm run data:download
npm run test:real

也可以按格式分别下载：

bash scripts/download-real-data.sh nifti
bash scripts/download-real-data.sh edf
bash scripts/download-real-data.sh brainvision
bash scripts/download-real-data.sh eeglab
bash scripts/download-real-data.sh nwb
数据源 领域与格式 本地测试数据 当前支持
OpenNeuro ds000005 人类结构 MRI、任务 fMRI；BIDS/NIfTI 3D T1、240-volume BOLD、JSON/TSV、压缩与解压 NIfTI ✅ 两个 .nii 文件
PhysioNet Sleep-EDF Expanded 人类睡眠 EEG/PSG；EDF+ PSG 与 Hypnogram Adapter 待实现
PhysioNet EEGMMIDB 人类运动想象 EEG；EDF+ 64 通道基线记录 Adapter 待实现
OpenNeuro ds007629 人类自然阅读 EEG；BrainVision .vhdr/.vmrk/.eeg 三件套 Adapter 待实现
EEGLAB sample data 人类 EEG；.set/.fdt 与 BrainVision EEGLAB 数据对与小型 BrainVision 回归样本 Adapter 待实现
DANDI 000006 小鼠 ALM 细胞外电生理；NWB 两个小型 .nwb session Python Worker 待实现

当前冒烟测试会解析真实的 160 × 192 × 192 3D T1 图像，以及真实的 64 × 64 × 34 × 240 4D fMRI 图像。尚未支持的格式会作为明确的负向语料保留，确保未来 Adapter 面对的是真实文件，而不是掩盖兼容问题的合成替代品。

固定下载地址、许可证、引用、隐私说明和逐文件哈希见 docs/real-datasets.md。即使人类数据已经公开或去标识化，也不得尝试重新识别数据主体。

开发与验证

npm run typecheck  # TypeScript 严格类型检查
npm test           # 合成 fixture 单元测试与契约测试
npm run test:real  # 使用本地真实 NIfTI 数据进行冒烟测试
npm run build      # 构建 Host ESM 与 DSH Web client bundle
npm run check      # typecheck + unit tests + build

合成测试覆盖 header 校验、截断输入、little/big endian、三个切面、4D volume、slope/intercept、非法 index、切片像素上限、提前取消、DSH Tool 注册、文件系统 Adapter、模型文本输出和 Client presentation metadata。

架构

DSH neuro_preview Tool
        │
        ▼
NeuroPreview Interface
        │
        ├── NIfTI Adapter（当前）
        ├── EDF / BrainVision Adapter（计划）
        └── Python Worker Adapter（计划：NWB/FIF/EEGLAB）
        │
        ▼
统一 PreviewDocument
        │
        ▼
DSH Web NeuroPreviewRow + Canvas

格式中立的核心模块与 DSH 集成相互分离：

  • src/core/preview.ts：定义 NeuroPreview 接口。
  • src/core/nifti.ts：检测、解析 NIfTI-1 文件并提取切片。
  • src/dsh/source.ts：将 DSH ctx.fs 转换为受限的 BinarySource。
  • src/index.ts：注册 Host 工具及面向模型的输出。
  • src/client.tsx：实现 DSH Web 工具卡片。

安全与资源限制

  • 仅通过 DSH ctx.fs 进行只读文件访问。
  • 默认单文件上限为 256 MiB。
  • 默认单切片上限为 4,194,304 像素。
  • 所有由 header 派生的维度、偏移和乘法都会进行安全整数检查。
  • 解析支持通过 AbortSignal 取消。
  • 浏览器仅接收一张归一化灰度切片，不会接收完整体数据。
  • DSH 当前文件系统接口尚不支持 byte-range read，因此 Host 会在配置的文件上限内读取完整文件。

路线图

  1. .nii.gz、NIfTI-2、qform/sform 解剖方向重排和交互式切片 session。
  2. BIDS 数据集关系、JSON/TSV 表格和 events 时间线。
  3. EDF/EDF+ 与 BrainVision 多通道波形和 marker。
  4. EEGLAB .set/.fdt 支持。
  5. 面向 NWB、MNE FIF、CIFTI 和 GIFTI 的可选 Python Worker。

许可

NeuroPreviewer 使用 MIT License 开源。真实测试数据不随源代码再分发，并继续受各自原始许可证、引用要求和隐私条款约束。