# NeuroPreviewer

[![npm version](https://img.shields.io/npm/v/%40brainpilot%2Fdsh-neuro-previewer)](https://www.npmjs.com/package/@brainpilot/dsh-neuro-previewer)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![DSH plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-5B5BD6)](https://github.com/deepseek-ai/deepseek-harness)

[English](README.md) | **简体中文**

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

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

`@brainpilot/dsh-neuro-previewer` · [GitHub](https://github.com/NeuroAIHub/NeuroPreviewer) · [MIT License](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 安装

```bash
dsh plugin --profile web add @brainpilot/dsh-neuro-previewer@0.1.0
dsh --profile web --dump-config
dsh --profile web
```

### 从源码构建并安装

```bash
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
```

导出的配置中应当包含：

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

## 使用 `neuro_preview`

工具调用示例：

```json
{
  "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](scripts/real-data.sha256) 校验。

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

```bash
npm run data:download
npm run test:real
```

也可以按格式分别下载：

```bash
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](docs/real-datasets.md)。即使人类数据已经公开或去标识化，也不得尝试重新识别数据主体。

## 开发与验证

```bash
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。

## 架构

```text
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](LICENSE) 开源。真实测试数据不随源代码再分发，并继续受各自原始许可证、引用要求和隐私条款约束。