{"_id":"@brainpilot/dsh-neuro-previewer","name":"@brainpilot/dsh-neuro-previewer","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@brainpilot/dsh-neuro-previewer","version":"0.1.0","description":"A read-only neuroscience data preview plugin for DeepSeek Harness (DSH)","type":"module","main":"lib/index.js","types":"lib/index.d.ts","exports":{".":{"types":"./lib/index.d.ts","default":"./lib/index.js"},"./client":"./lib/client.js","./package.json":"./package.json"},"repository":{"type":"git","url":"git+https://github.com/NeuroAIHub/NeuroPreviewer.git"},"homepage":"https://github.com/NeuroAIHub/NeuroPreviewer#readme","bugs":{"url":"https://github.com/NeuroAIHub/NeuroPreviewer/issues"},"publishConfig":{"access":"public"},"dsh":{"bundle":{"patch":"./cordis.patch.yml"},"client":{"platform":"web","inject":["@deepseek-ai/dsh-client-runtime","@deepseek-ai/dsh-client-ui-tool"]}},"scripts":{"build":"npm run clean && npm run build:host && npm run build:client","build:host":"tsdown --config tsdown.host.config.ts","build:client":"tsdown --config tsdown.client.config.ts","clean":"rm -rf lib coverage","test":"vitest run","test:watch":"vitest","test:real":"node scripts/smoke-real-data.mjs","data:download":"bash scripts/download-real-data.sh","typecheck":"tsc --noEmit","check":"npm run typecheck && npm test && npm run build","prepack":"npm run check"},"keywords":["dsh-plugin","deepseek-harness","neuroscience","nifti","neuroimaging"],"license":"MIT","engines":{"node":"^22.19.0 || >=24.0.0"},"peerDependencies":{"@deepseek-ai/cordis":"4.0.1","@deepseek-ai/dsh-client-runtime":"0.1.0-rc.6","@deepseek-ai/dsh-client-ui-tool":"0.1.0-rc.6","@deepseek-ai/dsh-fs":"0.1.0-rc.6","@deepseek-ai/dsh-tools":"0.1.0-rc.6","react":"^18.2.0"},"devDependencies":{"@deepseek-ai/cordis":"4.0.1","@deepseek-ai/dsh-client-runtime":"0.1.0-rc.6","@deepseek-ai/dsh-client-ui-tool":"0.1.0-rc.6","@deepseek-ai/dsh-fs":"0.1.0-rc.6","@deepseek-ai/dsh-tools":"0.1.0-rc.6","@types/node":"^24.0.0","@types/react":"^18.3.0","react":"^18.3.0","tsdown":"^0.22.2","typescript":"^6.0.3","vitest":"^4.1.8"},"_id":"@brainpilot/dsh-neuro-previewer@0.1.0","gitHead":"6adfd51e4edcb0ec7a7e5aed5f150ba85c2e7702","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-YN41B3GGM0TBc64J9sdZUQBYteYyMHFfui0q+fTZi6aD2iWt7aI+vgjXvRjPMZFB3YSSv0aKU1curvl3ozRZZQ==","shasum":"66a9e4a52f370250f2e83a08fafc2492144a8481","tarball":"https://registry.npmjs.org/@brainpilot/dsh-neuro-previewer/-/dsh-neuro-previewer-0.1.0.tgz","fileCount":14,"unpackedSize":98797,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBVkELUebnB/rb+OEiDSjXRVUkmzGObPLuo9I9hmRCt5AiEAg8WwB/X1qFUYFM+MYJ+GKELc7lkhMKK2m8W9DKN7HvQ="}]},"_npmUser":{"name":"gtc233","email":"pluto.gtc@gmail.com"},"directories":{},"maintainers":[{"name":"gtc233","email":"pluto.gtc@gmail.com"},{"name":"haoxuanlithucai","email":"hx-li25@mails.tsinghua.edu.cn"},{"name":"fxde42","email":"fxde42@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-neuro-previewer_0.1.0_1786714373061_0.9243161504013984"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T13:32:52.922Z","0.1.0":"2026-08-14T13:32:53.249Z","modified":"2026-08-14T13:32:53.465Z"},"maintainers":[{"name":"gtc233","email":"pluto.gtc@gmail.com"},{"name":"haoxuanlithucai","email":"hx-li25@mails.tsinghua.edu.cn"},{"name":"fxde42","email":"fxde42@gmail.com"}],"description":"A read-only neuroscience data preview plugin for DeepSeek Harness (DSH)","homepage":"https://github.com/NeuroAIHub/NeuroPreviewer#readme","keywords":["dsh-plugin","deepseek-harness","neuroscience","nifti","neuroimaging"],"repository":{"type":"git","url":"git+https://github.com/NeuroAIHub/NeuroPreviewer.git"},"bugs":{"url":"https://github.com/NeuroAIHub/NeuroPreviewer/issues"},"license":"MIT","readme":"# NeuroPreviewer\n\n[![npm version](https://img.shields.io/npm/v/%40brainpilot%2Fdsh-neuro-previewer)](https://www.npmjs.com/package/@brainpilot/dsh-neuro-previewer)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![DSH plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-5B5BD6)](https://github.com/deepseek-ai/deepseek-harness)\n\n[English](README.md) | **简体中文**\n\n> 直接在 DeepSeek Harness 中预览神经科学数据。\n\n**NeuroPreviewer 是一个面向 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 的神经科学数据预览插件。** 它以 DSH bundle 和 Web client extension 的形式安装，并非独立查看器。模型通过只读的 `neuro_preview` 工具检查本地数据，DSH Web 客户端则使用专用卡片呈现预览结果。\n\n`@brainpilot/dsh-neuro-previewer` · [GitHub](https://github.com/NeuroAIHub/NeuroPreviewer) · [MIT License](LICENSE)\n\n> **兼容性：** `0.1.0` 版本面向 DeepSeek Harness `0.1.0-rc.6`。DSH 仍处于开发者预览阶段，后续可能引入不兼容的接口变更。\n\n## 为什么选择 NeuroPreviewer？\n\nNeuroPreviewer 让 DSH 智能体能够安全、轻量地了解神经科学文件的基本信息，而不必把完整数据集发送到浏览器。Host 插件通过 DSH 文件系统接口读取并校验文件，在明确的资源上限内生成二维预览，再返回结构化元数据和适合 Web 显示的灰度图像。\n\n当前版本优先保证可复现性、明确的资源限制，以及 Web 客户端不可用时仍然有效的文本输出。\n\n## 当前能力\n\n| 能力 | 状态 | 说明 |\n| --- | --- | --- |\n| NIfTI-1 单文件 `.nii` | ✅ | 校验 `sizeof_hdr=348` 与 `n+1` magic |\n| 3D MRI | ✅ | axial、coronal、sagittal 三个切面 |\n| 4D fMRI | ✅ | 可指定零基 `volume` |\n| 数值类型 | ✅ | `uint8/int8/int16/uint16/int32/uint32/float32/float64` |\n| 强度处理 | ✅ | 应用 `scl_slope`/`scl_inter`，使用 2%–98% 分位窗 |\n| 大小端 | ✅ | little-endian 与 big-endian |\n| DSH Web 预览卡片 | ✅ | Canvas 灰度图、维度、类型、切面和强度范围 |\n| `.nii.gz`、NIfTI-2 | 计划中 | 已准备真实样本，尚未实现解压与解析 |\n| BIDS 元数据、CSV/TSV | 计划中 | 已准备真实 BIDS sidecar 和 events 文件 |\n| EDF/EDF+、BrainVision、EEGLAB | 计划中 | 已准备真实 EEG/PSG 样本，Adapter 待实现 |\n| NWB、FIF | 计划中 | 计划通过可选 Python Worker 支持 |\n\n当前渲染遵循 voxel 存储顺序，尚未根据 qform/sform 重新排列解剖方向。NeuroPreviewer 适用于科研数据检查和开发测试，不能用于临床判读或诊断。\n\n## 快速开始\n\n### 环境要求\n\n- Node.js `^22.19.0` 或 `>=24.0.0`\n- npm 与 pnpm\n- DeepSeek Harness `0.1.0-rc.6`\n\n### 从 npm 安装\n\n```bash\ndsh plugin --profile web add @brainpilot/dsh-neuro-previewer@0.1.0\ndsh --profile web --dump-config\ndsh --profile web\n```\n\n### 从源码构建并安装\n\n```bash\ngit clone https://github.com/NeuroAIHub/NeuroPreviewer.git\ncd NeuroPreviewer\nnpm install\nnpm run check\n\ndsh plugin --profile web add \"$(pwd)\"\ndsh --profile web --dump-config\ndsh --profile web\n```\n\n导出的配置中应当包含：\n\n```yaml\n- id: neuro-previewer\n  name: '@brainpilot/dsh-neuro-previewer'\n  config:\n    maxFileBytes: 268435456\n    maxSlicePixels: 4194304\n```\n\n## 使用 `neuro_preview`\n\n工具调用示例：\n\n```json\n{\n  \"path\": \"/absolute/path/to/image.nii\",\n  \"axis\": \"axial\",\n  \"index\": 48,\n  \"volume\": 0\n}\n```\n\n| 参数 | 必需 | 默认值 | 说明 |\n| --- | --- | --- | --- |\n| `path` | 是 | — | DSH 文件系统可访问的 `.nii` 文件路径 |\n| `axis` | 否 | `axial` | `axial`、`coronal` 或 `sagittal` |\n| `index` | 否 | 中央切片 | 零基切片序号 |\n| `volume` | 否 | `0` | 4D 数据的零基 volume 序号 |\n\n即使没有 Web extension，工具仍会返回文本摘要，包括维度、体素大小、数据类型、切片位置、强度范围和警告。\n\n## 使用真实神经科学数据测试\n\n真实数据会下载到已被 Git 忽略的 `test-data/real/`，不会进入代码仓库或 npm 包。所有下载文件都会通过 [scripts/real-data.sha256](scripts/real-data.sha256) 校验。\n\n下载完整语料库（约 190 MiB）并执行真实数据冒烟测试：\n\n```bash\nnpm run data:download\nnpm run test:real\n```\n\n也可以按格式分别下载：\n\n```bash\nbash scripts/download-real-data.sh nifti\nbash scripts/download-real-data.sh edf\nbash scripts/download-real-data.sh brainvision\nbash scripts/download-real-data.sh eeglab\nbash scripts/download-real-data.sh nwb\n```\n\n| 数据源 | 领域与格式 | 本地测试数据 | 当前支持 |\n| --- | --- | --- | --- |\n| OpenNeuro `ds000005` | 人类结构 MRI、任务 fMRI；BIDS/NIfTI | 3D T1、240-volume BOLD、JSON/TSV、压缩与解压 NIfTI | ✅ 两个 `.nii` 文件 |\n| PhysioNet Sleep-EDF Expanded | 人类睡眠 EEG/PSG；EDF+ | PSG 与 Hypnogram | Adapter 待实现 |\n| PhysioNet EEGMMIDB | 人类运动想象 EEG；EDF+ | 64 通道基线记录 | Adapter 待实现 |\n| OpenNeuro `ds007629` | 人类自然阅读 EEG；BrainVision | `.vhdr/.vmrk/.eeg` 三件套 | Adapter 待实现 |\n| EEGLAB sample data | 人类 EEG；`.set/.fdt` 与 BrainVision | EEGLAB 数据对与小型 BrainVision 回归样本 | Adapter 待实现 |\n| DANDI `000006` | 小鼠 ALM 细胞外电生理；NWB | 两个小型 `.nwb` session | Python Worker 待实现 |\n\n当前冒烟测试会解析真实的 `160 × 192 × 192` 3D T1 图像，以及真实的 `64 × 64 × 34 × 240` 4D fMRI 图像。尚未支持的格式会作为明确的负向语料保留，确保未来 Adapter 面对的是真实文件，而不是掩盖兼容问题的合成替代品。\n\n固定下载地址、许可证、引用、隐私说明和逐文件哈希见 [docs/real-datasets.md](docs/real-datasets.md)。即使人类数据已经公开或去标识化，也不得尝试重新识别数据主体。\n\n## 开发与验证\n\n```bash\nnpm run typecheck  # TypeScript 严格类型检查\nnpm test           # 合成 fixture 单元测试与契约测试\nnpm run test:real  # 使用本地真实 NIfTI 数据进行冒烟测试\nnpm run build      # 构建 Host ESM 与 DSH Web client bundle\nnpm run check      # typecheck + unit tests + build\n```\n\n合成测试覆盖 header 校验、截断输入、little/big endian、三个切面、4D volume、slope/intercept、非法 index、切片像素上限、提前取消、DSH Tool 注册、文件系统 Adapter、模型文本输出和 Client presentation metadata。\n\n## 架构\n\n```text\nDSH neuro_preview Tool\n        │\n        ▼\nNeuroPreview Interface\n        │\n        ├── NIfTI Adapter（当前）\n        ├── EDF / BrainVision Adapter（计划）\n        └── Python Worker Adapter（计划：NWB/FIF/EEGLAB）\n        │\n        ▼\n统一 PreviewDocument\n        │\n        ▼\nDSH Web NeuroPreviewRow + Canvas\n```\n\n格式中立的核心模块与 DSH 集成相互分离：\n\n- `src/core/preview.ts`：定义 `NeuroPreview` 接口。\n- `src/core/nifti.ts`：检测、解析 NIfTI-1 文件并提取切片。\n- `src/dsh/source.ts`：将 DSH `ctx.fs` 转换为受限的 `BinarySource`。\n- `src/index.ts`：注册 Host 工具及面向模型的输出。\n- `src/client.tsx`：实现 DSH Web 工具卡片。\n\n## 安全与资源限制\n\n- 仅通过 DSH `ctx.fs` 进行只读文件访问。\n- 默认单文件上限为 256 MiB。\n- 默认单切片上限为 4,194,304 像素。\n- 所有由 header 派生的维度、偏移和乘法都会进行安全整数检查。\n- 解析支持通过 `AbortSignal` 取消。\n- 浏览器仅接收一张归一化灰度切片，不会接收完整体数据。\n- DSH 当前文件系统接口尚不支持 byte-range read，因此 Host 会在配置的文件上限内读取完整文件。\n\n## 路线图\n\n1. `.nii.gz`、NIfTI-2、qform/sform 解剖方向重排和交互式切片 session。\n2. BIDS 数据集关系、JSON/TSV 表格和 events 时间线。\n3. EDF/EDF+ 与 BrainVision 多通道波形和 marker。\n4. EEGLAB `.set/.fdt` 支持。\n5. 面向 NWB、MNE FIF、CIFTI 和 GIFTI 的可选 Python Worker。\n\n## 许可\n\nNeuroPreviewer 使用 [MIT License](LICENSE) 开源。真实测试数据不随源代码再分发，并继续受各自原始许可证、引用要求和隐私条款约束。\n","readmeFilename":"README.zh-CN.md","_rev":"1-35e29a84c0228232cf54b04df448f2f3"}