1. 环境搭建
目标：克隆仓库、安装依赖、启动开发服务器，并确认测试通过。
克隆与安装
git clone <repo-url> freebci-daq
cd freebci-daq
npm install
目录结构（第一眼）
freebci-daq/
├── src/
│ ├── ai/ # AI 管线（兼容 OpenAI 接口）
│ ├── algorithms/ # 参与度指数公式
│ ├── analysis/ # FFT、IIR 滤波、导联脱落检测
│ ├── components/ # React 面板与 UI 原语
│ │ └── ui/ # Button、Card、Field、StatusDot 等
│ ├── config/ # EEG 与串口常量
│ ├── focus/ # 专注度校准状态机
│ ├── hooks/ # useAcquisitionActions（串口状态机 + refs）
│ ├── serial/ # Web Serial 适配器、协议解析器
│ ├── state/ # 观察者总线（rawWaveformBus、filteredWaveformBus）
│ ├── store/ # Zustand stores（eeg、ai）
│ ├── transport/ # 传输抽象层
│ ├── types/ # TypeScript 类型定义
│ └── utils/ # 辅助函数（如 tuningStorage）
├── tests/ # Vitest 测试文件
├── docs/ # 用户文档 + 开发文档（当前所在位置）
├── TUNING.md # 参数调优指南
├── AGENTS.md # 贡献者说明
└── .env.example # 环境变量模板
启动开发服务器
npm run dev
# → http://localhost:5173
这个应用是一个静态单页应用（SPA），没有后端，也没有 SSR。Vite 会在 5173 端口提供 React 应用。
运行测试
npm test # typecheck + 单元测试（23 个文件，162 个测试）
npm run test:unit # 仅运行单元测试
npm run typecheck # tsc --noEmit（只检查 src/，不含 tests/）
运行单个测试
npx vitest run tests/serialEegProtocol.test.ts
npx vitest run -t "parses a valid packet"
生产构建
npm run build # typecheck + vite build → dist/
npm run preview # 在本地 4173 端口预览 dist/
配置环境变量
cp .env.example .env
# 按你的硬件场景修改 .env（参见 TUNING.md）
所有 VITE_* 变量都会在构建时内联进产物。运行时如果 localStorage 中存在高级调参面板的覆盖值，它们会优先于 .env 生效。
验证一切正常
npm test && npm run build
# 预期：23 个测试文件通过，构建成功并输出 dist/