Merge origin/main into feat/export-service
同步 main（054f704），解决 contracts.py / main.py / README.md / 技术栈说明 的合并冲突。 - contracts.py：保留 pydantic 多行导入并新增 RequestOverride - main.py：合并 lifespan（导出孤儿清理 + 转写/本地模型生命周期） - README.md / 技术栈说明：文档取 main 最新版本 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Claude Code
@@ -5,7 +5,7 @@
|
||||
> 适用范围：桌面客户端、本地知识库、RAG、Agent、Skill、多模型接入、多模态处理与可选云同步
|
||||
> 目标读者：前端、Rust 桌面端、Python AI Core、算法、测试与后续接手项目的开发成员
|
||||
|
||||
> 实施状态更新：2026-09-04。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段已完成 Vue Web 联调前端、FastAPI、Knowledge/Retrieval、Agent/Tool/Permission、Skill/Plugin 声明式运行时、Mock/OpenAI-Compatible/Ollama Provider、DeepSeek/OpenAI 预设、模型发现及开发阶段 Fernet 凭据存储。Web Workspace 已通过 FastAPI 接入后端配置的真实单 Vault；第二阶段 Agent Trace 持久化、分页快照、可恢复 SSE、stdio MCP Bridge、隔离 Plugin Host、Plugin Command 与 Plugin Settings/Secret Contract 已完成。阶段 E 已完成 Responses/Anthropic 协议、国内 logo 预设、Provider 配置恢复和 Embedding/转写/声纹 API 路由；本地语音模型仍为阶段 F 接口预留。RAG Benchmark 检索评测（Dataset 加载、异步运行、SSE 进度、指标聚合与报告）已完成，Agent Benchmark 暂缓。后续继续接入真实音频处理、文档导出、主题包、Trace 可视化、Mermaid 和函数图像。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统和 Sync Server 仍未实现。
|
||||
> 实施状态更新：2026-09-05。本文同时包含目标架构、当前实现和第二阶段接口基线。第一阶段及第二阶段 A～F 工程范围已经合并到 `main`：Vue Web 联调前端、FastAPI、真实单 Vault、Knowledge/Retrieval、知识库 Chat、Agent/Tool/Permission、Skill/Plugin、MCP 配置与调用、Provider 多协议与国内 logo 预设、RAG Benchmark、本地 Embedding、音频转写、片段级声纹聚类、CPU/CUDA 运行管理及用量诊断均已实现。当前生产 Embedding 使用固定 revision 的 Bekko A8M，Granite 97M Multilingual r2 可选；音频本地链路使用 Qwen3-ASR-0.6B 与 ERes2NetV2。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统、生产级 MCP 沙箱和 Sync Server 仍未实现；逐字强制对齐、重叠语音分离及带标注长音频质量验收尚未完成。
|
||||
|
||||
---
|
||||
|
||||
@@ -47,17 +47,17 @@
|
||||
| 元数据 | SQLite | 笔记元数据、Block、标签、会话、Trace、任务、索引状态 |
|
||||
| 全文检索 | SQLite FTS5 | 关键词、标题、术语、标签等文本检索 |
|
||||
| 向量检索 | sqlite-vec + VectorStore | 本地语义检索 |
|
||||
| Embedding | 可插拔 EmbeddingProvider，默认本地 BGE-M3 类模型 | 为 Note Block 生成向量 |
|
||||
| Reranker | BGE reranker 类 Cross-Encoder | 对候选检索结果进行精排 |
|
||||
| Embedding | 可插拔 EmbeddingProvider；默认 Bekko A8M，可选 Granite 97M Multilingual r2 | 为 Note Block 生成 384 维向量，并按模型空间隔离索引 |
|
||||
| Reranker | 当前 `LexicalReranker`；保留 `RerankerProvider` 替换边界 | 对 RRF 候选进行词面重叠与原始分数加权精排 |
|
||||
| Agent | 自研 Agent Runtime | 模型推理、工具选择、工具调用、结果回灌、运行控制 |
|
||||
| Skill | 自研声明式 Skill Runtime | 复用提示词、工具集合、权限和检索配置 |
|
||||
| Plugin | 自研 Plugin Runtime + Plugin Manifest + MCP Bridge | 扩展程序能力、Tool、外部服务集成和受控 UI Contribution |
|
||||
| Theme | Theme Manifest + Design Token + 受限 CSS | 本地主题包导入、预览、启停与社区格式兼容 |
|
||||
| LLM | 自研 Provider Adapter | 统一不同模型服务商的输入、输出、Streaming 与 Tool Calling |
|
||||
| 模型协议 | OpenAI Responses / Chat Completions compatible / Anthropic Messages / Ollama | 用户自定义模型接入 |
|
||||
| ASR | faster-whisper | 音频转写 |
|
||||
| 说话人分离 | pyannote.audio | 课堂、会议等多人音频中的说话人区分 |
|
||||
| 情感识别 | emotion2vec | 可选音频分析能力 |
|
||||
| ASR | Qwen3-ASR-0.6B | 本地音频转写与语言识别，返回片段级时间边界 |
|
||||
| 声纹匹配与片段聚类 | ERes2NetV2 中文声纹模型 | 两段音频相似度与转写片段 speaker 聚类 |
|
||||
| 情感识别 | Provider 接口预留，尚未选择运行模型 | 后续可选音频分析能力 |
|
||||
| 文档导出 | Document AST + Exporter Adapter | Markdown 到 HTML、PDF、DOCX，并保留图表、公式和代码块 |
|
||||
| 密钥存储 | 当前 Fernet 开发存储；目标 Tauri Stronghold | Web 联调期避免明文落盘，桌面集成后保存模型 API Key 和同步凭证 |
|
||||
| 云同步 | 独立 Sync Server：FastAPI + PostgreSQL + S3/MinIO | 可选自托管，多设备 Vault 同步、版本管理和设备管理 |
|
||||
@@ -675,13 +675,15 @@ class EmbeddingProvider(Protocol):
|
||||
async def embed_query(self, query: str) -> list[float]: ...
|
||||
```
|
||||
|
||||
目标默认配置使用本地 BGE-M3 类模型。当前第一阶段实现是 128 维 `HashEmbeddingProvider`，只用于离线跑通向量存储、索引更新和 Hybrid 链路，不代表真实语义召回质量。第二阶段接入真实 Embedding 时继续实现相同接口，上层 Retrieval Core 不依赖具体模型运行时。
|
||||
生产默认配置使用 `hotchpotch/bekko-embedding-v1-a8m`，可选 `ibm-granite/granite-embedding-97m-multilingual-r2`，两者均输出 384 维向量。模型权重使用代码目录中审阅过的固定 revision，下载后校验，推理阶段离线读取。`HashEmbeddingProvider` 仅供测试显式注入，不进入生产检索回退。
|
||||
|
||||
Embedding 支持 Provider API 与本地模型路由：配置可用 API 时优先调用，响应失败或无效时回退本地模型；未配置 API 时直接使用本地模型；`local_only` 禁止远程调用。索引和查询冻结同一份模型与设备配置，并记录实际来源和回退原因。
|
||||
|
||||
索引记录需要保存 embedding model id、模型版本、向量维度和归一化方式。用户更换模型或任一索引兼容字段变化后，索引服务必须将旧向量标记为不可用并要求重建，禁止把不同模型生成的向量写入同一索引空间。
|
||||
|
||||
### 9.5 RRF 与 Reranker
|
||||
|
||||
FTS5 和 Vector Search 分别产生候选集合，经 RRF 进行排名融合。融合后的候选交给 BGE reranker 类 Cross-Encoder 进行精排。
|
||||
FTS5 和 Vector Search 分别产生候选集合，经 RRF 进行排名融合。当前 `LexicalReranker` 使用词面重叠和归一化原始分数做确定性精排；`RerankerProvider` 接口保留后续替换 Cross-Encoder 的边界，当前阶段没有随本地模型运行环境安装独立 Reranker 权重。
|
||||
|
||||
初始参数可以采用：
|
||||
|
||||
@@ -1268,7 +1270,7 @@ enabled
|
||||
→ 返回连接测试结果
|
||||
```
|
||||
|
||||
当前设置页已经提供 OpenAI、DeepSeek 与 Ollama 预设，保存后通过 `/api/providers/{provider_id}/models` 自动发现模型。Credential API 只返回配置状态，不提供任何明文读取接口。
|
||||
当前设置页提供 OpenAI、DeepSeek、通义千问、Kimi、智谱、豆包、腾讯混元、百度千帆、MiniMax、阶跃星辰、硅基流动和 Ollama 等带 logo 预设，也支持自定义兼容服务。保存后通过 `/api/providers/{provider_id}/models` 自动发现模型；聊天、Embedding、转写和声纹能力可独立绑定。Credential API 只返回配置状态，不提供任何明文读取接口。
|
||||
|
||||
日志中不记录完整 API Key。请求异常信息在进入前端前过滤 Authorization Header 和密钥片段。
|
||||
|
||||
@@ -1282,16 +1284,19 @@ enabled
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Audio"] --> D["pyannote.audio"]
|
||||
D --> S["Speaker Segments"]
|
||||
S --> W["faster-whisper"]
|
||||
W --> T["Timestamped Transcript"]
|
||||
A["Audio"] --> X["PyAV Decode · 16 kHz Mono"]
|
||||
X --> V["Energy Segmentation"]
|
||||
V --> W["Qwen3-ASR-0.6B"]
|
||||
V --> S["ERes2NetV2 Embeddings"]
|
||||
W --> T["Segment Transcript"]
|
||||
S --> SC["Speaker Clustering"]
|
||||
SC --> T
|
||||
T --> C["Content Structuring"]
|
||||
C --> M["Markdown Note"]
|
||||
M --> I["Index Pipeline"]
|
||||
```
|
||||
|
||||
pyannote.audio 生成说话人区间；faster-whisper 对各区间进行转写。最终 Transcript 至少包含：
|
||||
PyAV 将音轨解码为 16 kHz 单声道，能量分段后由 Qwen3-ASR-0.6B 转写；ERes2NetV2 为片段提取 192 维声纹并按相似度聚类。最终 Transcript 至少包含：
|
||||
|
||||
```text
|
||||
speaker
|
||||
@@ -1317,7 +1322,9 @@ status
|
||||
error
|
||||
```
|
||||
|
||||
`pyannote.audio` 和 `faster-whisper` 通过独立 Adapter 加载，模型下载、设备选择、精度、批量大小和缓存目录由配置管理。缺少说话人模型时可以只返回时间戳转写，但必须明确标记 diarization 不可用；模型失败不能生成伪造的 completed 结果。
|
||||
本地模型由独立运行环境和子进程按需加载，模型下载、固定 revision、设备、超时、内存预算和缓存目录由配置管理。转写与声纹也可以绑定 Provider API；API 无配置或返回无效时回退本地，`local_only` 请求禁止远程调用。缺少声纹模型时只能返回没有 speaker 的片段并明确标记 diarization 不可用，模型失败不能生成伪造的 completed 结果。
|
||||
|
||||
当前时间信息为能量分段产生的片段级边界，不是逐字强制对齐。ERes2NetV2 聚类不能处理同一片段内多人或重叠发言，因此不将当前能力描述为完整说话人分离。
|
||||
|
||||
### 14.2 OCR
|
||||
|
||||
@@ -1325,9 +1332,9 @@ OCR 作为 Media Pipeline 的输入适配能力，用于图片笔记、白板照
|
||||
|
||||
OCR 引擎在当前技术栈中尚未固定，调用接口先定义为 `OCRProvider`，具体实现完成 PoC 后确定。
|
||||
|
||||
### 14.3 emotion2vec
|
||||
### 14.3 音频情感分析
|
||||
|
||||
emotion2vec 作为音频扩展分析模块。输出可以附加到音频段元数据，不参与核心 RAG 索引和 Agent 启动流程。
|
||||
音频情感分析保留 Provider/Adapter 扩展位置，当前阶段未选定或集成本地运行模型。未来输出可以附加到片段元数据，但不参与核心 RAG 索引和 Agent 启动流程。
|
||||
|
||||
### 14.4 Document AST 与多格式导出
|
||||
|
||||
@@ -1630,7 +1637,7 @@ Agent 中间运行状态
|
||||
设备级性能配置
|
||||
```
|
||||
|
||||
例如 Client A 使用本地 BGE-M3，Client B 使用另一种 Embedding Provider。服务器只同步 Markdown。Client B 收到文件后按照自己的 Embedding 配置生成向量，并写入本机 VectorStore。
|
||||
例如 Client A 使用本地 Bekko A8M，Client B 使用 Granite 或 API Embedding Provider。服务器只同步 Markdown。Client B 收到文件后按照自己的 Embedding 配置生成向量，并写入本机对应的隔离向量空间。
|
||||
|
||||
### 16.5 多设备同步流程
|
||||
|
||||
@@ -2010,7 +2017,7 @@ SQLite
|
||||
Git
|
||||
```
|
||||
|
||||
Rust Toolchain 与 Tauri CLI 只在桌面容器阶段安装。当前轻量 Embedding/Reranker 不要求 CUDA；接入 faster-whisper、pyannote.audio 或真实本地模型时再按所选运行时增加 CPU/GPU 依赖。
|
||||
Rust Toolchain 与 Tauri CLI 只在桌面容器阶段安装。本地模型依赖与 API 环境分离，默认使用 CPU；Windows 可以通过设置页或 `backend/scripts/install-model-runtime.ps1 -Device cuda` 显式安装 PyTorch 2.9.1 cu128 运行组件。CPU 与 CUDA 环境可并存，安装脚本不安装或修改 NVIDIA 驱动，也不要求 vLLM 或 FlashAttention。
|
||||
|
||||
### 19.2 本地开发
|
||||
|
||||
@@ -2233,10 +2240,11 @@ Agent Runtime
|
||||
|
||||
```text
|
||||
Audio
|
||||
→ pyannote.audio
|
||||
→ Speaker Segments
|
||||
→ faster-whisper
|
||||
→ Timestamped Transcript
|
||||
→ PyAV 解码为 16 kHz 单声道
|
||||
→ 能量分段
|
||||
→ Qwen3-ASR-0.6B 片段转写
|
||||
→ ERes2NetV2 声纹提取与片段聚类
|
||||
→ 片段级时间戳 Transcript
|
||||
→ Content Structuring
|
||||
→ Markdown
|
||||
→ Note Core
|
||||
@@ -2333,14 +2341,17 @@ Markdown Workspace
|
||||
|
||||
第一阶段 Plugin Runtime 已完成安装、启用、停用、权限和声明式 Tool 注册，建立 Skill 调用 Plugin Tool 的基础链路。Command、Settings 和 MCP 执行不计入第一阶段完成项。
|
||||
|
||||
截至 2026-09-03，上述第一阶段后端链路和 Web 联调前端均已完成；第二阶段的 Workspace 去 Mock 联调、Agent Trace 持久化/恢复接口、stdio MCP Bridge / Plugin Host，以及 Plugin Command/Settings 前后端闭环也已完成。Plugin 详情页现已提供 Host 状态、重启、动态设置、Secret 管理和命令执行，全局命令面板可加载 Plugin Command。当前验证基线为后端 136 项测试、前端 32 项测试、TypeScript 类型检查及生产构建通过。向量链路当前使用 `HashEmbeddingProvider` 验证工程正确性，真实 Embedding 召回质量不属于该测试结论。
|
||||
截至 2026-09-05，上述第一阶段链路和第二阶段 A～F 工程范围均已合并。除 Workspace、Agent Trace、MCP、Plugin Command/Settings 外，当前还包含 Provider 多协议与国内预设、真实 Embedding 路由与隔离向量空间、RAG Benchmark、Qwen3-ASR 转写、ERes2NetV2 声纹匹配与片段聚类、CPU/CUDA 组件管理、请求 JSON、Token/音频用量及运行诊断。阶段 F 合并验证基线为后端 559 项测试、前端 103 项测试、TypeScript 类型检查及生产构建通过。
|
||||
|
||||
Bekko A8M 与 Granite 97M Multilingual r2 在 8 篇短文、6 条改写查询的小样本冒烟中均得到 Hit@1、Recall@5、MRR 1.0；该结果只证明中文检索闭环可运行，不足以区分质量优劣。CPU/CUDA 已完成短音频到知识库检索的真实闭环；带标注课程长音频的 WER/CER、DER、重叠语音和吞吐仍需专项验收。
|
||||
|
||||
第二阶段在既有 Contract 上接入：
|
||||
|
||||
```text
|
||||
Multimodal
|
||||
├── faster-whisper
|
||||
└── pyannote.audio
|
||||
├── Qwen3-ASR-0.6B
|
||||
├── ERes2NetV2 片段声纹聚类
|
||||
└── API → 本地模型回退路由
|
||||
|
||||
Extension / Model
|
||||
├── MCP Bridge（stdio 首版已实现）
|
||||
@@ -2365,7 +2376,7 @@ Frontend Extension
|
||||
└── Plugin Settings UI
|
||||
```
|
||||
|
||||
上述列表描述第二阶段技术范围，其中 stdio MCP Bridge、Plugin Command Contribution、Plugin Settings Contribution 后端 Contract 与 Markdown → HTML 导出已实现，其余能力以各自开发说明的状态为准。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。
|
||||
上述列表描述第二阶段技术范围。多模态、MCP Bridge、Plugin Command/Settings、RAG Benchmark、Provider 增强与 Markdown → HTML 导出已经实现；Agent Benchmark、PDF/DOCX 导出、Mermaid/函数图像完整编辑导出及社区主题包仍以各自开发说明的状态为准。每项功能必须继续经过现有 Service、Contract、Permission 和 Adapter 边界，不因 Demo 需要在 Vue 组件、Router 或 Agent Runtime 中直接绑定第三方协议。
|
||||
|
||||
第三阶段处理：
|
||||
|
||||
@@ -2417,11 +2428,11 @@ Sync Server 按独立服务开发和部署，不进入桌面客户端核心启
|
||||
|
||||
## 25. 当前技术基线摘要
|
||||
|
||||
目标桌面端采用 Tauri 2、Rust、Vue 3 和 TypeScript；当前可运行形态是 Vue/Vite Web 前端加 FastAPI。用户笔记以 Markdown 和 Assets 保存在本地 Vault，SQLite 已管理笔记元数据、全文索引、向量索引、任务及 Agent Trace；Provider/Extension Registry 当前仍为内存实现。
|
||||
目标桌面端采用 Tauri 2、Rust、Vue 3 和 TypeScript；当前可运行形态是 Vue/Vite Web 前端加 FastAPI。用户笔记以 Markdown 和 Assets 保存在本地 Vault，SQLite 已管理笔记元数据、全文索引、向量索引、搜索历史、Provider 配置、任务、多模态记录及 Agent Trace；MCP Server 配置持久化到后端数据目录，运行时 Tool/Extension Registry 在进程启动后按持久配置重建。
|
||||
|
||||
Python AI Core 未来作为 Tauri Sidecar 运行，当前由开发命令独立启动，FastAPI 提供本地接口。Knowledge Core 管理笔记结构；Retrieval Core 当前通过 FTS5、`HashEmbeddingProvider`、sqlite-vec、RRF 和轻量 Reranker 跑通混合检索，真实 Embedding 与正式 Benchmark 仍待第二阶段后续接入；Agent Runtime 使用 Tool Registry 操作知识库和任务，并已持久化可供前端可视化与 Benchmark 共用的 Agent Trace Contract；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置。
|
||||
Python AI Core 未来作为 Tauri Sidecar 运行，当前由开发命令独立启动，FastAPI 提供本地接口。Knowledge Core 管理笔记结构；Retrieval Core 通过 FTS5、sqlite-vec、RRF 和 `LexicalReranker` 运行混合检索，生产 Embedding 默认使用 Bekko A8M、可选 Granite 97M Multilingual r2 或 Provider API，并按模型空间隔离索引；`HashEmbeddingProvider` 仅用于测试。RAG Benchmark 已接入版本化 Dataset、异步运行、SSE 进度、指标和报告。Agent Runtime 使用 Tool Registry 操作知识库和任务，并持久化可供前端和 Benchmark 共用的 Agent Trace Contract；Skill Runtime 将提示词、工具、权限和检索参数组装为可复用 Agent 配置。
|
||||
|
||||
当前 Plugin Runtime 支持 Manifest、生命周期、声明式白名单 Tool Contribution、Plugin Command 与 Plugin Settings/Secret，并已通过 stdio MCP Bridge 接入独立进程 Tool、专用 MCP Command Target、Host 状态与重启接口。Provider Adapter 当前实现 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama，OpenAI Responses、Anthropic Messages 等协议仍待第二阶段后续完善。多模态目标方案使用 faster-whisper、pyannote.audio 和可选 emotion2vec；当前只读取 Host 预生成 transcript。
|
||||
当前 Plugin Runtime 支持 Manifest、生命周期、声明式白名单 Tool Contribution、Plugin Command 与 Plugin Settings/Secret，并已通过 MCP Bridge 接入 stdio、Streamable HTTP 和旧 SSE Server。Provider Adapter 已实现 OpenAI Chat/OpenAI-Compatible、OpenAI Responses、Anthropic Messages 与 Ollama，并支持模型发现、独立凭据和受限自定义请求 JSON。多模态本地链路使用 PyAV、Qwen3-ASR-0.6B 和 ERes2NetV2，默认 CPU、CUDA 显式选装；API 无配置或无效时回退本地模型。当前声纹聚类只处理片段，不等同于完整说话人分离。
|
||||
|
||||
第二阶段内容输出以 Document AST、Exporter Adapter、Mermaid Renderer 和 Function Plot Renderer 为共同边界，支持 HTML、PDF、DOCX 与静态图导出。Theme Package 使用 Manifest、Design Token 和受限 CSS 实现本地导入；联网主题市场不属于本阶段核心依赖。API Key 在 Web 联调期由 Fernet 开发存储加密保存，桌面版迁移到 Tauri Stronghold。多设备同步的目标方案为独立、可自托管的 Sync Server，目前尚未实现；本地核心功能不依赖 Sync Server。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user