From cbb7582bba56504d9b9aa6790eb69378bf0fdd1b Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 15:42:42 +0800
Subject: [PATCH 1/5] =?UTF-8?q?feat(knowledge):=20v3.3=20=E7=9F=A5?=
 =?UTF-8?q?=E8=AF=86=E5=B7=A5=E4=BD=9C=E7=A9=BA=E9=97=B4=20UI=20=E9=87=8D?=
 =?UTF-8?q?=E6=9E=84=E4=B8=8E=E6=96=87=E6=A1=A3=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 重构知识组件：拆分为 ProjectBrowser/ProjectWorkspace/KnowledgeNotesPanel/
  KnowledgeBoardPanel/KnowledgeTasksPanel，新增 BreadcrumbNav/MarkdownPreview/
  BacklinksPanel/BoardTaskCard/ProjectCard/QuickCreateBar/ThemeToggle
- 删除旧版 BoardCard/BoardPane/KnowledgeTopbar/NoteList/NotePreview/NotesPane/
  ProjectSidebar/TasksPane
- 设置页知识库区接入可配置根目录选择器（knowledgeRootPath）
- 更新 tauri 能力与依赖配置
- 同步更新 ARCHITECTURE/API/PRD/TESTING/GLOSSARY/TODO_INVENTORY/具体能力构思 文档
---
 apps/desktop/package.json                     |    1 +
 apps/desktop/src-tauri/Cargo.toml             |    1 +
 .../src-tauri/capabilities/default.json       |    1 +
 apps/desktop/src-tauri/src/lib.rs             |    1 +
 apps/desktop/src/App.vue                      |    9 +-
 .../components/knowledge/BacklinksPanel.vue   |   53 +
 .../src/components/knowledge/BoardCard.vue    |   24 -
 .../src/components/knowledge/BoardColumn.vue  |  159 ++-
 .../src/components/knowledge/BoardPane.vue    |   27 -
 .../components/knowledge/BoardTaskCard.vue    |   56 +
 .../components/knowledge/BreadcrumbNav.vue    |   37 +
 .../knowledge/KnowledgeBoardPanel.vue         |   68 +
 .../knowledge/KnowledgeNotesPanel.vue         |  153 +++
 .../knowledge/KnowledgeTasksPanel.vue         |   95 ++
 .../components/knowledge/KnowledgeTopbar.vue  |   62 -
 .../components/knowledge/MarkdownPreview.vue  |   75 ++
 .../src/components/knowledge/NoteList.vue     |   32 -
 .../src/components/knowledge/NotePreview.vue  |   52 -
 .../src/components/knowledge/NotesPane.vue    |   27 -
 .../components/knowledge/ProjectBrowser.vue   |   53 +
 .../src/components/knowledge/ProjectCard.vue  |   89 ++
 .../components/knowledge/ProjectSidebar.vue   |   51 -
 .../components/knowledge/ProjectWorkspace.vue |  106 ++
 .../components/knowledge/QuickCreateBar.vue   |   73 ++
 .../src/components/knowledge/TasksPane.vue    |   37 -
 .../src/components/knowledge/ThemeToggle.vue  |   46 +
 .../settings/sections/KnowledgeSection.vue    |   47 +-
 apps/desktop/src/composables/useSettings.ts   |   20 +-
 apps/desktop/src/composables/useTheme.ts      |   60 +
 apps/desktop/src/styles/knowledge.css         | 1142 ++++++++++++-----
 apps/desktop/src/styles/settings.css          |   16 +
 apps/desktop/src/views/SettingsView.vue       |    8 +-
 docs/API.md                                   |    3 +-
 docs/ARCHITECTURE.md                          |   26 +-
 docs/GLOSSARY.md                              |    3 +
 docs/PRD_overview.md                          |    8 +-
 docs/TESTING.md                               |   32 +
 docs/TODO_INVENTORY.md                        |   16 +-
 ...75\345\212\233\346\236\204\346\200\235.md" |   12 +-
 pnpm-lock.yaml                                |   10 +
 40 files changed, 2128 insertions(+), 663 deletions(-)
 create mode 100644 apps/desktop/src/components/knowledge/BacklinksPanel.vue
 delete mode 100644 apps/desktop/src/components/knowledge/BoardCard.vue
 delete mode 100644 apps/desktop/src/components/knowledge/BoardPane.vue
 create mode 100644 apps/desktop/src/components/knowledge/BoardTaskCard.vue
 create mode 100644 apps/desktop/src/components/knowledge/BreadcrumbNav.vue
 create mode 100644 apps/desktop/src/components/knowledge/KnowledgeBoardPanel.vue
 create mode 100644 apps/desktop/src/components/knowledge/KnowledgeNotesPanel.vue
 create mode 100644 apps/desktop/src/components/knowledge/KnowledgeTasksPanel.vue
 delete mode 100644 apps/desktop/src/components/knowledge/KnowledgeTopbar.vue
 create mode 100644 apps/desktop/src/components/knowledge/MarkdownPreview.vue
 delete mode 100644 apps/desktop/src/components/knowledge/NoteList.vue
 delete mode 100644 apps/desktop/src/components/knowledge/NotePreview.vue
 delete mode 100644 apps/desktop/src/components/knowledge/NotesPane.vue
 create mode 100644 apps/desktop/src/components/knowledge/ProjectBrowser.vue
 create mode 100644 apps/desktop/src/components/knowledge/ProjectCard.vue
 delete mode 100644 apps/desktop/src/components/knowledge/ProjectSidebar.vue
 create mode 100644 apps/desktop/src/components/knowledge/ProjectWorkspace.vue
 create mode 100644 apps/desktop/src/components/knowledge/QuickCreateBar.vue
 delete mode 100644 apps/desktop/src/components/knowledge/TasksPane.vue
 create mode 100644 apps/desktop/src/components/knowledge/ThemeToggle.vue
 create mode 100644 apps/desktop/src/composables/useTheme.ts

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index a2158fc..d857e75 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -13,6 +13,7 @@
   "dependencies": {
     "@neo-companion/shared": "workspace:*",
     "@tauri-apps/api": "^2.9.0",
+    "@tauri-apps/plugin-dialog": "^2.2.0",
     "@tiptap/core": "3.26.0",
     "@tiptap/extension-heading": "3.26.0",
     "@tiptap/extension-list": "3.26.0",
diff --git a/apps/desktop/src-tauri/Cargo.toml b/apps/desktop/src-tauri/Cargo.toml
index d0e7c53..d54f36d 100644
--- a/apps/desktop/src-tauri/Cargo.toml
+++ b/apps/desktop/src-tauri/Cargo.toml
@@ -15,6 +15,7 @@ tauri-build = { version = "2", features = [] }
 [dependencies]
 tauri = { version = "2", features = ["tray-icon"] }
 tauri-plugin-opener = "2"
+tauri-plugin-dialog = "2"
 tauri-plugin-window-state = "2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
diff --git a/apps/desktop/src-tauri/capabilities/default.json b/apps/desktop/src-tauri/capabilities/default.json
index f76d964..18538a6 100644
--- a/apps/desktop/src-tauri/capabilities/default.json
+++ b/apps/desktop/src-tauri/capabilities/default.json
@@ -13,6 +13,7 @@
     "core:window:allow-show",
     "core:window:allow-start-dragging",
     "opener:default",
+    "dialog:default",
     "window-state:default"
   ]
 }
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index adb99d8..482f326 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -5,6 +5,7 @@ use tauri::{LogicalSize, Manager, Size, WindowEvent};
 pub fn run() {
     let builder = tauri::Builder::default()
         .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_dialog::init())
         .plugin(tauri_plugin_window_state::Builder::default().build());
 
     #[cfg(target_os = "windows")]
diff --git a/apps/desktop/src/App.vue b/apps/desktop/src/App.vue
index ed65e78..0f231f2 100644
--- a/apps/desktop/src/App.vue
+++ b/apps/desktop/src/App.vue
@@ -35,6 +35,7 @@ import WallpaperView from "./views/WallpaperView.vue";
 import SettingsView from "./views/SettingsView.vue";
 import KnowledgeView from "./views/KnowledgeView.vue";
 import { useSettings } from "./composables/useSettings";
+import { useTheme } from "./composables/useTheme";
 
 const viewMode = new URLSearchParams(window.location.search).get("view");
 const isPetView = viewMode === "pet";
@@ -67,7 +68,7 @@ const weather = ref<WeatherSummary | null>(null);
 const lastWindow = ref<WindowSnapshot | null>(null);
 const serverReady = ref(false);
 const errorText = ref("");
-const isPanelDark = ref(false);
+const theme = useTheme();
 const activePanelPage = ref<PanelPage>("focus");
 const wallpaperVisible = ref(true);
 const focusStartTime = ref("");
@@ -240,7 +241,7 @@ function onTaskToggle(task: typeof tasks.tasks.value[0]) {
 }
 
 function togglePanelTheme() {
-  isPanelDark.value = !isPanelDark.value;
+  theme.toggleTheme();
 }
 
 function setActivePanelPage(pageId: string) {
@@ -305,7 +306,7 @@ function toggleImmersive() {
 
   <KnowledgeView v-else-if="isKnowledgeView" />
 
-  <main v-else class="panel-shell" :class="{ 'dark-mode': isPanelDark }">
+  <main v-else class="panel-shell" :class="{ 'dark-mode': theme.isDark.value }">
     <!-- Noise texture filter -->
     <svg width="0" height="0" style="position: absolute">
       <filter id="panel-noise-filter">
@@ -317,7 +318,7 @@ function toggleImmersive() {
     <!-- Top navigation -->
     <TopNav
       :pet-state="pet.petState.value"
-      :is-dark="isPanelDark"
+      :is-dark="theme.isDark.value"
       @toggle-theme="togglePanelTheme"
       @open-settings="openSettings"
     />
diff --git a/apps/desktop/src/components/knowledge/BacklinksPanel.vue b/apps/desktop/src/components/knowledge/BacklinksPanel.vue
new file mode 100644
index 0000000..bb0b1e0
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/BacklinksPanel.vue
@@ -0,0 +1,53 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+  entityId: string | null;
+  entityType: "note" | "task";
+}>();
+
+const emit = defineEmits<{
+  navigate: [sourceTitle: string];
+}>();
+
+const backlinks = computed(() => {
+  if (!props.entityId) return [];
+  return props.workspace.backlinksFor(props.entityId);
+});
+
+function sourceTitle(link: ReturnType<typeof props.workspace.backlinksFor>[number]): string {
+  if (link.sourceType === "note") {
+    const found = props.workspace.allNotes.value.find((n) => n.id === link.sourceId);
+    return found?.title ?? link.sourceId;
+  }
+  const found = props.workspace.allTasks.value.find((t) => t.id === link.sourceId);
+  return found?.title ?? link.sourceId;
+}
+
+function follow(link: ReturnType<typeof props.workspace.backlinksFor>[number]): void {
+  emit("navigate", sourceTitle(link));
+}
+</script>
+
+<template>
+  <aside v-if="backlinks.length > 0" class="backlinks-panel">
+    <header class="backlinks-header">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" />
+        <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" />
+      </svg>
+      引用此{{ entityType === "note" ? "笔记" : "任务" }}
+    </header>
+
+    <ul class="backlinks-list">
+      <li v-for="link in backlinks" :key="`${link.sourceId}-${link.targetId}`" class="backlinks-item">
+        <button type="button" @click="follow(link)">
+          <span class="backlinks-type">{{ link.sourceType === "note" ? "笔记" : "任务" }}</span>
+          <span class="backlinks-title">{{ sourceTitle(link) }}</span>
+        </button>
+      </li>
+    </ul>
+  </aside>
+</template>
diff --git a/apps/desktop/src/components/knowledge/BoardCard.vue b/apps/desktop/src/components/knowledge/BoardCard.vue
deleted file mode 100644
index 58ec4f2..0000000
--- a/apps/desktop/src/components/knowledge/BoardCard.vue
+++ /dev/null
@@ -1,24 +0,0 @@
-<script setup lang="ts">
-import type { KnowledgeTask } from "../../composables/useKnowledgeMock";
-
-defineProps<{
-  task: KnowledgeTask;
-}>();
-</script>
-
-<template>
-  <article class="knowledge-board-card" :data-status="task.status">
-    <div class="title">{{ task.title }}</div>
-    <div v-if="task.tags.length || task.linkedNoteId" class="meta">
-      <span v-for="tag in task.tags" :key="tag" class="tag">{{ tag }}</span>
-      <span v-if="task.linkedNoteId" class="linked" title="关联笔记">
-        <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round">
-          <path d="M9 17H7A5 5 0 0 1 7 7h2" />
-          <path d="M15 7h2a5 5 0 0 1 0 10h-2" />
-          <path d="M8 12h8" />
-        </svg>
-        笔记
-      </span>
-    </div>
-  </article>
-</template>
diff --git a/apps/desktop/src/components/knowledge/BoardColumn.vue b/apps/desktop/src/components/knowledge/BoardColumn.vue
index 225a0a1..460107b 100644
--- a/apps/desktop/src/components/knowledge/BoardColumn.vue
+++ b/apps/desktop/src/components/knowledge/BoardColumn.vue
@@ -1,22 +1,159 @@
 <script setup lang="ts">
-import type { BoardColumnMock, KnowledgeTask } from "../../composables/useKnowledgeMock";
-import BoardCard from "./BoardCard.vue";
+import { ref, computed } from "vue";
+import type { BoardColumn, KnowledgeTask } from "../../composables/useKnowledgeMock";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+import BoardTaskCard from "./BoardTaskCard.vue";
 
-defineProps<{
-  column: BoardColumnMock;
+const props = defineProps<{
+  column: BoardColumn;
   tasks: KnowledgeTask[];
+  workspace: KnowledgeWorkspaceState;
+  isDropTarget: boolean;
+  draggingTaskId: string | null;
 }>();
+
+const emit = defineEmits<{
+  dragStart: [taskId: string];
+  dragEnd: [];
+  dropTask: [taskId: string, columnId: string, index: number];
+  dragHover: [columnId: string];
+  dragLeave: [];
+}>();
+
+const newTaskTitle = ref("");
+const isCreating = ref(false);
+const columnRef = ref<HTMLElement | null>(null);
+const dropIndex = ref<number | null>(null);
+
+// 拖拽落点对应的卡片 id（在该卡片上方插入）；落点在列末尾时为 null 且 dropAtEnd=true。
+const visibleTasks = computed(() => props.tasks.filter((t) => t.id !== props.draggingTaskId));
+const dropTargetId = computed<string | null>(() => {
+  if (dropIndex.value === null) return null;
+  const list = visibleTasks.value;
+  if (dropIndex.value >= list.length) return null;
+  return list[dropIndex.value].id;
+});
+const dropAtEnd = computed(
+  () => dropIndex.value !== null && dropIndex.value >= visibleTasks.value.length,
+);
+
+function onDragEnter(event: DragEvent): void {
+  event.preventDefault();
+  if (event.dataTransfer) event.dataTransfer.dropEffect = "move";
+}
+
+function onDragOver(event: DragEvent): void {
+  event.preventDefault();
+  if (event.dataTransfer) event.dataTransfer.dropEffect = "move";
+  emit("dragHover", props.column.id);
+  dropIndex.value = computeDropIndex(event);
+}
+
+function onDragLeave(event: DragEvent): void {
+  if (!columnRef.value) return;
+  const related = event.relatedTarget as Node | null;
+  if (related && columnRef.value.contains(related)) return;
+  dropIndex.value = null;
+  emit("dragLeave");
+}
+
+function onDrop(event: DragEvent): void {
+  event.preventDefault();
+  const taskId =
+    event.dataTransfer?.getData("application/x-neo-task") || event.dataTransfer?.getData("text/plain");
+  const index = dropIndex.value ?? props.tasks.length;
+  dropIndex.value = null;
+  if (!taskId) return;
+  emit("dropTask", taskId, props.column.id, index);
+}
+
+function computeDropIndex(event: DragEvent): number {
+  if (!columnRef.value) return props.tasks.length;
+  const cards = Array.from(columnRef.value.querySelectorAll(".board-task-card")).filter(
+    (card) => card.getAttribute("data-task-id") !== props.draggingTaskId,
+  );
+  if (cards.length === 0) return 0;
+  const rect = columnRef.value.getBoundingClientRect();
+  const relativeY = event.clientY - rect.top;
+  for (let i = 0; i < cards.length; i += 1) {
+    const cardRect = cards[i].getBoundingClientRect();
+    const cardMiddle = cardRect.top + cardRect.height / 2 - rect.top;
+    if (relativeY < cardMiddle) return i;
+  }
+  return cards.length;
+}
+
+function startCreate(): void {
+  isCreating.value = true;
+  newTaskTitle.value = "";
+}
+
+function confirmCreate(): void {
+  const title = newTaskTitle.value.trim();
+  if (!title) return;
+  props.workspace.createTask(props.column.id, title);
+  newTaskTitle.value = "";
+  isCreating.value = false;
+}
+
+function cancelCreate(): void {
+  isCreating.value = false;
+  newTaskTitle.value = "";
+}
 </script>
 
 <template>
-  <section class="knowledge-board-column" :data-status="column.status">
-    <header>
-      <span class="title">{{ column.title }}</span>
-      <span class="count">{{ tasks.length }}</span>
+  <section
+    ref="columnRef"
+    class="board-column"
+    :class="{ 'is-drop-target': isDropTarget }"
+    @dragenter="onDragEnter"
+    @dragover="onDragOver"
+    @dragleave="onDragLeave"
+    @drop="onDrop"
+  >
+    <header class="board-column-header">
+      <span class="board-column-title">{{ column.title }}</span>
+      <span class="board-column-count">{{ tasks.length }}</span>
     </header>
-    <div class="cards">
-      <BoardCard v-for="task in tasks" :key="task.id" :task="task" />
-      <div v-if="!tasks.length" class="empty">空</div>
+
+    <div class="board-column-cards">
+      <BoardTaskCard
+        v-for="task in tasks"
+        :key="task.id"
+        :task="task"
+        :workspace="workspace"
+        :is-dragging="draggingTaskId === task.id"
+        :is-drop-above="dropTargetId === task.id"
+        @dragstart="$emit('dragStart', task.id); $emit('dragHover', column.id)"
+        @dragend="$emit('dragEnd')"
+      />
+
+      <div v-if="tasks.length === 0" class="board-column-empty">
+        拖拽任务到此处
+      </div>
+
+      <div v-if="dropAtEnd" class="board-drop-line" aria-hidden="true" />
+    </div>
+
+    <div class="board-column-footer">
+      <button v-if="!isCreating" type="button" class="board-column-add" @click="startCreate">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+          <path d="M12 5v14M5 12h14" />
+        </svg>
+        添加任务
+      </button>
+
+      <div v-else class="board-column-create" @keydown.esc="cancelCreate">
+        <input
+          v-model="newTaskTitle"
+          type="text"
+          placeholder="任务标题"
+          autofocus
+          @keydown.enter="confirmCreate"
+        />
+        <button type="button" @click="confirmCreate">创建</button>
+      </div>
     </div>
   </section>
 </template>
diff --git a/apps/desktop/src/components/knowledge/BoardPane.vue b/apps/desktop/src/components/knowledge/BoardPane.vue
deleted file mode 100644
index d381c35..0000000
--- a/apps/desktop/src/components/knowledge/BoardPane.vue
+++ /dev/null
@@ -1,27 +0,0 @@
-<script setup lang="ts">
-import { computed } from "vue";
-import type { BoardColumnMock, KnowledgeTask } from "../../composables/useKnowledgeMock";
-import BoardColumn from "./BoardColumn.vue";
-
-const props = defineProps<{
-  columns: BoardColumnMock[];
-  tasks: KnowledgeTask[];
-}>();
-
-const tasksByColumn = computed(() =>
-  Object.fromEntries(
-    props.columns.map((col) => [col.id, props.tasks.filter((t) => t.boardColumnId === col.id)]),
-  ) as Record<string, KnowledgeTask[]>,
-);
-</script>
-
-<template>
-  <div class="knowledge-board-pane">
-    <BoardColumn
-      v-for="column in columns"
-      :key="column.id"
-      :column="column"
-      :tasks="tasksByColumn[column.id] ?? []"
-    />
-  </div>
-</template>
diff --git a/apps/desktop/src/components/knowledge/BoardTaskCard.vue b/apps/desktop/src/components/knowledge/BoardTaskCard.vue
new file mode 100644
index 0000000..75d6808
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/BoardTaskCard.vue
@@ -0,0 +1,56 @@
+<script setup lang="ts">
+import type { KnowledgeTask } from "../../composables/useKnowledgeMock";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+
+const props = defineProps<{
+  task: KnowledgeTask;
+  workspace: KnowledgeWorkspaceState;
+  isDragging?: boolean;
+  isDropAbove?: boolean;
+}>();
+
+const emit = defineEmits<{
+  dragstart: [taskId: string];
+  dragend: [];
+}>();
+
+function onDragStart(event: DragEvent): void {
+  if (event.dataTransfer) {
+    event.dataTransfer.effectAllowed = "move";
+    event.dataTransfer.setData("text/plain", props.task.id);
+    event.dataTransfer.setData("application/x-neo-task", props.task.id);
+  }
+  emit("dragstart", props.task.id);
+}
+
+function linkedNoteTitle(): string {
+  if (!props.task.linkedNoteId) return "";
+  const note = props.workspace.allNotes.value.find((n) => n.id === props.task.linkedNoteId);
+  return note?.title ?? "";
+}
+</script>
+
+<template>
+  <article
+    class="board-task-card"
+    :class="{ 'is-dragging': isDragging, 'is-drop-above': isDropAbove }"
+    :data-status="task.status"
+    :data-task-id="task.id"
+    draggable="true"
+    @dragstart="onDragStart"
+    @dragend="emit('dragend')"
+  >
+    <h4 class="board-task-card-title">{{ task.title }}</h4>
+
+    <div v-if="task.tags.length > 0 || task.linkedNoteId" class="board-task-card-meta">
+      <span v-for="tag in task.tags" :key="tag" class="kw-tag">{{ tag }}</span>
+      <span v-if="task.linkedNoteId && linkedNoteTitle()" class="board-task-card-link">
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+          <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" />
+          <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" />
+        </svg>
+        {{ linkedNoteTitle() }}
+      </span>
+    </div>
+  </article>
+</template>
diff --git a/apps/desktop/src/components/knowledge/BreadcrumbNav.vue b/apps/desktop/src/components/knowledge/BreadcrumbNav.vue
new file mode 100644
index 0000000..9f82e8d
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/BreadcrumbNav.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import type { KnowledgeProject } from "../../composables/useKnowledgeMock";
+
+defineProps<{
+  path: KnowledgeProject[];
+}>();
+
+const emit = defineEmits<{
+  navigate: [id: string];
+  root: [];
+}>();
+</script>
+
+<template>
+  <nav class="knowledge-breadcrumb" aria-label="项目路径">
+    <button
+      type="button"
+      class="knowledge-breadcrumb-item"
+      :class="{ 'is-root': path.length === 0 }"
+      @click="emit('root')"
+    >
+      全部项目
+    </button>
+
+    <template v-for="(project, index) in path" :key="project.id">
+      <span class="knowledge-breadcrumb-separator" aria-hidden="true">/</span>
+      <button
+        type="button"
+        class="knowledge-breadcrumb-item"
+        :class="{ 'is-active': index === path.length - 1 }"
+        @click="emit('navigate', project.id)"
+      >
+        {{ project.title }}
+      </button>
+    </template>
+  </nav>
+</template>
diff --git a/apps/desktop/src/components/knowledge/KnowledgeBoardPanel.vue b/apps/desktop/src/components/knowledge/KnowledgeBoardPanel.vue
new file mode 100644
index 0000000..1f1388a
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/KnowledgeBoardPanel.vue
@@ -0,0 +1,68 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+import BoardColumn from "./BoardColumn.vue";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+}>();
+
+const hoverColumnId = ref<string | null>(null);
+const draggingTaskId = ref<string | null>(null);
+
+const columnsWithTasks = computed(() => {
+  return props.workspace.currentColumns.value.map((column) => ({
+    column,
+    tasks: props.workspace.currentTasks.value
+      .filter((t) => t.columnId === column.id)
+      .sort((a, b) => a.order - b.order),
+  }));
+});
+
+function handleDragStart(taskId: string): void {
+  draggingTaskId.value = taskId;
+}
+
+function handleDragEnd(): void {
+  draggingTaskId.value = null;
+  hoverColumnId.value = null;
+}
+
+function handleDrop(taskId: string, columnId: string, index: number): void {
+  props.workspace.moveTask(taskId, columnId, index);
+  handleDragEnd();
+}
+
+function handleDragHover(columnId: string): void {
+  hoverColumnId.value = columnId;
+}
+
+function handleDragLeave(): void {
+  hoverColumnId.value = null;
+}
+</script>
+
+<template>
+  <div class="knowledge-board-panel">
+    <div v-if="workspace.currentColumns.value.length === 0" class="knowledge-board-empty">
+      <p>该项目还没有看板列</p>
+    </div>
+
+    <div v-else class="knowledge-board-grid">
+      <BoardColumn
+        v-for="{ column, tasks } in columnsWithTasks"
+        :key="column.id"
+        :column="column"
+        :tasks="tasks"
+        :workspace="workspace"
+        :is-drop-target="hoverColumnId === column.id"
+        :dragging-task-id="draggingTaskId"
+        @drag-start="handleDragStart"
+        @drag-end="handleDragEnd"
+        @drop-task="handleDrop"
+        @drag-hover="handleDragHover"
+        @drag-leave="handleDragLeave"
+      />
+    </div>
+  </div>
+</template>
diff --git a/apps/desktop/src/components/knowledge/KnowledgeNotesPanel.vue b/apps/desktop/src/components/knowledge/KnowledgeNotesPanel.vue
new file mode 100644
index 0000000..7410582
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/KnowledgeNotesPanel.vue
@@ -0,0 +1,153 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+import type { KnowledgeNote } from "../../composables/useKnowledgeMock";
+import MarkdownEditor from "../markdown-editor/MarkdownEditor.vue";
+import MarkdownPreview from "./MarkdownPreview.vue";
+import BacklinksPanel from "./BacklinksPanel.vue";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+}>();
+
+const editing = ref(false);
+const newNoteTitle = ref("");
+const isCreating = ref(false);
+
+function selectNote(note: KnowledgeNote): void {
+  props.workspace.selectNote(note.id);
+  editing.value = false;
+}
+
+function toggleEditing(): void {
+  editing.value = !editing.value;
+}
+
+function updateBody(body: string): void {
+  const id = props.workspace.activeNote.value?.id;
+  if (!id) return;
+  props.workspace.updateNoteBody(id, body);
+}
+
+function startCreate(): void {
+  isCreating.value = true;
+  newNoteTitle.value = "";
+}
+
+function confirmCreate(): void {
+  const title = newNoteTitle.value.trim();
+  if (!title) return;
+  props.workspace.createNote(title);
+  newNoteTitle.value = "";
+  isCreating.value = false;
+  editing.value = true;
+}
+
+function cancelCreate(): void {
+  isCreating.value = false;
+  newNoteTitle.value = "";
+}
+
+function deleteActiveNote(): void {
+  const id = props.workspace.activeNote.value?.id;
+  if (!id) return;
+  props.workspace.deleteNote(id);
+}
+
+function followLink(label: string): void {
+  props.workspace.followLink(label);
+}
+</script>
+
+<template>
+  <div class="knowledge-notes-panel">
+    <aside class="knowledge-notes-list">
+      <header class="knowledge-notes-list-header">
+        <span class="knowledge-notes-count">{{ workspace.currentNotes.value.length }} 篇笔记</span>
+        <button type="button" class="knowledge-notes-add" @click="startCreate">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+            <path d="M12 5v14M5 12h14" />
+          </svg>
+          新笔记
+        </button>
+      </header>
+
+      <div v-if="isCreating" class="knowledge-notes-create">
+        <input
+          v-model="newNoteTitle"
+          type="text"
+          placeholder="笔记标题"
+          autofocus
+          @keydown.enter="confirmCreate"
+          @keydown.esc="cancelCreate"
+        />
+        <div class="knowledge-notes-create-actions">
+          <button type="button" class="primary" @click="confirmCreate">创建</button>
+          <button type="button" @click="cancelCreate">取消</button>
+        </div>
+      </div>
+
+      <button
+        v-for="note in workspace.currentNotes.value"
+        :key="note.id"
+        type="button"
+        class="knowledge-note-row"
+        :class="{ active: workspace.activeNote.value?.id === note.id }"
+        @click="selectNote(note)"
+      >
+        <span class="knowledge-note-row-title">{{ note.title }}</span>
+        <span class="knowledge-note-row-meta">{{ workspace.formatKwTime(note.updatedAt) }}</span>
+      </button>
+
+      <div v-if="workspace.currentNotes.value.length === 0 && !isCreating" class="knowledge-notes-empty">
+        <p>还没有笔记</p>
+        <button type="button" @click="startCreate">创建第一篇笔记</button>
+      </div>
+    </aside>
+
+    <div v-if="workspace.activeNote.value" class="knowledge-notes-preview">
+      <header class="knowledge-notes-preview-header">
+        <div class="knowledge-notes-preview-title-group">
+          <h2 class="knowledge-notes-preview-title">{{ workspace.activeNote.value.title }}</h2>
+          <span class="knowledge-notes-preview-meta">{{ workspace.formatKwTime(workspace.activeNote.value.updatedAt) }}</span>
+        </div>
+        <div class="knowledge-notes-preview-actions">
+          <button
+            type="button"
+            class="preview-edit"
+            :class="{ 'is-editing': editing }"
+            @click="toggleEditing"
+          >
+            {{ editing ? "完成" : "编辑" }}
+          </button>
+          <button type="button" class="preview-delete" @click="deleteActiveNote">删除</button>
+        </div>
+      </header>
+
+      <MarkdownEditor
+        v-if="editing"
+        :model-value="workspace.activeNote.value.body"
+        :editable="true"
+        :show-toolbar="true"
+        @update:model-value="updateBody"
+      />
+
+      <MarkdownPreview
+        v-else
+        :body="workspace.activeNote.value.body"
+        @link-click="followLink"
+      />
+
+      <BacklinksPanel
+        :workspace="workspace"
+        :entity-id="workspace.activeNote.value.id"
+        entity-type="note"
+        @navigate="workspace.followLink"
+      />
+    </div>
+
+    <div v-else class="knowledge-notes-empty-state">
+      <p>选择一篇笔记开始阅读，或创建新笔记</p>
+    </div>
+  </div>
+</template>
diff --git a/apps/desktop/src/components/knowledge/KnowledgeTasksPanel.vue b/apps/desktop/src/components/knowledge/KnowledgeTasksPanel.vue
new file mode 100644
index 0000000..7bd4660
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/KnowledgeTasksPanel.vue
@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import type { KnowledgeTask, TaskStatus } from "../../composables/useKnowledgeMock";
+import { STATUS_LABELS } from "../../composables/useKnowledgeMock";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+}>();
+
+const statusFilter = ref<TaskStatus | "all">("all");
+
+const filteredTasks = computed(() => {
+  const tasks = props.workspace.currentTasks.value;
+  if (statusFilter.value === "all") return tasks;
+  return tasks.filter((t) => t.status === statusFilter.value);
+});
+
+const statuses: TaskStatus[] = ["todo", "doing", "done", "archived"];
+
+function linkedNoteTitle(task: KnowledgeTask): string {
+  if (!task.linkedNoteId) return "";
+  const note = props.workspace.allNotes.value.find((n) => n.id === task.linkedNoteId);
+  return note?.title ?? "";
+}
+
+function deleteTask(task: KnowledgeTask): void {
+  props.workspace.deleteTask(task.id);
+}
+
+function changeStatus(task: KnowledgeTask, status: TaskStatus): void {
+  props.workspace.updateTaskStatus(task.id, status);
+}
+</script>
+
+<template>
+  <div class="knowledge-tasks-panel">
+    <header class="knowledge-tasks-header">
+      <span class="knowledge-tasks-count">{{ filteredTasks.length }} 项任务</span>
+
+      <div class="knowledge-tasks-filters">
+        <button
+          type="button"
+          class="filter-pill"
+          :class="{ active: statusFilter === 'all' }"
+          @click="statusFilter = 'all'"
+        >
+          全部
+        </button>
+        <button
+          v-for="status in statuses"
+          :key="status"
+          type="button"
+          class="filter-pill"
+          :class="{ active: statusFilter === status }"
+          @click="statusFilter = status"
+        >
+          {{ STATUS_LABELS[status] }}
+        </button>
+      </div>
+    </header>
+
+    <ul v-if="filteredTasks.length > 0" class="knowledge-tasks-list">
+      <li
+        v-for="task in filteredTasks"
+        :key="task.id"
+        class="knowledge-task-row"
+        :data-status="task.status"
+      >
+        <select
+          class="knowledge-task-status-select"
+          :value="task.status"
+          @change="changeStatus(task, ($event.target as HTMLSelectElement).value as TaskStatus)"
+        >
+          <option v-for="status in statuses" :key="status" :value="status">{{ STATUS_LABELS[status] }}</option>
+        </select>
+
+        <span class="knowledge-task-row-title">{{ task.title }}</span>
+
+        <div class="knowledge-task-row-meta">
+          <span v-for="tag in task.tags" :key="tag" class="kw-tag">{{ tag }}</span>
+          <span v-if="linkedNoteTitle(task)" class="knowledge-task-row-link">
+            {{ linkedNoteTitle(task) }}
+          </span>
+        </div>
+
+        <button type="button" class="knowledge-task-row-delete" @click="deleteTask(task)">删除</button>
+      </li>
+    </ul>
+
+    <div v-else class="knowledge-tasks-empty">
+      <p>没有符合条件的任务</p>
+    </div>
+  </div>
+</template>
diff --git a/apps/desktop/src/components/knowledge/KnowledgeTopbar.vue b/apps/desktop/src/components/knowledge/KnowledgeTopbar.vue
deleted file mode 100644
index b7f0c98..0000000
--- a/apps/desktop/src/components/knowledge/KnowledgeTopbar.vue
+++ /dev/null
@@ -1,62 +0,0 @@
-<script setup lang="ts">
-import {
-  VIEW_LABELS,
-  type IndexStatus,
-  type KnowledgeProject,
-  type KnowledgeViewKey,
-} from "../../composables/useKnowledgeMock";
-import IndexStatusDot from "./IndexStatusDot.vue";
-
-defineProps<{
-  project: KnowledgeProject | null;
-  activeView: KnowledgeViewKey;
-  searchQuery: string;
-  indexStatus: IndexStatus;
-}>();
-
-const emit = defineEmits<{
-  selectView: [view: KnowledgeViewKey];
-  "update:searchQuery": [value: string];
-}>();
-
-const views: KnowledgeViewKey[] = ["notes", "board", "tasks"];
-</script>
-
-<template>
-  <header class="knowledge-topbar">
-    <div class="knowledge-topbar-left">
-      <h1 class="knowledge-project-title">{{ project?.name ?? "—" }}</h1>
-      <span class="knowledge-project-meta">
-        {{ project?.noteCount ?? 0 }} 篇笔记 · {{ project?.taskCount ?? 0 }} 项任务
-      </span>
-    </div>
-
-    <nav class="knowledge-view-tabs" aria-label="视图切换">
-      <button
-        v-for="view in views"
-        :key="view"
-        type="button"
-        :class="{ active: activeView === view }"
-        @click="emit('selectView', view)"
-      >
-        {{ VIEW_LABELS[view] }}
-      </button>
-    </nav>
-
-    <div class="knowledge-topbar-right">
-      <label class="knowledge-search">
-        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-          <circle cx="11" cy="11" r="7" />
-          <path d="m20 20-3.5-3.5" />
-        </svg>
-        <input
-          type="text"
-          placeholder="搜索本项目笔记与任务"
-          :value="searchQuery"
-          @input="emit('update:searchQuery', ($event.target as HTMLInputElement).value)"
-        />
-      </label>
-      <IndexStatusDot :status="indexStatus" />
-    </div>
-  </header>
-</template>
diff --git a/apps/desktop/src/components/knowledge/MarkdownPreview.vue b/apps/desktop/src/components/knowledge/MarkdownPreview.vue
new file mode 100644
index 0000000..f047d50
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/MarkdownPreview.vue
@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { marked } from "marked";
+
+interface Props {
+  body: string;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  linkClick: [label: string];
+}>();
+
+const WIKI_LINK_REGEX = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+
+interface WikiLinkToken {
+  target: string;
+  display: string;
+}
+
+const renderedHtml = computed(() => {
+  const tokens: WikiLinkToken[] = [];
+
+  const preprocessed = (props.body || "").replace(WIKI_LINK_REGEX, (_match, target: string, display?: string) => {
+    const tokenIndex = tokens.length;
+    tokens.push({
+      target: target.trim(),
+      display: (display ?? target).trim(),
+    });
+    return `__NEO_WIKI_LINK_${tokenIndex}__`;
+  });
+
+  const rawHtml = marked.parse(preprocessed, { async: false }) as string;
+  const sanitized = sanitizeHtml(rawHtml);
+
+  return sanitized.replace(/__NEO_WIKI_LINK_(\d+)__/g, (_match, index: string) => {
+    const token = tokens[Number(index)];
+    if (!token) return "";
+    const safeTarget = escapeHtml(token.target);
+    const safeDisplay = escapeHtml(token.display);
+    return `<a class="kw-link" href="#" data-label="${safeTarget}" onclick="event.preventDefault()">${safeDisplay}</a>`;
+  });
+});
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+function sanitizeHtml(html: string): string {
+  return html
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "")
+    .replace(/javascript:/gi, "")
+    .replace(/on\w+\s*=/gi, "");
+}
+
+function handleClick(event: MouseEvent): void {
+  const target = (event.target as HTMLElement).closest(".kw-link");
+  if (!target) return;
+  event.preventDefault();
+  const label = target.getAttribute("data-label");
+  if (label) {
+    emit("linkClick", label);
+  }
+}
+</script>
+
+<template>
+  <div class="kw-markdown-preview" v-html="renderedHtml" @click="handleClick" />
+</template>
diff --git a/apps/desktop/src/components/knowledge/NoteList.vue b/apps/desktop/src/components/knowledge/NoteList.vue
deleted file mode 100644
index 5db9125..0000000
--- a/apps/desktop/src/components/knowledge/NoteList.vue
+++ /dev/null
@@ -1,32 +0,0 @@
-<script setup lang="ts">
-import { deriveExcerpt, type KnowledgeNote } from "../../composables/useKnowledgeMock";
-
-defineProps<{
-  notes: KnowledgeNote[];
-  activeId: string;
-}>();
-
-const emit = defineEmits<{
-  select: [id: string];
-}>();
-</script>
-
-<template>
-  <div class="knowledge-note-list">
-    <button
-      v-for="note in notes"
-      :key="note.id"
-      type="button"
-      class="knowledge-note-item"
-      :class="{ active: note.id === activeId }"
-      @click="emit('select', note.id)"
-    >
-      <div class="title">{{ note.title }}</div>
-      <div class="excerpt">{{ deriveExcerpt(note.body) }}</div>
-      <div class="meta">
-        <span v-for="tag in note.tags" :key="tag" class="tag">{{ tag }}</span>
-        <span class="time">{{ note.updatedAt }}</span>
-      </div>
-    </button>
-  </div>
-</template>
diff --git a/apps/desktop/src/components/knowledge/NotePreview.vue b/apps/desktop/src/components/knowledge/NotePreview.vue
deleted file mode 100644
index ee3018d..0000000
--- a/apps/desktop/src/components/knowledge/NotePreview.vue
+++ /dev/null
@@ -1,52 +0,0 @@
-<script setup lang="ts">
-import type { KnowledgeNote } from "../../composables/useKnowledgeMock";
-import MarkdownEditor from "../markdown-editor/MarkdownEditor.vue";
-
-const props = defineProps<{
-  note: KnowledgeNote | null;
-  /** 是否处于编辑模式（toolbar + 可写入）。 */
-  editable: boolean;
-}>();
-
-const emit = defineEmits<{
-  "update:body": [body: string];
-}>();
-
-function handleUpdate(body: string): void {
-  if (!props.note) return;
-  emit("update:body", body);
-}
-</script>
-
-<template>
-  <article v-if="note" class="knowledge-note-preview">
-    <header class="preview-head">
-      <div>
-        <div class="preview-title">{{ note.title }}</div>
-        <div class="preview-meta">
-          <span v-for="tag in note.tags" :key="tag" class="tag">{{ tag }}</span>
-          <span class="time">最近修改 {{ note.updatedAt }}</span>
-        </div>
-      </div>
-    </header>
-
-    <!--
-      readonly = 同一 Tiptap schema 渲染 markdown，与编辑模式视觉绝对一致；
-      editable = true 时显示 Toolbar + 接受输入。
-      MarkdownEditor 内部每次切 note 走 setContent 不重建 editor，避免 marked.use 副作用。
-    -->
-    <div class="preview-body">
-      <MarkdownEditor
-        :model-value="note.body"
-        :editable="editable"
-        :show-toolbar="editable"
-        placeholder="开始编辑这篇笔记…"
-        @update:model-value="handleUpdate"
-      />
-    </div>
-  </article>
-  <div v-else class="knowledge-empty">
-    <p>当前项目暂无笔记</p>
-    <small>v2 阶段可在此创建第一篇 Markdown 笔记</small>
-  </div>
-</template>
diff --git a/apps/desktop/src/components/knowledge/NotesPane.vue b/apps/desktop/src/components/knowledge/NotesPane.vue
deleted file mode 100644
index aac5790..0000000
--- a/apps/desktop/src/components/knowledge/NotesPane.vue
+++ /dev/null
@@ -1,27 +0,0 @@
-<script setup lang="ts">
-import type { KnowledgeNote } from "../../composables/useKnowledgeMock";
-import NoteList from "./NoteList.vue";
-import NotePreview from "./NotePreview.vue";
-
-defineProps<{
-  notes: KnowledgeNote[];
-  activeNote: KnowledgeNote | null;
-  editable: boolean;
-}>();
-
-const emit = defineEmits<{
-  select: [id: string];
-  "update:body": [body: string];
-}>();
-</script>
-
-<template>
-  <div class="knowledge-notes-pane">
-    <NoteList :notes="notes" :active-id="activeNote?.id ?? ''" @select="emit('select', $event)" />
-    <NotePreview
-      :note="activeNote"
-      :editable="editable"
-      @update:body="emit('update:body', $event)"
-    />
-  </div>
-</template>
diff --git a/apps/desktop/src/components/knowledge/ProjectBrowser.vue b/apps/desktop/src/components/knowledge/ProjectBrowser.vue
new file mode 100644
index 0000000..e9635ad
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/ProjectBrowser.vue
@@ -0,0 +1,53 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+import ProjectCard from "./ProjectCard.vue";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+}>();
+
+const emit = defineEmits<{
+  enter: [id: string];
+}>();
+
+const displayProjects = computed(() => {
+  if (props.workspace.currentProjectId.value) {
+    return props.workspace.childProjects.value;
+  }
+  return props.workspace.projects.value.filter((p) => p.parentId === null);
+});
+
+function childCount(id: string): number {
+  return props.workspace.childProjectsOf(id).length;
+}
+
+function noteCount(id: string): number {
+  return props.workspace.countNotes(id);
+}
+
+function taskCount(id: string): number {
+  return props.workspace.countTasks(id);
+}
+</script>
+
+<template>
+  <section class="project-browser" aria-label="项目浏览器">
+    <div v-if="displayProjects.length === 0" class="project-browser-empty">
+      <p>这里还没有项目</p>
+      <small>进入工作区后可创建子项目或笔记</small>
+    </div>
+
+    <div v-else class="project-grid">
+      <ProjectCard
+        v-for="project in displayProjects"
+        :key="project.id"
+        :project="project"
+        :child-count="childCount(project.id)"
+        :note-count="noteCount(project.id)"
+        :task-count="taskCount(project.id)"
+        @enter="emit('enter', $event)"
+      />
+    </div>
+  </section>
+</template>
diff --git a/apps/desktop/src/components/knowledge/ProjectCard.vue b/apps/desktop/src/components/knowledge/ProjectCard.vue
new file mode 100644
index 0000000..833347c
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/ProjectCard.vue
@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { KnowledgeProject } from "../../composables/useKnowledgeMock";
+
+const props = defineProps<{
+  project: KnowledgeProject;
+  childCount: number;
+  noteCount: number;
+  taskCount: number;
+}>();
+
+const emit = defineEmits<{
+  enter: [id: string];
+}>();
+
+const isContainer = computed(() => props.childCount > 0);
+const accentStyle = computed(() => ({
+  "--project-accent": props.project.color ?? "var(--kw-accent)",
+}));
+</script>
+
+<template>
+  <button
+    type="button"
+    class="project-card"
+    :class="{ 'is-container': isContainer, 'is-leaf': !isContainer }"
+    :style="accentStyle"
+    @click="emit('enter', project.id)"
+  >
+    <span class="project-card-accent" aria-hidden="true" />
+
+    <span class="project-card-icon">
+      <svg
+        v-if="project.isInbox"
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+      >
+        <path d="M22 12h-6l-2 3h-4l-2-3H2" />
+        <path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
+      </svg>
+      <svg
+        v-else-if="isContainer"
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+      >
+        <path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z" />
+      </svg>
+      <svg
+        v-else
+        width="22"
+        height="22"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+      >
+        <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
+        <polyline points="14 2 14 8 20 8" />
+      </svg>
+    </span>
+
+    <span class="project-card-body">
+      <span class="project-card-title">{{ project.title }}</span>
+      <span v-if="project.description" class="project-card-desc">{{ project.description }}</span>
+    </span>
+
+    <span class="project-card-meta">
+      <span v-if="childCount > 0" class="project-card-badge">{{ childCount }} 子项目</span>
+      <span v-else class="project-card-badge">{{ noteCount }} 笔记 · {{ taskCount }} 任务</span>
+    </span>
+
+    <span class="project-card-arrow" aria-hidden="true">
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+        <path d="m9 18 6-6-6-6" />
+      </svg>
+    </span>
+  </button>
+</template>
diff --git a/apps/desktop/src/components/knowledge/ProjectSidebar.vue b/apps/desktop/src/components/knowledge/ProjectSidebar.vue
deleted file mode 100644
index e421c87..0000000
--- a/apps/desktop/src/components/knowledge/ProjectSidebar.vue
+++ /dev/null
@@ -1,51 +0,0 @@
-<script setup lang="ts">
-import type { KnowledgeProject } from "../../composables/useKnowledgeMock";
-
-defineProps<{
-  projects: KnowledgeProject[];
-  activeProjectId: string;
-}>();
-
-const emit = defineEmits<{
-  select: [id: string];
-}>();
-</script>
-
-<template>
-  <aside class="knowledge-sidebar">
-    <div class="knowledge-sidebar-brand">
-      <div class="knowledge-sidebar-title">NeoCompanion</div>
-      <div class="knowledge-sidebar-sub">v3.3 · 知识工作空间</div>
-    </div>
-
-    <div class="knowledge-sidebar-section-label">项目</div>
-
-    <button
-      v-for="project in projects"
-      :key="project.id"
-      type="button"
-      class="knowledge-project-item"
-      :class="{ active: project.id === activeProjectId, inbox: project.isInbox }"
-      @click="emit('select', project.id)"
-    >
-      <span class="project-icon" aria-hidden="true">
-        <svg v-if="project.isInbox" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
-          <path d="M22 12h-6l-2 3h-4l-2-3H2" />
-          <path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
-        </svg>
-        <svg v-else width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
-          <path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z" />
-        </svg>
-      </span>
-      <span class="project-name">{{ project.name }}</span>
-      <span class="project-count">{{ project.noteCount }}</span>
-    </button>
-
-    <button type="button" class="knowledge-project-add" disabled title="v2 阶段实现">
-      <span aria-hidden="true">＋</span>
-      <span>新建项目</span>
-    </button>
-
-    <div class="knowledge-sidebar-footer">所有内容仅存储在本地</div>
-  </aside>
-</template>
diff --git a/apps/desktop/src/components/knowledge/ProjectWorkspace.vue b/apps/desktop/src/components/knowledge/ProjectWorkspace.vue
new file mode 100644
index 0000000..14c8115
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/ProjectWorkspace.vue
@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+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 ProjectBrowser from "./ProjectBrowser.vue";
+import QuickCreateBar from "./QuickCreateBar.vue";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+}>();
+
+const emit = defineEmits<{
+  exit: [];
+}>();
+
+const tabs = computed<KnowledgeViewTab[]>(() => {
+  const base: KnowledgeViewTab[] = ["notes", "board", "tasks"];
+  return props.workspace.hasChildren.value ? [...base, "projects"] : base;
+});
+
+const metaText = computed(() => {
+  const ws = props.workspace;
+  return `${ws.countNotes(ws.currentProjectId.value ?? "")} 笔记 · ${ws.countTasks(ws.currentProjectId.value ?? "")} 任务`;
+});
+</script>
+
+<template>
+  <section class="project-workspace">
+    <header class="project-workspace-header">
+      <div class="project-workspace-title-group">
+        <button
+          v-if="workspace.currentProject.value?.parentId"
+          type="button"
+          class="project-workspace-back"
+          @click="emit('exit')"
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+            <path d="m15 18-6-6 6-6" />
+          </svg>
+          返回上级
+        </button>
+
+        <div class="project-workspace-title-row">
+          <span
+            class="project-workspace-color"
+            :style="{ background: workspace.currentProject.value?.color ?? 'var(--kw-accent)' }"
+            aria-hidden="true"
+          />
+          <h1 class="project-workspace-title">{{ workspace.currentProject.value?.title }}</h1>
+        </div>
+
+        <p v-if="workspace.currentProject.value?.description" class="project-workspace-desc">
+          {{ workspace.currentProject.value.description }}
+        </p>
+
+        <span class="project-workspace-meta">{{ metaText }}</span>
+      </div>
+
+      <div class="project-workspace-actions">
+        <IndexStatusDot :status="workspace.indexStatus.value" />
+      </div>
+    </header>
+
+    <nav class="project-workspace-tabs" aria-label="工作区视图">
+      <button
+        v-for="tab in tabs"
+        :key="tab"
+        type="button"
+        class="project-workspace-tab"
+        :class="{ active: workspace.activeTab.value === tab }"
+        @click="workspace.selectTab(tab)"
+      >
+        {{ TAB_LABELS[tab] }}
+      </button>
+    </nav>
+
+    <div class="project-workspace-content">
+      <KnowledgeNotesPanel
+        v-if="workspace.activeTab.value === 'notes'"
+        :workspace="workspace"
+      />
+
+      <KnowledgeBoardPanel
+        v-else-if="workspace.activeTab.value === 'board'"
+        :workspace="workspace"
+      />
+
+      <KnowledgeTasksPanel
+        v-else-if="workspace.activeTab.value === 'tasks'"
+        :workspace="workspace"
+      />
+
+      <ProjectBrowser
+        v-else-if="workspace.activeTab.value === 'projects'"
+        :workspace="workspace"
+        @enter="workspace.enterProject"
+      />
+    </div>
+
+    <QuickCreateBar :workspace="workspace" />
+  </section>
+</template>
diff --git a/apps/desktop/src/components/knowledge/QuickCreateBar.vue b/apps/desktop/src/components/knowledge/QuickCreateBar.vue
new file mode 100644
index 0000000..eb4cc87
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/QuickCreateBar.vue
@@ -0,0 +1,73 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import type { KnowledgeWorkspaceState } from "../../composables/useKnowledgeWorkspace";
+
+const props = defineProps<{
+  workspace: KnowledgeWorkspaceState;
+}>();
+
+const mode = ref<"note" | "task">("task");
+const title = ref("");
+
+const placeholder = computed(() =>
+  mode.value === "note" ? "快速创建笔记…" : "快速创建任务…",
+);
+
+function submit(): void {
+  const value = title.value.trim();
+  if (!value) return;
+
+  if (mode.value === "note") {
+    props.workspace.createNote(value);
+  } else {
+    const column = props.workspace.currentColumns.value[0];
+    if (!column) return;
+    props.workspace.createTask(column.id, value);
+  }
+
+  title.value = "";
+}
+
+function setMode(next: "note" | "task"): void {
+  mode.value = next;
+}
+</script>
+
+<template>
+  <div class="quick-create-bar">
+    <div class="quick-create-modes">
+      <button
+        type="button"
+        class="quick-create-mode"
+        :class="{ active: mode === 'task' }"
+        @click="setMode('task')"
+      >
+        任务
+      </button>
+      <button
+        type="button"
+        class="quick-create-mode"
+        :class="{ active: mode === 'note' }"
+        @click="setMode('note')"
+      >
+        笔记
+      </button>
+    </div>
+
+    <input
+      v-model="title"
+      type="text"
+      class="quick-create-input"
+      :placeholder="placeholder"
+      @keydown.enter="submit"
+    />
+
+    <button type="button" class="quick-create-submit" @click="submit">
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+        <path d="M5 12h14" />
+        <path d="m12 5 7 7-7 7" />
+      </svg>
+      创建
+    </button>
+  </div>
+</template>
diff --git a/apps/desktop/src/components/knowledge/TasksPane.vue b/apps/desktop/src/components/knowledge/TasksPane.vue
deleted file mode 100644
index 3e5a3d9..0000000
--- a/apps/desktop/src/components/knowledge/TasksPane.vue
+++ /dev/null
@@ -1,37 +0,0 @@
-<script setup lang="ts">
-import type { KnowledgeTask } from "../../composables/useKnowledgeMock";
-
-defineProps<{
-  tasks: KnowledgeTask[];
-}>();
-
-const STATUS_LABEL: Record<KnowledgeTask["status"], string> = {
-  todo: "待办",
-  doing: "进行中",
-  done: "已完成",
-  archived: "已归档",
-};
-</script>
-
-<template>
-  <div class="knowledge-tasks-pane">
-    <p class="knowledge-tasks-tip">
-      统一任务视图：与看板共享同一份数据，便于平铺浏览。
-    </p>
-    <ul class="knowledge-task-list">
-      <li
-        v-for="task in tasks"
-        :key="task.id"
-        class="knowledge-task-row"
-        :data-status="task.status"
-      >
-        <span class="status-pill">{{ STATUS_LABEL[task.status] }}</span>
-        <span class="title">{{ task.title }}</span>
-        <span class="tags">
-          <span v-for="tag in task.tags" :key="tag" class="tag">{{ tag }}</span>
-          <span v-if="task.linkedNoteId" class="linked" title="关联笔记">↳ 笔记</span>
-        </span>
-      </li>
-    </ul>
-  </div>
-</template>
diff --git a/apps/desktop/src/components/knowledge/ThemeToggle.vue b/apps/desktop/src/components/knowledge/ThemeToggle.vue
new file mode 100644
index 0000000..d757b5f
--- /dev/null
+++ b/apps/desktop/src/components/knowledge/ThemeToggle.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import type { ThemeMode } from "../../composables/useTheme";
+
+defineProps<{
+  theme: ThemeMode;
+}>();
+
+const emit = defineEmits<{
+  toggle: [];
+}>();
+</script>
+
+<template>
+  <button
+    type="button"
+    class="knowledge-theme-toggle"
+    :aria-label="theme === 'light' ? '切换到深色模式' : '切换到浅色模式'"
+    @click="emit('toggle')"
+  >
+    <svg
+      v-if="theme === 'light'"
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+    >
+      <circle cx="12" cy="12" r="5" />
+      <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42" />
+    </svg>
+    <svg
+      v-else
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+    >
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+    </svg>
+  </button>
+</template>
diff --git a/apps/desktop/src/components/settings/sections/KnowledgeSection.vue b/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
index 29fcdf0..da75005 100644
--- a/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
+++ b/apps/desktop/src/components/settings/sections/KnowledgeSection.vue
@@ -1,15 +1,17 @@
 <script setup lang="ts">
+import { computed, ref } from "vue";
 import type {
   EmbeddingProvider,
   SearchScope,
   SettingsState,
 } from "../../../composables/useSettings";
+import { open } from "@tauri-apps/plugin-dialog";
 import SettingRow from "../SettingRow.vue";
 import ToggleSwitch from "../ToggleSwitch.vue";
 import TextField from "../TextField.vue";
 import SelectField from "../SelectField.vue";
 
-defineProps<{
+const props = defineProps<{
   state: SettingsState;
 }>();
 
@@ -24,6 +26,24 @@ const scopeOptions: { value: SearchScope; label: string }[] = [
   { value: "current", label: "当前项目" },
   { value: "all", label: "全部项目" },
 ];
+
+const isTauri = typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+const picking = ref(false);
+
+const rootPathDisplay = computed(() => props.state.knowledgeRootPath.value || "未选择");
+
+async function pickRootFolder(): Promise<void> {
+  if (!isTauri || picking.value) return;
+  picking.value = true;
+  try {
+    const selected = await open({ directory: true, multiple: false });
+    if (typeof selected === "string" && selected) {
+      props.state.setKnowledgeRootPath(selected);
+    }
+  } finally {
+    picking.value = false;
+  }
+}
 </script>
 
 <template>
@@ -42,6 +62,31 @@ const scopeOptions: { value: SearchScope; label: string }[] = [
         </div>
       </div>
 
+      <SettingRow
+        label="知识库根目录"
+        hint="笔记与索引数据的存放根目录（阶段 0 仅记录路径，文件化存储将在 v2 接入）"
+      >
+        <template #action>
+          <div class="knowledge-root-action">
+            <input
+              class="text-input knowledge-root-path"
+              :value="rootPathDisplay"
+              readonly
+              :title="state.knowledgeRootPath.value"
+            />
+            <button
+              type="button"
+              class="btn-ghost"
+              :disabled="!isTauri || picking"
+              :title="isTauri ? '' : '需在桌面端选择'"
+              @click="pickRootFolder"
+            >
+              选择文件夹
+            </button>
+          </div>
+        </template>
+      </SettingRow>
+
       <SettingRow label="Embedding Provider" hint="未配置时 AI 检索退化为仅 FTS5 全文搜索；笔记与看板始终可用">
         <template #action>
           <SelectField v-model="state.embeddingProvider.value" :options="providerOptions" />
diff --git a/apps/desktop/src/composables/useSettings.ts b/apps/desktop/src/composables/useSettings.ts
index 91e7fc6..02cb9e1 100644
--- a/apps/desktop/src/composables/useSettings.ts
+++ b/apps/desktop/src/composables/useSettings.ts
@@ -29,8 +29,9 @@ 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 isDark = ref(false);
   const activeSection = ref<SettingsSection>("general");
 
   // —— 通用设置
@@ -79,13 +80,22 @@ export function useSettings() {
   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) ?? "" : "",
+  );
 
   function reindexAll(): void {
     // mock：v2 接入后会调用 api.reindexKnowledge()
   }
 
-  function toggleTheme(): void {
-    isDark.value = !isDark.value;
+  function setKnowledgeRootPath(path: string): void {
+    const trimmed = path.trim();
+    knowledgeRootPath.value = trimmed;
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem(KNOWLEDGE_ROOT_PATH_KEY, trimmed);
+    }
   }
 
   function setSection(id: SettingsSection): void {
@@ -112,7 +122,6 @@ export function useSettings() {
 
   return {
     // state
-    isDark,
     activeSection,
     language,
     autoStart,
@@ -147,14 +156,15 @@ export function useSettings() {
     searchScope,
     chunkSize,
     indexAutoRebuild,
+    knowledgeRootPath,
     // actions
-    toggleTheme,
     setSection,
     selectModel,
     selectMount,
     removeBlacklistItem,
     addBlacklistItem,
     reindexAll,
+    setKnowledgeRootPath,
   };
 }
 
diff --git a/apps/desktop/src/composables/useTheme.ts b/apps/desktop/src/composables/useTheme.ts
new file mode 100644
index 0000000..49c86b7
--- /dev/null
+++ b/apps/desktop/src/composables/useTheme.ts
@@ -0,0 +1,60 @@
+import { computed, ref, watch } from "vue";
+
+/**
+ * Global light/dark theme state.
+ * Persists to localStorage and sets `data-theme` on the document element.
+ */
+
+export type ThemeMode = "light" | "dark";
+
+const STORAGE_KEY = "neo-theme";
+
+function isBrowser(): boolean {
+  return typeof document !== "undefined" && typeof localStorage !== "undefined";
+}
+
+function readStoredTheme(): ThemeMode {
+  if (!isBrowser()) return "light";
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (raw === "dark" || raw === "light") return raw;
+  } catch {
+    // ignore storage errors
+  }
+  return "light";
+}
+
+function applyTheme(theme: ThemeMode): void {
+  if (!isBrowser()) return;
+  document.documentElement.setAttribute("data-theme", theme);
+}
+
+const theme = ref<ThemeMode>(readStoredTheme());
+applyTheme(theme.value);
+
+watch(theme, (next) => {
+  applyTheme(next);
+  if (!isBrowser()) return;
+  try {
+    localStorage.setItem(STORAGE_KEY, next);
+  } catch {
+    // ignore storage errors
+  }
+});
+
+export function useTheme() {
+  function setTheme(value: ThemeMode): void {
+    theme.value = value;
+  }
+
+  function toggleTheme(): void {
+    theme.value = theme.value === "light" ? "dark" : "light";
+  }
+
+  return {
+    theme,
+    isDark: computed(() => theme.value === "dark"),
+    setTheme,
+    toggleTheme,
+  };
+}
diff --git a/apps/desktop/src/styles/knowledge.css b/apps/desktop/src/styles/knowledge.css
index cb0d241..8f8b417 100644
--- a/apps/desktop/src/styles/knowledge.css
+++ b/apps/desktop/src/styles/knowledge.css
@@ -2,10 +2,7 @@
  * Knowledge Workspace Styles
  *
  * 作用域：[data-view="knowledge"] 下的独立 webview，不污染 panel/settings。
- * 入口卡 .nc-knowledge-* 类挂在 panel-shell 内的 KnowledgeEntryCard，沿用 panel.css 的 token。
- *
- * 设计取向：与 settings 视图一脉相承的玻璃 + 浅色基底，但更强调"工作区"的密度——
- * 项目侧栏、笔记列表、看板列都倾向更紧凑的留白，避免在大窗口里显得空洞。
+ * 支持 light/dark 切换，通过 [data-knowledge-theme="dark"]。
  */
 
 /* ============================================================
@@ -122,15 +119,43 @@
   --kw-bg: #f6f5f2;
   --kw-surface: #ffffff;
   --kw-surface-alt: #fafaf8;
+  --kw-surface-hover: #f0eeea;
   --kw-border: #e9e7e2;
   --kw-text: #1c1a17;
   --kw-text-muted: #6b6660;
-  --kw-accent: #3b82f6;
-  --kw-accent-soft: rgba(59, 130, 246, 0.1);
+  --kw-accent: #4f46e5;
+  --kw-accent-soft: rgba(79, 70, 229, 0.1);
+  --kw-accent-text: #ffffff;
   --kw-tag-bg: rgba(28, 26, 23, 0.06);
+  --kw-danger: #ef4444;
+  --kw-danger-soft: rgba(239, 68, 68, 0.1);
+  --kw-radius-s: 8px;
+  --kw-radius-m: 12px;
   --kw-radius-l: 16px;
-  --kw-radius-m: 10px;
-  --kw-sidebar-width: 260px;
+  --kw-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
+  --kw-shadow-card: 0 4px 14px rgba(0, 0, 0, 0.06);
+
+  color-scheme: light;
+}
+
+[data-view="knowledge"][data-knowledge-theme="dark"] {
+  --kw-bg: #111827;
+  --kw-surface: #1f2937;
+  --kw-surface-alt: #18212f;
+  --kw-surface-hover: #273242;
+  --kw-border: #374151;
+  --kw-text: #f9fafb;
+  --kw-text-muted: #9ca3af;
+  --kw-accent: #818cf8;
+  --kw-accent-soft: rgba(129, 140, 248, 0.15);
+  --kw-accent-text: #1f2937;
+  --kw-tag-bg: rgba(255, 255, 255, 0.08);
+  --kw-danger: #f87171;
+  --kw-danger-soft: rgba(248, 113, 113, 0.15);
+  --kw-shadow: 0 1px 3px rgba(0, 0, 0, 0.25);
+  --kw-shadow-card: 0 4px 14px rgba(0, 0, 0, 0.35);
+
+  color-scheme: dark;
 }
 
 .knowledge-root,
@@ -139,355 +164,566 @@
 }
 
 .knowledge-root {
-  display: grid;
-  grid-template-columns: var(--kw-sidebar-width) 1fr;
+  display: flex;
+  flex-direction: column;
   height: 100vh;
   overflow: hidden;
   background: var(--kw-bg);
   color: var(--kw-text);
   font-family: "Inter", "Zen Maru Gothic", "Microsoft YaHei", "PingFang SC", sans-serif;
   -webkit-font-smoothing: antialiased;
+  transition: background-color 120ms ease, color 120ms ease;
 }
 
-/* ───── 项目侧栏 ───── */
-
-.knowledge-sidebar {
+/* Header */
+.knowledge-header {
   display: flex;
-  flex-direction: column;
-  padding: 24px 14px 18px;
-  background: var(--kw-surface-alt);
-  border-right: 1px solid var(--kw-border);
-  overflow-y: auto;
+  align-items: center;
+  gap: 20px;
+  padding: 14px 28px;
+  background: var(--kw-surface);
+  border-bottom: 1px solid var(--kw-border);
+  flex: none;
 }
 
-.knowledge-sidebar-brand {
-  padding: 0 8px 18px;
-  border-bottom: 1px solid var(--kw-border);
-  margin-bottom: 14px;
+.knowledge-header-brand {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 140px;
 }
 
-.knowledge-sidebar-title {
-  font-size: 1.05rem;
+.knowledge-header-logo {
+  font-size: 0.95rem;
   font-weight: 600;
   letter-spacing: -0.01em;
 }
 
-.knowledge-sidebar-sub {
-  font-size: 0.72rem;
+.knowledge-header-sub {
+  font-size: 0.7rem;
   color: var(--kw-text-muted);
-  margin-top: 2px;
 }
 
-.knowledge-sidebar-section-label {
-  font-size: 0.68rem;
-  font-weight: 500;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  color: var(--kw-text-muted);
-  padding: 8px 8px 6px;
+.knowledge-breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 0;
 }
 
-.knowledge-project-item {
+.knowledge-breadcrumb-item {
   appearance: none;
   border: none;
   background: transparent;
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  width: 100%;
-  padding: 9px 10px;
-  border-radius: var(--kw-radius-m);
-  font-size: 0.86rem;
-  color: var(--kw-text);
-  text-align: left;
+  padding: 4px 8px;
+  border-radius: var(--kw-radius-s);
+  font-size: 0.82rem;
+  color: var(--kw-text-muted);
   cursor: pointer;
-  transition: background 0.16s ease;
+  white-space: nowrap;
+  transition: background 0.15s ease, color 0.15s ease;
 }
 
-.knowledge-project-item:hover {
+.knowledge-breadcrumb-item:hover {
   background: var(--kw-tag-bg);
+  color: var(--kw-text);
 }
 
-.knowledge-project-item.active {
-  background: var(--kw-accent-soft);
-  color: var(--kw-accent);
+.knowledge-breadcrumb-item.is-root,
+.knowledge-breadcrumb-item.is-active {
+  color: var(--kw-text);
+  font-weight: 500;
+}
+
+.knowledge-breadcrumb-separator {
+  color: var(--kw-text-muted);
+  font-size: 0.75rem;
+  opacity: 0.5;
 }
 
-.knowledge-project-item .project-icon {
+.knowledge-theme-toggle {
+  appearance: none;
+  border: 1px solid var(--kw-border);
+  background: var(--kw-surface-alt);
+  color: var(--kw-text-muted);
+  width: 34px;
+  height: 34px;
+  border-radius: 999px;
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  color: var(--kw-text-muted);
-  flex: none;
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
 }
 
-.knowledge-project-item.active .project-icon {
+.knowledge-theme-toggle:hover {
+  background: var(--kw-accent-soft);
   color: var(--kw-accent);
+  border-color: var(--kw-accent);
 }
 
-.knowledge-project-item .project-name {
+/* Project Browser */
+.project-browser {
   flex: 1;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
+  min-height: 0;
+  overflow: auto;
+  padding: 28px;
 }
 
-.knowledge-project-item .project-count {
-  font-size: 0.7rem;
+.project-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 20px;
+  max-width: 1200px;
+}
+
+.project-browser-empty,
+.project-card-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  padding: 80px 20px;
   color: var(--kw-text-muted);
-  font-variant-numeric: tabular-nums;
+  text-align: center;
 }
 
-.knowledge-project-item.inbox .project-name {
-  font-weight: 500;
+.project-browser-empty p {
+  margin: 0;
+  font-size: 1rem;
+}
+
+.project-browser-empty small {
+  font-size: 0.78rem;
 }
 
-.knowledge-project-add {
+.project-card {
   appearance: none;
-  border: 1px dashed var(--kw-border);
-  background: transparent;
+  border: 1px solid var(--kw-border);
+  background: var(--kw-surface);
+  border-radius: var(--kw-radius-l);
+  padding: 20px;
   display: flex;
+  flex-direction: column;
+  gap: 14px;
+  text-align: left;
+  cursor: pointer;
+  box-shadow: var(--kw-shadow);
+  transition: transform 0.18s ease, box-shadow 0.18s ease, border-color 0.18s ease;
+  position: relative;
+  overflow: hidden;
+}
+
+.project-card:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--kw-shadow-card);
+  border-color: var(--kw-accent);
+}
+
+.project-card-accent {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 4px;
+  height: 100%;
+  background: var(--project-accent, var(--kw-accent));
+}
+
+.project-card-icon {
+  width: 44px;
+  height: 44px;
+  border-radius: var(--kw-radius-m);
+  background: var(--kw-surface-alt);
+  color: var(--kw-text-muted);
+  display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: 6px;
-  width: 100%;
-  padding: 9px;
-  margin-top: 6px;
-  border-radius: var(--kw-radius-m);
+}
+
+.project-card:hover .project-card-icon {
+  color: var(--kw-accent);
+}
+
+.project-card-body {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.project-card-title {
+  font-size: 1.05rem;
+  font-weight: 600;
+  color: var(--kw-text);
+}
+
+.project-card-desc {
   font-size: 0.78rem;
   color: var(--kw-text-muted);
-  cursor: not-allowed;
+  line-height: 1.45;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
 }
 
-.knowledge-sidebar-footer {
+.project-card-meta {
   margin-top: auto;
-  padding: 12px 8px 0;
-  border-top: 1px solid var(--kw-border);
-  font-size: 0.7rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.project-card-badge {
+  font-size: 0.72rem;
+  padding: 4px 10px;
+  border-radius: 999px;
+  background: var(--kw-tag-bg);
   color: var(--kw-text-muted);
 }
 
-/* ───── 主区 ───── */
+.project-card-arrow {
+  color: var(--kw-text-muted);
+  transition: transform 0.18s ease, color 0.18s ease;
+}
+
+.project-card:hover .project-card-arrow {
+  transform: translateX(3px);
+  color: var(--kw-accent);
+}
 
-.knowledge-main {
+/* Project Workspace */
+.project-workspace {
+  flex: 1;
+  min-height: 0;
   display: flex;
   flex-direction: column;
-  min-width: 0;
   overflow: hidden;
 }
 
-/* Topbar */
-
-.knowledge-topbar {
+.project-workspace-header {
   display: flex;
-  align-items: center;
-  gap: 24px;
-  padding: 18px 28px;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 20px;
+  padding: 20px 28px 16px;
   background: var(--kw-surface);
   border-bottom: 1px solid var(--kw-border);
+  flex: none;
 }
 
-.knowledge-topbar-left {
+.project-workspace-title-group {
   display: flex;
   flex-direction: column;
-  gap: 2px;
-  min-width: 200px;
+  gap: 6px;
+  min-width: 0;
+}
+
+.project-workspace-back {
+  appearance: none;
+  border: none;
+  background: transparent;
+  padding: 0;
+  font-size: 0.72rem;
+  color: var(--kw-text-muted);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  transition: color 0.15s ease;
+}
+
+.project-workspace-back:hover {
+  color: var(--kw-accent);
+}
+
+.project-workspace-title-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.project-workspace-color {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  flex: none;
 }
 
-.knowledge-project-title {
+.project-workspace-title {
   margin: 0;
-  font-size: 1.08rem;
+  font-size: 1.35rem;
   font-weight: 600;
   letter-spacing: -0.01em;
+  color: var(--kw-text);
+}
+
+.project-workspace-desc {
+  margin: 0;
+  font-size: 0.82rem;
+  color: var(--kw-text-muted);
 }
 
-.knowledge-project-meta {
+.project-workspace-meta {
   font-size: 0.72rem;
   color: var(--kw-text-muted);
-  font-variant-numeric: tabular-nums;
 }
 
-.knowledge-view-tabs {
+.project-workspace-actions {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.project-workspace-tabs {
   display: flex;
   gap: 4px;
-  padding: 3px;
-  background: var(--kw-surface-alt);
-  border-radius: 999px;
+  padding: 10px 28px;
+  background: var(--kw-surface);
+  border-bottom: 1px solid var(--kw-border);
+  flex: none;
 }
 
-.knowledge-view-tabs button {
+.project-workspace-tab {
   appearance: none;
   border: none;
   background: transparent;
   padding: 6px 16px;
   border-radius: 999px;
-  font-size: 0.78rem;
+  font-size: 0.8rem;
   color: var(--kw-text-muted);
   cursor: pointer;
-  transition: background 0.16s ease, color 0.16s ease;
+  transition: background 0.15s ease, color 0.15s ease;
 }
 
-.knowledge-view-tabs button.active {
-  background: var(--kw-surface);
+.project-workspace-tab:hover {
+  background: var(--kw-surface-hover);
   color: var(--kw-text);
-  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
-}
-
-.knowledge-topbar-right {
-  margin-left: auto;
-  display: flex;
-  align-items: center;
-  gap: 16px;
-}
-
-.knowledge-search {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 12px;
-  border-radius: 999px;
-  background: var(--kw-surface-alt);
-  border: 1px solid var(--kw-border);
-  color: var(--kw-text-muted);
-  width: 240px;
 }
 
-.knowledge-search input {
-  flex: 1;
-  border: none;
-  background: transparent;
-  outline: none;
-  font-size: 0.8rem;
-  color: var(--kw-text);
+.project-workspace-tab.active {
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+  font-weight: 500;
 }
 
-/* 主滚动区 */
-.knowledge-content-scroll {
+.project-workspace-content {
   flex: 1;
   min-height: 0;
   overflow: auto;
   padding: 20px 28px 28px;
 }
 
-/* ───── 笔记视图 ───── */
-
-.knowledge-notes-pane {
+/* Notes Panel */
+.knowledge-notes-panel {
   display: grid;
-  grid-template-columns: 320px 1fr;
+  grid-template-columns: 280px 1fr;
   gap: 20px;
-  min-height: 100%;
+  height: 100%;
+  min-height: 0;
 }
 
-.knowledge-note-list {
+.knowledge-notes-list {
   display: flex;
   flex-direction: column;
   gap: 6px;
+  background: var(--kw-surface);
+  border: 1px solid var(--kw-border);
+  border-radius: var(--kw-radius-l);
+  padding: 12px;
+  overflow: auto;
   align-self: start;
+  max-height: 100%;
 }
 
-.knowledge-note-item {
-  appearance: none;
-  border: 1px solid transparent;
-  background: var(--kw-surface);
-  text-align: left;
-  padding: 12px 14px;
-  border-radius: var(--kw-radius-m);
-  cursor: pointer;
-  transition: border-color 0.16s ease, background 0.16s ease;
+.knowledge-notes-list-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 4px 6px 8px;
+  border-bottom: 1px solid var(--kw-border);
+  margin-bottom: 4px;
 }
 
-.knowledge-note-item:hover {
-  border-color: var(--kw-border);
+.knowledge-notes-count {
+  font-size: 0.72rem;
+  color: var(--kw-text-muted);
+  font-weight: 500;
 }
 
-.knowledge-note-item.active {
-  border-color: var(--kw-accent);
-  background: var(--kw-accent-soft);
+.knowledge-notes-add {
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: var(--kw-accent);
+  font-size: 0.75rem;
+  font-weight: 500;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
 }
 
-.knowledge-note-item .title {
-  font-size: 0.9rem;
-  font-weight: 500;
-  margin-bottom: 4px;
+.knowledge-notes-add:hover {
+  text-decoration: underline;
 }
 
-.knowledge-note-item .excerpt {
-  font-size: 0.76rem;
-  color: var(--kw-text-muted);
-  line-height: 1.5;
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  -webkit-box-orient: vertical;
-  overflow: hidden;
+.knowledge-notes-create {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 8px;
 }
 
-.knowledge-note-item .meta {
+.knowledge-notes-create input {
+  width: 100%;
+  padding: 8px 10px;
+  border: 1px solid var(--kw-border);
+  border-radius: var(--kw-radius-s);
+  background: var(--kw-surface-alt);
+  color: var(--kw-text);
+  font-size: 0.82rem;
+  outline: none;
+}
+
+.knowledge-notes-create input:focus {
+  border-color: var(--kw-accent);
+  box-shadow: 0 0 0 3px var(--kw-accent-soft);
+}
+
+.knowledge-notes-create-actions {
   display: flex;
-  align-items: center;
-  gap: 6px;
-  margin-top: 8px;
-  flex-wrap: wrap;
+  gap: 8px;
 }
 
-.knowledge-note-item .meta .tag {
-  font-size: 0.66rem;
-  padding: 2px 8px;
-  border-radius: 999px;
-  background: var(--kw-tag-bg);
-  color: var(--kw-text-muted);
+.knowledge-notes-create-actions button {
+  appearance: none;
+  border: 1px solid var(--kw-border);
+  background: var(--kw-surface-alt);
+  color: var(--kw-text);
+  padding: 6px 12px;
+  border-radius: var(--kw-radius-s);
+  font-size: 0.75rem;
+  cursor: pointer;
+}
+
+.knowledge-notes-create-actions button.primary {
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+  border-color: var(--kw-accent);
+}
+
+.knowledge-note-row {
+  appearance: none;
+  border: 1px solid transparent;
+  background: transparent;
+  text-align: left;
+  padding: 10px 12px;
+  border-radius: var(--kw-radius-m);
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  transition: background 0.15s ease, border-color 0.15s ease;
+}
+
+.knowledge-note-row:hover {
+  background: var(--kw-surface-hover);
+}
+
+.knowledge-note-row.active {
+  background: var(--kw-accent-soft);
+  border-color: var(--kw-accent);
 }
 
-.knowledge-note-item .meta .time {
-  margin-left: auto;
+.knowledge-note-row-title {
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--kw-text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.knowledge-note-row-meta {
   font-size: 0.68rem;
   color: var(--kw-text-muted);
-  font-variant-numeric: tabular-nums;
 }
 
-.knowledge-note-preview {
+.knowledge-notes-empty,
+.knowledge-notes-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  padding: 40px 20px;
+  color: var(--kw-text-muted);
+  text-align: center;
+}
+
+.knowledge-notes-empty button {
+  appearance: none;
+  border: 1px solid var(--kw-border);
+  background: var(--kw-surface-alt);
+  color: var(--kw-text);
+  padding: 8px 16px;
+  border-radius: var(--kw-radius-s);
+  font-size: 0.78rem;
+  cursor: pointer;
+}
+
+.knowledge-notes-preview {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
   background: var(--kw-surface);
   border: 1px solid var(--kw-border);
   border-radius: var(--kw-radius-l);
-  padding: 24px 28px 32px;
+  padding: 24px;
   min-height: 100%;
+  overflow: auto;
 }
 
-.knowledge-note-preview .preview-head {
+.knowledge-notes-preview-header {
   display: flex;
   align-items: flex-start;
+  justify-content: space-between;
   gap: 16px;
   padding-bottom: 16px;
   border-bottom: 1px solid var(--kw-border);
-  margin-bottom: 18px;
 }
 
-.knowledge-note-preview .preview-title {
-  font-size: 1.18rem;
+.knowledge-notes-preview-title-group {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+.knowledge-notes-preview-title {
+  margin: 0;
+  font-size: 1.25rem;
   font-weight: 600;
   letter-spacing: -0.01em;
-  margin-bottom: 6px;
 }
 
-.knowledge-note-preview .preview-meta {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  flex-wrap: wrap;
+.knowledge-notes-preview-meta {
   font-size: 0.72rem;
   color: var(--kw-text-muted);
 }
 
-.knowledge-note-preview .preview-meta .tag {
-  padding: 2px 8px;
-  border-radius: 999px;
-  background: var(--kw-tag-bg);
+.knowledge-notes-preview-actions {
+  display: flex;
+  gap: 8px;
 }
 
-.knowledge-note-preview .preview-edit {
-  margin-left: auto;
+.preview-edit,
+.preview-delete {
   appearance: none;
   border: 1px solid var(--kw-border);
-  background: var(--kw-surface);
+  background: var(--kw-surface-alt);
   padding: 6px 14px;
   border-radius: 999px;
   font-size: 0.76rem;
@@ -496,120 +732,265 @@
   transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
 }
 
-.knowledge-note-preview .preview-edit:hover:not(:disabled) {
+.preview-edit:hover,
+.preview-delete:hover {
   background: var(--kw-accent-soft);
   border-color: var(--kw-accent);
   color: var(--kw-accent);
 }
 
-.knowledge-note-preview .preview-edit:disabled {
-  cursor: not-allowed;
-  opacity: 0.6;
-}
-
-.knowledge-note-preview .preview-edit.is-editing {
+.preview-edit.is-editing {
   background: var(--kw-accent);
   border-color: var(--kw-accent);
-  color: #ffffff;
+  color: var(--kw-accent-text);
 }
 
-.knowledge-note-preview .preview-body {
-  /* 容器层基线；具体 markdown 元素样式见 styles/markdown.css 的 .nc-md-* 类。 */
-  font-size: 0.92rem;
+.preview-delete:hover {
+  background: var(--kw-danger-soft);
+  border-color: var(--kw-danger);
+  color: var(--kw-danger);
+}
+
+.kw-markdown-preview {
+  font-size: 0.95rem;
   line-height: 1.7;
   color: var(--kw-text);
 }
 
-.knowledge-empty {
-  text-align: center;
+.kw-markdown-preview h1 {
+  font-size: 1.5rem;
+  margin: 0 0 16px;
+}
+
+.kw-markdown-preview h2 {
+  font-size: 1.2rem;
+  margin: 24px 0 12px;
+}
+
+.kw-markdown-preview p {
+  margin: 0 0 12px;
+}
+
+.kw-markdown-preview blockquote {
+  margin: 0 0 12px;
+  padding: 8px 16px;
+  border-left: 3px solid var(--kw-accent);
+  background: var(--kw-surface-alt);
+  border-radius: 0 var(--kw-radius-s) var(--kw-radius-s) 0;
   color: var(--kw-text-muted);
-  padding: 60px 20px;
 }
 
-.knowledge-empty p {
-  margin: 0 0 6px;
-  font-size: 0.9rem;
+.kw-markdown-preview code {
+  font-family: var(--font-mono);
+  background: var(--kw-surface-alt);
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 0.85em;
 }
 
-.knowledge-empty small {
-  font-size: 0.72rem;
+.kw-markdown-preview pre {
+  background: var(--kw-surface-alt);
+  padding: 14px;
+  border-radius: var(--kw-radius-m);
+  overflow: auto;
+}
+
+.kw-markdown-preview pre code {
+  background: transparent;
+  padding: 0;
+}
+
+.kw-link {
+  color: var(--kw-accent);
+  text-decoration: none;
+  font-weight: 500;
+  cursor: pointer;
 }
 
-/* ───── 看板视图 ───── */
+.kw-link:hover {
+  text-decoration: underline;
+}
+
+/* Backlinks */
+.backlinks-panel {
+  margin-top: auto;
+  padding-top: 16px;
+  border-top: 1px solid var(--kw-border);
+}
 
-.knowledge-board-pane {
+.backlinks-header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 0.78rem;
+  font-weight: 500;
+  color: var(--kw-text-muted);
+  margin-bottom: 10px;
+}
+
+.backlinks-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.backlinks-item button {
+  appearance: none;
+  border: 1px solid var(--kw-border);
+  background: var(--kw-surface-alt);
+  border-radius: var(--kw-radius-s);
+  padding: 8px 12px;
+  width: 100%;
+  text-align: left;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  transition: border-color 0.15s ease;
+}
+
+.backlinks-item button:hover {
+  border-color: var(--kw-accent);
+}
+
+.backlinks-type {
+  font-size: 0.65rem;
+  padding: 2px 6px;
+  border-radius: 999px;
+  background: var(--kw-tag-bg);
+  color: var(--kw-text-muted);
+}
+
+.backlinks-title {
+  font-size: 0.8rem;
+  color: var(--kw-text);
+}
+
+/* Board Panel */
+.knowledge-board-panel {
+  height: 100%;
+  min-height: 0;
+}
+
+.knowledge-board-grid {
   display: grid;
-  grid-template-columns: repeat(4, minmax(0, 1fr));
-  gap: 14px;
-  min-height: 100%;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 16px;
+  height: 100%;
+  align-items: start;
+}
+
+.knowledge-board-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: var(--kw-text-muted);
 }
 
-.knowledge-board-column {
+.board-column {
   display: flex;
   flex-direction: column;
+  gap: 12px;
   background: var(--kw-surface-alt);
+  border: 1px solid var(--kw-border);
   border-radius: var(--kw-radius-l);
-  padding: 14px 12px;
-  min-width: 0;
+  padding: 14px;
+  min-height: 160px;
+  max-height: 100%;
+  transition: border-color 0.15s ease, background 0.15s ease;
 }
 
-.knowledge-board-column header {
+.board-column.is-drop-target {
+  border-color: var(--kw-accent);
+  background: var(--kw-accent-soft);
+}
+
+.board-column-header {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: 0 4px 10px;
-  font-size: 0.78rem;
-  font-weight: 500;
-  color: var(--kw-text-muted);
+  padding: 0 4px;
 }
 
-.knowledge-board-column header .count {
+.board-column-title {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--kw-text);
+}
+
+.board-column-count {
   font-size: 0.7rem;
-  background: var(--kw-tag-bg);
-  padding: 1px 8px;
+  padding: 2px 8px;
   border-radius: 999px;
-  font-variant-numeric: tabular-nums;
+  background: var(--kw-tag-bg);
+  color: var(--kw-text-muted);
 }
 
-.knowledge-board-column .cards {
+.board-column-cards {
   display: flex;
   flex-direction: column;
   gap: 8px;
+  min-height: 40px;
 }
 
-.knowledge-board-column .empty {
+.board-column-empty {
   font-size: 0.72rem;
   color: var(--kw-text-muted);
-  padding: 16px;
   text-align: center;
+  padding: 16px;
   border: 1px dashed var(--kw-border);
   border-radius: var(--kw-radius-m);
 }
 
-.knowledge-board-card {
+.board-task-card {
   background: var(--kw-surface);
   border: 1px solid var(--kw-border);
   border-radius: var(--kw-radius-m);
-  padding: 10px 12px;
+  padding: 12px;
+  cursor: grab;
   display: flex;
   flex-direction: column;
-  gap: 8px;
+  gap: 10px;
+  transition: box-shadow 0.15s ease, transform 0.15s ease;
 }
 
-.knowledge-board-card .title {
-  font-size: 0.82rem;
+.board-task-card:hover {
+  box-shadow: var(--kw-shadow);
+}
+
+.board-task-card:active {
+  cursor: grabbing;
+}
+
+.board-task-card.is-dragging {
+  opacity: 0.4;
+}
+
+.board-task-card-title {
+  margin: 0;
+  font-size: 0.85rem;
   font-weight: 500;
-  line-height: 1.45;
+  line-height: 1.4;
+  color: var(--kw-text);
 }
 
-.knowledge-board-card .meta {
+.board-task-card[data-status="done"] .board-task-card-title,
+.board-task-card[data-status="archived"] .board-task-card-title {
+  color: var(--kw-text-muted);
+  text-decoration: line-through;
+}
+
+.board-task-card-meta {
   display: flex;
-  align-items: center;
-  gap: 6px;
   flex-wrap: wrap;
+  gap: 6px;
 }
 
-.knowledge-board-card .tag {
+.kw-tag {
   font-size: 0.66rem;
   padding: 2px 8px;
   border-radius: 999px;
@@ -617,37 +998,122 @@
   color: var(--kw-text-muted);
 }
 
-.knowledge-board-card .linked {
+.board-task-card-link {
+  font-size: 0.68rem;
+  color: var(--kw-accent);
   display: inline-flex;
   align-items: center;
   gap: 3px;
-  font-size: 0.66rem;
-  color: var(--kw-accent);
 }
 
-.knowledge-board-card[data-status="done"] .title,
-.knowledge-board-card[data-status="archived"] .title {
+.board-task-card.is-drop-above {
+  box-shadow: 0 -2px 0 0 var(--kw-accent);
+}
+
+.board-drop-line {
+  height: 2px;
+  margin: 1px 0;
+  border-radius: 1px;
+  background: var(--kw-accent);
+}
+
+.board-column-add,
+.board-column-create button {
+  appearance: none;
+  border: none;
+  background: transparent;
   color: var(--kw-text-muted);
-  text-decoration: line-through;
-  text-decoration-color: rgba(28, 26, 23, 0.25);
+  font-size: 0.75rem;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.board-column-add:hover {
+  color: var(--kw-accent);
+}
+
+.board-column-create {
+  display: flex;
+  gap: 8px;
+}
+
+.board-column-create input {
+  flex: 1;
+  padding: 6px 10px;
+  border: 1px solid var(--kw-border);
+  border-radius: var(--kw-radius-s);
+  background: var(--kw-surface);
+  color: var(--kw-text);
+  font-size: 0.78rem;
+  outline: none;
+}
+
+.board-column-create input:focus {
+  border-color: var(--kw-accent);
 }
 
-/* ───── 任务视图 ───── */
+.board-column-create button {
+  padding: 6px 10px;
+  border-radius: var(--kw-radius-s);
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+}
 
-.knowledge-tasks-pane {
+/* Tasks Panel */
+.knowledge-tasks-panel {
   background: var(--kw-surface);
   border: 1px solid var(--kw-border);
   border-radius: var(--kw-radius-l);
-  padding: 18px 22px;
+  padding: 20px;
+  min-height: 100%;
+}
+
+.knowledge-tasks-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 16px;
+  flex-wrap: wrap;
+}
+
+.knowledge-tasks-count {
+  font-size: 0.78rem;
+  color: var(--kw-text-muted);
+  font-weight: 500;
+}
+
+.knowledge-tasks-filters {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
 }
 
-.knowledge-tasks-tip {
-  margin: 0 0 14px;
-  font-size: 0.74rem;
+.filter-pill {
+  appearance: none;
+  border: 1px solid var(--kw-border);
+  background: var(--kw-surface-alt);
   color: var(--kw-text-muted);
+  padding: 4px 12px;
+  border-radius: 999px;
+  font-size: 0.72rem;
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
 }
 
-.knowledge-task-list {
+.filter-pill:hover {
+  border-color: var(--kw-accent);
+}
+
+.filter-pill.active {
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+  border-color: var(--kw-accent);
+}
+
+.knowledge-tasks-list {
   list-style: none;
   margin: 0;
   padding: 0;
@@ -657,98 +1123,156 @@
 
 .knowledge-task-row {
   display: grid;
-  grid-template-columns: 80px 1fr auto;
+  grid-template-columns: 100px 1fr auto;
   align-items: center;
   gap: 12px;
-  padding: 10px 4px;
+  padding: 12px 8px;
   border-bottom: 1px solid var(--kw-border);
-  font-size: 0.84rem;
+  font-size: 0.85rem;
 }
 
 .knowledge-task-row:last-child {
   border-bottom: none;
 }
 
-.knowledge-task-row .status-pill {
-  font-size: 0.7rem;
-  padding: 2px 10px;
-  border-radius: 999px;
-  background: var(--kw-tag-bg);
-  color: var(--kw-text-muted);
-  text-align: center;
-  width: fit-content;
-}
-
-.knowledge-task-row[data-status="doing"] .status-pill {
-  background: rgba(59, 130, 246, 0.12);
-  color: #2563eb;
+.knowledge-task-status-select {
+  padding: 4px 8px;
+  border: 1px solid var(--kw-border);
+  border-radius: var(--kw-radius-s);
+  background: var(--kw-surface-alt);
+  color: var(--kw-text);
+  font-size: 0.75rem;
+  cursor: pointer;
 }
 
-.knowledge-task-row[data-status="done"] .status-pill {
-  background: rgba(34, 197, 94, 0.14);
-  color: #15803d;
+.knowledge-task-row-title {
+  color: var(--kw-text);
+  font-weight: 500;
 }
 
-.knowledge-task-row[data-status="done"] .title,
-.knowledge-task-row[data-status="archived"] .title {
+.knowledge-task-row[data-status="done"] .knowledge-task-row-title,
+.knowledge-task-row[data-status="archived"] .knowledge-task-row-title {
   color: var(--kw-text-muted);
   text-decoration: line-through;
-  text-decoration-color: rgba(28, 26, 23, 0.25);
 }
 
-.knowledge-task-row .tags {
-  display: inline-flex;
+.knowledge-task-row-meta {
+  display: flex;
   align-items: center;
   gap: 6px;
   flex-wrap: wrap;
 }
 
-.knowledge-task-row .tags .tag {
-  font-size: 0.66rem;
-  padding: 2px 8px;
-  border-radius: 999px;
-  background: var(--kw-tag-bg);
+.knowledge-task-row-link {
+  font-size: 0.7rem;
+  color: var(--kw-accent);
+}
+
+.knowledge-task-row-delete {
+  appearance: none;
+  border: 1px solid var(--kw-border);
+  background: transparent;
   color: var(--kw-text-muted);
+  padding: 4px 10px;
+  border-radius: var(--kw-radius-s);
+  font-size: 0.72rem;
+  cursor: pointer;
 }
 
-.knowledge-task-row .tags .linked {
-  font-size: 0.68rem;
-  color: var(--kw-accent);
+.knowledge-task-row-delete:hover {
+  background: var(--kw-danger-soft);
+  border-color: var(--kw-danger);
+  color: var(--kw-danger);
 }
 
-/* ---------- Knowledge edit-strip（KnowledgeView 顶部的「编辑/完成」按钮容器） ---------- */
+.knowledge-tasks-empty {
+  text-align: center;
+  padding: 60px 20px;
+  color: var(--kw-text-muted);
+}
 
-.knowledge-main .knowledge-edit-strip {
+/* Quick Create Bar */
+.quick-create-bar {
+  flex: none;
   display: flex;
-  justify-content: flex-end;
-  padding: 8px 24px 0;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 28px;
+  background: var(--kw-surface);
+  border-top: 1px solid var(--kw-border);
 }
 
-.knowledge-main .knowledge-edit-strip .preview-edit {
+.quick-create-modes {
+  display: flex;
+  gap: 4px;
+  padding: 3px;
+  background: var(--kw-surface-alt);
+  border-radius: 999px;
+}
+
+.quick-create-mode {
   appearance: none;
-  border: 1px solid var(--kw-border);
-  background: var(--kw-surface);
-  padding: 6px 14px;
+  border: none;
+  background: transparent;
+  padding: 5px 12px;
   border-radius: 999px;
-  font-size: 0.76rem;
+  font-size: 0.75rem;
   color: var(--kw-text-muted);
   cursor: pointer;
-  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+  transition: background 0.15s ease, color 0.15s ease;
 }
 
-.knowledge-main .knowledge-edit-strip .preview-edit:hover:not(:disabled) {
-  background: var(--kw-accent-soft);
-  border-color: var(--kw-accent);
-  color: var(--kw-accent);
+.quick-create-mode.active {
+  background: var(--kw-surface);
+  color: var(--kw-text);
+  box-shadow: var(--kw-shadow);
 }
 
-.knowledge-main .knowledge-edit-strip .preview-edit:disabled {
-  cursor: not-allowed;
-  opacity: 0.6;
+.quick-create-input {
+  flex: 1;
+  min-width: 0;
+  padding: 8px 14px;
+  border: 1px solid var(--kw-border);
+  border-radius: 999px;
+  background: var(--kw-surface-alt);
+  color: var(--kw-text);
+  font-size: 0.82rem;
+  outline: none;
 }
 
-.knowledge-main .knowledge-edit-strip .preview-edit.is-editing {
-  background: var(--kw-accent);
+.quick-create-input:focus {
   border-color: var(--kw-accent);
-  color: #ffffff;
+  box-shadow: 0 0 0 3px var(--kw-accent-soft);
+}
+
+.quick-create-submit {
+  appearance: none;
+  border: none;
+  background: var(--kw-accent);
+  color: var(--kw-accent-text);
+  padding: 8px 16px;
+  border-radius: 999px;
+  font-size: 0.78rem;
+  font-weight: 500;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  transition: filter 0.15s ease;
+}
+
+.quick-create-submit:hover {
+  filter: brightness(1.08);
+}
+
+/* Responsive */
+@media (max-width: 900px) {
+  .knowledge-notes-panel {
+    grid-template-columns: 1fr;
+    grid-template-rows: 200px 1fr;
+  }
+
+  .knowledge-board-grid {
+    grid-template-columns: 1fr;
+  }
 }
diff --git a/apps/desktop/src/styles/settings.css b/apps/desktop/src/styles/settings.css
index 05b69f7..3545fc6 100644
--- a/apps/desktop/src/styles/settings.css
+++ b/apps/desktop/src/styles/settings.css
@@ -443,6 +443,22 @@
   margin-left: 16px;
 }
 
+.knowledge-root-action {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.knowledge-root-action .knowledge-root-path {
+  width: 220px;
+  max-width: 220px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-muted);
+  cursor: default;
+}
+
 .settings-root .toggle {
   width: 44px;
   height: 26px;
diff --git a/apps/desktop/src/views/SettingsView.vue b/apps/desktop/src/views/SettingsView.vue
index 8e1aee4..f904920 100644
--- a/apps/desktop/src/views/SettingsView.vue
+++ b/apps/desktop/src/views/SettingsView.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed } from "vue";
 import { SECTION_TITLES, useSettings } from "../composables/useSettings";
+import { useTheme } from "../composables/useTheme";
 import SettingsSidebar from "../components/settings/SettingsSidebar.vue";
 import SettingsTopbar from "../components/settings/SettingsTopbar.vue";
 import GeneralSection from "../components/settings/sections/GeneralSection.vue";
@@ -12,12 +13,13 @@ import KnowledgeSection from "../components/settings/sections/KnowledgeSection.v
 import HookSection from "../components/settings/sections/HookSection.vue";
 
 const settings = useSettings();
+const theme = useTheme();
 
 const sectionTitle = computed(() => SECTION_TITLES[settings.activeSection.value]);
 </script>
 
 <template>
-  <div class="settings-root" :class="{ 'dark-mode': settings.isDark.value }" data-view="settings">
+  <div class="settings-root" :class="{ 'dark-mode': theme.isDark.value }" data-view="settings">
     <svg class="settings-noise-defs" aria-hidden="true">
       <filter id="noise-filter">
         <feTurbulence baseFrequency="0.65" numOctaves="3" stitchTiles="stitch" result="noise" />
@@ -31,8 +33,8 @@ const sectionTitle = computed(() => SECTION_TITLES[settings.activeSection.value]
       <main class="main-area">
         <SettingsTopbar
           :title="sectionTitle"
-          :is-dark="settings.isDark.value"
-          @toggle-theme="settings.toggleTheme"
+          :is-dark="theme.isDark.value"
+          @toggle-theme="theme.toggleTheme"
         />
 
         <div class="content-scroll">
diff --git a/docs/API.md b/docs/API.md
index 3c49ed6..1891d32 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -371,5 +371,6 @@ sidecar 会广播以下消息类型：
 
 ## 说明
 
-- 知识工作空间相关的搜索端点（`/api/knowledge/*`）**尚未实现**。当前知识工作空间 UI 由前端 mock 驱动。
+- 知识工作空间相关的搜索端点（`/api/knowledge/*`）**尚未实现**。当前知识工作空间 UI 由前端 mock 驱动，但已具备可交互的卡片化项目浏览器、嵌套导航、笔记/看板/任务工作区、双向链接与 backlinks、看板拖拽排序和全局主题切换，用于验证 UX。
+- 当前 `/api/tasks` 使用 `status: "open" | "done"`。v2 知识工作空间将任务状态扩展为 `"todo" | "doing" | "done" | "archived"`，并与看板列绑定；迁移时需将旧任务映射到新状态与列。
 - 错误响应格式通常为 `{ "error": "message" }`，除非另有说明。
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 789a996..e1c5dc8 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -36,7 +36,7 @@
 本文档同时描述 **已实现** 与 **规划中** 的技术设计。已实现的内容指当前代码中真实存在并运行的模块；规划中的内容标注为 `(Planned)` 或 `(Partial)`，例如：
 
 - **已实现**：Tauri 多窗口管理、Fastify Sidecar TCP 模式、SQLite + Drizzle ORM、任务/专注/天气/AI/TTS/窗口/Hook 等核心端点、WebSocket 实时推送、GitHub Actions CI/CD。
-- **部分实现 (Partial)**：v3.3 知识工作空间 UI（前端 mock 阶段，后端存储与检索尚未接入）。
+- **部分实现 (Partial)**：v3.3 知识工作空间 UI 交互层已交付（卡片化项目浏览器、嵌套项目导航、笔记/看板/任务工作区、按项目自定义看板列、HTML5 拖拽排序、双向 wiki 链接与 backlinks、全局 light/dark 主题），但仍为前端 mock 数据，后端 SQLite 存储、FTS5 / `sqlite-vec` 检索与相关 API 尚未接入。
 - **规划中 (Planned)**：FTS5 全文索引、`sqlite-vec` 向量检索与混合排序、零端口 UDS Socket 模式 B、文件监听 Hook、MQTT 接入、屏幕上下文感知与本地长期记忆模块。
 
 阅读时请注意段落中的状态标注，避免将规划内容误认为已交付功能。
@@ -723,10 +723,10 @@ packages/server-local/src/
 知识工作空间新增的跨包公共类型归属 `packages/shared`：
 
 ```typescript
-export interface Project { id: string; name: string; isInbox: boolean }
+export interface Project { id: string; title: string; description?: string; parentId: string | null; isInbox: boolean; order: number }
 export interface Note { id: string; projectId: string; title: string; body: string; tags: string[] }
-export interface Board { id: string; projectId: string; name: string }
-export interface BoardColumn { id: string; boardId: string; name: string; position: number }
+export interface Board { id: string; projectId: string; title: string }
+export interface BoardColumn { id: string; boardId: string; title: string; status: 'todo' | 'doing' | 'done' | 'archived'; position: number }
 
 export interface KnowledgeSource {
   sourceType: 'note' | 'task';
@@ -1072,8 +1072,11 @@ import { sqliteTable, text, integer, real } from 'drizzle-orm/sqlite-core';
 // 项目。系统迁移时创建默认“收件箱”。
 export const projects = sqliteTable('projects', {
   id: text('id').primaryKey(),
-  name: text('name').notNull(),
+  title: text('title').notNull(),
+  description: text('description'),
+  parentId: text('parent_id').references(() => projects.id),
   isInbox: integer('is_inbox', { mode: 'boolean' }).notNull().default(false),
+  order: integer('order').notNull().default(0),
   createdAt: text('created_at').notNull(),
   updatedAt: text('updated_at').notNull(),
 });
@@ -1081,14 +1084,15 @@ export const projects = sqliteTable('projects', {
 export const boards = sqliteTable('boards', {
   id: text('id').primaryKey(),
   projectId: text('project_id').notNull().references(() => projects.id),
-  name: text('name').notNull(),
+  title: text('title').notNull(),
   createdAt: text('created_at').notNull(),
 });
 
 export const boardColumns = sqliteTable('board_columns', {
   id: text('id').primaryKey(),
   boardId: text('board_id').notNull().references(() => boards.id),
-  name: text('name').notNull(),
+  title: text('title').notNull(),
+  status: text('status').notNull().default('todo'), // 'todo' | 'doing' | 'done' | 'archived'
   position: integer('position').notNull(),
 });
 
@@ -1100,7 +1104,7 @@ export const tasks = sqliteTable('tasks', {
   columnId: text('column_id').references(() => boardColumns.id),
   title: text('title').notNull(),
   description: text('description'),
-  status: text('status').notNull().default('open'), // 'open' | 'done'
+  status: text('status').notNull().default('todo'), // 'todo' | 'doing' | 'done' | 'archived'
   position: integer('position').notNull().default(0),
   createdAt: text('created_at').notNull(),
   updatedAt: text('updated_at').notNull(),
@@ -1263,8 +1267,8 @@ pnpm --filter db drizzle-kit migrate   # 执行迁移
 
 知识工作空间首次迁移必须在单一事务中完成：
 
-1. 创建默认“收件箱”项目、默认看板和“待处理 / 进行中 / 已完成”三列。
-2. 为旧 `tasks` 行补齐项目、看板、列、位置和更新时间；`open` 进入“待处理”，`done` 进入“已完成”，保留原 ID、标题和完成时间。
+1. 创建默认“收件箱”项目、默认看板和“待办 / 进行中 / 已完成 / 归档”四列；若项目已存在自定义列，则保留已有列。
+2. 为旧 `tasks` 行补齐项目、看板、列、位置和更新时间；`open` 映射为 `todo` 并进入“待办”列，`done` 映射为 `done` 并进入“已完成”列，保留原 ID、标题和完成时间。
 3. 创建 notes、tags、knowledge_chunks、FTS5 与 sqlite-vec 结构；旧任务随后进入增量索引队列。
 4. sqlite-vec 加载失败不得回滚业务表迁移；记录 `fts-only` 能力状态并继续启动。
 
@@ -1723,7 +1727,7 @@ export async function getApiKey(provider: string): Promise<string> {
 
 | 模块 | v2 新增 |
 |------|---------|
-| apps/desktop | 知识库入口、Markdown 编辑、项目切换、看板、搜索和来源跳转 |
+| apps/desktop | v3.3 已交付交互预览版（卡片化项目浏览器、嵌套项目、笔记/看板/任务工作区、双向链接、主题切换）；v2 接入真实后端与检索 |
 | packages/server-local | Project/Note/Board/Knowledge 模块、增量索引与 RAG 编排 |
 | packages/ai | 聊天模型与 EmbeddingAdapter 分离，OpenAI-compatible Embedding 实现 |
 | packages/db | 项目、笔记、看板、统一任务、知识分块、FTS5 与 sqlite-vec 迁移 |
diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
index 80a6106..f33446f 100644
--- a/docs/GLOSSARY.md
+++ b/docs/GLOSSARY.md
@@ -14,6 +14,9 @@
 | **任务 / Task** | 待办事项 | 在简单任务清单和看板中统一 |
 | **Hook** | 外部 Agent 集成机制 | 外部脚本通过本地 API 推送状态或请求权限 |
 | **知识工作空间 / Knowledge Workspace** | 项目、笔记、看板、AI 对话工作区 | v3.3 已引入 UI；后端存储与检索计划中 |
+| **项目卡片 / Project Card** | 知识库入口的卡片化项目展示单元 | v3.3 新增 |
+| **双向链接 / Bidirectional Link** | 笔记中 `[[...]]` 语法，支持来源追踪与 backlinks | v3.3 新增 |
+| **主题切换 / Theme Toggle** | 全局 light/dark 模式切换，作用于 knowledge/panel/settings 三视图 | v3.3 新增 |
 | **助手寄语 / Assistant Message** | 壁纸层中央淡出的简短反馈文字 | 旧称"伴侣寄语" |
 
 ## 弃用术语
diff --git a/docs/PRD_overview.md b/docs/PRD_overview.md
index 2910a7f..c56011c 100644
--- a/docs/PRD_overview.md
+++ b/docs/PRD_overview.md
@@ -122,8 +122,9 @@ NeoCompanion 的长期能力分为四层：
 - **助手工作日志**：日终自动生成以助手口吻撰写的温度成长记录。
 
 ### 5.3 Knowledge & AI Layer (本地知识与 AI 层)
-- **单一本地工作空间**：项目是顶层组织单元；每个项目关联 Markdown 笔记、看板与任务，未分类内容进入默认“收件箱”。
-- **统一任务模型**：现有简单待办升级为任务清单视图；同一任务可归属项目、看板与列，避免维护两套任务数据。
+- **单一本地工作空间**：项目是顶层组织单元；每个项目关联 Markdown 笔记、看板与任务，未分类内容进入默认“收件箱”。项目支持嵌套：非底层项目以卡片网格展示其子项目，底层项目展开为笔记/看板/任务工作区。
+- **统一任务模型**：现有简单待办升级为任务清单视图；同一任务可归属项目、看板与列，避免维护两套任务数据。看板列按项目自定义，任务支持跨列拖拽、列内排序和完成状态。
+- **双向链接**：Markdown 笔记正文支持 `[[目标]]` 或 `[[目标|显示文本]]` 语法，点击可跳转到对应笔记或任务，并在目标详情展示 backlinks。
 - **混合知识检索**：SQLite FTS5 负责标题、正文、标签和专有名词检索，`sqlite-vec` 负责语义召回，两路结果融合排序。
 - **有来源的 AI 回答**：AI 默认检索当前项目，也允许检索全部项目；回答后展示实际召回的笔记或任务来源。
 - **可用性优先**：Embedding 未配置、额度不足或索引失败时，笔记、看板和全文检索继续工作，AI 知识问答使用关键词召回并明确显示降级状态。
@@ -149,8 +150,9 @@ NeoCompanion 的长期能力分为四层：
 
 ### 6.2 v2: 本地知识工作空间与知识增强对话 (Local Knowledge Workspace & RAG)
 - **目标**：完成“记录 → 组织 → 检索 → 引用回答”的本地知识闭环。
+- **前置状态**：v3.3 已交付知识工作空间前端交互预览版（卡片化项目浏览器、嵌套项目、笔记/看板/任务工作区、双向链接、全局主题切换），当前为 mock 数据驱动。
 - **核心功能**：
-  - 项目、Markdown 笔记、看板和统一任务管理。
+  - 项目、Markdown 笔记、看板和统一任务管理（后端持久化与检索接入）。
   - SQLite FTS5 + `sqlite-vec` 混合检索、增量索引、索引状态和手动重建。
   - 可配置的聊天模型与 OpenAI-compatible Embedding Provider；密钥只进入系统凭据存储。
   - AI 回答附可点击来源；向量能力失败时降级全文检索。
diff --git a/docs/TESTING.md b/docs/TESTING.md
index 4314362..b6dd1ee 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -79,6 +79,38 @@ const app = await createApp({
 4. 涉及数据库或 sidecar 的测试，使用上文依赖注入模式。
 5. 提交前运行 `pnpm test`。
 
+## 知识工作空间手动验证清单
+
+以下流程在 `pnpm dev:tauri` 启动后，通过 panel 的「知识工作空间」入口打开独立窗口验证：
+
+1. **项目浏览器**
+   - 根视图展示顶层项目卡片（收件箱、产品研究、学习笔记、写作素材）。
+   - 点击「产品研究」（非底层项目）进入子项目卡片网格（竞品调研、用户研究）。
+   - 点击任意底层项目进入工作区。
+
+2. **工作区导航**
+   - 面包屑显示当前路径，点击任意段可跳转。
+   - 「返回上级」回到父项目或根浏览器。
+
+3. **笔记**
+   - 创建新笔记，标题出现在左侧列表。
+   - 编辑笔记正文，使用 `[[Rust borrow checker 速记]]` 建立链接。
+   - 切换到只读预览，点击链接跳转到目标笔记。
+   - 在目标笔记详情查看 backlinks 面板，确认来源列出。
+
+4. **看板**
+   - 在看板列底部输入创建任务。
+   - 拖拽任务跨列，确认列计数与任务状态同步更新。
+   - 在同一列内拖拽任务，确认排序变化。
+   - 使用键盘方向键（←↑↓→）移动聚焦的任务卡片。
+
+5. **任务列表**
+   - 切换「任务」tab，确认 flat 列表与看板数据一致。
+   - 使用状态筛选按钮过滤任务。
+
+6. **主题切换**
+   - 点击知识窗口 header 的主题按钮，确认 knowledge/panel/settings 三视图均切换 light/dark。
+
 ## 持续集成
 
 `ci-check.yml` 工作流会在每个针对 `main` 的 Pull Request 上运行 `pnpm typecheck` 和 `pnpm test`。
diff --git a/docs/TODO_INVENTORY.md b/docs/TODO_INVENTORY.md
index 0df2e83..deba1fe 100644
--- a/docs/TODO_INVENTORY.md
+++ b/docs/TODO_INVENTORY.md
@@ -39,9 +39,23 @@
 ## 知识工作空间
 
 - **文件**：`apps/desktop/src/composables/useKnowledgeMock.ts`
-- **影响**：整个知识工作空间（项目、笔记、看板、任务）目前为前端 mock 数据。真正的后端端点、SQLite 存储、FTS5 全文检索和 `sqlite-vec` 向量检索计划在 v2 实现。
+- **已交付（v3.3 UI）**：
+  - 卡片化项目浏览器与嵌套项目导航。
+  - 项目工作区（笔记 / 看板 / 任务 / 子项目 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
 
+### 数据模型与迁移待对齐项
+
+- **项目/看板字段名**：`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 首次迁移需为项目创建默认列，并支持自定义列持久化。
+
 ## 如何更新本清单
 
 1. 在提交文档 PR 前运行 `./scripts/verify-docs.sh`。
diff --git "a/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md" "b/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md"
index f655d85..08d1474 100644
--- "a/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md"
+++ "b/docs/\345\205\267\344\275\223\350\203\275\345\212\233\346\236\204\346\200\235.md"
@@ -144,9 +144,16 @@ NeoCompanion 不把复杂跨应用自动执行作为产品主轴，而是围绕
 
 ### 4.2 Markdown 笔记与看板
 - **Markdown 笔记**：首版提供标题、正文、标签和预览，不实现 Notion 式块编辑、附件、协作和版本历史。
-- **基础看板**：项目可包含看板与有序列；任务支持跨列移动、排序和完成状态。
+- **基础看板**：项目可包含看板与有序列；任务支持跨列移动、排序和完成状态。v3.3 UI 已实现看板拖拽与键盘移动，后端持久化待 v2 接入。
+- **双向链接**：笔记正文支持 `[[目标笔记标题]]` 或 `[[目标|显示文本]]` 语法。点击链接跳转到对应笔记或任务；目标详情页展示 backlinks，列出引用当前内容的其他笔记。v3.3 UI 已实现，后端解析与索引待 v2 接入。
 - **内容关联**：AI 检索覆盖笔记和任务，来源可以直接打开对应内容，形成“资料 → 行动 → 回顾”的连续工作流。
 
+### 4.2.1 项目浏览器与嵌套
+- **卡片化项目视图**：知识库入口以卡片网格展示项目，每张卡片显示标题、描述、颜色标识、子项目数量或笔记/任务统计。
+- **嵌套导航**：非底层项目点击进入后展示其子项目卡片；底层项目点击进入工作区（笔记/看板/任务）。
+- **混合容器**：项目可同时包含子项目卡片和属于该项目自身的笔记、任务与看板。
+- **面包屑与返回**：工作区顶部显示当前项目路径，支持点击面包屑快速跳转，并提供“返回上级”入口。
+
 ### 4.3 混合检索与索引生命周期
 - **全文检索**：SQLite FTS5 索引标题、Markdown 正文、标签和任务描述，保证专有名词和精确关键词可命中。
 - **向量检索**：`sqlite-vec` 保存语义向量；Markdown 按标题和段落稳定分块，单块约 1200 字符并保留少量重叠，任务作为单独知识条目。
@@ -250,8 +257,9 @@ Hook 是独立的外部状态入口，不绑定任何特定 Agent 或 CLI。外
 
 ### 6.2 Phase 2: 本地知识工作空间 (Local Knowledge Workspace)
 - **目标**：完成“记录 → 组织 → 检索 → 引用回答”的知识闭环。
+- **前置状态**：v3.3 已交付前端交互层（卡片化项目浏览器、嵌套项目、笔记/看板/任务工作区、双向链接、全局 light/dark 主题），由 mock 数据驱动。
 - **功能**：
-  - 项目、Markdown 笔记、统一任务与基础看板。
+  - 项目、Markdown 笔记、统一任务与基础看板的后端持久化与检索接入。
   - SQLite FTS5 与 `sqlite-vec` 混合检索、增量索引、索引状态和重建。
   - 聊天模型与 Embedding Provider 独立配置，AI 回答展示可点击来源。
   - 保留通用 Hook API、文件监听、UDS / Named Pipe 与权限审批能力，但不自动修改第三方配置。
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dcf7c06..b727fcf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,6 +26,9 @@ importers:
       '@tauri-apps/api':
         specifier: ^2.9.0
         version: 2.11.0
+      '@tauri-apps/plugin-dialog':
+        specifier: ^2.2.0
+        version: 2.7.1
       '@tiptap/core':
         specifier: 3.26.0
         version: 3.26.0(@tiptap/pm@3.26.0)
@@ -676,6 +679,9 @@ packages:
     engines: {node: '>= 10'}
     hasBin: true
 
+  '@tauri-apps/plugin-dialog@2.7.1':
+    resolution: {integrity: sha512-OK1UBXYt+ojcmxMktzzuyonYIFta8CmAASpX+CA+DTGK24KlHjhYI6x2iOJ/TjZF4N7/ACK1oFmEOjIY9IhzOQ==}
+
   '@tiptap/core@3.26.0':
     resolution: {integrity: sha512-7jTed/RirIVsp+lLdLvGzGqF3EBGpnGHGYKOwz6t28V2BIJLAFdUhfEVdWie7xPxQNWK0TP+fPlsqZS0vxfHBg==}
     peerDependencies:
@@ -2209,6 +2215,10 @@ snapshots:
       '@tauri-apps/cli-win32-ia32-msvc': 2.11.2
       '@tauri-apps/cli-win32-x64-msvc': 2.11.2
 
+  '@tauri-apps/plugin-dialog@2.7.1':
+    dependencies:
+      '@tauri-apps/api': 2.11.0
+
   '@tiptap/core@3.26.0(@tiptap/pm@3.26.0)':
     dependencies:
       '@tiptap/pm': 3.26.0

From bf6e6d39a2fe4fb73d5fcf1e1b7c6f219c275823 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 15:43:43 +0800
Subject: [PATCH 2/5] =?UTF-8?q?feat(knowledge):=20v2=20=E7=9F=A5=E8=AF=86?=
 =?UTF-8?q?=E5=BA=93=E5=90=8E=E7=AB=AF=E5=AD=98=E5=82=A8=E4=B8=8E=20FTS5?=
 =?UTF-8?q?=20=E6=A3=80=E7=B4=A2=E7=AE=A1=E7=BA=BF=20+=20=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=20API=20=E6=8E=A5=E5=85=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

后端（packages/db + packages/server-local）：
- 新增知识实体表（projects/notes/tags/note_tags/board_columns/knowledge_tasks/
  knowledge_chunks）+ FTS5 虚拟表 knowledge_chunks_fts
- createKnowledgeStore 同步 CRUD（tags 同步、级联删除、backlinks、moveTask 重排）
- Markdown-header 分块 + content-hash 去重 + FTS5 BM25 检索
  （项目范围过滤、按 source 去重、index_status 生命周期）
- 混合文件镜像：entity ↔ Markdown front-matter/JSONL，Obsidian 友好布局，
  export/import + root-path 端点（SQLite 权威 + 文件镜像）
- /api/knowledge/* CRUD + search + index-status + reindex + mirror，
  sqlite 未加载时降级 503

前端（apps/desktop）：
- useKnowledgeApi：乐观本地缓存（与 mock 同形状 KnowledgeDataSource 接口），
  写失败回滚+提示，loadAll 失败回退 mock
- useKnowledgeWorkspace 数据源切换为 api（mock 回退），编排层与 14 组件零改动
- KnowledgeView onMounted loadAll + 降级 banner
- api.ts 新增知识端点方法

类型（packages/shared）：知识实体 + IndexMode/KnowledgeIndexState/
  AiRetrievalMode/ContextLevel/AiAnswer/KnowledgeChunkIndexStatus

测试：desktop 28、server-local 23+5skip、db 9+1skip 全绿；
sqlite-native 不可用时 skipIf（CI 跑）
---
 apps/desktop/src/api.ts                       |  51 +-
 .../src/composables/useKnowledgeApi.ts        | 395 +++++++++++
 .../src/composables/useKnowledgeMock.ts       | 536 +++++++++++----
 .../src/composables/useKnowledgeWorkspace.ts  | 268 ++++++++
 apps/desktop/src/views/KnowledgeView.vue      | 109 ++-
 apps/desktop/tests/useKnowledgeApi.test.ts    | 110 +++
 packages/db/src/db.test.ts                    |  56 +-
 packages/db/src/index.ts                      | 645 +++++++++++++++++-
 packages/db/src/knowledge-fs.test.ts          |  84 +++
 packages/db/src/knowledge-fs.ts               | Bin 0 -> 5927 bytes
 packages/db/src/schema.ts                     |  77 +++
 packages/server-local/src/app.ts              |  11 +-
 .../src/modules/knowledge/chunker.test.ts     |  85 +++
 .../src/modules/knowledge/chunker.ts          | 203 ++++++
 .../src/modules/knowledge/indexer.test.ts     |  90 +++
 .../src/modules/knowledge/mirror.test.ts      | 161 +++++
 .../src/modules/knowledge/mirror.ts           | 253 +++++++
 .../src/modules/knowledge/routes.ts           | 283 ++++++++
 .../src/modules/knowledge/service.ts          |  66 ++
 packages/shared/src/index.ts                  |  97 +++
 20 files changed, 3396 insertions(+), 184 deletions(-)
 create mode 100644 apps/desktop/src/composables/useKnowledgeApi.ts
 create mode 100644 apps/desktop/src/composables/useKnowledgeWorkspace.ts
 create mode 100644 apps/desktop/tests/useKnowledgeApi.test.ts
 create mode 100644 packages/db/src/knowledge-fs.test.ts
 create mode 100644 packages/db/src/knowledge-fs.ts
 create mode 100644 packages/server-local/src/modules/knowledge/chunker.test.ts
 create mode 100644 packages/server-local/src/modules/knowledge/chunker.ts
 create mode 100644 packages/server-local/src/modules/knowledge/indexer.test.ts
 create mode 100644 packages/server-local/src/modules/knowledge/mirror.test.ts
 create mode 100644 packages/server-local/src/modules/knowledge/mirror.ts
 create mode 100644 packages/server-local/src/modules/knowledge/routes.ts
 create mode 100644 packages/server-local/src/modules/knowledge/service.ts

diff --git a/apps/desktop/src/api.ts b/apps/desktop/src/api.ts
index 35a12d0..1073967 100644
--- a/apps/desktop/src/api.ts
+++ b/apps/desktop/src/api.ts
@@ -1,4 +1,5 @@
 import type { ChatMessage, FocusSession, Task, TtsResult, WeatherSummary, WsMessage } from "@neo-companion/shared";
+import type { BoardColumn, KnowledgeNote, KnowledgeProject, KnowledgeTask, TaskStatus } from "./composables/useKnowledgeMock";
 
 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,7 +33,55 @@ export const api = {
   weather: () => request<WeatherSummary>("/api/weather"),
   chat: (message: string) => request<{ text: string }>("/api/ai/chat", { method: "POST", body: JSON.stringify({ message }) }),
   speak: (text: string, style?: string) =>
-    request<TtsResult>("/api/tts/speak", { method: "POST", body: JSON.stringify({ text, style }) })
+    request<TtsResult>("/api/tts/speak", { method: "POST", body: JSON.stringify({ text, style }) }),
+
+  // ── Knowledge workspace ──
+  knowledgeListProjects: () => request<KnowledgeProject[]>("/api/knowledge/projects?root=1"),
+  knowledgeChildProjects: (parentId: string) =>
+    request<KnowledgeProject[]>(`/api/knowledge/projects?parentId=${encodeURIComponent(parentId)}`),
+  knowledgeProjectPath: (id: string) =>
+    request<KnowledgeProject[]>(`/api/knowledge/projects/${encodeURIComponent(id)}/path`),
+  knowledgeCreateProject: (input: { title: string; parentId?: string | null; description?: string; color?: string; icon?: string }) =>
+    request<KnowledgeProject>("/api/knowledge/projects", { method: "POST", body: JSON.stringify(input) }),
+  knowledgeUpdateProject: (id: string, patch: Partial<Pick<KnowledgeProject, "title" | "description" | "color" | "icon" | "parentId" | "order">>) =>
+    request<KnowledgeProject>(`/api/knowledge/projects/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify(patch) }),
+  knowledgeDeleteProject: (id: string) =>
+    request<void>(`/api/knowledge/projects/${encodeURIComponent(id)}`, { method: "DELETE" }),
+  knowledgeListNotes: (projectId: string) =>
+    request<KnowledgeNote[]>(`/api/knowledge/projects/${encodeURIComponent(projectId)}/notes`),
+  knowledgeCreateNote: (projectId: string, title: string) =>
+    request<KnowledgeNote>(`/api/knowledge/projects/${encodeURIComponent(projectId)}/notes`, { method: "POST", body: JSON.stringify({ title }) }),
+  knowledgeUpdateNote: (id: string, patch: Partial<Pick<KnowledgeNote, "title" | "body" | "tags">>) =>
+    request<KnowledgeNote>(`/api/knowledge/notes/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify(patch) }),
+  knowledgeDeleteNote: (id: string) =>
+    request<void>(`/api/knowledge/notes/${encodeURIComponent(id)}`, { method: "DELETE" }),
+  knowledgeBacklinks: (id: string) =>
+    request<{ sourceType: "note" | "task"; sourceId: string }[]>(`/api/knowledge/notes/${encodeURIComponent(id)}/backlinks`),
+  knowledgeListColumns: (projectId: string) =>
+    request<BoardColumn[]>(`/api/knowledge/projects/${encodeURIComponent(projectId)}/columns`),
+  knowledgeCreateColumn: (projectId: string, input: { title: string; status: TaskStatus; order: number }) =>
+    request<BoardColumn>(`/api/knowledge/projects/${encodeURIComponent(projectId)}/columns`, { method: "POST", body: JSON.stringify(input) }),
+  knowledgeUpdateColumn: (id: string, patch: Partial<Pick<BoardColumn, "title" | "status" | "order">>) =>
+    request<BoardColumn>(`/api/knowledge/columns/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify(patch) }),
+  knowledgeDeleteColumn: (id: string) =>
+    request<void>(`/api/knowledge/columns/${encodeURIComponent(id)}`, { method: "DELETE" }),
+  knowledgeListTasks: (projectId: string) =>
+    request<KnowledgeTask[]>(`/api/knowledge/projects/${encodeURIComponent(projectId)}/tasks`),
+  knowledgeCreateTask: (projectId: string, columnId: string, title: string) =>
+    request<KnowledgeTask>(`/api/knowledge/projects/${encodeURIComponent(projectId)}/tasks`, { method: "POST", body: JSON.stringify({ columnId, title }) }),
+  knowledgeUpdateTask: (id: string, patch: Partial<Pick<KnowledgeTask, "title" | "description" | "status" | "columnId" | "order">> & { linkedNoteId?: string | null }) =>
+    request<KnowledgeTask>(`/api/knowledge/tasks/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify(patch) }),
+  knowledgeDeleteTask: (id: string) =>
+    request<void>(`/api/knowledge/tasks/${encodeURIComponent(id)}`, { method: "DELETE" }),
+  knowledgeMoveTask: (id: string, columnId: string, index: number) =>
+    request<void>(`/api/knowledge/tasks/${encodeURIComponent(id)}/move`, { method: "POST", body: JSON.stringify({ columnId, index }) }),
+  knowledgeGetRootPath: () => request<{ path: string }>("/api/knowledge/root-path"),
+  knowledgeSetRootPath: (path: string) =>
+    request<{ path: string }>("/api/knowledge/root-path", { method: "PUT", body: JSON.stringify({ path }) }),
+  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 }) })
 };
 
 let activeWs: WebSocket | null = null;
diff --git a/apps/desktop/src/composables/useKnowledgeApi.ts b/apps/desktop/src/composables/useKnowledgeApi.ts
new file mode 100644
index 0000000..405238b
--- /dev/null
+++ b/apps/desktop/src/composables/useKnowledgeApi.ts
@@ -0,0 +1,395 @@
+import { computed, ref, type ComputedRef, type Ref } from "vue";
+import { api } from "../api";
+import {
+  INDEX_STATUS_LABELS,
+  STATUS_LABELS,
+  TAB_LABELS,
+  deriveExcerpt,
+  type BoardColumn,
+  type IndexStatus,
+  type KnowledgeLink,
+  type KnowledgeNote,
+  type KnowledgeProject,
+  type KnowledgeTask,
+  type KnowledgeViewTab,
+  type TaskStatus,
+} from "./useKnowledgeMock";
+
+/**
+ * Shared reactive data-source shape that both useKnowledgeMock and
+ * useKnowledgeApi satisfy. This is the contract useKnowledgeWorkspace (and the
+ * 14 knowledge components) depend on. `loadAll`/`ready` are API-only
+ * (mock is always ready synchronously).
+ */
+export interface KnowledgeDataSource {
+  loadAll?(): Promise<void>;
+  ready?: Ref<boolean>;
+  lastError: Ref<string | null>;
+  projects: Ref<KnowledgeProject[]>;
+  notes: Ref<KnowledgeNote[]>;
+  tasks: Ref<KnowledgeTask[]>;
+  columns: Ref<BoardColumn[]>;
+  indexStatus: Ref<IndexStatus>;
+  projectById: ComputedRef<Map<string, KnowledgeProject>>;
+  childrenByParentId: ComputedRef<Map<string, KnowledgeProject[]>>;
+  childProjects: (projectId: string) => KnowledgeProject[];
+  projectPath: (projectId: string) => KnowledgeProject[];
+  notesForProject: (projectId: string) => KnowledgeNote[];
+  tasksForProject: (projectId: string) => KnowledgeTask[];
+  columnsForProject: (projectId: string) => BoardColumn[];
+  links: ComputedRef<KnowledgeLink[]>;
+  createNote: (projectId: string, title: string) => KnowledgeNote;
+  updateNote: (id: string, patch: Partial<KnowledgeNote>) => void;
+  deleteNote: (id: string) => void;
+  createTask: (projectId: string, columnId: string, title: string) => KnowledgeTask | null;
+  updateTask: (id: string, patch: Partial<KnowledgeTask>) => void;
+  deleteTask: (id: string) => void;
+  moveTask: (taskId: string, targetColumnId: string, targetIndex: number) => void;
+  resolveLink: (label: string) => { type: "note" | "task"; id: string } | null;
+  backlinksFor: (id: string) => KnowledgeLink[];
+}
+
+/**
+ * Real-API data source for the knowledge workspace.
+ *
+ * Same return shape as `useKnowledgeMock` (so `useKnowledgeWorkspace` and the 14
+ * knowledge components need no changes), but the reactive collections are
+ * populated by `loadAll()` from the sidecar and writes are optimistic:
+ *   1. mutate the local reactive cache synchronously (returns the optimistic
+ *      object, matching the mock's sync signatures),
+ *   2. fire the API call in the background,
+ *   3. on success, reconcile the local object with the server response
+ *      (notably replace the optimistic id/timestamps with the canonical ones),
+ *   4. on failure, roll back the local mutation and surface the error.
+ *
+ * Local-first: the sidecar is on the same machine with negligible latency, so
+ * optimistic updates give instant feedback and failures are rare. We do not
+ * build a retry queue (YAGNI).
+ */
+
+const LINK_REGEX = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+
+function parseWikiLink(raw: string): { target: string } {
+  return { target: raw.split("|").map((s) => s.trim())[0] };
+}
+
+function resolveLinkTarget(
+  label: string,
+  noteByTitle: Map<string, KnowledgeNote>,
+  noteById: Map<string, KnowledgeNote>,
+  taskById: Map<string, KnowledgeTask>
+): { type: "note" | "task"; id: string } | null {
+  const key = label.toLowerCase();
+  const byTitle = noteByTitle.get(key);
+  if (byTitle) return { type: "note", id: byTitle.id };
+  const byId = noteById.get(label);
+  if (byId) return { type: "note", id: byId.id };
+  const task = taskById.get(label);
+  if (task) return { type: "task", id: task.id };
+  return null;
+}
+
+function scanLinks(notes: KnowledgeNote[], tasks: KnowledgeTask[]): KnowledgeLink[] {
+  const noteByTitle = new Map<string, KnowledgeNote>();
+  const noteById = new Map<string, KnowledgeNote>();
+  const taskById = new Map<string, KnowledgeTask>();
+  for (const note of notes) {
+    noteById.set(note.id, note);
+    noteByTitle.set(note.title.toLowerCase(), note);
+  }
+  for (const task of tasks) taskById.set(task.id, task);
+
+  const links: KnowledgeLink[] = [];
+  for (const note of notes) {
+    for (const match of note.body.matchAll(LINK_REGEX)) {
+      const { target } = parseWikiLink(match[1]);
+      const resolved = resolveLinkTarget(target, noteByTitle, noteById, taskById);
+      if (resolved) {
+        links.push({ sourceId: note.id, sourceType: "note", targetId: resolved.id, targetType: resolved.type, label: target });
+      }
+    }
+  }
+  return links;
+}
+
+function buildProjectById(projects: KnowledgeProject[]): Map<string, KnowledgeProject> {
+  return projects.reduce((map, p) => map.set(p.id, p), new Map<string, KnowledgeProject>());
+}
+
+function buildChildrenByParentId(projects: KnowledgeProject[]): Map<string, KnowledgeProject[]> {
+  const grouped = projects.reduce<Record<string, KnowledgeProject[]>>((acc, p) => {
+    const key = p.parentId ?? "__root__";
+    acc[key] = [...(acc[key] ?? []), p];
+    return acc;
+  }, {});
+  return Object.entries(grouped).reduce((map, [key, list]) => {
+    map.set(key, [...list].sort((a, b) => (a.order ?? 0) - (b.order ?? 0)));
+    return map;
+  }, new Map<string, KnowledgeProject[]>());
+}
+
+function uid(prefix: string): string {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function useKnowledgeApi(): KnowledgeDataSource {
+  const projects = ref<KnowledgeProject[]>([]);
+  const notesRef = ref<KnowledgeNote[]>([]);
+  const tasksRef = ref<KnowledgeTask[]>([]);
+  const columnsRef = ref<BoardColumn[]>([]);
+  const indexStatus = ref<IndexStatus>("ok");
+  const ready = ref(false);
+  const lastError = ref<string | null>(null);
+
+  const projectById = computed(() => buildProjectById(projects.value));
+  const childrenByParentId = computed(() => buildChildrenByParentId(projects.value));
+  const links = computed(() => scanLinks(notesRef.value, tasksRef.value));
+
+  async function loadAll(): Promise<void> {
+    try {
+      const [projectList, ...rest] = await Promise.all([
+        api.knowledgeListProjects(),
+        // also need columns/notes/tasks per project; fetch after we know projects
+      ]);
+      void rest;
+      projects.value = projectList;
+
+      // For each project load its notes/columns/tasks in parallel.
+      const ids = projectList.map((p) => p.id);
+      const [notesByProject, columnsByProject, tasksByProject] = await Promise.all([
+        Promise.all(ids.map((id) => api.knowledgeListNotes(id).catch(() => [] as KnowledgeNote[]))).then((arrs) => arrs.flat()),
+        Promise.all(ids.map((id) => api.knowledgeListColumns(id).catch(() => [] as BoardColumn[]))).then((arrs) => arrs.flat()),
+        Promise.all(ids.map((id) => api.knowledgeListTasks(id).catch(() => [] as KnowledgeTask[]))).then((arrs) => arrs.flat())
+      ]);
+      notesRef.value = notesByProject;
+      columnsRef.value = columnsByProject;
+      tasksRef.value = tasksByProject;
+
+      ready.value = true;
+      lastError.value = null;
+    } catch (error) {
+      ready.value = false;
+      lastError.value = error instanceof Error ? error.message : "加载知识库失败";
+      throw error;
+    }
+  }
+
+  function childProjects(projectId: string): KnowledgeProject[] {
+    return childrenByParentId.value.get(projectId) ?? [];
+  }
+
+  function projectPath(projectId: string): KnowledgeProject[] {
+    const path: KnowledgeProject[] = [];
+    let current = projectById.value.get(projectId);
+    while (current) {
+      path.unshift(current);
+      current = current.parentId ? projectById.value.get(current.parentId) : undefined;
+    }
+    return path;
+  }
+
+  function notesForProject(projectId: string): KnowledgeNote[] {
+    return notesRef.value.filter((n) => n.projectId === projectId);
+  }
+
+  function tasksForProject(projectId: string): KnowledgeTask[] {
+    return tasksRef.value.filter((t) => t.projectId === projectId);
+  }
+
+  function columnsForProject(projectId: string): BoardColumn[] {
+    return columnsRef.value.filter((c) => c.projectId === projectId).sort((a, b) => a.order - b.order);
+  }
+
+  // ── 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;
+    }, 5000);
+  }
+
+  function createNote(projectId: string, title: string): KnowledgeNote {
+    const now = Date.now();
+    const optimistic: KnowledgeNote = {
+      id: uid("n"),
+      projectId,
+      title: title.trim(),
+      body: `# ${title.trim()}\n\n`,
+      tags: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+    notesRef.value = [...notesRef.value, optimistic];
+
+    void api.knowledgeCreateNote(projectId, title)
+      .then((server) => {
+        notesRef.value = notesRef.value.map((n) => (n.id === optimistic.id ? server : n));
+      })
+      .catch((error: unknown) => {
+        notesRef.value = notesRef.value.filter((n) => n.id !== optimistic.id);
+        surfaceError(error, "创建笔记失败");
+      });
+    return optimistic;
+  }
+
+  function updateNote(id: string, patch: Partial<KnowledgeNote>): void {
+    const now = Date.now();
+    const allowed: Partial<KnowledgeNote> = {
+      title: patch.title,
+      body: patch.body,
+      tags: patch.tags,
+      projectId: patch.projectId,
+    };
+    const previous = notesRef.value;
+    notesRef.value = notesRef.value.map((n) => (n.id === id ? { ...n, ...allowed, updatedAt: now } : n));
+
+    void api.knowledgeUpdateNote(id, allowed as Partial<Pick<KnowledgeNote, "title" | "body" | "tags">>)
+      .catch((error: unknown) => {
+        notesRef.value = previous;
+        surfaceError(error, "保存笔记失败");
+      });
+  }
+
+  function deleteNote(id: string): void {
+    const previous = notesRef.value;
+    notesRef.value = notesRef.value.filter((n) => n.id !== id);
+    tasksRef.value = tasksRef.value.map((t) => (t.linkedNoteId === id ? { ...t, linkedNoteId: undefined } : t));
+
+    void api.knowledgeDeleteNote(id)
+      .catch((error: unknown) => {
+        notesRef.value = previous;
+        surfaceError(error, "删除笔记失败");
+      });
+  }
+
+  function createTask(projectId: string, columnId: string, title: string): KnowledgeTask | null {
+    const column = columnsRef.value.find((c) => c.id === columnId);
+    if (!column) return null;
+    const now = Date.now();
+    const maxOrder = tasksRef.value.filter((t) => t.columnId === columnId).reduce((max, t) => Math.max(max, t.order), -1);
+    const optimistic: KnowledgeTask = {
+      id: uid("t"),
+      projectId,
+      columnId,
+      title: title.trim(),
+      status: column.status,
+      order: maxOrder + 1,
+      tags: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+    tasksRef.value = [...tasksRef.value, optimistic];
+
+    void api.knowledgeCreateTask(projectId, columnId, title)
+      .then((server) => {
+        tasksRef.value = tasksRef.value.map((t) => (t.id === optimistic.id ? server : t));
+      })
+      .catch((error: unknown) => {
+        tasksRef.value = tasksRef.value.filter((t) => t.id !== optimistic.id);
+        surfaceError(error, "创建任务失败");
+      });
+    return optimistic;
+  }
+
+  function updateTask(id: string, patch: Partial<KnowledgeTask>): void {
+    const now = Date.now();
+    const previous = tasksRef.value;
+    tasksRef.value = tasksRef.value.map((t) => (t.id === id ? { ...t, ...patch, updatedAt: now } : t));
+
+    const apiPatch: Partial<Pick<KnowledgeTask, "title" | "description" | "status" | "columnId" | "order">> & { linkedNoteId?: string | null } = {
+      title: patch.title,
+      description: patch.description,
+      status: patch.status,
+      columnId: patch.columnId,
+      order: patch.order,
+      linkedNoteId: patch.linkedNoteId ?? null,
+    };
+    void api.knowledgeUpdateTask(id, apiPatch)
+      .catch((error: unknown) => {
+        tasksRef.value = previous;
+        surfaceError(error, "更新任务失败");
+      });
+  }
+
+  function deleteTask(id: string): void {
+    const previous = tasksRef.value;
+    tasksRef.value = tasksRef.value.filter((t) => t.id !== id);
+
+    void api.knowledgeDeleteTask(id)
+      .catch((error: unknown) => {
+        tasksRef.value = previous;
+        surfaceError(error, "删除任务失败");
+      });
+  }
+
+  function moveTask(taskId: string, targetColumnId: string, targetIndex: number): void {
+    const task = tasksRef.value.find((t) => t.id === taskId);
+    const targetColumn = columnsRef.value.find((c) => c.id === targetColumnId);
+    if (!task || !targetColumn) return;
+
+    const previous = tasksRef.value;
+    const others = tasksRef.value.filter((t) => t.id !== taskId);
+    const columnTasks = others.filter((t) => t.columnId === targetColumnId).sort((a, b) => a.order - b.order);
+    const before = columnTasks.slice(0, targetIndex);
+    const after = columnTasks.slice(targetIndex);
+    const nextTasks = others.filter((t) => t.columnId !== targetColumnId);
+    const movedTask: KnowledgeTask = { ...task, columnId: targetColumnId, status: targetColumn.status, updatedAt: Date.now() };
+    const reordered = [...before, movedTask, ...after].map((t, index) => ({ ...t, order: index }));
+    tasksRef.value = [...nextTasks, ...reordered];
+
+    void api.knowledgeMoveTask(taskId, targetColumnId, targetIndex)
+      .catch((error: unknown) => {
+        tasksRef.value = previous;
+        surfaceError(error, "移动任务失败");
+      });
+  }
+
+  function resolveLink(label: string): { type: "note" | "task"; id: string } | null {
+    const { target } = parseWikiLink(label);
+    const noteByTitle = new Map<string, KnowledgeNote>();
+    const noteById = new Map<string, KnowledgeNote>();
+    const taskById = new Map<string, KnowledgeTask>();
+    for (const note of notesRef.value) {
+      noteById.set(note.id, note);
+      noteByTitle.set(note.title.toLowerCase(), note);
+    }
+    for (const task of tasksRef.value) taskById.set(task.id, task);
+    return resolveLinkTarget(target, noteByTitle, noteById, taskById);
+  }
+
+  function backlinksFor(id: string): KnowledgeLink[] {
+    return links.value.filter((l) => l.targetId === id);
+  }
+
+  return {
+    loadAll,
+    lastError,
+    ready,
+    projects,
+    notes: notesRef,
+    tasks: tasksRef,
+    columns: columnsRef,
+    indexStatus,
+    projectById,
+    childrenByParentId,
+    childProjects,
+    projectPath,
+    notesForProject,
+    tasksForProject,
+    columnsForProject,
+    links,
+    createNote,
+    updateNote,
+    deleteNote,
+    createTask,
+    updateTask,
+    deleteTask,
+    moveTask,
+    resolveLink,
+    backlinksFor,
+  };
+}
+
+export type { BoardColumn, IndexStatus, KnowledgeLink, KnowledgeNote, KnowledgeProject, KnowledgeTask, KnowledgeViewTab, TaskStatus };
+export { deriveExcerpt, INDEX_STATUS_LABELS, STATUS_LABELS, TAB_LABELS };
diff --git a/apps/desktop/src/composables/useKnowledgeMock.ts b/apps/desktop/src/composables/useKnowledgeMock.ts
index 91e63b6..c55196c 100644
--- a/apps/desktop/src/composables/useKnowledgeMock.ts
+++ b/apps/desktop/src/composables/useKnowledgeMock.ts
@@ -1,28 +1,26 @@
 import { computed, ref } from "vue";
 
 /**
- * Knowledge workspace mock composable — 阶段 2（v1.5）：把笔记正文从 excerpt（HTML）
- * 升级为真正的 Markdown 字符串（body 字段），与 docs/ARCHITECTURE.md 第 717 行的
- * `Note { id, projectId, title, body, tags }` schema 对齐。仍是纯前端 mock，不连
- * sidecar/WS。
- *
- * 设计要点：
- * - body 是 markdown 全文（编辑器 single source of truth）；列表用 deriveExcerpt 从
- *   body 截取首段做摘要，避免重复存储。
- * - "收件箱" 项目 ID 固定为 "inbox"，对齐 PRD 4.1 不可缺省语义。
- * - indexStatus 区分 "ok" / "fts_only" / "indexing" 三态，对齐降级语义。
+ * Knowledge workspace mock composable — v2 redesign phase.
+ * 支持嵌套项目、按项目自定义看板列、笔记/任务 CRUD、双向链接扫描。
+ * 仍是纯前端 mock，不连 sidecar/WS，但数据模型与 docs/ARCHITECTURE.md 对齐。
  */
 
-export type KnowledgeViewKey = "notes" | "board" | "tasks";
+export type KnowledgeViewTab = "notes" | "board" | "tasks" | "projects";
 export type IndexStatus = "ok" | "fts_only" | "indexing";
+export type TaskStatus = "todo" | "doing" | "done" | "archived";
 
 export interface KnowledgeProject {
   id: string;
-  name: string;
-  noteCount: number;
-  taskCount: number;
-  boardCount: number;
+  title: string;
+  description?: string;
+  parentId: string | null;
+  color?: string;
+  icon?: string;
   isInbox?: boolean;
+  order: number;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export interface KnowledgeNote {
@@ -32,37 +30,111 @@ export interface KnowledgeNote {
   /** Markdown 全文（SSOT）。列表显示请用 `deriveExcerpt(body)` 派生。 */
   body: string;
   tags: string[];
-  /** 显示用文本，例如 "06·12 14:32"。 */
-  updatedAt: string;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export interface KnowledgeTask {
   id: string;
   projectId: string;
+  columnId: string;
   title: string;
-  status: "todo" | "doing" | "done" | "archived";
-  boardColumnId?: string;
+  description?: string;
+  status: TaskStatus;
+  order: number;
   linkedNoteId?: string;
   tags: string[];
+  createdAt: number;
+  updatedAt: number;
 }
 
-export interface BoardColumnMock {
+export interface BoardColumn {
   id: string;
+  projectId: string;
   title: string;
-  status: "todo" | "doing" | "done" | "archived";
+  status: TaskStatus;
+  order: number;
 }
 
+export interface KnowledgeLink {
+  sourceId: string;
+  sourceType: "note" | "task";
+  targetId: string;
+  targetType: "note" | "task";
+  label: string;
+}
+
+const NOW = Date.now();
+const DAY = 86_400_000;
+
 const PROJECTS: KnowledgeProject[] = [
-  { id: "inbox", name: "收件箱", noteCount: 3, taskCount: 5, boardCount: 0, isInbox: true },
-  { id: "proj-product", name: "产品研究", noteCount: 12, taskCount: 8, boardCount: 1 },
-  { id: "proj-learning", name: "学习笔记", noteCount: 7, taskCount: 3, boardCount: 1 },
-  { id: "proj-writing", name: "写作素材", noteCount: 5, taskCount: 1, boardCount: 0 },
+  {
+    id: "inbox",
+    title: "收件箱",
+    description: "临时想法与未分类内容",
+    parentId: null,
+    color: "#6b7280",
+    isInbox: true,
+    order: 0,
+    createdAt: NOW - DAY * 30,
+    updatedAt: NOW - DAY,
+  },
+  {
+    id: "proj-product",
+    title: "产品研究",
+    description: "NeoCompanion 产品方向与迭代",
+    parentId: null,
+    color: "#3b82f6",
+    order: 1,
+    createdAt: NOW - DAY * 20,
+    updatedAt: NOW - DAY * 2,
+  },
+  {
+    id: "proj-product-competitor",
+    title: "竞品调研",
+    description: "本地优先笔记与 AI 助手竞品",
+    parentId: "proj-product",
+    color: "#0ea5e9",
+    order: 0,
+    createdAt: NOW - DAY * 15,
+    updatedAt: NOW - DAY * 3,
+  },
+  {
+    id: "proj-product-user",
+    title: "用户研究",
+    description: "用户访谈与需求分析",
+    parentId: "proj-product",
+    color: "#8b5cf6",
+    order: 1,
+    createdAt: NOW - DAY * 12,
+    updatedAt: NOW - DAY * 4,
+  },
+  {
+    id: "proj-learning",
+    title: "学习笔记",
+    description: "技术、设计与阅读",
+    parentId: null,
+    color: "#22c55e",
+    order: 2,
+    createdAt: NOW - DAY * 18,
+    updatedAt: NOW - DAY * 1,
+  },
+  {
+    id: "proj-writing",
+    title: "写作素材",
+    description: "文章、文案与灵感",
+    parentId: null,
+    color: "#f59e0b",
+    order: 3,
+    createdAt: NOW - DAY * 10,
+    updatedAt: NOW - DAY * 5,
+  },
 ];
 
 const NOTES_INIT: KnowledgeNote[] = [
   {
     id: "n-001",
-    projectId: "proj-product",
+    projectId: "proj-product-competitor",
     title: "竞品分析：本地优先笔记应用",
     body:
       "# 竞品分析：本地优先笔记应用\n\n" +
@@ -72,13 +144,15 @@ const NOTES_INIT: KnowledgeNote[] = [
       "| Obsidian | ✅ Markdown 文件 | ✅ 强 | ⚠️ 插件 |\n" +
       "| Logseq | ✅ Markdown/Org | ✅ 强 | ⚠️ 插件 |\n" +
       "| Reflect | ⚠️ 云优先 | ✅ 中 | ✅ 内建 |\n\n" +
-      "结论：本地优先 + 内建 AI 检索是差异化方向。",
+      "结论：本地优先 + 内建 AI 检索是差异化方向。\n\n" +
+      "相关：[[Rust borrow checker 速记]]",
     tags: ["竞品", "调研"],
-    updatedAt: "06·12 14:32",
+    createdAt: NOW - DAY * 5,
+    updatedAt: NOW - DAY * 2,
   },
   {
     id: "n-002",
-    projectId: "proj-product",
+    projectId: "proj-product-user",
     title: "用户访谈纪要 · 06-10",
     body:
       "# 用户访谈纪要 · 06-10\n\n" +
@@ -90,7 +164,8 @@ const NOTES_INIT: KnowledgeNote[] = [
       "- 数据可导出：Markdown 即可\n\n" +
       "#访谈 #用户故事",
     tags: ["访谈", "用户故事"],
-    updatedAt: "06·11 09:18",
+    createdAt: NOW - DAY * 6,
+    updatedAt: NOW - DAY * 4,
   },
   {
     id: "n-003",
@@ -107,9 +182,11 @@ const NOTES_INIT: KnowledgeNote[] = [
       "- 未配置 Embedding Provider\n" +
       "- 云端额度不足或网络失败\n" +
       "- sqlite-vec 扩展加载失败\n\n" +
-      "任一条件触发后退化为纯 FTS5，并在 UI 显式标注「仅 FTS 可用」。",
+      "任一条件触发后退化为纯 FTS5，并在 UI 显式标注「仅 FTS 可用」。\n\n" +
+      "延伸阅读：[[竞品分析：本地优先笔记应用]]",
     tags: ["技术", "检索"],
-    updatedAt: "06·09 22:04",
+    createdAt: NOW - DAY * 8,
+    updatedAt: NOW - DAY * 3,
   },
   {
     id: "n-004",
@@ -128,7 +205,8 @@ const NOTES_INIT: KnowledgeNote[] = [
       "参考：[memos 项目首页](https://github.com/usememos/memos)\n\n" +
       "#设计 #v2",
     tags: ["设计", "v2"],
-    updatedAt: "06·08 16:50",
+    createdAt: NOW - DAY * 10,
+    updatedAt: NOW - DAY * 6,
   },
   {
     id: "n-005",
@@ -137,11 +215,12 @@ const NOTES_INIT: KnowledgeNote[] = [
     body:
       "# 降级体验文案\n\n" +
       "Embedding 不可用时如何向用户清晰说明，避免误以为 AI 在编造。\n\n" +
-      "原则：*告诉用户当前能力的真实边界*，使用 `仅 FTS 可用` 这种带形容词的明确文案，\n" +
+      "原则：*告诉用户当前能力的真实边界*，使用 `仅 FTS 可用` 这种带形容词的明确文案，" +
       "而不是模糊的 `检索受限`。\n\n" +
       "#文案",
     tags: ["文案"],
-    updatedAt: "06·06 11:22",
+    createdAt: NOW - DAY * 12,
+    updatedAt: NOW - DAY * 8,
   },
   {
     id: "n-006",
@@ -158,42 +237,76 @@ const NOTES_INIT: KnowledgeNote[] = [
       "3. 字段级借用：编译器能识别 struct 字段独立\n\n" +
       "#Rust #笔记",
     tags: ["Rust", "笔记"],
-    updatedAt: "06·12 23:18",
+    createdAt: NOW - DAY * 4,
+    updatedAt: NOW - DAY * 1,
+  },
+  {
+    id: "n-007",
+    projectId: "inbox",
+    title: "临时想法：AI 引用卡片",
+    body:
+      "# 临时想法：AI 引用卡片\n\n" +
+      "在 AI 回答里把引用来源做成可点击卡片，跳转到对应笔记段落。\n\n" +
+      "参考：[[FTS5 与 sqlite-vec 融合策略]]",
+    tags: ["想法"],
+    createdAt: NOW - DAY * 2,
+    updatedAt: NOW - DAY * 1,
   },
 ];
 
-const TASKS: KnowledgeTask[] = [
-  { id: "t-101", projectId: "proj-product", title: "整理 6 月用户访谈共性问题", status: "doing", boardColumnId: "col-doing", linkedNoteId: "n-002", tags: ["访谈"] },
-  { id: "t-102", projectId: "proj-product", title: "草拟 v2 看板拖拽交互", status: "todo", boardColumnId: "col-todo", linkedNoteId: "n-004", tags: ["设计"] },
-  { id: "t-103", projectId: "proj-product", title: "对比 chunk 大小 800 / 1200 / 1600", status: "todo", boardColumnId: "col-todo", linkedNoteId: "n-003", tags: ["技术"] },
-  { id: "t-104", projectId: "proj-product", title: "确认 sqlite-vec 在 Windows ARM 上的可行性", status: "doing", boardColumnId: "col-doing", tags: ["技术"] },
-  { id: "t-105", projectId: "proj-product", title: "降级文案 Review", status: "done", boardColumnId: "col-done", linkedNoteId: "n-005", tags: ["文案"] },
-  { id: "t-106", projectId: "proj-product", title: "归档 5 月旧迭代记录", status: "archived", boardColumnId: "col-archived", tags: [] },
-  { id: "t-107", projectId: "proj-product", title: "整理 RRF 公式来源出处", status: "done", boardColumnId: "col-done", linkedNoteId: "n-003", tags: ["技术"] },
-  { id: "t-108", projectId: "proj-product", title: "导出本周专注热力图", status: "todo", boardColumnId: "col-todo", tags: [] },
+const BOARD_COLUMNS_INIT: BoardColumn[] = [
+  { id: "col-product-todo", projectId: "proj-product", title: "待办", status: "todo", order: 0 },
+  { id: "col-product-doing", projectId: "proj-product", title: "进行中", status: "doing", order: 1 },
+  { id: "col-product-done", projectId: "proj-product", title: "已完成", status: "done", order: 2 },
+  { id: "col-competitor-todo", projectId: "proj-product-competitor", title: "待调研", status: "todo", order: 0 },
+  { id: "col-competitor-done", projectId: "proj-product-competitor", title: "已整理", status: "done", order: 1 },
+  { id: "col-user-todo", projectId: "proj-product-user", title: "待访谈", status: "todo", order: 0 },
+  { id: "col-user-doing", projectId: "proj-product-user", title: "分析中", status: "doing", order: 1 },
+  { id: "col-user-done", projectId: "proj-product-user", title: "已归档", status: "done", order: 2 },
+  { id: "col-learning-todo", projectId: "proj-learning", title: "待学", status: "todo", order: 0 },
+  { id: "col-learning-done", projectId: "proj-learning", title: "已总结", status: "done", order: 1 },
+  { id: "col-writing-todo", projectId: "proj-writing", title: "素材", status: "todo", order: 0 },
+  { id: "col-writing-done", projectId: "proj-writing", title: "成稿", status: "done", order: 1 },
+  { id: "col-inbox-todo", projectId: "inbox", title: "待处理", status: "todo", order: 0 },
+  { id: "col-inbox-done", projectId: "inbox", title: "已归档", status: "done", order: 1 },
 ];
 
-const BOARD_COLUMNS: BoardColumnMock[] = [
-  { id: "col-todo", title: "待办", status: "todo" },
-  { id: "col-doing", title: "进行中", status: "doing" },
-  { id: "col-done", title: "已完成", status: "done" },
-  { id: "col-archived", title: "归档", status: "archived" },
+const TASKS_INIT: KnowledgeTask[] = [
+  { id: "t-101", projectId: "proj-product-user", columnId: "col-user-doing", title: "整理 6 月用户访谈共性问题", status: "doing", order: 0, linkedNoteId: "n-002", tags: ["访谈"], createdAt: NOW - DAY * 4, updatedAt: NOW - DAY * 1 },
+  { id: "t-102", projectId: "proj-product", columnId: "col-product-todo", title: "草拟 v2 看板拖拽交互", status: "todo", order: 0, linkedNoteId: "n-004", tags: ["设计"], createdAt: NOW - DAY * 5, updatedAt: NOW - DAY * 2 },
+  { id: "t-103", projectId: "proj-product", columnId: "col-product-todo", title: "对比 chunk 大小 800 / 1200 / 1600", status: "todo", order: 1, linkedNoteId: "n-003", tags: ["技术"], createdAt: NOW - DAY * 5, updatedAt: NOW - DAY * 2 },
+  { id: "t-104", projectId: "proj-product", columnId: "col-product-doing", title: "确认 sqlite-vec 在 Windows ARM 上的可行性", status: "doing", order: 0, tags: ["技术"], createdAt: NOW - DAY * 3, updatedAt: NOW - DAY * 1 },
+  { id: "t-105", projectId: "proj-product", columnId: "col-product-done", title: "降级文案 Review", status: "done", order: 0, linkedNoteId: "n-005", tags: ["文案"], createdAt: NOW - DAY * 8, updatedAt: NOW - DAY * 6 },
+  { id: "t-106", projectId: "proj-product", columnId: "col-product-done", title: "归档 5 月旧迭代记录", status: "done", order: 1, tags: [], createdAt: NOW - DAY * 10, updatedAt: NOW - DAY * 8 },
+  { id: "t-107", projectId: "proj-product-competitor", columnId: "col-competitor-done", title: "整理 RRF 公式来源出处", status: "done", order: 0, linkedNoteId: "n-003", tags: ["技术"], createdAt: NOW - DAY * 6, updatedAt: NOW - DAY * 4 },
+  { id: "t-108", projectId: "proj-learning", columnId: "col-learning-todo", title: "导出本周专注热力图", status: "todo", order: 0, tags: [], createdAt: NOW - DAY * 2, updatedAt: NOW - DAY * 1 },
+  { id: "t-109", projectId: "inbox", columnId: "col-inbox-todo", title: "把 AI 引用卡片想法写成笔记", status: "todo", order: 0, linkedNoteId: "n-007", tags: ["想法"], createdAt: NOW - DAY * 1, updatedAt: NOW - DAY * 1 },
 ];
 
-/**
- * 从 markdown body 中派生列表用摘要：取第一段非标题/非空白文本，去掉常见 markdown 标记。
- * 实现简单，够列表展示用；不追求完整反 markdown 解析。
- */
+let nextId = 1000;
+
+function uid(prefix: string): string {
+  nextId += 1;
+  return `${prefix}-${String(nextId).padStart(4, "0")}`;
+}
+
+export function formatKwTime(timestamp: number): string {
+  const d = new Date(timestamp);
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  return `${m}·${day} ${hh}:${mm}`;
+}
+
 export function deriveExcerpt(body: string, maxChars = 120): string {
   if (!body) return "";
   const blocks = body.split(/\n{2,}/);
   for (const block of blocks) {
     const trimmed = block.trim();
     if (!trimmed) continue;
-    // 跳过标题、引用、代码块、列表项符号
     if (/^(#{1,6}\s|>\s|```|---|\[)/.test(trimmed)) continue;
     if (/^[*\-+]\s|^\d+\.\s/.test(trimmed)) {
-      // 列表项也可作摘要，但去掉前缀
       const stripped = trimmed.replace(/^[*\-+]\s|^\d+\.\s/, "");
       return clampExcerpt(stripMarkdown(stripped), maxChars);
     }
@@ -204,11 +317,11 @@ export function deriveExcerpt(body: string, maxChars = 120): string {
 
 function stripMarkdown(text: string): string {
   return text
-    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1") // 链接 / 图片 → alt 文本
-    .replace(/`([^`]+)`/g, "$1") // 行内 code
-    .replace(/\*\*([^*]+)\*\*/g, "$1") // 粗体
-    .replace(/\*([^*]+)\*/g, "$1") // 斜体
-    .replace(/[#>*_~`]/g, "") // 残留符号
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\*([^*]+)\*/g, "$1")
+    .replace(/[#>*_~`]/g, "")
     .replace(/\s+/g, " ")
     .trim();
 }
@@ -218,90 +331,276 @@ function clampExcerpt(text: string, maxChars: number): string {
   return `${text.slice(0, maxChars - 1)}…`;
 }
 
-function formatNowKwStyle(): string {
-  const now = new Date();
-  const m = String(now.getMonth() + 1).padStart(2, "0");
-  const d = String(now.getDate()).padStart(2, "0");
-  const hh = String(now.getHours()).padStart(2, "0");
-  const mm = String(now.getMinutes()).padStart(2, "0");
-  return `${m}·${d} ${hh}:${mm}`;
+const LINK_REGEX = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+
+function parseWikiLink(raw: string): { target: string; display: string } {
+  const parts = raw.split("|").map((s) => s.trim());
+  const target = parts[0];
+  const display = parts[1] ?? target;
+  return { target, display };
+}
+
+function scanLinks(notes: KnowledgeNote[], tasks: KnowledgeTask[]): KnowledgeLink[] {
+  const noteByTitle = new Map<string, KnowledgeNote>();
+  const noteById = new Map<string, KnowledgeNote>();
+  const taskById = new Map<string, KnowledgeTask>();
+
+  for (const note of notes) {
+    noteById.set(note.id, note);
+    noteByTitle.set(note.title.toLowerCase(), note);
+  }
+  for (const task of tasks) {
+    taskById.set(task.id, task);
+  }
+
+  const links: KnowledgeLink[] = [];
+
+  for (const note of notes) {
+    for (const match of note.body.matchAll(LINK_REGEX)) {
+      const { target } = parseWikiLink(match[1]);
+      const resolved = resolveLinkTarget(target, noteByTitle, noteById, taskById);
+      if (resolved) {
+        links.push({
+          sourceId: note.id,
+          sourceType: "note",
+          targetId: resolved.id,
+          targetType: resolved.type,
+          label: target,
+        });
+      }
+    }
+  }
+
+  return links;
+}
+
+function resolveLinkTarget(
+  label: string,
+  noteByTitle: Map<string, KnowledgeNote>,
+  noteById: Map<string, KnowledgeNote>,
+  taskById: Map<string, KnowledgeTask>,
+): { type: "note" | "task"; id: string } | null {
+  const key = label.toLowerCase();
+  const noteByTitleMatch = noteByTitle.get(key);
+  if (noteByTitleMatch) return { type: "note", id: noteByTitleMatch.id };
+  const noteByIdMatch = noteById.get(label);
+  if (noteByIdMatch) return { type: "note", id: noteByIdMatch.id };
+  const taskByIdMatch = taskById.get(label);
+  if (taskByIdMatch) return { type: "task", id: taskByIdMatch.id };
+  return null;
 }
 
 export function useKnowledgeMock() {
-  const projects = ref<KnowledgeProject[]>(PROJECTS);
+  const projects = ref<KnowledgeProject[]>([...PROJECTS]);
   const notesRef = ref<KnowledgeNote[]>([...NOTES_INIT]);
-  const activeProjectId = ref<string>("proj-product");
-  const activeView = ref<KnowledgeViewKey>("notes");
-  const activeNoteId = ref<string>("n-003");
-  const searchQuery = ref<string>("");
+  const tasksRef = ref<KnowledgeTask[]>([...TASKS_INIT]);
+  const columnsRef = ref<BoardColumn[]>([...BOARD_COLUMNS_INIT]);
   const indexStatus = ref<IndexStatus>("ok");
+  // Mock is always ready synchronously; satisfies KnowledgeDataSource.
+  const lastError = ref<string | null>(null);
 
-  const activeProject = computed<KnowledgeProject | null>(
-    () => projects.value.find((p) => p.id === activeProjectId.value) ?? null,
-  );
+  const projectById = computed(() => buildProjectById(projects.value));
+  const childrenByParentId = computed(() => buildChildrenByParentId(projects.value));
+  const links = computed(() => scanLinks(notesRef.value, tasksRef.value));
 
-  const projectNotes = computed<KnowledgeNote[]>(() =>
-    notesRef.value.filter((n) => n.projectId === activeProjectId.value),
-  );
+  function childProjects(projectId: string): KnowledgeProject[] {
+    return childrenByParentId.value.get(projectId) ?? [];
+  }
 
-  const projectTasks = computed<KnowledgeTask[]>(() =>
-    TASKS.filter((t) => t.projectId === activeProjectId.value),
-  );
+  function projectPath(projectId: string): KnowledgeProject[] {
+    const path: KnowledgeProject[] = [];
+    let current = projectById.value.get(projectId);
+    while (current) {
+      path.unshift(current);
+      current = current.parentId ? projectById.value.get(current.parentId) : undefined;
+    }
+    return path;
+  }
 
-  const activeNote = computed<KnowledgeNote | null>(() => {
-    const list = projectNotes.value;
-    return list.find((n) => n.id === activeNoteId.value) ?? list[0] ?? null;
-  });
+  function notesForProject(projectId: string): KnowledgeNote[] {
+    return notesRef.value.filter((n) => n.projectId === projectId);
+  }
 
-  function selectProject(id: string): void {
-    activeProjectId.value = id;
-    const firstNote = notesRef.value.find((n) => n.projectId === id);
-    activeNoteId.value = firstNote?.id ?? "";
+  function tasksForProject(projectId: string): KnowledgeTask[] {
+    return tasksRef.value.filter((t) => t.projectId === projectId);
   }
 
-  function selectView(view: KnowledgeViewKey): void {
-    activeView.value = view;
+  function columnsForProject(projectId: string): BoardColumn[] {
+    return columnsRef.value
+      .filter((c) => c.projectId === projectId)
+      .sort((a, b) => a.order - b.order);
   }
 
-  function selectNote(id: string): void {
-    activeNoteId.value = id;
+  function createNote(projectId: string, title: string): KnowledgeNote {
+    const now = Date.now();
+    const note: KnowledgeNote = {
+      id: uid("n"),
+      projectId,
+      title: title.trim(),
+      body: `# ${title.trim()}\n\n`,
+      tags: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+    notesRef.value = [...notesRef.value, note];
+    return note;
   }
 
-  /**
-   * 写入笔记正文（仅内存，刷新即丢失，符合 mock 范围）。
-   */
-  function setNoteBody(id: string, body: string): void {
-    const next = notesRef.value.map((n) =>
-      n.id === id ? { ...n, body, updatedAt: formatNowKwStyle() } : n,
+  function updateNote(id: string, patch: Partial<KnowledgeNote>): void {
+    const now = Date.now();
+    const allowed: Partial<KnowledgeNote> = {
+      title: patch.title,
+      body: patch.body,
+      tags: patch.tags,
+      projectId: patch.projectId,
+    };
+    notesRef.value = notesRef.value.map((n) =>
+      n.id === id ? { ...n, ...allowed, updatedAt: now } : n,
     );
-    notesRef.value = next;
+  }
+
+  function deleteNote(id: string): void {
+    notesRef.value = notesRef.value.filter((n) => n.id !== id);
+    tasksRef.value = tasksRef.value.map((t) =>
+      t.linkedNoteId === id ? { ...t, linkedNoteId: undefined } : t,
+    );
+  }
+
+  function createTask(projectId: string, columnId: string, title: string): KnowledgeTask | null {
+    const column = columnsRef.value.find((c) => c.id === columnId);
+    if (!column) return null;
+    const now = Date.now();
+    const maxOrder = tasksRef.value
+      .filter((t) => t.columnId === columnId)
+      .reduce((max, t) => Math.max(max, t.order), -1);
+    const task: KnowledgeTask = {
+      id: uid("t"),
+      projectId,
+      columnId,
+      title: title.trim(),
+      status: column.status,
+      order: maxOrder + 1,
+      tags: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+    tasksRef.value = [...tasksRef.value, task];
+    return task;
+  }
+
+  function updateTask(id: string, patch: Partial<KnowledgeTask>): void {
+    const now = Date.now();
+    tasksRef.value = tasksRef.value.map((t) =>
+      t.id === id ? { ...t, ...patch, updatedAt: now } : t,
+    );
+  }
+
+  function deleteTask(id: string): void {
+    tasksRef.value = tasksRef.value.filter((t) => t.id !== id);
+  }
+
+  function moveTask(taskId: string, targetColumnId: string, targetIndex: number): void {
+    const task = tasksRef.value.find((t) => t.id === taskId);
+    const targetColumn = columnsRef.value.find((c) => c.id === targetColumnId);
+    if (!task || !targetColumn) return;
+
+    const others = tasksRef.value.filter((t) => t.id !== taskId);
+    const columnTasks = others
+      .filter((t) => t.columnId === targetColumnId)
+      .sort((a, b) => a.order - b.order);
+    const before = columnTasks.slice(0, targetIndex);
+    const after = columnTasks.slice(targetIndex);
+
+    const nextTasks = others.filter((t) => t.columnId !== targetColumnId);
+
+    const movedTask: KnowledgeTask = {
+      ...task,
+      columnId: targetColumnId,
+      status: targetColumn.status,
+      updatedAt: Date.now(),
+    };
+
+    const reordered = [...before, movedTask, ...after].map((t, index) => ({
+      ...t,
+      order: index,
+    }));
+
+    tasksRef.value = [...nextTasks, ...reordered];
+  }
+
+  function resolveLink(label: string): { type: "note" | "task"; id: string } | null {
+    const { target } = parseWikiLink(label);
+    const noteByTitle = new Map<string, KnowledgeNote>();
+    const noteById = new Map<string, KnowledgeNote>();
+    const taskById = new Map<string, KnowledgeTask>();
+    for (const note of notesRef.value) {
+      noteById.set(note.id, note);
+      noteByTitle.set(note.title.toLowerCase(), note);
+    }
+    for (const task of tasksRef.value) {
+      taskById.set(task.id, task);
+    }
+    return resolveLinkTarget(target, noteByTitle, noteById, taskById);
+  }
+
+  function backlinksFor(id: string): KnowledgeLink[] {
+    return links.value.filter((l) => l.targetId === id);
   }
 
   return {
     projects,
-    activeProject,
-    activeProjectId,
-    activeView,
-    activeNoteId,
-    activeNote,
-    projectNotes,
-    projectTasks,
-    boardColumns: ref<BoardColumnMock[]>(BOARD_COLUMNS),
-    searchQuery,
+    notes: notesRef,
+    tasks: tasksRef,
+    columns: columnsRef,
     indexStatus,
-    selectProject,
-    selectView,
-    selectNote,
-    setNoteBody,
+    lastError,
+    projectById,
+    childrenByParentId,
+    childProjects,
+    projectPath,
+    notesForProject,
+    tasksForProject,
+    columnsForProject,
+    links,
+    createNote,
+    updateNote,
+    deleteNote,
+    createTask,
+    updateTask,
+    deleteTask,
+    moveTask,
+    resolveLink,
+    backlinksFor,
   };
 }
 
+function buildProjectById(projects: KnowledgeProject[]): Map<string, KnowledgeProject> {
+  return projects.reduce((map, p) => {
+    map.set(p.id, p);
+    return map;
+  }, new Map<string, KnowledgeProject>());
+}
+
+function buildChildrenByParentId(projects: KnowledgeProject[]): Map<string, KnowledgeProject[]> {
+  const grouped = projects.reduce<Record<string, KnowledgeProject[]>>((acc, p) => {
+    const key = p.parentId ?? "__root__";
+    acc[key] = [...(acc[key] ?? []), p];
+    return acc;
+  }, {});
+
+  return Object.entries(grouped).reduce((map, [key, list]) => {
+    map.set(key, [...list].sort((a, b) => (a.order ?? 0) - (b.order ?? 0)));
+    return map;
+  }, new Map<string, KnowledgeProject[]>());
+}
+
 export type KnowledgeMockState = ReturnType<typeof useKnowledgeMock>;
 
-export const VIEW_LABELS: Record<KnowledgeViewKey, string> = {
+export const TAB_LABELS: Record<KnowledgeViewTab, string> = {
   notes: "笔记",
   board: "看板",
   tasks: "任务",
+  projects: "子项目",
 };
 
 export const INDEX_STATUS_LABELS: Record<IndexStatus, string> = {
@@ -309,3 +608,10 @@ export const INDEX_STATUS_LABELS: Record<IndexStatus, string> = {
   fts_only: "仅 FTS 可用",
   indexing: "索引中…",
 };
+
+export const STATUS_LABELS: Record<TaskStatus, string> = {
+  todo: "待办",
+  doing: "进行中",
+  done: "已完成",
+  archived: "已归档",
+};
diff --git a/apps/desktop/src/composables/useKnowledgeWorkspace.ts b/apps/desktop/src/composables/useKnowledgeWorkspace.ts
new file mode 100644
index 0000000..ac307c6
--- /dev/null
+++ b/apps/desktop/src/composables/useKnowledgeWorkspace.ts
@@ -0,0 +1,268 @@
+import { computed, ref, shallowRef } from "vue";
+import {
+  formatKwTime,
+  useKnowledgeMock,
+  type BoardColumn,
+  type KnowledgeLink,
+  type KnowledgeNote,
+  type KnowledgeProject,
+  type KnowledgeTask,
+  type KnowledgeViewTab,
+} from "./useKnowledgeMock";
+import { useKnowledgeApi, type KnowledgeDataSource } from "./useKnowledgeApi";
+
+/**
+ * Knowledge workspace orchestration composable.
+ * Builds on a data source (real API with mock fallback) to provide navigation,
+ * selection, CRUD, drag-and-drop, and bidirectional link resolution scoped to a
+ * project. The data source's reactive collections and sync CRUD signatures are
+ * shared between useKnowledgeMock and useKnowledgeApi, so this orchestration
+ * layer (and the 14 knowledge components) is source-agnostic.
+ */
+
+export function useKnowledgeWorkspace() {
+  const apiSource = useKnowledgeApi();
+  const mock = useKnowledgeMock();
+
+  // Live data source: real API when available, mock on failure (local preview).
+  // shallowRef avoids Vue deep-unwrapping the nested Refs inside the data source.
+  const source = shallowRef<KnowledgeDataSource>(apiSource);
+  const fallbackToMock = ref(false);
+  const loadError = ref<string | null>(null);
+
+  async function loadAll(): Promise<void> {
+    try {
+      await apiSource.loadAll?.();
+      source.value = apiSource;
+      fallbackToMock.value = false;
+      loadError.value = null;
+    } catch {
+      // sidecar unavailable (e.g. sqlite not loaded) → local mock preview
+      source.value = mock;
+      fallbackToMock.value = true;
+      loadError.value = "后端知识库未就绪，当前为本地预览数据。";
+    }
+  }
+
+  const data = computed(() => source.value);
+  const usingApi = computed(() => source.value === apiSource);
+
+  const currentProjectId = ref<string | null>(null);
+  const activeTab = ref<KnowledgeViewTab>("notes");
+  const selectedNoteId = ref<string | null>(null);
+  const selectedTaskId = ref<string | null>(null);
+
+  const currentProject = computed<KnowledgeProject | null>(
+    () => (currentProjectId.value ? data.value.projectById.value.get(currentProjectId.value) ?? null : null),
+  );
+
+  const projectPath = computed<KnowledgeProject[]>(() =>
+    currentProjectId.value ? data.value.projectPath(currentProjectId.value) : [],
+  );
+
+  const childProjects = computed<KnowledgeProject[]>(() =>
+    currentProjectId.value ? data.value.childProjects(currentProjectId.value) : [],
+  );
+
+  const hasChildren = computed<boolean>(() => childProjects.value.length > 0);
+
+  const currentNotes = computed<KnowledgeNote[]>(() =>
+    currentProjectId.value ? data.value.notesForProject(currentProjectId.value) : [],
+  );
+
+  const currentTasks = computed<KnowledgeTask[]>(() =>
+    currentProjectId.value ? data.value.tasksForProject(currentProjectId.value) : [],
+  );
+
+  const currentColumns = computed<BoardColumn[]>(() =>
+    currentProjectId.value ? data.value.columnsForProject(currentProjectId.value) : [],
+  );
+
+  const activeNote = computed<KnowledgeNote | null>(() => {
+    const list = currentNotes.value;
+    return list.find((n) => n.id === selectedNoteId.value) ?? list[0] ?? null;
+  });
+
+  const activeTask = computed<KnowledgeTask | null>(() => {
+    const list = currentTasks.value;
+    return list.find((t) => t.id === selectedTaskId.value) ?? null;
+  });
+
+  function enterProject(id: string): void {
+    currentProjectId.value = id;
+    activeTab.value = "notes";
+    selectedNoteId.value = null;
+    selectedTaskId.value = null;
+  }
+
+  function exitToParent(): void {
+    const parentId = currentProject.value?.parentId;
+    currentProjectId.value = parentId ?? null;
+    selectedNoteId.value = null;
+    selectedTaskId.value = null;
+  }
+
+  function selectRoot(): void {
+    currentProjectId.value = null;
+    activeTab.value = "projects";
+    selectedNoteId.value = null;
+    selectedTaskId.value = null;
+  }
+
+  function selectTab(tab: KnowledgeViewTab): void {
+    activeTab.value = tab;
+  }
+
+  function selectNote(id: string | null): void {
+    selectedNoteId.value = id;
+  }
+
+  function selectTask(id: string | null): void {
+    selectedTaskId.value = id;
+  }
+
+  function createNote(title: string): KnowledgeNote | null {
+    const projectId = currentProjectId.value;
+    if (!projectId) return null;
+    const note = data.value.createNote(projectId, title);
+    selectedNoteId.value = note.id;
+    activeTab.value = "notes";
+    return note;
+  }
+
+  function updateNoteBody(id: string, body: string): void {
+    data.value.updateNote(id, { body });
+  }
+
+  function deleteNote(id: string): void {
+    data.value.deleteNote(id);
+    if (selectedNoteId.value === id) {
+      selectedNoteId.value = currentNotes.value[0]?.id ?? null;
+    }
+  }
+
+  function createTask(columnId: string, title: string): KnowledgeTask | null {
+    const projectId = currentProjectId.value;
+    if (!projectId) return null;
+    const task = data.value.createTask(projectId, columnId, title);
+    if (!task) return null;
+    activeTab.value = "board";
+    return task;
+  }
+
+  function updateTaskStatus(id: string, status: KnowledgeTask["status"]): void {
+    const column = currentColumns.value.find((c) => c.status === status);
+    if (!column) return;
+    data.value.updateTask(id, { status, columnId: column.id });
+  }
+
+  function deleteTask(id: string): void {
+    data.value.deleteTask(id);
+    if (selectedTaskId.value === id) {
+      selectedTaskId.value = null;
+    }
+  }
+
+  function moveTask(taskId: string, targetColumnId: string, targetIndex: number): void {
+    data.value.moveTask(taskId, targetColumnId, targetIndex);
+  }
+
+  function resolveLink(label: string): { type: "note" | "task"; id: string } | null {
+    return data.value.resolveLink(label);
+  }
+
+  function followLink(label: string): boolean {
+    const target = resolveLink(label);
+    if (!target) return false;
+    if (target.type === "note") {
+      const note = data.value.notes.value.find((n) => n.id === target.id);
+      if (!note) return false;
+      enterProject(note.projectId);
+      selectNote(note.id);
+      activeTab.value = "notes";
+      return true;
+    }
+    const task = data.value.tasks.value.find((t) => t.id === target.id);
+    if (!task) return false;
+    enterProject(task.projectId);
+    selectTask(task.id);
+    activeTab.value = "tasks";
+    return true;
+  }
+
+  function backlinksFor(id: string): KnowledgeLink[] {
+    return data.value.backlinksFor(id);
+  }
+
+  function childProjectsOf(projectId: string): KnowledgeProject[] {
+    return data.value.childProjects(projectId);
+  }
+
+  function countNotes(projectId: string): number {
+    return data.value.notes.value.filter((n) => n.projectId === projectId).length;
+  }
+
+  function countTasks(projectId: string): number {
+    return data.value.tasks.value.filter((t) => t.projectId === projectId).length;
+  }
+
+  return {
+    // Data source lifecycle
+    loadAll,
+    ready: computed(() => (usingApi.value ? apiSource.ready?.value ?? true : true)),
+    loadError,
+    fallbackToMock,
+
+    // Navigation
+    currentProjectId,
+    currentProject,
+    projectPath,
+    childProjects,
+    childProjectsOf,
+    hasChildren,
+    enterProject,
+    exitToParent,
+    selectRoot,
+
+    // Tabs
+    activeTab,
+    selectTab,
+
+    // Notes
+    currentNotes,
+    activeNote,
+    selectedNoteId,
+    selectNote,
+    createNote,
+    updateNoteBody,
+    deleteNote,
+    countNotes,
+
+    // Tasks / Board
+    currentTasks,
+    activeTask,
+    selectedTaskId,
+    selectTask,
+    currentColumns,
+    createTask,
+    updateTaskStatus,
+    deleteTask,
+    moveTask,
+    countTasks,
+
+    // Links
+    links: computed(() => data.value.links.value),
+    resolveLink,
+    followLink,
+    backlinksFor,
+
+    // Shared
+    projects: computed(() => data.value.projects.value),
+    allNotes: computed(() => data.value.notes.value),
+    allTasks: computed(() => data.value.tasks.value),
+    indexStatus: computed(() => data.value.indexStatus.value),
+    formatKwTime,
+  };
+}
+
+export type KnowledgeWorkspaceState = ReturnType<typeof useKnowledgeWorkspace>;
diff --git a/apps/desktop/src/views/KnowledgeView.vue b/apps/desktop/src/views/KnowledgeView.vue
index 313d644..a8b2c9b 100644
--- a/apps/desktop/src/views/KnowledgeView.vue
+++ b/apps/desktop/src/views/KnowledgeView.vue
@@ -1,73 +1,56 @@
 <script setup lang="ts">
-import { ref } from "vue";
-import { useKnowledgeMock } from "../composables/useKnowledgeMock";
-import ProjectSidebar from "../components/knowledge/ProjectSidebar.vue";
-import KnowledgeTopbar from "../components/knowledge/KnowledgeTopbar.vue";
-import NotesPane from "../components/knowledge/NotesPane.vue";
-import BoardPane from "../components/knowledge/BoardPane.vue";
-import TasksPane from "../components/knowledge/TasksPane.vue";
-
-const knowledge = useKnowledgeMock();
-const editing = ref(false);
-
-function toggleEditing(): void {
-  editing.value = !editing.value;
-}
-
-function handleBodyUpdate(body: string): void {
-  if (!knowledge.activeNoteId.value) return;
-  knowledge.setNoteBody(knowledge.activeNoteId.value, body);
-}
+import { onMounted } from "vue";
+import { useKnowledgeWorkspace } from "../composables/useKnowledgeWorkspace";
+import { useTheme } from "../composables/useTheme";
+import ProjectBrowser from "../components/knowledge/ProjectBrowser.vue";
+import ProjectWorkspace from "../components/knowledge/ProjectWorkspace.vue";
+import BreadcrumbNav from "../components/knowledge/BreadcrumbNav.vue";
+import ThemeToggle from "../components/knowledge/ThemeToggle.vue";
+
+const workspace = useKnowledgeWorkspace();
+const theme = useTheme();
+
+onMounted(() => {
+  void workspace.loadAll();
+});
 </script>
 
 <template>
-  <div class="knowledge-root" data-view="knowledge">
-    <ProjectSidebar
-      :projects="knowledge.projects.value"
-      :active-project-id="knowledge.activeProjectId.value"
-      @select="knowledge.selectProject"
-    />
-
-    <main class="knowledge-main">
-      <KnowledgeTopbar
-        :project="knowledge.activeProject.value"
-        :active-view="knowledge.activeView.value"
-        :search-query="knowledge.searchQuery.value"
-        :index-status="knowledge.indexStatus.value"
-        @select-view="knowledge.selectView"
-        @update:search-query="knowledge.searchQuery.value = $event"
-      />
-
-      <div v-if="knowledge.activeView.value === 'notes'" class="knowledge-edit-strip">
-        <button
-          type="button"
-          class="preview-edit"
-          :class="{ 'is-editing': editing }"
-          :disabled="!knowledge.activeNote.value"
-          @click="toggleEditing"
-        >
-          {{ editing ? "完成" : "编辑" }}
-        </button>
+  <div
+    class="knowledge-root"
+    data-view="knowledge"
+    :data-knowledge-theme="theme.theme.value"
+  >
+    <header class="knowledge-header">
+      <div class="knowledge-header-brand">
+        <span class="knowledge-header-logo">NeoCompanion</span>
+        <span class="knowledge-header-sub">知识工作空间</span>
       </div>
+      <BreadcrumbNav
+        :path="workspace.projectPath.value"
+        @navigate="workspace.enterProject"
+        @root="workspace.selectRoot"
+      />
+      <ThemeToggle
+        :theme="theme.theme.value"
+        @toggle="theme.toggleTheme"
+      />
+    </header>
 
-      <div class="knowledge-content-scroll">
-        <NotesPane
-          v-if="knowledge.activeView.value === 'notes'"
-          :notes="knowledge.projectNotes.value"
-          :active-note="knowledge.activeNote.value"
-          :editable="editing"
-          @select="knowledge.selectNote"
-          @update:body="handleBodyUpdate"
-        />
+    <div v-if="workspace.fallbackToMock.value" class="knowledge-banner knowledge-banner--warn">
+      {{ workspace.loadError.value ?? "后端未就绪，当前为本地预览数据。" }}
+    </div>
 
-        <BoardPane
-          v-else-if="knowledge.activeView.value === 'board'"
-          :columns="knowledge.boardColumns.value"
-          :tasks="knowledge.projectTasks.value"
-        />
+    <ProjectBrowser
+      v-if="!workspace.currentProjectId.value"
+      :workspace="workspace"
+      @enter="workspace.enterProject"
+    />
 
-        <TasksPane v-else :tasks="knowledge.projectTasks.value" />
-      </div>
-    </main>
+    <ProjectWorkspace
+      v-else
+      :workspace="workspace"
+      @exit="workspace.exitToParent"
+    />
   </div>
 </template>
diff --git a/apps/desktop/tests/useKnowledgeApi.test.ts b/apps/desktop/tests/useKnowledgeApi.test.ts
new file mode 100644
index 0000000..de716aa
--- /dev/null
+++ b/apps/desktop/tests/useKnowledgeApi.test.ts
@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useKnowledgeApi } from "../src/composables/useKnowledgeApi";
+import type { KnowledgeProject } from "../src/composables/useKnowledgeMock";
+
+const API = "http://127.0.0.1:10103";
+
+function jsonOnce(status: number, body: unknown): typeof fetch {
+  return vi.fn(async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: "OK",
+    json: async () => body,
+    text: async () => JSON.stringify(body)
+  })) as unknown as typeof fetch;
+}
+
+const project: KnowledgeProject = {
+  id: "p1", title: "产品研究", parentId: null, order: 0, createdAt: 1, updatedAt: 1
+};
+
+describe("useKnowledgeApi optimistic writes", () => {
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("loadAll populates reactive collections from the API", async () => {
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/knowledge/projects?root=1")) return (jsonOnce(200, [project])()) as unknown as Response;
+      if (url.includes("/notes")) return (jsonOnce(200, [])()) as unknown as Response;
+      if (url.includes("/columns")) return (jsonOnce(200, [])()) as unknown as Response;
+      if (url.includes("/tasks")) return (jsonOnce(200, [])()) as unknown as Response;
+      throw new Error(`unexpected ${url}`);
+    });
+
+    const ds = useKnowledgeApi();
+    await ds.loadAll();
+    expect(ds.projects.value).toHaveLength(1);
+    expect(ds.projects.value[0].title).toBe("产品研究");
+    expect(ds.ready.value).toBe(true);
+    expect(ds.lastError.value).toBeNull();
+  });
+
+  it("loadAll failure sets lastError and rethrows for fallback", async () => {
+    globalThis.fetch = jsonOnce(503, { error: "knowledge store unavailable (sqlite not loaded)" });
+    const ds = useKnowledgeApi();
+    await expect(ds.loadAll()).rejects.toThrow();
+    expect(ds.ready.value).toBe(false);
+    expect(ds.lastError.value).toBeTruthy();
+  });
+
+  it("createNote optimistically adds then reconciles with server id", async () => {
+    // loadAll first
+    let createCalls = 0;
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith("/api/knowledge/projects?root=1")) return (jsonOnce(200, [project])()) as unknown as Response;
+      if (url.includes("/notes") && init?.method === "POST") {
+        createCalls += 1;
+        return (jsonOnce(200, {
+          id: "server-id", projectId: "p1", title: "RRF", body: "", tags: [], createdAt: 100, updatedAt: 100
+        })()) as unknown as Response;
+      }
+      if (url.includes("/notes")) return (jsonOnce(200, [])()) as unknown as Response;
+      if (url.includes("/columns")) return (jsonOnce(200, [])()) as unknown as Response;
+      if (url.includes("/tasks")) return (jsonOnce(200, [])()) as unknown as Response;
+      throw new Error(`unexpected ${url}`);
+    });
+
+    const ds = useKnowledgeApi();
+    await ds.loadAll();
+
+    const optimistic = ds.createNote("p1", "RRF");
+    // optimistic object returned synchronously
+    expect(optimistic.title).toBe("RRF");
+    expect(ds.notes.value).toHaveLength(1);
+    expect(ds.notes.value[0].id).toBe(optimistic.id); // optimistic id initially
+
+    // let the API promise resolve and the .then reconcile run
+    await vi.waitFor(() => expect(ds.notes.value[0].id).toBe("server-id"));
+  });
+
+  it("createNote rolls back on API failure and surfaces error", async () => {
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith("/api/knowledge/projects?root=1")) return (jsonOnce(200, [project])()) as unknown as Response;
+      if (url.includes("/notes") && init?.method === "POST") {
+        return (jsonOnce(500, { error: "boom" })()) as unknown as Response;
+      }
+      if (url.includes("/notes")) return (jsonOnce(200, [])()) as unknown as Response;
+      if (url.includes("/columns")) return (jsonOnce(200, [])()) as unknown as Response;
+      if (url.includes("/tasks")) return (jsonOnce(200, [])()) as unknown as Response;
+      throw new Error(`unexpected ${url}`);
+    });
+
+    const ds = useKnowledgeApi();
+    await ds.loadAll();
+
+    ds.createNote("p1", "doomed");
+    expect(ds.notes.value).toHaveLength(1); // optimistic
+    await vi.waitFor(() => expect(ds.notes.value).toHaveLength(0)); // rolled back
+    expect(ds.lastError.value).toBeTruthy();
+  });
+});
diff --git a/packages/db/src/db.test.ts b/packages/db/src/db.test.ts
index 26d71de..94b9c36 100644
--- a/packages/db/src/db.test.ts
+++ b/packages/db/src/db.test.ts
@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { createDatabase, createFocusStore, createTaskStore, createWindowEventStore } from "./index";
+import { createDatabase, createFocusStore, createKnowledgeStore, createTaskStore, createWindowEventStore } from "./index";
+
+// better-sqlite3's native binding may be unavailable in some environments
+// (e.g. Node 24 without a prebuilt binary). The knowledge store requires the
+// sqlite path; skip its tests when only the memory fallback is reachable.
+const SQLITE_AVAILABLE = createDatabase(":memory:").kind === "sqlite";
 
 describe("db stores", () => {
   it("persists todo CRUD and focus sessions", () => {
@@ -36,3 +41,52 @@ describe("db stores", () => {
     database.close();
   });
 });
+
+describe.skipIf(!SQLITE_AVAILABLE)("knowledge store", () => {
+  it("persists projects, notes, columns, tasks with mock-compatible shapes", () => {
+    const database = createDatabase(":memory:");
+    const kw = createKnowledgeStore(database);
+
+    const inbox = kw.ensureInbox();
+    expect(inbox.isInbox).toBe(true);
+    expect(kw.ensureInbox().id).toBe(inbox.id);
+
+    const project = kw.createProject({ title: "产品研究", color: "#3b82f6", order: 1 });
+    const child = kw.createProject({ title: "竞品", parentId: project.id });
+    expect(kw.childProjects(project.id)).toHaveLength(1);
+    expect(kw.projectPath(child.id).map((p) => p.id)).toEqual([project.id, child.id]);
+
+    // timestamps are epoch-ms numbers (mock contract)
+    expect(typeof project.createdAt).toBe("number");
+    expect(typeof project.updatedAt).toBe("number");
+
+    const column = kw.createColumn(project.id, { title: "待办", status: "todo", order: 0 });
+    expect(kw.columnsForProject(project.id)).toHaveLength(1);
+
+    const note = kw.createNote(project.id, "RRF 笔记");
+    const updated = kw.updateNote(note.id, { body: "见 [[t-100]]", tags: ["技术", "检索"] });
+    expect(updated?.body).toBe("见 [[t-100]]");
+    expect(updated?.tags).toEqual(expect.arrayContaining(["技术", "检索"]));
+    expect(kw.notesForProject(project.id)[0].tags).toHaveLength(2);
+
+    const task = kw.createTask(project.id, column.id, "实现 RRF");
+    expect(task.columnId).toBe(column.id);
+    expect(task.status).toBe("todo");
+
+    // move task reorders within a column
+    const task2 = kw.createTask(project.id, column.id, "写测试");
+    kw.moveTask(task2.id, column.id, 0);
+    const ordered = kw.tasksForProject(project.id);
+    expect(ordered[0].id).toBe(task2.id);
+
+    // backlinks scan notes referencing a target id
+    const links = kw.backlinksFor("t-100");
+    expect(links.some((l) => l.sourceId === note.id)).toBe(true);
+
+    // cascade delete
+    kw.deleteProject(project.id);
+    expect(kw.getProject(project.id)).toBeNull();
+    expect(kw.notesForProject(project.id)).toHaveLength(0);
+    database.close();
+  });
+});
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 9436233..ca8445e 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -1,10 +1,33 @@
 import Database from "better-sqlite3";
 import { drizzle } from "drizzle-orm/better-sqlite3";
-import { eq } from "drizzle-orm";
-import type { FocusSession, Task, WindowSnapshot } from "@neo-companion/shared";
-import { focusSessions, tasks, windowEvents } from "./schema";
+import { and, eq, like, asc } from "drizzle-orm";
+import type {
+  FocusSession,
+  IndexStatus,
+  KnowledgeBoardColumn,
+  KnowledgeNote,
+  KnowledgeProject,
+  KnowledgeSource,
+  KnowledgeTask,
+  KnowledgeTaskStatus,
+  Task,
+  WindowSnapshot
+} from "@neo-companion/shared";
+import {
+  focusSessions,
+  knowledgeBoardColumns,
+  knowledgeChunks,
+  knowledgeNoteTags,
+  knowledgeNotes,
+  knowledgeProjects,
+  knowledgeTags,
+  knowledgeTasks,
+  tasks,
+  windowEvents
+} from "./schema";
 
 export * from "./schema";
+export * from "./knowledge-fs";
 
 export type NeoDatabase =
   | {
@@ -49,6 +72,17 @@ export function createDatabase(filename = process.env.NEO_DB_PATH ?? "neo-compan
   }
 }
 
+/** True when the better-sqlite3 native binding loads (sqlite path reachable). */
+export function isSqliteAvailable(): boolean {
+  try {
+    const probe = new Database(":memory:");
+    probe.close();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function initSchema(sqlite: Database.Database) {
   sqlite.exec(`
     CREATE TABLE IF NOT EXISTS tasks (
@@ -96,6 +130,84 @@ export function initSchema(sqlite: Database.Database) {
       dwell_seconds INTEGER NOT NULL,
       classification TEXT NOT NULL
     );
+
+    -- Knowledge Workspace (v2)
+    CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      description TEXT,
+      parent_id TEXT,
+      color TEXT,
+      icon TEXT,
+      is_inbox INTEGER NOT NULL DEFAULT 0,
+      "order" INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS notes (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS tags (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE
+    );
+
+    CREATE TABLE IF NOT EXISTS note_tags (
+      note_id TEXT NOT NULL,
+      tag_id TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS board_columns (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'todo',
+      "order" INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS knowledge_tasks (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      column_id TEXT,
+      title TEXT NOT NULL,
+      description TEXT,
+      status TEXT NOT NULL DEFAULT 'todo',
+      "order" INTEGER NOT NULL DEFAULT 0,
+      linked_note_id TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS knowledge_chunks (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      source_type TEXT NOT NULL,
+      source_id TEXT NOT NULL,
+      ordinal INTEGER NOT NULL,
+      content TEXT NOT NULL,
+      content_hash TEXT NOT NULL,
+      embedding_model TEXT,
+      embedding_dimensions INTEGER,
+      index_status TEXT NOT NULL DEFAULT 'pending',
+      index_error 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(
+      content,
+      project_id UNINDEXED,
+      source_type UNINDEXED,
+      source_id UNINDEXED,
+      content_hash UNINDEXED
+    );
   `);
 }
 
@@ -311,3 +423,530 @@ function toFocusRow(session: FocusSession): typeof focusSessions.$inferInsert {
     durationMinutes: session.durationMinutes
   };
 }
+
+// ── Knowledge Workspace store ──
+// Sync CRUD over better-sqlite3. Timestamps are stored as ISO TEXT and mapped
+// to epoch-ms numbers to match the frontend mock contract. Tags are synced via
+// the note_tags join on note write. The memory fallback is not supported for
+// knowledge (tests use the sqlite :memory: path, which goes through the sqlite
+// branch) — memory callers get an explicit error.
+
+export interface KnowledgeStore {
+  // 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;
+  updateProject(id: string, patch: Partial<Pick<KnowledgeProject, "title" | "description" | "color" | "icon" | "parentId" | "order">>): KnowledgeProject | null;
+  deleteProject(id: string): void;
+  ensureInbox(): KnowledgeProject;
+  // Notes
+  notesForProject(projectId: string): KnowledgeNote[];
+  getNote(id: string): KnowledgeNote | null;
+  createNote(projectId: string, title: string): KnowledgeNote;
+  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;
+  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;
+  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;
+  // Indexing (Phase 2). `chunk` is injected so the db package stays free of
+  // server-local's chunker dependency.
+  reindexNote(note: KnowledgeNote, chunk: (text: string) => { content: string; contentHash: string }[]): void;
+  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[];
+  markStale(embeddingModel?: string): void;
+  getIndexStatus(providerConfigured: boolean, vectorExtensionAvailable: boolean): IndexStatus;
+}
+
+function isoToMs(iso: string | null): number {
+  if (!iso) return 0;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? 0 : t;
+}
+
+export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
+  if (database.kind !== "sqlite") {
+    throw new Error("Knowledge store requires a sqlite database (memory fallback unsupported)");
+  }
+  const { db, sqlite } = database;
+
+  // ── tags helpers ──
+  function ensureTagIds(names: string[]): string[] {
+    const ids: string[] = [];
+    for (const name of names) {
+      const trimmed = name.trim();
+      if (!trimmed) continue;
+      const existing = db.select().from(knowledgeTags).where(eq(knowledgeTags.name, trimmed)).get();
+      if (existing) {
+        ids.push(existing.id);
+      } else {
+        const id = crypto.randomUUID();
+        db.insert(knowledgeTags).values({ id, name: trimmed }).run();
+        ids.push(id);
+      }
+    }
+    return ids;
+  }
+
+  function loadNoteTags(noteId: string): string[] {
+    const rows = db
+      .select({ name: knowledgeTags.name })
+      .from(knowledgeNoteTags)
+      .innerJoin(knowledgeTags, eq(knowledgeNoteTags.tagId, knowledgeTags.id))
+      .where(eq(knowledgeNoteTags.noteId, noteId))
+      .all();
+    return rows.map((r) => r.name);
+  }
+
+  function syncNoteTags(noteId: string, tags: string[]): void {
+    db.delete(knowledgeNoteTags).where(eq(knowledgeNoteTags.noteId, noteId)).run();
+    const ids = ensureTagIds(tags);
+    if (ids.length) {
+      db.insert(knowledgeNoteTags).values(ids.map((tagId) => ({ noteId, tagId }))).run();
+    }
+  }
+
+  // ── mappers ──
+  function rowToProject(row: typeof knowledgeProjects.$inferSelect): KnowledgeProject {
+    return {
+      id: row.id,
+      title: row.title,
+      description: row.description ?? undefined,
+      parentId: row.parentId,
+      color: row.color ?? undefined,
+      icon: row.icon ?? undefined,
+      isInbox: row.isInbox,
+      order: row.order,
+      createdAt: isoToMs(row.createdAt),
+      updatedAt: isoToMs(row.updatedAt)
+    };
+  }
+
+  function rowToNote(row: typeof knowledgeNotes.$inferSelect): KnowledgeNote {
+    return {
+      id: row.id,
+      projectId: row.projectId,
+      title: row.title,
+      body: row.body,
+      tags: loadNoteTags(row.id),
+      createdAt: isoToMs(row.createdAt),
+      updatedAt: isoToMs(row.updatedAt)
+    };
+  }
+
+  function rowToColumn(row: typeof knowledgeBoardColumns.$inferSelect): KnowledgeBoardColumn {
+    return {
+      id: row.id,
+      projectId: row.projectId,
+      title: row.title,
+      status: row.status,
+      order: row.order
+    };
+  }
+
+  function rowToTask(row: typeof knowledgeTasks.$inferSelect): KnowledgeTask {
+    return {
+      id: row.id,
+      projectId: row.projectId,
+      columnId: row.columnId ?? "",
+      title: row.title,
+      description: row.description ?? undefined,
+      status: row.status,
+      order: row.order,
+      linkedNoteId: row.linkedNoteId ?? undefined,
+      tags: [],
+      createdAt: isoToMs(row.createdAt),
+      updatedAt: isoToMs(row.updatedAt)
+    };
+  }
+
+  function nowIso(): string {
+    return new Date().toISOString();
+  }
+
+  // ── projects ──
+  function listProjects(): KnowledgeProject[] {
+    return db.select().from(knowledgeProjects).orderBy(asc(knowledgeProjects.order)).all().map(rowToProject);
+  }
+  function getProject(id: string): KnowledgeProject | null {
+    const row = db.select().from(knowledgeProjects).where(eq(knowledgeProjects.id, id)).get();
+    return row ? rowToProject(row) : null;
+  }
+  function childProjects(parentId: string): KnowledgeProject[] {
+    return db.select().from(knowledgeProjects).where(eq(knowledgeProjects.parentId, parentId)).orderBy(asc(knowledgeProjects.order)).all().map(rowToProject);
+  }
+  function projectPath(id: string): KnowledgeProject[] {
+    const path: KnowledgeProject[] = [];
+    let current = getProject(id);
+    let guard = 0;
+    while (current && guard < 32) {
+      path.unshift(current);
+      current = current.parentId ? getProject(current.parentId) : null;
+      guard += 1;
+    }
+    return path;
+  }
+  function createProject(input: { title: string; parentId?: string | null; description?: string; color?: string; icon?: string; isInbox?: boolean; order?: number }): KnowledgeProject {
+    const id = crypto.randomUUID();
+    const ts = nowIso();
+    db.insert(knowledgeProjects).values({
+      id,
+      title: input.title.trim(),
+      description: input.description ?? null,
+      parentId: input.parentId ?? null,
+      color: input.color ?? null,
+      icon: input.icon ?? null,
+      isInbox: input.isInbox ?? false,
+      order: input.order ?? 0,
+      createdAt: ts,
+      updatedAt: ts
+    }).run();
+    return getProject(id)!;
+  }
+  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;
+    db.update(knowledgeProjects).set({
+      title: patch.title?.trim() ?? existing.title,
+      description: patch.description !== undefined ? patch.description : existing.description,
+      color: patch.color !== undefined ? patch.color : existing.color,
+      icon: patch.icon !== undefined ? patch.icon : existing.icon,
+      parentId: patch.parentId !== undefined ? patch.parentId : existing.parentId,
+      order: patch.order ?? existing.order,
+      updatedAt: nowIso()
+    }).where(eq(knowledgeProjects.id, id)).run();
+    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();
+  }
+  function ensureInbox(): KnowledgeProject {
+    const existing = db.select().from(knowledgeProjects).where(eq(knowledgeProjects.isInbox, true)).get();
+    if (existing) return rowToProject(existing);
+    return createProject({ title: "收件箱", description: "临时想法与未分类内容", color: "#6b7280", isInbox: true, order: 0 });
+  }
+
+  // ── notes ──
+  function notesForProject(projectId: string): KnowledgeNote[] {
+    return db.select().from(knowledgeNotes).where(eq(knowledgeNotes.projectId, projectId)).orderBy(asc(knowledgeNotes.updatedAt)).all().map(rowToNote);
+  }
+  function getNote(id: string): KnowledgeNote | null {
+    const row = db.select().from(knowledgeNotes).where(eq(knowledgeNotes.id, id)).get();
+    return row ? rowToNote(row) : null;
+  }
+  function createNote(projectId: string, title: string): KnowledgeNote {
+    const id = crypto.randomUUID();
+    const ts = nowIso();
+    db.insert(knowledgeNotes).values({
+      id,
+      projectId,
+      title: title.trim() || "无标题笔记",
+      body: "",
+      createdAt: ts,
+      updatedAt: ts
+    }).run();
+    return getNote(id)!;
+  }
+  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;
+    db.update(knowledgeNotes).set({
+      title: patch.title !== undefined ? patch.title.trim() : existing.title,
+      body: patch.body !== undefined ? patch.body : existing.body,
+      updatedAt: nowIso()
+    }).where(eq(knowledgeNotes.id, id)).run();
+    if (patch.tags !== undefined) syncNoteTags(id, patch.tags);
+    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();
+  }
+  function backlinksFor(targetId: string): { sourceType: "note" | "task"; sourceId: string }[] {
+    // Basic [[target]] scan; upgraded to FTS in Phase 2.
+    const pattern = `%[[${targetId}]%`;
+    const notes = db
+      .select({ id: knowledgeNotes.id })
+      .from(knowledgeNotes)
+      .where(like(knowledgeNotes.body, pattern))
+      .all()
+      .map((r) => ({ sourceType: "note" as const, sourceId: r.id }));
+    return notes;
+  }
+
+  // ── columns ──
+  function columnsForProject(projectId: string): KnowledgeBoardColumn[] {
+    return db.select().from(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.projectId, projectId)).orderBy(asc(knowledgeBoardColumns.order)).all().map(rowToColumn);
+  }
+  function createColumn(projectId: string, input: { title: string; status: KnowledgeTaskStatus; order: number }): KnowledgeBoardColumn {
+    const id = crypto.randomUUID();
+    db.insert(knowledgeBoardColumns).values({ id, projectId, title: input.title.trim(), status: input.status, order: input.order }).run();
+    const row = db.select().from(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.id, id)).get();
+    return rowToColumn(row!);
+  }
+  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;
+    db.update(knowledgeBoardColumns).set({
+      title: patch.title?.trim() ?? existing.title,
+      status: patch.status ?? existing.status,
+      order: patch.order ?? existing.order
+    }).where(eq(knowledgeBoardColumns.id, id)).run();
+    const row = db.select().from(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.id, id)).get();
+    return row ? rowToColumn(row) : null;
+  }
+  function deleteColumn(id: string): void {
+    // unhook tasks in this column rather than deleting them
+    db.update(knowledgeTasks).set({ columnId: null }).where(eq(knowledgeTasks.columnId, id)).run();
+    db.delete(knowledgeBoardColumns).where(eq(knowledgeBoardColumns.id, id)).run();
+  }
+
+  // ── tasks ──
+  function tasksForProject(projectId: string): KnowledgeTask[] {
+    return db.select().from(knowledgeTasks).where(eq(knowledgeTasks.projectId, projectId)).orderBy(asc(knowledgeTasks.order)).all().map(rowToTask);
+  }
+  function createTask(projectId: string, columnId: string, title: string): KnowledgeTask {
+    const id = crypto.randomUUID();
+    const ts = nowIso();
+    db.insert(knowledgeTasks).values({
+      id,
+      projectId,
+      columnId: columnId || null,
+      title: title.trim(),
+      status: "todo",
+      order: 0,
+      linkedNoteId: null,
+      createdAt: ts,
+      updatedAt: ts
+    }).run();
+    return rowToTask(db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, id)).get()!);
+  }
+  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;
+    db.update(knowledgeTasks).set({
+      title: patch.title !== undefined ? patch.title.trim() : existing.title,
+      description: patch.description !== undefined ? patch.description : existing.description,
+      status: patch.status ?? existing.status,
+      columnId: patch.columnId !== undefined ? (patch.columnId || null) : existing.columnId,
+      order: patch.order ?? existing.order,
+      linkedNoteId: patch.linkedNoteId !== undefined ? patch.linkedNoteId : existing.linkedNoteId,
+      updatedAt: nowIso()
+    }).where(eq(knowledgeTasks.id, id)).run();
+    const row = db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, id)).get();
+    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();
+  }
+  function moveTask(taskId: string, targetColumnId: string, targetIndex: number): void {
+    const task = db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, taskId)).get();
+    if (!task) return;
+    const projectId = task.projectId;
+    // shift siblings in target column then place
+    const siblings = db.select().from(knowledgeTasks)
+      .where(and(eq(knowledgeTasks.projectId, projectId), eq(knowledgeTasks.columnId, targetColumnId)))
+      .orderBy(asc(knowledgeTasks.order)).all().filter((t) => t.id !== taskId);
+    const clamped = Math.max(0, Math.min(targetIndex, siblings.length));
+    siblings.splice(clamped, 0, task);
+    siblings.forEach((t, idx) => {
+      db.update(knowledgeTasks).set({ columnId: targetColumnId, order: idx }).where(eq(knowledgeTasks.id, t.id)).run();
+    });
+  }
+
+  // ── indexing (Phase 2): chunk dedup + FTS5 sync ──
+  // Re-chunks a note, replacing its existing chunks. content-hash dedup: chunks
+  // whose hash already exists for this source are reused (skipping re-embed in
+  // Phase 3). FTS5 mirror is written synchronously; embedding stays 'pending'.
+  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;
+    }
+  }
+
+  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();
+      ordinal += 1;
+    }
+  }
+
+  function removeIndex(sourceType: "note" | "task", sourceId: string): void {
+    // 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)}`
+    );
+    db.delete(knowledgeChunks)
+      .where(and(eq(knowledgeChunks.sourceType, sourceType), eq(knowledgeChunks.sourceId, sourceId)))
+      .run();
+  }
+
+  function searchFts(projectId: string | null, query: string, limit: number): KnowledgeSource[] {
+    const sanitized = sanitizeFtsQuery(query);
+    if (!sanitized) return [];
+    // FTS5 BM25 via match(); rank by bm25(). Scope by project_id when given.
+    const sql = projectId
+      ? `SELECT 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(sanitized)} AND k.project_id = ${sqlStr(projectId)}
+         ORDER BY rank LIMIT ${Math.max(1, Math.min(limit, 50))}`
+      : `SELECT 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(sanitized)}
+         ORDER BY rank LIMIT ${Math.max(1, Math.min(limit, 50))}`;
+    const rows = sqlite.prepare(sql).all() as Array<{
+      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>();
+    for (const row of rows) {
+      const key = `${row.source_type}:${row.source_id}`;
+      if (bySource.has(key)) continue;
+      const title = resolveSourceTitle(row.source_type, row.source_id);
+      bySource.set(key, {
+        sourceType: row.source_type,
+        sourceId: row.source_id,
+        projectId: row.project_id,
+        title,
+        excerpt: deriveExcerpt(row.content),
+        chunkId: key
+      });
+    }
+    return [...bySource.values()];
+  }
+
+  function resolveSourceTitle(sourceType: "note" | "task", sourceId: string): string {
+    if (sourceType === "note") {
+      const row = db.select().from(knowledgeNotes).where(eq(knowledgeNotes.id, sourceId)).get();
+      return row?.title ?? "未命名笔记";
+    }
+    const row = db.select().from(knowledgeTasks).where(eq(knowledgeTasks.id, sourceId)).get();
+    return row?.title ?? "未命名任务";
+  }
+
+  function deriveExcerpt(content: string, maxChars = 120): string {
+    const flat = content.replace(/[#>*_~`]/g, "").replace(/\s+/g, " ").trim();
+    return flat.length <= maxChars ? flat : `${flat.slice(0, maxChars - 1)}…`;
+  }
+
+  function markStale(embeddingModel?: string): void {
+    // mark indexed chunks stale when the embedding model changes (Phase 3)
+    if (embeddingModel) {
+      db.update(knowledgeChunks)
+        .set({ indexStatus: "stale" })
+        .where(and(eq(knowledgeChunks.indexStatus, "indexed"), eq(knowledgeChunks.embeddingModel, embeddingModel)))
+        .run();
+    } else {
+      db.update(knowledgeChunks).set({ indexStatus: "stale" }).where(eq(knowledgeChunks.indexStatus, "indexed")).run();
+    }
+  }
+
+  function getIndexStatus(providerConfigured: boolean, vectorExtensionAvailable: 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;
+    };
+    return {
+      mode: vectorExtensionAvailable ? "hybrid" : "fts-only",
+      pending: countBy("pending"),
+      failed: countBy("failed"),
+      stale: countBy("stale"),
+      providerConfigured,
+      vectorExtensionAvailable
+    };
+  }
+
+  // safe SQL string literal (single-quote escape) for raw FTS queries
+  function sqlStr(value: string): string {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  function sanitizeFtsQuery(query: string): string {
+    // FTS5 query syntax: keep alphanumeric + CJK, wrap terms; strip operators.
+    const terms = query
+      .split(/[\s,，。、]+/)
+      .map((t) => t.replace(/[^\p{L}\p{N}]+/gu, ""))
+      .filter(Boolean);
+    if (!terms.length) return "";
+    // OR-join quoted terms so a multi-word query matches any term (lenient).
+    return terms.map((t) => `"${t.replace(/"/g, "")}"`).join(" OR ");
+  }
+
+  // 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
+  };
+}
diff --git a/packages/db/src/knowledge-fs.test.ts b/packages/db/src/knowledge-fs.test.ts
new file mode 100644
index 0000000..71b124c
--- /dev/null
+++ b/packages/db/src/knowledge-fs.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import {
+  fromJsonl,
+  markdownToNote,
+  noteToMarkdown,
+  projectToMeta,
+  sanitizeFilename,
+  toJsonl
+} from "./knowledge-fs";
+import type { KnowledgeNote, KnowledgeProject } from "@neo-companion/shared";
+
+const note: KnowledgeNote = {
+  id: "n-1",
+  projectId: "p-1",
+  title: "RRF 笔记",
+  body: "见 [[t-100]]\n\n## 要点\n- 公式",
+  tags: ["技术", "检索"],
+  createdAt: 1_700_000_000_000,
+  updatedAt: 1_700_000_100_000
+};
+
+describe("knowledge-fs serialization", () => {
+  it("sanitizes filenames and rejects path separators", () => {
+    expect(sanitizeFilename("a/b\\c:d*e?")).toBe("a b c d e");
+    expect(sanitizeFilename("   ")).toBe("untitled");
+    expect(sanitizeFilename("CON")).toBe("_CON");
+  });
+
+  it("round-trips a note through markdown front-matter", () => {
+    const md = noteToMarkdown(note);
+    expect(md).toContain("---");
+    expect(md).toContain("id: n-1");
+    expect(md).toContain("见 [[t-100]]");
+
+    const parsed = markdownToNote(md);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.frontMatter.id).toBe("n-1");
+    expect(parsed!.frontMatter.title).toBe("RRF 笔记");
+    expect(parsed!.frontMatter.tags).toEqual(["技术", "检索"]);
+    expect(parsed!.frontMatter.updatedAt).toBe(note.updatedAt);
+    expect(parsed!.body).toBe(note.body);
+  });
+
+  it("handles notes with no tags and special-char titles", () => {
+    const n: KnowledgeNote = { ...note, title: '含"引号" 与: 冒号', tags: [] };
+    const md = noteToMarkdown(n);
+    const parsed = markdownToNote(md);
+    expect(parsed!.frontMatter.title).toBe('含"引号" 与: 冒号');
+    expect(parsed!.frontMatter.tags).toEqual([]);
+  });
+
+  it("returns null when markdown has no front-matter", () => {
+    expect(markdownToNote("just body, no front matter")).toBeNull();
+  });
+
+  it("round-trips JSONL for columns and tasks", () => {
+    const items = [{ id: "1", title: "待办", status: "todo", order: 0 }, { id: "2", title: "进行中", status: "doing", order: 1 }];
+    const text = toJsonl(items);
+    expect(text.split("\n").filter(Boolean)).toHaveLength(2);
+    expect(fromJsonl(text)).toEqual(items);
+  });
+
+  it("round-trips empty JSONL", () => {
+    expect(toJsonl([])).toBe("");
+    expect(fromJsonl("")).toEqual([]);
+  });
+
+  it("maps a project to its on-disk metadata", () => {
+    const project: KnowledgeProject = {
+      id: "p-1",
+      title: "产品研究",
+      description: "方向",
+      color: "#3b82f6",
+      order: 1,
+      parentId: null,
+      createdAt: 1,
+      updatedAt: 2
+    };
+    const meta = projectToMeta(project);
+    expect(meta.id).toBe("p-1");
+    expect(meta.parentId).toBeNull();
+    expect(meta.color).toBe("#3b82f6");
+  });
+});
diff --git a/packages/db/src/knowledge-fs.ts b/packages/db/src/knowledge-fs.ts
new file mode 100644
index 0000000000000000000000000000000000000000..950d2d55740542dd2ec1137753c882bd09c49f7e
GIT binary patch
literal 5927
zcma)A+j84D65VJ2#C8~OLOK!|@1rmBI8IXQS>M)HW_L=`#E=Nth)GaGQsa0WRn14t
z7tWXLX#k{1Nwc-CRBSf78^FQo3lQz>Y|#!~&2veG%#}#gucB0$rfHT_c`s?I64^~v
zp5wbvv7~Hj<o8eGT*dUDv&TfncQ7xrT!!$*4sZT-rb?EHr-CLzXIf1}vJXpDP@2W_
zL{chd1xa11QptkKESlz7N<!1+7!xU>yVG1r9VbuhG1J{x6%Uk%r)*wQk(pIIX8A)g
z6B9}BJInG?jNw`6nB><|=2|4l6UkT^`JP)G(LtVNWiMjC{BtnNvoCT|cBfeq%e)sE
zsr&CGxluX<C_GNSmPIM!#y~M2+p(bXNfc_CMb0+-QUKHX=Ov}G6tO799;vuPu`DLJ
znlbPlnq*0qcSue6Bg-)%K8jO4&c1f2ELJ9f_B_>vnILIQFwR6Cvo9WnA1&$oo68Hz
z#=KLSVH=6ka>ZLIiicHSL@&w6{~s?0IxA%_Oyhbf^&c<k$K&%e!YS*rn~D<WLq6{w
z3`it?i90N`ECPB%=OTZIvqw$iEav0qWnN@7El8z&%mv*`Q1*}Ce#g#m#4{#vnG0Qj
zw<+9Mems$Ye6Cg5EpcRq9FMBJ2ZPvS@pHl~1+)8No~w}hAiS8AbCHlC+i7$Olzss{
zm3Fi(qMGuN4U4cWnD)_@T^f~7GfB@|ME|T};~k&Hi8+c+Q+@%gT7oOf!<MX%BiULo
zY$<u)fm7W{md=C*SEAw``-{E(tu2tHDCzX#hvT!;_n$wWo_)ADKL7Cf<R8b^Hy~~_
zIOy$p(Qx?fXy-58zmB52eP?q0;pW5j4<FutW_?!G@{w+2=?}b<%L}hV-qp4Fb^Pf+
z{B`l^jDMY6p6~MSv#b8DHwv(VXlDn<HY0(hN{LX)Q+u)qZ3qi7MLtma4)Hk?<vr5P
zU5e-r89Dit50$2KJu%6r!1hY@tNe)MqeUuxLy<k?lN=s`>JNjm-T5SuLL(#(?VLav
z0hr5Kg52P5h6Sr95AoX6jE2RV=&m_}8B-toBg7IzJQjt-EY*D9zL7WQ9EK!_bEveC
z9#Uwra#+m3GT#fmVDNTCFkmUGsww$x_``cq_-q@N*{2y|^aQGY5CoLVa-M6t{k;9m
z=8N0Pftdm*-2u`b?Y@1x)U~Q%ktksBwqpjZq4Q=JvcTCz^vCbN;oqhZO_f%uNIImm
zI;$dM%>rk$wN;-R(wLaZA4QtnAl-}H|3xHoSshpV+%V_Qa|8gxph`x!6iOFV%;W@h
zh$i56u}?Aq-ZF*87+iO#MT5PU!@+R$ym-~wIr`T7+jqC#>lZ^kib9TaJ8i&Nn+1gS
z5b4F?p%ny%IaH(SZ9iMZiZO^3LxUlHyr3ph<gxTMWUqsTXU<@OB{?{ai~TL&>G-TP
za@>@w6G!?-PJHJ!?>+NI;tCi(%NE0p0O_z&7>rml$)!NqIWG4|&(pEYSva4ejI@Qz
z1=I(_S-GE8S=Hyyy=8vl)wK`Da($Zat*!jfLC33SHz6`OmQioO$ZSTpVzUh^<pghp
z&7H81`r8gS_r$~XH;fks2@{H3Fc4%@L<{~3T@W16Ef!;D9c({WgJ?E<zYOTGM{6W4
zgCP8pDeZGY3l^hW+Cyrne2h$3SMk^Fc88kxZd|K)F|@(Yf;GoHIcJ6dTHDXOCj3$F
z)%mEuF;;KXjn&^6Gc&UvgC*BRj%5yBB;G5;3VO9>X&sBn1IiYX?^MYoE>Kn3D5PtX
zN(yi&NjUfr)=k5W2|0E3xSw6%Kzt5X<nD@|;Lfx4Vd=fbntd~MrA`a_W@mrKfm*7e
zADG;8UbUV>^X*4J@vifuq4o#EVt6y!ISR~YB|fU;!FFVlH0RV8#<<Rdyw4?R#z_WT
z4$*yL!ojW$ESuSZPCfAV(K6_NGE+t%hu0_s4%I_cGhoj-?;X4L%>)fSKK5(z$V4^g
zV93hrNo46bX3N@O1RWdcybEq4xYw@Ck-I#r=vC><K?gIZRl_zM_~A}49BoI1S&A(-
zX=P~1&6@=RCL%e4t4h^zRnf>y;Gic%;LOqXuH^T^rPjdKQDcD{1Ja)VF3Y$kyXiSi
zHc}-YJhdrfMK&$om^$w}z;MktI%4o`cBoU$hV`@!P4GF}r7-}l9M!Q0#+r;;O<51H
z_1oIEj>lE~dcf+N-7V}awu9xog;=c<@+Q($@quu<mJ@XT2ll+t%^Ey<CiU7wM+f_-
zT1e3*OY#+tLls>MxB7f@GvsvV99deUxv<b%O%;CyFIYcRI+kBAr@psmd2dN%6hOxA
zZeXHS>AC4<sz`p297V=K-Fd(!a7<z5SE{C9ww2lY8`^Dab2z|lK-l#Fe{i6<V%uUB
zhTAA_V2H76AZ?*F5b!i+IK))}cZ`4Irr^Iusi#-3TqA+&=u%t(*DU{LcN|Kl>Duiu
zOqHzBT-ZJWt~ZR;t%pUu5jAelob&63jW2a)btkskNSE37xOgT$t~n{XiMi&>iyn;H
z)!uEuC?SQQQu3cB=Gi^q;I>;$pRBy9mP3t9^agi0cD^jX9^_m>dHEY!5x&TnMIH2U
zjBZ6ezr=;TaV&jgL#Cx$8jl*NR=8_rX35Mrvt&a(+wr;XekCJqGBW!#LFrpZqM*Lr
zz!GbF#gF(&gkLXa0A&^VWy|O8av#l;!I^!v;2l{f7r50_+vSjO?*!*~7P!Lgs2)PB
zVEzMZ)Qi^M6kzJ^_^W0dW^1Oc*8<p@d;KQM4YrN90a$VuQoL7rbEP~bej2lGB7oa!
z6BvIT6fpG95VVQPnt(z}TL#h*hLLV#ZPjc}UPJp9?VLHN#X7{d)}{sXs(uSsXVAcQ
zRlNbFQ(nSp*Ma5Rim`T;aHud-Y}WeU*NDc`(oua@@QxK{c}v0%PHlmGbb@SbYdPa<
z9;BKV5Cjcc!P9ybuD4^|x{5aS>r%NCZpaeugm7oUK7IGqxUx7DmMp39Xc2%rb!WVK
zQK`g@yGjGArCCE*6CnfbD|-W^9bp8Q1Lgq_D4=XwAR9wgV67aYl|TF9XY7{HR)dwq
ztz>y2tQ2a<twsavN~0EGiWbG{-h{cxFE5;<+*R>PO&$*F_bk2xpc^*Gc{p!R#a?e?
zNdfWK-g4M|buYq0p}oYc7A_l5eOtaxQDD%>@Ka`k0*zNSTZ!GtTg8pFhvTm4lfN4t
M`}l0R;&FELU-a>R1poj5

literal 0
HcmV?d00001

diff --git a/packages/db/src/schema.ts b/packages/db/src/schema.ts
index 9e6c379..e3788d4 100644
--- a/packages/db/src/schema.ts
+++ b/packages/db/src/schema.ts
@@ -45,3 +45,80 @@ export const windowEvents = sqliteTable("window_events", {
   dwellSeconds: integer("dwell_seconds").notNull(),
   classification: text("classification", { enum: ["focused", "distracted", "stuck"] }).notNull()
 });
+
+// ── Knowledge Workspace (v2) ──
+// Kept separate from the v1 `tasks` table (which drives the pet-panel checklist
+// with `open|done`). Knowledge kanban tasks use a 4-state status. Unification is
+// tracked in docs/TODO_INVENTORY.md.
+
+export const knowledgeProjects = sqliteTable("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  description: text("description"),
+  parentId: text("parent_id"),
+  color: text("color"),
+  icon: text("icon"),
+  isInbox: integer("is_inbox", { mode: "boolean" }).notNull().default(false),
+  order: integer("order").notNull().default(0),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull()
+});
+
+export const knowledgeNotes = sqliteTable("notes", {
+  id: text("id").primaryKey(),
+  projectId: text("project_id").notNull(),
+  title: text("title").notNull(),
+  body: text("body").notNull().default(""),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull()
+});
+
+export const knowledgeTags = sqliteTable("tags", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull().unique()
+});
+
+export const knowledgeNoteTags = sqliteTable("note_tags", {
+  noteId: text("note_id").notNull(),
+  tagId: text("tag_id").notNull()
+});
+
+export const knowledgeBoardColumns = sqliteTable("board_columns", {
+  id: text("id").primaryKey(),
+  projectId: text("project_id").notNull(),
+  title: text("title").notNull(),
+  status: text("status", { enum: ["todo", "doing", "done", "archived"] }).notNull().default("todo"),
+  order: integer("order").notNull().default(0)
+});
+
+export const knowledgeTasks = sqliteTable("knowledge_tasks", {
+  id: text("id").primaryKey(),
+  projectId: text("project_id").notNull(),
+  columnId: text("column_id"),
+  title: text("title").notNull(),
+  description: text("description"),
+  status: text("status", { enum: ["todo", "doing", "done", "archived"] }).notNull().default("todo"),
+  order: integer("order").notNull().default(0),
+  linkedNoteId: text("linked_note_id"),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull()
+});
+
+// FTS5 + sqlite-vec retrieval targets. `knowledge_chunks` holds chunk text +
+// content hash (dedup) + index lifecycle; FTS5 mirror is managed by the
+// knowledge service; vec0 virtual table is created lazily when the sqlite-vec
+// extension loads (Phase 3).
+export const knowledgeChunks = sqliteTable("knowledge_chunks", {
+  id: text("id").primaryKey(),
+  projectId: text("project_id").notNull(),
+  sourceType: text("source_type", { enum: ["note", "task"] }).notNull(),
+  sourceId: text("source_id").notNull(),
+  ordinal: integer("ordinal").notNull(),
+  content: text("content").notNull(),
+  contentHash: text("content_hash").notNull(),
+  embeddingModel: text("embedding_model"),
+  embeddingDimensions: integer("embedding_dimensions"),
+  indexStatus: text("index_status", { enum: ["pending", "indexed", "failed", "stale"] }).notNull().default("pending"),
+  indexError: text("index_error"),
+  updatedAt: text("updated_at").notNull()
+});
diff --git a/packages/server-local/src/app.ts b/packages/server-local/src/app.ts
index e1a3903..9cfafaa 100644
--- a/packages/server-local/src/app.ts
+++ b/packages/server-local/src/app.ts
@@ -2,13 +2,15 @@ import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
 import Fastify, { type FastifyInstance } from "fastify";
 import { streamDeepSeekChat } from "@neo-companion/ai";
-import { createDatabase, createTaskStore, createWindowEventStore, type NeoDatabase } from "@neo-companion/db";
+import { createDatabase, createKnowledgeStore, createTaskStore, createWindowEventStore, 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";
 import { createHookManager, type HookManagerEvents } from "./services/hook-manager";
 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 { WsHub } from "./ws-hub";
 
 export interface AppDependencies {
@@ -25,6 +27,11 @@ export async function createApp(dependencies: AppDependencies = {}) {
   const database = dependencies.database ?? createDatabase();
   const taskStore = createTaskStore(database);
   const windowStore = createWindowEventStore(database);
+  // Knowledge store requires the sqlite path; null when only the memory
+  // 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;
   const hub = new WsHub();
   const app = Fastify({ logger: true });
   const aiStream = dependencies.aiStream ?? ((messages) => streamDeepSeekChat(messages));
@@ -92,6 +99,8 @@ export async function createApp(dependencies: AppDependencies = {}) {
     return task;
   });
 
+  registerKnowledgeRoutes(app, knowledgeStore, knowledgeService);
+
   app.post("/api/focus/start", async (request) => {
     const body = request.body as { taskId?: string | null; durationMinutes?: number };
     const session = focus.start(body.taskId ?? null, body.durationMinutes ?? 25);
diff --git a/packages/server-local/src/modules/knowledge/chunker.test.ts b/packages/server-local/src/modules/knowledge/chunker.test.ts
new file mode 100644
index 0000000..f6ef42e
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/chunker.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { chunkMarkdown, chunkTask, estimateTokens, hashContent, resolveChunkingConfig } from "./chunker";
+
+describe("chunker", () => {
+  it("estimates tokens as ~chars/4", () => {
+    expect(estimateTokens("abcd")).toBe(1);
+    expect(estimateTokens("ab")).toBe(1);
+    expect(estimateTokens("".padEnd(400, "x"))).toBe(100);
+  });
+
+  it("hashes content deterministically", () => {
+    expect(hashContent("hello")).toBe(hashContent("hello"));
+    expect(hashContent("hello")).not.toBe(hashContent("world"));
+  });
+
+  it("keeps headers with their section bodies", () => {
+    const md = "# Title\n\nintro\n\n## Section A\n\nbody A\n\n## Section B\n\nbody B";
+    const chunks = chunkMarkdown(md, { chunkSize: 400, chunkOverlap: 0, minChunkSize: 1 });
+    // each section becomes one chunk, heading prefixed
+    const joined = chunks.map((c) => c.content).join("\n---\n");
+    expect(joined).toContain("# Title");
+    expect(joined).toContain("## Section A");
+    expect(joined).toContain("body B");
+    expect(chunks.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("drops chunks below min size", () => {
+    const md = "# A\n\nx\n\n# B\n\n" + "y".repeat(40);
+    const chunks = chunkMarkdown(md, { chunkSize: 400, chunkOverlap: 0, minChunkSize: 5 });
+    // the "x" section (1 token) should be filtered
+    expect(chunks.every((c) => estimateTokens(c.content) >= 5)).toBe(true);
+  });
+
+  it("splits over-long sections with overlap", () => {
+    const long = "# Big\n\n" + "word ".repeat(2000); // ~10000 chars, ~2500 tokens
+    const chunks = chunkMarkdown(long, { chunkSize: 100, chunkOverlap: 20, minChunkSize: 1 });
+    expect(chunks.length).toBeGreaterThan(1);
+    // every chunk should stay near the budget; overlap lets a chunk carry a
+    // tail from the previous one plus a separator, so allow slack.
+    for (const c of chunks) {
+      expect(estimateTokens(c.content)).toBeLessThanOrEqual(160);
+    }
+  });
+
+  it("assigns sequential ordinals and unique hashes", () => {
+    const md = "# A\n\nalpha\n\n# B\n\nbeta";
+    const chunks = chunkMarkdown(md, { chunkSize: 400, chunkOverlap: 0, minChunkSize: 1 });
+    expect(chunks.map((c) => c.ordinal)).toEqual(chunks.map((_, i) => i));
+    const hashes = chunks.map((c) => c.contentHash);
+    expect(new Set(hashes).size).toBe(hashes.length);
+  });
+
+  it("chunks a task as a single block", () => {
+    const chunks = chunkTask("实现 RRF", "用 k=60 融合", { chunkSize: 400, chunkOverlap: 0, minChunkSize: 1 });
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0].content).toContain("实现 RRF");
+    expect(chunks[0].content).toContain("k=60");
+  });
+
+  it("returns no chunk for empty/too-small tasks", () => {
+    expect(chunkTask("", undefined)).toEqual([]);
+    expect(chunkTask("x", undefined, { chunkSize: 400, chunkOverlap: 0, minChunkSize: 5 })).toEqual([]);
+  });
+
+  it("respects env-configured sizes with safe clamping", () => {
+    const orig = { ...process.env };
+    process.env.NEO_CHUNK_SIZE = "200";
+    process.env.NEO_CHUNK_OVERLAP = "10";
+    process.env.NEO_MIN_CHUNK_SIZE = "2";
+    const cfg = resolveChunkingConfig();
+    expect(cfg.chunkSize).toBe(200);
+    expect(cfg.chunkOverlap).toBe(10);
+    expect(cfg.minChunkSize).toBe(2);
+    process.env = orig;
+  });
+
+  it("clamps overlap below chunk size", () => {
+    const orig = { ...process.env };
+    process.env.NEO_CHUNK_SIZE = "200";
+    process.env.NEO_CHUNK_OVERLAP = "500"; // invalid, falls back to 15%
+    const cfg = resolveChunkingConfig();
+    expect(cfg.chunkOverlap).toBeLessThan(cfg.chunkSize);
+    process.env = orig;
+  });
+});
diff --git a/packages/server-local/src/modules/knowledge/chunker.ts b/packages/server-local/src/modules/knowledge/chunker.ts
new file mode 100644
index 0000000..3630dda
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/chunker.ts
@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Markdown-aware chunking for the knowledge indexer (open-notebook port, point 2).
+ *
+ * Strategy:
+ *   1. Split Markdown by H1/H2/H3 headers so each chunk respects semantic
+ *      section boundaries (keeps a heading with its body).
+ *   2. Recursively split any over-long section by paragraph → sentence → char.
+ *   3. Size budgets are TOKEN-level (~chars/4 heuristic, no tokenizer dep),
+ *      with overlap so cross-boundary context isn't lost.
+ *   4. Drop chunks below MIN_CHUNK_SIZE (avoids null/useless embeddings and
+ *      FTS noise from stray punctuation).
+ *
+ * Pure — no DB, no I/O. Unit-testable in isolation.
+ */
+
+export interface ChunkingConfig {
+  /** Target chunk size in tokens. Default 400 (≈1600 chars). */
+  chunkSize: number;
+  /** Overlap between adjacent chunks in tokens. Default 15% of chunkSize. */
+  chunkOverlap: number;
+  /** Chunks below this token count are dropped. Default 5. */
+  minChunkSize: number;
+}
+
+export const DEFAULT_CHUNKING_CONFIG: ChunkingConfig = {
+  chunkSize: 400,
+  chunkOverlap: 60,
+  minChunkSize: 5
+};
+
+export function resolveChunkingConfig(overrides?: Partial<ChunkingConfig>): ChunkingConfig {
+  const env = process.env;
+  const chunkSize = parsePositiveInt(env.NEO_CHUNK_SIZE, DEFAULT_CHUNKING_CONFIG.chunkSize);
+  const overlap = parseNonNegativeInt(env.NEO_CHUNK_OVERLAP, Math.floor(chunkSize * 0.15));
+  const minChunkSize = parseNonNegativeInt(env.NEO_MIN_CHUNK_SIZE, DEFAULT_CHUNKING_CONFIG.minChunkSize);
+  return {
+    chunkSize,
+    chunkOverlap: overlap >= chunkSize ? Math.floor(chunkSize * 0.15) : overlap,
+    minChunkSize,
+    ...overrides
+  };
+}
+
+function parsePositiveInt(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 100 ? n : fallback;
+}
+function parseNonNegativeInt(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+/** Rough token estimate: ~4 chars/token, rounded up. Good enough for budgeting. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+const HEADER_RE = /^(#{1,3})\s+(.*)$/;
+
+export interface Chunk {
+  content: string;
+  ordinal: number;
+  contentHash: string;
+}
+
+/**
+ * Split Markdown text into chunks. Each chunk keeps its section heading as a
+ * prefix so the chunk is self-describing for retrieval.
+ */
+export function chunkMarkdown(text: string, config: ChunkingConfig = DEFAULT_CHUNKING_CONFIG): Chunk[] {
+  const sections = splitByHeaders(text);
+  const raw: string[] = [];
+  for (const section of sections) {
+    if (estimateTokens(section) <= config.chunkSize) {
+      raw.push(section);
+    } else {
+      raw.push(...recursiveSplit(section, config.chunkSize, config.chunkOverlap));
+    }
+  }
+
+  const chunks: Chunk[] = [];
+  let ordinal = 0;
+  for (const piece of raw) {
+    const trimmed = piece.trim();
+    if (!trimmed) continue;
+    if (estimateTokens(trimmed) < config.minChunkSize) continue;
+    chunks.push({
+      content: trimmed,
+      ordinal,
+      contentHash: hashContent(trimmed)
+    });
+    ordinal += 1;
+  }
+  return chunks;
+}
+
+/** Chunk a task (title + optional description) as a single block. */
+export function chunkTask(title: string, description: string | undefined, config: ChunkingConfig = DEFAULT_CHUNKING_CONFIG): Chunk[] {
+  const body = description ? `${title}\n\n${description}` : title;
+  const trimmed = body.trim();
+  if (!trimmed || estimateTokens(trimmed) < config.minChunkSize) return [];
+  return [{ content: trimmed, ordinal: 0, contentHash: hashContent(trimmed) }];
+}
+
+/** Split into header-bounded sections. Each section includes its heading line. */
+function splitByHeaders(text: string): string[] {
+  const lines = text.split(/\r?\n/);
+  const sections: string[] = [];
+  let current: string[] = [];
+  let currentHeading = "";
+
+  const flush = () => {
+    if (current.length) {
+      sections.push([...currentHeading ? [currentHeading] : [], ...current].join("\n"));
+    }
+    current = [];
+    currentHeading = "";
+  };
+
+  for (const line of lines) {
+    if (HEADER_RE.test(line)) {
+      flush();
+      currentHeading = line;
+    } else {
+      current.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+/** Recursive character splitter: paragraph → sentence → word → char. */
+function recursiveSplit(text: string, maxTokens: number, overlap: number): string[] {
+  const maxChars = maxTokens * 4;
+  const overlapChars = overlap * 4;
+  if (text.length <= maxChars) return [text];
+
+  const separators = ["\n\n", "\n", "。", ". ", "! ", "? ", " ", ""];
+  return splitRecursive(text, maxChars, overlapChars, separators, 0);
+}
+
+function splitRecursive(text: string, maxChars: number, overlapChars: number, separators: string[], depth: number): string[] {
+  if (text.length <= maxChars) return [text];
+  if (depth >= separators.length) {
+    // last resort: hard char slice with overlap
+    return hardSlice(text, maxChars, overlapChars);
+  }
+  const sep = separators[depth];
+  if (sep === "") return hardSlice(text, maxChars, overlapChars);
+
+  const parts = text.split(sep);
+  if (parts.length <= 1) return splitRecursive(text, maxChars, overlapChars, separators, depth + 1);
+
+  const chunks: string[] = [];
+  let buffer = "";
+  for (const part of parts) {
+    const candidate = buffer ? buffer + sep + part : part;
+    if (candidate.length <= maxChars) {
+      buffer = candidate;
+    } else {
+      if (buffer) chunks.push(buffer);
+      if (part.length > maxChars) {
+        chunks.push(...splitRecursive(part, maxChars, overlapChars, separators, depth + 1));
+        buffer = "";
+      } else {
+        buffer = part;
+      }
+    }
+  }
+  if (buffer) chunks.push(buffer);
+
+  // re-add overlap between chunks at this level
+  return addOverlap(chunks, sep, overlapChars);
+}
+
+function addOverlap(chunks: string[], sep: string, overlapChars: number): string[] {
+  if (chunks.length <= 1 || overlapChars <= 0) return chunks;
+  const result: string[] = [chunks[0]];
+  for (let i = 1; i < chunks.length; i++) {
+    const prev = chunks[i - 1];
+    const tail = prev.length > overlapChars ? prev.slice(-overlapChars) : prev;
+    result.push(tail + sep + chunks[i]);
+  }
+  return result;
+}
+
+function hardSlice(text: string, maxChars: number, overlapChars: number): string[] {
+  const out: string[] = [];
+  const step = Math.max(1, maxChars - overlapChars);
+  for (let i = 0; i < text.length; i += step) {
+    out.push(text.slice(i, i + maxChars));
+    if (i + maxChars >= text.length) break;
+  }
+  return out;
+}
+
+export function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
diff --git a/packages/server-local/src/modules/knowledge/indexer.test.ts b/packages/server-local/src/modules/knowledge/indexer.test.ts
new file mode 100644
index 0000000..9b3dbc8
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/indexer.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { createDatabase, createKnowledgeStore, isSqliteAvailable } from "@neo-companion/db";
+import { createKnowledgeService } from "./service";
+
+// Skipped when better-sqlite3 native binding is unavailable (this environment).
+describe.skipIf(!isSqliteAvailable())("knowledge indexer (FTS5)", () => {
+  it("reindexes a note and returns it via FTS5 search", () => {
+    const database = createDatabase(":memory:");
+    const store = createKnowledgeStore(database);
+    const service = createKnowledgeService(store);
+
+    const project = store.createProject({ title: "研究" });
+    const note = store.createNote(project.id, "RRF 检索融合");
+    store.updateNote(note.id, { body: "使用倒数排名融合 RRF 把 BM25 与向量结果合并。" });
+
+    // createNote/updateNote via store don't auto-index; service.reindexNote does.
+    service.reindexNote(store.getNote(note.id)!);
+
+    const hits = service.search(project.id, "RRF");
+    expect(hits.length).toBeGreaterThanOrEqual(1);
+    expect(hits[0].sourceId).toBe(note.id);
+    expect(hits[0].sourceType).toBe("note");
+    expect(hits[0].title).toBe("RRF 检索融合");
+    database.close();
+  });
+
+  it("scopes search to a project and dedups by source", () => {
+    const database = createDatabase(":memory:");
+    const store = createKnowledgeStore(database);
+    const service = createKnowledgeService(store);
+
+    const a = store.createProject({ title: "A" });
+    const b = store.createProject({ title: "B" });
+    const noteA = store.createNote(a.id, "向量检索");
+    store.updateNote(noteA.id, { body: "sqlite-vec 向量检索与余弦相似度。" });
+    service.reindexNote(store.getNote(noteA.id)!);
+    const noteB = store.createNote(b.id, "向量检索 B");
+    store.updateNote(noteB.id, { body: "另一个项目的向量检索内容。" });
+    service.reindexNote(store.getNote(noteB.id)!);
+
+    const scoped = service.search(a.id, "向量");
+    expect(scoped.every((h) => h.projectId === a.id)).toBe(true);
+    expect(scoped.some((h) => h.sourceId === noteA.id)).toBe(true);
+
+    const all = service.search(null, "向量");
+    expect(all.length).toBeGreaterThanOrEqual(2);
+    database.close();
+  });
+
+  it("removes stale chunks on reindex (no duplicate FTS hits)", () => {
+    const database = createDatabase(":memory:");
+    const store = createKnowledgeStore(database);
+    const service = createKnowledgeService(store);
+
+    const project = store.createProject({ title: "P" });
+    const note = store.createNote(project.id, "初稿");
+    store.updateNote(note.id, { body: "旧内容 alpha" });
+    service.reindexNote(store.getNote(note.id)!);
+    store.updateNote(note.id, { body: "新内容 beta gamma" });
+    service.reindexNote(store.getNote(note.id)!);
+
+    // old term should no longer match
+    expect(service.search(project.id, "alpha")).toHaveLength(0);
+    expect(service.search(project.id, "gamma")).toHaveLength(1);
+    database.close();
+  });
+
+  it("reports index status (fts-only when no vector ext)", () => {
+    const database = createDatabase(":memory:");
+    const store = createKnowledgeStore(database);
+    const service = createKnowledgeService(store);
+    const status = service.indexStatus(false, false);
+    expect(status.mode).toBe("fts-only");
+    expect(status.vectorExtensionAvailable).toBe(false);
+    database.close();
+  });
+
+  it("reindexAll walks every project", () => {
+    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();
+    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
new file mode 100644
index 0000000..57f0700
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/mirror.test.ts
@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { KnowledgeStore } from "@neo-companion/db";
+import { exportToDir, importFromDir } from "./mirror";
+import type {
+  KnowledgeBoardColumn,
+  KnowledgeNote,
+  KnowledgeProject,
+  KnowledgeTask,
+  KnowledgeTaskStatus
+} from "@neo-companion/shared";
+
+/** Minimal in-memory KnowledgeStore for testing the mirror's fs logic. */
+function createFakeStore(): KnowledgeStore {
+  const projects = new Map<string, KnowledgeProject>();
+  const notes = new Map<string, KnowledgeNote>();
+  const columns = new Map<string, KnowledgeBoardColumn>();
+  const tasks = new Map<string, KnowledgeTask>();
+  let counter = 0;
+  const id = () => `id-${++counter}`;
+  const now = () => Date.now();
+
+  const store: KnowledgeStore = {
+    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),
+    projectPath: (i) => {
+      const out: KnowledgeProject[] = [];
+      let cur = projects.get(i) ?? null;
+      while (cur) { out.unshift(cur); cur = cur.parentId ? projects.get(cur.parentId) ?? null : null; }
+      return out;
+    },
+    createProject: (input) => {
+      const p: KnowledgeProject = {
+        id: id(), title: input.title, description: input.description, parentId: input.parentId ?? null,
+        color: input.color, icon: input.icon, isInbox: input.isInbox ?? false, order: input.order ?? 0,
+        createdAt: now(), updatedAt: now()
+      };
+      projects.set(p.id, p); return p;
+    },
+    updateProject: (i, patch) => {
+      const ex = projects.get(i); if (!ex) return null;
+      const next: KnowledgeProject = { ...ex, ...patch, updatedAt: now() };
+      projects.set(i, next); return next;
+    },
+    deleteProject: (i) => {
+      projects.delete(i);
+      for (const [nid, n] of notes) if (n.projectId === i) notes.delete(nid);
+    },
+    ensureInbox: () => store.createProject({ title: "收件箱", isInbox: true, order: 0 }),
+    notesForProject: (pid) => [...notes.values()].filter((n) => n.projectId === pid),
+    getNote: (i) => notes.get(i) ?? null,
+    createNote: (pid, title) => {
+      const n: KnowledgeNote = { id: id(), projectId: pid, title: title || "无标题", body: "", tags: [], createdAt: now(), updatedAt: now() };
+      notes.set(n.id, n); return n;
+    },
+    updateNote: (i, patch) => {
+      const ex = notes.get(i); if (!ex) return null;
+      const next: KnowledgeNote = { ...ex, ...patch, updatedAt: now() };
+      notes.set(i, next); return next;
+    },
+    deleteNote: (i) => { notes.delete(i); },
+    backlinksFor: () => [],
+    columnsForProject: (pid) => [...columns.values()].filter((c) => c.projectId === pid).sort((a, b) => a.order - b.order),
+    createColumn: (pid, input) => {
+      const c: KnowledgeBoardColumn = { id: id(), projectId: pid, title: input.title, status: input.status, order: input.order };
+      columns.set(c.id, c); return c;
+    },
+    updateColumn: (i, patch) => {
+      const ex = columns.get(i); if (!ex) return null;
+      const next = { ...ex, ...patch };
+      columns.set(i, next); return next;
+    },
+    deleteColumn: (i) => { columns.delete(i); },
+    tasksForProject: (pid) => [...tasks.values()].filter((t) => t.projectId === pid).sort((a, b) => a.order - b.order),
+    createTask: (pid, columnId, title) => {
+      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;
+    },
+    updateTask: (i, patch) => {
+      const ex = tasks.get(i); if (!ex) return null;
+      const next: KnowledgeTask = {
+        ...ex,
+        title: patch.title ?? ex.title,
+        description: patch.description ?? ex.description,
+        status: patch.status ?? ex.status,
+        columnId: patch.columnId ?? ex.columnId,
+        order: patch.order ?? ex.order,
+        linkedNoteId: patch.linkedNoteId !== undefined ? (patch.linkedNoteId ?? undefined) : ex.linkedNoteId,
+        updatedAt: now()
+      };
+      tasks.set(i, next); return next;
+    },
+    deleteTask: (i) => { tasks.delete(i); },
+    moveTask: () => {},
+    reindexNote: () => {},
+    reindexTask: () => {},
+    removeIndex: () => {},
+    searchFts: () => [],
+    markStale: () => {},
+    getIndexStatus: () => ({
+      mode: "fts-only" as const, pending: 0, failed: 0, stale: 0,
+      providerConfigured: false, vectorExtensionAvailable: false
+    })
+  };
+  return store;
+}
+
+describe("knowledge file mirror", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = path.join(os.tmpdir(), `neo-mirror-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await fs.mkdir(dir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it("exports entities to an Obsidian-friendly folder layout", async () => {
+    const store = createFakeStore();
+    const project = store.createProject({ title: "产品研究", color: "#3b82f6", order: 1 });
+    const child = store.createProject({ title: "竞品", parentId: project.id });
+    const column = store.createColumn(project.id, { title: "待办", status: "todo" as KnowledgeTaskStatus, order: 0 });
+    store.createTask(project.id, column.id, "实现 RRF");
+    const note = store.createNote(project.id, "RRF 笔记");
+    store.updateNote(note.id, { body: "见 [[t-100]]", tags: ["技术"] });
+
+    const stats = await exportToDir(store, dir);
+    expect(stats.projects).toBe(2);
+    expect(stats.notes).toBe(1);
+    expect(stats.tasks).toBe(1);
+
+    const projectFolder = path.join(dir, "产品研究");
+    await expect(fs.readFile(path.join(projectFolder, ".neo", "project.json"), "utf8")).resolves.toContain("产品研究");
+    await expect(fs.readFile(path.join(projectFolder, "RRF 笔记.md"), "utf8")).resolves.toContain("见 [[t-100]]");
+    await expect(fs.readFile(path.join(projectFolder, ".neo", "columns.jsonl"), "utf8")).resolves.toContain("待办");
+    await expect(fs.readFile(path.join(projectFolder, ".neo", "tasks.jsonl"), "utf8")).resolves.toContain("实现 RRF");
+
+    // nested project = subfolder
+    await expect(fs.readFile(path.join(projectFolder, "竞品", ".neo", "project.json"), "utf8")).resolves.toContain("竞品");
+  });
+
+  it("imports on-disk files back into an empty store", async () => {
+    const source = createFakeStore();
+    const project = source.createProject({ title: "导入项目", order: 1 });
+    const note = source.createNote(project.id, "导入笔记");
+    source.updateNote(note.id, { body: "外部编辑内容", tags: ["x"] });
+
+    await exportToDir(source, dir);
+
+    const target = createFakeStore();
+    const stats = await importFromDir(target, dir);
+    expect(stats.importedProjects).toBe(1);
+    expect(target.listProjects()[0].title).toBe("导入项目");
+    expect(target.notesForProject(project.id)).toHaveLength(1);
+  });
+});
diff --git a/packages/server-local/src/modules/knowledge/mirror.ts b/packages/server-local/src/modules/knowledge/mirror.ts
new file mode 100644
index 0000000..b778a3e
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/mirror.ts
@@ -0,0 +1,253 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { KnowledgeStore } from "@neo-companion/db";
+import {
+  fromJsonl,
+  markdownToNote,
+  noteFileName,
+  noteToMarkdown,
+  projectFolderLayout,
+  projectToMeta,
+  sanitizeFilename,
+  toJsonl,
+  type ProjectMeta
+} from "@neo-companion/db";
+import type {
+  KnowledgeBoardColumn,
+  KnowledgeNote,
+  KnowledgeProject,
+  KnowledgeTask
+} from "@neo-companion/shared";
+
+/**
+ * File-mirror side of the hybrid knowledge store.
+ *
+ * SQLite stays canonical. `exportToDir` writes the full workspace to an
+ * Obsidian-friendly folder layout under `rootPath`; `importFromDir` reconciles
+ * on-disk edits back into SQLite with last-write-wins by `updatedAt`. Pure
+ * serialization lives in @neo-companion/db/knowledge-fs; this module owns disk
+ * I/O and is written against the `KnowledgeStore` interface so it can be tested
+ * with an in-memory fake + temp dir (no sqlite native needed).
+ */
+
+const NEO_DIR = ".neo";
+
+async function ensureDir(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function readJsonOptional<T>(file: string): Promise<T | null> {
+  try {
+    const text = await fs.readFile(file, "utf8");
+    return JSON.parse(text) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function readTextOptional(file: string): Promise<string | null> {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** Resolve the on-disk folder path for a project by walking its ancestor chain. */
+function resolveProjectFolder(rootPath: string, project: KnowledgeProject, pathById: Map<string, KnowledgeProject>): string {
+  const segments: string[] = [];
+  let current: KnowledgeProject | null = project;
+  let guard = 0;
+  while (current && guard < 32) {
+    segments.unshift(sanitizeFilename(current.title));
+    current = current.parentId ? (pathById.get(current.parentId) ?? null) : null;
+    guard += 1;
+  }
+  return path.join(rootPath, ...segments);
+}
+
+export interface MirrorStats {
+  projects: number;
+  notes: number;
+  columns: number;
+  tasks: number;
+}
+
+/** Write the entire workspace (SQLite → files). Overwrites existing mirror files. */
+export async function exportToDir(store: KnowledgeStore, rootPath: string): Promise<MirrorStats> {
+  await ensureDir(rootPath);
+  const projects = store.listProjects();
+  const pathById = new Map(projects.map((p) => [p.id, p]));
+
+  const stats: MirrorStats = { projects: 0, notes: 0, columns: 0, tasks: 0 };
+
+  for (const project of projects) {
+    const folder = resolveProjectFolder(rootPath, project, pathById);
+    const neoDir = path.join(folder, NEO_DIR);
+    await ensureDir(neoDir);
+
+    const layout = projectFolderLayout(folder);
+    await fs.writeFile(layout.projectMetaPath, JSON.stringify(projectToMeta(project), null, 2), "utf8");
+
+    const columns = store.columnsForProject(project.id);
+    await fs.writeFile(layout.columnsPath, toJsonl(columns), "utf8");
+    stats.columns += columns.length;
+
+    const tasks = store.tasksForProject(project.id);
+    await fs.writeFile(layout.tasksPath, toJsonl(tasks), "utf8");
+    stats.tasks += tasks.length;
+
+    for (const note of store.notesForProject(project.id)) {
+      await fs.writeFile(path.join(folder, noteFileName(note)), noteToMarkdown(note), "utf8");
+      stats.notes += 1;
+    }
+    stats.projects += 1;
+  }
+
+  return stats;
+}
+
+export interface ImportStats {
+  importedProjects: number;
+  importedNotes: number;
+  importedColumns: number;
+  importedTasks: number;
+  skipped: number;
+}
+
+/**
+ * Reconcile on-disk edits back into SQLite (files → SQLite), last-write-wins
+ * 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 };
+
+  const projectFolders = await collectProjectFolders(rootPath);
+  for (const folder of projectFolders) {
+    const meta = await readJsonOptional<ProjectMeta>(path.join(folder, NEO_DIR, "project.json"));
+    if (!meta) {
+      stats.skipped += 1;
+      continue;
+    }
+
+    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 });
+      stats.importedProjects += 1;
+    }
+
+    // notes
+    const entries = await fs.readdir(folder, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+      const content = await fs.readFile(path.join(folder, entry.name), "utf8");
+      const parsed = markdownToNote(content);
+      if (!parsed) continue;
+      const fm = parsed.frontMatter;
+      const existingNote = store.getNote(fm.id);
+      if (!existingNote || fm.updatedAt > existingNote.updatedAt) {
+        const noteInput: KnowledgeNote = {
+          id: fm.id,
+          projectId: meta.id,
+          title: fm.title,
+          body: parsed.body,
+          tags: fm.tags,
+          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
+        }
+        stats.importedNotes += 1;
+      }
+    }
+
+    // columns
+    const columnsText = await readTextOptional(path.join(folder, NEO_DIR, "columns.jsonl"));
+    if (columnsText) {
+      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 });
+          stats.importedColumns += 1;
+        }
+      }
+    }
+
+    // tasks
+    const tasksText = await readTextOptional(path.join(folder, NEO_DIR, "tasks.jsonl"));
+    if (tasksText) {
+      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
+            });
+          }
+          stats.importedTasks += 1;
+        }
+      }
+    }
+  }
+
+  return stats;
+}
+
+/** Recursively find folders containing a `.neo/project.json`. */
+async function collectProjectFolders(rootPath: string): Promise<string[]> {
+  const result: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === NEO_DIR) continue;
+      const child = path.join(dir, entry.name);
+      const metaExists = await readJsonOptional(path.join(child, NEO_DIR, "project.json"));
+      if (metaExists !== null) {
+        result.push(child);
+        await walk(child); // nested projects
+      }
+    }
+  }
+  await walk(rootPath);
+  return result;
+}
diff --git a/packages/server-local/src/modules/knowledge/routes.ts b/packages/server-local/src/modules/knowledge/routes.ts
new file mode 100644
index 0000000..da1a1d5
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/routes.ts
@@ -0,0 +1,283 @@
+import type { FastifyInstance } from "fastify";
+import type { KnowledgeStore } from "@neo-companion/db";
+import type {
+  KnowledgeTaskStatus
+} from "@neo-companion/shared";
+import { exportToDir, importFromDir } from "./mirror";
+import type { KnowledgeService } from "./service";
+
+/**
+ * Knowledge workspace REST routes (Phase 1 CRUD).
+ *
+ * The knowledge store requires the sqlite path; when only the memory fallback
+ * is reachable (e.g. better-sqlite3 native binding unavailable), `store` is null
+ * and these routes return 503 so the rest of the app keeps working.
+ *
+ * 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) {
+  // 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 = "";
+
+  const requireStore = (reply: import("fastify").FastifyReply): KnowledgeStore | null => {
+    if (!store) {
+      reply.code(503).send({ error: "knowledge store unavailable (sqlite not loaded)" });
+      return null;
+    }
+    return store;
+  };
+  const requireService = (reply: import("fastify").FastifyReply): KnowledgeService | null => {
+    if (!service) {
+      reply.code(503).send({ error: "knowledge index unavailable (sqlite not loaded)" });
+      return null;
+    }
+    return service;
+  };
+
+  // ── Projects ──
+  app.get("/api/knowledge/projects", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const query = request.query as { parentId?: string; root?: string };
+    if (query.parentId) return kw.childProjects(query.parentId);
+    if (query.root === "1") {
+      return kw.listProjects().filter((p) => p.parentId === null);
+    }
+    return kw.listProjects();
+  });
+
+  app.get("/api/knowledge/projects/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const project = kw.getProject(id);
+    if (!project) return reply.code(404).send({ error: "project not found" });
+    return project;
+  });
+
+  app.get("/api/knowledge/projects/:id/path", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    return kw.projectPath(id);
+  });
+
+  app.post("/api/knowledge/projects", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const body = request.body as { title?: string; parentId?: string | null; description?: string; color?: string; icon?: string };
+    if (!body.title?.trim()) return reply.code(400).send({ error: "title is required" });
+    return kw.createProject({ title: body.title, parentId: body.parentId ?? null, description: body.description, color: body.color, icon: body.icon });
+  });
+
+  app.patch("/api/knowledge/projects/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { title?: string; description?: string; color?: string; icon?: string; parentId?: string | null; order?: number };
+    const project = kw.updateProject(id, body);
+    if (!project) return reply.code(404).send({ error: "project not found" });
+    return project;
+  });
+
+  app.delete("/api/knowledge/projects/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    kw.deleteProject(id);
+    return reply.code(204).send();
+  });
+
+  // ── Notes ──
+  app.get("/api/knowledge/projects/:id/notes", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    return kw.notesForProject(id);
+  });
+
+  app.post("/api/knowledge/projects/:id/notes", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { title?: string };
+    const note = kw.createNote(id, body.title?.trim() || "无标题笔记");
+    service?.reindexNote(note);
+    return note;
+  });
+
+  app.get("/api/knowledge/notes/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const note = kw.getNote(id);
+    if (!note) return reply.code(404).send({ error: "note not found" });
+    return note;
+  });
+
+  app.patch("/api/knowledge/notes/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { title?: string; body?: string; tags?: string[] };
+    const note = kw.updateNote(id, body);
+    if (!note) return reply.code(404).send({ error: "note not found" });
+    service?.reindexNote(note);
+    return note;
+  });
+
+  app.delete("/api/knowledge/notes/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    kw.deleteNote(id);
+    service && kw; // removeIndex handled by store.deleteNote cascade (chunks deleted)
+    return reply.code(204).send();
+  });
+
+  app.get("/api/knowledge/notes/:id/backlinks", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    return kw.backlinksFor(id);
+  });
+
+  // ── Board columns ──
+  app.get("/api/knowledge/projects/:id/columns", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    return kw.columnsForProject(id);
+  });
+
+  app.post("/api/knowledge/projects/:id/columns", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { title?: string; status?: KnowledgeTaskStatus; order?: number };
+    if (!body.title?.trim()) return reply.code(400).send({ error: "title is required" });
+    return kw.createColumn(id, { title: body.title, status: body.status ?? "todo", order: body.order ?? 0 });
+  });
+
+  app.patch("/api/knowledge/columns/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { title?: string; status?: KnowledgeTaskStatus; order?: number };
+    const column = kw.updateColumn(id, body);
+    if (!column) return reply.code(404).send({ error: "column not found" });
+    return column;
+  });
+
+  app.delete("/api/knowledge/columns/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    kw.deleteColumn(id);
+    return reply.code(204).send();
+  });
+
+  // ── Tasks ──
+  app.get("/api/knowledge/projects/:id/tasks", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    return kw.tasksForProject(id);
+  });
+
+  app.post("/api/knowledge/projects/:id/tasks", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { columnId?: string; title?: string };
+    if (!body.title?.trim()) return reply.code(400).send({ error: "title is required" });
+    const task = kw.createTask(id, body.columnId ?? "", body.title);
+    service?.reindexTask(task);
+    return task;
+  });
+
+  app.patch("/api/knowledge/tasks/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { title?: string; description?: string; status?: KnowledgeTaskStatus; columnId?: string; order?: number; linkedNoteId?: string | null };
+    const task = kw.updateTask(id, body);
+    if (!task) return reply.code(404).send({ error: "task not found" });
+    if (body.title !== undefined || body.description !== undefined) service?.reindexTask(task);
+    return task;
+  });
+
+  app.delete("/api/knowledge/tasks/:id", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    kw.deleteTask(id);
+    return reply.code(204).send();
+  });
+
+  app.post("/api/knowledge/tasks/:id/move", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const { id } = request.params as { id: string };
+    const body = request.body as { columnId?: string; index?: number };
+    kw.moveTask(id, body.columnId ?? "", body.index ?? 0);
+    return reply.code(204).send();
+  });
+
+  // ── Retrieval (Phase 2: FTS5; Phase 3 adds vec + RRF) ──
+  app.get("/api/knowledge/search", async (request, reply) => {
+    const svc = requireService(reply);
+    if (!svc) return;
+    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);
+  });
+
+  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);
+  });
+
+  app.post("/api/knowledge/reindex", async (request, reply) => {
+    const svc = requireService(reply);
+    if (!svc) return;
+    const body = (request.body as { embeddingModel?: string } | null) ?? {};
+    if (body.embeddingModel) svc.markStale(body.embeddingModel);
+    return svc.reindexAll();
+  });
+
+  // ── File mirror (hybrid SQLite + Markdown/JSONL) ──
+  app.get("/api/knowledge/root-path", async () => ({ path: rootPath }));
+
+  app.put("/api/knowledge/root-path", async (request, reply) => {
+    const body = request.body as { path?: string };
+    rootPath = (body.path ?? "").trim();
+    return { path: rootPath };
+  });
+
+  app.post("/api/knowledge/mirror/export", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    const body = (request.body as { path?: string } | null) ?? {};
+    const target = (body.path ?? rootPath).trim();
+    if (!target) return reply.code(400).send({ error: "rootPath not set" });
+    const stats = await exportToDir(kw, target);
+    return stats;
+  });
+
+  app.post("/api/knowledge/mirror/import", async (request, reply) => {
+    const kw = requireStore(reply);
+    if (!kw) return;
+    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);
+    return stats;
+  });
+}
diff --git a/packages/server-local/src/modules/knowledge/service.ts b/packages/server-local/src/modules/knowledge/service.ts
new file mode 100644
index 0000000..a4a3378
--- /dev/null
+++ b/packages/server-local/src/modules/knowledge/service.ts
@@ -0,0 +1,66 @@
+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";
+
+/**
+ * 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.
+ */
+export function createKnowledgeService(store: KnowledgeStore) {
+  const config = resolveChunkingConfig();
+
+  function chunkNoteText(text: string): { content: string; contentHash: string }[] {
+    return chunkMarkdown(text, config).map((c: Chunk) => ({ content: c.content, contentHash: c.contentHash }));
+  }
+  function chunkTaskText(text: string): { content: string; contentHash: string }[] {
+    return chunkTask("", text, config).map((c: Chunk) => ({ content: c.content, contentHash: c.contentHash }));
+  }
+
+  return {
+    config,
+
+    reindexNote(note: KnowledgeNote): void {
+      store.reindexNote(note, chunkNoteText);
+    },
+
+    reindexTask(task: KnowledgeTask): void {
+      store.reindexTask(task, (text) => chunkTaskText(text));
+    },
+
+    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);
+    },
+
+    markStale(embeddingModel?: string): void {
+      store.markStale(embeddingModel);
+    },
+
+    /** Re-chunk every note + task in the workspace (manual rebuild). */
+    reindexAll(): { notes: number; tasks: number } {
+      let notes = 0;
+      let tasks = 0;
+      for (const project of store.listProjects()) {
+        for (const note of store.notesForProject(project.id)) {
+          store.reindexNote(note, chunkNoteText);
+          notes += 1;
+        }
+        for (const task of store.tasksForProject(project.id)) {
+          store.reindexTask(task, (text) => chunkTaskText(text));
+          tasks += 1;
+        }
+      }
+      return { notes, tasks };
+    }
+  };
+}
+
+export type KnowledgeService = ReturnType<typeof createKnowledgeService>;
+
+// re-export status type for route typing
+export type { KnowledgeTaskStatus };
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 5504ad2..3bd8663 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -150,3 +150,100 @@ export interface PermissionAutoDismissPayload {
 
 export const DEFAULT_DEEPSEEK_MODEL = "deepseek-v4-flash";
 export const LEGACY_DEEPSEEK_MODELS = new Set(["deepseek-chat", "deepseek-reasoner"]);
+
+// ── Knowledge Workspace (v2) ──
+// These types match the frontend mock contract (useKnowledgeMock.ts), which is
+// the de-facto UI contract: epoch-ms timestamps, BoardColumn scoped directly to
+// a project (no boards layer — YAGNI for the current UI), optional color/icon.
+// Note: the v1 pet-panel task feature keeps its own `open|done` TaskStatus above;
+// knowledge kanban tasks use a separate 4-state status and table. Unifying the
+// two is tracked in docs/TODO_INVENTORY.md.
+
+export interface KnowledgeProject {
+  id: string;
+  title: string;
+  description?: string;
+  parentId: string | null;
+  color?: string;
+  icon?: string;
+  isInbox?: boolean;
+  order: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface KnowledgeNote {
+  id: string;
+  projectId: string;
+  title: string;
+  /** Markdown 全文（SSOT）。列表显示请用 excerpt 派生。 */
+  body: string;
+  tags: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export type KnowledgeTaskStatus = "todo" | "doing" | "done" | "archived";
+
+/** 看板列，直接归属项目（当前 UI 不暴露多看板层）。 */
+export interface KnowledgeBoardColumn {
+  id: string;
+  projectId: string;
+  title: string;
+  status: KnowledgeTaskStatus;
+  order: number;
+}
+
+export interface KnowledgeTask {
+  id: string;
+  projectId: string;
+  columnId: string;
+  title: string;
+  description?: string;
+  status: KnowledgeTaskStatus;
+  order: number;
+  linkedNoteId?: string;
+  tags: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** A retrieval hit used as a citable source in AI answers. */
+export interface KnowledgeSource {
+  sourceType: "note" | "task";
+  sourceId: string;
+  projectId: string;
+  title: string;
+  excerpt: string;
+  chunkId: string;
+}
+
+/** Rich index status returned by the API; the UI maps it to KnowledgeIndexState. */
+export type IndexMode = "hybrid" | "fts-only";
+
+export interface IndexStatus {
+  mode: IndexMode;
+  pending: number;
+  failed: number;
+  stale: number;
+  providerConfigured: boolean;
+  vectorExtensionAvailable: boolean;
+}
+
+/** Simplified UI state consumed by IndexStatusDot. */
+export type KnowledgeIndexState = "ok" | "fts_only" | "indexing";
+
+/** open-notebook RAG移植：AI 对话的两种检索模式。 */
+export type AiRetrievalMode = "chat" | "ask";
+
+/** open-notebook 移植：每条笔记/任务进入 AI 上下文的三级权限。 */
+export type ContextLevel = "full" | "summary" | "excluded";
+
+/** AI 对话统一响应：文本 + 服务端生成的可引用来源 + 实际检索模式。 */
+export interface AiAnswer {
+  text: string;
+  sources: KnowledgeSource[];
+  retrievalMode: AiRetrievalMode;
+}
+
+export type KnowledgeChunkIndexStatus = "pending" | "indexed" | "failed" | "stale";

From a66b2b1de6033d192d3dccb06e5078b708c5daf4 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 16:18:02 +0800
Subject: [PATCH 3/5] =?UTF-8?q?fix(knowledge):=20FTS5=20=E7=94=A8=20trigra?=
 =?UTF-8?q?m=20=E5=88=86=E8=AF=8D=E5=99=A8=20+=20=E5=89=8D=E7=BC=80?=
 =?UTF-8?q?=E6=9F=A5=E8=AF=A2=E4=BF=AE=E5=A4=8D=E4=B8=AD=E6=96=87=E6=A3=80?=
 =?UTF-8?q?=E7=B4=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI(linux) 跑 indexer 集成测试时，「按项目范围搜索」用例失败：FTS5 默认
unicode61 分词器对中文不分词，"向量" 短语匹配不上「向量检索…」正文。

- knowledge_chunks_fts 改用 tokenize='trigram'（FTS5 内置，SQLite 3.34+，
  对中文做 3-gram 分词）
- sanitizeFtsQuery 改为前缀查询 "term"*，使短词（<3 字符）也能经
  trigram 前缀展开命中
---
 packages/db/src/index.ts | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index ca8445e..6dcd65d 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -206,7 +206,8 @@ export function initSchema(sqlite: Database.Database) {
       project_id UNINDEXED,
       source_type UNINDEXED,
       source_id UNINDEXED,
-      content_hash UNINDEXED
+      content_hash UNINDEXED,
+      tokenize = 'trigram'
     );
   `);
 }
@@ -929,14 +930,14 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
     return `'${value.replace(/'/g, "''")}'`;
   }
   function sanitizeFtsQuery(query: string): string {
-    // FTS5 query syntax: keep alphanumeric + CJK, wrap terms; strip operators.
+    // trigram tokenizer: split into terms, OR-join as prefix queries so short
+    // CJK terms (e.g. 2-char "向量") still match via trigram prefix expansion.
     const terms = query
       .split(/[\s,，。、]+/)
       .map((t) => t.replace(/[^\p{L}\p{N}]+/gu, ""))
       .filter(Boolean);
     if (!terms.length) return "";
-    // OR-join quoted terms so a multi-word query matches any term (lenient).
-    return terms.map((t) => `"${t.replace(/"/g, "")}"`).join(" OR ");
+    return terms.map((t) => `"${t.replace(/"/g, "")}"*`).join(" OR ");
   }
 
   // silence unused binding reserved for Phase 3 raw-vec access

From ea7a250730f4d877c9406a3bf5edbff2859aa8f3 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 16:20:33 +0800
Subject: [PATCH 4/5] =?UTF-8?q?fix(knowledge):=20=E7=9F=AD=E4=B8=AD?=
 =?UTF-8?q?=E6=96=87=E8=AF=8D=E6=A3=80=E7=B4=A2=E5=9B=9E=E9=80=80=20LIKE?=
 =?UTF-8?q?=20=E5=AD=90=E4=B8=B2=E5=8C=B9=E9=85=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

trigram 分词器索引 3-gram，查询词 <3 字符（如「向量」）的 MATCH
前缀查询仍不命中。改为：查询词均 ≥3 字符时走 FTS5 MATCH + BM25 排序；
否则回退 LIKE %term% 子串扫描（保留项目范围过滤），按命中返回。
Phase 3 向量检索将接管语义排序，此 LIKE 路径为短词兜底。
---
 packages/db/src/index.ts | 45 ++++++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 6dcd65d..69fffc5 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -847,20 +847,32 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   }
 
   function searchFts(projectId: string | null, query: string, limit: number): KnowledgeSource[] {
-    const sanitized = sanitizeFtsQuery(query);
-    if (!sanitized) return [];
-    // FTS5 BM25 via match(); rank by bm25(). Scope by project_id when given.
-    const sql = projectId
-      ? `SELECT k.source_type, k.source_id, k.project_id, k.content,
+    // trigram tokenizer indexes 3-grams, so CJK queries shorter than 3 chars
+    // (e.g. "向量") won't MATCH reliably. Use FTS5 MATCH for BM25 ranking when
+    // the query is long enough, and fall back to a LIKE substring scan for
+    // short queries so 2-char Chinese terms still hit.
+    const terms = extractTerms(query);
+    if (!terms.length) return [];
+    const useMatch = terms.every((t) => [...t].length >= 3);
+    const cap = Math.max(1, Math.min(limit, 50));
+    const projectClause = projectId ? ` AND k.project_id = ${sqlStr(projectId)}` : "";
+
+    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,
                 bm25(knowledge_chunks_fts) AS rank
          FROM knowledge_chunks_fts k
-         WHERE k.content MATCH ${sqlStr(sanitized)} AND k.project_id = ${sqlStr(projectId)}
-         ORDER BY rank LIMIT ${Math.max(1, Math.min(limit, 50))}`
-      : `SELECT k.source_type, k.source_id, k.project_id, k.content,
-                bm25(knowledge_chunks_fts) AS rank
+         WHERE k.content MATCH ${sqlStr(ftsQuery)}${projectClause}
+         ORDER BY rank LIMIT ${cap}`;
+    } 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
          FROM knowledge_chunks_fts k
-         WHERE k.content MATCH ${sqlStr(sanitized)}
-         ORDER BY rank LIMIT ${Math.max(1, Math.min(limit, 50))}`;
+         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;
     }>;
@@ -929,15 +941,12 @@ export function createKnowledgeStore(database: NeoDatabase): KnowledgeStore {
   function sqlStr(value: string): string {
     return `'${value.replace(/'/g, "''")}'`;
   }
-  function sanitizeFtsQuery(query: string): string {
-    // trigram tokenizer: split into terms, OR-join as prefix queries so short
-    // CJK terms (e.g. 2-char "向量") still match via trigram prefix expansion.
-    const terms = query
-      .split(/[\s,，。、]+/)
+  function extractTerms(query: string): string[] {
+    // Split on whitespace + common CJK punctuation; keep letters/numbers (incl. CJK).
+    return query
+      .split(/[\s,，。、；;！!？?]+/)
       .map((t) => t.replace(/[^\p{L}\p{N}]+/gu, ""))
       .filter(Boolean);
-    if (!terms.length) return "";
-    return terms.map((t) => `"${t.replace(/"/g, "")}"*`).join(" OR ");
   }
 
   // silence unused binding reserved for Phase 3 raw-vec access

From bf08b58dabed5179feb12ddf7de7d5aab72e1147 Mon Sep 17 00:00:00 2001
From: Yumiue <229866007@qq.com>
Date: Sat, 20 Jun 2026 16:24:13 +0800
Subject: [PATCH 5/5] =?UTF-8?q?fix(ci):=20=E7=BB=99=20scripts/verify-docs.?=
 =?UTF-8?q?sh=20=E5=8A=A0=E5=8F=AF=E6=89=A7=E8=A1=8C=E4=BD=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

该脚本在 d53f4bf 引入时 git 存为 100644（非可执行），CI checkout 后
'Verify documentation consistency' 步骤 Permission denied (exit 126)。
---
 scripts/verify-docs.sh | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 scripts/verify-docs.sh

diff --git a/scripts/verify-docs.sh b/scripts/verify-docs.sh
old mode 100644
new mode 100755