> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elata.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# 集成路径

> 为设备集成选择合适的打包和归属方式。

请在编写适配器代码之前阅读本页。

合适的路径取决于：这个集成是否具有广泛用途、是否需要厂商 SDK 或原生桥接，以及是否会作为公开的 SDK 能力长期维护。

## 推荐的默认方式

如果该设备可能对更广泛的 Elata SDK 用户有用，请将其放在上游的 `@elata-biosciences/eeg-web-ble` 中。

这样可以集中管理传输行为，避免在多个应用中出现并行的适配器。

## 按目标选择

| 路径 | 最适合 | 原因 |
| - | - | - |
| `eeg-web-ble` 中的上游设备模块 | 设备具有广泛用途，且可通过浏览器 BLE 工作 | 公开 SDK 支持的最佳默认选择 |
| `packages/` 下的独立包 | 需要厂商 SDK、许可证限制，或 localhost/原生桥接 | 将较重的集成隔离开 |
| 应用本地适配器 | 验证概念或交付私有集成 | 不需要共享包时最快的方式 |

## 路径 1：放在上游的 `eeg-web-ble` 中

在以下情况选择此路径：

* 设备可以在浏览器中通过 Web Bluetooth 工作
* 该集成可能被多个应用复用
* 你希望传输行为只有一份共享实现

此路径通常意味着：

1. 在 BLE 包下添加设备模块
2. 复用 `BleTransport`
3. 添加模拟测试
4. 更新使用者文档和设备说明

<Check>
  这是公开、长期集成的最佳路径，能让它成为 SDK 的一等公民。
</Check>

## 路径 2：独立包

当设备需要的不仅仅是干净的浏览器 BLE 流程时，选择此路径。

典型原因：

| 情况 | 独立包的好处 |
| - | - |
| 需要许可证或较重的厂商 SDK | 让额外依赖远离主 BLE 包 |
| localhost 辅助程序或原生桥接 | 可以干净地发布针对桥接的传输层 |
| 独立的发布节奏 | 由厂商或合作方负责版本和支持 |

该包仍应暴露 `HeadbandTransport`（或其轻量封装），以便应用代码与 Elata 技术栈的其他部分保持一致。

## 路径 3：应用本地适配器

当速度比复用更重要时，选择此路径。

适用于：

* 私有的客户部署
* 快速的概念验证
* 在公开包出现之前的评估工作

即使代码保持私有，也要保持相同的协议。这样以后更容易迁移到上游。

## 决策顺序

<Steps>
  <Step title="判断集成是否应可复用">
    如果多个应用会受益，先假设走上游路径。
  </Step>

  <Step title="检查浏览器 BLE 的阻碍">
    如果 Web Bluetooth 无法工作，或需要原生桥接，请改用独立包。
  </Step>

  <Step title="确定长期支持由谁负责">
    共享支持通常属于上游。由厂商负责的发布线通常更适合独立包。
  </Step>

  <Step title="保持应用协议稳定">
    无论代码放在哪里，面向应用的协议都应是 `HeadbandTransport` 和 `HeadbandFrameV1`。
  </Step>
</Steps>

## 应避免的路径

不要仅仅因为第一个小时最容易就选择应用本地适配器。

如果集成之后需要公开，这通常会带来额外工作。

也不要把较重的、基于桥接的或需要许可证的集成塞进共享的 BLE 包。保持公开包精简。

## 相关文档

* [EEG BLE 快速上手](/cn/sdk/eeg-web-ble/getting-started)
* [传输协议](./transport-contract)
* [适配器实现](./adapter-implementation)
* [兼容性](/cn/sdk/operations/compatibility)

## 下一步

<CardGroup cols={2}>
  <Card title="传输协议" icon="arrow-right" href="./transport-contract">
    查看你所选路径仍需满足的共享接口。
  </Card>

  <Card title="协议要求" icon="arrow-right" href="./protocol-requirements">
    在实现前收集所需的协议细节。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.