feat(workspace): 接入真实Vault数据链路

frontend/src/contracts/index.ts

@@ -24,6 +24,7 @@ export interface NoteBlock {
 
 export interface FileNode {
   id: string
+  note_id?: string
   name: string
   path: string
   type: 'file' | 'folder'
@@ -387,6 +388,29 @@ export interface PageMeta {
   offset: number
 }
 
+export interface ApiWorkspaceInfo {
+  vault_id: string
+  name: string
+  path: string
+  file_count: number
+  indexed_note_count: number
+  requires_refresh: boolean
+}
+
+export interface ApiWorkspaceEntry {
+  entry_id: string
+  name: string
+  path: string
+  type: 'file' | 'folder'
+  note_id?: string | null
+  children: ApiWorkspaceEntry[]
+}
+
+export interface ApiWorkspaceSnapshot {
+  workspace: ApiWorkspaceInfo
+  items: ApiWorkspaceEntry[]
+}
+
 export interface OperationResponse {
   status: 'accepted' | 'completed'
   resource_id?: string | null

frontend/src/features/editor/EditorPane.spec.ts

@@ -1,10 +1,11 @@
 // @vitest-environment happy-dom
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mount, type VueWrapper } from '@vue/test-utils'
 import { createPinia, setActivePinia } from 'pinia'
 import { nextTick } from 'vue'
 import EditorPane from './EditorPane.vue'
 import { useEditorStore } from '@/stores/editor'
+import * as workspaceService from '@/services/workspaceService'
 
 let wrapper: VueWrapper | null = null
 
@@ -19,12 +20,20 @@ async function waitForText(text: string) {
 beforeEach(() => {
   localStorage.clear()
   setActivePinia(createPinia())
+  vi.spyOn(workspaceService, 'readFileContent').mockImplementation(async (filePath) => {
+    if (filePath === '/欢迎使用 NotesAgent.md') {
+      return '# 欢迎使用 NotesAgent\n\n祝你写作愉快'
+    }
+    if (filePath === '/数据结构/红黑树.md') return '# 红黑树\n\n新的文件内容'
+    throw new Error(`Unexpected file path: ${filePath}`)
+  })
 })
 
 afterEach(() => {
   wrapper?.unmount()
   wrapper = null
   document.body.innerHTML = ''
+  vi.restoreAllMocks()
 })
 
 describe('EditorPane file switching', () => {

frontend/src/features/vault/VaultEntry.vue

@@ -4,7 +4,7 @@ import { useRouter } from 'vue-router'
 import { useWorkspaceStore } from '@/stores/workspace'
 import { useThemeStore } from '@/stores/theme'
 import { useSettingsStore } from '@/stores/settings'
-import { ArrowRight, Document, Folder, FolderOpened, Moon, Plus, Sunny } from '@element-plus/icons-vue'
+import { ArrowRight, Document, Folder, FolderOpened, Moon, Sunny } from '@element-plus/icons-vue'
 import AppIcon from '@/components/common/AppIcon.vue'
 
 const router = useRouter()
@@ -13,17 +13,19 @@ const themeStore = useThemeStore()
 const settingsStore = useSettingsStore()
 
 const isLoading = ref(false)
-const showCreateDialog = ref(false)
-const newVaultName = ref('')
-const newVaultPath = ref('')
 const aiCoreStatus = ref<'checking' | 'running' | 'stopped'>('checking')
 
 onMounted(async () => {
-  await Promise.all([workspaceStore.loadRecentVaults(), settingsStore.loadDiagnostics()])
+  await Promise.allSettled([workspaceStore.loadRecentVaults(), settingsStore.loadDiagnostics()])
   const lastVaultPath = localStorage.getItem('last-vault-path')
   if (settingsStore.restoreLastVault && lastVaultPath) {
-    await openVault(lastVaultPath)
-    return
+    try {
+      await openVault(lastVaultPath)
+      return
+    } catch {
+      // Mock 阶段保存的旧路径可能与当前后端 Vault 不同，清除后让用户重新选择。
+      localStorage.removeItem('last-vault-path')
+    }
   }
   setTimeout(() => {
     aiCoreStatus.value = settingsStore.aiCoreStatus === 'running' ? 'running' : 'stopped'
@@ -41,24 +43,8 @@ async function openVault(path: string) {
 }
 
 async function openFolderPicker() {
-  // In Tauri this would use the native dialog
-  // For web dev, simulate
-  const path = prompt('请输入 Vault 路径（开发模式）', '/Users/demo/Documents/MyVault')
-  if (path) {
-    await openVault(path)
-  }
-}
-
-async function createVault() {
-  if (!newVaultName.value || !newVaultPath.value) return
-  isLoading.value = true
-  try {
-    await workspaceStore.createVault(newVaultPath.value, newVaultName.value)
-    router.push('/workspace')
-  } finally {
-    isLoading.value = false
-    showCreateDialog.value = false
-  }
+  const configured = workspaceStore.recentVaults[0]
+  if (configured) await openVault(configured.path)
 }
 </script>
 
@@ -74,7 +60,7 @@ async function createVault() {
 
       <div class="vault-card">
         <h2 class="card-title">选择知识库</h2>
-        <p class="card-desc">选择一个本地 Vault 开始你的知识之旅</p>
+        <p class="card-desc">Web 联调模式连接 AI Core 当前配置的 Vault</p>
 
         <div v-if="workspaceStore.recentVaults.length" class="recent-vaults">
           <div class="section-label">最近打开</div>
@@ -97,11 +83,8 @@ async function createVault() {
         </div>
 
         <div class="actions">
-          <button class="btn btn-primary" @click="openFolderPicker" :disabled="isLoading">
-            <AppIcon :icon="FolderOpened" /> 打开本地 Vault
-          </button>
-          <button class="btn btn-secondary" @click="showCreateDialog = true" :disabled="isLoading">
-            <AppIcon :icon="Plus" /> 创建新 Vault
+          <button class="btn btn-primary" @click="openFolderPicker" :disabled="isLoading || !workspaceStore.recentVaults.length">
+            <AppIcon :icon="FolderOpened" /> 打开后端 Vault
           </button>
         </div>
 
@@ -122,24 +105,6 @@ async function createVault() {
       </div>
     </div>
 
-    <!-- Create Vault Dialog -->
-    <div v-if="showCreateDialog" class="dialog-overlay" @click.self="showCreateDialog = false">
-      <div class="dialog">
-        <h3>创建新 Vault</h3>
-        <div class="form-group">
-          <label>Vault 名称</label>
-          <input v-model="newVaultName" type="text" placeholder="我的知识库" />
-        </div>
-        <div class="form-group">
-          <label>存储路径</label>
-          <input v-model="newVaultPath" type="text" placeholder="/path/to/vault" />
-        </div>
-        <div class="dialog-actions">
-          <button class="btn btn-secondary" @click="showCreateDialog = false">取消</button>
-          <button class="btn btn-primary" @click="createVault" :disabled="!newVaultName || !newVaultPath">创建</button>
-        </div>
-      </div>
-    </div>
   </div>
 </template>
 
@@ -408,67 +373,5 @@ async function createVault() {
   }
 }
 
-.dialog-overlay {
-  position: fixed;
-  inset: 0;
-  background: var(--color-background-overlay);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  z-index: var(--z-modal);
-  animation: dialog-backdrop-in var(--motion-fast) both;
-}
-
-.dialog {
-  background: var(--color-surface-primary);
-  border-radius: var(--radius-lg);
-  padding: var(--space-xl);
-  width: 90%;
-  max-width: 400px;
-  box-shadow: var(--shadow-xl);
-  animation: dialog-in var(--motion-normal) both;
-}
-
 @keyframes entry-in { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }
-@keyframes dialog-backdrop-in { from { opacity: 0; } to { opacity: 1; } }
-@keyframes dialog-in { from { opacity: 0; transform: translateY(8px) scale(.985); } to { opacity: 1; transform: translateY(0) scale(1); } }
-
-.dialog h3 {
-  margin: 0 0 var(--space-lg) 0;
-  font-size: 18px;
-}
-
-.form-group {
-  margin-bottom: var(--space-md);
-
-  label {
-    display: block;
-    font-size: 13px;
-    color: var(--color-text-secondary);
-    margin-bottom: var(--space-xs);
-  }
-
-  input {
-    width: 100%;
-    padding: 8px 12px;
-    background: var(--color-background-secondary);
-    border: 1px solid var(--color-border-default);
-    border-radius: var(--radius-md);
-    font-size: 14px;
-    color: var(--color-text-primary);
-    outline: none;
-    transition: border-color var(--motion-fast);
-
-    &:focus {
-      border-color: var(--color-border-focus);
-    }
-  }
-}
-
-.dialog-actions {
-  display: flex;
-  justify-content: flex-end;
-  gap: var(--space-sm);
-  margin-top: var(--space-lg);
-}
 </style>

frontend/src/features/workspace/FileTreePanel.spec.ts

@@ -1,11 +1,12 @@
 // @vitest-environment happy-dom
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mount, type VueWrapper } from '@vue/test-utils'
 import { createPinia, setActivePinia } from 'pinia'
 import { createMemoryHistory, createRouter } from 'vue-router'
 import FileTreePanel from './FileTreePanel.vue'
 import { useEditorStore } from '@/stores/editor'
 import { useWorkspaceStore } from '@/stores/workspace'
+import * as workspaceService from '@/services/workspaceService'
 
 let wrapper: VueWrapper | null = null
 
@@ -21,12 +22,26 @@ async function waitForPath(path: string) {
 beforeEach(() => {
   localStorage.clear()
   setActivePinia(createPinia())
+  vi.spyOn(workspaceService, 'openVault').mockResolvedValue({ path: 'C:/vault', name: 'vault' })
+  vi.spyOn(workspaceService, 'getFileTree').mockResolvedValue([
+    {
+      id: 'folder-data', name: '数据结构', path: '/数据结构', type: 'folder', is_open: true,
+      children: [
+        { id: 'note-rbt', note_id: 'note-rbt', name: '红黑树.md', path: '/数据结构/红黑树.md', type: 'file' },
+        { id: 'note-bst', note_id: 'note-bst', name: '二叉搜索树.md', path: '/数据结构/二叉搜索树.md', type: 'file' },
+      ],
+    },
+  ])
+  vi.spyOn(workspaceService, 'readFileContent').mockImplementation(async (path) =>
+    path.includes('红黑树') ? '# 红黑树\n' : '# 二叉搜索树\n'
+  )
 })
 
 afterEach(() => {
   wrapper?.unmount()
   wrapper = null
   document.body.innerHTML = ''
+  vi.restoreAllMocks()
 })
 
 describe('FileTreePanel file switching', () => {
@@ -40,7 +55,7 @@ describe('FileTreePanel file switching', () => {
 
     const workspaceStore = useWorkspaceStore()
     const editorStore = useEditorStore()
-    await workspaceStore.openVault('/mock-vault')
+    await workspaceStore.openVault('C:/vault')
     wrapper = mount(FileTreePanel, { attachTo: document.body, global: { plugins: [router] } })
 
     const findNode = (name: string) => wrapper!.findAll('.tree-node').find((node) => node.text().includes(name))!

frontend/src/features/workspace/WorkspaceView.spec.ts

@@ -17,16 +17,16 @@ afterEach(() => {
   wrapper = null
 })
 
-describe('WorkspaceView initial file', () => {
-  it('does not overwrite a file selected while the welcome note is loading', async () => {
+describe('WorkspaceView empty state', () => {
+  it('does not fabricate a Mock welcome note when no backend file is selected', async () => {
     const workspaceStore = useWorkspaceStore()
     wrapper = mount(WorkspaceView, {
       global: { stubs: { EditorHeader: true, EditorPane: true } },
     })
 
-    workspaceStore.openFile('/数据结构/红黑树.md')
     await new Promise((resolve) => setTimeout(resolve, 0))
 
-    expect(workspaceStore.activeFilePath).toBe('/数据结构/红黑树.md')
+    expect(workspaceStore.activeFilePath).toBeNull()
+    expect(wrapper.find('.empty-workspace').exists()).toBe(true)
   })
 })

frontend/src/features/workspace/WorkspaceView.vue

@@ -1,28 +1,11 @@
 <script setup lang="ts">
-import { onMounted } from 'vue'
 import { useWorkspaceStore } from '@/stores/workspace'
-import { useEditorStore } from '@/stores/editor'
 import EditorHeader from '@/features/editor/EditorHeader.vue'
 import EditorPane from '@/features/editor/EditorPane.vue'
 import { EditPen } from '@element-plus/icons-vue'
 import AppIcon from '@/components/common/AppIcon.vue'
 
 const workspaceStore = useWorkspaceStore()
-const editorStore = useEditorStore()
-
-onMounted(() => {
-  if (!workspaceStore.fileTree.length && workspaceStore.hasVault) {
-    // Already loaded
-  }
-  if (!workspaceStore.activeFilePath && workspaceStore.fileTree.length === 0) {
-    void editorStore.loadFile('/欢迎使用 NotesAgent.md').then(() => {
-      // 默认文件加载期间用户可能已经点击了其他文件，不能覆盖用户的选择。
-      if (!workspaceStore.activeFilePath && editorStore.currentFilePath === '/欢迎使用 NotesAgent.md') {
-        workspaceStore.openFile('/欢迎使用 NotesAgent.md')
-      }
-    })
-  }
-})
 </script>
 
 <template>

frontend/src/services/noteService.ts

@@ -37,3 +37,7 @@ export async function deleteNote(noteId: string): Promise<OperationResponse> {
 export async function moveNote(noteId: string, folder: string): Promise<ApiNote> {
   return apiClient.post(`/api/notes/${noteId}/move`, { folder })
 }
+
+export async function renameNote(noteId: string, fileName: string): Promise<ApiNote> {
+  return apiClient.post(`/api/notes/${noteId}/rename`, { file_name: fileName })
+}

frontend/src/services/workspaceService.spec.ts

@@ -0,0 +1,126 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiErrorClass } from './apiClient'
+import * as workspaceService from './workspaceService'
+
+function jsonResponse(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+const workspaceSnapshot = {
+  workspace: {
+    vault_id: 'default',
+    name: 'vault',
+    path: 'C:\\data\\vault',
+    file_count: 1,
+    indexed_note_count: 1,
+    requires_refresh: false,
+  },
+  items: [
+    {
+      entry_id: 'folder-course',
+      name: '课程',
+      path: '/课程',
+      type: 'folder',
+      note_id: null,
+      children: [
+        {
+          entry_id: 'note-os',
+          note_id: 'note-os',
+          name: '操作系统.md',
+          path: '/课程/操作系统.md',
+          type: 'file',
+          children: [],
+        },
+      ],
+    },
+  ],
+}
+
+beforeEach(() => {
+  vi.stubGlobal('fetch', vi.fn())
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('workspaceService backend adapter', () => {
+  it('opens the configured Vault and reads/saves Markdown through Note API', async () => {
+    const fetchMock = vi.mocked(fetch)
+    fetchMock.mockImplementation(async (input, init) => {
+      const url = String(input)
+      if (url === '/api/workspace/open') return jsonResponse(workspaceSnapshot)
+      if (url === '/api/notes/note-os' && init?.method === 'GET') {
+        return jsonResponse({
+          note_id: 'note-os', title: '操作系统', file_path: '课程/操作系统.md', tags: [],
+          created_at: '2026-08-31T00:00:00Z', updated_at: '2026-08-31T00:00:00Z',
+          markdown: '# 操作系统\n', blocks: [],
+        })
+      }
+      if (url === '/api/notes/note-os' && init?.method === 'PATCH') {
+        return jsonResponse({})
+      }
+      throw new Error(`Unexpected request: ${init?.method} ${url}`)
+    })
+
+    const vault = await workspaceService.openVault('C:\\data\\vault')
+    const tree = await workspaceService.getFileTree()
+    const markdown = await workspaceService.readFileContent('/课程/操作系统.md')
+    await workspaceService.saveFileContent('/课程/操作系统.md', '# 已更新\n')
+
+    expect(vault).toEqual({ path: 'C:\\data\\vault', name: 'vault' })
+    expect(tree[0].children?.[0]).toMatchObject({
+      id: 'note-os', note_id: 'note-os', path: '/课程/操作系统.md', type: 'file',
+    })
+    expect(markdown).toBe('# 操作系统\n')
+    const patchCall = fetchMock.mock.calls.find(([, init]) => init?.method === 'PATCH')
+    expect(JSON.parse(String(patchCall?.[1]?.body))).toEqual({ markdown: '# 已更新\n' })
+  })
+
+  it('creates notes and folders with Vault-relative paths', async () => {
+    const fetchMock = vi.mocked(fetch)
+    fetchMock.mockImplementation(async (input, init) => {
+      const url = String(input)
+      if (url === '/api/workspace/open') return jsonResponse(workspaceSnapshot)
+      if (url === '/api/notes' && init?.method === 'POST') {
+        return jsonResponse({
+          note_id: 'note-new', title: '新笔记', file_path: '课程/新笔记.md', tags: [],
+          created_at: '2026-08-31T00:00:00Z', updated_at: '2026-08-31T00:00:00Z',
+          markdown: '# 新笔记\n', blocks: [],
+        })
+      }
+      if (url === '/api/workspace/folders' && init?.method === 'POST') {
+        return jsonResponse({
+          entry_id: 'folder-child', name: '子目录', path: '/课程/子目录', type: 'folder',
+          note_id: null, children: [],
+        })
+      }
+      throw new Error(`Unexpected request: ${init?.method} ${url}`)
+    })
+    await workspaceService.openVault('C:\\data\\vault')
+
+    const note = await workspaceService.createFile('/课程', '新笔记.md', '# 新笔记\n')
+    const folder = await workspaceService.createFolder('/课程', '子目录')
+
+    expect(note).toMatchObject({ id: 'note-new', path: '/课程/新笔记.md' })
+    expect(folder).toMatchObject({ id: 'folder-child', path: '/课程/子目录' })
+    const bodies = fetchMock.mock.calls
+      .filter(([, init]) => init?.method === 'POST')
+      .map(([, init]) => JSON.parse(String(init?.body)))
+    expect(bodies).toContainEqual({ title: '新笔记', folder: '课程', markdown: '# 新笔记\n' })
+    expect(bodies).toContainEqual({ parent: '课程', name: '子目录' })
+  })
+
+  it('reports backend connectivity errors instead of falling back to Mock data', async () => {
+    vi.mocked(fetch).mockRejectedValue(new Error('offline'))
+
+    await expect(workspaceService.getWorkspaceInfo()).rejects.toEqual(
+      expect.objectContaining<Partial<ApiErrorClass>>({ code: 'NETWORK_ERROR' }),
+    )
+  })
+})

frontend/src/services/workspaceService.ts

@@ -1,258 +1,171 @@
-import type { FileNode } from '@/contracts'
-
-// Web 开发模式使用内存实现，服务签名保持与未来桌面文件系统适配器一致。
-// TODO(desktop): Tauri Host 就绪后通过 IPC 替换 Mock，并保留路径规范化与错误映射。
+import type {
+  ApiNote,
+  ApiWorkspaceEntry,
+  ApiWorkspaceInfo,
+  ApiWorkspaceSnapshot,
+  FileNode,
+  OperationResponse,
+} from '@/contracts'
+import apiClient from './apiClient'
+import * as noteService from './noteService'
 
+/** Web 联调只连接 AI Core 配置的单一 Vault；多 Vault 选择由 Tauri Host 接管。 */
 export interface VaultInfo {
   path: string
   name: string
 }
 
-const MOCK_VAULTS: VaultInfo[] = [
-  { path: '/Users/demo/Documents/MyVault', name: '我的知识库' },
-  { path: '/Users/demo/Documents/StudyNotes', name: '学习笔记' },
-]
+let cachedTree: FileNode[] | null = null
+const noteIdByPath = new Map<string, string>()
+const typeByPath = new Map<string, FileNode['type']>()
 
-const MOCK_FILE_TREE: FileNode[] = [
-  {
-    id: 'f-data',
-    name: '数据结构',
-    path: '/数据结构',
-    type: 'folder',
-    is_open: true,
-    children: [
-      { id: 'n-rbt', name: '红黑树.md', path: '/数据结构/红黑树.md', type: 'file' },
-      { id: 'n-bst', name: '二叉搜索树.md', path: '/数据结构/二叉搜索树.md', type: 'file' },
-      {
-        id: 'f-list',
-        name: '链表',
-        path: '/数据结构/链表',
-        type: 'folder',
-        is_open: false,
-        children: [
-          { id: 'n-slist', name: '单链表.md', path: '/数据结构/链表/单链表.md', type: 'file' },
-          { id: 'n-dlist', name: '双向链表.md', path: '/数据结构/链表/双向链表.md', type: 'file' },
-        ],
-      },
-    ],
-  },
-  {
-    id: 'f-os',
-    name: '操作系统',
-    path: '/操作系统',
-    type: 'folder',
+function normalizePublicPath(path: string): string {
+  const normalized = path.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '')
+  return normalized ? `/${normalized}` : '/'
+}
+
+function relativePath(path: string): string {
+  return normalizePublicPath(path).replace(/^\//, '')
+}
+
+function toFileNode(entry: ApiWorkspaceEntry): FileNode {
+  const path = normalizePublicPath(entry.path)
+  const node: FileNode = {
+    id: entry.entry_id,
+    note_id: entry.note_id ?? undefined,
+    name: entry.name,
+    path,
+    type: entry.type,
     is_open: false,
-    children: [
-      { id: 'n-deadlock', name: '死锁.md', path: '/操作系统/死锁.md', type: 'file' },
-      { id: 'n-sched', name: '进程调度.md', path: '/操作系统/进程调度.md', type: 'file' },
-    ],
-  },
-  {
-    id: 'f-net',
-    name: '计算机网络',
-    path: '/计算机网络',
-    type: 'folder',
-    is_open: false,
-    children: [
-      { id: 'n-tcp', name: 'TCP_IP.md', path: '/计算机网络/TCP_IP.md', type: 'file' },
-      { id: 'n-http', name: 'HTTP协议.md', path: '/计算机网络/HTTP协议.md', type: 'file' },
-    ],
-  },
-  { id: 'n-welcome', name: '欢迎使用 NotesAgent.md', path: '/欢迎使用 NotesAgent.md', type: 'file' },
-]
-
-const mockFileContents = new Map<string, string>()
-
-function rememberContent(path: string, content: string): Promise<string> {
-  mockFileContents.set(path, content)
-  return Promise.resolve(content)
-}
-
-export function getRecentVaults(): Promise<VaultInfo[]> {
-  return Promise.resolve(MOCK_VAULTS)
-}
-
-export function openVault(path: string): Promise<VaultInfo> {
-  const name = path.split(/[/\\]/).filter(Boolean).pop() || 'Vault'
-  return Promise.resolve({ path, name })
-}
-
-export function createVault(path: string, name: string): Promise<VaultInfo> {
-  return Promise.resolve({ path, name })
-}
-
-export function getFileTree(): Promise<FileNode[]> {
-  return Promise.resolve(JSON.parse(JSON.stringify(MOCK_FILE_TREE)))
-}
-
-export function readFileContent(filePath: string): Promise<string> {
-  const saved = mockFileContents.get(filePath)
-  if (saved !== undefined) return Promise.resolve(saved)
-  const name = filePath.split('/').pop() || 'Untitled'
-  if (name === '欢迎使用 NotesAgent.md') {
-    return rememberContent(filePath, `# 欢迎使用 NotesAgent
-
-这是一款本地优先的 AI 笔记软件，支持 Markdown 编辑、智能检索、RAG 问答和 Agent 助手。
-
-## 核心特性
-
-- **本地优先**：所有笔记以 Markdown 格式保存在本地，数据完全由你掌控
-- **混合检索**：FTS5 全文检索 + 向量语义检索，精准定位知识
-- **AI 问答**：基于 RAG 技术，让 AI 基于你的笔记回答问题
-- **Agent 助手**：通过工具调用，AI 可以帮你管理笔记、创建任务
-- **Skill 系统**：将常用 AI 工作流保存为可复用的 Skill
-- **插件扩展**：通过 Plugin 扩展应用能力
-
-## 快速开始
-
-1. 在左侧文件树中创建你的第一篇笔记
-2. 使用 \`Ctrl+P\` 打开命令面板
-3. 使用搜索功能快速找到你的笔记
-4. 打开 AI 对话，开始与你的知识对话
-
-> 提示：你可以在设置中配置你的模型提供商，开始使用 AI 功能。
-
-## 编辑器模式
-
-- **所见即所得模式**：使用 Milkdown 提供流畅的 Markdown 编辑体验
-- **源码模式**：使用 CodeMirror 6 编辑原始 Markdown 源码
-
-点击右上角按钮可以切换编辑模式。
-
-## 代码示例
-
-\`\`\`python
-def quick_sort(arr):
-    if len(arr) <= 1:
-        return arr
-    pivot = arr[len(arr) // 2]
-    left = [x for x in arr if x < pivot]
-    middle = [x for x in arr if x == pivot]
-    right = [x for x in arr if x > pivot]
-    return quick_sort(left) + middle + quick_sort(right)
-\`\`\`
-
-## 任务列表
-
-- [x] 完成项目初始化
-- [x] 设计技术架构
-- [ ] 实现前端界面
-- [ ] 接入后端 AI Core
-- [ ] 性能优化与测试
-
----
-
-祝你写作愉快！
-`)
+    children: entry.type === 'folder' ? entry.children.map(toFileNode) : undefined,
   }
-  if (name === '红黑树.md') {
-    return rememberContent(filePath, `# 红黑树
+  typeByPath.set(path, entry.type)
+  if (entry.note_id) noteIdByPath.set(path, entry.note_id)
+  return node
+}
 
-红黑树（Red-Black Tree）是一种自平衡二叉搜索树，每个节点带有颜色属性（红色或黑色）。
+function cacheEntries(entries: ApiWorkspaceEntry[]): FileNode[] {
+  noteIdByPath.clear()
+  typeByPath.clear()
+  cachedTree = entries.map(toFileNode)
+  return cachedTree
+}
 
-## 性质
-
-1. 每个节点是红色或黑色
-2. 根节点是黑色
-3. 所有叶子节点（NIL）是黑色
-4. 如果一个节点是红色，则它的两个子节点都是黑色
-5. 从任一节点到其每个叶子的所有简单路径都包含相同数目的黑色节点
-
-这些性质确保了红黑树的关键特性：**从根到叶子的最长可能路径不会超过最短可能路径的两倍长**。
-
-## 插入操作
-
-插入后可能破坏红黑性质，需要通过变色和旋转来修复。
-
-### 情况1：叔叔节点是红色
-
-将父节点和叔叔节点设为黑色，将祖父节点设为红色，当前节点上移到祖父节点，继续向上调整。
-
-### 情况2：叔叔节点是黑色，且当前节点是右孩子
-
-以父节点为支点左旋，将当前节点转换为左孩子，进入情况3。
-
-### 情况3：叔叔节点是黑色，且当前节点是左孩子
-
-以祖父节点为支点右旋，将父节点设为黑色，祖父节点设为红色。
-
-## 与 AVL 树对比
-
-| 特性 | AVL 树 | 红黑树 |
-|------|--------|--------|
-| 平衡严格度 | 高度差 ≤ 1 | 黑色高度相同 |
-| 查找速度 | 更快 | 略慢 |
-| 插入删除 | 旋转更多 | 旋转更少 |
-| 适用场景 | 读多写少 | 读写均衡 |
-
-## 应用场景
-
-- C++ STL 的 map/set
-- Java 的 TreeMap
-- Linux 内核的完全公平调度器
-`)
+function nodeFromNote(note: ApiNote): FileNode {
+  const path = normalizePublicPath(note.file_path)
+  noteIdByPath.set(path, note.note_id)
+  typeByPath.set(path, 'file')
+  return {
+    id: note.note_id,
+    note_id: note.note_id,
+    name: path.split('/').at(-1) || note.title,
+    path,
+    type: 'file',
   }
-  return rememberContent(filePath, `# ${name.replace('.md', '')}
-
-这是一篇示例笔记。
-
-## 第一部分
-
-这里是笔记的内容。
-
-## 第二部分
-
-更多内容...
-
-> 引用内容示例
-
-\`\`\`javascript
-console.log('Hello, NotesAgent!');
-\`\`\`
-`)
 }
 
-export function saveFileContent(filePath: string, content: string): Promise<void> {
-  console.debug(`[workspaceService] Save ${filePath}, ${content.length} chars`)
-  mockFileContents.set(filePath, content)
-  return Promise.resolve()
-}
-
-export function createFile(folderPath: string, name: string, content = ''): Promise<FileNode> {
-  const path = `${folderPath === '/' ? '' : folderPath}/${name}`
-  const id = `n-${Date.now()}`
-  mockFileContents.set(path, content)
-  return Promise.resolve({ id, name, path, type: 'file' })
-}
-
-export function createFolder(parentPath: string, name: string): Promise<FileNode> {
-  const path = `${parentPath === '/' ? '' : parentPath}/${name}`
-  const id = `f-${Date.now()}`
-  return Promise.resolve({ id, name, path, type: 'folder', is_open: true, children: [] })
-}
-
-export function renameFile(oldPath: string, newName: string): Promise<void> {
-  const separator = oldPath.lastIndexOf('/')
-  const newPath = `${oldPath.slice(0, separator + 1)}${newName}`
-  for (const [path, content] of [...mockFileContents]) {
-    if (path === oldPath || path.startsWith(`${oldPath}/`)) {
-      mockFileContents.delete(path)
-      mockFileContents.set(`${newPath}${path.slice(oldPath.length)}`, content)
-    }
+async function requireNoteId(filePath: string): Promise<string> {
+  const path = normalizePublicPath(filePath)
+  let noteId = noteIdByPath.get(path)
+  if (!noteId) {
+    await refreshTree()
+    noteId = noteIdByPath.get(path)
   }
-  return Promise.resolve()
+  if (!noteId) throw new Error(`笔记尚未建立后端索引：${path}`)
+  return noteId
 }
 
-export function deleteFile(path: string): Promise<void> {
-  for (const filePath of [...mockFileContents.keys()]) {
-    if (filePath === path || filePath.startsWith(`${path}/`)) mockFileContents.delete(filePath)
+export async function getWorkspaceInfo(): Promise<ApiWorkspaceInfo> {
+  return apiClient.get('/api/workspace')
+}
+
+export async function getRecentVaults(): Promise<VaultInfo[]> {
+  const workspace = await getWorkspaceInfo()
+  return [{ path: workspace.path, name: workspace.name }]
+}
+
+export async function openVault(path: string): Promise<VaultInfo> {
+  const snapshot = await apiClient.post<ApiWorkspaceSnapshot>('/api/workspace/open', { path })
+  cacheEntries(snapshot.items)
+  return { path: snapshot.workspace.path, name: snapshot.workspace.name }
+}
+
+export async function createVault(path: string, name: string): Promise<VaultInfo> {
+  // Web 模式不能创建任意本地目录；路径匹配时等价于初始化后端配置的 Vault。
+  void name
+  return openVault(path)
+}
+
+export async function refreshTree(): Promise<FileNode[]> {
+  const entries = await apiClient.get<ApiWorkspaceEntry[]>('/api/workspace/tree')
+  return cacheEntries(entries)
+}
+
+export async function getFileTree(): Promise<FileNode[]> {
+  return cachedTree ?? refreshTree()
+}
+
+export async function readFileContent(filePath: string): Promise<string> {
+  const note = await noteService.getNote(await requireNoteId(filePath))
+  return note.markdown
+}
+
+export async function saveFileContent(filePath: string, content: string): Promise<void> {
+  await noteService.updateNote(await requireNoteId(filePath), { markdown: content })
+}
+
+export async function createFile(
+  folderPath: string,
+  name: string,
+  content = '',
+): Promise<FileNode> {
+  const title = name.replace(/\.md$/i, '')
+  const note = await noteService.createNote({
+    title,
+    folder: relativePath(folderPath),
+    markdown: content,
+  })
+  return nodeFromNote(note)
+}
+
+export async function createFolder(parentPath: string, name: string): Promise<FileNode> {
+  const entry = await apiClient.post<ApiWorkspaceEntry>('/api/workspace/folders', {
+    parent: relativePath(parentPath),
+    name,
+  })
+  return toFileNode(entry)
+}
+
+export async function renameFile(oldPath: string, newName: string): Promise<void> {
+  const path = normalizePublicPath(oldPath)
+  if (typeByPath.get(path) === 'folder') {
+    await apiClient.post('/api/workspace/folders/rename', {
+      path: relativePath(path),
+      new_name: newName,
+    })
+  } else {
+    await noteService.renameNote(await requireNoteId(path), newName)
   }
-  return Promise.resolve()
+  await refreshTree()
 }
 
-export function moveFile(sourcePath: string, targetPath: string): Promise<void> {
-  // Mock 文件树由 Store 同步更新；真实实现必须在 Host 侧执行原子移动。
-  void sourcePath
-  void targetPath
-  return Promise.resolve()
+export async function deleteFile(pathValue: string): Promise<void> {
+  const path = normalizePublicPath(pathValue)
+  if (typeByPath.get(path) === 'folder') {
+    await apiClient.post<OperationResponse>('/api/workspace/folders/delete', {
+      path: relativePath(path),
+    })
+  } else {
+    await noteService.deleteNote(await requireNoteId(path))
+  }
+  await refreshTree()
+}
+
+export async function moveFile(sourcePath: string, targetPath: string): Promise<void> {
+  const source = normalizePublicPath(sourcePath)
+  if (typeByPath.get(source) !== 'file') {
+    throw new Error('当前阶段只支持移动笔记文件。')
+  }
+  await noteService.moveNote(await requireNoteId(source), relativePath(targetPath))
+  await refreshTree()
 }