From 62d2273413a11093e2586c11ea6e47144baf2408 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 19:52:21 +0800
Subject: [PATCH 1/6] =?UTF-8?q?feat(knowledge):=20v2=20Phase=203+4=20?=
 =?UTF-8?q?=E5=90=91=E9=87=8F=E6=B7=B7=E5=90=88=E6=A3=80=E7=B4=A2=E4=B8=8E?=
 =?UTF-8?q?=20AI=20Chat/Ask=20=E5=8F=8C=E6=A8=A1=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 3 — sqlite-vec 向量索引 + RRF 混合检索：
- packages/ai: 新增 embedding.ts（OpenAI 兼容 /v1/embeddings batch，重试+超时，与 chat provider 解耦）
- packages/db: loadVecExtension/toVecBuffer + vec0 延迟建表（维度发现）+ embedding_cache 去重 + searchKnn(KNN)
  + getIndexStatus 三态(hybrid/indexing/fts-only) + 顺手修 reindexTask 缺 FTS5 INSERT bug
- modules/knowledge: service drain 队列(单飞 mutex, cache 复用) + searchHybrid(FTS5+vec) + rrf.ts 纯函数(k=60)
- routes: search 切 hybrid、index-status 真实 flags、新增 GET/PUT /embedding-config(内存态, apiKey 不回显)
- 前端: api 层 + KnowledgeSection embedding baseUrl/apiKey 配置闭环

Phase 4 — AI Chat/Ask 双模式 + 三级上下文 + 引用审计：
- packages/db: ai_conversations/ai_messages 表 + createAiConversationStore(多轮持久化 + sources_json)
- modules/ai/context.ts: ContextBuilder 纯函数(权重/greedy fill/gap fill 句子边界/三明治排序)
- modules/ai/citation.ts: injectSources(稳定 sN id) + parseAndAuditCitations(丢弃未注入 id 防幻觉) + buildSources(服务端生成)
- modules/ai/service.ts: handleChat(全量上下文多轮) + handleAsk(RAG 一次性) + plainChat 降级
- app.ts: /api/ai/chat 重构委托 service，请求体扩 mode/projectId/context/conversationId，ai:done 携带 {text,sources,retrievalMode}

测试：embedding(8)、rrf(6)、context(7)、citation(5)、db vec(skipIf)、server-local 全绿
本机无 better-sqlite3 binding，vec/sqlite 专属测试 skipIf，CI 验证

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .env.example                                  |   7 +
 apps/desktop/src-tauri/Cargo.lock             | 144 +++++++-
 apps/desktop/src/api.ts                       |  49 ++-
 .../settings/sections/KnowledgeSection.vue    |  40 ++-
 apps/desktop/src/composables/useSettings.ts   |  42 ++-
 packages/ai/src/embedding.test.ts             |  98 ++++++
 packages/ai/src/embedding.ts                  | 102 ++++++
 packages/ai/src/index.ts                      |   3 +
 packages/db/package.json                      |   3 +-
 packages/db/src/db.test.ts                    |  62 ++++
 packages/db/src/index.ts                      | 309 +++++++++++++++++-
 packages/db/src/schema.ts                     |  31 +-
 packages/server-local/src/app.ts              |  65 ++--
 .../src/modules/ai/citation.test.ts           |  53 +++
 .../server-local/src/modules/ai/citation.ts   |  93 ++++++
 .../src/modules/ai/context.test.ts            |  79 +++++
 .../server-local/src/modules/ai/context.ts    | 156 +++++++++
 .../server-local/src/modules/ai/service.ts    | 210 ++++++++++++
 .../src/modules/knowledge/indexer.test.ts     |   6 +-
 .../src/modules/knowledge/mirror.test.ts      |  12 +-
 .../src/modules/knowledge/routes.ts           |  54 ++-
 .../src/modules/knowledge/rrf.test.ts         |  54 +++
 .../server-local/src/modules/knowledge/rrf.ts |  39 +++
 .../src/modules/knowledge/service.ts          | 140 +++++++-
 packages/shared/src/index.ts                  |  20 +-
 pnpm-lock.yaml                                |  54 +++
 26 files changed, 1870 insertions(+), 55 deletions(-)
 create mode 100644 packages/ai/src/embedding.test.ts
 create mode 100644 packages/ai/src/embedding.ts
 create mode 100644 packages/server-local/src/modules/ai/citation.test.ts
 create mode 100644 packages/server-local/src/modules/ai/citation.ts
 create mode 100644 packages/server-local/src/modules/ai/context.test.ts
 create mode 100644 packages/server-local/src/modules/ai/context.ts
 create mode 100644 packages/server-local/src/modules/ai/service.ts
 create mode 100644 packages/server-local/src/modules/knowledge/rrf.test.ts
 create mode 100644 packages/server-local/src/modules/knowledge/rrf.ts

diff --git a/.env.example b/.env.example
index 778dac2..4e0fb43 100644
--- a/.env.example
+++ b/.env.example
@@ -4,3 +4,10 @@ MIMO_API_KEY=
 MIMO_TTS_VOICE=茉莉
 NEO_CITY=Beijing
 NEO_SERVER_PORT=10103
+
+# Embedding provider (Phase 3) — separate from chat; DeepSeek has no embeddings.
+# The desktop UI pushes these to the sidecar via PUT /api/knowledge/embedding-config;
+# these env vars are a fallback for headless/CI runs.
+EMBEDDING_API_KEY=
+EMBEDDING_BASE_URL=https://api.openai.com
+EMBEDDING_MODEL=text-embedding-3-small
diff --git a/apps/desktop/src-tauri/Cargo.lock b/apps/desktop/src-tauri/Cargo.lock
index 381bc18..a919440 100644
--- a/apps/desktop/src-tauri/Cargo.lock
+++ b/apps/desktop/src-tauri/Cargo.lock
@@ -2058,6 +2058,7 @@ dependencies = [
  "serde_json",
  "tauri",
  "tauri-build",
+ "tauri-plugin-dialog",
  "tauri-plugin-opener",
  "tauri-plugin-wallpaper",
  "tauri-plugin-window-state",
@@ -2229,6 +2230,7 @@ checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
 dependencies = [
  "bitflags 2.13.0",
  "block2",
+ "libc",
  "objc2",
  "objc2-core-foundation",
 ]
@@ -2762,6 +2764,30 @@ dependencies = [
  "web-sys",
 ]
 
+[[package]]
+name = "rfd"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a15ad77d9e70a92437d8f74c35d99b4e4691128df018833e99f90bcd36152672"
+dependencies = [
+ "block2",
+ "dispatch2",
+ "glib-sys",
+ "gobject-sys",
+ "gtk-sys",
+ "js-sys",
+ "log",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-foundation",
+ "raw-window-handle",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+ "windows-sys 0.60.2",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.2"
@@ -3445,6 +3471,48 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "tauri-plugin-dialog"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65981abb771e74e571a38196c3baa11c459379164791eba0e67abc1a5fac9884"
+dependencies = [
+ "log",
+ "raw-window-handle",
+ "rfd",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "tauri-plugin-fs",
+ "thiserror 2.0.18",
+ "url",
+]
+
+[[package]]
+name = "tauri-plugin-fs"
+version = "2.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7ecc274121aca0c036a2b42d1cbe83d368d348f54e0bb8a735c2b1548e8f371"
+dependencies = [
+ "anyhow",
+ "dunce",
+ "glob",
+ "log",
+ "objc2-foundation",
+ "percent-encoding",
+ "schemars 0.8.22",
+ "serde",
+ "serde_json",
+ "serde_repr",
+ "tauri",
+ "tauri-plugin",
+ "tauri-utils",
+ "thiserror 2.0.18",
+ "toml 1.1.2+spec-1.1.0",
+ "url",
+]
+
 [[package]]
 name = "tauri-plugin-opener"
 version = "2.5.4"
@@ -4577,6 +4645,15 @@ dependencies = [
  "windows-targets 0.52.6",
 ]
 
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.61.2"
@@ -4610,13 +4687,30 @@ dependencies = [
  "windows_aarch64_gnullvm 0.52.6",
  "windows_aarch64_msvc 0.52.6",
  "windows_i686_gnu 0.52.6",
- "windows_i686_gnullvm",
+ "windows_i686_gnullvm 0.52.6",
  "windows_i686_msvc 0.52.6",
  "windows_x86_64_gnu 0.52.6",
  "windows_x86_64_gnullvm 0.52.6",
  "windows_x86_64_msvc 0.52.6",
 ]
 
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link 0.2.1",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
 [[package]]
 name = "windows-threading"
 version = "0.1.0"
@@ -4647,6 +4741,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.42.2"
@@ -4659,6 +4759,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
 [[package]]
 name = "windows_i686_gnu"
 version = "0.42.2"
@@ -4671,12 +4777,24 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
 
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
 [[package]]
 name = "windows_i686_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
 [[package]]
 name = "windows_i686_msvc"
 version = "0.42.2"
@@ -4689,6 +4807,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
 
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.42.2"
@@ -4701,6 +4825,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.42.2"
@@ -4713,6 +4843,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.42.2"
@@ -4725,6 +4861,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
 [[package]]
 name = "winnow"
 version = "0.5.40"
diff --git a/apps/desktop/src/api.ts b/apps/desktop/src/api.ts
index 1073967..4bafe46 100644
--- a/apps/desktop/src/api.ts
+++ b/apps/desktop/src/api.ts
@@ -1,6 +1,38 @@
-import type { ChatMessage, FocusSession, Task, TtsResult, WeatherSummary, WsMessage } from "@neo-companion/shared";
+import type {
+  AiAnswer,
+  AiRetrievalMode,
+  ChatMessage,
+  ContextLevel,
+  FocusSession,
+  IndexStatus,
+  KnowledgeSource,
+  Task,
+  TtsResult,
+  WeatherSummary,
+  WsMessage
+} from "@neo-companion/shared";
 import type { BoardColumn, KnowledgeNote, KnowledgeProject, KnowledgeTask, TaskStatus } from "./composables/useKnowledgeMock";
 
+export interface EmbeddingConfigInput {
+  provider: string;
+  baseUrl?: string;
+  apiKey?: string;
+  model?: string;
+}
+export interface EmbeddingConfigStatus {
+  provider: string;
+  baseUrl: string;
+  model: string;
+  configured: boolean;
+}
+export interface AiChatRequest {
+  message: string;
+  mode?: AiRetrievalMode;
+  projectId?: string | null;
+  context?: { notes: Record<string, ContextLevel>; tasks: Record<string, ContextLevel> };
+  conversationId?: string;
+}
+
 export const API_BASE = import.meta.env.VITE_NEO_SERVER_URL ?? "http://127.0.0.1:10103";
 export const WS_BASE = API_BASE.replace(/^http/, "ws");
 
@@ -32,6 +64,8 @@ export const api = {
   completeFocus: (id: string) => request<FocusSession>(`/api/focus/${id}/complete`, { method: "POST" }),
   weather: () => request<WeatherSummary>("/api/weather"),
   chat: (message: string) => request<{ text: string }>("/api/ai/chat", { method: "POST", body: JSON.stringify({ message }) }),
+  aiChat: (req: AiChatRequest) =>
+    request<AiAnswer>("/api/ai/chat", { method: "POST", body: JSON.stringify(req) }),
   speak: (text: string, style?: string) =>
     request<TtsResult>("/api/tts/speak", { method: "POST", body: JSON.stringify({ text, style }) }),
 
@@ -81,7 +115,18 @@ export const api = {
   knowledgeMirrorExport: (path?: string) =>
     request<{ projects: number; notes: number; columns: number; tasks: number }>("/api/knowledge/mirror/export", { method: "POST", body: JSON.stringify({ path }) }),
   knowledgeMirrorImport: (path?: string) =>
-    request<{ importedProjects: number; importedNotes: number; importedColumns: number; importedTasks: number; skipped: number }>("/api/knowledge/mirror/import", { method: "POST", body: JSON.stringify({ path }) })
+    request<{ importedProjects: number; importedNotes: number; importedColumns: number; importedTasks: number; skipped: number }>("/api/knowledge/mirror/import", { method: "POST", body: JSON.stringify({ path }) }),
+
+  // ── Knowledge retrieval + embedding config (Phase 3) ──
+  knowledgeSearch: (query: string, projectId?: string | null, limit = 20) =>
+    request<KnowledgeSource[]>(`/api/knowledge/search?q=${encodeURIComponent(query)}${projectId ? `&projectId=${encodeURIComponent(projectId)}` : ""}&limit=${limit}`),
+  knowledgeIndexStatus: () => request<IndexStatus>("/api/knowledge/index-status"),
+  knowledgeReindex: (embeddingModel?: string) =>
+    request<{ notes: number; tasks: number }>("/api/knowledge/reindex", { method: "POST", body: JSON.stringify({ embeddingModel }) }),
+  knowledgeGetEmbeddingConfig: () =>
+    request<EmbeddingConfigStatus>("/api/knowledge/embedding-config"),
+  knowledgeSetEmbeddingConfig: (config: EmbeddingConfigInput) =>
+    request<{ ok: boolean }>("/api/knowledge/embedding-config", { method: "PUT", body: JSON.stringify(config) })
 };
 
 let activeWs: WebSocket | null = null;
diff --git a/apps/desktop/src/components/settings/sections/KnowledgeSection.vue b/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
index da75005..3892709 100644
--- a/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
+++ b/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref } from "vue";
+import { computed, onMounted, ref } from "vue";
 import type {
   EmbeddingProvider,
   SearchScope,
@@ -29,9 +29,14 @@ const scopeOptions: { value: SearchScope; label: string }[] = [
 
 const isTauri = typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
 const picking = ref(false);
+const saving = ref(false);
 
 const rootPathDisplay = computed(() => props.state.knowledgeRootPath.value || "未选择");
 
+onMounted(() => {
+  void props.state.loadEmbeddingConfig();
+});
+
 async function pickRootFolder(): Promise<void> {
   if (!isTauri || picking.value) return;
   picking.value = true;
@@ -44,6 +49,16 @@ async function pickRootFolder(): Promise<void> {
     picking.value = false;
   }
 }
+
+async function saveEmbeddingConfig(): Promise<void> {
+  if (saving.value) return;
+  saving.value = true;
+  try {
+    await props.state.saveEmbeddingConfig();
+  } finally {
+    saving.value = false;
+  }
+}
 </script>
 
 <template>
@@ -99,6 +114,29 @@ async function pickRootFolder(): Promise<void> {
         </template>
       </SettingRow>
 
+      <SettingRow label="Embedding API Base URL" hint="OpenAI 兼容端点；留空使用 Provider 默认">
+        <template #action>
+          <TextField v-model="state.embeddingBaseUrl.value" placeholder="https://api.openai.com" />
+        </template>
+      </SettingRow>
+
+      <SettingRow label="Embedding API Key" hint="推送至本地服务端后从内存清除；不落盘">
+        <template #action>
+          <TextField
+            v-model="state.embeddingApiKey.value"
+            :placeholder="state.embeddingConfigured.value ? '已配置（留空保持不变）' : 'sk-...'"
+          />
+        </template>
+      </SettingRow>
+
+      <SettingRow label="保存 Embedding 配置" hint="推送至本地服务端并触发后台向量索引">
+        <template #action>
+          <button type="button" class="btn-ghost" :disabled="saving" @click="saveEmbeddingConfig">
+            保存配置
+          </button>
+        </template>
+      </SettingRow>
+
       <SettingRow label="默认检索范围" hint="AI 对话可临时切换；这里设置打开 AI 卡时的初始范围">
         <template #action>
           <SelectField v-model="state.searchScope.value" :options="scopeOptions" />
diff --git a/apps/desktop/src/composables/useSettings.ts b/apps/desktop/src/composables/useSettings.ts
index 02cb9e1..05bb06c 100644
--- a/apps/desktop/src/composables/useSettings.ts
+++ b/apps/desktop/src/composables/useSettings.ts
@@ -1,4 +1,5 @@
 import { ref } from "vue";
+import { api } from "../api";
 
 /**
  * Settings composable — 阶段 1 仅维护本地状态，所有改动留在内存里。
@@ -77,6 +78,12 @@ export function useSettings() {
   // —— 知识库（v3.3 新增；mock 状态，等 v2 接 sidecar 时迁出）
   const embeddingProvider = ref<EmbeddingProvider>("none");
   const embeddingModel = ref("");
+  const embeddingBaseUrl = ref(
+    typeof localStorage !== "undefined" ? localStorage.getItem("neo.embeddingBaseUrl") ?? "" : "",
+  );
+  // apiKey 仅存内存 + 推送服务端，不落 localStorage（敏感）
+  const embeddingApiKey = ref("");
+  const embeddingConfigured = ref(false);
   const searchScope = ref<SearchScope>("current");
   const chunkSize = ref("1200");
   const indexAutoRebuild = ref(true);
@@ -86,8 +93,34 @@ export function useSettings() {
     typeof localStorage !== "undefined" ? localStorage.getItem(KNOWLEDGE_ROOT_PATH_KEY) ?? "" : "",
   );
 
-  function reindexAll(): void {
-    // mock：v2 接入后会调用 api.reindexKnowledge()
+  async function loadEmbeddingConfig(): Promise<void> {
+    try {
+      const status = await api.knowledgeGetEmbeddingConfig();
+      embeddingProvider.value = (status.provider as EmbeddingProvider) || "none";
+      embeddingBaseUrl.value = status.baseUrl;
+      embeddingModel.value = status.model;
+      embeddingConfigured.value = status.configured;
+    } catch {
+      // sidecar 不可用时静默降级
+    }
+  }
+
+  async function saveEmbeddingConfig(): Promise<void> {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("neo.embeddingBaseUrl", embeddingBaseUrl.value);
+    }
+    await api.knowledgeSetEmbeddingConfig({
+      provider: embeddingProvider.value,
+      baseUrl: embeddingBaseUrl.value || undefined,
+      apiKey: embeddingApiKey.value || undefined,
+      model: embeddingModel.value || undefined
+    });
+    embeddingApiKey.value = ""; // 清空内存中的明文 key
+    await loadEmbeddingConfig();
+  }
+
+  async function reindexAll(): Promise<void> {
+    await api.knowledgeReindex(embeddingModel.value || undefined);
   }
 
   function setKnowledgeRootPath(path: string): void {
@@ -153,6 +186,9 @@ export function useSettings() {
     mqttEnabled,
     embeddingProvider,
     embeddingModel,
+    embeddingBaseUrl,
+    embeddingApiKey,
+    embeddingConfigured,
     searchScope,
     chunkSize,
     indexAutoRebuild,
@@ -165,6 +201,8 @@ export function useSettings() {
     addBlacklistItem,
     reindexAll,
     setKnowledgeRootPath,
+    loadEmbeddingConfig,
+    saveEmbeddingConfig,
   };
 }
 
diff --git a/packages/ai/src/embedding.test.ts b/packages/ai/src/embedding.test.ts
new file mode 100644
index 0000000..92d1fa3
--- /dev/null
+++ b/packages/ai/src/embedding.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it, vi } from "vitest";
+import { embedContents } from "./embedding";
+
+function makeFetch(impl: (body: any) => any, status = 200): typeof fetch {
+  return vi.fn(async (_url: string, init: RequestInit) => {
+    const parsed = JSON.parse(String(init.body));
+    const payload = impl(parsed);
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      statusText: "OK",
+      json: async () => payload
+    } as Response;
+  }) as unknown as typeof fetch;
+}
+
+describe("embedContents", () => {
+  it("sends input as an array and returns vectors + dimensions in order", async () => {
+    const fetchImpl = makeFetch((body) => ({
+      data: [
+        { embedding: [0.1, 0.2, 0.3], index: 0 },
+        { embedding: [0.4, 0.5, 0.6], index: 1 }
+      ]
+    }));
+
+    const result = await embedContents(["你好", "世界"], {
+      apiKey: "k",
+      baseUrl: "https://embed.test",
+      model: "m",
+      fetchImpl
+    });
+
+    expect(result.dimensions).toBe(3);
+    expect(result.vectors).toEqual([
+      [0.1, 0.2, 0.3],
+      [0.4, 0.5, 0.6]
+    ]);
+    const calls = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls;
+    const body = JSON.parse(String(calls[0][1].body));
+    expect(body.input).toEqual(["你好", "世界"]);
+    expect(calls[0][0]).toBe("https://embed.test/v1/embeddings");
+  });
+
+  it("re-sorts by index when the provider returns out of order", async () => {
+    const fetchImpl = makeFetch(() => ({
+      data: [
+        { embedding: [0.9, 0.9, 0.9], index: 1 },
+        { embedding: [0.1, 0.1, 0.1], index: 0 }
+      ]
+    }));
+    const result = await embedContents(["a", "b"], { apiKey: "k", fetchImpl });
+    expect(result.vectors[0]).toEqual([0.1, 0.1, 0.1]);
+    expect(result.vectors[1]).toEqual([0.9, 0.9, 0.9]);
+  });
+
+  it("throws when the api key is missing", async () => {
+    await expect(embedContents(["x"])).rejects.toThrow(/EMBEDDING_API_KEY/);
+  });
+
+  it("returns empty for empty input without calling fetch", async () => {
+    const fetchImpl = makeFetch(() => ({ data: [] }));
+    const result = await embedContents([], { apiKey: "k", fetchImpl });
+    expect(result.vectors).toEqual([]);
+    expect(result.dimensions).toBe(0);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("retries on 5xx then succeeds", async () => {
+    let calls = 0;
+    const fetchImpl = vi.fn(async () => {
+      calls += 1;
+      if (calls < 2) {
+        return { ok: false, status: 503, statusText: "Service Unavailable", json: async () => ({}) } as Response;
+      }
+      return {
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        json: async () => ({ data: [{ embedding: [0.1], index: 0 }] })
+      } as Response;
+    }) as unknown as typeof fetch;
+
+    const result = await embedContents(["x"], { apiKey: "k", fetchImpl, maxRetries: 3 });
+    expect(result.vectors).toEqual([[0.1]]);
+    expect(calls).toBe(2);
+  });
+
+  it("fails fast on 4xx (non-429)", async () => {
+    const fetchImpl = vi.fn(async () => ({
+      ok: false,
+      status: 401,
+      statusText: "Unauthorized",
+      json: async () => ({})
+    })) as unknown as typeof fetch;
+    await expect(embedContents(["x"], { apiKey: "k", fetchImpl, maxRetries: 3 })).rejects.toThrow(/401/);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/ai/src/embedding.ts b/packages/ai/src/embedding.ts
new file mode 100644
index 0000000..df65a40
--- /dev/null
+++ b/packages/ai/src/embedding.ts
@@ -0,0 +1,102 @@
+/**
+ * OpenAI-compatible embedding adapter. Mirrors streamDeepSeekChat's option/env
+ * resolution so the embedding provider stays decoupled from the chat provider
+ * (DeepSeek has no embeddings endpoint).
+ */
+export interface EmbeddingOptions {
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  maxRetries?: number;
+}
+
+export interface EmbeddingResult {
+  vectors: number[][];
+  dimensions: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+
+interface OpenAIEmbeddingResponse {
+  data?: Array<{ embedding?: number[]; index?: number }>;
+}
+
+/** Thrown for non-retryable failures (4xx except 429); escapes the retry loop. */
+class NonRetryableError extends Error {}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Embed a batch of texts in a single /v1/embeddings request. Returns vectors in
+ * input order plus the discovered dimension (from the first vector).
+ */
+export async function embedContents(texts: string[], options: EmbeddingOptions = {}): Promise<EmbeddingResult> {
+  if (texts.length === 0) {
+    return { vectors: [], dimensions: 0 };
+  }
+
+  const apiKey = options.apiKey ?? process.env.EMBEDDING_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing EMBEDDING_API_KEY");
+  }
+
+  const fetcher = options.fetchImpl ?? fetch;
+  const baseUrl = options.baseUrl ?? process.env.EMBEDDING_BASE_URL ?? "https://api.openai.com";
+  const model = options.model ?? process.env.EMBEDDING_MODEL ?? "text-embedding-3-small";
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetcher(`${baseUrl}/v1/embeddings`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ model, input: texts }),
+        signal: controller.signal
+      });
+
+      if (!response.ok) {
+        // Retry on 5xx / 429; fail fast on 4xx (except 429).
+        if (response.status >= 500 || response.status === 429) {
+          lastError = new Error(`Embedding request failed: ${response.status} ${response.statusText}`);
+        } else {
+          throw new NonRetryableError(`Embedding request failed: ${response.status} ${response.statusText}`);
+        }
+      } else {
+        const parsed = (await response.json()) as OpenAIEmbeddingResponse;
+        const data = parsed.data ?? [];
+        if (data.length !== texts.length) {
+          throw new Error(`Embedding count mismatch: expected ${texts.length}, got ${data.length}`);
+        }
+        // Re-sort by index in case the provider returns out of order.
+        const sorted = [...data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+        const vectors = sorted.map((d) => d.embedding ?? []);
+        const dimensions = vectors[0]?.length ?? 0;
+        return { vectors, dimensions };
+      }
+    } catch (error) {
+      // Non-retryable errors propagate immediately; everything else retries.
+      if (error instanceof NonRetryableError) throw error;
+      lastError = error;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (attempt < maxRetries - 1) {
+      await sleep(2 ** attempt * 500); // 500ms, 1s, 2s
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error("Embedding request failed");
+}
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index fcebd56..5abeb06 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -1,5 +1,8 @@
 import { DEFAULT_DEEPSEEK_MODEL, LEGACY_DEEPSEEK_MODELS, type ChatMessage } from "@neo-companion/shared";
 
+export { embedContents } from "./embedding";
+export type { EmbeddingOptions, EmbeddingResult } from "./embedding";
+
 export interface DeepSeekOptions {
   apiKey?: string;
   model?: string;
diff --git a/packages/db/package.json b/packages/db/package.json
index f6977e6..3edf42c 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -15,7 +15,8 @@
   "dependencies": {
     "@neo-companion/shared": "workspace:*",
     "better-sqlite3": "12.10.0",
-    "drizzle-orm": "0.45.2"
+    "drizzle-orm": "0.45.2",
+    "sqlite-vec": "^0.1.9"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
diff --git a/packages/db/src/db.test.ts b/packages/db/src/db.test.ts
index 94b9c36..048d787 100644
--- a/packages/db/src/db.test.ts
+++ b/packages/db/src/db.test.ts
@@ -90,3 +90,65 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge store", () => {
     database.close();
   });
 });
+
+describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
+  it("loads sqlite-vec, writes chunks, and returns KNN hits", () => {
+    const database = createDatabase(":memory:");
+    const kw = createKnowledgeStore(database);
+    expect(kw.vecLoaded).toBe(true);
+
+    const dim = 4;
+    expect(kw.ensureVecTable(dim)).toBe(true);
+
+    const project = kw.createProject({ title: "P" });
+    const note = kw.createNote(project.id, "向量化笔记");
+    kw.updateNote(note.id, { body: "sqlite-vec 向量检索" });
+
+    // simulate an embedded chunk: insert a pending chunk then put its vector
+    const pending = kw.listPendingChunks(10);
+    expect(pending.length).toBeGreaterThanOrEqual(1);
+    const chunk = pending[0];
+    const vec = [0.1, 0.2, 0.3, 0.4];
+    kw.putVecChunk(chunk.id, vec);
+    kw.markChunkIndexed(chunk.id, "test-embed", dim);
+
+    const hits = kw.searchKnn([0.1, 0.2, 0.3, 0.4], 5, null);
+    expect(hits.length).toBeGreaterThanOrEqual(1);
+    expect(hits[0].sourceId).toBe(note.id);
+    expect(hits[0].sourceType).toBe("note");
+    database.close();
+  });
+
+  it("scopes KNN to a project", () => {
+    const database = createDatabase(":memory:");
+    const kw = createKnowledgeStore(database);
+    kw.ensureVecTable(2);
+
+    const a = kw.createProject({ title: "A" });
+    const b = kw.createProject({ title: "B" });
+    const noteA = kw.createNote(a.id, "A 笔记");
+    kw.updateNote(noteA.id, { body: "内容 A" });
+    const noteB = kw.createNote(b.id, "B 笔记");
+    kw.updateNote(noteB.id, { body: "内容 B" });
+
+    const pending = kw.listPendingChunks(20);
+    for (const c of pending) {
+      kw.putVecChunk(c.id, [0.5, 0.5]);
+      kw.markChunkIndexed(c.id, "test-embed", 2);
+    }
+
+    const scopedA = kw.searchKnn([0.5, 0.5], 10, a.id);
+    expect(scopedA.every((h) => h.projectId === a.id)).toBe(true);
+    database.close();
+  });
+
+  it("caches and reuses embeddings by content hash", () => {
+    const database = createDatabase(":memory:");
+    const kw = createKnowledgeStore(database);
+    const vec = [0.1, 0.2, 0.3];
+    kw.putCachedEmbedding("hash-1", vec, "test-embed", 3);
+    expect(kw.getCachedEmbedding("hash-1")).toEqual({ vector: vec, dimensions: 3 });
+    expect(kw.getCachedEmbedding("missing")).toBeNull();
+    database.close();
+  });
+});
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 69fffc5..29defc6 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -1,7 +1,11 @@
 import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
 import { drizzle } from "drizzle-orm/better-sqlite3";
-import { and, eq, like, asc } from "drizzle-orm";
+import { and, eq, like, asc, inArray } from "drizzle-orm";
 import type {
+  AiConversation,
+  AiMessage,
+  AiRetrievalMode,
   FocusSession,
   IndexStatus,
   KnowledgeBoardColumn,
@@ -14,6 +18,8 @@ import type {
   WindowSnapshot
 } from "@neo-companion/shared";
 import {
+  aiConversations,
+  aiMessages,
   focusSessions,
   knowledgeBoardColumns,
   knowledgeChunks,
@@ -22,6 +28,7 @@ import {
   knowledgeProjects,
   knowledgeTags,
   knowledgeTasks,
+  embeddingCache,
   tasks,
   windowEvents
 } from "./schema";
@@ -209,9 +216,57 @@ export function initSchema(sqlite: Database.Database) {
       content_hash UNINDEXED,
       tokenize = 'trigram'
     );
+
+    -- Embedding cache (Phase 3): same content_hash → reuse stored vector.
+    CREATE TABLE IF NOT EXISTS embedding_cache (
+      content_hash TEXT PRIMARY KEY,
+      embedding BLOB NOT NULL,
+      model TEXT NOT NULL,
+      dimensions INTEGER NOT NULL
+    );
+
+    -- AI conversations (Phase 4), separate from v1 pet conversations.
+    CREATE TABLE IF NOT EXISTS ai_conversations (
+      id TEXT PRIMARY KEY,
+      project_id TEXT,
+      mode TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS ai_messages (
+      id TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      sources_json TEXT,
+      created_at TEXT NOT NULL
+    );
   `);
 }
 
+/** Load the sqlite-vec extension into a connection. Never throws; returns loaded state. */
+export function loadVecExtension(database: NeoDatabase): { loaded: boolean; version?: string } {
+  if (database.kind !== "sqlite") return { loaded: false };
+  try {
+    sqliteVec.load(database.sqlite);
+    const row = database.sqlite.prepare("SELECT vec_version() AS v").get() as { v?: string } | undefined;
+    return { loaded: true, version: row?.v };
+  } catch {
+    return { loaded: false };
+  }
+}
+
+/** Serialize a vector for better-sqlite3 BLOB binding (Float32 little-endian). */
+export function toVecBuffer(vec: number[]): Buffer {
+  return Buffer.from(new Float32Array(vec).buffer);
+}
+
+/** Deserialize a stored BLOB back to a number[]. */
+function bufferToVec(buf: Buffer | Uint8Array): number[] {
+  return Array.from(new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4));
+}
+
 export function createTaskStore(database: NeoDatabase) {
   if (database.kind === "memory") {
     return {
@@ -467,7 +522,20 @@ export interface KnowledgeStore {
   removeIndex(sourceType: "note" | "task", sourceId: string): void;
   searchFts(projectId: string | null, query: string, limit: number): KnowledgeSource[];
   markStale(embeddingModel?: string): void;
-  getIndexStatus(providerConfigured: boolean, vectorExtensionAvailable: boolean): IndexStatus;
+  getIndexStatus(providerConfigured: boolean): IndexStatus;
+  // Vector indexing (Phase 3). vecLoaded reflects whether sqlite-vec loaded.
+  vecLoaded: boolean;
+  ensureVecTable(dim: number): boolean;
+  searchKnn(queryVec: number[], k: number, projectId: string | null): KnowledgeSource[];
+  putVecChunk(chunkId: string, vec: number[]): void;
+  delVecChunk(chunkId: string): void;
+  getCachedEmbedding(contentHash: string): { vector: number[]; dimensions: number } | null;
+  putCachedEmbedding(contentHash: string, vec: number[], model: string, dim: number): void;
+  listPendingChunks(limit: number): Array<{
+    id: string; content: string; contentHash: string; projectId: string; sourceType: "note" | "task"; sourceId: string;
+  }>;
+  markChunkIndexed(chunkId: string, model: string, dim: number): void;
+  markChunkFailed(chunkId: string, error: string): void;
 }
 
 function isoToMs(iso: string | null): number {
@@ -481,6 +549,9 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     throw new Error("Knowledge store requires a sqlite database (memory fallback unsupported)");
   }
   const { db, sqlite } = database;
+  const vecState = loadVecExtension(database);
+  let vecLoaded = vecState.loaded;
+  let vecDim: number | null = null;
 
   // ── tags helpers ──
   function ensureTagIds(names: string[]): string[] {
@@ -832,11 +903,21 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
         indexError: null,
         updatedAt: now
       }).run();
+      sqlite.exec(
+        `INSERT INTO knowledge_chunks_fts (content, project_id, source_type, source_id, content_hash)
+         VALUES (${sqlStr(piece.content)}, ${sqlStr(task.projectId)}, 'task', ${sqlStr(task.id)}, ${sqlStr(piece.contentHash)})`
+      );
       ordinal += 1;
     }
   }
 
   function removeIndex(sourceType: "note" | "task", sourceId: string): void {
+    // Collect chunk ids so we can also drop their vec0 rows before deleting.
+    const chunkIds = db.select({ id: knowledgeChunks.id })
+      .from(knowledgeChunks)
+      .where(and(eq(knowledgeChunks.sourceType, sourceType), eq(knowledgeChunks.sourceId, sourceId)))
+      .all().map((r) => r.id);
+    for (const cid of chunkIds) delVecChunk(cid);
     // FTS5 delete-then-reinsert: drop matching FTS rows, then the chunk rows.
     sqlite.exec(
       `DELETE FROM knowledge_chunks_fts WHERE source_type = ${sqlStr(sourceType)} AND source_id = ${sqlStr(sourceId)}`
@@ -920,23 +1001,154 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     }
   }
 
-  function getIndexStatus(providerConfigured: boolean, vectorExtensionAvailable: boolean): IndexStatus {
+  function getIndexStatus(providerConfigured: boolean): IndexStatus {
     const countBy = (status: string): number => {
       const row = sqlite.prepare(
         `SELECT COUNT(*) AS n FROM knowledge_chunks WHERE index_status = ${sqlStr(status)}`
       ).get() as { n: number } | undefined;
       return row?.n ?? 0;
     };
+    const pending = countBy("pending");
+    const stale = countBy("stale");
+    const hybridCapable = vecLoaded && providerConfigured;
+    const mode: IndexStatus["mode"] = hybridCapable
+      ? pending + stale > 0
+        ? "indexing"
+        : "hybrid"
+      : "fts-only";
     return {
-      mode: vectorExtensionAvailable ? "hybrid" : "fts-only",
-      pending: countBy("pending"),
+      mode,
+      pending,
       failed: countBy("failed"),
-      stale: countBy("stale"),
+      stale,
       providerConfigured,
-      vectorExtensionAvailable
+      vectorExtensionAvailable: vecLoaded
     };
   }
 
+  // ── vector indexing (Phase 3) ──
+  function ensureVecTable(dim: number): boolean {
+    if (!vecLoaded) return false;
+    if (vecDim === null) {
+      sqlite.exec(
+        `CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_chunks_vec USING vec0(chunk_id TEXT PRIMARY KEY, embedding FLOAT[${dim}])`
+      );
+      vecDim = dim;
+    } else if (vecDim !== dim) {
+      // dimension changed (model swap) → drop, recreate, force full re-embed
+      sqlite.exec("DROP TABLE IF EXISTS knowledge_chunks_vec");
+      sqlite.exec(
+        `CREATE VIRTUAL TABLE knowledge_chunks_vec USING vec0(chunk_id TEXT PRIMARY KEY, embedding FLOAT[${dim}])`
+      );
+      vecDim = dim;
+      markStale();
+    }
+    return true;
+  }
+
+  function putVecChunk(chunkId: string, vec: number[]): void {
+    if (!vecLoaded || vecDim === null) return;
+    sqlite.prepare(
+      "INSERT OR REPLACE INTO knowledge_chunks_vec (chunk_id, embedding) VALUES (?, ?)"
+    ).run(chunkId, toVecBuffer(vec));
+  }
+
+  function delVecChunk(chunkId: string): void {
+    if (!vecLoaded || vecDim === null) return;
+    sqlite.prepare("DELETE FROM knowledge_chunks_vec WHERE chunk_id = ?").run(chunkId);
+  }
+
+  function searchKnn(
+    queryVec: number[],
+    k: number,
+    projectId: string | null
+  ): KnowledgeSource[] {
+    if (!vecLoaded || vecDim === null || queryVec.length !== vecDim) return [];
+    const cap = Math.max(1, Math.min(k, 50));
+    const rows = sqlite.prepare(
+      `SELECT v.chunk_id AS chunk_id, v.distance AS distance
+         FROM knowledge_chunks_vec v
+         WHERE v.embedding MATCH ?
+         ORDER BY v.distance
+         LIMIT ${cap}`
+    ).all(toVecBuffer(queryVec)) as Array<{ chunk_id: string; distance: number }>;
+    if (!rows.length) return [];
+    const ids = rows.map((r) => r.chunk_id);
+    const chunkRows = db.select().from(knowledgeChunks).where(inArray(knowledgeChunks.id, ids)).all();
+    const byId = new Map(chunkRows.map((r) => [r.id, r]));
+    // dedup by source (first hit wins — rows are distance-sorted) + resolve title/excerpt
+    const bySource = new Map<string, KnowledgeSource>();
+    for (const r of rows) {
+      const c = byId.get(r.chunk_id);
+      if (!c) continue;
+      if (projectId && c.projectId !== projectId) continue;
+      const key = `${c.sourceType}:${c.sourceId}`;
+      if (bySource.has(key)) continue;
+      bySource.set(key, {
+        sourceType: c.sourceType,
+        sourceId: c.sourceId,
+        projectId: c.projectId,
+        title: resolveSourceTitle(c.sourceType, c.sourceId),
+        excerpt: deriveExcerpt(c.content),
+        chunkId: r.chunk_id
+      });
+    }
+    return [...bySource.values()];
+  }
+
+  function getCachedEmbedding(contentHash: string): { vector: number[]; dimensions: number } | null {
+    const row = db.select().from(embeddingCache).where(eq(embeddingCache.contentHash, contentHash)).get();
+    if (!row) return null;
+    return { vector: bufferToVec(row.embedding), dimensions: row.dimensions };
+  }
+
+  function putCachedEmbedding(contentHash: string, vec: number[], model: string, dim: number): void {
+    db.insert(embeddingCache).values({
+      contentHash,
+      embedding: toVecBuffer(vec),
+      model,
+      dimensions: dim
+    }).onConflictDoUpdate({
+      target: embeddingCache.contentHash,
+      set: { embedding: toVecBuffer(vec), model, dimensions: dim }
+    }).run();
+  }
+
+  function listPendingChunks(limit: number): Array<{
+    id: string; content: string; contentHash: string; projectId: string; sourceType: "note" | "task"; sourceId: string;
+  }> {
+    return db.select({
+      id: knowledgeChunks.id,
+      content: knowledgeChunks.content,
+      contentHash: knowledgeChunks.contentHash,
+      projectId: knowledgeChunks.projectId,
+      sourceType: knowledgeChunks.sourceType,
+      sourceId: knowledgeChunks.sourceId
+    })
+      .from(knowledgeChunks)
+      .where(inArray(knowledgeChunks.indexStatus, ["pending", "stale"]))
+      .limit(limit)
+      .all();
+  }
+
+  function markChunkIndexed(chunkId: string, model: string, dim: number): void {
+    db.update(knowledgeChunks).set({
+      indexStatus: "indexed",
+      embeddingModel: model,
+      embeddingDimensions: dim,
+      indexError: null,
+      updatedAt: nowIso()
+    }).where(eq(knowledgeChunks.id, chunkId)).run();
+  }
+
+  function markChunkFailed(chunkId: string, error: string): void {
+    db.update(knowledgeChunks).set({
+      indexStatus: "failed",
+      indexError: error,
+      updatedAt: nowIso()
+    }).where(eq(knowledgeChunks.id, chunkId)).run();
+  }
+
   // safe SQL string literal (single-quote escape) for raw FTS queries
   function sqlStr(value: string): string {
     return `'${value.replace(/'/g, "''")}'`;
@@ -949,14 +1161,89 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
       .filter(Boolean);
   }
 
-  // silence unused binding reserved for Phase 3 raw-vec access
-  void sqlite;
-
   return {
     listProjects, getProject, childProjects, projectPath, createProject, updateProject, deleteProject, ensureInbox,
     notesForProject, getNote, createNote, updateNote, deleteNote, backlinksFor,
     columnsForProject, createColumn, updateColumn, deleteColumn,
     tasksForProject, createTask, updateTask, deleteTask, moveTask,
-    reindexNote, reindexTask, removeIndex, searchFts, markStale, getIndexStatus
+    reindexNote, reindexTask, removeIndex, searchFts, markStale, getIndexStatus,
+    get vecLoaded() { return vecLoaded; },
+    ensureVecTable, searchKnn, putVecChunk, delVecChunk, getCachedEmbedding, putCachedEmbedding,
+    listPendingChunks, markChunkIndexed, markChunkFailed
   };
 }
+
+/** AI conversation store (Phase 4): multi-turn chat persistence with sources. */
+export function createAiConversationStore(database: NeoDatabase) {
+  if (database.kind !== "sqlite") {
+    throw new Error("AI conversation store requires a sqlite database");
+  }
+  const { db } = database;
+
+  function createConversation(projectId: string | null, mode: AiRetrievalMode): AiConversation {
+    const id = crypto.randomUUID();
+    const ts = new Date().toISOString();
+    db.insert(aiConversations).values({ id, projectId, mode, createdAt: ts, updatedAt: ts }).run();
+    return { id, projectId, mode, createdAt: Date.parse(ts), updatedAt: Date.parse(ts) };
+  }
+
+  function getConversation(id: string): AiConversation | null {
+    const row = db.select().from(aiConversations).where(eq(aiConversations.id, id)).get();
+    if (!row) return null;
+    return {
+      id: row.id,
+      projectId: row.projectId,
+      mode: row.mode,
+      createdAt: Date.parse(row.createdAt),
+      updatedAt: Date.parse(row.updatedAt)
+    };
+  }
+
+  function listMessages(conversationId: string): AiMessage[] {
+    return db.select().from(aiMessages)
+      .where(eq(aiMessages.conversationId, conversationId))
+      .orderBy(asc(aiMessages.createdAt))
+      .all()
+      .map((row) => ({
+        id: row.id,
+        conversationId: row.conversationId,
+        role: row.role,
+        content: row.content,
+        sources: row.sourcesJson ? safeParseSources(row.sourcesJson) : [],
+        createdAt: Date.parse(row.createdAt)
+      }));
+  }
+
+  function appendMessage(
+    conversationId: string,
+    role: AiMessage["role"],
+    content: string,
+    sources: KnowledgeSource[] = []
+  ): AiMessage {
+    const id = crypto.randomUUID();
+    const ts = new Date().toISOString();
+    db.insert(aiMessages).values({
+      id,
+      conversationId,
+      role,
+      content,
+      sourcesJson: sources.length ? JSON.stringify(sources) : null,
+      createdAt: ts
+    }).run();
+    db.update(aiConversations).set({ updatedAt: ts }).where(eq(aiConversations.id, conversationId)).run();
+    return { id, conversationId, role, content, sources, createdAt: Date.parse(ts) };
+  }
+
+  return { createConversation, getConversation, listMessages, appendMessage };
+}
+
+export type AiConversationStore = ReturnType<typeof createAiConversationStore>;
+
+function safeParseSources(json: string): KnowledgeSource[] {
+  try {
+    const parsed = JSON.parse(json) as unknown;
+    return Array.isArray(parsed) ? (parsed as KnowledgeSource[]) : [];
+  } catch {
+    return [];
+  }
+}
diff --git a/packages/db/src/schema.ts b/packages/db/src/schema.ts
index e3788d4..d63cc00 100644
--- a/packages/db/src/schema.ts
+++ b/packages/db/src/schema.ts
@@ -1,4 +1,4 @@
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { blob, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
 
 export const tasks = sqliteTable("tasks", {
   id: text("id").primaryKey(),
@@ -122,3 +122,32 @@ export const knowledgeChunks = sqliteTable("knowledge_chunks", {
   indexError: text("index_error"),
   updatedAt: text("updated_at").notNull()
 });
+
+// Embedding cache keyed by content hash. Same-hash chunks reuse the stored
+// vector, skipping redundant embedding API calls (Phase 3).
+export const embeddingCache = sqliteTable("embedding_cache", {
+  contentHash: text("content_hash").primaryKey(),
+  embedding: blob("embedding", { mode: "buffer" }).notNull(),
+  model: text("model").notNull(),
+  dimensions: integer("dimensions").notNull()
+});
+
+// AI conversations (Phase 4). Separate from the v1 `conversations`/`messages`
+// tables (pet-panel chat) — these carry knowledge RAG context + sources.
+export const aiConversations = sqliteTable("ai_conversations", {
+  id: text("id").primaryKey(),
+  projectId: text("project_id"),
+  mode: text("mode", { enum: ["chat", "ask"] }).notNull(),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull()
+});
+
+export const aiMessages = sqliteTable("ai_messages", {
+  id: text("id").primaryKey(),
+  conversationId: text("conversation_id").notNull(),
+  role: text("role", { enum: ["system", "user", "assistant"] }).notNull(),
+  content: text("content").notNull(),
+  sourcesJson: text("sources_json"),
+  createdAt: text("created_at").notNull()
+});
+
diff --git a/packages/server-local/src/app.ts b/packages/server-local/src/app.ts
index 9cfafaa..987c2c7 100644
--- a/packages/server-local/src/app.ts
+++ b/packages/server-local/src/app.ts
@@ -1,8 +1,8 @@
 import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
 import Fastify, { type FastifyInstance } from "fastify";
-import { streamDeepSeekChat } from "@neo-companion/ai";
-import { createDatabase, createKnowledgeStore, createTaskStore, createWindowEventStore, type KnowledgeStore, type NeoDatabase } from "@neo-companion/db";
+import { streamDeepSeekChat, embedContents } from "@neo-companion/ai";
+import { createAiConversationStore, createDatabase, createKnowledgeStore, createTaskStore, createWindowEventStore, type AiConversationStore, type KnowledgeStore, type NeoDatabase } from "@neo-companion/db";
 import type { ChatMessage, CompanionFeedback, TtsResult } from "@neo-companion/shared";
 import { speakWithMimo } from "@neo-companion/tts";
 import { createFocusManager } from "./services/focus-manager";
@@ -10,7 +10,8 @@ import { createHookManager, type HookManagerEvents } from "./services/hook-manag
 import { getWeatherSummary } from "./services/weather-service";
 import { getActiveWindowSnapshot } from "./services/window-service";
 import { registerKnowledgeRoutes } from "./modules/knowledge/routes";
-import { createKnowledgeService, type KnowledgeService } from "./modules/knowledge/service";
+import { createKnowledgeService, type EmbeddingConfig, type KnowledgeService } from "./modules/knowledge/service";
+import { createAiService, resolveMode, type AiService, type ChatContextSelection } from "./modules/ai/service";
 import { WsHub } from "./ws-hub";
 
 export interface AppDependencies {
@@ -31,10 +32,32 @@ export async function createApp(dependencies: AppDependencies = {}) {
   // fallback is reachable (better-sqlite3 native binding unavailable). Routes
   // degrade to 503 in that case.
   const knowledgeStore: KnowledgeStore | null = database.kind === "sqlite" ? createKnowledgeStore(database) : null;
-  const knowledgeService: KnowledgeService | null = knowledgeStore ? createKnowledgeService(knowledgeStore) : null;
+  // Embedding provider config held in memory (pushed from the client via the
+  // /embedding-config route, like root-path). Survives for the process lifetime.
+  let embeddingConfig: EmbeddingConfig = { provider: "none" };
+  const embeddingConfigController = {
+    get: () => embeddingConfig,
+    set: (next: EmbeddingConfig) => {
+      embeddingConfig = next;
+    }
+  };
+  const knowledgeService: KnowledgeService | null = knowledgeStore
+    ? createKnowledgeService(knowledgeStore, {
+        embedFn: embedContents,
+        getEmbeddingConfig: embeddingConfigController.get
+      })
+    : null;
   const hub = new WsHub();
   const app = Fastify({ logger: true });
   const aiStream = dependencies.aiStream ?? ((messages) => streamDeepSeekChat(messages));
+  const aiConversationStore: AiConversationStore | null = database.kind === "sqlite" ? createAiConversationStore(database) : null;
+  const aiService = createAiService({
+    conversationStore: aiConversationStore,
+    knowledgeService,
+    knowledgeStore,
+    aiStream,
+    hub
+  });
   const ttsSpeak = dependencies.ttsSpeak ?? ((text, style) => speakWithMimo(text, style));
   const windowSnapshot = dependencies.windowSnapshot ?? getActiveWindowSnapshot;
 
@@ -99,7 +122,7 @@ export async function createApp(dependencies: AppDependencies = {}) {
     return task;
   });
 
-  registerKnowledgeRoutes(app, knowledgeStore, knowledgeService);
+  registerKnowledgeRoutes(app, knowledgeStore, knowledgeService, embeddingConfigController);
 
   app.post("/api/focus/start", async (request) => {
     const body = request.body as { taskId?: string | null; durationMinutes?: number };
@@ -120,26 +143,28 @@ export async function createApp(dependencies: AppDependencies = {}) {
   app.get("/api/weather", async () => dependencies.weather?.() ?? getWeatherSummary());
 
   app.post("/api/ai/chat", async (request, reply) => {
-    const body = request.body as { message?: string };
+    const body = request.body as {
+      message?: string;
+      mode?: string;
+      projectId?: string;
+      context?: ChatContextSelection;
+      conversationId?: string;
+    };
     if (!body.message?.trim()) return reply.code(400).send({ error: "message is required" });
 
-    const messages: ChatMessage[] = [
-      { role: "system", content: "你是 NeoCompanion 的中文温柔陪伴助手，回答简洁、具体，不使用强主宠称呼。" },
-      { role: "user", content: body.message }
-    ];
-    let text = "";
-
     try {
-      hub.broadcast({ type: "companion:feedback", payload: { state: "thinking", text: "我想一想。", speak: false } satisfies CompanionFeedback });
-      for await (const chunk of aiStream(messages)) {
-        text += chunk;
-        hub.broadcast({ type: "ai:chunk", payload: { chunk } });
-      }
-      hub.broadcast({ type: "ai:done", payload: { text } });
-      return { text };
+      const mode = resolveMode(body.mode);
+      const answer = mode === "ask"
+        ? await aiService.handleAsk({ message: body.message, projectId: body.projectId ?? null })
+        : await aiService.handleChat({
+            message: body.message,
+            projectId: body.projectId ?? null,
+            context: body.context,
+            conversationId: body.conversationId
+          });
+      return answer;
     } catch (error) {
       const message = error instanceof Error ? error.message : "AI request failed";
-      hub.broadcast({ type: "ai:error", payload: { message } });
       return reply.code(500).send({ error: message });
     }
   });
diff --git a/packages/server-local/src/modules/ai/citation.test.ts b/packages/server-local/src/modules/ai/citation.test.ts
new file mode 100644
index 0000000..af8c1e1
--- /dev/null
+++ b/packages/server-local/src/modules/ai/citation.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import type { KnowledgeSource } from "@neo-companion/shared";
+import { injectSources, parseAndAuditCitations, buildSources } from "./citation";
+import type { ContextBlock } from "./context";
+
+function block(ref: string, content: string, ordinal = 0): ContextBlock {
+  return { type: "note", ref, content, weight: 100, ordinal };
+}
+
+function source(ref: string): KnowledgeSource {
+  return { sourceType: "note", sourceId: ref, projectId: "p", title: ref, excerpt: "", chunkId: ref };
+}
+
+describe("citation injection + audit", () => {
+  it("assigns stable ids s0..sN and renders source elements", () => {
+    const injected = injectSources([block("n1", "内容一"), block("n2", "内容二")]);
+    expect(injected.idToRef.get("s0")).toBe("n1");
+    expect(injected.idToRef.get("s1")).toBe("n2");
+    expect(injected.contextText).toContain('<source id="s0"');
+    expect(injected.contextText).toContain("内容一");
+    expect(injected.systemPrompt).toContain("不得发明新 id");
+  });
+
+  it("keeps valid citations and drops invented ids", () => {
+    const valid = new Set(["s0", "s1"]);
+    const text = "根据笔记 [s0] 和虚构的 [s9] 以及 (s1)。";
+    const result = parseAndAuditCitations(text, valid);
+    expect(result.citedIds).toEqual(["s0", "s1"]);
+    expect(result.cleanedText).not.toContain("s9");
+    expect(result.cleanedText).toContain("[s0]");
+    expect(result.cleanedText).toContain("(s1)");
+  });
+
+  it("dedupes repeated citations in first-appearance order", () => {
+    const valid = new Set(["s0", "s1"]);
+    const result = parseAndAuditCitations("[s1][s0][s1]", valid);
+    expect(result.citedIds).toEqual(["s1", "s0"]);
+  });
+
+  it("builds sources only for cited, injected blocks", () => {
+    const injected = injectSources([block("n1", "a"), block("n2", "b")]);
+    const lookup = new Map<string, KnowledgeSource>([["n1", source("n1")], ["n2", source("n2")]]);
+    const sources = buildSources(injected, ["s0"], lookup);
+    expect(sources).toHaveLength(1);
+    expect(sources[0].sourceId).toBe("n1");
+  });
+
+  it("returns no sources when nothing is cited", () => {
+    const injected = injectSources([block("n1", "a")]);
+    const lookup = new Map([["n1", source("n1")]]);
+    expect(buildSources(injected, [], lookup)).toEqual([]);
+  });
+});
diff --git a/packages/server-local/src/modules/ai/citation.ts b/packages/server-local/src/modules/ai/citation.ts
new file mode 100644
index 0000000..c04947e
--- /dev/null
+++ b/packages/server-local/src/modules/ai/citation.ts
@@ -0,0 +1,93 @@
+import type { KnowledgeSource } from "@neo-companion/shared";
+import type { ContextBlock } from "./context";
+
+/**
+ * Citation injection + audit (Phase 4). Each packed block becomes a
+ * <source id="sN"> element in the prompt; the system prompt forbids inventing
+ * ids. After the model replies, parseAndAuditCitations drops any citation id
+ * the model produced that wasn't actually injected (anti-hallucination).
+ */
+
+export interface InjectedContext {
+  systemPrompt: string;
+  contextText: string;
+  /** Map of injected id → block ref (noteId/taskId/messageId). */
+  idToRef: Map<string, string>;
+  /** Blocks in prompt order, with their assigned ids. */
+  blocks: Array<ContextBlock & { id: string }>;
+}
+
+const SYSTEM_PROMPT = `你是 NeoCompanion 的知识助手。回答基于下方提供的 <source> 段落。
+引用规则：
+- 只能引用已提供的 source id（如 s0、s1），不得发明新 id。
+- 引用标记放在相关句末，格式 [sN]；多个来源并列写作 [s0][s1]。
+- 若上下文不足以回答，如实说明，不要编造来源。
+回答简洁、具体。`;
+
+/** Render packed blocks as <source> elements with stable ids s0..sN. */
+export function injectSources(blocks: ContextBlock[]): InjectedContext {
+  const idToRef = new Map<string, string>();
+  const tagged: Array<ContextBlock & { id: string }> = [];
+  const lines: string[] = [];
+
+  blocks.forEach((block, index) => {
+    const id = `s${index}`;
+    idToRef.set(id, block.ref);
+    tagged.push({ ...block, id });
+    const typeLabel = block.type === "note" ? "笔记" : block.type === "task" ? "任务" : "历史";
+    lines.push(`<source id="${id}" type="${typeLabel}" ref="${block.ref}">${block.content}</source>`);
+  });
+
+  return {
+    systemPrompt: SYSTEM_PROMPT,
+    contextText: lines.join("\n\n"),
+    idToRef,
+    blocks: tagged
+  };
+}
+
+/** Match citation markers like [s0], (s1), or bare s0 at word boundaries. */
+const CITATION_RE = /\[?(s\d+)\]?/g;
+
+export interface AuditedCitations {
+  /** Text with invalid citation markers removed. */
+  cleanedText: string;
+  /** Valid cited ids (subset of validIds), in first-appearance order, deduped. */
+  citedIds: string[];
+}
+
+/** Extract citation ids, keep only those that were actually injected. */
+export function parseAndAuditCitations(text: string, validIds: Set<string>): AuditedCitations {
+  const cited: string[] = [];
+  const seen = new Set<string>();
+  const cleaned = text.replace(CITATION_RE, (full, id: string) => {
+    if (validIds.has(id)) {
+      if (!seen.has(id)) {
+        cited.push(id);
+        seen.add(id);
+      }
+      return full; // keep valid marker
+    }
+    return ""; // drop invented/unknown marker
+  });
+  return { cleanedText: cleaned, citedIds: cited };
+}
+
+/** Build the KnowledgeSource[] to return to the client, limited to cited blocks. */
+export function buildSources(
+  injected: InjectedContext,
+  citedIds: string[],
+  sourceLookup: Map<string, KnowledgeSource>
+): KnowledgeSource[] {
+  const out: KnowledgeSource[] = [];
+  const seen = new Set<string>();
+  for (const id of citedIds) {
+    const ref = injected.idToRef.get(id);
+    if (!ref) continue;
+    const source = sourceLookup.get(ref);
+    if (!source || seen.has(ref)) continue;
+    seen.add(ref);
+    out.push(source);
+  }
+  return out;
+}
diff --git a/packages/server-local/src/modules/ai/context.test.ts b/packages/server-local/src/modules/ai/context.test.ts
new file mode 100644
index 0000000..c594c4f
--- /dev/null
+++ b/packages/server-local/src/modules/ai/context.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import type { ContextLevel, KnowledgeNote, KnowledgeTask } from "@neo-companion/shared";
+import { buildChatBlocks, estimateTokens, packContext, summarizeNote, WEIGHTS, type ContextBlock } from "./context";
+
+function note(id: string, title: string, body: string): KnowledgeNote {
+  return { id, projectId: "p", title, body, tags: [], createdAt: 0, updatedAt: 0 };
+}
+
+describe("context assembly", () => {
+  it("summarizes a note to its first section", () => {
+    const n = note("n1", "标题", "首段内容。\n\n## 第二节\n更多内容。");
+    expect(summarizeNote(n)).toBe("首段内容。");
+  });
+
+  it("builds chat blocks with full/summary/excluded levels and weights", () => {
+    const full = note("n1", "F", "full body");
+    const summ = note("n2", "S", "summary body");
+    const excluded = note("n3", "X", "excluded body");
+    const blocks = buildChatBlocks(
+      [
+        { note: full, level: "full" },
+        { note: summ, level: "summary" },
+        { note: excluded, level: "excluded" }
+      ],
+      [],
+      []
+    );
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0].weight).toBe(WEIGHTS.noteFull);
+    expect(blocks[1].weight).toBe(WEIGHTS.noteSummary);
+    expect(blocks[1].content).toContain("summary body"); // summary keeps body when short
+  });
+
+  it("greedy-fills within budget and drops blocks that don't fit", () => {
+    const big: ContextBlock = { type: "note", ref: "big", content: "x".repeat(400), weight: 100, ordinal: 0 };
+    const small: ContextBlock = { type: "note", ref: "small", content: "y".repeat(40), weight: 50, ordinal: 1 };
+    const packed = packContext([big, small], 200); // budget ~200 tokens ≈ 800 chars
+    // big is 400 chars ≈ 100 tokens, fits; small 40 chars ≈ 10 tokens, fits
+    expect(packed.usedRefs.has("big")).toBe(true);
+    expect(packed.usedRefs.has("small")).toBe(true);
+  });
+
+  it("gap-fills a truncated slice when a block cannot fit whole", () => {
+    const huge: ContextBlock = {
+      type: "note", ref: "huge",
+      content: "第一句。第二句。第三句。第四句。第五句。第六句。第七句。第八句。第九句。第十句。",
+      weight: 100, ordinal: 0
+    };
+    const tiny: ContextBlock = { type: "note", ref: "tiny", content: "小", weight: 90, ordinal: 1 };
+    // huge ≈ 10 tokens, tiny ≈ 1 token; budget 9 → tiny fits, huge skipped then gap-filled
+    const packed = packContext([huge, tiny], 9);
+    expect(packed.usedRefs.has("tiny")).toBe(true);
+    expect(packed.usedRefs.has("huge")).toBe(true);
+    const hugeBlock = packed.ordered.find((b) => b.ref === "huge");
+    expect(hugeBlock?.content.length).toBeLessThan(huge.content.length);
+  });
+
+  it("sandwich-orders: highest weight first", () => {
+    const low: ContextBlock = { type: "message", ref: "m1", content: "low", weight: 40, ordinal: 0 };
+    const high: ContextBlock = { type: "note", ref: "n1", content: "high", weight: 100, ordinal: 1 };
+    const mid: ContextBlock = { type: "task", ref: "t1", content: "mid", weight: 55, ordinal: 2 };
+    const packed = packContext([low, high, mid], 1000);
+    expect(packed.ordered[0].ref).toBe("n1"); // highest weight first
+  });
+
+  it("keeps same-source blocks in document order", () => {
+    const a: ContextBlock = { type: "note", ref: "n1", content: "a", weight: 100, ordinal: 0 };
+    const b: ContextBlock = { type: "note", ref: "n1", content: "b", weight: 100, ordinal: 1 };
+    const packed = packContext([a, b], 1000);
+    const refs = packed.ordered.map((x) => x.content);
+    expect(refs).toEqual(["a", "b"]);
+  });
+
+  it("estimateTokens ≈ chars/4", () => {
+    expect(estimateTokens("abcd")).toBe(1);
+    expect(estimateTokens("ab")).toBe(1);
+    expect(estimateTokens("abcdefgh")).toBe(2);
+  });
+});
diff --git a/packages/server-local/src/modules/ai/context.ts b/packages/server-local/src/modules/ai/context.ts
new file mode 100644
index 0000000..e5add2f
--- /dev/null
+++ b/packages/server-local/src/modules/ai/context.ts
@@ -0,0 +1,156 @@
+import type { ContextLevel, KnowledgeNote, KnowledgeTask, KnowledgeSource } from "@neo-companion/shared";
+
+/**
+ * Context assembly for AI Chat/Ask (Phase 4, ported from open-notebook's
+ * ContextBuilder). Pure functions: token-budget packing with priority weights,
+ * greedy fill, gap fill at sentence boundaries, and sandwich ordering.
+ */
+
+export interface ContextBlock {
+  /** Stable id used as the citation anchor, e.g. "s0". Assigned by injectSources. */
+  id?: string;
+  type: "note" | "task" | "message";
+  ref: string; // noteId / taskId / messageId
+  content: string;
+  weight: number;
+  /** Original document order within the same source (for stable sandwiching). */
+  ordinal: number;
+}
+
+export interface PackedContext {
+  /** Blocks in the order they should appear in the prompt (sandwich order). */
+  ordered: ContextBlock[];
+  /** Set of block refs actually included (after budget pruning). */
+  usedRefs: Set<string>;
+}
+
+/** Priority weights (higher = more important to include). Tunable. */
+export const WEIGHTS = {
+  noteFull: 100,
+  askChunk: 90,
+  noteSummary: 70,
+  task: 55,
+  history: 40
+} as const;
+
+/** Rough token estimate (~chars/4 for mixed CJK/latin). */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/** Summarize a note to its first heading section or leading characters. */
+export function summarizeNote(note: KnowledgeNote, maxChars = 400): string {
+  const body = note.body.trim();
+  if (!body) return note.title;
+  const firstSection = body.split(/\n#{2,}\s/)[0]?.trim() ?? body;
+  if (firstSection.length <= maxChars) return firstSection;
+  return `${firstSection.slice(0, maxChars - 1)}…`;
+}
+
+/** Build context blocks for Chat mode from selected notes/tasks + history. */
+export function buildChatBlocks(
+  notes: Array<{ note: KnowledgeNote; level: ContextLevel }>,
+  tasks: Array<{ task: KnowledgeTask; level: ContextLevel }>,
+  history: Array<{ role: "user" | "assistant"; content: string; id: string }> = []
+): ContextBlock[] {
+  const blocks: ContextBlock[] = [];
+  let ordinal = 0;
+  for (const { note, level } of notes) {
+    if (level === "excluded") continue;
+    blocks.push({
+      type: "note",
+      ref: note.id,
+      content: level === "summary" ? summarizeNote(note) : `${note.title}\n\n${note.body}`,
+      weight: level === "summary" ? WEIGHTS.noteSummary : WEIGHTS.noteFull,
+      ordinal: ordinal++
+    });
+  }
+  for (const { task, level } of tasks) {
+    if (level === "excluded") continue;
+    const content = task.description ? `${task.title}\n\n${task.description}` : task.title;
+    blocks.push({ type: "task", ref: task.id, content, weight: WEIGHTS.task, ordinal: ordinal++ });
+  }
+  history.forEach((m) => {
+    blocks.push({
+      type: "message",
+      ref: m.id,
+      content: m.content,
+      weight: WEIGHTS.history,
+      ordinal: ordinal++
+    });
+  });
+  return blocks;
+}
+
+/** Build context blocks for Ask mode from retrieved chunks. */
+export function buildAskBlocks(chunks: KnowledgeSource[], chunkContents: Map<string, string>): ContextBlock[] {
+  return chunks.map((chunk, idx) => ({
+    type: chunk.sourceType,
+    ref: chunk.sourceId,
+    content: chunkContents.get(chunk.chunkId) ?? chunk.excerpt,
+    weight: WEIGHTS.askChunk,
+    ordinal: idx
+  }));
+}
+
+const SENTENCE_BOUNDARY = /[。！？\n.!?]/;
+
+/** Truncate at the last sentence boundary fitting within remaining tokens. */
+function truncateAtSentence(text: string, maxTokens: number): string {
+  const maxChars = maxTokens * 4;
+  if (text.length <= maxChars) return text;
+  const slice = text.slice(0, maxChars);
+  let lastBoundary = -1;
+  for (let i = slice.length - 1; i >= 0; i -= 1) {
+    if (SENTENCE_BOUNDARY.test(slice[i])) {
+      lastBoundary = i;
+      break;
+    }
+  }
+  return lastBoundary > 0 ? slice.slice(0, lastBoundary + 1) : slice;
+}
+
+/**
+ * Pack blocks into a token budget:
+ * 1. Greedy fill — sort by weight desc, take whole blocks while budget remains.
+ * 2. Gap fill — for skipped high-weight blocks, try a sentence-truncated slice
+ *    in remaining budget (partial > nothing).
+ * 3. Sandwich order — highest weight first, lowest in the middle, second-highest
+ *    last (LLMs attend to首尾); same-source blocks keep document order.
+ */
+export function packContext(blocks: ContextBlock[], budgetTokens: number): PackedContext {
+  const byWeight = [...blocks].sort((a, b) => b.weight - a.weight || a.ordinal - b.ordinal);
+
+  const included: ContextBlock[] = [];
+  const usedRefs = new Set<string>();
+  let remaining = budgetTokens;
+
+  // Greedy fill
+  const skipped: ContextBlock[] = [];
+  for (const block of byWeight) {
+    const cost = estimateTokens(block.content);
+    if (cost <= remaining) {
+      included.push(block);
+      usedRefs.add(block.ref);
+      remaining -= cost;
+    } else {
+      skipped.push(block);
+    }
+  }
+
+  // Gap fill: truncated slices of skipped blocks
+  for (const block of skipped) {
+    if (remaining < 8) break;
+    const truncated = truncateAtSentence(block.content, remaining);
+    if (truncated.length < 16) continue;
+    included.push({ ...block, content: truncated });
+    usedRefs.add(block.ref);
+    remaining -= estimateTokens(truncated);
+  }
+
+  // Sandwich order: highest weight first (LLMs attend to the start), with
+  // same-weight blocks keeping document order so co-source chunks stay together.
+  const sorted = [...included].sort((a, b) => b.weight - a.weight || a.ordinal - b.ordinal);
+
+  return { ordered: sorted, usedRefs };
+}
diff --git a/packages/server-local/src/modules/ai/service.ts b/packages/server-local/src/modules/ai/service.ts
new file mode 100644
index 0000000..5817666
--- /dev/null
+++ b/packages/server-local/src/modules/ai/service.ts
@@ -0,0 +1,210 @@
+import type { AiConversationStore, KnowledgeStore } from "@neo-companion/db";
+import type {
+  AiAnswer,
+  AiRetrievalMode,
+  ChatMessage,
+  ContextLevel,
+  KnowledgeSource
+} from "@neo-companion/shared";
+import type { WsHub } from "../../ws-hub";
+import type { KnowledgeService } from "../knowledge/service";
+import { buildAskBlocks, packContext, type ContextBlock } from "./context";
+import { injectSources, parseAndAuditCitations, buildSources } from "./citation";
+
+/** Token budget reserved for packed knowledge context (notes/tasks/chunks). */
+const CONTEXT_TOKEN_BUDGET = 6000;
+const DEFAULT_SYSTEM_PROMPT = "你是 NeoCompanion 的中文温柔陪伴助手，回答简洁、具体，不使用强主宠称呼。";
+
+export interface ChatContextSelection {
+  notes: Record<string, ContextLevel>;
+  tasks: Record<string, ContextLevel>;
+}
+
+export interface AiServiceDeps {
+  conversationStore: AiConversationStore | null;
+  knowledgeService: KnowledgeService | null;
+  knowledgeStore: KnowledgeStore | null;
+  aiStream: (messages: ChatMessage[]) => AsyncIterable<string>;
+  hub: WsHub;
+}
+
+export interface ChatRequest {
+  message: string;
+  projectId?: string | null;
+  context?: ChatContextSelection;
+  conversationId?: string;
+}
+
+export interface AskRequest {
+  message: string;
+  projectId?: string | null;
+}
+
+export function createAiService(deps: AiServiceDeps) {
+  const { conversationStore, knowledgeService, knowledgeStore, aiStream, hub } = deps;
+
+  async function streamReply(messages: ChatMessage[]): Promise<string> {
+    let text = "";
+    for await (const chunk of aiStream(messages)) {
+      text += chunk;
+      hub.broadcast({ type: "ai:chunk", payload: { chunk } });
+    }
+    return text;
+  }
+
+  /** Plain fallback chat (no knowledge context), preserving existing behavior. */
+  async function plainChat(message: string): Promise<AiAnswer> {
+    const messages: ChatMessage[] = [
+      { role: "system", content: DEFAULT_SYSTEM_PROMPT },
+      { role: "user", content: message }
+    ];
+    hub.broadcast({ type: "companion:feedback", payload: { state: "thinking", text: "我想一想。", speak: false } });
+    const text = await streamReply(messages);
+    const answer: AiAnswer = { text, sources: [], retrievalMode: "chat" };
+    hub.broadcast({ type: "ai:done", payload: answer });
+    return answer;
+  }
+
+  async function handleChat(req: ChatRequest): Promise<AiAnswer> {
+    const ctx = req.context;
+    const hasSelection = ctx && (Object.keys(ctx.notes).length || Object.keys(ctx.tasks).length);
+    if (!hasSelection || !knowledgeStore) {
+      return plainChat(req.message);
+    }
+
+    // Resolve selected notes/tasks into context blocks.
+    const noteBlocks: ContextBlock[] = [];
+    const sourceLookup = new Map<string, KnowledgeSource>();
+    for (const [noteId, level] of Object.entries(ctx.notes)) {
+      if (level === "excluded") continue;
+      const note = knowledgeStore.getNote(noteId);
+      if (!note) continue;
+      noteBlocks.push({
+        type: "note",
+        ref: note.id,
+        content: level === "summary" ? note.body.slice(0, 400) : `${note.title}\n\n${note.body}`,
+        weight: level === "summary" ? 70 : 100,
+        ordinal: noteBlocks.length
+      });
+      sourceLookup.set(note.id, {
+        sourceType: "note", sourceId: note.id, projectId: note.projectId,
+        title: note.title, excerpt: note.body.slice(0, 120), chunkId: note.id
+      });
+    }
+    const taskBlocks: ContextBlock[] = [];
+    for (const [taskId, level] of Object.entries(ctx.tasks)) {
+      if (level === "excluded") continue;
+      const task = knowledgeStore.tasksForProject(req.projectId ?? "").find((t) => t.id === taskId);
+      if (!task) continue;
+      const content = task.description ? `${task.title}\n\n${task.description}` : task.title;
+      taskBlocks.push({ type: "task", ref: task.id, content, weight: 55, ordinal: taskBlocks.length });
+      sourceLookup.set(task.id, {
+        sourceType: "task", sourceId: task.id, projectId: task.projectId,
+        title: task.title, excerpt: content.slice(0, 120), chunkId: task.id
+      });
+    }
+
+    const packed = packContext([...noteBlocks, ...taskBlocks], CONTEXT_TOKEN_BUDGET);
+    if (!packed.ordered.length) return plainChat(req.message);
+
+    const injected = injectSources(packed.ordered);
+    const validIds = new Set(injected.idToRef.keys());
+
+    // Multi-turn: load history for the conversation.
+    let conversationId = req.conversationId;
+    const historyMessages: ChatMessage[] = [];
+    if (conversationStore && conversationId) {
+      const msgs = conversationStore.listMessages(conversationId);
+      for (const m of msgs) {
+        if (m.role === "user" || m.role === "assistant") {
+          historyMessages.push({ role: m.role, content: m.content });
+        }
+      }
+    } else if (conversationStore && req.projectId !== undefined) {
+      const conv = conversationStore.createConversation(req.projectId ?? null, "chat");
+      conversationId = conv.id;
+    }
+
+    const messages: ChatMessage[] = [
+      { role: "system", content: `${injected.systemPrompt}\n\n${injected.contextText}` },
+      ...historyMessages,
+      { role: "user", content: req.message }
+    ];
+
+    hub.broadcast({ type: "companion:feedback", payload: { state: "thinking", text: "我想一想。", speak: false } });
+    let text: string;
+    try {
+      text = await streamReply(messages);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : "AI request failed";
+      hub.broadcast({ type: "ai:error", payload: { message: msg } });
+      throw error;
+    }
+
+    const audited = parseAndAuditCitations(text, validIds);
+    const sources = buildSources(injected, audited.citedIds, sourceLookup);
+
+    // Persist the turn.
+    if (conversationStore && conversationId) {
+      conversationStore.appendMessage(conversationId, "user", req.message);
+      conversationStore.appendMessage(conversationId, "assistant", audited.cleanedText, sources);
+    }
+
+    const answer: AiAnswer = { text: audited.cleanedText, sources, retrievalMode: "chat" };
+    hub.broadcast({ type: "ai:done", payload: answer });
+    return answer;
+  }
+
+  async function handleAsk(req: AskRequest): Promise<AiAnswer> {
+    if (!knowledgeService || !req.projectId) return plainChat(req.message);
+
+    const sources = await knowledgeService.searchHybrid(req.projectId, req.message, 8);
+    if (!sources.length) return plainChat(req.message);
+
+    const sourceLookup = new Map<string, KnowledgeSource>();
+    sources.forEach((s) => sourceLookup.set(s.sourceId, s));
+    const blocks = buildAskBlocks(sources, new Map());
+    const packed = packContext(blocks, CONTEXT_TOKEN_BUDGET);
+    if (!packed.ordered.length) return plainChat(req.message);
+
+    const injected = injectSources(packed.ordered);
+    const validIds = new Set(injected.idToRef.keys());
+
+    const messages: ChatMessage[] = [
+      { role: "system", content: `${injected.systemPrompt}\n\n${injected.contextText}` },
+      { role: "user", content: req.message }
+    ];
+
+    hub.broadcast({ type: "companion:feedback", payload: { state: "thinking", text: "我查一下笔记。", speak: false } });
+    let text: string;
+    try {
+      text = await streamReply(messages);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : "AI request failed";
+      hub.broadcast({ type: "ai:error", payload: { message: msg } });
+      throw error;
+    }
+
+    const audited = parseAndAuditCitations(text, validIds);
+    const finalSources = buildSources(injected, audited.citedIds, sourceLookup);
+
+    // Ask is one-shot; persist a single-turn conversation for history.
+    if (conversationStore && req.projectId) {
+      const conv = conversationStore.createConversation(req.projectId, "ask");
+      conversationStore.appendMessage(conv.id, "user", req.message);
+      conversationStore.appendMessage(conv.id, "assistant", audited.cleanedText, finalSources);
+    }
+
+    const answer: AiAnswer = { text: audited.cleanedText, sources: finalSources, retrievalMode: "ask" };
+    hub.broadcast({ type: "ai:done", payload: answer });
+    return answer;
+  }
+
+  return { handleChat, handleAsk, plainChat };
+}
+
+export type AiService = ReturnType<typeof createAiService>;
+
+export function resolveMode(mode: unknown): AiRetrievalMode {
+  return mode === "ask" ? "ask" : "chat";
+}
diff --git a/packages/server-local/src/modules/knowledge/indexer.test.ts b/packages/server-local/src/modules/knowledge/indexer.test.ts
index 9b3dbc8..73eb26e 100644
--- a/packages/server-local/src/modules/knowledge/indexer.test.ts
+++ b/packages/server-local/src/modules/knowledge/indexer.test.ts
@@ -69,20 +69,20 @@ describe.skipIf(!isSqliteAvailable())("knowledge indexer (FTS5)", () => {
     const database = createDatabase(":memory:");
     const store = createKnowledgeStore(database);
     const service = createKnowledgeService(store);
-    const status = service.indexStatus(false, false);
+    const status = service.indexStatus();
     expect(status.mode).toBe("fts-only");
     expect(status.vectorExtensionAvailable).toBe(false);
     database.close();
   });
 
-  it("reindexAll walks every project", () => {
+  it("reindexAll walks every project", async () => {
     const database = createDatabase(":memory:");
     const store = createKnowledgeStore(database);
     const service = createKnowledgeService(store);
     const p = store.createProject({ title: "P" });
     store.createNote(p.id, "笔记一");
     store.createTask(p.id, "", "任务一");
-    const counts = service.reindexAll();
+    const counts = await service.reindexAll();
     expect(counts.notes).toBe(1);
     expect(counts.tasks).toBe(1);
     database.close();
diff --git a/packages/server-local/src/modules/knowledge/mirror.test.ts b/packages/server-local/src/modules/knowledge/mirror.test.ts
index 57f0700..53ebd04 100644
--- a/packages/server-local/src/modules/knowledge/mirror.test.ts
+++ b/packages/server-local/src/modules/knowledge/mirror.test.ts
@@ -103,7 +103,17 @@ function createFakeStore(): KnowledgeStore {
     getIndexStatus: () => ({
       mode: "fts-only" as const, pending: 0, failed: 0, stale: 0,
       providerConfigured: false, vectorExtensionAvailable: false
-    })
+    }),
+    vecLoaded: false,
+    ensureVecTable: () => false,
+    searchKnn: () => [],
+    putVecChunk: () => {},
+    delVecChunk: () => {},
+    getCachedEmbedding: () => null as { vector: number[]; dimensions: number } | null,
+    putCachedEmbedding: () => {},
+    listPendingChunks: () => [],
+    markChunkIndexed: () => {},
+    markChunkFailed: () => {}
   };
   return store;
 }
diff --git a/packages/server-local/src/modules/knowledge/routes.ts b/packages/server-local/src/modules/knowledge/routes.ts
index da1a1d5..6999aa9 100644
--- a/packages/server-local/src/modules/knowledge/routes.ts
+++ b/packages/server-local/src/modules/knowledge/routes.ts
@@ -4,7 +4,13 @@ import type {
   KnowledgeTaskStatus
 } from "@neo-companion/shared";
 import { exportToDir, importFromDir } from "./mirror";
-import type { KnowledgeService } from "./service";
+import type { EmbeddingConfig, KnowledgeService } from "./service";
+
+/** Lets the embedding-config route read/mutate the shared config held in app.ts. */
+export interface EmbeddingConfigController {
+  get(): EmbeddingConfig;
+  set(config: EmbeddingConfig): void;
+}
 
 /**
  * Knowledge workspace REST routes (Phase 1 CRUD).
@@ -16,7 +22,12 @@ import type { KnowledgeService } from "./service";
  * Retrieval (search / index-status / reindex) and AI integration land in
  * Phase 2–4 via modules/knowledge/service.ts.
  */
-export function registerKnowledgeRoutes(app: FastifyInstance, store: KnowledgeStore | null, service: KnowledgeService | null) {
+export function registerKnowledgeRoutes(
+  app: FastifyInstance,
+  store: KnowledgeStore | null,
+  service: KnowledgeService | null,
+  embeddingConfigController?: EmbeddingConfigController
+) {
   // File-mirror root path. The frontend owns the canonical path in localStorage
   // (useSettings.knowledgeRootPath) and pushes it here so the sidecar can do
   // export/import. Empty until the user picks a folder.
@@ -234,14 +245,13 @@ export function registerKnowledgeRoutes(app: FastifyInstance, store: KnowledgeSt
     const query = request.query as { q?: string; projectId?: string; limit?: string };
     if (!query.q?.trim()) return reply.code(400).send({ error: "q is required" });
     const limit = query.limit ? Number.parseInt(query.limit, 10) : 20;
-    return svc.search(query.projectId ?? null, query.q, Number.isFinite(limit) ? limit : 20);
+    return svc.searchHybrid(query.projectId ?? null, query.q, Number.isFinite(limit) ? limit : 20);
   });
 
   app.get("/api/knowledge/index-status", async (request, reply) => {
     const svc = requireService(reply);
     if (!svc) return;
-    // Phase 3 will pass real provider/vector flags; for now FTS-only mode.
-    return svc.indexStatus(false, false);
+    return svc.indexStatus();
   });
 
   app.post("/api/knowledge/reindex", async (request, reply) => {
@@ -252,6 +262,40 @@ export function registerKnowledgeRoutes(app: FastifyInstance, store: KnowledgeSt
     return svc.reindexAll();
   });
 
+  // ── Embedding provider config (Phase 3) ──
+  // Server holds the config in memory (pushed from the client, like root-path);
+  // apiKey is never echoed back.
+  app.get("/api/knowledge/embedding-config", async () => {
+    const cfg = embeddingConfigController?.get() ?? { provider: "none" };
+    return {
+      provider: cfg.provider,
+      baseUrl: cfg.baseUrl ?? "",
+      model: cfg.model ?? "",
+      configured: !!cfg.apiKey && cfg.provider !== "none"
+    };
+  });
+
+  app.put("/api/knowledge/embedding-config", async (request, reply) => {
+    if (!embeddingConfigController) return reply.code(503).send({ error: "embedding config unavailable" });
+    const body = request.body as Partial<EmbeddingConfig>;
+    const current = embeddingConfigController.get();
+    // empty apiKey on PUT means "keep existing" (UI masks the secret)
+    const apiKey = body.apiKey ? body.apiKey : current.apiKey;
+    const next: EmbeddingConfig = {
+      provider: body.provider ?? current.provider,
+      baseUrl: body.baseUrl ?? current.baseUrl,
+      apiKey,
+      model: body.model ?? current.model
+    };
+    embeddingConfigController.set(next);
+    // model change → mark stale so chunks re-embed with the new model
+    if (next.model && next.model !== current.model) {
+      service?.markStale(next.model);
+    }
+    await service?.drainEmbeddings();
+    return { ok: true };
+  });
+
   // ── File mirror (hybrid SQLite + Markdown/JSONL) ──
   app.get("/api/knowledge/root-path", async () => ({ path: rootPath }));
 
diff --git a/packages/server-local/src/modules/knowledge/rrf.test.ts b/packages/server-local/src/modules/knowledge/rrf.test.ts
new file mode 100644
index 0000000..627b371
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/rrf.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import type { KnowledgeSource } from "@neo-companion/shared";
+import { fuseRrf } from "./rrf";
+
+function src(sourceType: "note" | "task", sourceId: string, projectId = "p"): KnowledgeSource {
+  return { sourceType, sourceId, projectId, title: sourceId, excerpt: "", chunkId: sourceId };
+}
+
+describe("fuseRrf", () => {
+  it("returns empty for two empty lists", () => {
+    expect(fuseRrf([], [])).toEqual([]);
+  });
+
+  it("fuses two non-overlapping ranked lists", () => {
+    const fts = [src("note", "a"), src("note", "b")];
+    const knn = [src("note", "c"), src("note", "d")];
+    const out = fuseRrf(fts, knn);
+    expect(out.map((s) => s.sourceId)).toEqual(["a", "c", "b", "d"]);
+  });
+
+  it("boosts sources appearing in both lists (a wins over c)", () => {
+    const fts = [src("note", "a"), src("note", "b")];
+    const knn = [src("note", "c"), src("note", "a")]; // a appears in both
+    const out = fuseRrf(fts, knn);
+    // a: 1/61 + 1/62 ≈ 0.0325 ; c: 1/61 ≈ 0.0164 ; b: 1/62 ≈ 0.0161
+    expect(out[0].sourceId).toBe("a");
+    expect(out.map((s) => s.sourceId)).toEqual(["a", "c", "b"]);
+  });
+
+  it("dedups by source across lists (keeps the fused entry once)", () => {
+    const fts = [src("note", "a")];
+    const knn = [src("note", "a")];
+    const out = fuseRrf(fts, knn);
+    expect(out).toHaveLength(1);
+    expect(out[0].sourceId).toBe("a");
+  });
+
+  it("distinguishes note vs task with same id", () => {
+    const fts = [src("note", "x")];
+    const knn = [src("task", "x")];
+    const out = fuseRrf(fts, knn);
+    expect(out).toHaveLength(2);
+  });
+
+  it("respects custom k", () => {
+    const fts = [src("note", "a")];
+    const knn = [src("note", "b")];
+    const outK1 = fuseRrf(fts, knn, 1);
+    const outK60 = fuseRrf(fts, knn, 60);
+    // ordering identical here, but scores differ; just ensure no throw + length
+    expect(outK1).toHaveLength(2);
+    expect(outK60).toHaveLength(2);
+  });
+});
diff --git a/packages/server-local/src/modules/knowledge/rrf.ts b/packages/server-local/src/modules/knowledge/rrf.ts
new file mode 100644
index 0000000..c351160
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/rrf.ts
@@ -0,0 +1,39 @@
+import type { KnowledgeSource } from "@neo-companion/shared";
+
+/**
+ * Reciprocal Rank Fusion (Cormack 2009, k=60). Fuses two ranked source lists
+ * into one by summing `1/(k + rank)` per source; a source appearing in both
+ * lists gets both contributions. Input lists are assumed already deduped per
+ * source and ordered best-first (rank 1 = best).
+ */
+export function fuseRrf(
+  ftsRanked: KnowledgeSource[],
+  knnRanked: KnowledgeSource[],
+  k = 60
+): KnowledgeSource[] {
+  const scores = new Map<string, { source: KnowledgeSource; score: number }>();
+
+  const add = (list: KnowledgeSource[]): void => {
+    list.forEach((source, index) => {
+      const key = sourceKey(source);
+      const contribution = 1 / (k + (index + 1));
+      const existing = scores.get(key);
+      if (existing) {
+        existing.score += contribution;
+      } else {
+        scores.set(key, { source, score: contribution });
+      }
+    });
+  };
+
+  add(ftsRanked);
+  add(knnRanked);
+
+  return [...scores.values()]
+    .sort((a, b) => b.score - a.score)
+    .map((entry) => entry.source);
+}
+
+function sourceKey(s: KnowledgeSource): string {
+  return `${s.sourceType}:${s.sourceId}`;
+}
diff --git a/packages/server-local/src/modules/knowledge/service.ts b/packages/server-local/src/modules/knowledge/service.ts
index a4a3378..c255dfd 100644
--- a/packages/server-local/src/modules/knowledge/service.ts
+++ b/packages/server-local/src/modules/knowledge/service.ts
@@ -1,15 +1,41 @@
 import type { KnowledgeStore } from "@neo-companion/db";
 import type { KnowledgeNote, KnowledgeTask, KnowledgeTaskStatus, KnowledgeSource, IndexStatus } from "@neo-companion/shared";
 import { chunkMarkdown, chunkTask, resolveChunkingConfig, type Chunk } from "./chunker";
+import { fuseRrf } from "./rrf";
+
+/** Embedding provider config pushed from the client (see /embedding-config route). */
+export interface EmbeddingConfig {
+  provider: string; // "none" | "openai" | "cohere" | "local" | ...
+  baseUrl?: string;
+  apiKey?: string;
+  model?: string;
+}
+
+export interface EmbeddingCallOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+}
+
+export type EmbedFn = (texts: string[], options: EmbeddingCallOptions) => Promise<{ vectors: number[][]; dimensions: number }>;
+
+export interface KnowledgeServiceOptions {
+  embedFn?: EmbedFn;
+  getEmbeddingConfig?: () => EmbeddingConfig | null;
+}
+
+const DRAIN_BATCH = 64;
 
 /**
  * Knowledge service: wraps the store so every note/task write triggers a
  * re-chunk + FTS5 sync. The chunker is pure (in this package); the store owns
  * the raw sqlite FTS writes. This keeps the db package free of a
- * server-local dependency.
+ * server-local dependency. Phase 3 adds an async embedding drain that consumes
+ * pending chunks into the vec0 table, plus hybrid (FTS5 + vector RRF) search.
  */
-export function createKnowledgeService(store: KnowledgeStore) {
+export function createKnowledgeService(store: KnowledgeStore, options: KnowledgeServiceOptions = {}) {
   const config = resolveChunkingConfig();
+  const { embedFn, getEmbeddingConfig } = options;
 
   function chunkNoteText(text: string): { content: string; contentHash: string }[] {
     return chunkMarkdown(text, config).map((c: Chunk) => ({ content: c.content, contentHash: c.contentHash }));
@@ -18,31 +44,127 @@ export function createKnowledgeService(store: KnowledgeStore) {
     return chunkTask("", text, config).map((c: Chunk) => ({ content: c.content, contentHash: c.contentHash }));
   }
 
+  function embeddingConfig(): EmbeddingConfig | null {
+    return getEmbeddingConfig?.() ?? null;
+  }
+  function providerConfigured(): boolean {
+    const cfg = embeddingConfig();
+    return !!cfg && cfg.provider !== "none" && !!cfg.apiKey && !!cfg.model;
+  }
+  function embedCallOptions(): EmbeddingCallOptions {
+    const cfg = embeddingConfig() ?? { provider: "none" };
+    return { apiKey: cfg.apiKey, baseUrl: cfg.baseUrl, model: cfg.model };
+  }
+
+  let draining = false;
+  /**
+   * Consume pending/stale chunks: embed in batches (with content-hash cache
+   * reuse), write vectors into vec0, mark indexed/failed. Single-flight via the
+   * `draining` flag. No-op when vec/embedding unavailable. Fire-and-forget from
+   * write paths; awaited from explicit reindex.
+   */
+  async function drainEmbeddingQueue(): Promise<void> {
+    if (draining) return;
+    if (!embedFn || !store.vecLoaded || !providerConfigured()) return;
+    draining = true;
+    try {
+      const model = embeddingConfig()!.model!;
+      while (true) {
+        const pending = store.listPendingChunks(DRAIN_BATCH);
+        if (!pending.length) break;
+
+        const cached: Array<{ chunk: (typeof pending)[number]; emb: { vector: number[]; dimensions: number } }> = [];
+        const need: Array<{ chunk: (typeof pending)[number]; idx: number }> = [];
+        for (const chunk of pending) {
+          const hit = store.getCachedEmbedding(chunk.contentHash);
+          if (hit) cached.push({ chunk, emb: hit });
+          else need.push({ chunk, idx: need.length });
+        }
+
+        let dim: number | null = null;
+        let newVecs: number[][] = [];
+
+        if (need.length) {
+          try {
+            const result = await embedFn(need.map((n) => n.chunk.content), embedCallOptions());
+            dim = result.dimensions;
+            if (!store.ensureVecTable(dim)) break;
+            newVecs = result.vectors;
+            for (const n of need) {
+              const v = newVecs[n.idx];
+              if (!v || v.length !== dim) {
+                store.markChunkFailed(n.chunk.id, "embedding dimension mismatch");
+                continue;
+              }
+              store.putVecChunk(n.chunk.id, v);
+              store.putCachedEmbedding(n.chunk.contentHash, v, model, dim);
+              store.markChunkIndexed(n.chunk.id, model, dim);
+            }
+          } catch (error) {
+            const msg = error instanceof Error ? error.message : "embedding failed";
+            for (const n of need) store.markChunkFailed(n.chunk.id, msg);
+            break; // avoid tight retry loop; next write/reindex re-triggers
+          }
+        }
+
+        for (const c of cached) {
+          if (dim === null) dim = c.emb.dimensions;
+          if (!store.ensureVecTable(dim)) break;
+          store.putVecChunk(c.chunk.id, c.emb.vector);
+          store.markChunkIndexed(c.chunk.id, model, dim);
+        }
+      }
+    } finally {
+      draining = false;
+    }
+  }
+
   return {
     config,
 
     reindexNote(note: KnowledgeNote): void {
       store.reindexNote(note, chunkNoteText);
+      void drainEmbeddingQueue();
     },
 
     reindexTask(task: KnowledgeTask): void {
       store.reindexTask(task, (text) => chunkTaskText(text));
+      void drainEmbeddingQueue();
     },
 
+    /** Synchronous FTS5-only search (kept for backward-compatible tests). */
     search(projectId: string | null, query: string, limit = 20): KnowledgeSource[] {
       return store.searchFts(projectId, query, limit);
     },
 
-    indexStatus(providerConfigured: boolean, vectorExtensionAvailable: boolean): IndexStatus {
-      return store.getIndexStatus(providerConfigured, vectorExtensionAvailable);
+    /** Hybrid search: FTS5 BM25 + sqlite-vec KNN fused via RRF. Falls back to
+     * FTS-only when vec/embedding is unavailable or the query embedding fails. */
+    async searchHybrid(projectId: string | null, query: string, limit = 20): Promise<KnowledgeSource[]> {
+      const fts = store.searchFts(projectId, query, limit);
+      if (!store.vecLoaded || !providerConfigured() || !embedFn) return fts;
+      try {
+        const result = await embedFn([query], embedCallOptions());
+        const queryVec = result.vectors[0];
+        if (!queryVec) return fts;
+        const knn = store.searchKnn(queryVec, limit, projectId);
+        if (!knn.length) return fts;
+        return fuseRrf(fts, knn);
+      } catch {
+        return fts;
+      }
+    },
+
+    indexStatus(): IndexStatus {
+      return store.getIndexStatus(providerConfigured());
     },
 
     markStale(embeddingModel?: string): void {
       store.markStale(embeddingModel);
+      void drainEmbeddingQueue();
     },
 
-    /** Re-chunk every note + task in the workspace (manual rebuild). */
-    reindexAll(): { notes: number; tasks: number } {
+    /** Explicit rebuild: re-chunk everything, then drain embeddings. */
+    async reindexAll(): Promise<{ notes: number; tasks: number }> {
       let notes = 0;
       let tasks = 0;
       for (const project of store.listProjects()) {
@@ -55,7 +177,13 @@ export function createKnowledgeService(store: KnowledgeStore) {
           tasks += 1;
         }
       }
+      await drainEmbeddingQueue();
       return { notes, tasks };
+    },
+
+    /** Trigger embedding drain without re-chunking (e.g. after config change). */
+    async drainEmbeddings(): Promise<void> {
+      await drainEmbeddingQueue();
     }
   };
 }
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 3bd8663..e1413c1 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -219,7 +219,7 @@ export interface KnowledgeSource {
 }
 
 /** Rich index status returned by the API; the UI maps it to KnowledgeIndexState. */
-export type IndexMode = "hybrid" | "fts-only";
+export type IndexMode = "hybrid" | "fts-only" | "indexing";
 
 export interface IndexStatus {
   mode: IndexMode;
@@ -246,4 +246,22 @@ export interface AiAnswer {
   retrievalMode: AiRetrievalMode;
 }
 
+/** AI 多轮会话（Phase 4，与 v1 pet 对话表分离）。 */
+export interface AiConversation {
+  id: string;
+  projectId: string | null;
+  mode: AiRetrievalMode;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface AiMessage {
+  id: string;
+  conversationId: string;
+  role: "system" | "user" | "assistant";
+  content: string;
+  sources: KnowledgeSource[];
+  createdAt: number;
+}
+
 export type KnowledgeChunkIndexStatus = "pending" | "indexed" | "failed" | "stale";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b727fcf..623476b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -118,6 +118,9 @@ importers:
       drizzle-orm:
         specifier: 0.45.2
         version: 0.45.2(@types/better-sqlite3@7.6.13)(better-sqlite3@12.10.0)
+      sqlite-vec:
+        specifier: ^0.1.9
+        version: 0.1.9
     devDependencies:
       '@types/better-sqlite3':
         specifier: ^7.6.13
@@ -1617,6 +1620,34 @@ packages:
     resolution: {integrity: sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==}
     engines: {node: '>= 10.x'}
 
+  sqlite-vec-darwin-arm64@0.1.9:
+    resolution: {integrity: sha512-jSsZpE42OfBkGL/ItyJTVCUwl6o6Ka3U5rc4j+UBDIQzC1ulSSKMEhQLthsOnF/MdAf1MuAkYhkdKmmcjaIZQg==}
+    cpu: [arm64]
+    os: [darwin]
+
+  sqlite-vec-darwin-x64@0.1.9:
+    resolution: {integrity: sha512-KDlVyqQT7pnOhU1ymB9gs7dMbSoVmKHitT+k1/xkjarcX8bBqPxWrGlK/R+C5WmWkfvWwyq5FfXfiBYCBs6PlA==}
+    cpu: [x64]
+    os: [darwin]
+
+  sqlite-vec-linux-arm64@0.1.9:
+    resolution: {integrity: sha512-5wXVJ9c9kR4CHm/wVqXb/R+XUHTdpZ4nWbPHlS+gc9qQFVHs92Km4bPnCKX4rtcPMzvNis+SIzMJR1SCEwpuUw==}
+    cpu: [arm64]
+    os: [linux]
+
+  sqlite-vec-linux-x64@0.1.9:
+    resolution: {integrity: sha512-w3tCH8xK2finW8fQJ/m8uqKodXUZ9KAuAar2UIhz4BHILfpE0WM/MTGCRfa7RjYbrYim5Luk3guvMOGI7T7JQA==}
+    cpu: [x64]
+    os: [linux]
+
+  sqlite-vec-windows-x64@0.1.9:
+    resolution: {integrity: sha512-y3gEIyy/17bq2QFPQOWLE68TYWcRZkBQVA2XLrTPHNTOp55xJi/BBBmOm40tVMDMjtP+Elpk6UBUXdaq+46b0Q==}
+    cpu: [x64]
+    os: [win32]
+
+  sqlite-vec@0.1.9:
+    resolution: {integrity: sha512-L7XJWRIBNvR9O5+vh1FQ+IGkh/3D2AzVksW5gdtk28m78Hy8skFD0pqReKH1Yp0/BUKRGcffgKvyO/EON5JXpA==}
+
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -3170,6 +3201,29 @@ snapshots:
 
   split2@4.2.0: {}
 
+  sqlite-vec-darwin-arm64@0.1.9:
+    optional: true
+
+  sqlite-vec-darwin-x64@0.1.9:
+    optional: true
+
+  sqlite-vec-linux-arm64@0.1.9:
+    optional: true
+
+  sqlite-vec-linux-x64@0.1.9:
+    optional: true
+
+  sqlite-vec-windows-x64@0.1.9:
+    optional: true
+
+  sqlite-vec@0.1.9:
+    optionalDependencies:
+      sqlite-vec-darwin-arm64: 0.1.9
+      sqlite-vec-darwin-x64: 0.1.9
+      sqlite-vec-linux-arm64: 0.1.9
+      sqlite-vec-linux-x64: 0.1.9
+      sqlite-vec-windows-x64: 0.1.9
+
   stackback@0.0.2: {}
 
   std-env@4.1.0: {}

From e5d7e6de8d9aa79230617505d5b9df72d9ffff53 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 19:54:17 +0800
Subject: [PATCH 2/6] =?UTF-8?q?test(knowledge):=20=E4=BF=AE=E5=A4=8D=20vec?=
 =?UTF-8?q?=20=E6=B5=8B=E8=AF=95=E2=80=94=E2=80=94=E6=98=BE=E5=BC=8F=20rei?=
 =?UTF-8?q?ndex=20=E4=BA=A7=E7=94=9F=20chunk=20+=20Float32=20=E8=BF=91?=
 =?UTF-8?q?=E4=BC=BC=E6=AF=94=E8=BE=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI 在真实 sqlite-vec 环境暴露两个本机 skipIf 漏掉的问题：
- KNN 测试用 updateNote 后未 reindex → 无 chunk → listPendingChunks 空。改用 reindexNote 显式触发。
- cache 测试 toEqual 失败：Float32 序列化 0.1→0.10000000149 精度损失。改 toBeCloseTo。

Co-Authored-By: Claude <noreply@anthropic.com>
---
 packages/db/src/db.test.ts | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/packages/db/src/db.test.ts b/packages/db/src/db.test.ts
index 048d787..673f50b 100644
--- a/packages/db/src/db.test.ts
+++ b/packages/db/src/db.test.ts
@@ -92,6 +92,10 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge store", () => {
 });
 
 describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
+  // Minimal chunk fn: one chunk per whole text (db test stays free of the
+  // server-local chunker). content-hash via a simple substring stamp.
+  const simpleChunk = (text: string) => [{ content: text, contentHash: `h-${text.length}` }];
+
   it("loads sqlite-vec, writes chunks, and returns KNN hits", () => {
     const database = createDatabase(":memory:");
     const kw = createKnowledgeStore(database);
@@ -102,14 +106,14 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
 
     const project = kw.createProject({ title: "P" });
     const note = kw.createNote(project.id, "向量化笔记");
-    kw.updateNote(note.id, { body: "sqlite-vec 向量检索" });
+    const updated = kw.updateNote(note.id, { body: "sqlite-vec 向量检索" })!;
+    // updateNote does not auto-reindex; reindex explicitly to produce chunks.
+    kw.reindexNote(updated, simpleChunk);
 
-    // simulate an embedded chunk: insert a pending chunk then put its vector
     const pending = kw.listPendingChunks(10);
     expect(pending.length).toBeGreaterThanOrEqual(1);
     const chunk = pending[0];
-    const vec = [0.1, 0.2, 0.3, 0.4];
-    kw.putVecChunk(chunk.id, vec);
+    kw.putVecChunk(chunk.id, [0.1, 0.2, 0.3, 0.4]);
     kw.markChunkIndexed(chunk.id, "test-embed", dim);
 
     const hits = kw.searchKnn([0.1, 0.2, 0.3, 0.4], 5, null);
@@ -126,10 +130,10 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
 
     const a = kw.createProject({ title: "A" });
     const b = kw.createProject({ title: "B" });
-    const noteA = kw.createNote(a.id, "A 笔记");
-    kw.updateNote(noteA.id, { body: "内容 A" });
-    const noteB = kw.createNote(b.id, "B 笔记");
-    kw.updateNote(noteB.id, { body: "内容 B" });
+    const noteA = kw.updateNote(kw.createNote(a.id, "A 笔记").id, { body: "内容 A" })!;
+    const noteB = kw.updateNote(kw.createNote(b.id, "B 笔记").id, { body: "内容 B" })!;
+    kw.reindexNote(noteA, simpleChunk);
+    kw.reindexNote(noteB, simpleChunk);
 
     const pending = kw.listPendingChunks(20);
     for (const c of pending) {
@@ -147,7 +151,14 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
     const kw = createKnowledgeStore(database);
     const vec = [0.1, 0.2, 0.3];
     kw.putCachedEmbedding("hash-1", vec, "test-embed", 3);
-    expect(kw.getCachedEmbedding("hash-1")).toEqual({ vector: vec, dimensions: 3 });
+    const got = kw.getCachedEmbedding("hash-1");
+    expect(got).not.toBeNull();
+    expect(got!.dimensions).toBe(3);
+    // Float32 round-trip introduces tiny error; compare approximately.
+    expect(got!.vector.length).toBe(3);
+    expect(got!.vector[0]).toBeCloseTo(0.1, 5);
+    expect(got!.vector[1]).toBeCloseTo(0.2, 5);
+    expect(got!.vector[2]).toBeCloseTo(0.3, 5);
     expect(kw.getCachedEmbedding("missing")).toBeNull();
     database.close();
   });

From f7fb066a78375a820ed289776bb7a15e74d17268 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 19:55:56 +0800
Subject: [PATCH 3/6] =?UTF-8?q?test(knowledge):=20index-status=20=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E6=94=B9=E4=B8=BA=E5=8F=8D=E6=98=A0=E7=9C=9F=E5=AE=9E?=
 =?UTF-8?q?=E8=AF=AD=E4=B9=89=E2=80=94=E2=80=94=E6=97=A0=20provider=20?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E5=8D=B3=20fts-only?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

原测试断言 vectorExtensionAvailable===false，但 CI 环境 vec 实际加载成功。
真实语义：mode 由 vecLoaded && providerConfigured 共同决定；无 embedding provider
配置时（providerConfigured=false）即为 fts-only，与 vec 是否加载无关。

Co-Authored-By: Claude <noreply@anthropic.com>
---
 packages/server-local/src/modules/knowledge/indexer.test.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/server-local/src/modules/knowledge/indexer.test.ts b/packages/server-local/src/modules/knowledge/indexer.test.ts
index 73eb26e..a1f6874 100644
--- a/packages/server-local/src/modules/knowledge/indexer.test.ts
+++ b/packages/server-local/src/modules/knowledge/indexer.test.ts
@@ -65,13 +65,15 @@ describe.skipIf(!isSqliteAvailable())("knowledge indexer (FTS5)", () => {
     database.close();
   });
 
-  it("reports index status (fts-only when no vector ext)", () => {
+  it("reports fts-only mode when no embedding provider is configured", () => {
     const database = createDatabase(":memory:");
     const store = createKnowledgeStore(database);
+    // No embedding config injected → providerConfigured=false → fts-only,
+    // regardless of whether the vec extension itself loaded.
     const service = createKnowledgeService(store);
     const status = service.indexStatus();
     expect(status.mode).toBe("fts-only");
-    expect(status.vectorExtensionAvailable).toBe(false);
+    expect(status.providerConfigured).toBe(false);
     database.close();
   });
 

From 83ab55a881af03a6a62cfd100ad6ba9aa2472402 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sun, 21 Jun 2026 16:46:59 +0800
Subject: [PATCH 4/6] =?UTF-8?q?feat(knowledge):=20Phase=204=20AI=20?=
 =?UTF-8?q?=E9=9D=A2=E6=9D=BF=E5=89=8D=E7=AB=AF=20+=20=E9=85=8D=E7=BD=AE?=
 =?UTF-8?q?=E8=90=BD=E5=BA=93=20+=20=E5=90=91=E9=87=8F=E9=99=8D=E7=BA=A7?=
 =?UTF-8?q?=E5=8F=AF=E8=A7=81=20+=20=E6=96=87=E6=A1=A3=E5=90=8C=E6=AD=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

环境：本机 better-sqlite3 原生 binding 经 prebuild-install 就位，向量检索链路
（FTS5 + sqlite-vec KNN + RRF + 硅基流动 bge-m3 embedding）端到端验证通过，
此前 skip 的 vec/indexer 测试转为通过。

代码优化：
- embedding 配置落库 app_config 表，sidecar 重启不丢失；apiKey 双通道
  （落库 or 环境变量 EMBEDDING_API_KEY），GET 不回显并返回 apiKeySource。
- IndexStatus 暴露 vecVersion/vecLoadError，前端 banner 显示向量降级原因，
  不再静默 fts-only。
- useKnowledgeApi 接入真实 index-status 端点，简化态映射 + 降级原因透传。
- 修复 useKnowledgeApi 定时器 window 依赖（jsdom cleanup 后失效）。

Phase 4 前端：KnowledgeAiPanel + useKnowledgeAi（Chat/Ask 双模式、三级上下文
权限、引用点击跳转、WS 流式），KnowledgeView/ProjectWorkspace 集成。

文档：ARCHITECTURE §1.2 状态更新、新增 §9.4 AI Chat/Ask 双模式与引用审计；
TODO_INVENTORY/API 同步后端已实现状态。
---
 .../components/knowledge/KnowledgeAiPanel.vue | 159 +++++++++
 .../components/knowledge/ProjectWorkspace.vue |  13 +-
 .../desktop/src/composables/useKnowledgeAi.ts | 228 ++++++++++++
 .../src/composables/useKnowledgeApi.ts        |  39 +-
 .../src/composables/useKnowledgeMock.ts       |   3 +-
 .../src/composables/useKnowledgeWorkspace.ts  |   1 +
 apps/desktop/src/styles/knowledge.css         | 337 ++++++++++++++++++
 apps/desktop/src/views/KnowledgeView.vue      |  19 +-
 docs/API.md                                   |  26 +-
 docs/ARCHITECTURE.md                          |  61 +++-
 docs/TODO_INVENTORY.md                        |  21 +-
 packages/db/src/index.ts                      |  36 +-
 packages/server-local/src/app.ts              |  23 +-
 .../server-local/src/modules/ai/service.ts    |   6 +-
 .../src/modules/knowledge/routes.ts           |  23 +-
 .../src/modules/knowledge/service.ts          |   9 +-
 packages/shared/src/index.ts                  |   6 +
 17 files changed, 964 insertions(+), 46 deletions(-)
 create mode 100644 apps/desktop/src/components/knowledge/KnowledgeAiPanel.vue
 create mode 100644 apps/desktop/src/composables/useKnowledgeAi.ts

diff --git a/apps/desktop/src/components/knowledge/KnowledgeAiPanel.vue b/apps/desktop/src/components/knowledge/KnowledgeAiPanel.vue
new file mode 100644
index 0000000..6dfd452
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/KnowledgeAiPanel.vue
@@ -0,0 +1,159 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+import {
+  stripCitations,
+  type KnowledgeAiState
+} from "../../composables/useKnowledgeAi";
+import type { ContextLevel, KnowledgeSource } from "@neo-companion/shared";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+  ai: KnowledgeAiState;
+}>();
+
+const inputText = ref("");
+const contextOpen = ref(false);
+
+function onSend(): void {
+  if (!inputText.value.trim() || props.ai.chatLoading.value) return;
+  const text = inputText.value;
+  inputText.value = "";
+  void props.ai.send(text);
+}
+
+function levelOf(id: string): string {
+  return props.ai.contextLabel[props.ai.contextSelection.value[id] ?? "full"];
+}
+
+function levelClassOf(id: string): ContextLevel {
+  return props.ai.contextSelection.value[id] ?? "full";
+}
+
+function sourceKindLabel(source: KnowledgeSource): string {
+  return source.sourceType === "note" ? "笔记" : "任务";
+}
+</script>
+
+<template>
+  <div class="knowledge-ai-panel">
+    <header class="knowledge-ai-header">
+      <div class="quick-create-modes knowledge-ai-modes">
+        <button
+          type="button"
+          class="quick-create-mode"
+          :class="{ active: ai.aiMode.value === 'chat' }"
+          @click="ai.aiMode.value = 'chat'"
+        >
+          对话
+        </button>
+        <button
+          type="button"
+          class="quick-create-mode"
+          :class="{ active: ai.aiMode.value === 'ask' }"
+          @click="ai.aiMode.value = 'ask'"
+        >
+          问答
+        </button>
+      </div>
+
+      <p class="knowledge-ai-hint">
+        {{ ai.aiMode.value === "chat" ? "基于你勾选的笔记/任务上下文多轮对话。" : "向知识库提问，自动检索相关片段作答。" }}
+      </p>
+
+      <button
+        v-if="ai.aiMode.value === 'chat'"
+        type="button"
+        class="knowledge-ai-context-toggle"
+        @click="contextOpen = !contextOpen"
+      >
+        {{ contextOpen ? "收起上下文" : "上下文选择" }}
+      </button>
+    </header>
+
+    <section v-if="ai.aiMode.value === 'chat' && contextOpen" class="knowledge-ai-context">
+      <div
+        v-if="workspace.currentNotes.value.length === 0 && workspace.currentTasks.value.length === 0"
+        class="knowledge-ai-context-empty"
+      >
+        当前项目暂无笔记/任务。
+      </div>
+      <ul v-else class="knowledge-ai-context-list">
+        <li v-for="note in workspace.currentNotes.value" :key="`n-${note.id}`" class="knowledge-ai-context-row">
+          <span class="knowledge-ai-context-kind knowledge-ai-context-kind--note">笔记</span>
+          <span class="knowledge-ai-context-title">{{ note.title }}</span>
+          <button
+            type="button"
+            class="knowledge-ai-context-level"
+            :class="`is-${levelClassOf(note.id)}`"
+            @click="ai.cycleContextLevel(note.id)"
+          >
+            {{ levelOf(note.id) }}
+          </button>
+        </li>
+        <li v-for="task in workspace.currentTasks.value" :key="`t-${task.id}`" class="knowledge-ai-context-row">
+          <span class="knowledge-ai-context-kind knowledge-ai-context-kind--task">任务</span>
+          <span class="knowledge-ai-context-title">{{ task.title }}</span>
+          <button
+            type="button"
+            class="knowledge-ai-context-level"
+            :class="`is-${levelClassOf(task.id)}`"
+            @click="ai.cycleContextLevel(task.id)"
+          >
+            {{ levelOf(task.id) }}
+          </button>
+        </li>
+      </ul>
+    </section>
+
+    <div class="knowledge-ai-messages">
+      <div v-if="ai.messages.value.length === 0" class="knowledge-ai-empty">
+        <p>向知识助手提问，或就当前项目笔记展开对话。</p>
+      </div>
+
+      <div
+        v-for="message in ai.messages.value"
+        :key="message.id"
+        class="knowledge-ai-message"
+        :class="[`is-${message.role}`, { 'is-error': message.error, 'is-streaming': message.streaming }]"
+      >
+        <div class="knowledge-ai-message-bubble">
+          <template v-if="message.role === 'assistant'">
+            <span v-if="message.streaming && !message.text" class="knowledge-ai-thinking">思考中…</span>
+            <span v-else class="knowledge-ai-message-text">{{ stripCitations(message.text) }}</span>
+          </template>
+          <span v-else class="knowledge-ai-message-text">{{ message.text }}</span>
+        </div>
+
+        <ul v-if="message.sources && message.sources.length > 0" class="knowledge-ai-sources">
+          <li v-for="source in message.sources" :key="`${source.sourceType}-${source.sourceId}`">
+            <button
+              type="button"
+              class="knowledge-ai-source"
+              :disabled="ai.chatLoading.value"
+              @click="ai.openSource(source)"
+            >
+              <span class="knowledge-ai-source-kind" :class="`is-${source.sourceType}`">{{ sourceKindLabel(source) }}</span>
+              <span class="knowledge-ai-source-title">{{ source.title }}</span>
+              <span class="knowledge-ai-source-excerpt">{{ source.excerpt }}</span>
+            </button>
+          </li>
+        </ul>
+      </div>
+    </div>
+
+    <form class="knowledge-ai-input" @submit.prevent="onSend">
+      <input
+        v-model="inputText"
+        type="text"
+        class="knowledge-ai-input-field"
+        placeholder="输入消息，Enter 发送"
+        :disabled="ai.chatLoading.value"
+        @keydown.enter.prevent="onSend"
+      />
+      <button type="submit" class="knowledge-ai-send" :disabled="ai.chatLoading.value || !inputText.trim()">
+        {{ ai.chatLoading.value ? "…" : "发送" }}
+      </button>
+    </form>
+  </div>
+</template>
diff --git a/apps/desktop/src/components/knowledge/ProjectWorkspace.vue b/apps/desktop/src/components/knowledge/ProjectWorkspace.vue
index 14c8115..10133e5 100644
--- a/apps/desktop/src/components/knowledge/ProjectWorkspace.vue
+++ b/apps/desktop/src/components/knowledge/ProjectWorkspace.vue
@@ -1,16 +1,19 @@
 <script setup lang="ts">
 import { computed } from "vue";
 import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+import type { KnowledgeAiState } from "../../composables/useKnowledgeAi";
 import { TAB_LABELS, type KnowledgeViewTab } from "../../composables/useKnowledgeMock";
 import IndexStatusDot from "./IndexStatusDot.vue";
 import KnowledgeNotesPanel from "./KnowledgeNotesPanel.vue";
 import KnowledgeBoardPanel from "./KnowledgeBoardPanel.vue";
 import KnowledgeTasksPanel from "./KnowledgeTasksPanel.vue";
+import KnowledgeAiPanel from "./KnowledgeAiPanel.vue";
 import ProjectBrowser from "./ProjectBrowser.vue";
 import QuickCreateBar from "./QuickCreateBar.vue";
 
 const props = defineProps<{
   workspace: KnowledgeWorkspaceState;
+  ai: KnowledgeAiState;
 }>();
 
 const emit = defineEmits<{
@@ -18,7 +21,7 @@ const emit = defineEmits<{
 }>();
 
 const tabs = computed<KnowledgeViewTab[]>(() => {
-  const base: KnowledgeViewTab[] = ["notes", "board", "tasks"];
+  const base: KnowledgeViewTab[] = ["notes", "board", "tasks", "ai"];
   return props.workspace.hasChildren.value ? [...base, "projects"] : base;
 });
 
@@ -94,6 +97,12 @@ const metaText = computed(() => {
         :workspace="workspace"
       />
 
+      <KnowledgeAiPanel
+        v-else-if="workspace.activeTab.value === 'ai'"
+        :workspace="workspace"
+        :ai="ai"
+      />
+
       <ProjectBrowser
         v-else-if="workspace.activeTab.value === 'projects'"
         :workspace="workspace"
@@ -101,6 +110,6 @@ const metaText = computed(() => {
       />
     </div>
 
-    <QuickCreateBar :workspace="workspace" />
+    <QuickCreateBar v-if="workspace.activeTab.value !== 'ai'" :workspace="workspace" />
   </section>
 </template>
diff --git a/apps/desktop/src/composables/useKnowledgeAi.ts b/apps/desktop/src/composables/useKnowledgeAi.ts
new file mode 100644
index 0000000..5df2888
--- /dev/null
+++ b/apps/desktop/src/composables/useKnowledgeAi.ts
@@ -0,0 +1,228 @@
+import { ref, watch } from "vue";
+import type {
+  AiAnswer,
+  AiRetrievalMode,
+  ContextLevel,
+  KnowledgeSource,
+  WsMessage
+} from "@neo-companion/shared";
+import { api } from "../api";
+import type { KnowledgeWorkspaceState } from "./useKnowledgeWorkspace";
+
+/** UI-side chat message: assistant messages carry optional citable sources. */
+export interface UiChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  sources?: KnowledgeSource[];
+  streaming?: boolean;
+  error?: boolean;
+}
+
+const CONTEXT_CYCLE: ContextLevel[] = ["full", "summary", "excluded"];
+const CONTEXT_LABEL: Record<ContextLevel, string> = {
+  full: "完整",
+  summary: "摘要",
+  excluded: "排除"
+};
+
+function nextId(): string {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `m-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Knowledge-scoped AI chat/ask composable.
+ *
+ * Transport: the request is HTTP POST `api.aiChat` (which resolves with the
+ * final `AiAnswer` once streaming completes); WebSocket `ai:chunk` is used only
+ * for live token display. The HTTP response is the authoritative source of the
+ * final text/sources/conversationId; WS `ai:done`/`ai:error` act as fallbacks
+ * if the HTTP response hasn't resolved. A `finalized` guard prevents the two
+ * channels from double-finalizing the in-flight assistant message.
+ */
+export function useKnowledgeAi(workspace: KnowledgeWorkspaceState) {
+  const aiMode = ref<AiRetrievalMode>("chat");
+  const messages = ref<UiChatMessage[]>([]);
+  const chatLoading = ref(false);
+  const conversationId = ref<string | null>(null);
+  /** key = noteId/taskId → ContextLevel. Defaults rebuilt per project. */
+  const contextSelection = ref<Record<string, ContextLevel>>({});
+  const contextLabel = CONTEXT_LABEL;
+
+  // In-flight state (not reactive-relevant, kept as plain closures).
+  let finalized = false;
+  let pendingAssistantId: string | null = null;
+
+  function rebuildContextDefaults(): void {
+    const next: Record<string, ContextLevel> = {};
+    for (const note of workspace.currentNotes.value) next[note.id] = "full";
+    for (const task of workspace.currentTasks.value) next[task.id] = "full";
+    contextSelection.value = next;
+  }
+
+  function resetThread(): void {
+    messages.value = [];
+    conversationId.value = null;
+    chatLoading.value = false;
+    finalized = false;
+    pendingAssistantId = null;
+  }
+
+  // Project change → reset thread + rebuild context defaults for the new project.
+  watch(
+    () => workspace.currentProjectId.value,
+    () => {
+      resetThread();
+      rebuildContextDefaults();
+    }
+  );
+
+  // Mode switch → reset thread (Ask is one-shot; Chat restarts). Context kept.
+  watch(aiMode, () => {
+    resetThread();
+  });
+
+  function cycleContextLevel(id: string): void {
+    const current = contextSelection.value[id] ?? "full";
+    const idx = CONTEXT_CYCLE.indexOf(current);
+    const nextLevel = CONTEXT_CYCLE[(idx + 1) % CONTEXT_CYCLE.length];
+    contextSelection.value = { ...contextSelection.value, [id]: nextLevel };
+  }
+
+  /** Build the ChatContextSelection for the current project (excludes 'excluded'). */
+  function buildContext(): { notes: Record<string, ContextLevel>; tasks: Record<string, ContextLevel> } {
+    const notes: Record<string, ContextLevel> = {};
+    const tasks: Record<string, ContextLevel> = {};
+    const noteIds = new Set(workspace.currentNotes.value.map((n) => n.id));
+    const taskIds = new Set(workspace.currentTasks.value.map((t) => t.id));
+    for (const [id, level] of Object.entries(contextSelection.value)) {
+      if (level === "excluded") continue;
+      if (noteIds.has(id)) notes[id] = level;
+      else if (taskIds.has(id)) tasks[id] = level;
+    }
+    return { notes, tasks };
+  }
+
+  function finalizeAssistant(id: string, answer: AiAnswer): void {
+    const idx = messages.value.findIndex((m) => m.id === id);
+    if (idx === -1) return;
+    const updated = { ...messages.value[idx], text: answer.text, sources: answer.sources, streaming: false, error: false };
+    messages.value = [...messages.value.slice(0, idx), updated, ...messages.value.slice(idx + 1)];
+    if (answer.conversationId) conversationId.value = answer.conversationId;
+  }
+
+  function finalizeError(id: string, message: string): void {
+    const idx = messages.value.findIndex((m) => m.id === id);
+    if (idx === -1) return;
+    const updated = { ...messages.value[idx], text: message, streaming: false, error: true };
+    messages.value = [...messages.value.slice(0, idx), updated, ...messages.value.slice(idx + 1)];
+  }
+
+  function appendToStreaming(chunk: string): void {
+    if (!pendingAssistantId) return;
+    const idx = messages.value.findIndex((m) => m.id === pendingAssistantId);
+    if (idx === -1) return;
+    const prev = messages.value[idx];
+    const updated = { ...prev, text: prev.text + chunk };
+    messages.value = [...messages.value.slice(0, idx), updated, ...messages.value.slice(idx + 1)];
+  }
+
+  function handleWsMessage(message: WsMessage): void {
+    if (message.type === "ai:chunk") {
+      const payload = message.payload as { chunk: string };
+      appendToStreaming(payload.chunk);
+      return;
+    }
+    if (message.type === "ai:done" && !finalized && pendingAssistantId) {
+      finalized = true;
+      chatLoading.value = false;
+      finalizeAssistant(pendingAssistantId, message.payload as AiAnswer);
+      pendingAssistantId = null;
+      return;
+    }
+    if (message.type === "ai:error" && !finalized && pendingAssistantId) {
+      finalized = true;
+      chatLoading.value = false;
+      const payload = message.payload as { message?: string };
+      finalizeError(pendingAssistantId, payload.message ?? "AI 请求失败");
+      pendingAssistantId = null;
+    }
+  }
+
+  async function send(text: string): Promise<void> {
+    const trimmed = text.trim();
+    if (!trimmed || chatLoading.value) return;
+
+    const projectId = workspace.currentProjectId.value;
+    const userMsg: UiChatMessage = { id: nextId(), role: "user", text: trimmed };
+    const assistantId = nextId();
+    const assistantMsg: UiChatMessage = { id: assistantId, role: "assistant", text: "", streaming: true };
+    messages.value = [...messages.value, userMsg, assistantMsg];
+
+    chatLoading.value = true;
+    finalized = false;
+    pendingAssistantId = assistantId;
+
+    const req: Parameters<typeof api.aiChat>[0] = { message: trimmed, mode: aiMode.value, projectId };
+    if (aiMode.value === "chat") {
+      req.context = buildContext();
+      if (conversationId.value) req.conversationId = conversationId.value;
+    }
+
+    try {
+      const answer = await api.aiChat(req);
+      if (!finalized) {
+        finalized = true;
+        chatLoading.value = false;
+        finalizeAssistant(assistantId, answer);
+        pendingAssistantId = null;
+      }
+    } catch (error) {
+      if (!finalized) {
+        finalized = true;
+        chatLoading.value = false;
+        const msg = error instanceof Error ? error.message : "AI 请求失败";
+        finalizeError(assistantId, msg);
+        pendingAssistantId = null;
+      }
+    }
+  }
+
+  /** Navigate to a cited source, cross-project if needed. */
+  function openSource(source: KnowledgeSource): void {
+    if (chatLoading.value) return;
+    if (source.projectId && source.projectId !== workspace.currentProjectId.value) {
+      workspace.enterProject(source.projectId);
+    }
+    if (source.sourceType === "note") {
+      workspace.selectTab("notes");
+      workspace.selectNote(source.sourceId);
+    } else {
+      workspace.selectTab("tasks");
+      workspace.selectTask(source.sourceId);
+    }
+  }
+
+  return {
+    aiMode,
+    messages,
+    chatLoading,
+    conversationId,
+    contextSelection,
+    contextLabel,
+    send,
+    resetThread,
+    cycleContextLevel,
+    handleWsMessage,
+    openSource
+  };
+}
+
+export type KnowledgeAiState = ReturnType<typeof useKnowledgeAi>;
+
+/** Helper for templates: strip [sN] citation markers from assistant text. */
+export function stripCitations(text: string): string {
+  return text.replace(/\[s\d+\]/g, "").trim();
+}
diff --git a/apps/desktop/src/composables/useKnowledgeApi.ts b/apps/desktop/src/composables/useKnowledgeApi.ts
index 405238b..dbef51b 100644
--- a/apps/desktop/src/composables/useKnowledgeApi.ts
+++ b/apps/desktop/src/composables/useKnowledgeApi.ts
@@ -47,6 +47,10 @@ export interface KnowledgeDataSource {
   moveTask: (taskId: string, targetColumnId: string, targetIndex: number) => void;
   resolveLink: (label: string) => { type: "note" | "task"; id: string } | null;
   backlinksFor: (id: string) => KnowledgeLink[];
+  /** Reason vector retrieval is unavailable, when known (null = healthy/env). */
+  vecDegradedReason?: Ref<string | null>;
+  /** Refresh index status from the sidecar (API data source only). */
+  loadIndexStatus?(): Promise<void>;
 }
 
 /**
@@ -138,6 +142,7 @@ export function useKnowledgeApi(): KnowledgeDataSource {
   const tasksRef = ref<KnowledgeTask[]>([]);
   const columnsRef = ref<BoardColumn[]>([]);
   const indexStatus = ref<IndexStatus>("ok");
+  const vecDegradedReason = ref<string | null>(null);
   const ready = ref(false);
   const lastError = ref<string | null>(null);
 
@@ -165,6 +170,8 @@ export function useKnowledgeApi(): KnowledgeDataSource {
       columnsRef.value = columnsByProject;
       tasksRef.value = tasksByProject;
 
+      void loadIndexStatus();
+
       ready.value = true;
       lastError.value = null;
     } catch (error) {
@@ -174,6 +181,27 @@ export function useKnowledgeApi(): KnowledgeDataSource {
     }
   }
 
+  /** Pull the rich index status from the sidecar and map it to the UI state +
+   *  surface why vector retrieval is unavailable (so silent degradation is visible). */
+  async function loadIndexStatus(): Promise<void> {
+    try {
+      const status = await api.knowledgeIndexStatus();
+      indexStatus.value =
+        status.mode === "hybrid" ? "ok" : status.mode === "indexing" ? "indexing" : "fts_only";
+      if (status.mode === "fts-only") {
+        vecDegradedReason.value = status.vecLoadError
+          ? `向量扩展加载失败：${status.vecLoadError}`
+          : !status.providerConfigured
+            ? "未配置 embedding provider，仅全文检索可用"
+            : null;
+      } else {
+        vecDegradedReason.value = null;
+      }
+    } catch {
+      // Index status is best-effort; never block loadAll on it.
+    }
+  }
+
   function childProjects(projectId: string): KnowledgeProject[] {
     return childrenByParentId.value.get(projectId) ?? [];
   }
@@ -203,9 +231,12 @@ export function useKnowledgeApi(): KnowledgeDataSource {
   // ── optimistic write helpers ──
   function surfaceError(error: unknown, fallback: string): void {
     lastError.value = error instanceof Error ? error.message : fallback;
-    // auto-clear after a few seconds so the banner isn't sticky
-    window.setTimeout(() => {
-      if (lastError.value === (error instanceof Error ? error.message : fallback)) lastError.value = null;
+    // auto-clear after a few seconds so the banner isn't sticky.
+    // Use the global setTimeout (not window.setTimeout) so test cleanup that
+    // tears down window before the timer fires doesn't throw ReferenceError.
+    const msg = error instanceof Error ? error.message : fallback;
+    setTimeout(() => {
+      if (lastError.value === msg) lastError.value = null;
     }, 5000);
   }
 
@@ -364,6 +395,7 @@ export function useKnowledgeApi(): KnowledgeDataSource {
 
   return {
     loadAll,
+    loadIndexStatus,
     lastError,
     ready,
     projects,
@@ -371,6 +403,7 @@ export function useKnowledgeApi(): KnowledgeDataSource {
     tasks: tasksRef,
     columns: columnsRef,
     indexStatus,
+    vecDegradedReason,
     projectById,
     childrenByParentId,
     childProjects,
diff --git a/apps/desktop/src/composables/useKnowledgeMock.ts b/apps/desktop/src/composables/useKnowledgeMock.ts
index c55196c..076c3b5 100644
--- a/apps/desktop/src/composables/useKnowledgeMock.ts
+++ b/apps/desktop/src/composables/useKnowledgeMock.ts
@@ -6,7 +6,7 @@ import { computed, ref } from "vue";
  * 仍是纯前端 mock，不连 sidecar/WS，但数据模型与 docs/ARCHITECTURE.md 对齐。
  */
 
-export type KnowledgeViewTab = "notes" | "board" | "tasks" | "projects";
+export type KnowledgeViewTab = "notes" | "board" | "tasks" | "projects" | "ai";
 export type IndexStatus = "ok" | "fts_only" | "indexing";
 export type TaskStatus = "todo" | "doing" | "done" | "archived";
 
@@ -601,6 +601,7 @@ export const TAB_LABELS: Record<KnowledgeViewTab, string> = {
   board: "看板",
   tasks: "任务",
   projects: "子项目",
+  ai: "AI",
 };
 
 export const INDEX_STATUS_LABELS: Record<IndexStatus, string> = {
diff --git a/apps/desktop/src/composables/useKnowledgeWorkspace.ts b/apps/desktop/src/composables/useKnowledgeWorkspace.ts
index ac307c6..433b208 100644
--- a/apps/desktop/src/composables/useKnowledgeWorkspace.ts
+++ b/apps/desktop/src/composables/useKnowledgeWorkspace.ts
@@ -261,6 +261,7 @@ export function useKnowledgeWorkspace() {
     allNotes: computed(() => data.value.notes.value),
     allTasks: computed(() => data.value.tasks.value),
     indexStatus: computed(() => data.value.indexStatus.value),
+    vecDegradedReason: computed(() => data.value.vecDegradedReason?.value ?? null),
     formatKwTime,
   };
 }
diff --git a/apps/desktop/src/styles/knowledge.css b/apps/desktop/src/styles/knowledge.css
index 8f8b417..36b05b5 100644
--- a/apps/desktop/src/styles/knowledge.css
+++ b/apps/desktop/src/styles/knowledge.css
@@ -1276,3 +1276,340 @@
     grid-template-columns: 1fr;
   }
 }
+
+/* ── AI 对话面板（Phase 4.5） ── */
+.knowledge-ai-panel {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  gap: var(--kw-space, 12px);
+}
+
+.knowledge-ai-header {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--kw-border);
+}
+
+.knowledge-ai-modes {
+  align-self: flex-start;
+}
+
+.knowledge-ai-hint {
+  margin: 0;
+  font-size: 0.72rem;
+  color: var(--kw-text-muted);
+}
+
+.knowledge-ai-context-toggle {
+  background: none;
+  border: 1px solid var(--kw-border);
+  color: var(--kw-text-muted);
+  padding: 3px 10px;
+  border-radius: 999px;
+  font-size: 0.72rem;
+  cursor: pointer;
+}
+
+.knowledge-ai-context-toggle:hover {
+  color: var(--kw-text);
+  border-color: var(--kw-accent);
+}
+
+.knowledge-ai-context {
+  max-height: 220px;
+  overflow-y: auto;
+  padding: 8px 4px;
+  border-bottom: 1px solid var(--kw-border);
+}
+
+.knowledge-ai-context-empty {
+  font-size: 0.75rem;
+  color: var(--kw-text-muted);
+  padding: 6px 0;
+}
+
+.knowledge-ai-context-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.knowledge-ai-context-row {
+  display: grid;
+  grid-template-columns: 40px 1fr auto;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 6px;
+  border-radius: var(--kw-radius-s, 8px);
+}
+
+.knowledge-ai-context-row:hover {
+  background: var(--kw-surface-hover);
+}
+
+.knowledge-ai-context-kind {
+  font-size: 0.66rem;
+  padding: 2px 6px;
+  border-radius: 999px;
+  text-align: center;
+}
+
+.knowledge-ai-context-kind--note {
+  background: var(--kw-accent-soft);
+  color: var(--kw-accent-text);
+}
+
+.knowledge-ai-context-kind--task {
+  background: var(--kw-surface-alt);
+  color: var(--kw-text-muted);
+}
+
+.knowledge-ai-context-title {
+  font-size: 0.8rem;
+  color: var(--kw-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.knowledge-ai-context-level {
+  background: none;
+  border: 1px solid var(--kw-border);
+  color: var(--kw-text-muted);
+  padding: 2px 10px;
+  border-radius: 999px;
+  font-size: 0.7rem;
+  cursor: pointer;
+}
+
+.knowledge-ai-context-level.is-full {
+  border-color: var(--kw-accent);
+  color: var(--kw-accent-text);
+}
+
+.knowledge-ai-context-level.is-summary {
+  border-color: var(--kw-accent);
+  color: var(--kw-text-muted);
+}
+
+.knowledge-ai-context-level.is-excluded {
+  border-color: var(--kw-border);
+  color: var(--kw-text-muted);
+  opacity: 0.6;
+  text-decoration: line-through;
+}
+
+.knowledge-ai-messages {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 4px;
+}
+
+.knowledge-ai-empty {
+  margin: auto;
+  color: var(--kw-text-muted);
+  font-size: 0.85rem;
+  text-align: center;
+}
+
+.knowledge-ai-message {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  max-width: 88%;
+}
+
+.knowledge-ai-message.is-user {
+  align-self: flex-end;
+  align-items: flex-end;
+}
+
+.knowledge-ai-message.is-assistant {
+  align-self: flex-start;
+  align-items: flex-start;
+}
+
+.knowledge-ai-message-bubble {
+  padding: 9px 13px;
+  border-radius: var(--kw-radius-m, 14px);
+  font-size: 0.85rem;
+  line-height: 1.55;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+.is-user .knowledge-ai-message-bubble {
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+  border-bottom-right-radius: 4px;
+}
+
+.is-assistant .knowledge-ai-message-bubble {
+  background: var(--kw-surface-alt);
+  color: var(--kw-text);
+  border-bottom-left-radius: 4px;
+}
+
+.knowledge-ai-message.is-error .knowledge-ai-message-bubble {
+  background: rgba(192, 80, 80, 0.16);
+  color: #d98a8a;
+}
+
+.knowledge-ai-thinking {
+  color: var(--kw-text-muted);
+  font-style: italic;
+}
+
+.knowledge-ai-message.is-streaming .knowledge-ai-message-text::after {
+  content: "▍";
+  animation: kw-ai-cursor 1s steps(2) infinite;
+  color: var(--kw-accent);
+}
+
+@keyframes kw-ai-cursor {
+  50% { opacity: 0; }
+}
+
+.knowledge-ai-sources {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  width: 100%;
+}
+
+.knowledge-ai-source {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  width: 100%;
+  text-align: left;
+  background: var(--kw-surface);
+  border: 1px solid var(--kw-border);
+  border-radius: var(--kw-radius-s, 8px);
+  padding: 6px 10px;
+  cursor: pointer;
+  transition: border-color 0.15s ease, background 0.15s ease;
+}
+
+.knowledge-ai-source:hover:not(:disabled) {
+  border-color: var(--kw-accent);
+  background: var(--kw-surface-hover);
+}
+
+.knowledge-ai-source:disabled {
+  cursor: default;
+  opacity: 0.7;
+}
+
+.knowledge-ai-source-kind {
+  flex: 0 0 auto;
+  font-size: 0.66rem;
+  padding: 1px 6px;
+  border-radius: 999px;
+  background: var(--kw-accent-soft);
+  color: var(--kw-accent-text);
+}
+
+.knowledge-ai-source-kind.is-task {
+  background: var(--kw-surface-alt);
+  color: var(--kw-text-muted);
+}
+
+.knowledge-ai-source-title {
+  flex: 0 0 auto;
+  font-size: 0.78rem;
+  font-weight: 500;
+  color: var(--kw-text);
+}
+
+.knowledge-ai-source-excerpt {
+  flex: 1 1 auto;
+  font-size: 0.72rem;
+  color: var(--kw-text-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.knowledge-ai-input {
+  display: flex;
+  gap: 8px;
+  padding: 8px 0 2px;
+  border-top: 1px solid var(--kw-border);
+}
+
+.knowledge-ai-input-field {
+  flex: 1;
+  background: var(--kw-surface);
+  border: 1px solid var(--kw-border);
+  border-radius: var(--kw-radius-m, 14px);
+  padding: 8px 14px;
+  font-size: 0.85rem;
+  color: var(--kw-text);
+  outline: none;
+}
+
+.knowledge-ai-input-field:focus {
+  border-color: var(--kw-accent);
+}
+
+.knowledge-ai-input-field:disabled {
+  opacity: 0.6;
+}
+
+.knowledge-ai-send {
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+  border: none;
+  border-radius: var(--kw-radius-m, 14px);
+  padding: 8px 18px;
+  font-size: 0.8rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: filter 0.15s ease;
+}
+
+.knowledge-ai-send:hover:not(:disabled) {
+  filter: brightness(1.08);
+}
+
+.knowledge-ai-send:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+/* ── status banners (KnowledgeView) ── */
+.knowledge-banner {
+  margin: 0 0 12px;
+  padding: 8px 12px;
+  border-radius: 6px;
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.knowledge-banner--warn {
+  background: rgba(245, 158, 11, 0.14);
+  border: 1px solid rgba(245, 158, 11, 0.4);
+  color: #b45309;
+}
+
+.knowledge-banner--info {
+  background: rgba(59, 130, 246, 0.12);
+  border: 1px solid rgba(59, 130, 246, 0.35);
+  color: #1d4ed8;
+}
diff --git a/apps/desktop/src/views/KnowledgeView.vue b/apps/desktop/src/views/KnowledgeView.vue
index a8b2c9b..455d9a7 100644
--- a/apps/desktop/src/views/KnowledgeView.vue
+++ b/apps/desktop/src/views/KnowledgeView.vue
@@ -1,7 +1,9 @@
 <script setup lang="ts">
-import { onMounted } from "vue";
+import { onMounted, onUnmounted } from "vue";
 import { useKnowledgeWorkspace } from "../composables/useKnowledgeWorkspace";
+import { useKnowledgeAi } from "../composables/useKnowledgeAi";
 import { useTheme } from "../composables/useTheme";
+import { connectWs } from "../api";
 import ProjectBrowser from "../components/knowledge/ProjectBrowser.vue";
 import ProjectWorkspace from "../components/knowledge/ProjectWorkspace.vue";
 import BreadcrumbNav from "../components/knowledge/BreadcrumbNav.vue";
@@ -9,9 +11,19 @@ import ThemeToggle from "../components/knowledge/ThemeToggle.vue";
 
 const workspace = useKnowledgeWorkspace();
 const theme = useTheme();
+const ai = useKnowledgeAi(workspace);
+
+let disconnectWs: (() => void) | null = null;
 
 onMounted(() => {
   void workspace.loadAll();
+  // Knowledge view is its own window; connect WS for ai:chunk streaming.
+  disconnectWs = connectWs(ai.handleWsMessage);
+});
+
+onUnmounted(() => {
+  disconnectWs?.();
+  disconnectWs = null;
 });
 </script>
 
@@ -41,6 +53,10 @@ onMounted(() => {
       {{ workspace.loadError.value ?? "后端未就绪，当前为本地预览数据。" }}
     </div>
 
+    <div v-if="workspace.vecDegradedReason.value" class="knowledge-banner knowledge-banner--info">
+      {{ workspace.vecDegradedReason.value }}
+    </div>
+
     <ProjectBrowser
       v-if="!workspace.currentProjectId.value"
       :workspace="workspace"
@@ -50,6 +66,7 @@ onMounted(() => {
     <ProjectWorkspace
       v-else
       :workspace="workspace"
+      :ai="ai"
       @exit="workspace.exitToParent"
     />
   </div>
diff --git a/docs/API.md b/docs/API.md
index 1891d32..6483071 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -147,18 +147,36 @@ NeoCompanion sidecar 是一个本地 Fastify 应用，为 Vue 前端提供 REST
 
 ```json
 {
-  "message": "接下来该做什么？"
+  "message": "向量检索怎么工作？",
+  "mode": "ask",
+  "projectId": "<可选，限定检索范围>",
+  "context": "可选，Chat 模式下手选条目与三级权限",
+  "conversationId": "可选，Chat 模式多轮续接"
 }
 ```
 
+`mode` 取值：
+
+- `ask` — RAG 自动检索（`searchHybrid`）相关分块作答，单次问答。
+- `chat` — 基于用户手选上下文（`context`）多轮对话，支持 `conversationId` 续接。
+
+`context`（Chat 模式）为数组，每项含条目 id、`contextLevel: "full" | "summary" | "excluded"`。
+
 **响应：**
 
 ```json
 {
-  "text": "要不要先查看未完成任务？"
+  "text": "知识库使用 sqlite-vec 做向量检索……",
+  "sources": [
+    { "sourceType": "note", "sourceId": "...", "projectId": "...", "title": "...", "excerpt": "...", "chunkId": "..." }
+  ],
+  "retrievalMode": "ask",
+  "conversationId": "可选，用于续接"
 }
 ```
 
+`sources` 由服务端根据实际召回/引用审计结果生成（模型输出无权新增，编造的引用 ID 会被剔除）。
+
 **请求过程中会广播以下 WebSocket 事件：**
 
 - `companion:feedback`，状态为 `thinking`
@@ -371,6 +389,6 @@ sidecar 会广播以下消息类型：
 
 ## 说明
 
-- 知识工作空间相关的搜索端点（`/api/knowledge/*`）**尚未实现**。当前知识工作空间 UI 由前端 mock 驱动，但已具备可交互的卡片化项目浏览器、嵌套导航、笔记/看板/任务工作区、双向链接与 backlinks、看板拖拽排序和全局主题切换，用于验证 UX。
-- 当前 `/api/tasks` 使用 `status: "open" | "done"`。v2 知识工作空间将任务状态扩展为 `"todo" | "doing" | "done" | "archived"`，并与看板列绑定；迁移时需将旧任务映射到新状态与列。
+- 知识工作空间后端端点（`/api/knowledge/*`）**已实现**：项目/笔记/看板列/任务的 CRUD、`GET /api/knowledge/search`（FTS5 + sqlite-vec 混合检索，参数 `q`/`projectId`/`limit`）、`GET /api/knowledge/index-status`、`POST /api/knowledge/reindex`、`GET/PUT /api/knowledge/embedding-config`（apiKey 不回显，落库持久化）、`GET/PUT /api/knowledge/root-path`、`POST /api/knowledge/mirror/export|import`。前端通过 `useKnowledgeApi` 接入，API 不可用时降级 mock 并显示 banner。详见 `docs/ARCHITECTURE.md` §9.3、§9.4。
+- 当前 v1 `/api/tasks` 使用 `status: "open" | "done"`。v2 知识工作空间用独立表 `knowledge_tasks`（四态 `"todo" | "doing" | "done" | "archived"`），与看板列绑定；两表统一为延后决策。
 - 错误响应格式通常为 `{ "error": "message" }`，除非另有说明。
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e1c5dc8..28ff1f3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -35,9 +35,9 @@
 
 本文档同时描述 **已实现** 与 **规划中** 的技术设计。已实现的内容指当前代码中真实存在并运行的模块；规划中的内容标注为 `(Planned)` 或 `(Partial)`，例如：
 
-- **已实现**：Tauri 多窗口管理、Fastify Sidecar TCP 模式、SQLite + Drizzle ORM、任务/专注/天气/AI/TTS/窗口/Hook 等核心端点、WebSocket 实时推送、GitHub Actions CI/CD。
-- **部分实现 (Partial)**：v3.3 知识工作空间 UI 交互层已交付（卡片化项目浏览器、嵌套项目导航、笔记/看板/任务工作区、按项目自定义看板列、HTML5 拖拽排序、双向 wiki 链接与 backlinks、全局 light/dark 主题），但仍为前端 mock 数据，后端 SQLite 存储、FTS5 / `sqlite-vec` 检索与相关 API 尚未接入。
-- **规划中 (Planned)**：FTS5 全文索引、`sqlite-vec` 向量检索与混合排序、零端口 UDS Socket 模式 B、文件监听 Hook、MQTT 接入、屏幕上下文感知与本地长期记忆模块。
+- **已实现**：Tauri 多窗口管理、Fastify Sidecar TCP 模式、SQLite + Drizzle ORM、任务/专注/天气/AI/TTS/窗口/Hook 等核心端点、WebSocket 实时推送、GitHub Actions CI/CD。知识工作空间 v2（Phase 0–4）：文件型存储方向、后端 SQLite CRUD + 混合文件镜像、FTS5 全文检索（trigram，支持 CJK）、`sqlite-vec` 向量检索 + RRF 融合、Embedding Adapter（OpenAI 兼容，落库持久化 + 环境变量双通道）、AI Chat/Ask 双模式 + 三级上下文权限 + 引用审计反幻觉 + 多轮会话持久化。
+- **部分实现 (Partial)**：v1 `tasks(open|done)` 与 v2 `knowledge_tasks`（四态）的状态枚举统一尚未执行（延后决策，见 TODO_INVENTORY）。
+- **规划中 (Planned)**：零端口 UDS Socket 模式 B、文件监听 Hook、MQTT 接入、屏幕上下文感知与本地长期记忆模块。
 
 阅读时请注意段落中的状态标注，避免将规划内容误认为已交付功能。
 
@@ -1240,7 +1240,56 @@ export interface EmbeddingAdapter {
 
 当向量不可用时，`IndexStatus.mode` 为 `fts-only`，服务端继续用全文候选回答并在 UI 显示降级状态；不得静默退化为不使用知识库的普通聊天。
 
-### 9.4 Data Location
+`IndexStatus` 三态：`hybrid`（vec 加载且 provider 配置、无 pending/stale）、`indexing`（hybrid 可行但有 pending/stale 分块待嵌入）、`fts-only`（vec 未加载或 provider 未配置）。新增 `vecVersion`（sqlite-vec 版本）与 `vecLoadError`（加载失败原因），供前端在静默降级时向用户显示原因（"向量扩展加载失败：…" 或 "未配置 embedding provider，仅全文检索可用"）。
+
+### 9.4 AI Chat/Ask 双模式与引用审计
+
+移植自 [open-notebook](https://github.com/lfnovo/open-notebook) 的双模式 RAG 设计，由 `packages/server-local/src/modules/ai/` 实现：
+
+#### 9.4.1 双模式
+
+- **Chat 模式**：基于用户**手选**的笔记/任务上下文多轮对话。上下文来源是用户在 AI 面板勾选的条目（非检索），整篇或按权限裁剪后送 LLM，支持 `conversationId` 续接历史。
+- **Ask 模式**：向知识库提问，**自动检索**（`searchHybrid`）相关分块作答。单次问答，命中 chunk 送 LLM，一次性返回。
+
+两者共用同一套上下文打包与引用审计管线，差异仅在上下文来源（手选 vs 检索）。
+
+#### 9.4.2 三级上下文权限
+
+Chat 模式下每条笔记/任务可设 `full`（整篇正文）/ `summary`（首段摘要）/ `excluded`（排除）。`excluded` 条目不进入请求载荷。`context.ts` 按以下权重构建上下文块：
+
+| 块类型 | 权重 |
+|--------|------|
+| noteFull | 100 |
+| askChunk（检索命中） | 90 |
+| noteSummary | 70 |
+| task | 55 |
+| history（对话历史） | 40 |
+
+#### 9.4.3 上下文打包策略
+
+`packContext()` 在 6000 token 预算内：
+
+1. **greedy fill**：高权重块优先入，超预算整块丢弃。
+2. **gap fill**：剩余预算在**句子边界**截断补齐次权重块。
+3. **sandwich ordering**：最相关块置最前、次相关置最后（利用 LLM 对首尾注意力最强），同源块保留文档序。
+
+#### 9.4.4 引用注入与反幻觉审计
+
+`citation.ts`：
+
+1. `injectSources()`：每块注入为带稳定 ID 的可引用单元（`<source id="s0" …>`），系统 prompt 要求模型只引用已提供 ID、不发明新 ID、冲突并列引用。
+2. `parseAndAuditCitations()`：解析模型输出，**剔除模型编造的 ID**（反幻觉）。
+3. `buildSources()`：只返回实际被引用的 source，由服务端检索结果生成（非模型自报）→ 前端可点击跳转。
+
+#### 9.4.5 多轮会话持久化
+
+`ai_conversations`（会话，含 mode）与 `ai_messages`（消息，含 `sources_json`）表持久化对话。`AiAnswer.conversationId` 透传给前端，Ask 模式单轮、Chat 模式多轮续接。
+
+#### 9.4.6 Embedding 配置持久化
+
+Embedding provider 配置（provider/baseUrl/model/apiKey）持久化到 `app_config` 表，sidecar 重启不丢失。apiKey 双通道：PUT 传 `apiKey` 则明文落库（仅存本地 db 文件，不进 git，GET 不回显）；传 `apiKey:null` 则清空落库值、运行时回退环境变量 `EMBEDDING_API_KEY`。GET 端点返回 `apiKeySource: "stored" | "env" | "none"` 供前端提示。
+
+### 9.5 Data Location
 
 ```
 用户数据目录 (Tauri app data):
@@ -1254,7 +1303,7 @@ export interface EmbeddingAdapter {
 
 数据目录由 Tauri 的 `app_data_dir()` 管理，跨平台统一。
 
-### 9.5 Migration Strategy
+### 9.6 Migration Strategy
 
 使用 Drizzle Kit 管理数据库迁移：
 
@@ -1272,7 +1321,7 @@ pnpm --filter db drizzle-kit migrate   # 执行迁移
 3. 创建 notes、tags、knowledge_chunks、FTS5 与 sqlite-vec 结构；旧任务随后进入增量索引队列。
 4. sqlite-vec 加载失败不得回滚业务表迁移；记录 `fts-only` 能力状态并继续启动。
 
-### 9.6 SQLite 并发并发安全与高频事件防抖写入 (SQLite Concurrency & Debounced Writes)
+### 9.7 SQLite 并发并发安全与高频事件防抖写入 (SQLite Concurrency & Debounced Writes)
 
 由于屏幕感知引擎与窗口检测模块会高频产生用户活动状态 Ticks（如窗口切换、空闲检测、打字活跃状态），如果每次微小变化都直接进行一次 SQLite 数据库写事务，将带来极高的磁盘 I/O 压力并诱发 `SQLITE_BUSY: database is locked` 并发锁定冲突。为此，系统强制应用以下并发优化：
 
diff --git a/docs/TODO_INVENTORY.md b/docs/TODO_INVENTORY.md
index deba1fe..c25ae84 100644
--- a/docs/TODO_INVENTORY.md
+++ b/docs/TODO_INVENTORY.md
@@ -38,23 +38,24 @@
 
 ## 知识工作空间
 
-- **文件**：`apps/desktop/src/composables/useKnowledgeMock.ts`
-- **已交付（v3.3 UI）**：
+- **文件**：`apps/desktop/src/composables/useKnowledgeMock.ts`（现仅作开发/降级数据源）、`packages/server-local/src/modules/knowledge/`（后端）、`packages/db/src/index.ts`（存储）
+- **已交付（v3.3 UI + v2 后端 Phase 0–4）**：
   - 卡片化项目浏览器与嵌套项目导航。
-  - 项目工作区（笔记 / 看板 / 任务 / 子项目 tab）。
+  - 项目工作区（笔记 / 看板 / 任务 / 子项目 / AI tab）。
   - 按项目自定义看板列与原生 HTML5 拖拽排序。
   - 双向 wiki 链接 `[[目标]]` / `[[目标|显示文本]]` 与 backlinks 面板。
   - 底部快速创建条与全局 light/dark 主题切换。
-- **仍为 mock（v2 接入）**：
-  - 真正的后端端点（`/api/notes`、`/api/boards`、`/api/tasks`、`/api/knowledge/*`）。
-  - SQLite 持久化存储、FTS5 全文检索和 `sqlite-vec` 向量检索。
-- **另见**：`docs/ARCHITECTURE.md` §1.2 Document Scope
+  - 后端 SQLite CRUD + 混合文件镜像（Obsidian 友好 Markdown/JSONL）。
+  - FTS5 全文检索（trigram，支持 CJK）、`sqlite-vec` 向量检索 + RRF 融合。
+  - Embedding Adapter（OpenAI 兼容，配置落库 + 环境变量双通道）。
+  - AI Chat/Ask 双模式 + 三级上下文权限 + 引用审计反幻觉 + 多轮会话持久化。
+  - 前端通过 `useKnowledgeApi` 接入真实 API，API 不可用时自动降级 mock 并显示 banner。
+- **另见**：`docs/ARCHITECTURE.md` §1.2 Document Scope、§9.3 向量与混合检索、§9.4 AI Chat/Ask 双模式与引用审计。
 
 ### 数据模型与迁移待对齐项
 
-- **项目/看板字段名**：`docs/ARCHITECTURE.md` §9.2 原 schema 使用 `projects.name` / `boards.name`，但 v3.3 前端 mock 与 UI 已统一使用 `title`。v2 后端实现时需以 `title` 为准，并在首次迁移中处理。
-- **任务状态枚举**：现有 `tasks.status` 为 `'open' | 'done'`，v3.3 看板工作流为 `'todo' | 'doing' | 'done' | 'archived'`。v2 迁移需将旧任务状态映射到看板列与新枚举。
-- **看板列默认值**：v3.3 中各项目可拥有不同的看板列（如“待办/进行中/已完成/归档”或“待调研/已整理”）。v2 首次迁移需为项目创建默认列，并支持自定义列持久化。
+- **任务状态枚举（延后决策）**：现有 v1 `tasks.status` 为 `'open' | 'done'`（驱动 pet 面板/focus），v2 `knowledge_tasks` 为四态 `'todo' | 'doing' | 'done' | 'archived'`。统一枚举是行为变更，暂延后；knowledge 用独立表 `knowledge_tasks`。
+- **看板列默认值**：v2 首次迁移需为项目创建默认列，并支持自定义列持久化。
 
 ## 如何更新本清单
 
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 29defc6..0c2116c 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -242,18 +242,38 @@ export function initSchema(sqlite: Database.Database) {
       sources_json TEXT,
       created_at TEXT NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS app_config (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
   `);
 }
 
-/** Load the sqlite-vec extension into a connection. Never throws; returns loaded state. */
-export function loadVecExtension(database: NeoDatabase): { loaded: boolean; version?: string } {
-  if (database.kind !== "sqlite") return { loaded: false };
+/** Read a single app_config value (JSON string), or null when absent. */
+export function getAppConfig(database: NeoDatabase, key: string): string | null {
+  if (database.kind !== "sqlite") return null;
+  const row = database.sqlite.prepare("SELECT value FROM app_config WHERE key = ?").get(key) as { value?: string } | undefined;
+  return row?.value ?? null;
+}
+
+/** Write (upsert) a single app_config value. No-op on the memory fallback. */
+export function setAppConfig(database: NeoDatabase, key: string, value: string): void {
+  if (database.kind !== "sqlite") return;
+  database.sqlite
+    .prepare("INSERT INTO app_config (key, value, updated_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at")
+    .run(key, value, new Date().toISOString());
+}
+
+/** Load the sqlite-vec extension into a connection. Never throws; returns loaded state + error reason. */
+export function loadVecExtension(database: NeoDatabase): { loaded: boolean; version?: string; error?: string } {
+  if (database.kind !== "sqlite") return { loaded: false, error: "memory database (no native sqlite)" };
   try {
     sqliteVec.load(database.sqlite);
     const row = database.sqlite.prepare("SELECT vec_version() AS v").get() as { v?: string } | undefined;
     return { loaded: true, version: row?.v };
-  } catch {
-    return { loaded: false };
+  } catch (e) {
+    return { loaded: false, error: e instanceof Error ? e.message : String(e) };
   }
 }
 
@@ -551,6 +571,8 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   const { db, sqlite } = database;
   const vecState = loadVecExtension(database);
   let vecLoaded = vecState.loaded;
+  const vecVersion = vecState.version;
+  const vecLoadError = vecState.error;
   let vecDim: number | null = null;
 
   // ── tags helpers ──
@@ -1022,7 +1044,9 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
       failed: countBy("failed"),
       stale,
       providerConfigured,
-      vectorExtensionAvailable: vecLoaded
+      vectorExtensionAvailable: vecLoaded,
+      vecVersion,
+      vecLoadError: vecLoaded ? undefined : vecLoadError
     };
   }
 
diff --git a/packages/server-local/src/app.ts b/packages/server-local/src/app.ts
index 987c2c7..a30ca78 100644
--- a/packages/server-local/src/app.ts
+++ b/packages/server-local/src/app.ts
@@ -2,7 +2,7 @@ import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
 import Fastify, { type FastifyInstance } from "fastify";
 import { streamDeepSeekChat, embedContents } from "@neo-companion/ai";
-import { createAiConversationStore, createDatabase, createKnowledgeStore, createTaskStore, createWindowEventStore, type AiConversationStore, type KnowledgeStore, type NeoDatabase } from "@neo-companion/db";
+import { createAiConversationStore, createDatabase, createKnowledgeStore, createTaskStore, createWindowEventStore, getAppConfig, setAppConfig, type AiConversationStore, type KnowledgeStore, type NeoDatabase } from "@neo-companion/db";
 import type { ChatMessage, CompanionFeedback, TtsResult } from "@neo-companion/shared";
 import { speakWithMimo } from "@neo-companion/tts";
 import { createFocusManager } from "./services/focus-manager";
@@ -32,13 +32,28 @@ export async function createApp(dependencies: AppDependencies = {}) {
   // fallback is reachable (better-sqlite3 native binding unavailable). Routes
   // degrade to 503 in that case.
   const knowledgeStore: KnowledgeStore | null = database.kind === "sqlite" ? createKnowledgeStore(database) : null;
-  // Embedding provider config held in memory (pushed from the client via the
-  // /embedding-config route, like root-path). Survives for the process lifetime.
-  let embeddingConfig: EmbeddingConfig = { provider: "none" };
+  // Embedding provider config persisted to the app_config table so it survives
+  // sidecar restarts (apiKey lives only in the local db file, never in git).
+  // Falls back to an in-memory variable on the memory database.
+  const EMBEDDING_CONFIG_KEY = "embedding";
+  const parseConfig = (raw: string | null): EmbeddingConfig => {
+    if (!raw) return { provider: "none" };
+    try {
+      const parsed = JSON.parse(raw) as EmbeddingConfig;
+      return parsed && typeof parsed === "object" ? parsed : { provider: "none" };
+    } catch {
+      return { provider: "none" };
+    }
+  };
+  let embeddingConfig: EmbeddingConfig =
+    database.kind === "sqlite" ? parseConfig(getAppConfig(database, EMBEDDING_CONFIG_KEY)) : { provider: "none" };
   const embeddingConfigController = {
     get: () => embeddingConfig,
     set: (next: EmbeddingConfig) => {
       embeddingConfig = next;
+      if (database.kind === "sqlite") {
+        setAppConfig(database, EMBEDDING_CONFIG_KEY, JSON.stringify(next));
+      }
     }
   };
   const knowledgeService: KnowledgeService | null = knowledgeStore
diff --git a/packages/server-local/src/modules/ai/service.ts b/packages/server-local/src/modules/ai/service.ts
index 5817666..4963869 100644
--- a/packages/server-local/src/modules/ai/service.ts
+++ b/packages/server-local/src/modules/ai/service.ts
@@ -150,7 +150,7 @@ export function createAiService(deps: AiServiceDeps) {
       conversationStore.appendMessage(conversationId, "assistant", audited.cleanedText, sources);
     }
 
-    const answer: AiAnswer = { text: audited.cleanedText, sources, retrievalMode: "chat" };
+    const answer: AiAnswer = { text: audited.cleanedText, sources, retrievalMode: "chat", conversationId };
     hub.broadcast({ type: "ai:done", payload: answer });
     return answer;
   }
@@ -189,13 +189,15 @@ export function createAiService(deps: AiServiceDeps) {
     const finalSources = buildSources(injected, audited.citedIds, sourceLookup);
 
     // Ask is one-shot; persist a single-turn conversation for history.
+    let askConversationId: string | undefined;
     if (conversationStore && req.projectId) {
       const conv = conversationStore.createConversation(req.projectId, "ask");
+      askConversationId = conv.id;
       conversationStore.appendMessage(conv.id, "user", req.message);
       conversationStore.appendMessage(conv.id, "assistant", audited.cleanedText, finalSources);
     }
 
-    const answer: AiAnswer = { text: audited.cleanedText, sources: finalSources, retrievalMode: "ask" };
+    const answer: AiAnswer = { text: audited.cleanedText, sources: finalSources, retrievalMode: "ask", conversationId: askConversationId };
     hub.broadcast({ type: "ai:done", payload: answer });
     return answer;
   }
diff --git a/packages/server-local/src/modules/knowledge/routes.ts b/packages/server-local/src/modules/knowledge/routes.ts
index 6999aa9..2c73b8d 100644
--- a/packages/server-local/src/modules/knowledge/routes.ts
+++ b/packages/server-local/src/modules/knowledge/routes.ts
@@ -263,15 +263,19 @@ export function registerKnowledgeRoutes(
   });
 
   // ── Embedding provider config (Phase 3) ──
-  // Server holds the config in memory (pushed from the client, like root-path);
-  // apiKey is never echoed back.
+  // Persisted to app_config (survives restart); apiKey lives only in the local
+  // db file and is never echoed back. apiKey is optional — when absent the
+  // service falls back to the EMBEDDING_API_KEY env var.
   app.get("/api/knowledge/embedding-config", async () => {
     const cfg = embeddingConfigController?.get() ?? { provider: "none" };
+    const hasStoredKey = !!cfg.apiKey;
+    const hasEnvKey = !!process.env.EMBEDDING_API_KEY;
     return {
       provider: cfg.provider,
       baseUrl: cfg.baseUrl ?? "",
       model: cfg.model ?? "",
-      configured: !!cfg.apiKey && cfg.provider !== "none"
+      configured: cfg.provider !== "none" && !!cfg.model && (hasStoredKey || hasEnvKey),
+      apiKeySource: hasStoredKey ? "stored" : hasEnvKey ? "env" : "none"
     };
   });
 
@@ -279,8 +283,17 @@ export function registerKnowledgeRoutes(
     if (!embeddingConfigController) return reply.code(503).send({ error: "embedding config unavailable" });
     const body = request.body as Partial<EmbeddingConfig>;
     const current = embeddingConfigController.get();
-    // empty apiKey on PUT means "keep existing" (UI masks the secret)
-    const apiKey = body.apiKey ? body.apiKey : current.apiKey;
+    // A non-empty apiKey overwrites the stored secret; an absent/empty apiKey
+    // keeps the existing stored key (UI masks the secret). To switch to env-var
+    // mode the client sends an explicit apiKey: null which clears the stored key.
+    let apiKey: string | undefined;
+    if (body.apiKey) {
+      apiKey = body.apiKey;
+    } else if (body.apiKey === null) {
+      apiKey = undefined; // clear stored key → fall back to env var
+    } else {
+      apiKey = current.apiKey;
+    }
     const next: EmbeddingConfig = {
       provider: body.provider ?? current.provider,
       baseUrl: body.baseUrl ?? current.baseUrl,
diff --git a/packages/server-local/src/modules/knowledge/service.ts b/packages/server-local/src/modules/knowledge/service.ts
index c255dfd..8ad8e79 100644
--- a/packages/server-local/src/modules/knowledge/service.ts
+++ b/packages/server-local/src/modules/knowledge/service.ts
@@ -47,13 +47,18 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
   function embeddingConfig(): EmbeddingConfig | null {
     return getEmbeddingConfig?.() ?? null;
   }
+  /** Resolved API key: stored config value, else env EMBEDDING_API_KEY. */
+  function resolvedApiKey(): string | undefined {
+    const cfg = embeddingConfig();
+    return cfg?.apiKey || process.env.EMBEDDING_API_KEY || undefined;
+  }
   function providerConfigured(): boolean {
     const cfg = embeddingConfig();
-    return !!cfg && cfg.provider !== "none" && !!cfg.apiKey && !!cfg.model;
+    return !!cfg && cfg.provider !== "none" && !!cfg.model && !!resolvedApiKey();
   }
   function embedCallOptions(): EmbeddingCallOptions {
     const cfg = embeddingConfig() ?? { provider: "none" };
-    return { apiKey: cfg.apiKey, baseUrl: cfg.baseUrl, model: cfg.model };
+    return { apiKey: resolvedApiKey(), baseUrl: cfg.baseUrl, model: cfg.model };
   }
 
   let draining = false;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index e1413c1..ff3c5e5 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -228,6 +228,10 @@ export interface IndexStatus {
   stale: number;
   providerConfigured: boolean;
   vectorExtensionAvailable: boolean;
+  /** sqlite-vec version when loaded; absent when not loaded. */
+  vecVersion?: string;
+  /** Reason sqlite-vec failed to load, so the UI can surface silent degradation. */
+  vecLoadError?: string;
 }
 
 /** Simplified UI state consumed by IndexStatusDot. */
@@ -244,6 +248,8 @@ export interface AiAnswer {
   text: string;
   sources: KnowledgeSource[];
   retrievalMode: AiRetrievalMode;
+  /** Chat 模式下回传的会话 id，供前端续传多轮；降级/Ask-未续传时为 undefined。 */
+  conversationId?: string;
 }
 
 /** AI 多轮会话（Phase 4，与 v1 pet 对话表分离）。 */

From 94b795998bf98aa911d140230e852a89e3a14e00 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sun, 21 Jun 2026 20:53:36 +0800
Subject: [PATCH 5/6] fix(knowledge): harden local retrieval pipeline

---
 apps/desktop/src-tauri/Cargo.lock             |  17 +
 apps/desktop/src-tauri/Cargo.toml             |   1 +
 apps/desktop/src-tauri/src/lib.rs             |  40 ++
 apps/desktop/src/api.ts                       |  77 +++-
 .../settings/sections/KnowledgeSection.vue    |  29 +-
 apps/desktop/src/composables/useSettings.ts   |  77 +++-
 apps/desktop/src/main.ts                      |   4 +
 apps/desktop/src/styles/settings.css          |  13 +
 apps/desktop/vitest.config.ts                 |   3 +
 package.json                                  |   4 +-
 packages/db/src/db.test.ts                    |  62 ++-
 packages/db/src/index.ts                      | 376 +++++++++++++-----
 packages/db/src/schema.ts                     |   8 +-
 packages/server-local/src/app.ts              |  85 +++-
 .../src/modules/ai/context.test.ts            |   7 +-
 .../server-local/src/modules/ai/service.ts    |  14 +-
 .../src/modules/knowledge/mirror.test.ts      |  13 +-
 .../src/modules/knowledge/mirror.ts           |  76 ++--
 .../src/modules/knowledge/routes.ts           |  39 +-
 .../src/modules/knowledge/service.ts          |  23 +-
 packages/server-local/src/tests/app.test.ts   |  29 +-
 packages/server-local/src/tests/auth.test.ts  |  45 +++
 packages/server-local/src/tests/hook.test.ts  |  10 +-
 packages/shared/src/index.ts                  |   2 +
 scripts/dev.mjs                               |  26 ++
 25 files changed, 869 insertions(+), 211 deletions(-)
 create mode 100644 packages/server-local/src/tests/auth.test.ts
 create mode 100644 scripts/dev.mjs

diff --git a/apps/desktop/src-tauri/Cargo.lock b/apps/desktop/src-tauri/Cargo.lock
index a919440..87a45a5 100644
--- a/apps/desktop/src-tauri/Cargo.lock
+++ b/apps/desktop/src-tauri/Cargo.lock
@@ -1861,6 +1861,16 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "keyring"
+version = "3.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
+dependencies = [
+ "log",
+ "zeroize",
+]
+
 [[package]]
 name = "leb128fmt"
 version = "0.1.0"
@@ -2054,6 +2064,7 @@ dependencies = [
 name = "neo-companion"
 version = "0.1.0"
 dependencies = [
+ "keyring",
  "serde",
  "serde_json",
  "tauri",
@@ -5171,6 +5182,12 @@ dependencies = [
  "synstructure",
 ]
 
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
 [[package]]
 name = "zerotrie"
 version = "0.2.4"
diff --git a/apps/desktop/src-tauri/Cargo.toml b/apps/desktop/src-tauri/Cargo.toml
index d54f36d..2f29656 100644
--- a/apps/desktop/src-tauri/Cargo.toml
+++ b/apps/desktop/src-tauri/Cargo.toml
@@ -19,6 +19,7 @@ tauri-plugin-dialog = "2"
 tauri-plugin-window-state = "2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+keyring = "3"
 
 [target.'cfg(target_os = "windows")'.dependencies]
 tauri-plugin-wallpaper = "3.0.0"
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 482f326..233bbe8 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -2,6 +2,40 @@ use tauri::menu::{Menu, MenuItem};
 use tauri::tray::{TrayIconBuilder, TrayIconEvent};
 use tauri::{LogicalSize, Manager, Size, WindowEvent};
 
+#[tauri::command]
+fn get_app_auth_token() -> Result<String, String> {
+    std::env::var("APP_AUTH_TOKEN").map_err(|_| "APP_AUTH_TOKEN is required".to_string())
+}
+
+const KEYRING_SERVICE: &str = "com.neocompanion.desktop";
+const EMBEDDING_KEY_ACCOUNT: &str = "embedding-api-key";
+
+fn embedding_key_entry() -> Result<keyring::Entry, String> {
+    keyring::Entry::new(KEYRING_SERVICE, EMBEDDING_KEY_ACCOUNT).map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+fn set_embedding_api_key(api_key: String) -> Result<(), String> {
+    embedding_key_entry()?.set_password(&api_key).map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+fn get_embedding_api_key() -> Result<Option<String>, String> {
+    match embedding_key_entry()?.get_password() {
+        Ok(value) => Ok(Some(value)),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(error) => Err(error.to_string()),
+    }
+}
+
+#[tauri::command]
+fn delete_embedding_api_key() -> Result<(), String> {
+    match embedding_key_entry()?.delete_credential() {
+        Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+        Err(error) => Err(error.to_string()),
+    }
+}
+
 pub fn run() {
     let builder = tauri::Builder::default()
         .plugin(tauri_plugin_opener::init())
@@ -12,6 +46,12 @@ pub fn run() {
     let builder = builder.plugin(tauri_plugin_wallpaper::init());
 
     builder
+        .invoke_handler(tauri::generate_handler![
+            get_app_auth_token,
+            set_embedding_api_key,
+            get_embedding_api_key,
+            delete_embedding_api_key
+        ])
         .setup(|app| {
             let show = MenuItem::with_id(app, "show", "显示", true, None::<&str>)?;
             let quit = MenuItem::with_id(app, "quit", "退出", true, None::<&str>)?;
diff --git a/apps/desktop/src/api.ts b/apps/desktop/src/api.ts
index 4bafe46..a46648f 100644
--- a/apps/desktop/src/api.ts
+++ b/apps/desktop/src/api.ts
@@ -12,18 +12,22 @@ import type {
   WsMessage
 } from "@neo-companion/shared";
 import type { BoardColumn, KnowledgeNote, KnowledgeProject, KnowledgeTask, TaskStatus } from "./composables/useKnowledgeMock";
+import { invoke } from "@tauri-apps/api/core";
 
 export interface EmbeddingConfigInput {
-  provider: string;
+  provider?: string;
   baseUrl?: string;
-  apiKey?: string;
+  apiKey?: string | null;
   model?: string;
+  apiKeySource?: "keychain" | "env" | "legacy" | "none";
 }
 export interface EmbeddingConfigStatus {
   provider: string;
   baseUrl: string;
   model: string;
   configured: boolean;
+  apiKeySource: "keychain" | "env" | "legacy" | "none";
+  legacyMigrationRequired: boolean;
 }
 export interface AiChatRequest {
   message: string;
@@ -37,10 +41,12 @@ export const API_BASE = import.meta.env.VITE_NEO_SERVER_URL ?? "http://127.0.0.1
 export const WS_BASE = API_BASE.replace(/^http/, "ws");
 
 async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const token = await getAuthToken();
   const response = await fetch(`${API_BASE}${path}`, {
     ...options,
     headers: {
       "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
       ...options?.headers
     }
   });
@@ -50,9 +56,25 @@ async function request<T>(path: string, options?: RequestInit): Promise<T> {
     throw new Error(body.error ?? response.statusText);
   }
 
+  if (response.status === 204) return undefined as T;
+
   return response.json() as Promise<T>;
 }
 
+let authTokenPromise: Promise<string> | null = null;
+function getAuthToken(): Promise<string> {
+  if (!authTokenPromise) {
+    const envToken = import.meta.env.VITE_NEO_AUTH_TOKEN as string | undefined;
+    const isTauri = typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+    authTokenPromise = isTauri
+      ? invoke<string>("get_app_auth_token")
+      : envToken
+        ? Promise.resolve(envToken)
+        : Promise.reject(new Error("VITE_NEO_AUTH_TOKEN is required"));
+  }
+  return authTokenPromise;
+}
+
 export const api = {
   health: () => request<{ ok: boolean }>("/health"),
   listTasks: () => request<Task[]>("/api/tasks"),
@@ -115,7 +137,7 @@ export const api = {
   knowledgeMirrorExport: (path?: string) =>
     request<{ projects: number; notes: number; columns: number; tasks: number }>("/api/knowledge/mirror/export", { method: "POST", body: JSON.stringify({ path }) }),
   knowledgeMirrorImport: (path?: string) =>
-    request<{ importedProjects: number; importedNotes: number; importedColumns: number; importedTasks: number; skipped: number }>("/api/knowledge/mirror/import", { method: "POST", body: JSON.stringify({ path }) }),
+    request<{ importedProjects: number; importedNotes: number; importedColumns: number; importedTasks: number; skipped: number; reindexedNotes: number; reindexedTasks: number; errors: string[] }>("/api/knowledge/mirror/import", { method: "POST", body: JSON.stringify({ path }) }),
 
   // ── Knowledge retrieval + embedding config (Phase 3) ──
   knowledgeSearch: (query: string, projectId?: string | null, limit = 20) =>
@@ -126,25 +148,54 @@ export const api = {
   knowledgeGetEmbeddingConfig: () =>
     request<EmbeddingConfigStatus>("/api/knowledge/embedding-config"),
   knowledgeSetEmbeddingConfig: (config: EmbeddingConfigInput) =>
-    request<{ ok: boolean }>("/api/knowledge/embedding-config", { method: "PUT", body: JSON.stringify(config) })
+    request<{ ok: boolean }>("/api/knowledge/embedding-config", { method: "PUT", body: JSON.stringify(config) }),
+  knowledgeClaimLegacyEmbeddingSecret: () =>
+    request<{ apiKey: string }>("/api/knowledge/embedding-config/legacy-secret/claim", { method: "POST" }),
+  knowledgeClearLegacyEmbeddingSecret: () =>
+    request<void>("/api/knowledge/embedding-config/legacy-secret", { method: "DELETE" })
 };
 
+/** Hydrate the sidecar's in-memory embedding secret from the OS keychain. */
+export async function bootstrapEmbeddingSecret(): Promise<void> {
+  const isTauri = typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+  if (!isTauri) return;
+  const status = await api.knowledgeGetEmbeddingConfig();
+  if (status.legacyMigrationRequired) {
+    const legacy = await api.knowledgeClaimLegacyEmbeddingSecret();
+    await invoke("set_embedding_api_key", { apiKey: legacy.apiKey });
+    await api.knowledgeSetEmbeddingConfig({ apiKey: legacy.apiKey, apiKeySource: "keychain" });
+    await api.knowledgeClearLegacyEmbeddingSecret();
+    return;
+  }
+  const stored = await invoke<string | null>("get_embedding_api_key");
+  if (stored) await api.knowledgeSetEmbeddingConfig({ apiKey: stored, apiKeySource: "keychain" });
+}
+
 let activeWs: WebSocket | null = null;
 
 export function connectWs(onMessage: (message: WsMessage) => void) {
-  const ws = new WebSocket(`${WS_BASE}/ws`);
-  activeWs = ws;
-  ws.addEventListener("message", (event) => {
-    onMessage(JSON.parse(event.data) as WsMessage);
+  let ws: WebSocket | null = null;
+  let heartbeat: number | null = null;
+  let cancelled = false;
+  void getAuthToken().then((token) => {
+    if (cancelled) return;
+    ws = new WebSocket(`${WS_BASE}/ws`, ["neo-companion", `auth.${token}`]);
+    activeWs = ws;
+    ws.addEventListener("message", (event) => {
+      onMessage(JSON.parse(event.data) as WsMessage);
+    });
+    heartbeat = window.setInterval(() => {
+      if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" }));
+    }, 30000);
+  }).catch((error: unknown) => {
+    onMessage({ type: "ai:error", payload: { message: error instanceof Error ? error.message : "authentication failed" } });
   });
-  const heartbeat = window.setInterval(() => {
-    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" }));
-  }, 30000);
 
   return () => {
-    window.clearInterval(heartbeat);
+    cancelled = true;
+    if (heartbeat !== null) window.clearInterval(heartbeat);
     activeWs = null;
-    ws.close();
+    ws?.close();
   };
 }
 
diff --git a/apps/desktop/src/components/settings/sections/KnowledgeSection.vue b/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
index 3892709..bd2368c 100644
--- a/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
+++ b/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
@@ -35,6 +35,7 @@ const rootPathDisplay = computed(() => props.state.knowledgeRootPath.value || "
 
 onMounted(() => {
   void props.state.loadEmbeddingConfig();
+  void props.state.loadKnowledgeRootPath();
 });
 
 async function pickRootFolder(): Promise<void> {
@@ -43,7 +44,7 @@ async function pickRootFolder(): Promise<void> {
   try {
     const selected = await open({ directory: true, multiple: false });
     if (typeof selected === "string" && selected) {
-      props.state.setKnowledgeRootPath(selected);
+      await props.state.setKnowledgeRootPath(selected);
     }
   } finally {
     picking.value = false;
@@ -79,7 +80,7 @@ async function saveEmbeddingConfig(): Promise<void> {
 
       <SettingRow
         label="知识库根目录"
-        hint="笔记与索引数据的存放根目录（阶段 0 仅记录路径，文件化存储将在 v2 接入）"
+        hint="Markdown 文件镜像的根目录；SQLite 仍是业务数据与索引的主存储"
       >
         <template #action>
           <div class="knowledge-root-action">
@@ -102,6 +103,28 @@ async function saveEmbeddingConfig(): Promise<void> {
         </template>
       </SettingRow>
 
+      <SettingRow label="文件镜像" hint="SQLite 为主存储；手动导入或导出 Markdown 镜像，不同步文件删除">
+        <template #action>
+          <div class="knowledge-root-action">
+            <button type="button" class="btn-ghost" :disabled="state.knowledgeMirrorBusy.value || !state.knowledgeRootPath.value" @click="state.importKnowledgeMirror">
+              导入
+            </button>
+            <button type="button" class="btn-ghost" :disabled="state.knowledgeMirrorBusy.value || !state.knowledgeRootPath.value" @click="state.exportKnowledgeMirror">
+              导出
+            </button>
+          </div>
+        </template>
+      </SettingRow>
+
+      <p
+        v-if="state.knowledgeMirrorMessage.value"
+        class="knowledge-mirror-status"
+        :class="{ 'is-error': state.knowledgeMirrorError.value }"
+        role="status"
+      >
+        {{ state.knowledgeMirrorMessage.value }}
+      </p>
+
       <SettingRow label="Embedding Provider" hint="未配置时 AI 检索退化为仅 FTS5 全文搜索；笔记与看板始终可用">
         <template #action>
           <SelectField v-model="state.embeddingProvider.value" :options="providerOptions" />
@@ -120,7 +143,7 @@ async function saveEmbeddingConfig(): Promise<void> {
         </template>
       </SettingRow>
 
-      <SettingRow label="Embedding API Key" hint="推送至本地服务端后从内存清除；不落盘">
+      <SettingRow label="Embedding API Key" hint="由系统钥匙链保存；Sidecar 仅在进程内存中使用">
         <template #action>
           <TextField
             v-model="state.embeddingApiKey.value"
diff --git a/apps/desktop/src/composables/useSettings.ts b/apps/desktop/src/composables/useSettings.ts
index 05bb06c..3eb6d75 100644
--- a/apps/desktop/src/composables/useSettings.ts
+++ b/apps/desktop/src/composables/useSettings.ts
@@ -1,5 +1,6 @@
 import { ref } from "vue";
-import { api } from "../api";
+import { api, bootstrapEmbeddingSecret } from "../api";
+import { invoke } from "@tauri-apps/api/core";
 
 /**
  * Settings composable — 阶段 1 仅维护本地状态，所有改动留在内存里。
@@ -30,8 +31,6 @@ export type CommandFrequency = string;
 export type EmbeddingProvider = "none" | "openai" | "cohere" | "local";
 export type SearchScope = "current" | "all";
 
-const KNOWLEDGE_ROOT_PATH_KEY = "neo:knowledgeRootPath";
-
 export function useSettings() {
   const activeSection = ref<SettingsSection>("general");
 
@@ -84,22 +83,26 @@ export function useSettings() {
   // apiKey 仅存内存 + 推送服务端，不落 localStorage（敏感）
   const embeddingApiKey = ref("");
   const embeddingConfigured = ref(false);
+  const embeddingApiKeySource = ref<"keychain" | "env" | "legacy" | "none">("none");
   const searchScope = ref<SearchScope>("current");
   const chunkSize = ref("1200");
   const indexAutoRebuild = ref(true);
   // 知识库根目录：阶段 0 仅记录路径并持久化到 localStorage，数据仍为 mock；
   // v2 文件化存储接入后由 sidecar 读取此路径作为笔记/索引落盘根目录。
-  const knowledgeRootPath = ref<string>(
-    typeof localStorage !== "undefined" ? localStorage.getItem(KNOWLEDGE_ROOT_PATH_KEY) ?? "" : "",
-  );
+  const knowledgeRootPath = ref("");
+  const knowledgeMirrorBusy = ref(false);
+  const knowledgeMirrorMessage = ref("");
+  const knowledgeMirrorError = ref(false);
 
   async function loadEmbeddingConfig(): Promise<void> {
     try {
+      await bootstrapEmbeddingSecret();
       const status = await api.knowledgeGetEmbeddingConfig();
       embeddingProvider.value = (status.provider as EmbeddingProvider) || "none";
       embeddingBaseUrl.value = status.baseUrl;
       embeddingModel.value = status.model;
       embeddingConfigured.value = status.configured;
+      embeddingApiKeySource.value = status.apiKeySource;
     } catch {
       // sidecar 不可用时静默降级
     }
@@ -109,12 +112,24 @@ export function useSettings() {
     if (typeof localStorage !== "undefined") {
       localStorage.setItem("neo.embeddingBaseUrl", embeddingBaseUrl.value);
     }
+    const isTauri = typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+    if (isTauri && embeddingProvider.value === "none") {
+      await invoke("delete_embedding_api_key");
+    } else if (isTauri && embeddingApiKey.value) {
+      await invoke("set_embedding_api_key", { apiKey: embeddingApiKey.value });
+    }
     await api.knowledgeSetEmbeddingConfig({
       provider: embeddingProvider.value,
       baseUrl: embeddingBaseUrl.value || undefined,
-      apiKey: embeddingApiKey.value || undefined,
-      model: embeddingModel.value || undefined
+      apiKey: embeddingProvider.value === "none" ? null : (embeddingApiKey.value || undefined),
+      model: embeddingModel.value || undefined,
+      apiKeySource: embeddingProvider.value === "none"
+        ? "none"
+        : isTauri && (embeddingApiKey.value || embeddingApiKeySource.value === "keychain") ? "keychain" : undefined
     });
+    if (embeddingApiKeySource.value === "legacy") {
+      await api.knowledgeClearLegacyEmbeddingSecret();
+    }
     embeddingApiKey.value = ""; // 清空内存中的明文 key
     await loadEmbeddingConfig();
   }
@@ -123,11 +138,42 @@ export function useSettings() {
     await api.knowledgeReindex(embeddingModel.value || undefined);
   }
 
-  function setKnowledgeRootPath(path: string): void {
+  async function loadKnowledgeRootPath(): Promise<void> {
+    const result = await api.knowledgeGetRootPath();
+    knowledgeRootPath.value = result.path;
+  }
+
+  async function setKnowledgeRootPath(path: string): Promise<void> {
     const trimmed = path.trim();
-    knowledgeRootPath.value = trimmed;
-    if (typeof localStorage !== "undefined") {
-      localStorage.setItem(KNOWLEDGE_ROOT_PATH_KEY, trimmed);
+    const result = await api.knowledgeSetRootPath(trimmed);
+    knowledgeRootPath.value = result.path;
+  }
+
+  async function exportKnowledgeMirror(): Promise<void> {
+    knowledgeMirrorBusy.value = true;
+    knowledgeMirrorError.value = false;
+    try {
+      const result = await api.knowledgeMirrorExport();
+      knowledgeMirrorMessage.value = `已导出 ${result.projects} 个项目、${result.notes} 篇笔记、${result.tasks} 个任务`;
+    } catch (error) {
+      knowledgeMirrorError.value = true;
+      knowledgeMirrorMessage.value = error instanceof Error ? error.message : "导出失败";
+    } finally {
+      knowledgeMirrorBusy.value = false;
+    }
+  }
+
+  async function importKnowledgeMirror(): Promise<void> {
+    knowledgeMirrorBusy.value = true;
+    knowledgeMirrorError.value = false;
+    try {
+      const result = await api.knowledgeMirrorImport();
+      knowledgeMirrorMessage.value = `已导入 ${result.importedProjects} 个项目、${result.importedNotes} 篇笔记；重建 ${result.reindexedNotes} 篇笔记索引`;
+    } catch (error) {
+      knowledgeMirrorError.value = true;
+      knowledgeMirrorMessage.value = error instanceof Error ? error.message : "导入失败";
+    } finally {
+      knowledgeMirrorBusy.value = false;
     }
   }
 
@@ -189,10 +235,14 @@ export function useSettings() {
     embeddingBaseUrl,
     embeddingApiKey,
     embeddingConfigured,
+    embeddingApiKeySource,
     searchScope,
     chunkSize,
     indexAutoRebuild,
     knowledgeRootPath,
+    knowledgeMirrorBusy,
+    knowledgeMirrorMessage,
+    knowledgeMirrorError,
     // actions
     setSection,
     selectModel,
@@ -201,6 +251,9 @@ export function useSettings() {
     addBlacklistItem,
     reindexAll,
     setKnowledgeRootPath,
+    loadKnowledgeRootPath,
+    exportKnowledgeMirror,
+    importKnowledgeMirror,
     loadEmbeddingConfig,
     saveEmbeddingConfig,
   };
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 2454bca..c17f385 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -10,5 +10,9 @@ import "./styles/wallpaper.css";
 import "./styles/settings.css";
 import "./styles/knowledge.css";
 import "./styles/markdown.css";
+import { bootstrapEmbeddingSecret } from "./api";
 
 createApp(App).mount("#app");
+void bootstrapEmbeddingSecret().catch(() => {
+  // The settings view retries and surfaces credential/bootstrap errors.
+});
diff --git a/apps/desktop/src/styles/settings.css b/apps/desktop/src/styles/settings.css
index 3545fc6..62f12c4 100644
--- a/apps/desktop/src/styles/settings.css
+++ b/apps/desktop/src/styles/settings.css
@@ -459,6 +459,19 @@
   cursor: default;
 }
 
+.knowledge-mirror-status {
+  margin: -4px 0 10px;
+  color: var(--text-muted);
+  font-size: 12px;
+  line-height: 1.5;
+  text-align: right;
+  text-wrap: pretty;
+}
+
+.knowledge-mirror-status.is-error {
+  color: var(--danger);
+}
+
 .settings-root .toggle {
   width: 44px;
   height: 26px;
diff --git a/apps/desktop/vitest.config.ts b/apps/desktop/vitest.config.ts
index 2ebb5f6..38b3251 100644
--- a/apps/desktop/vitest.config.ts
+++ b/apps/desktop/vitest.config.ts
@@ -5,6 +5,9 @@ import { defineConfig } from "vitest/config";
 // dev/build pipelines stay lean and only tests load jsdom.
 export default defineConfig({
   plugins: [vue()],
+  define: {
+    "import.meta.env.VITE_NEO_AUTH_TOKEN": JSON.stringify("test-token"),
+  },
   test: {
     environment: "jsdom",
     setupFiles: ["./tests/setup.ts"],
diff --git a/package.json b/package.json
index cbcc3dc..a2759d7 100644
--- a/package.json
+++ b/package.json
@@ -5,8 +5,8 @@
   "type": "module",
   "packageManager": "pnpm@10.32.0",
   "scripts": {
-    "dev": "concurrently -n server,desktop -c green,cyan \"pnpm --filter @neo-companion/server-local dev\" \"pnpm --filter @neo-companion/desktop dev:web\"",
-    "dev:tauri": "concurrently -n server,tauri -c green,cyan \"pnpm --filter @neo-companion/server-local dev\" \"pnpm --filter @neo-companion/desktop dev:tauri\"",
+    "dev": "node scripts/dev.mjs web",
+    "dev:tauri": "node scripts/dev.mjs tauri",
     "build": "pnpm -r build",
     "typecheck": "pnpm -r typecheck",
     "test": "pnpm -r test",
diff --git a/packages/db/src/db.test.ts b/packages/db/src/db.test.ts
index 673f50b..c148398 100644
--- a/packages/db/src/db.test.ts
+++ b/packages/db/src/db.test.ts
@@ -113,7 +113,7 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
     const pending = kw.listPendingChunks(10);
     expect(pending.length).toBeGreaterThanOrEqual(1);
     const chunk = pending[0];
-    kw.putVecChunk(chunk.id, [0.1, 0.2, 0.3, 0.4]);
+    kw.putVecChunk(chunk.id, chunk.projectId, [0.1, 0.2, 0.3, 0.4]);
     kw.markChunkIndexed(chunk.id, "test-embed", dim);
 
     const hits = kw.searchKnn([0.1, 0.2, 0.3, 0.4], 5, null);
@@ -137,7 +137,7 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
 
     const pending = kw.listPendingChunks(20);
     for (const c of pending) {
-      kw.putVecChunk(c.id, [0.5, 0.5]);
+      kw.putVecChunk(c.id, c.projectId, [0.5, 0.5]);
       kw.markChunkIndexed(c.id, "test-embed", 2);
     }
 
@@ -151,7 +151,7 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
     const kw = createKnowledgeStore(database);
     const vec = [0.1, 0.2, 0.3];
     kw.putCachedEmbedding("hash-1", vec, "test-embed", 3);
-    const got = kw.getCachedEmbedding("hash-1");
+    const got = kw.getCachedEmbedding("hash-1", "test-embed");
     expect(got).not.toBeNull();
     expect(got!.dimensions).toBe(3);
     // Float32 round-trip introduces tiny error; compare approximately.
@@ -159,7 +159,61 @@ describe.skipIf(!SQLITE_AVAILABLE)("knowledge vector index", () => {
     expect(got!.vector[0]).toBeCloseTo(0.1, 5);
     expect(got!.vector[1]).toBeCloseTo(0.2, 5);
     expect(got!.vector[2]).toBeCloseTo(0.3, 5);
-    expect(kw.getCachedEmbedding("missing")).toBeNull();
+    expect(kw.getCachedEmbedding("missing", "test-embed")).toBeNull();
+    database.close();
+  });
+
+  it("restores vector table dimensions when the store is recreated", () => {
+    const database = createDatabase(":memory:");
+    const first = createKnowledgeStore(database);
+    first.ensureVecTable(2);
+    const project = first.createProject({ title: "P" });
+    const note = first.createNote(project.id, "restart vector content");
+    first.reindexNote(note, simpleChunk);
+    const chunk = first.listPendingChunks(1)[0];
+    first.putVecChunk(chunk.id, project.id, [0.2, 0.8]);
+    first.markChunkIndexed(chunk.id, "model", 2);
+    const reopened = createKnowledgeStore(database);
+    expect(reopened.searchKnn([0.2, 0.8], 5, project.id)[0].sourceId).toBe(note.id);
+    database.close();
+  });
+
+  it("keeps embedding caches isolated by model", () => {
+    const database = createDatabase(":memory:");
+    const kw = createKnowledgeStore(database);
+    kw.putCachedEmbedding("same-content", [1, 0], "model-a", 2);
+    expect(kw.getCachedEmbedding("same-content", "model-a")).not.toBeNull();
+    expect(kw.getCachedEmbedding("same-content", "model-b")).toBeNull();
+    database.close();
+  });
+
+  it("marks vectors from a different model stale", () => {
+    const database = createDatabase(":memory:");
+    if (database.kind !== "sqlite") throw new Error("sqlite required");
+    const kw = createKnowledgeStore(database);
+    const project = kw.createProject({ title: "P" });
+    const note = kw.createNote(project.id, "model migration content");
+    kw.reindexNote(note, simpleChunk);
+    const chunk = kw.listPendingChunks(1)[0];
+    kw.markChunkIndexed(chunk.id, "model-a", 2);
+    kw.markStale("model-b");
+    expect((database.sqlite.prepare("SELECT index_status FROM knowledge_chunks WHERE id = ?").get(chunk.id) as { index_status: string }).index_status).toBe("stale");
+    database.close();
+  });
+
+  it("returns real chunk ids and removes all index rows on delete", () => {
+    const database = createDatabase(":memory:");
+    if (database.kind !== "sqlite") throw new Error("sqlite required");
+    const kw = createKnowledgeStore(database);
+    const project = kw.createProject({ title: "P" });
+    const note = kw.updateNote(kw.createNote(project.id, "Delete me").id, { body: "unique deletion sentinel" })!;
+    kw.reindexNote(note, simpleChunk);
+    const actual = database.sqlite.prepare("SELECT id FROM knowledge_chunks WHERE source_id = ?").get(note.id) as { id: string };
+    const hit = kw.searchFts(project.id, "deletion sentinel", 5)[0];
+    expect(hit.chunkId).toBe(actual.id);
+    kw.deleteNote(note.id);
+    expect(kw.searchFts(project.id, "deletion sentinel", 5)).toEqual([]);
+    expect(database.sqlite.prepare("SELECT COUNT(*) AS n FROM knowledge_chunks_fts WHERE source_id = ?").get(note.id)).toEqual({ n: 0 });
     database.close();
   });
 });
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 0c2116c..8e27e4a 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -1,7 +1,7 @@
 import Database from "better-sqlite3";
 import * as sqliteVec from "sqlite-vec";
 import { drizzle } from "drizzle-orm/better-sqlite3";
-import { and, eq, like, asc, inArray } from "drizzle-orm";
+import { and, eq, like, asc, inArray, ne, or, isNull, lt, lte } from "drizzle-orm";
 import type {
   AiConversation,
   AiMessage,
@@ -204,11 +204,14 @@ export function initSchema(sqlite: Database.Database) {
       embedding_dimensions INTEGER,
       index_status TEXT NOT NULL DEFAULT 'pending',
       index_error TEXT,
+      retry_count INTEGER NOT NULL DEFAULT 0,
+      next_retry_at TEXT,
       updated_at TEXT NOT NULL
     );
 
     -- FTS5 mirror of chunk content for full-text search (works without sqlite-vec).
     CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_chunks_fts USING fts5(
+      chunk_id UNINDEXED,
       content,
       project_id UNINDEXED,
       source_type UNINDEXED,
@@ -219,10 +222,11 @@ export function initSchema(sqlite: Database.Database) {
 
     -- Embedding cache (Phase 3): same content_hash → reuse stored vector.
     CREATE TABLE IF NOT EXISTS embedding_cache (
-      content_hash TEXT PRIMARY KEY,
+      content_hash TEXT NOT NULL,
       embedding BLOB NOT NULL,
       model TEXT NOT NULL,
-      dimensions INTEGER NOT NULL
+      dimensions INTEGER NOT NULL,
+      PRIMARY KEY (content_hash, model)
     );
 
     -- AI conversations (Phase 4), separate from v1 pet conversations.
@@ -247,7 +251,66 @@ export function initSchema(sqlite: Database.Database) {
       value TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    );
   `);
+  runSchemaMigrations(sqlite);
+}
+
+function runSchemaMigrations(sqlite: Database.Database): void {
+  const applied = new Set((sqlite.prepare("SELECT version FROM schema_migrations").all() as Array<{ version: number }>).map((r) => r.version));
+  const apply = (version: number, migrate: () => void) => {
+    if (applied.has(version)) return;
+    sqlite.transaction(() => {
+      migrate();
+      sqlite.prepare("INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)").run(version, new Date().toISOString());
+    })();
+  };
+
+  apply(1, () => {
+    const columns = sqlite.prepare("PRAGMA table_info(embedding_cache)").all() as Array<{ name: string; pk: number }>;
+    const composite = columns.filter((c) => c.pk > 0).length === 2;
+    if (!composite) {
+      sqlite.exec(`
+        CREATE TABLE embedding_cache_v2 (
+          content_hash TEXT NOT NULL,
+          embedding BLOB NOT NULL,
+          model TEXT NOT NULL,
+          dimensions INTEGER NOT NULL,
+          PRIMARY KEY (content_hash, model)
+        );
+        INSERT OR REPLACE INTO embedding_cache_v2 SELECT content_hash, embedding, model, dimensions FROM embedding_cache;
+        DROP TABLE embedding_cache;
+        ALTER TABLE embedding_cache_v2 RENAME TO embedding_cache;
+      `);
+    }
+  });
+  apply(2, () => {
+    const names = new Set((sqlite.prepare("PRAGMA table_info(knowledge_chunks)").all() as Array<{ name: string }>).map((c) => c.name));
+    if (!names.has("retry_count")) sqlite.exec("ALTER TABLE knowledge_chunks ADD COLUMN retry_count INTEGER NOT NULL DEFAULT 0");
+    if (!names.has("next_retry_at")) sqlite.exec("ALTER TABLE knowledge_chunks ADD COLUMN next_retry_at TEXT");
+  });
+  apply(3, () => {
+    const sql = (sqlite.prepare("SELECT sql FROM sqlite_master WHERE name = 'knowledge_chunks_fts'").get() as { sql?: string } | undefined)?.sql ?? "";
+    if (!/chunk_id/i.test(sql)) {
+      sqlite.exec(`
+        DROP TABLE IF EXISTS knowledge_chunks_fts;
+        CREATE VIRTUAL TABLE knowledge_chunks_fts USING fts5(
+          chunk_id UNINDEXED,
+          content,
+          project_id UNINDEXED,
+          source_type UNINDEXED,
+          source_id UNINDEXED,
+          content_hash UNINDEXED,
+          tokenize = 'trigram'
+        );
+        INSERT INTO knowledge_chunks_fts (chunk_id, content, project_id, source_type, source_id, content_hash)
+          SELECT id, content, project_id, source_type, source_id, content_hash FROM knowledge_chunks;
+      `);
+    }
+  });
 }
 
 /** Read a single app_config value (JSON string), or null when absent. */
@@ -508,12 +571,14 @@ function toFocusRow(session: FocusSession): typeof focusSessions.$inferInsert {
 // branch) — memory callers get an explicit error.
 
 export interface KnowledgeStore {
+  runInTransaction<T>(operation: () => T): T;
   // Projects
   listProjects(): KnowledgeProject[];
   getProject(id: string): KnowledgeProject | null;
   childProjects(parentId: string): KnowledgeProject[];
   projectPath(id: string): KnowledgeProject[];
   createProject(input: { title: string; parentId?: string | null; description?: string; color?: string; icon?: string; isInbox?: boolean; order?: number }): KnowledgeProject;
+  upsertImportedProject(project: KnowledgeProject): void;
   updateProject(id: string, patch: Partial<Pick<KnowledgeProject, "title" | "description" | "color" | "icon" | "parentId" | "order">>): KnowledgeProject | null;
   deleteProject(id: string): void;
   ensureInbox(): KnowledgeProject;
@@ -521,17 +586,20 @@ export interface KnowledgeStore {
   notesForProject(projectId: string): KnowledgeNote[];
   getNote(id: string): KnowledgeNote | null;
   createNote(projectId: string, title: string): KnowledgeNote;
+  upsertImportedNote(note: KnowledgeNote): void;
   updateNote(id: string, patch: Partial<Pick<KnowledgeNote, "title" | "body" | "tags">>): KnowledgeNote | null;
   deleteNote(id: string): void;
   backlinksFor(targetId: string): { sourceType: "note" | "task"; sourceId: string }[];
   // Board columns
   columnsForProject(projectId: string): KnowledgeBoardColumn[];
   createColumn(projectId: string, input: { title: string; status: KnowledgeTaskStatus; order: number }): KnowledgeBoardColumn;
+  upsertImportedColumn(column: KnowledgeBoardColumn): void;
   updateColumn(id: string, patch: Partial<Pick<KnowledgeBoardColumn, "title" | "status" | "order">>): KnowledgeBoardColumn | null;
   deleteColumn(id: string): void;
   // Tasks
   tasksForProject(projectId: string): KnowledgeTask[];
   createTask(projectId: string, columnId: string, title: string): KnowledgeTask;
+  upsertImportedTask(task: KnowledgeTask): void;
   updateTask(id: string, patch: { title?: string; description?: string; status?: KnowledgeTaskStatus; columnId?: string; order?: number; linkedNoteId?: string | null }): KnowledgeTask | null;
   deleteTask(id: string): void;
   moveTask(taskId: string, targetColumnId: string, targetIndex: number): void;
@@ -541,15 +609,16 @@ export interface KnowledgeStore {
   reindexTask(task: KnowledgeTask, chunk: (text: string) => { content: string; contentHash: string }[]): void;
   removeIndex(sourceType: "note" | "task", sourceId: string): void;
   searchFts(projectId: string | null, query: string, limit: number): KnowledgeSource[];
+  getChunkContents(chunkIds: string[]): Map<string, string>;
   markStale(embeddingModel?: string): void;
   getIndexStatus(providerConfigured: boolean): IndexStatus;
   // Vector indexing (Phase 3). vecLoaded reflects whether sqlite-vec loaded.
   vecLoaded: boolean;
   ensureVecTable(dim: number): boolean;
   searchKnn(queryVec: number[], k: number, projectId: string | null): KnowledgeSource[];
-  putVecChunk(chunkId: string, vec: number[]): void;
+  putVecChunk(chunkId: string, projectId: string, vec: number[]): void;
   delVecChunk(chunkId: string): void;
-  getCachedEmbedding(contentHash: string): { vector: number[]; dimensions: number } | null;
+  getCachedEmbedding(contentHash: string, model: string): { vector: number[]; dimensions: number } | null;
   putCachedEmbedding(contentHash: string, vec: number[], model: string, dim: number): void;
   listPendingChunks(limit: number): Array<{
     id: string; content: string; contentHash: string; projectId: string; sourceType: "note" | "task"; sourceId: string;
@@ -574,6 +643,23 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   const vecVersion = vecState.version;
   const vecLoadError = vecState.error;
   let vecDim: number | null = null;
+  if (vecLoaded) {
+    const existingSql = (sqlite.prepare("SELECT sql FROM sqlite_master WHERE name = 'knowledge_chunks_vec'").get() as { sql?: string } | undefined)?.sql;
+    if (existingSql) {
+      const existingDim = Number(existingSql.match(/FLOAT\[(\d+)\]/i)?.[1]);
+      const hasPartition = /project_id\s+TEXT\s+PARTITION\s+KEY/i.test(existingSql);
+      if (Number.isFinite(existingDim) && hasPartition) {
+        vecDim = existingDim;
+      } else {
+        sqlite.exec("DROP TABLE knowledge_chunks_vec");
+        sqlite.prepare("UPDATE knowledge_chunks SET index_status = 'stale' WHERE index_status = 'indexed'").run();
+      }
+    }
+  }
+
+  function runInTransaction<T>(operation: () => T): T {
+    return sqlite.transaction(operation)();
+  }
 
   // ── tags helpers ──
   function ensureTagIds(names: string[]): string[] {
@@ -708,6 +794,18 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     }).run();
     return getProject(id)!;
   }
+  function upsertImportedProject(project: KnowledgeProject): void {
+    db.insert(knowledgeProjects).values({
+      id: project.id, title: project.title, description: project.description ?? null,
+      parentId: project.parentId, color: project.color ?? null, icon: project.icon ?? null,
+      isInbox: project.isInbox ?? false, order: project.order,
+      createdAt: new Date(project.createdAt).toISOString(), updatedAt: new Date(project.updatedAt).toISOString()
+    }).onConflictDoUpdate({ target: knowledgeProjects.id, set: {
+      title: project.title, description: project.description ?? null, parentId: project.parentId,
+      color: project.color ?? null, icon: project.icon ?? null, isInbox: project.isInbox ?? false,
+      order: project.order, updatedAt: new Date(project.updatedAt).toISOString()
+    }}).run();
+  }
   function updateProject(id: string, patch: Partial<Pick<KnowledgeProject, "title" | "description" | "color" | "icon" | "parentId" | "order">>): KnowledgeProject | null {
     const existing = db.select().from(knowledgeProjects).where(eq(knowledgeProjects.id, id)).get();
     if (!existing) return null;
@@ -723,12 +821,28 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     return getProject(id);
   }
   function deleteProject(id: string): void {
-    // cascade: notes (→ tags), columns, tasks, chunks
-    db.delete(knowledgeNotes).where(eq(knowledgeNotes.projectId, id)).run();
-    db.delete(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.projectId, id)).run();
-    db.delete(knowledgeTasks).where(eq(knowledgeTasks.projectId, id)).run();
-    db.delete(knowledgeChunks).where(eq(knowledgeChunks.projectId, id)).run();
-    db.delete(knowledgeProjects).where(eq(knowledgeProjects.id, id)).run();
+    sqlite.transaction(() => {
+      const projectIds: string[] = [];
+      const visited = new Set<string>();
+      const collect = (projectId: string) => {
+        if (visited.has(projectId)) return;
+        visited.add(projectId);
+        for (const child of childProjects(projectId)) collect(child.id);
+        projectIds.push(projectId);
+      };
+      collect(id);
+      for (const projectId of projectIds) {
+        for (const note of notesForProject(projectId)) {
+          removeIndex("note", note.id);
+          db.delete(knowledgeNoteTags).where(eq(knowledgeNoteTags.noteId, note.id)).run();
+        }
+        for (const task of tasksForProject(projectId)) removeIndex("task", task.id);
+        db.delete(knowledgeNotes).where(eq(knowledgeNotes.projectId, projectId)).run();
+        db.delete(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.projectId, projectId)).run();
+        db.delete(knowledgeTasks).where(eq(knowledgeTasks.projectId, projectId)).run();
+        db.delete(knowledgeProjects).where(eq(knowledgeProjects.id, projectId)).run();
+      }
+    })();
   }
   function ensureInbox(): KnowledgeProject {
     const existing = db.select().from(knowledgeProjects).where(eq(knowledgeProjects.isInbox, true)).get();
@@ -757,6 +871,16 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     }).run();
     return getNote(id)!;
   }
+  function upsertImportedNote(note: KnowledgeNote): void {
+    db.insert(knowledgeNotes).values({
+      id: note.id, projectId: note.projectId, title: note.title, body: note.body,
+      createdAt: new Date(note.createdAt).toISOString(), updatedAt: new Date(note.updatedAt).toISOString()
+    }).onConflictDoUpdate({ target: knowledgeNotes.id, set: {
+      projectId: note.projectId, title: note.title, body: note.body,
+      updatedAt: new Date(note.updatedAt).toISOString()
+    }}).run();
+    syncNoteTags(note.id, note.tags);
+  }
   function updateNote(id: string, patch: Partial<Pick<KnowledgeNote, "title" | "body" | "tags">>): KnowledgeNote | null {
     const existing = db.select().from(knowledgeNotes).where(eq(knowledgeNotes.id, id)).get();
     if (!existing) return null;
@@ -769,9 +893,11 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     return getNote(id);
   }
   function deleteNote(id: string): void {
-    db.delete(knowledgeNoteTags).where(eq(knowledgeNoteTags.noteId, id)).run();
-    db.delete(knowledgeNotes).where(eq(knowledgeNotes.id, id)).run();
-    db.delete(knowledgeChunks).where(eq(knowledgeChunks.sourceId, id)).run();
+    sqlite.transaction(() => {
+      removeIndex("note", id);
+      db.delete(knowledgeNoteTags).where(eq(knowledgeNoteTags.noteId, id)).run();
+      db.delete(knowledgeNotes).where(eq(knowledgeNotes.id, id)).run();
+    })();
   }
   function backlinksFor(targetId: string): { sourceType: "note" | "task"; sourceId: string }[] {
     // Basic [[target]] scan; upgraded to FTS in Phase 2.
@@ -795,6 +921,14 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     const row = db.select().from(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.id, id)).get();
     return rowToColumn(row!);
   }
+  function upsertImportedColumn(column: KnowledgeBoardColumn): void {
+    db.insert(knowledgeBoardColumns).values({
+      id: column.id, projectId: column.projectId, title: column.title,
+      status: column.status, order: column.order
+    }).onConflictDoUpdate({ target: knowledgeBoardColumns.id, set: {
+      projectId: column.projectId, title: column.title, status: column.status, order: column.order
+    }}).run();
+  }
   function updateColumn(id: string, patch: Partial<Pick<KnowledgeBoardColumn, "title" | "status" | "order">>): KnowledgeBoardColumn | null {
     const existing = db.select().from(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.id, id)).get();
     if (!existing) return null;
@@ -832,6 +966,18 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     }).run();
     return rowToTask(db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, id)).get()!);
   }
+  function upsertImportedTask(task: KnowledgeTask): void {
+    db.insert(knowledgeTasks).values({
+      id: task.id, projectId: task.projectId, columnId: task.columnId || null,
+      title: task.title, description: task.description ?? null, status: task.status,
+      order: task.order, linkedNoteId: task.linkedNoteId ?? null,
+      createdAt: new Date(task.createdAt).toISOString(), updatedAt: new Date(task.updatedAt).toISOString()
+    }).onConflictDoUpdate({ target: knowledgeTasks.id, set: {
+      projectId: task.projectId, columnId: task.columnId || null, title: task.title,
+      description: task.description ?? null, status: task.status, order: task.order,
+      linkedNoteId: task.linkedNoteId ?? null, updatedAt: new Date(task.updatedAt).toISOString()
+    }}).run();
+  }
   function updateTask(id: string, patch: { title?: string; description?: string; status?: KnowledgeTaskStatus; columnId?: string; order?: number; linkedNoteId?: string | null }): KnowledgeTask | null {
     const existing = db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, id)).get();
     if (!existing) return null;
@@ -848,8 +994,10 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     return row ? rowToTask(row) : null;
   }
   function deleteTask(id: string): void {
-    db.delete(knowledgeTasks).where(eq(knowledgeTasks.id, id)).run();
-    db.delete(knowledgeChunks).where(eq(knowledgeChunks.sourceId, id)).run();
+    sqlite.transaction(() => {
+      removeIndex("task", id);
+      db.delete(knowledgeTasks).where(eq(knowledgeTasks.id, id)).run();
+    })();
   }
   function moveTask(taskId: string, targetColumnId: string, targetIndex: number): void {
     const task = db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, taskId)).get();
@@ -873,64 +1021,43 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   function reindexNote(note: KnowledgeNote, chunk: (text: string) => { content: string; contentHash: string }[]): void {
     const text = note.body ? `${note.title}\n\n${note.body}` : note.title;
     const pieces = chunk(text);
-    // delete existing chunks + FTS rows for this source
-    removeIndex("note", note.id);
-
-    const now = nowIso();
-    let ordinal = 0;
-    for (const piece of pieces) {
-      const chunkId = crypto.randomUUID();
-      db.insert(knowledgeChunks).values({
-        id: chunkId,
-        projectId: note.projectId,
-        sourceType: "note",
-        sourceId: note.id,
-        ordinal,
-        content: piece.content,
-        contentHash: piece.contentHash,
-        embeddingModel: null,
-        embeddingDimensions: null,
-        indexStatus: "pending",
-        indexError: null,
-        updatedAt: now
-      }).run();
-      sqlite.exec(
-        `INSERT INTO knowledge_chunks_fts (content, project_id, source_type, source_id, content_hash)
-         VALUES (${sqlStr(piece.content)}, ${sqlStr(note.projectId)}, 'note', ${sqlStr(note.id)}, ${sqlStr(piece.contentHash)})`
-      );
-      ordinal += 1;
-    }
+    sqlite.transaction(() => {
+      removeIndex("note", note.id);
+      const now = nowIso();
+      pieces.forEach((piece, ordinal) => {
+        const chunkId = crypto.randomUUID();
+        db.insert(knowledgeChunks).values({
+          id: chunkId, projectId: note.projectId, sourceType: "note", sourceId: note.id,
+          ordinal, content: piece.content, contentHash: piece.contentHash,
+          embeddingModel: null, embeddingDimensions: null, indexStatus: "pending",
+          indexError: null, retryCount: 0, nextRetryAt: null, updatedAt: now
+        }).run();
+        sqlite.prepare(`INSERT INTO knowledge_chunks_fts
+          (chunk_id, content, project_id, source_type, source_id, content_hash) VALUES (?, ?, ?, 'note', ?, ?)`)
+          .run(chunkId, piece.content, note.projectId, note.id, piece.contentHash);
+      });
+    })();
   }
 
   function reindexTask(task: KnowledgeTask, chunk: (text: string) => { content: string; contentHash: string }[]): void {
     const text = task.description ? `${task.title}\n\n${task.description}` : task.title;
     const pieces = chunk(text);
-    removeIndex("task", task.id);
-
-    const now = nowIso();
-    let ordinal = 0;
-    for (const piece of pieces) {
-      const chunkId = crypto.randomUUID();
-      db.insert(knowledgeChunks).values({
-        id: chunkId,
-        projectId: task.projectId,
-        sourceType: "task",
-        sourceId: task.id,
-        ordinal,
-        content: piece.content,
-        contentHash: piece.contentHash,
-        embeddingModel: null,
-        embeddingDimensions: null,
-        indexStatus: "pending",
-        indexError: null,
-        updatedAt: now
-      }).run();
-      sqlite.exec(
-        `INSERT INTO knowledge_chunks_fts (content, project_id, source_type, source_id, content_hash)
-         VALUES (${sqlStr(piece.content)}, ${sqlStr(task.projectId)}, 'task', ${sqlStr(task.id)}, ${sqlStr(piece.contentHash)})`
-      );
-      ordinal += 1;
-    }
+    sqlite.transaction(() => {
+      removeIndex("task", task.id);
+      const now = nowIso();
+      pieces.forEach((piece, ordinal) => {
+        const chunkId = crypto.randomUUID();
+        db.insert(knowledgeChunks).values({
+          id: chunkId, projectId: task.projectId, sourceType: "task", sourceId: task.id,
+          ordinal, content: piece.content, contentHash: piece.contentHash,
+          embeddingModel: null, embeddingDimensions: null, indexStatus: "pending",
+          indexError: null, retryCount: 0, nextRetryAt: null, updatedAt: now
+        }).run();
+        sqlite.prepare(`INSERT INTO knowledge_chunks_fts
+          (chunk_id, content, project_id, source_type, source_id, content_hash) VALUES (?, ?, ?, 'task', ?, ?)`)
+          .run(chunkId, piece.content, task.projectId, task.id, piece.contentHash);
+      });
+    })();
   }
 
   function removeIndex(sourceType: "note" | "task", sourceId: string): void {
@@ -963,7 +1090,7 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     let sql: string;
     if (useMatch) {
       const ftsQuery = terms.map((t) => `"${t.replace(/"/g, "")}"*`).join(" OR ");
-      sql = `SELECT k.source_type, k.source_id, k.project_id, k.content,
+      sql = `SELECT k.chunk_id, k.source_type, k.source_id, k.project_id, k.content,
                 bm25(knowledge_chunks_fts) AS rank
          FROM knowledge_chunks_fts k
          WHERE k.content MATCH ${sqlStr(ftsQuery)}${projectClause}
@@ -971,13 +1098,13 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     } else {
       // LIKE fallback for short CJK terms; rank by position (earlier = better)
       const likeTerms = terms.map((t) => `k.content LIKE ${sqlStr(`%${t.replace(/[%_]/g, "\\$&")}%`)} ESCAPE '\\'`);
-      sql = `SELECT k.source_type, k.source_id, k.project_id, k.content, 0 AS rank
+      sql = `SELECT k.chunk_id, k.source_type, k.source_id, k.project_id, k.content, 0 AS rank
          FROM knowledge_chunks_fts k
          WHERE (${likeTerms.join(" OR ")})${projectClause}
          LIMIT ${cap}`;
     }
     const rows = sqlite.prepare(sql).all() as Array<{
-      source_type: "note" | "task"; source_id: string; project_id: string; content: string; rank: number;
+      chunk_id: string; source_type: "note" | "task"; source_id: string; project_id: string; content: string; rank: number;
     }>;
     // resolve titles + dedup by source (return best chunk per source)
     const bySource = new Map<string, KnowledgeSource>();
@@ -991,12 +1118,19 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
         projectId: row.project_id,
         title,
         excerpt: deriveExcerpt(row.content),
-        chunkId: key
+        chunkId: row.chunk_id
       });
     }
     return [...bySource.values()];
   }
 
+  function getChunkContents(chunkIds: string[]): Map<string, string> {
+    if (!chunkIds.length) return new Map();
+    const rows = db.select({ id: knowledgeChunks.id, content: knowledgeChunks.content })
+      .from(knowledgeChunks).where(inArray(knowledgeChunks.id, chunkIds)).all();
+    return new Map(rows.map((row) => [row.id, row.content]));
+  }
+
   function resolveSourceTitle(sourceType: "note" | "task", sourceId: string): string {
     if (sourceType === "note") {
       const row = db.select().from(knowledgeNotes).where(eq(knowledgeNotes.id, sourceId)).get();
@@ -1016,7 +1150,10 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     if (embeddingModel) {
       db.update(knowledgeChunks)
         .set({ indexStatus: "stale" })
-        .where(and(eq(knowledgeChunks.indexStatus, "indexed"), eq(knowledgeChunks.embeddingModel, embeddingModel)))
+        .where(and(
+          eq(knowledgeChunks.indexStatus, "indexed"),
+          or(isNull(knowledgeChunks.embeddingModel), ne(knowledgeChunks.embeddingModel, embeddingModel))
+        ))
         .run();
     } else {
       db.update(knowledgeChunks).set({ indexStatus: "stale" }).where(eq(knowledgeChunks.indexStatus, "indexed")).run();
@@ -1032,9 +1169,12 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     };
     const pending = countBy("pending");
     const stale = countBy("stale");
+    const retrying = (sqlite.prepare(
+      "SELECT COUNT(*) AS n FROM knowledge_chunks WHERE index_status = 'failed' AND retry_count < 3 AND next_retry_at IS NOT NULL"
+    ).get() as { n: number }).n;
     const hybridCapable = vecLoaded && providerConfigured;
     const mode: IndexStatus["mode"] = hybridCapable
-      ? pending + stale > 0
+      ? pending + stale + retrying > 0
         ? "indexing"
         : "hybrid"
       : "fts-only";
@@ -1043,6 +1183,7 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
       pending,
       failed: countBy("failed"),
       stale,
+      retrying,
       providerConfigured,
       vectorExtensionAvailable: vecLoaded,
       vecVersion,
@@ -1054,15 +1195,28 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   function ensureVecTable(dim: number): boolean {
     if (!vecLoaded) return false;
     if (vecDim === null) {
-      sqlite.exec(
-        `CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_chunks_vec USING vec0(chunk_id TEXT PRIMARY KEY, embedding FLOAT[${dim}])`
-      );
+      const existingSql = (sqlite.prepare("SELECT sql FROM sqlite_master WHERE name = 'knowledge_chunks_vec'").get() as { sql?: string } | undefined)?.sql;
+      const existingDim = Number(existingSql?.match(/FLOAT\[(\d+)\]/i)?.[1]);
+      const hasPartition = /project_id\s+TEXT\s+PARTITION\s+KEY/i.test(existingSql ?? "");
+      if (existingSql && (existingDim !== dim || !hasPartition)) {
+        sqlite.exec("DROP TABLE knowledge_chunks_vec");
+        markStale();
+      }
+      sqlite.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_chunks_vec USING vec0(
+        chunk_id TEXT PRIMARY KEY,
+        project_id TEXT PARTITION KEY,
+        embedding FLOAT[${dim}]
+      )`);
       vecDim = dim;
     } else if (vecDim !== dim) {
       // dimension changed (model swap) → drop, recreate, force full re-embed
       sqlite.exec("DROP TABLE IF EXISTS knowledge_chunks_vec");
       sqlite.exec(
-        `CREATE VIRTUAL TABLE knowledge_chunks_vec USING vec0(chunk_id TEXT PRIMARY KEY, embedding FLOAT[${dim}])`
+        `CREATE VIRTUAL TABLE knowledge_chunks_vec USING vec0(
+          chunk_id TEXT PRIMARY KEY,
+          project_id TEXT PARTITION KEY,
+          embedding FLOAT[${dim}]
+        )`
       );
       vecDim = dim;
       markStale();
@@ -1070,16 +1224,17 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     return true;
   }
 
-  function putVecChunk(chunkId: string, vec: number[]): void {
+  function putVecChunk(chunkId: string, projectId: string, vec: number[]): void {
     if (!vecLoaded || vecDim === null) return;
     sqlite.prepare(
-      "INSERT OR REPLACE INTO knowledge_chunks_vec (chunk_id, embedding) VALUES (?, ?)"
-    ).run(chunkId, toVecBuffer(vec));
+      "INSERT OR REPLACE INTO knowledge_chunks_vec (chunk_id, project_id, embedding) VALUES (?, ?, ?)"
+    ).run(chunkId, projectId, toVecBuffer(vec));
   }
 
   function delVecChunk(chunkId: string): void {
-    if (!vecLoaded || vecDim === null) return;
-    sqlite.prepare("DELETE FROM knowledge_chunks_vec WHERE chunk_id = ?").run(chunkId);
+    if (!vecLoaded) return;
+    const exists = sqlite.prepare("SELECT 1 FROM sqlite_master WHERE name = 'knowledge_chunks_vec'").get();
+    if (exists) sqlite.prepare("DELETE FROM knowledge_chunks_vec WHERE chunk_id = ?").run(chunkId);
   }
 
   function searchKnn(
@@ -1089,13 +1244,15 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   ): KnowledgeSource[] {
     if (!vecLoaded || vecDim === null || queryVec.length !== vecDim) return [];
     const cap = Math.max(1, Math.min(k, 50));
-    const rows = sqlite.prepare(
-      `SELECT v.chunk_id AS chunk_id, v.distance AS distance
-         FROM knowledge_chunks_vec v
-         WHERE v.embedding MATCH ?
-         ORDER BY v.distance
-         LIMIT ${cap}`
-    ).all(toVecBuffer(queryVec)) as Array<{ chunk_id: string; distance: number }>;
+    const rows = projectId
+      ? sqlite.prepare(`SELECT v.chunk_id AS chunk_id, v.distance AS distance
+          FROM knowledge_chunks_vec v
+          WHERE v.embedding MATCH ? AND v.project_id = ? AND k = ?
+          ORDER BY v.distance`).all(toVecBuffer(queryVec), projectId, cap) as Array<{ chunk_id: string; distance: number }>
+      : sqlite.prepare(`SELECT v.chunk_id AS chunk_id, v.distance AS distance
+          FROM knowledge_chunks_vec v
+          WHERE v.embedding MATCH ? AND k = ?
+          ORDER BY v.distance`).all(toVecBuffer(queryVec), cap) as Array<{ chunk_id: string; distance: number }>;
     if (!rows.length) return [];
     const ids = rows.map((r) => r.chunk_id);
     const chunkRows = db.select().from(knowledgeChunks).where(inArray(knowledgeChunks.id, ids)).all();
@@ -1120,8 +1277,9 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     return [...bySource.values()];
   }
 
-  function getCachedEmbedding(contentHash: string): { vector: number[]; dimensions: number } | null {
-    const row = db.select().from(embeddingCache).where(eq(embeddingCache.contentHash, contentHash)).get();
+  function getCachedEmbedding(contentHash: string, model: string): { vector: number[]; dimensions: number } | null {
+    const row = db.select().from(embeddingCache)
+      .where(and(eq(embeddingCache.contentHash, contentHash), eq(embeddingCache.model, model))).get();
     if (!row) return null;
     return { vector: bufferToVec(row.embedding), dimensions: row.dimensions };
   }
@@ -1133,7 +1291,7 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
       model,
       dimensions: dim
     }).onConflictDoUpdate({
-      target: embeddingCache.contentHash,
+      target: [embeddingCache.contentHash, embeddingCache.model],
       set: { embedding: toVecBuffer(vec), model, dimensions: dim }
     }).run();
   }
@@ -1150,7 +1308,14 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
       sourceId: knowledgeChunks.sourceId
     })
       .from(knowledgeChunks)
-      .where(inArray(knowledgeChunks.indexStatus, ["pending", "stale"]))
+      .where(or(
+        inArray(knowledgeChunks.indexStatus, ["pending", "stale"]),
+        and(
+          eq(knowledgeChunks.indexStatus, "failed"),
+          lt(knowledgeChunks.retryCount, 3),
+          lte(knowledgeChunks.nextRetryAt, nowIso())
+        )
+      ))
       .limit(limit)
       .all();
   }
@@ -1161,14 +1326,24 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
       embeddingModel: model,
       embeddingDimensions: dim,
       indexError: null,
+      retryCount: 0,
+      nextRetryAt: null,
       updatedAt: nowIso()
     }).where(eq(knowledgeChunks.id, chunkId)).run();
   }
 
   function markChunkFailed(chunkId: string, error: string): void {
+    const current = db.select({ retryCount: knowledgeChunks.retryCount })
+      .from(knowledgeChunks).where(eq(knowledgeChunks.id, chunkId)).get();
+    const retryCount = (current?.retryCount ?? 0) + 1;
+    const retryDelays = [60_000, 300_000, 1_800_000];
     db.update(knowledgeChunks).set({
       indexStatus: "failed",
       indexError: error,
+      retryCount,
+      nextRetryAt: retryCount <= retryDelays.length
+        ? new Date(Date.now() + retryDelays[retryCount - 1]).toISOString()
+        : null,
       updatedAt: nowIso()
     }).where(eq(knowledgeChunks.id, chunkId)).run();
   }
@@ -1186,11 +1361,12 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   }
 
   return {
-    listProjects, getProject, childProjects, projectPath, createProject, updateProject, deleteProject, ensureInbox,
-    notesForProject, getNote, createNote, updateNote, deleteNote, backlinksFor,
-    columnsForProject, createColumn, updateColumn, deleteColumn,
-    tasksForProject, createTask, updateTask, deleteTask, moveTask,
-    reindexNote, reindexTask, removeIndex, searchFts, markStale, getIndexStatus,
+    runInTransaction,
+    listProjects, getProject, childProjects, projectPath, createProject, upsertImportedProject, updateProject, deleteProject, ensureInbox,
+    notesForProject, getNote, createNote, upsertImportedNote, updateNote, deleteNote, backlinksFor,
+    columnsForProject, createColumn, upsertImportedColumn, updateColumn, deleteColumn,
+    tasksForProject, createTask, upsertImportedTask, updateTask, deleteTask, moveTask,
+    reindexNote, reindexTask, removeIndex, searchFts, getChunkContents, markStale, getIndexStatus,
     get vecLoaded() { return vecLoaded; },
     ensureVecTable, searchKnn, putVecChunk, delVecChunk, getCachedEmbedding, putCachedEmbedding,
     listPendingChunks, markChunkIndexed, markChunkFailed
diff --git a/packages/db/src/schema.ts b/packages/db/src/schema.ts
index d63cc00..6d14ec8 100644
--- a/packages/db/src/schema.ts
+++ b/packages/db/src/schema.ts
@@ -1,4 +1,4 @@
-import { blob, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { blob, integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
 
 export const tasks = sqliteTable("tasks", {
   id: text("id").primaryKey(),
@@ -120,17 +120,19 @@ export const knowledgeChunks = sqliteTable("knowledge_chunks", {
   embeddingDimensions: integer("embedding_dimensions"),
   indexStatus: text("index_status", { enum: ["pending", "indexed", "failed", "stale"] }).notNull().default("pending"),
   indexError: text("index_error"),
+  retryCount: integer("retry_count").notNull().default(0),
+  nextRetryAt: text("next_retry_at"),
   updatedAt: text("updated_at").notNull()
 });
 
 // Embedding cache keyed by content hash. Same-hash chunks reuse the stored
 // vector, skipping redundant embedding API calls (Phase 3).
 export const embeddingCache = sqliteTable("embedding_cache", {
-  contentHash: text("content_hash").primaryKey(),
+  contentHash: text("content_hash").notNull(),
   embedding: blob("embedding", { mode: "buffer" }).notNull(),
   model: text("model").notNull(),
   dimensions: integer("dimensions").notNull()
-});
+}, (table) => [primaryKey({ columns: [table.contentHash, table.model] })]);
 
 // AI conversations (Phase 4). Separate from the v1 `conversations`/`messages`
 // tables (pet-panel chat) — these carry knowledge RAG context + sources.
diff --git a/packages/server-local/src/app.ts b/packages/server-local/src/app.ts
index a30ca78..30b4df8 100644
--- a/packages/server-local/src/app.ts
+++ b/packages/server-local/src/app.ts
@@ -1,6 +1,7 @@
 import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
 import Fastify, { type FastifyInstance } from "fastify";
+import { timingSafeEqual } from "node:crypto";
 import { streamDeepSeekChat, embedContents } from "@neo-companion/ai";
 import { createAiConversationStore, createDatabase, createKnowledgeStore, createTaskStore, createWindowEventStore, getAppConfig, setAppConfig, type AiConversationStore, type KnowledgeStore, type NeoDatabase } from "@neo-companion/db";
 import type { ChatMessage, CompanionFeedback, TtsResult } from "@neo-companion/shared";
@@ -22,9 +23,13 @@ export interface AppDependencies {
   windowSnapshot?: typeof getActiveWindowSnapshot;
   startBackground?: boolean;
   hookManager?: ReturnType<typeof createHookManager>;
+  /** Shared bearer token. Tests inject this; production reads APP_AUTH_TOKEN. */
+  authToken?: string;
 }
 
 export async function createApp(dependencies: AppDependencies = {}) {
+  const authToken = dependencies.authToken ?? process.env.APP_AUTH_TOKEN;
+  if (!authToken) throw new Error("APP_AUTH_TOKEN is required");
   const database = dependencies.database ?? createDatabase();
   const taskStore = createTaskStore(database);
   const windowStore = createWindowEventStore(database);
@@ -45,15 +50,27 @@ export async function createApp(dependencies: AppDependencies = {}) {
       return { provider: "none" };
     }
   };
-  let embeddingConfig: EmbeddingConfig =
-    database.kind === "sqlite" ? parseConfig(getAppConfig(database, EMBEDDING_CONFIG_KEY)) : { provider: "none" };
+  const loadedEmbeddingConfig = database.kind === "sqlite" ? parseConfig(getAppConfig(database, EMBEDDING_CONFIG_KEY)) : { provider: "none" };
+  let legacyEmbeddingApiKey = loadedEmbeddingConfig.apiKey;
+  let runtimeEmbeddingApiKey: string | undefined;
+  let embeddingConfig: EmbeddingConfig = { ...loadedEmbeddingConfig, apiKey: undefined };
+  const persistEmbeddingConfig = () => {
+    if (database.kind !== "sqlite") return;
+    const persisted = { ...embeddingConfig, apiKey: legacyEmbeddingApiKey };
+    if (!legacyEmbeddingApiKey) delete persisted.apiKey;
+    setAppConfig(database, EMBEDDING_CONFIG_KEY, JSON.stringify(persisted));
+  };
   const embeddingConfigController = {
-    get: () => embeddingConfig,
+    get: () => ({ ...embeddingConfig, apiKey: runtimeEmbeddingApiKey ?? legacyEmbeddingApiKey }),
     set: (next: EmbeddingConfig) => {
-      embeddingConfig = next;
-      if (database.kind === "sqlite") {
-        setAppConfig(database, EMBEDDING_CONFIG_KEY, JSON.stringify(next));
-      }
+      runtimeEmbeddingApiKey = next.apiKey;
+      embeddingConfig = { ...next, apiKey: undefined };
+      persistEmbeddingConfig();
+    },
+    getLegacySecret: () => legacyEmbeddingApiKey,
+    clearLegacySecret: () => {
+      legacyEmbeddingApiKey = undefined;
+      persistEmbeddingConfig();
     }
   };
   const knowledgeService: KnowledgeService | null = knowledgeStore
@@ -62,6 +79,7 @@ export async function createApp(dependencies: AppDependencies = {}) {
         getEmbeddingConfig: embeddingConfigController.get
       })
     : null;
+  void knowledgeService?.drainEmbeddings();
   const hub = new WsHub();
   const app = Fastify({ logger: true });
   const aiStream = dependencies.aiStream ?? ((messages) => streamDeepSeekChat(messages));
@@ -76,9 +94,58 @@ export async function createApp(dependencies: AppDependencies = {}) {
   const ttsSpeak = dependencies.ttsSpeak ?? ((text, style) => speakWithMimo(text, style));
   const windowSnapshot = dependencies.windowSnapshot ?? getActiveWindowSnapshot;
 
-  await app.register(cors, { origin: true });
+  const allowedOrigins = new Set([
+    "tauri://localhost",
+    "http://tauri.localhost",
+    "https://tauri.localhost",
+    "http://127.0.0.1:5173",
+    ...(process.env.NEO_ALLOWED_ORIGINS ?? "").split(",").map((v) => v.trim()).filter(Boolean)
+  ]);
+  await app.register(cors, {
+    origin(origin, callback) {
+      if (!origin || allowedOrigins.has(origin)) callback(null, true);
+      else callback(null, false);
+    }
+  });
   await app.register(websocket);
 
+  const tokenMatches = (candidate: string | undefined): boolean => {
+    if (!candidate) return false;
+    const expected = Buffer.from(authToken);
+    const actual = Buffer.from(candidate);
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+  };
+  const ROOT_PATH_KEY = "knowledge.rootPath";
+  let knowledgeRootPath = database.kind === "sqlite" ? (getAppConfig(database, ROOT_PATH_KEY) ?? "") : "";
+  const rootPathController = {
+    get: () => knowledgeRootPath,
+    set: (path: string) => {
+      knowledgeRootPath = path;
+      if (database.kind === "sqlite") setAppConfig(database, ROOT_PATH_KEY, path);
+    }
+  };
+
+  app.addHook("onRequest", async (request, reply) => {
+    const rawHost = request.headers.host ?? "";
+    const host = rawHost.startsWith("[") ? rawHost.slice(1, rawHost.indexOf("]")) : rawHost.split(":")[0];
+    if (!new Set(["127.0.0.1", "localhost", "::1"]).has(host)) {
+      return reply.code(403).send({ error: "host not allowed" });
+    }
+    const origin = request.headers.origin;
+    if (origin && !allowedOrigins.has(origin)) {
+      return reply.code(403).send({ error: "origin not allowed" });
+    }
+    if (request.method === "OPTIONS") return;
+    const bearer = request.headers.authorization?.match(/^Bearer\s+(.+)$/i)?.[1];
+    const protocols = String(request.headers["sec-websocket-protocol"] ?? "")
+      .split(",")
+      .map((value) => value.trim());
+    const wsToken = protocols.find((value) => value.startsWith("auth."))?.slice(5);
+    if (!tokenMatches(bearer) && !tokenMatches(wsToken)) {
+      return reply.code(401).send({ error: "unauthorized" });
+    }
+  });
+
   const focus = createFocusManager(database, {
     onTick(payload) {
       hub.broadcast({ type: "focus:tick", payload });
@@ -137,7 +204,7 @@ export async function createApp(dependencies: AppDependencies = {}) {
     return task;
   });
 
-  registerKnowledgeRoutes(app, knowledgeStore, knowledgeService, embeddingConfigController);
+  registerKnowledgeRoutes(app, knowledgeStore, knowledgeService, embeddingConfigController, rootPathController);
 
   app.post("/api/focus/start", async (request) => {
     const body = request.body as { taskId?: string | null; durationMinutes?: number };
diff --git a/packages/server-local/src/modules/ai/context.test.ts b/packages/server-local/src/modules/ai/context.test.ts
index c594c4f..1cf1b4f 100644
--- a/packages/server-local/src/modules/ai/context.test.ts
+++ b/packages/server-local/src/modules/ai/context.test.ts
@@ -1,12 +1,17 @@
 import { describe, expect, it } from "vitest";
 import type { ContextLevel, KnowledgeNote, KnowledgeTask } from "@neo-companion/shared";
-import { buildChatBlocks, estimateTokens, packContext, summarizeNote, WEIGHTS, type ContextBlock } from "./context";
+import { buildAskBlocks, buildChatBlocks, estimateTokens, packContext, summarizeNote, WEIGHTS, type ContextBlock } from "./context";
 
 function note(id: string, title: string, body: string): KnowledgeNote {
   return { id, projectId: "p", title, body, tags: [], createdAt: 0, updatedAt: 0 };
 }
 
 describe("context assembly", () => {
+  it("uses full retrieved chunk content for Ask blocks", () => {
+    const source = { sourceType: "note" as const, sourceId: "n1", projectId: "p1", title: "T", excerpt: "short", chunkId: "c1" };
+    const blocks = buildAskBlocks([source], new Map([["c1", "full chunk content"]]));
+    expect(blocks[0].content).toBe("full chunk content");
+  });
   it("summarizes a note to its first section", () => {
     const n = note("n1", "标题", "首段内容。\n\n## 第二节\n更多内容。");
     expect(summarizeNote(n)).toBe("首段内容。");
diff --git a/packages/server-local/src/modules/ai/service.ts b/packages/server-local/src/modules/ai/service.ts
index 4963869..424315e 100644
--- a/packages/server-local/src/modules/ai/service.ts
+++ b/packages/server-local/src/modules/ai/service.ts
@@ -53,14 +53,14 @@ export function createAiService(deps: AiServiceDeps) {
   }
 
   /** Plain fallback chat (no knowledge context), preserving existing behavior. */
-  async function plainChat(message: string): Promise<AiAnswer> {
+  async function plainChat(message: string, retrievalMode: AiRetrievalMode = "chat"): Promise<AiAnswer> {
     const messages: ChatMessage[] = [
       { role: "system", content: DEFAULT_SYSTEM_PROMPT },
       { role: "user", content: message }
     ];
     hub.broadcast({ type: "companion:feedback", payload: { state: "thinking", text: "我想一想。", speak: false } });
     const text = await streamReply(messages);
-    const answer: AiAnswer = { text, sources: [], retrievalMode: "chat" };
+    const answer: AiAnswer = { text, sources: [], retrievalMode };
     hub.broadcast({ type: "ai:done", payload: answer });
     return answer;
   }
@@ -78,7 +78,7 @@ export function createAiService(deps: AiServiceDeps) {
     for (const [noteId, level] of Object.entries(ctx.notes)) {
       if (level === "excluded") continue;
       const note = knowledgeStore.getNote(noteId);
-      if (!note) continue;
+      if (!note || (req.projectId && note.projectId !== req.projectId)) continue;
       noteBlocks.push({
         type: "note",
         ref: note.id,
@@ -156,16 +156,16 @@ export function createAiService(deps: AiServiceDeps) {
   }
 
   async function handleAsk(req: AskRequest): Promise<AiAnswer> {
-    if (!knowledgeService || !req.projectId) return plainChat(req.message);
+    if (!knowledgeService || !req.projectId) return plainChat(req.message, "ask");
 
     const sources = await knowledgeService.searchHybrid(req.projectId, req.message, 8);
-    if (!sources.length) return plainChat(req.message);
+    if (!sources.length) return plainChat(req.message, "ask");
 
     const sourceLookup = new Map<string, KnowledgeSource>();
     sources.forEach((s) => sourceLookup.set(s.sourceId, s));
-    const blocks = buildAskBlocks(sources, new Map());
+    const blocks = buildAskBlocks(sources, knowledgeService.getChunkContents(sources.map((source) => source.chunkId)));
     const packed = packContext(blocks, CONTEXT_TOKEN_BUDGET);
-    if (!packed.ordered.length) return plainChat(req.message);
+    if (!packed.ordered.length) return plainChat(req.message, "ask");
 
     const injected = injectSources(packed.ordered);
     const validIds = new Set(injected.idToRef.keys());
diff --git a/packages/server-local/src/modules/knowledge/mirror.test.ts b/packages/server-local/src/modules/knowledge/mirror.test.ts
index 53ebd04..2bb456c 100644
--- a/packages/server-local/src/modules/knowledge/mirror.test.ts
+++ b/packages/server-local/src/modules/knowledge/mirror.test.ts
@@ -23,6 +23,7 @@ function createFakeStore(): KnowledgeStore {
   const now = () => Date.now();
 
   const store: KnowledgeStore = {
+    runInTransaction: (operation) => operation(),
     listProjects: () => [...projects.values()].sort((a, b) => a.order - b.order),
     getProject: (i) => projects.get(i) ?? null,
     childProjects: (pid) => [...projects.values()].filter((p) => p.parentId === pid).sort((a, b) => a.order - b.order),
@@ -40,6 +41,7 @@ function createFakeStore(): KnowledgeStore {
       };
       projects.set(p.id, p); return p;
     },
+    upsertImportedProject: (p) => { projects.set(p.id, { ...p }); },
     updateProject: (i, patch) => {
       const ex = projects.get(i); if (!ex) return null;
       const next: KnowledgeProject = { ...ex, ...patch, updatedAt: now() };
@@ -56,6 +58,7 @@ function createFakeStore(): KnowledgeStore {
       const n: KnowledgeNote = { id: id(), projectId: pid, title: title || "无标题", body: "", tags: [], createdAt: now(), updatedAt: now() };
       notes.set(n.id, n); return n;
     },
+    upsertImportedNote: (n) => { notes.set(n.id, { ...n }); },
     updateNote: (i, patch) => {
       const ex = notes.get(i); if (!ex) return null;
       const next: KnowledgeNote = { ...ex, ...patch, updatedAt: now() };
@@ -68,6 +71,7 @@ function createFakeStore(): KnowledgeStore {
       const c: KnowledgeBoardColumn = { id: id(), projectId: pid, title: input.title, status: input.status, order: input.order };
       columns.set(c.id, c); return c;
     },
+    upsertImportedColumn: (c) => { columns.set(c.id, { ...c }); },
     updateColumn: (i, patch) => {
       const ex = columns.get(i); if (!ex) return null;
       const next = { ...ex, ...patch };
@@ -79,6 +83,7 @@ function createFakeStore(): KnowledgeStore {
       const t: KnowledgeTask = { id: id(), projectId: pid, columnId, title, status: "todo", order: 0, tags: [], createdAt: now(), updatedAt: now() };
       tasks.set(t.id, t); return t;
     },
+    upsertImportedTask: (t) => { tasks.set(t.id, { ...t }); },
     updateTask: (i, patch) => {
       const ex = tasks.get(i); if (!ex) return null;
       const next: KnowledgeTask = {
@@ -99,9 +104,10 @@ function createFakeStore(): KnowledgeStore {
     reindexTask: () => {},
     removeIndex: () => {},
     searchFts: () => [],
+    getChunkContents: () => new Map(),
     markStale: () => {},
     getIndexStatus: () => ({
-      mode: "fts-only" as const, pending: 0, failed: 0, stale: 0,
+      mode: "fts-only" as const, pending: 0, failed: 0, stale: 0, retrying: 0,
       providerConfigured: false, vectorExtensionAvailable: false
     }),
     vecLoaded: false,
@@ -167,5 +173,10 @@ describe("knowledge file mirror", () => {
     expect(stats.importedProjects).toBe(1);
     expect(target.listProjects()[0].title).toBe("导入项目");
     expect(target.notesForProject(project.id)).toHaveLength(1);
+    expect(target.notesForProject(project.id)[0].id).toBe(note.id);
+
+    const second = await importFromDir(target, dir);
+    expect(second.importedProjects).toBe(0);
+    expect(second.importedNotes).toBe(0);
   });
 });
diff --git a/packages/server-local/src/modules/knowledge/mirror.ts b/packages/server-local/src/modules/knowledge/mirror.ts
index b778a3e..2407d11 100644
--- a/packages/server-local/src/modules/knowledge/mirror.ts
+++ b/packages/server-local/src/modules/knowledge/mirror.ts
@@ -115,6 +115,14 @@ export interface ImportStats {
   importedColumns: number;
   importedTasks: number;
   skipped: number;
+  reindexedNotes: number;
+  reindexedTasks: number;
+  errors: string[];
+}
+
+export interface ImportHooks {
+  noteChanged?: (note: KnowledgeNote) => void;
+  taskChanged?: (task: KnowledgeTask) => void;
 }
 
 /**
@@ -122,11 +130,15 @@ export interface ImportStats {
  * by `updatedAt`. Creates projects/notes/columns/tasks that exist on disk but
  * not in SQLite; updates those whose file `updatedAt` is newer.
  */
-export async function importFromDir(store: KnowledgeStore, rootPath: string): Promise<ImportStats> {
-  const stats: ImportStats = { importedProjects: 0, importedNotes: 0, importedColumns: 0, importedTasks: 0, skipped: 0 };
+export async function importFromDir(store: KnowledgeStore, rootPath: string, hooks: ImportHooks = {}): Promise<ImportStats> {
+  const stats: ImportStats = {
+    importedProjects: 0, importedNotes: 0, importedColumns: 0, importedTasks: 0,
+    skipped: 0, reindexedNotes: 0, reindexedTasks: 0, errors: []
+  };
 
   const projectFolders = await collectProjectFolders(rootPath);
   for (const folder of projectFolders) {
+    try {
     const meta = await readJsonOptional<ProjectMeta>(path.join(folder, NEO_DIR, "project.json"));
     if (!meta) {
       stats.skipped += 1;
@@ -135,17 +147,12 @@ export async function importFromDir(store: KnowledgeStore, rootPath: string): Pr
 
     const existing = store.getProject(meta.id);
     if (!existing || meta.updatedAt > existing.updatedAt) {
-      const input = {
-        title: meta.title,
-        parentId: meta.parentId,
-        description: meta.description,
-        color: meta.color,
-        icon: meta.icon,
-        isInbox: meta.isInbox,
-        order: meta.order
-      };
-      if (existing) store.updateProject(meta.id, input);
-      else store.createProject({ ...input, title: meta.title });
+      store.runInTransaction(() => store.upsertImportedProject({
+          id: meta.id, title: meta.title, parentId: meta.parentId,
+          description: meta.description, color: meta.color, icon: meta.icon,
+          isInbox: meta.isInbox, order: meta.order,
+          createdAt: meta.createdAt, updatedAt: meta.updatedAt
+        }));
       stats.importedProjects += 1;
     }
 
@@ -168,13 +175,11 @@ export async function importFromDir(store: KnowledgeStore, rootPath: string): Pr
           createdAt: fm.createdAt,
           updatedAt: fm.updatedAt
         };
-        if (existingNote) store.updateNote(fm.id, { title: noteInput.title, body: noteInput.body, tags: noteInput.tags });
-        else {
-          // create then patch body/tags (store.createNote only takes title)
-          const created = store.createNote(meta.id, fm.title);
-          store.updateNote(created.id, { body: noteInput.body, tags: noteInput.tags });
-          // note: created.id differs from fm.id; for v1 we accept re-id on import-create
-        }
+        store.runInTransaction(() => {
+          store.upsertImportedNote(noteInput);
+          hooks.noteChanged?.(noteInput);
+        });
+        stats.reindexedNotes += 1;
         stats.importedNotes += 1;
       }
     }
@@ -185,8 +190,7 @@ export async function importFromDir(store: KnowledgeStore, rootPath: string): Pr
       for (const col of fromJsonl<KnowledgeBoardColumn>(columnsText)) {
         const existingCol = store.columnsForProject(meta.id).find((c) => c.id === col.id);
         if (!existingCol || col.order !== existingCol.order || col.title !== existingCol.title || col.status !== existingCol.status) {
-          if (existingCol) store.updateColumn(col.id, { title: col.title, status: col.status, order: col.order });
-          else store.createColumn(meta.id, { title: col.title, status: col.status, order: col.order });
+          store.runInTransaction(() => store.upsertImportedColumn({ ...col, projectId: meta.id }));
           stats.importedColumns += 1;
         }
       }
@@ -198,29 +202,19 @@ export async function importFromDir(store: KnowledgeStore, rootPath: string): Pr
       for (const task of fromJsonl<KnowledgeTask>(tasksText)) {
         const existingTask = store.tasksForProject(meta.id).find((t) => t.id === task.id);
         if (!existingTask || task.updatedAt > existingTask.updatedAt) {
-          if (existingTask) {
-            store.updateTask(task.id, {
-              title: task.title,
-              description: task.description,
-              status: task.status,
-              columnId: task.columnId,
-              order: task.order,
-              linkedNoteId: task.linkedNoteId ?? null
-            });
-          } else {
-            const created = store.createTask(meta.id, task.columnId || "", task.title);
-            store.updateTask(created.id, {
-              description: task.description,
-              status: task.status,
-              columnId: task.columnId,
-              order: task.order,
-              linkedNoteId: task.linkedNoteId ?? null
-            });
-          }
+          const importedTask = { ...task, projectId: meta.id };
+          store.runInTransaction(() => {
+            store.upsertImportedTask(importedTask);
+            hooks.taskChanged?.(importedTask);
+          });
+          stats.reindexedTasks += 1;
           stats.importedTasks += 1;
         }
       }
     }
+    } catch (error) {
+      stats.errors.push(`${folder}: ${error instanceof Error ? error.message : String(error)}`);
+    }
   }
 
   return stats;
diff --git a/packages/server-local/src/modules/knowledge/routes.ts b/packages/server-local/src/modules/knowledge/routes.ts
index 2c73b8d..9a58fba 100644
--- a/packages/server-local/src/modules/knowledge/routes.ts
+++ b/packages/server-local/src/modules/knowledge/routes.ts
@@ -10,6 +10,12 @@ import type { EmbeddingConfig, KnowledgeService } from "./service";
 export interface EmbeddingConfigController {
   get(): EmbeddingConfig;
   set(config: EmbeddingConfig): void;
+  getLegacySecret(): string | undefined;
+  clearLegacySecret(): void;
+}
+export interface RootPathController {
+  get(): string;
+  set(path: string): void;
 }
 
 /**
@@ -26,12 +32,13 @@ export function registerKnowledgeRoutes(
   app: FastifyInstance,
   store: KnowledgeStore | null,
   service: KnowledgeService | null,
-  embeddingConfigController?: EmbeddingConfigController
+  embeddingConfigController?: EmbeddingConfigController,
+  rootPathController?: RootPathController
 ) {
   // File-mirror root path. The frontend owns the canonical path in localStorage
   // (useSettings.knowledgeRootPath) and pushes it here so the sidecar can do
   // export/import. Empty until the user picks a folder.
-  let rootPath = "";
+  let rootPath = rootPathController?.get() ?? "";
 
   const requireStore = (reply: import("fastify").FastifyReply): KnowledgeStore | null => {
     if (!store) {
@@ -268,17 +275,30 @@ export function registerKnowledgeRoutes(
   // service falls back to the EMBEDDING_API_KEY env var.
   app.get("/api/knowledge/embedding-config", async () => {
     const cfg = embeddingConfigController?.get() ?? { provider: "none" };
-    const hasStoredKey = !!cfg.apiKey;
+    const hasRuntimeKey = !!cfg.apiKey;
+    const hasLegacyKey = !!embeddingConfigController?.getLegacySecret();
     const hasEnvKey = !!process.env.EMBEDDING_API_KEY;
     return {
       provider: cfg.provider,
       baseUrl: cfg.baseUrl ?? "",
       model: cfg.model ?? "",
-      configured: cfg.provider !== "none" && !!cfg.model && (hasStoredKey || hasEnvKey),
-      apiKeySource: hasStoredKey ? "stored" : hasEnvKey ? "env" : "none"
+      configured: cfg.provider !== "none" && !!cfg.model && (hasRuntimeKey || hasLegacyKey || hasEnvKey),
+      apiKeySource: hasLegacyKey ? "legacy" : cfg.apiKeySource === "keychain" ? "keychain" : hasEnvKey ? "env" : "none",
+      legacyMigrationRequired: hasLegacyKey
     };
   });
 
+  app.post("/api/knowledge/embedding-config/legacy-secret/claim", async (request, reply) => {
+    const apiKey = embeddingConfigController?.getLegacySecret();
+    if (!apiKey) return reply.code(404).send({ error: "legacy secret not found" });
+    return { apiKey };
+  });
+
+  app.delete("/api/knowledge/embedding-config/legacy-secret", async (request, reply) => {
+    embeddingConfigController?.clearLegacySecret();
+    return reply.code(204).send();
+  });
+
   app.put("/api/knowledge/embedding-config", async (request, reply) => {
     if (!embeddingConfigController) return reply.code(503).send({ error: "embedding config unavailable" });
     const body = request.body as Partial<EmbeddingConfig>;
@@ -298,7 +318,8 @@ export function registerKnowledgeRoutes(
       provider: body.provider ?? current.provider,
       baseUrl: body.baseUrl ?? current.baseUrl,
       apiKey,
-      model: body.model ?? current.model
+      model: body.model ?? current.model,
+      apiKeySource: body.apiKeySource ?? current.apiKeySource
     };
     embeddingConfigController.set(next);
     // model change → mark stale so chunks re-embed with the new model
@@ -315,6 +336,7 @@ export function registerKnowledgeRoutes(
   app.put("/api/knowledge/root-path", async (request, reply) => {
     const body = request.body as { path?: string };
     rootPath = (body.path ?? "").trim();
+    rootPathController?.set(rootPath);
     return { path: rootPath };
   });
 
@@ -334,7 +356,10 @@ export function registerKnowledgeRoutes(
     const body = (request.body as { path?: string } | null) ?? {};
     const source = (body.path ?? rootPath).trim();
     if (!source) return reply.code(400).send({ error: "rootPath not set" });
-    const stats = await importFromDir(kw, source);
+    const stats = await importFromDir(kw, source, {
+      noteChanged: (note) => service?.reindexNote(note),
+      taskChanged: (task) => service?.reindexTask(task)
+    });
     return stats;
   });
 }
diff --git a/packages/server-local/src/modules/knowledge/service.ts b/packages/server-local/src/modules/knowledge/service.ts
index 8ad8e79..eaea562 100644
--- a/packages/server-local/src/modules/knowledge/service.ts
+++ b/packages/server-local/src/modules/knowledge/service.ts
@@ -9,6 +9,7 @@ export interface EmbeddingConfig {
   baseUrl?: string;
   apiKey?: string;
   model?: string;
+  apiKeySource?: "keychain" | "env" | "legacy" | "none";
 }
 
 export interface EmbeddingCallOptions {
@@ -62,6 +63,15 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
   }
 
   let draining = false;
+  let retryTimer: NodeJS.Timeout | null = null;
+  function scheduleRetry(): void {
+    if (retryTimer) return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void drainEmbeddingQueue();
+    }, 60_000);
+    retryTimer.unref();
+  }
   /**
    * Consume pending/stale chunks: embed in batches (with content-hash cache
    * reuse), write vectors into vec0, mark indexed/failed. Single-flight via the
@@ -81,7 +91,7 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
         const cached: Array<{ chunk: (typeof pending)[number]; emb: { vector: number[]; dimensions: number } }> = [];
         const need: Array<{ chunk: (typeof pending)[number]; idx: number }> = [];
         for (const chunk of pending) {
-          const hit = store.getCachedEmbedding(chunk.contentHash);
+          const hit = store.getCachedEmbedding(chunk.contentHash, model);
           if (hit) cached.push({ chunk, emb: hit });
           else need.push({ chunk, idx: need.length });
         }
@@ -101,13 +111,14 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
                 store.markChunkFailed(n.chunk.id, "embedding dimension mismatch");
                 continue;
               }
-              store.putVecChunk(n.chunk.id, v);
+              store.putVecChunk(n.chunk.id, n.chunk.projectId, v);
               store.putCachedEmbedding(n.chunk.contentHash, v, model, dim);
               store.markChunkIndexed(n.chunk.id, model, dim);
             }
           } catch (error) {
             const msg = error instanceof Error ? error.message : "embedding failed";
             for (const n of need) store.markChunkFailed(n.chunk.id, msg);
+            scheduleRetry();
             break; // avoid tight retry loop; next write/reindex re-triggers
           }
         }
@@ -115,7 +126,7 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
         for (const c of cached) {
           if (dim === null) dim = c.emb.dimensions;
           if (!store.ensureVecTable(dim)) break;
-          store.putVecChunk(c.chunk.id, c.emb.vector);
+          store.putVecChunk(c.chunk.id, c.chunk.projectId, c.emb.vector);
           store.markChunkIndexed(c.chunk.id, model, dim);
         }
       }
@@ -153,7 +164,7 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
         if (!queryVec) return fts;
         const knn = store.searchKnn(queryVec, limit, projectId);
         if (!knn.length) return fts;
-        return fuseRrf(fts, knn);
+        return fuseRrf(fts, knn).slice(0, Math.max(1, Math.min(limit, 50)));
       } catch {
         return fts;
       }
@@ -163,6 +174,10 @@ export function createKnowledgeService(store: KnowledgeStore, options: Knowledge
       return store.getIndexStatus(providerConfigured());
     },
 
+    getChunkContents(chunkIds: string[]): Map<string, string> {
+      return store.getChunkContents(chunkIds);
+    },
+
     markStale(embeddingModel?: string): void {
       store.markStale(embeddingModel);
       void drainEmbeddingQueue();
diff --git a/packages/server-local/src/tests/app.test.ts b/packages/server-local/src/tests/app.test.ts
index 8f495e8..0cfb350 100644
--- a/packages/server-local/src/tests/app.test.ts
+++ b/packages/server-local/src/tests/app.test.ts
@@ -1,4 +1,4 @@
-import { createDatabase } from "@neo-companion/db";
+import { createDatabase, getAppConfig, type NeoDatabase } from "@neo-companion/db";
 import type { ChatMessage } from "@neo-companion/shared";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { WebSocket } from "ws";
@@ -7,10 +7,13 @@ import type { AddressInfo } from "node:net";
 import { createApp } from "../app";
 
 let app: FastifyInstance;
+let database: NeoDatabase;
 
 beforeEach(async () => {
+  database = createDatabase(":memory:");
   app = await createApp({
-    database: createDatabase(":memory:"),
+    authToken: "test-token",
+    database,
     startBackground: false,
     aiStream: async function* (_messages: ChatMessage[]) {
       yield "你好，";
@@ -19,6 +22,13 @@ beforeEach(async () => {
     ttsSpeak: async () => ({ audioUrl: "data:audio/mp3;base64,AA==", format: "mp3", provider: "mimo", cached: false }),
     weather: async () => ({ city: "Beijing", temperatureC: 20, precipitationChance: 0, text: "北京现在约 20°C。" })
   });
+  const rawInject = app.inject.bind(app);
+  app.inject = ((options: any) => rawInject(
+    typeof options === "string" ? options : {
+      ...options,
+      headers: { authorization: "Bearer test-token", ...options.headers }
+    }
+  )) as typeof app.inject;
   await app.listen({ port: 0, host: "127.0.0.1" });
 });
 
@@ -27,6 +37,19 @@ afterEach(async () => {
 });
 
 describe("server app", () => {
+  it("persists root path but never persists a new embedding secret", async () => {
+    await app.inject({ method: "PUT", url: "/api/knowledge/root-path", payload: { path: "D:/notes" } });
+    expect((await app.inject({ method: "GET", url: "/api/knowledge/root-path" })).json()).toEqual({ path: "D:/notes" });
+
+    await app.inject({
+      method: "PUT",
+      url: "/api/knowledge/embedding-config",
+      payload: { provider: "openai", model: "embed-model", apiKey: "secret-value", apiKeySource: "keychain" }
+    });
+    expect(getAppConfig(database, "embedding")).not.toContain("secret-value");
+    const status = (await app.inject({ method: "GET", url: "/api/knowledge/embedding-config" })).json();
+    expect(status.apiKeySource).toBe("keychain");
+  });
   it("serves health and task CRUD", async () => {
     const health = await app.inject({ method: "GET", url: "/health" });
     expect(health.statusCode).toBe(200);
@@ -51,7 +74,7 @@ describe("server app", () => {
   it("streams AI chunks through websocket and returns final text", async () => {
     const received: string[] = [];
     const address = app.server.address() as AddressInfo;
-    const ws = new WebSocket(`ws://127.0.0.1:${address.port}/ws`);
+    const ws = new WebSocket(`ws://127.0.0.1:${address.port}/ws`, ["neo-companion", "auth.test-token"]);
     await new Promise<void>((resolve) => ws.once("open", () => resolve()));
     ws.on("message", (data: Buffer) => {
       const message = JSON.parse(data.toString()) as { type: string; payload: { chunk?: string } };
diff --git a/packages/server-local/src/tests/auth.test.ts b/packages/server-local/src/tests/auth.test.ts
new file mode 100644
index 0000000..6b27d65
--- /dev/null
+++ b/packages/server-local/src/tests/auth.test.ts
@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp } from "../app";
+import { createDatabase, getAppConfig, setAppConfig } from "@neo-companion/db";
+
+describe("sidecar authentication", () => {
+  let app: Awaited<ReturnType<typeof createApp>> | null = null;
+
+  afterEach(async () => {
+    await app?.close();
+    app = null;
+  });
+
+  it("requires APP_AUTH_TOKEN", async () => {
+    const previous = process.env.APP_AUTH_TOKEN;
+    delete process.env.APP_AUTH_TOKEN;
+    await expect(createApp({ startBackground: false })).rejects.toThrow("APP_AUTH_TOKEN is required");
+    if (previous) process.env.APP_AUTH_TOKEN = previous;
+  });
+
+  it("rejects missing and invalid bearer tokens", async () => {
+    app = await createApp({ authToken: "secret", startBackground: false });
+    expect((await app.inject({ method: "GET", url: "/health" })).statusCode).toBe(401);
+    expect((await app.inject({ method: "GET", url: "/health", headers: { authorization: "Bearer wrong" } })).statusCode).toBe(401);
+  });
+
+  it("accepts a valid token and rejects untrusted origin or host", async () => {
+    app = await createApp({ authToken: "secret", startBackground: false });
+    const authorization = "Bearer secret";
+    expect((await app.inject({ method: "GET", url: "/health", headers: { authorization } })).statusCode).toBe(200);
+    expect((await app.inject({ method: "GET", url: "/health", headers: { authorization, origin: "https://evil.example" } })).statusCode).toBe(403);
+    expect((await app.inject({ method: "GET", url: "/health", headers: { authorization, host: "evil.example" } })).statusCode).toBe(403);
+  });
+
+  it("keeps a legacy secret until the authenticated client confirms migration", async () => {
+    const database = createDatabase(":memory:");
+    setAppConfig(database, "embedding", JSON.stringify({ provider: "openai", model: "m", apiKey: "legacy-secret" }));
+    app = await createApp({ database, authToken: "secret", startBackground: false });
+    const headers = { authorization: "Bearer secret" };
+    const claimed = await app.inject({ method: "POST", url: "/api/knowledge/embedding-config/legacy-secret/claim", headers });
+    expect(claimed.json()).toEqual({ apiKey: "legacy-secret" });
+    expect(getAppConfig(database, "embedding")).toContain("legacy-secret");
+    await app.inject({ method: "DELETE", url: "/api/knowledge/embedding-config/legacy-secret", headers });
+    expect(getAppConfig(database, "embedding")).not.toContain("legacy-secret");
+  });
+});
diff --git a/packages/server-local/src/tests/hook.test.ts b/packages/server-local/src/tests/hook.test.ts
index 4523691..2cbf9c8 100644
--- a/packages/server-local/src/tests/hook.test.ts
+++ b/packages/server-local/src/tests/hook.test.ts
@@ -11,9 +11,17 @@ let baseUrl: string;
 
 beforeEach(async () => {
   app = await createApp({
+    authToken: "test-token",
     database: createDatabase(":memory:"),
     startBackground: false,
   });
+  const rawInject = app.inject.bind(app);
+  app.inject = ((options: any) => rawInject(
+    typeof options === "string" ? options : {
+      ...options,
+      headers: { authorization: "Bearer test-token", ...options.headers }
+    }
+  )) as typeof app.inject;
   await app.listen({ port: 0, host: "127.0.0.1" });
   const address = app.server.address() as AddressInfo;
   baseUrl = `http://127.0.0.1:${address.port}`;
@@ -26,7 +34,7 @@ afterEach(async () => {
 function connectTestWs(): Promise<{ ws: WebSocket; messages: unknown[]; close: () => void }> {
   return new Promise((resolve) => {
     const address = app.server.address() as AddressInfo;
-    const ws = new WebSocket(`ws://127.0.0.1:${address.port}/ws`);
+    const ws = new WebSocket(`ws://127.0.0.1:${address.port}/ws`, ["neo-companion", "auth.test-token"]);
     const messages: unknown[] = [];
     ws.on("message", (data: Buffer) => {
       messages.push(JSON.parse(data.toString()));
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index ff3c5e5..4451687 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -226,6 +226,8 @@ export interface IndexStatus {
   pending: number;
   failed: number;
   stale: number;
+  /** Failed chunks currently eligible for automatic retry. */
+  retrying: number;
   providerConfigured: boolean;
   vectorExtensionAvailable: boolean;
   /** sqlite-vec version when loaded; absent when not loaded. */
diff --git a/scripts/dev.mjs b/scripts/dev.mjs
new file mode 100644
index 0000000..c43a2c8
--- /dev/null
+++ b/scripts/dev.mjs
@@ -0,0 +1,26 @@
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+
+const desktopTarget = process.argv[2] === "tauri" ? "dev:tauri" : "dev:web";
+const token = randomBytes(32).toString("base64url");
+const env = { ...process.env, APP_AUTH_TOKEN: token, VITE_NEO_AUTH_TOKEN: token };
+const children = [
+  spawn("pnpm --filter @neo-companion/server-local dev", { stdio: "inherit", shell: true, env }),
+  spawn(`pnpm --filter @neo-companion/desktop ${desktopTarget}`, { stdio: "inherit", shell: true, env })
+];
+
+let stopping = false;
+function stop(code = 0) {
+  if (stopping) return;
+  stopping = true;
+  for (const child of children) child.kill();
+  process.exit(code);
+}
+
+for (const child of children) {
+  child.on("exit", (code, signal) => {
+    if (!stopping) stop(signal ? 1 : (code ?? 1));
+  });
+}
+process.on("SIGINT", () => stop(0));
+process.on("SIGTERM", () => stop(0));

From 27ba1b374274e92f6476142d751f2c0351dd7dce Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sun, 21 Jun 2026 20:53:44 +0800
Subject: [PATCH 6/6] docs(knowledge): align security and retrieval status

---
 CLAUDE.md            |  3 ++-
 README.md            |  2 +-
 docs/API.md          | 12 +++++++++++-
 docs/ARCHITECTURE.md |  2 +-
 4 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index b297274..d85c754 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,7 +44,8 @@ Vue 3 Frontend
 
 ## Current State Notes
 
-- The **knowledge workspace** UI exists but is backed by a front-end mock (`useKnowledgeMock.ts`). The real SQLite-backed API, FTS5 full-text search, and `sqlite-vec` vector retrieval described in the architecture doc are **planned for v2**, not yet implemented.
+- The **knowledge workspace** is backed by SQLite CRUD, transactional FTS5 indexing, optional `sqlite-vec` hybrid retrieval, file mirror import/export, and cited AI Ask/Chat flows. `useKnowledgeMock.ts` remains only as a preview fallback when the authenticated sidecar is unavailable.
+- Every Sidecar REST and WebSocket request requires the shared `APP_AUTH_TOKEN`; use the root `pnpm dev` / `pnpm dev:tauri` launchers so development processes receive the same ephemeral token.
 - The codebase still uses `pet`/`companion` identifiers in many places (`components/pet/`, `usePetState.ts`, `pet.css`). The product-facing terminology is **assistant**, but a full code-level rename is out of scope for documentation-only work.
 - The sidecar runs on `http://127.0.0.1:10103` by default (configurable via `NEO_SERVER_PORT`).
 
diff --git a/README.md b/README.md
index aec7463..5621432 100644
--- a/README.md
+++ b/README.md
@@ -148,7 +148,7 @@ NeoCompanion 的能力由浅入深分为四层：
 | 数据库 | **SQLite** (Drizzle ORM) |
 | AI | 聊天模型适配器 + OpenAI-compatible Embedding Adapter |
 
-架构核心：Tauri (Rust) 提供系统级能力 → Fastify (TypeScript) 处理业务逻辑与 AI 调度 → Vue 提供 UI → SQLite 统一存储业务数据。v2 计划引入 FTS5 全文索引与 sqlite-vec 向量索引，当前版本尚未实现。
+架构核心：Tauri (Rust) 提供系统级能力与系统钥匙链 → Fastify (TypeScript) 处理业务逻辑、知识索引与 AI 调度 → Vue 提供 UI → SQLite 统一存储业务数据。知识工作空间已接入 FTS5 全文索引、可选 sqlite-vec 混合检索、文件镜像与带来源的 RAG。
 
 详见 [**系统架构设计**](docs/ARCHITECTURE.md)。
 
diff --git a/docs/API.md b/docs/API.md
index 6483071..bdffdad 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -8,6 +8,16 @@ NeoCompanion sidecar 是一个本地 Fastify 应用，为 Vue 前端提供 REST
 
 所有端点默认返回 JSON，除非另有说明。
 
+## 鉴权
+
+Sidecar 启动时必须配置 `APP_AUTH_TOKEN`。所有 REST（包括 `/health` 与 Hook API）使用：
+
+```http
+Authorization: Bearer <APP_AUTH_TOKEN>
+```
+
+WebSocket 通过 `Sec-WebSocket-Protocol` 同时发送 `neo-companion` 与 `auth.<APP_AUTH_TOKEN>`。缺少或错误 token 返回 `401`；非本地 Host 或不受信任 Origin 返回 `403`。根目录开发命令会为桌面端与 Sidecar 自动生成并注入同一个临时 token。
+
 ---
 
 ## 健康检查
@@ -389,6 +399,6 @@ sidecar 会广播以下消息类型：
 
 ## 说明
 
-- 知识工作空间后端端点（`/api/knowledge/*`）**已实现**：项目/笔记/看板列/任务的 CRUD、`GET /api/knowledge/search`（FTS5 + sqlite-vec 混合检索，参数 `q`/`projectId`/`limit`）、`GET /api/knowledge/index-status`、`POST /api/knowledge/reindex`、`GET/PUT /api/knowledge/embedding-config`（apiKey 不回显，落库持久化）、`GET/PUT /api/knowledge/root-path`、`POST /api/knowledge/mirror/export|import`。前端通过 `useKnowledgeApi` 接入，API 不可用时降级 mock 并显示 banner。详见 `docs/ARCHITECTURE.md` §9.3、§9.4。
+- 知识工作空间后端端点（`/api/knowledge/*`）**已实现**：项目/笔记/看板列/任务的 CRUD、`GET /api/knowledge/search`（FTS5 + sqlite-vec 混合检索，参数 `q`/`projectId`/`limit`）、`GET /api/knowledge/index-status`、`POST /api/knowledge/reindex`、`GET/PUT /api/knowledge/embedding-config`、`GET/PUT /api/knowledge/root-path`、`POST /api/knowledge/mirror/export|import`。Embedding API Key 只在系统钥匙链和 Sidecar 进程内存中存在；旧版 SQLite 明文密钥通过认证端点一次性迁移后删除。前端通过 `useKnowledgeApi` 接入，API 不可用时降级 mock 并显示 banner。详见 `docs/ARCHITECTURE.md` §9.3、§9.4。
 - 当前 v1 `/api/tasks` 使用 `status: "open" | "done"`。v2 知识工作空间用独立表 `knowledge_tasks`（四态 `"todo" | "doing" | "done" | "archived"`），与看板列绑定；两表统一为延后决策。
 - 错误响应格式通常为 `{ "error": "message" }`，除非另有说明。
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 28ff1f3..919ebf7 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1287,7 +1287,7 @@ Chat 模式下每条笔记/任务可设 `full`（整篇正文）/ `summary`（
 
 #### 9.4.6 Embedding 配置持久化
 
-Embedding provider 配置（provider/baseUrl/model/apiKey）持久化到 `app_config` 表，sidecar 重启不丢失。apiKey 双通道：PUT 传 `apiKey` 则明文落库（仅存本地 db 文件，不进 git，GET 不回显）；传 `apiKey:null` 则清空落库值、运行时回退环境变量 `EMBEDDING_API_KEY`。GET 端点返回 `apiKeySource: "stored" | "env" | "none"` 供前端提示。
+Embedding provider 的非敏感配置（provider/baseUrl/model）持久化到 `app_config` 表。API Key 由 Tauri 写入系统钥匙链，桌面端启动后通过认证通道回填到 Sidecar 进程内存；也可由 `EMBEDDING_API_KEY` 环境变量提供。旧版 SQLite 明文密钥使用 claim → 写入钥匙链 → clear 两阶段流程迁移，钥匙链写入失败时不删除旧值。GET 端点返回 `apiKeySource: "keychain" | "env" | "legacy" | "none"`。
 
 ### 9.5 Data Location