docs: define recoverable semantic recall architecture

Author: MarkShawn2020

.github/workflows/release.yml

@@ -3,15 +3,15 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Tag to build (e.g., v0.40.1)'
+        description: "Tag to build (e.g., v0.40.1)"
         required: true
         type: string
       target:
-        description: 'Target to build'
+        description: "Target to build"
         required: false
         default: all
         type: choice
@@ -207,8 +207,8 @@ jobs:
           workspaces: src-tauri
           cache-bin: false
           # A release bump updates the root package entry in Cargo.lock, but it
-          # does not require recompiling Tantivy/LanceDB and the rest of the
-          # dependency graph. Keep one dependency cache per Rust host and let
+          # does not require recompiling the unchanged dependency graph. Keep
+          # one dependency cache per Rust host and let
           # Cargo's fingerprints rebuild only crates whose inputs changed.
           shared-key: ataru-release-dependencies
           add-rust-environment-hash-key: false

docs/adr/0002-semantic-recall-background-hybrid-pipeline.md

@@ -0,0 +1,56 @@
+# ADR-0002：语义召回采用可恢复的后台混合检索管线
+
+## 状态
+
+已接受；分阶段实施。
+
+## 背景
+
+Ataru 是本地优先的 AI 对话召回器。关键词检索必须开箱即用，且不应要求用户配置模型、网络或远程凭据。
+
+实际抽样显示，2,539 个来源会话约有 119,651 个候选片段，需要约 3,740 批远程 Embedding 请求。一次性前台全量构建会长时间占用网络与进程，也无法清楚说明进度、可恢复性和数据外发边界。
+
+## 决策
+
+1. 默认路径保持本地关键词检索：Tantivy + Jieba，语义召回保持高级选项并默认关闭。
+2. 用户明确启用远程 Embedding 后，初始化作为后台作业执行；作业支持暂停、恢复、取消、增量补齐与断点续跑，搜索页面始终保留关键词结果。
+3. 首次初始化提供范围选择：最近会话、当前项目、收藏内容或全部历史。UI 先显示本地抽样估算的片段数、请求批次、预计时间、数据外发范围和配置的模型。
+4. 每个语义条目使用稳定身份：`projectId/sessionId/runIndex/turnId`、来源路径、来源 mtime、内容哈希、分块策略版本与 Embedding 模型版本。来源或策略变化时，只重建受影响条目。
+5. 查询执行两路召回：关键词 Top-K 与向量 Top-K 并行，使用 RRF 融合。仅在融合后的少量候选上运行可选 reranker；远程语义超时或索引未就绪时，直接降级为关键词结果。
+6. SQLite 保留为元数据、队列、任务检查点和向量持久化的唯一默认存储。当前向量读取内存的穷举搜索只作为中等规模过渡；达到实际延迟或内存门槛后，再以基准决定是否采用打包的本地 ANN 实现。
+
+## 后果
+
+### 正面
+
+- 小型安装仍有即时、零配置的本地检索。
+- 长历史不会在一次点击后变成数小时的前台等待。
+- 用户能理解哪些内容会发送到 Embedding 服务，并可随时停止。
+- 关键词、自然语言与中英文混合检索都有明确的召回路径。
+
+### 代价
+
+- 需要任务状态、检查点、失效检测和进度事件，索引实现比一次性重建更复杂。
+- 混合检索与 rerank 必须由固定评测集和 TTCR 指标持续校准。
+- 本地 ANN 扩展会增加跨平台打包与更新验证成本，因此不在当前版本预先引入。
+
+## 备选方案
+
+### 一次性全量语义初始化
+
+拒绝。初次体验和失败恢复较差，且会使查询路径隐式触发长任务。
+
+### 默认远程语义检索
+
+拒绝。它破坏本地优先与零配置体验，也不能让用户在发送历史内容前作出明确选择。
+
+### 立即引入独立向量数据库
+
+拒绝。当前规模和单机桌面产品不需要新的服务运维面；先测量 SQLite 过渡方案的真实内存与查询延迟。
+
+## 验收门槛
+
+- 索引作业可在应用退出后从已提交批次继续，重复运行不会重复发送未变更内容。
+- 搜索输入和关键词结果在作业运行时保持可用。
+- UI 展示处理数、待处理数、失败数、当前范围、可复制诊断与暂停/继续/取消入口。
+- Hybrid p95、Recall@10、MRR@10 与 TTCR 使用固定的中英文对话评测集回归验证。