mirror of
https://github.com/Youzini-afk/ST-Bionic-Memory-Ecology.git
synced 2026-06-14 02:40:45 +08:00
75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# 服务器集成（Authority / st-doa）
|
||
|
||
ST-BME 可以独立运行（纯前端），也可以在检测到 st-doa/Authority 服务器时自动升级到更稳定的数据平面操作。本文档说明这套自动集成。
|
||
|
||
## 核心原则
|
||
|
||
1. **BME 独立运行是第一公民。** 没有 st-doa 时，BME 必须完整可用，优雅降级，不报错。纯前端模式显示"纯前端模式"，不是错误状态。
|
||
2. **第三方自定义 URL embedding 是主流路径。** OpenAI 兼容 `/v1/embeddings`、one-api、new-api、litellm、vLLM、llama.cpp、Ollama 桥接等，都是一等公民。embedding 默认在客户端执行（`embeddingTransportMode` 默认 `"direct"`，直连第三方 URL）。
|
||
3. **集成是自动的，不需要用户配置。** 能力探测驱动的升级/降级，没有面向用户的"服务器模式"开关。既要优雅降级（无 st-doa），也要优雅升级（有 st-doa），全程零用户干预。
|
||
|
||
> Authority 是**增强层**，不是硬依赖。它不生成 embedding——只通过 Trivium 存储/搜索向量，并要求调用方提供向量。
|
||
|
||
## 三档集成模式
|
||
|
||
| 模式 | 含义 | embedding | 存储 |
|
||
| --- | --- | --- | --- |
|
||
| **Mode A** | 纯前端（基线） | 前端生成 | 浏览器本地（IndexedDB/OPFS） |
|
||
| **Mode B** | Authority 存储增强 | 前端仍生成 | Authority 负责可靠 SQL/Trivium 持久化与诊断 |
|
||
| **Mode C** | 可选服务器端 embedding | 服务器端（**仅 opt-in**） | Authority |
|
||
|
||
Mode A 必须完全稳定（它是基线）。Mode C 是可选的、必须显式开启。
|
||
|
||
## 自动升级状态机
|
||
|
||
ST-BME 维护一个派生的 `authorityUpgradeState`，由能力探测驱动：
|
||
|
||
```
|
||
standalone → probing → shadow → candidate → enhanced → degraded
|
||
```
|
||
|
||
- **standalone**：没有 Authority，纯前端模式。
|
||
- **probing**：检测到可能的 Authority，正在探测能力。
|
||
- **shadow / candidate**：逐步确认 Authority 各项能力。
|
||
- **enhanced**：Authority 各项能力就绪，使用增强数据平面。
|
||
- **degraded**：Authority 部分能力不可用，自动回退到仍可用的层。
|
||
|
||
面板显示当前自动模式，但不提供手动切换开关。
|
||
|
||
## 能力探测
|
||
|
||
ST-BME 从 Authority 的 `/probe` 和 session 响应里读取 BME 专属能力标志：
|
||
|
||
- `bmeVectorManifestReady`
|
||
- `bmeVectorApplyReady`
|
||
- `bmeVectorApplyJobsReady`
|
||
- `bmeServerEmbeddingProbeReady`
|
||
- `bmeCandidateSearchReady`
|
||
- `bme.protocolVersion`
|
||
|
||
旧版/无 Authority 时这些默认全 false，自动走 fallback。这保证了对老 Authority 探针的向后兼容。
|
||
|
||
## 任务类型协商
|
||
|
||
Authority 的后台 job 系统只支持特定 job 类型。ST-BME 不能盲目提交。
|
||
|
||
> `shouldUseAuthorityJobs` 校验具体 job 类型是否在服务器声明的 registry 中（从 `jobs.builtinTypes` / `jobs.registry.jobTypes` / `core.health.jobRegistrySummary.jobTypes` 读取）。服务器没声明支持的 job 类型不提交，直接走直连同步。
|
||
|
||
> 空的 `supportedJobTypes: []` 表示"服务器明确不支持任何 job"；缺失/默认则表示"未知"，保持对旧探针的向后兼容。
|
||
|
||
## 向量应用端点
|
||
|
||
`POST /bme/vector-apply`：客户端生成向量后，由 Authority 执行 Trivium 批量 upsert + link。
|
||
|
||
> Authority 不碰 embedding API key。它只接收客户端生成好的向量。
|
||
|
||
> 该端点按批校验 `vectorSpaceId` / `observedDim` 一致性，拒绝混合维度，返回带类型的校验错误。
|
||
|
||
向量空间身份和维度门禁的算法见 [`../algorithms/vector-and-embedding.md`](../algorithms/vector-and-embedding.md)。
|
||
|
||
## Authority SQL 图谱存储选择
|
||
|
||
> Authority SQL 图谱持久化由 `storagePrimaryReady`（SQL + session + permission）门控，**不是** `serverPrimaryReady`（SQL + Trivium + Jobs + Blob）。
|
||
|
||
这意味着 Blob/Jobs/Trivium 降级不会禁用 SQL 持久化——SQL 图谱持久化只需要 SQL + 会话 + 权限。这条避免了"某个增强能力不可用就连主存储都不写"的过度联动。
|