@lemoncat7/dsh-knowledge 1.2.0 → 2.1.0

package/web/app.js

@@ -1,5 +1,7 @@
 const API_BASE = document.querySelector('meta[name="dsh-knowledge-api"]')?.content || '/knowledge-api/v1'
 const AUTH_MODE = document.querySelector('meta[name="dsh-knowledge-auth-mode"]')?.content || 'bearer'
+const WEB_PATH = document.querySelector('meta[name="dsh-knowledge-web"]')?.content || '/knowledge'
+const ASSET_VERSION = document.querySelector('meta[name="dsh-knowledge-asset-version"]')?.content || ''
 const HOST_THEME_MESSAGE = '@lemoncat7/dsh-knowledge/host-theme'
 const HOST_THEME_READY_MESSAGE = '@lemoncat7/dsh-knowledge/host-theme-ready'
 const HOST_THEME_PROTOCOL_VERSION = 1
@@ -20,6 +22,7 @@ const WRITE_MODE_LABELS = { none: '仅召回', audit: '审核写入', direct: '
 const EVIDENCE_LABELS = { explicit: '用户明确', verified: '结果已验证', inferred: '模型推断' }
 const DOCUMENT_STATE_LABELS = { open: '进行中', resolved: '已解决', complete: '已收集完成' }
 const DOCUMENT_LAYOUT_KEY = 'dsh-knowledge.document-layout'
+const NOTE_MAX_FILE_SIZE = 64 * 1024 * 1024
 const pageParams = new URLSearchParams(location.search)
 const mountContext = {
   sessionId: pageParams.get('sessionId')?.trim() || '',
@@ -32,7 +35,9 @@ const savedDocumentLayout = readDocumentLayout()
 function createDocumentViewState(overrides = {}) {
   return {
     knowledgeBaseId: '', documentId: '', query: '', mode: 'preview', treeOpen: false,
-    expandedBases: new Set(), editor: null, ...overrides,
+    expandedBases: new Set(), documentPages: new Map(),
+    searchResults: [], searchNextCursor: '', searchTotal: 0, searchLoading: false, searchError: '', searchRequest: 0,
+    editor: null, editorLoading: false, loadingDocumentId: '', ...overrides,
   }
 }
 
@@ -75,9 +80,17 @@ const state = {
   modelCatalog: null,
   settingsSaving: false,
   tokens: [],
+  notes: {
+    children: new Map(), loadedFolders: new Set(), expandedFolders: new Set(),
+    selectedId: '', selectedNode: null, currentFolderId: null, breadcrumbs: [],
+    content: '', draft: '', dirty: false, assetUrl: '', query: '', searchResults: [],
+    transfer: null, loadingNodeId: '',
+  },
   service: { publicApiEnabled: false, publicApiPrefix: '/knowledge-api/v1', remote: false },
   scrollPositions: new Map(),
   loading: false,
+  loadingPhase: '',
+  loadingProgress: 0,
   error: '',
 }
 
@@ -86,6 +99,16 @@ let navigationController = null
 let navigationRequest = 0
 let navigationSave = Promise.resolve(true)
 let libraryDetailRequest = 0
+let documentSearchTimer = 0
+let noteSearchTimer = 0
+let markdownEditorHandle = null
+let noteEditorLoader = null
+let markdownEditorMountRequest = 0
+let plainTextEditorHandle = null
+let plainTextEditorMountRequest = 0
+let noteTransferFrame = 0
+let noteTransferSequence = 0
+let noteSelectionRequest = 0
 
 function installHostThemeBridge() {
   if (window.parent === window) return Promise.resolve()
@@ -219,6 +242,10 @@ function element(tag, attributes = {}, ...children) {
   return node
 }
 
+function refreshWorkspaceEffects(root = document) {
+  window.DshKnowledgeEffects?.refresh(root)
+}
+
 function actionButton(label, onClick, variant = '', attributes = {}) {
   return element('button', { type: 'button', class: `button ${variant}`.trim(), onClick, ...attributes }, label)
 }
@@ -277,11 +304,83 @@ async function api(path, options = {}) {
   return payload
 }
 
+async function binaryRequest(path, options = {}) {
+  const headers = { accept: options.accept || 'application/json' }
+  if (AUTH_MODE === 'same-origin') headers['x-dsh-knowledge-client'] = 'management-web'
+  if (state.token) headers.authorization = `Bearer ${state.token}`
+  if (options.contentType) headers['content-type'] = options.contentType
+  const response = await fetch(`${API_BASE}/${path.replace(/^\/+/, '')}`, {
+    method: options.method || 'GET',
+    headers,
+    body: options.body,
+    signal: options.signal,
+  })
+  if (options.responseType === 'blob') {
+    if (!response.ok) throw await responseError(response)
+    return response.blob()
+  }
+  const text = await response.text()
+  let payload
+  if (text) {
+    try { payload = JSON.parse(text) } catch { throw new Error('服务返回了无法识别的数据') }
+  }
+  if (!response.ok) {
+    const error = new Error(payload?.error || `请求失败（HTTP ${response.status}）`)
+    error.status = response.status
+    throw error
+  }
+  return payload
+}
+
+function binaryUploadRequest(path, body, options = {}) {
+  return new Promise((resolve, reject) => {
+    const request = new XMLHttpRequest()
+    request.open(options.method || 'POST', `${API_BASE}/${path.replace(/^\/+/, '')}`)
+    request.responseType = 'text'
+    request.setRequestHeader('accept', 'application/json')
+    if (AUTH_MODE === 'same-origin') request.setRequestHeader('x-dsh-knowledge-client', 'management-web')
+    if (state.token) request.setRequestHeader('authorization', `Bearer ${state.token}`)
+    if (options.contentType) request.setRequestHeader('content-type', options.contentType)
+    request.upload.addEventListener('progress', event => {
+      if (event.lengthComputable) options.onProgress?.(event.loaded, event.total)
+    })
+    request.addEventListener('load', () => {
+      let payload
+      if (request.responseText) {
+        try { payload = JSON.parse(request.responseText) }
+        catch { return reject(new Error('服务返回了无法识别的数据')) }
+      }
+      if (request.status < 200 || request.status >= 300) {
+        const error = new Error(payload?.error || `请求失败（HTTP ${request.status}）`)
+        error.status = request.status
+        reject(error)
+        return
+      }
+      resolve(payload)
+    })
+    request.addEventListener('error', () => reject(new Error('上传连接中断，请检查网络后重试')))
+    request.addEventListener('abort', () => reject(new DOMException('上传已取消', 'AbortError')))
+    request.send(body)
+  })
+}
+
+async function responseError(response) {
+  let message = `请求失败（HTTP ${response.status}）`
+  try {
+    const payload = await response.json()
+    if (payload?.error) message = payload.error
+  } catch {}
+  return Object.assign(new Error(message), { status: response.status })
+}
+
 async function boot() {
   if (AUTH_MODE === 'same-origin') {
     state.token = ''
-    try { state.service = await api('service') } catch {}
-    await navigate('entries')
+    await Promise.all([
+      api('service').then(service => { state.service = service }).catch(() => {}),
+      navigate('entries'),
+    ])
+    renderShell()
     return
   }
   if (!state.token) {
@@ -339,18 +438,22 @@ function renderLogin(message = '') {
     element('p', {}, '管理对话中沉淀的长期知识与 AI 提取候选。'),
     form,
   )))
+  refreshWorkspaceEffects(app)
 }
 
 function signOut() {
+  releaseNoteEditors()
+  releaseNoteAsset()
   sessionStorage.removeItem(TOKEN_KEY)
   Object.assign(state, { token: '', stats: null, overview: null, knowledgeBases: [], mounts: [], resolvedMounts: [], entries: [], documents: [], candidates: [], candidateTargets: new Map(), settings: { writebackPolicy: 'conservative', updatedAt: '' }, tokens: [] })
+  state.notes = { children: new Map(), loadedFolders: new Set(), expandedFolders: new Set(), selectedId: '', selectedNode: null, currentFolderId: null, breadcrumbs: [], content: '', draft: '', dirty: false, assetUrl: '', query: '', searchResults: [], transfer: null, loadingNodeId: '' }
   if (AUTH_MODE === 'same-origin') void boot()
   else renderLogin()
 }
 
 async function navigate(view) {
   const request = ++navigationRequest
-  navigationSave = navigationSave.then(() => saveBeforeLeavingDocument(), () => saveBeforeLeavingDocument())
+  navigationSave = navigationSave.then(() => saveBeforeNavigation(), () => saveBeforeNavigation())
   if (!await navigationSave || request !== navigationRequest) return
   navigationController?.abort()
   const controller = new AbortController()
@@ -362,13 +465,16 @@ async function navigate(view) {
   state.view = view
   state.menuOpen = false
   state.loading = true
+  state.loadingPhase = loadingPhaseForView(view)
+  state.loadingProgress = .12
   state.error = ''
   renderShell()
   try {
     if (view === 'overview') await loadOverview(controller.signal)
     if (view === 'bases') await loadKnowledgeBasesPage(controller.signal)
-    if (view === 'entries') await loadDocuments(controller.signal)
+    if (view === 'entries') await loadDocuments(controller.signal, (label, progress) => updateLoadingPhase(request, label, progress))
     if (view === 'candidates') await loadCandidates(controller.signal)
+    if (view === 'notes') await loadNotes(controller.signal, (label, progress) => updateLoadingPhase(request, label, progress))
     if (view === 'tokens') await loadTokens(controller.signal)
   } catch (error) {
     if (controller.signal.aborted) return
@@ -377,10 +483,31 @@ async function navigate(view) {
   } finally {
     if (navigationController !== controller) return
     state.loading = false
+    state.loadingPhase = ''
+    state.loadingProgress = 1
     renderShell()
   }
 }
 
+function loadingPhaseForView(view) {
+  return ({
+    overview: '正在汇总知识活动', bases: '正在读取知识库配置', entries: '正在读取知识目录',
+    notes: '正在读取笔记目录', candidates: '正在准备审核队列', tokens: '正在读取访问权限',
+  })[view] || '正在准备工作区'
+}
+
+function updateLoadingPhase(request, label, progress) {
+  if (request !== navigationRequest || !state.loading) return
+  state.loadingPhase = label
+  state.loadingProgress = Math.max(0, Math.min(1, progress))
+  renderShell()
+}
+
+async function saveBeforeNavigation() {
+  if (state.view === 'notes' && state.notes.dirty) return saveNoteDocument()
+  return saveBeforeLeavingDocument()
+}
+
 async function saveBeforeLeavingDocument() {
   const workspace = activeDocumentWorkspace()
   const editor = workspace?.view.editor
@@ -457,19 +584,26 @@ async function loadEntries(cursor = '') {
   if (!state.stats) await refreshStats()
 }
 
-async function loadDocuments(signal) {
+async function loadDocuments(signal, onPhase = () => {}) {
+  onPhase('正在读取可用知识库', .24)
   const options = { signal }
-  const requests = [api('knowledge-bases', options), api('documents', options)]
+  const requests = [api('knowledge-bases', options)]
   if (state.mountContext.sessionId) {
     const params = new URLSearchParams({ sessionId: state.mountContext.sessionId })
     if (state.mountContext.projectId) params.set('projectId', state.mountContext.projectId)
     requests.push(api(`mounts/resolve?${params}`, options))
   }
-  const [bases, documents, resolved = []] = await Promise.all(requests)
+  const [results, stats] = await Promise.all([
+    Promise.all(requests),
+    state.stats ? Promise.resolve(state.stats) : api('stats', options),
+  ])
+  const [bases, resolved = []] = results
   state.knowledgeBases = bases
   state.resolvedMounts = resolved
+  state.stats = stats
+  onPhase('正在建立文档索引', .56)
   const visibleBaseIds = new Set(documentKnowledgeBases(bases).map(base => base.id))
-  state.documents = documents.filter(document => visibleBaseIds.has(document.knowledgeBaseId))
+  state.documents = state.documents.filter(document => visibleBaseIds.has(document.knowledgeBaseId))
   const workspace = sessionDocumentWorkspace()
   const view = workspace.view
   const availableBaseIds = visibleBaseIds
@@ -478,10 +612,30 @@ async function loadDocuments(signal) {
       ? state.entryFilters.knowledgeBaseId
       : documentKnowledgeBases(bases)[0]?.id || ''
   }
+  if (view.knowledgeBaseId) {
+    view.expandedBases.add(view.knowledgeBaseId)
+    await loadDocumentPage(workspace, view.knowledgeBaseId, { signal })
+  }
   selectDefaultDocument(workspace)
-  if (view.documentId) await loadDocumentEditor(workspace, view.documentId, signal)
+  if (view.documentId) {
+    onPhase('正在打开最近文档', .82)
+    await loadDocumentEditor(workspace, view.documentId, signal)
+  }
   else view.editor = null
-  if (!state.stats) await refreshStats(signal)
+}
+
+async function loadNotes(signal, onPhase = () => {}) {
+  onPhase('正在读取顶层目录', .36)
+  state.notes.children.set('root', await api('notes?limit=500', { signal }))
+  state.notes.loadedFolders.add('root')
+  if (state.notes.selectedId) {
+    onPhase('正在恢复上次打开的笔记', .74)
+    const selected = state.notes.selectedNode?.id === state.notes.selectedId
+      ? state.notes.selectedNode
+      : await api(`notes/${encodeURIComponent(state.notes.selectedId)}`, { signal }).catch(() => null)
+    if (!selected) clearNoteSelection()
+    else state.notes.selectedNode = selected
+  }
 }
 
 function documentKnowledgeBases(bases = state.knowledgeBases) {
@@ -514,6 +668,139 @@ function setDocumentWorkspaceDocuments(workspace, documents) {
   else state.documents = documents
 }
 
+function documentPageState(workspace, knowledgeBaseId) {
+  const pages = workspace.view.documentPages
+  if (!pages.has(knowledgeBaseId)) {
+    pages.set(knowledgeBaseId, { loaded: false, loading: false, nextCursor: '', total: 0, error: '' })
+  }
+  return pages.get(knowledgeBaseId)
+}
+
+function mergeDocumentSummaries(workspace, items, knowledgeBaseId, reset) {
+  const current = documentWorkspaceDocuments(workspace)
+  const retained = reset ? current.filter(document => document.knowledgeBaseId !== knowledgeBaseId) : current
+  const merged = new Map(retained.map(document => [document.id, document]))
+  for (const item of items) merged.set(item.id, item)
+  setDocumentWorkspaceDocuments(workspace, [...merged.values()])
+}
+
+async function loadDocumentPage(workspace, knowledgeBaseId, options = {}) {
+  if (!knowledgeBaseId) return
+  const page = documentPageState(workspace, knowledgeBaseId)
+  if (page.loading || (!options.reset && !options.append && page.loaded)) return
+  if (options.append && !page.nextCursor) return
+  page.loading = true
+  page.error = ''
+  const cursor = options.append ? page.nextCursor : ''
+  try {
+    const params = new URLSearchParams({ knowledgeBaseId, limit: '60' })
+    if (cursor) params.set('cursor', cursor)
+    const result = await api(`document-index?${params}`, { signal: options.signal })
+    mergeDocumentSummaries(workspace, result.items, knowledgeBaseId, !options.append)
+    page.loaded = true
+    page.nextCursor = result.nextCursor || ''
+    page.total = result.total
+  } catch (error) {
+    if (error.name === 'AbortError') throw error
+    page.error = friendlyError(error)
+    if (options.throwOnError) throw error
+  } finally {
+    page.loading = false
+  }
+}
+
+async function toggleDocumentBase(workspace, baseId) {
+  const view = workspace.view
+  view.knowledgeBaseId = baseId
+  if (view.expandedBases.has(baseId)) {
+    view.expandedBases.delete(baseId)
+    renderShell()
+    return
+  }
+  view.expandedBases.add(baseId)
+  const page = documentPageState(workspace, baseId)
+  if (!page.loaded) page.loading = true
+  renderShell()
+  if (!page.loaded) {
+    page.loading = false
+    await loadDocumentPage(workspace, baseId)
+    renderShell()
+  }
+}
+
+function resetDocumentSearch(view) {
+  view.searchRequest += 1
+  view.searchResults = []
+  view.searchNextCursor = ''
+  view.searchTotal = 0
+  view.searchLoading = false
+  view.searchError = ''
+}
+
+function scheduleDocumentSearch(workspace) {
+  window.clearTimeout(documentSearchTimer)
+  const view = workspace.view
+  if (!view.query.trim()) {
+    resetDocumentSearch(view)
+    renderShell()
+    return
+  }
+  view.searchLoading = true
+  view.searchError = ''
+  renderShell()
+  documentSearchTimer = window.setTimeout(() => { void loadDocumentSearch(workspace, true) }, 220)
+}
+
+function renderDocumentSearchState(workspace) {
+  renderShell()
+  window.requestAnimationFrame(() => {
+    const input = document.querySelector(`.note-tree-search[data-document-scope="${workspace.kind}"]`)
+    input?.focus()
+    input?.setSelectionRange(input.value.length, input.value.length)
+  })
+}
+
+async function loadDocumentSearch(workspace, reset = false) {
+  const view = workspace.view
+  const query = view.query.trim()
+  if (!query) return resetDocumentSearch(view)
+  const request = ++view.searchRequest
+  view.searchLoading = true
+  view.searchError = ''
+  const params = new URLSearchParams({ q: query, limit: '80' })
+  const bases = documentWorkspaceBases(workspace)
+  if (bases.length === 0) {
+    resetDocumentSearch(view)
+    return renderShell()
+  }
+  if (workspace.kind === 'library') {
+    params.append('knowledgeBaseId', state.libraryDetail.knowledgeBaseId)
+  } else if (state.mountContext.sessionId) {
+    params.set('sessionId', state.mountContext.sessionId)
+    if (state.mountContext.projectId) params.set('projectId', state.mountContext.projectId)
+  } else {
+    params.set('active', '1')
+  }
+  if (!reset && view.searchNextCursor) params.set('cursor', view.searchNextCursor)
+  try {
+    const result = await api(`document-index?${params}`)
+    if (request !== view.searchRequest || query !== view.query.trim()) return
+    const merged = new Map((reset ? [] : view.searchResults).map(document => [document.id, document]))
+    for (const item of result.items) merged.set(item.id, item)
+    view.searchResults = [...merged.values()]
+    view.searchNextCursor = result.nextCursor || ''
+    view.searchTotal = result.total
+  } catch (error) {
+    if (request !== view.searchRequest) return
+    view.searchError = friendlyError(error)
+  } finally {
+    if (request === view.searchRequest) {
+      view.searchLoading = false
+      renderDocumentSearchState(workspace)
+    }
+  }
+}
+
 function documentWorkspaceBases(workspace) {
   if (workspace.kind === 'library') {
     const base = state.knowledgeBases.find(item => item.id === state.libraryDetail.knowledgeBaseId)
@@ -527,21 +814,23 @@ function documentWorkspaceReadOnly(workspace) {
 }
 
 async function reloadDocumentWorkspace(workspace) {
-  const libraryBaseId = workspace.kind === 'library' ? state.libraryDetail.knowledgeBaseId : ''
-  const documents = workspace.kind === 'library'
-    ? await api(`documents?knowledgeBaseId=${encodeURIComponent(libraryBaseId)}`)
-    : await api('documents')
-  if (workspace.kind === 'library') {
-    if (state.libraryDetail.knowledgeBaseId !== libraryBaseId) return false
-    setDocumentWorkspaceDocuments(workspace, documents)
-  }
-  else {
-    const visibleBaseIds = new Set(documentKnowledgeBases().map(base => base.id))
-    setDocumentWorkspaceDocuments(workspace, documents.filter(document => visibleBaseIds.has(document.knowledgeBaseId)))
+  const baseId = workspace.kind === 'library' ? state.libraryDetail.knowledgeBaseId : workspace.view.knowledgeBaseId
+  if (!baseId) return true
+  await loadDocumentPage(workspace, baseId, { reset: true, throwOnError: true })
+  if (workspace.kind === 'library' && state.libraryDetail.knowledgeBaseId !== baseId) return false
+  const selectedId = workspace.view.documentId
+  if (selectedId && !documentWorkspaceDocuments(workspace).some(document => document.id === selectedId)) {
+    const document = await api(`documents/${encodeURIComponent(selectedId)}`)
+    mergeDocumentSummaries(workspace, [documentSummary(document)], baseId, false)
   }
   return true
 }
 
+function documentSummary(document) {
+  const { content: _content, ...summary } = document
+  return summary
+}
+
 function selectDefaultDocument(workspace) {
   const view = workspace.view
   const documents = documentWorkspaceDocuments(workspace).filter(document => document.knowledgeBaseId === view.knowledgeBaseId)
@@ -554,11 +843,15 @@ function selectDefaultDocument(workspace) {
 async function loadDocumentEditor(workspace, id, signal) {
   const revision = (workspace.view.loadRevision || 0) + 1
   workspace.view.loadRevision = revision
-  const entry = await api(`entries/${encodeURIComponent(id)}`, { signal })
+  const [entry, noteReferences] = await Promise.all([
+    api(`entries/${encodeURIComponent(id)}`, { signal }),
+    api(`entries/${encodeURIComponent(id)}/note-references`, { signal }),
+  ])
   if (workspace.view.loadRevision !== revision || workspace.view.documentId !== id) return false
   workspace.view.mode = 'preview'
   workspace.view.editor = {
     ...entry,
+    noteReferences,
     tagsText: entry.tags.join(', '),
     dirty: false,
     isNew: false,
@@ -578,7 +871,7 @@ function createBlankDocument(workspace, baseId) {
   view.expandedBases.add(base.id)
   view.editor = {
     id: '', knowledgeBaseId: base.id, title: '', body: '', type: 'fact', tags: [], tagsText: '',
-    scope: { kind: 'global' }, confidence: .8, dirty: true, isNew: true, saveState: '新文档',
+    scope: { kind: 'global' }, confidence: .8, noteReferences: [], dirty: true, isNew: true, saveState: '新文档',
   }
   renderShell()
   document.querySelector('.note-title-input')?.focus()
@@ -597,7 +890,21 @@ async function selectDocument(workspace, id) {
   if (editor?.dirty && !emptyDraft && !await saveDocumentEditor(workspace)) return
   workspace.view.documentId = id
   workspace.view.treeOpen = false
-  if (await loadDocumentEditor(workspace, id)) renderShell()
+  workspace.view.editor = null
+  workspace.view.editorLoading = true
+  workspace.view.loadingDocumentId = id
+  renderShell()
+  try {
+    await loadDocumentEditor(workspace, id)
+  } catch (error) {
+    if (workspace.view.documentId === id) showToast(friendlyError(error), 'error')
+  } finally {
+    if (workspace.view.loadingDocumentId === id) {
+      workspace.view.editorLoading = false
+      workspace.view.loadingDocumentId = ''
+      renderShell()
+    }
+  }
 }
 
 function editorDraft(editor) {
@@ -680,15 +987,18 @@ async function loadTokens(signal) {
 }
 
 function renderShell() {
+  releaseNoteEditors()
   captureScrollPosition()
   const titles = {
     overview: ['概览', '知识库运行状态与最近活动'],
     bases: ['知识库与挂载', '管理知识目录，并限定项目与会话的召回和写入范围'],
     entries: ['知识文档', '在知识目录中阅读、整理和维护 Markdown 文档'],
+    notes: ['笔记文档', '像本地目录一样整理笔记和资料，并按需关联到知识文档'],
     candidates: ['待审核', '确认 AI 提取结果后再写入知识文档'],
     tokens: ['访问管理', '管理其他客户端连接中央知识库的权限'],
   }
   const [title, subtitle] = titles[state.view]
+  const viewIndexes = { overview: '00', notes: '01', entries: '02', candidates: '03', bases: '04', tokens: '05' }
   const shell = element('div', {
     class: 'app-shell', 'data-menu-open': String(state.menuOpen),
     'data-view': state.view, 'data-loading': String(state.loading),
@@ -713,16 +1023,25 @@ function renderShell() {
             workspace.view.treeOpen = !workspace.view.treeOpen
             renderShell()
           }, '知识目录') : null,
-          element('div', {}, element('h1', {}, title), element('p', {}, subtitle)),
+          element('div', { class: 'topbar-heading' },
+            element('span', { class: 'topbar-kicker' }, `KNOWLEDGE / ${viewIndexes[state.view] || '00'}`),
+            element('h1', {}, title),
+            element('p', {}, subtitle)),
         ),
+        state.loading ? element('div', {
+          class: 'route-progress', role: 'progressbar', 'aria-label': state.loadingPhase || '正在加载',
+          'aria-valuemin': '0', 'aria-valuemax': '100', 'aria-valuenow': String(Math.round(state.loadingProgress * 100)),
+        }, element('span', { style: `--route-progress: ${state.loadingProgress}` })) : null,
       ),
-      element('div', { class: 'page' }, renderCurrentView()),
+      element('div', { class: 'page' }, element('div', { class: 'view-stage', 'data-view-stage': state.view }, renderCurrentView())),
     ),
   )
   if (state.menuOpen) shell.addEventListener('click', (event) => {
     if (event.target === shell) { state.menuOpen = false; renderShell() }
   })
   app.replaceChildren(shell)
+  applySidebarVisibility(shell, state.documentView.sidebarHidden)
+  refreshWorkspaceEffects(shell)
   restoreScrollPosition(currentScrollState())
 }
 
@@ -788,17 +1107,46 @@ function setSidebarWidth(width, shell, handle) {
 function setSidebarHidden(hidden) {
   state.documentView.sidebarHidden = hidden
   saveDocumentLayout()
-  renderShell()
+  const shell = app.querySelector('.app-shell')
+  if (shell) applySidebarVisibility(shell, hidden)
+}
+
+function applySidebarVisibility(shell, hidden) {
+  shell.dataset.sidebarHidden = String(hidden)
+  const sidebar = shell.querySelector(':scope > .sidebar')
+  const resizer = shell.querySelector(':scope > .app-sidebar-resizer')
+  const toggle = shell.querySelector('.pane-toggle-button[data-pane="main"]')
+  sidebar?.toggleAttribute('inert', hidden)
+  resizer?.toggleAttribute('inert', hidden)
+  if (sidebar) {
+    if (hidden) sidebar.setAttribute('aria-hidden', 'true')
+    else sidebar.removeAttribute('aria-hidden')
+  }
+  if (resizer) {
+    resizer.tabIndex = hidden ? -1 : 0
+    if (hidden) resizer.setAttribute('aria-hidden', 'true')
+    else resizer.removeAttribute('aria-hidden')
+  }
+  if (toggle) {
+    const visible = !hidden
+    const action = `${visible ? '隐藏' : '显示'}主导航栏`
+    toggle.setAttribute('aria-pressed', String(visible))
+    toggle.setAttribute('aria-label', action)
+    toggle.title = action
+  }
 }
 
 function renderSidebar() {
   const pending = state.stats?.candidates.pending
   const navGroups = [
-    ['知识工作区', [['entries', '文档'], ['candidates', '待审核'], ['bases', '知识库与挂载']]],
+    ['笔记工作区', [['notes', '笔记文档']]],
+    ['知识工作区', [['entries', '知识文档'], ['candidates', '待审核'], ['bases', '知识库与挂载']]],
     ['连接', [['tokens', '访问管理']].filter(([id]) => id !== 'tokens' || !state.service.remote)],
   ].filter(([, items]) => items.length)
+  let navIndex = 0
   return element('aside', { class: 'sidebar', 'aria-label': '知识库导航' },
     element('div', { class: 'brand' },
+      element('span', { class: 'brand-emblem', 'aria-hidden': 'true' }, element('span', {})),
       element('div', { class: 'brand-copy' }, element('span', {}, 'DSH Knowledge'), element('strong', {}, '知识库')),
     ),
     element('nav', { class: 'nav' }, navGroups.map(([group, items]) => element('div', { class: 'nav-group' },
@@ -806,7 +1154,7 @@ function renderSidebar() {
       items.map(([id, label]) => element('button', {
         type: 'button', class: 'nav-button', 'aria-current': state.view === id ? 'page' : undefined,
         onClick: () => navigate(id),
-      }, element('span', { class: 'nav-label' }, label),
+      }, element('span', { class: 'nav-index', 'aria-hidden': 'true' }, String(++navIndex).padStart(2, '0')), element('span', { class: 'nav-label' }, label),
       id === 'candidates' && pending ? element('span', { class: 'nav-count', 'aria-label': `${pending} 条待审核` }, pending) : null))))),
     element('div', { class: 'sidebar-footer' },
       element('div', { class: 'connection' }, element('span', { class: 'status-dot', 'aria-hidden': 'true' }), state.service.remote ? '中央知识库已连接' : '本地知识库已连接'),
@@ -816,26 +1164,38 @@ function renderSidebar() {
 }
 
 function renderCurrentView() {
-  if (state.loading) return loadingView()
+  if (state.loading) return loadingView(state.view, state.loadingPhase, state.loadingProgress)
   if (state.error) return errorView(state.error, () => navigate(state.view))
   if (state.view === 'overview') return renderOverview()
   if (state.view === 'bases') return renderKnowledgeBases()
   if (state.view === 'entries') return renderEntries()
+  if (state.view === 'notes') return renderNotes()
   if (state.view === 'candidates') return renderCandidates()
   return renderTokens()
 }
 
-function loadingView() {
-  return element('div', { class: 'loading-skeleton', role: 'status', 'aria-label': '正在加载' },
-    element('span', { class: 'visually-hidden' }, '正在加载'),
-    element('div', { class: 'skeleton-line skeleton-title', 'aria-hidden': 'true' }),
-    element('div', { class: 'skeleton-line skeleton-copy', 'aria-hidden': 'true' }),
-    element('div', { class: 'skeleton-grid', 'aria-hidden': 'true' },
-      element('div', { class: 'skeleton-block' }),
-      element('div', { class: 'skeleton-block' }),
-      element('div', { class: 'skeleton-block' }),
-    ),
+function loadingView(view = state.view, phase = '正在加载', progress = 0) {
+  const label = phase || loadingPhaseForView(view)
+  const header = element('div', { class: 'skeleton-heading' },
+    element('div', {}, element('div', { class: 'skeleton-line skeleton-title', 'aria-hidden': 'true' }), element('div', { class: 'skeleton-line skeleton-copy', 'aria-hidden': 'true' })),
+    element('span', { class: 'skeleton-phase' }, label),
   )
+  const content = view === 'entries'
+    ? element('div', { class: 'skeleton-workspace skeleton-workspace-documents', 'aria-hidden': 'true' },
+      element('div', { class: 'skeleton-pane skeleton-pane-tree' }, ...Array.from({ length: 7 }, (_, index) => element('div', { class: `skeleton-line skeleton-tree-row is-${index % 3}` }))),
+      element('div', { class: 'skeleton-pane skeleton-pane-paper' }, element('div', { class: 'skeleton-line skeleton-paper-title' }), ...Array.from({ length: 8 }, (_, index) => element('div', { class: `skeleton-line skeleton-paper-row is-${index % 4}` }))),
+    )
+    : view === 'notes'
+      ? element('div', { class: 'skeleton-workspace skeleton-workspace-notes', 'aria-hidden': 'true' },
+        element('div', { class: 'skeleton-pane skeleton-pane-tree' }, ...Array.from({ length: 8 }, (_, index) => element('div', { class: `skeleton-line skeleton-tree-row is-${index % 3}` }))),
+        element('div', { class: 'skeleton-pane skeleton-pane-list' }, ...Array.from({ length: 6 }, () => element('div', { class: 'skeleton-list-row' }, element('span', { class: 'skeleton-block' }), element('span', { class: 'skeleton-line' })))),
+      )
+      : element('div', { class: 'skeleton-grid', 'aria-hidden': 'true' },
+        element('div', { class: 'skeleton-block' }), element('div', { class: 'skeleton-block' }), element('div', { class: 'skeleton-block' }))
+  return element('div', {
+    class: `loading-skeleton loading-skeleton--${view}`, role: 'status', 'aria-label': label,
+    style: `--loading-progress: ${progress}`,
+  }, element('span', { class: 'visually-hidden' }, label), header, content)
 }
 
 function errorView(message, retry) {
@@ -1061,7 +1421,10 @@ function renderKnowledgeBaseCard(base) {
   const archived = base.status === 'archived'
   const visibleTags = base.defaultTags.slice(0, 4)
   const hiddenTagCount = Math.max(0, base.defaultTags.length - visibleTags.length)
-  return element('article', { class: `base-card${archived ? ' is-archived' : ''}` },
+  return element('article', {
+    class: `base-card${archived ? ' is-archived' : ''}`,
+    'data-knowledge-motion-key': `knowledge-library:${base.id}`,
+  },
     element('div', { class: 'base-card-header' },
       element('div', { class: 'base-card-identity' },
         element('span', { class: 'base-symbol', 'aria-hidden': 'true' }, base.name.trim().slice(0, 1).toLocaleUpperCase() || 'K'),
@@ -1193,7 +1556,11 @@ function renderMountListRow(base, view, targetKind, targetId) {
     },
   })
   const modelLabel = writebackRouteLabel(base)
-  return element('article', { class: `mount-list-row${selected ? ' is-selected' : ''}`, role: 'listitem' },
+  return element('article', {
+    class: `mount-list-row${selected ? ' is-selected' : ''}`,
+    role: 'listitem',
+    'data-knowledge-motion-key': `knowledge-mount:${targetKind}:${base.id}`,
+  },
     element('label', { class: 'mount-select' }, checkbox, element('span', { class: 'visually-hidden' }, `选择 ${base.name}`)),
     element('div', { class: 'mount-list-main' },
       element('div', { class: 'mount-list-title' }, element('strong', {}, base.name), badge(view.statusLabel, view.statusVariant), badge(modelLabel)),
@@ -1249,53 +1616,82 @@ function renderDocumentWorkspace(workspace, options = {}) {
     'data-document-scope': workspace.kind,
     onInput: (event) => {
       view.query = event.target.value
-      renderShell()
-      const input = document.querySelector(`.note-tree-search[data-document-scope="${workspace.kind}"]`)
-      input?.focus()
-      input?.setSelectionRange(input.value.length, input.value.length)
+      scheduleDocumentSearch(workspace)
+      window.requestAnimationFrame(() => {
+        const input = document.querySelector(`.note-tree-search[data-document-scope="${workspace.kind}"]`)
+        input?.focus()
+        input?.setSelectionRange(input.value.length, input.value.length)
+      })
     },
   })
-  const tree = activeBases.map(base => {
+  const visibleBases = query
+    ? activeBases.filter(base => view.searchResults.some(document => document.knowledgeBaseId === base.id))
+    : activeBases
+  const tree = visibleBases.map(base => {
     const expanded = view.expandedBases.has(base.id) || Boolean(query)
-    const documents = workspaceDocuments.filter(document => document.knowledgeBaseId === base.id
-      && (!query || [document.title, document.relPath, document.content].some(value => value.toLocaleLowerCase().includes(query))))
-    return element('section', { class: 'note-tree-group', 'data-expanded': String(expanded) },
+    const page = documentPageState(workspace, base.id)
+    const documents = (query ? view.searchResults : workspaceDocuments).filter(document => document.knowledgeBaseId === base.id)
+    return element('section', {
+      class: 'note-tree-group', 'data-expanded': String(expanded),
+    },
       element('button', {
         type: 'button', class: 'note-tree-base', 'aria-expanded': String(expanded),
+        'data-knowledge-motion-key': `knowledge-base:${workspace.kind}:${base.id}`,
         onClick: () => {
-          view.knowledgeBaseId = base.id
-          if (expanded && !query) view.expandedBases.delete(base.id)
-          else view.expandedBases.add(base.id)
-          renderShell()
+          if (query) { view.knowledgeBaseId = base.id; return renderShell() }
+          void toggleDocumentBase(workspace, base.id)
         },
       },
       element('span', { class: 'tree-disclosure', 'aria-hidden': 'true' }),
       element('span', { class: 'tree-folder-icon', 'aria-hidden': 'true' }),
       element('span', { class: 'tree-base-name' }, base.name),
-      element('span', { class: 'tree-count' }, documents.length)),
+      element('span', { class: 'tree-count' }, query ? documents.length : page.loaded ? page.total : '—')),
       expanded ? element('div', { class: 'note-tree-documents', role: 'group', 'aria-label': `${base.name}文档` },
+        !query && page.loading && documents.length === 0 ? element('div', { class: 'note-tree-status', role: 'status' }, '正在读取目录…') : null,
+        !query && page.error ? element('div', { class: 'note-tree-status is-error' },
+          element('span', {}, page.error),
+          actionButton('重试', () => { void loadDocumentPage(workspace, base.id, { reset: true }).then(renderShell) }, 'ghost small')) : null,
         documents.map(document => element('button', {
           type: 'button', class: 'note-tree-document', 'aria-current': document.id === view.documentId ? 'page' : undefined,
-          onClick: () => { void selectDocument(workspace, document.id) },
+          'data-document-id': document.id,
+          'data-knowledge-motion-key': `knowledge-document:${workspace.kind}:${document.id}`,
+          onClick: () => { view.knowledgeBaseId = base.id; void selectDocument(workspace, document.id) },
         }, element('span', { class: 'tree-document-icon', 'aria-hidden': 'true' }), element('span', { class: 'tree-document-copy' },
           element('strong', {}, document.title), element('small', {}, document.relPath)),
         document.documentState !== 'open' ? badge(DOCUMENT_STATE_LABELS[document.documentState] || '已结束', 'success') : null)),
+        !query && page.nextCursor ? element('button', {
+          type: 'button', class: 'note-tree-more', disabled: page.loading,
+          onClick: () => { void loadDocumentPage(workspace, base.id, { append: true }).then(renderShell) },
+        }, page.loading ? '正在加载…' : `继续加载（已显示 ${documents.length} / ${page.total}）`) : null,
+        !query && page.loaded && documents.length === 0 ? element('div', { class: 'note-tree-status' }, '这个知识库还没有文档。') : null,
         !query && !readOnly ? element('button', { type: 'button', class: 'note-tree-new', onClick: () => { void startBlankDocument(workspace, base.id) } },
           element('span', { 'aria-hidden': 'true' }, '+'), '新建文档') : null,
       ) : null,
     )
   })
+  const treeContent = query
+    ? [
+      view.searchLoading && view.searchResults.length === 0 ? element('div', { class: 'note-tree-status', role: 'status' }, '正在搜索文档…') : null,
+      view.searchError ? element('div', { class: 'note-tree-status is-error' }, view.searchError) : null,
+      ...tree,
+      !view.searchLoading && !view.searchError && view.searchResults.length === 0 ? element('div', { class: 'note-tree-empty' }, '没有匹配的文档') : null,
+      view.searchNextCursor ? element('button', {
+        type: 'button', class: 'note-tree-more search-more', disabled: view.searchLoading,
+        onClick: () => { void loadDocumentSearch(workspace, false) },
+      }, view.searchLoading ? '正在加载…' : `继续加载搜索结果（${view.searchResults.length} / ${view.searchTotal}）`) : null,
+    ]
+    : tree.length ? tree : [element('div', { class: 'note-tree-empty' }, workspace.kind === 'session' && state.mountContext.sessionId ? '当前会话未挂载知识库' : '还没有知识库')]
   return element('section', {
     class: `note-workspace note-workspace--${workspace.kind}`, 'aria-labelledby': `${workspace.kind}-documents-heading`,
     'data-tree-open': String(view.treeOpen),
   },
     element('aside', { class: 'note-tree-panel', 'aria-label': '知识目录' },
       element('header', { class: 'note-tree-header' },
-        element('div', {}, element('h2', { id: `${workspace.kind}-documents-heading` }, options.heading || '知识目录'), element('span', {}, `${workspaceDocuments.length} 篇文档`)),
+        element('div', {}, element('h2', { id: `${workspace.kind}-documents-heading` }, options.heading || '知识目录'), element('span', {}, query ? `${view.searchTotal} 条搜索结果` : `${workspaceDocuments.length} 篇已加载`)),
         !readOnly ? actionButton('+', () => { void startBlankDocument(workspace, view.knowledgeBaseId || activeBases[0]?.id) }, 'ghost note-add-button', { 'aria-label': '新建文档', title: '新建文档' }) : null,
       ),
       element('div', { class: 'note-tree-search-wrap' }, interfaceIcon('search', 'search-symbol'), search),
-      element('nav', { class: 'note-tree', 'data-scroll-key': `${workspace.kind}-note-tree` }, tree.length ? tree : element('div', { class: 'note-tree-empty' }, workspace.kind === 'session' && state.mountContext.sessionId ? '当前会话未挂载知识库' : '还没有知识库')),
+      element('nav', { class: 'note-tree', 'data-scroll-key': `${workspace.kind}-note-tree` }, treeContent),
       workspace.kind === 'session' ? element('footer', { class: 'note-tree-footer' }, actionButton('新建知识库', () => openKnowledgeBaseEditor(), 'ghost small')) : null,
     ),
     view.treeOpen ? element('button', {
@@ -1309,6 +1705,7 @@ function renderDocumentWorkspace(workspace, options = {}) {
 function renderNoteEditor(workspace, editor, base) {
   const view = workspace.view
   const readOnly = documentWorkspaceReadOnly(workspace)
+  if (view.editorLoading) return renderDocumentEditorLoading(base)
   if (!editor) return element('main', { class: 'note-editor note-editor-empty' },
     element('div', { class: 'note-empty-content' },
       element('span', { class: 'empty-document-mark', 'aria-hidden': 'true' }),
@@ -1332,28 +1729,29 @@ function renderNoteEditor(workspace, editor, base) {
     class: 'note-title-input', value: editor.title, maxlength: 200, placeholder: '无标题文档', 'aria-label': '文档标题',
     onInput: event => update('title', event.target.value), onKeyDown: saveShortcut,
   })
-  const body = element('textarea', {
-    class: 'note-body-editor', maxlength: 50000, placeholder: '从这里开始记录…', 'aria-label': '文档正文',
-    onInput: event => { update('body', event.target.value); resizeDocumentEditor(event.target) }, onKeyDown: saveShortcut,
-  })
-  body.value = editor.body
   const finalized = !editor.isNew && editor.documentState !== 'open'
-  const mode = finalized || readOnly ? 'preview' : view.mode === 'edit' ? 'edit' : 'preview'
-  if (mode === 'edit') window.requestAnimationFrame(() => resizeDocumentEditor(body))
+  const editable = !finalized && !readOnly
+  const body = editable
+    ? element('div', { class: 'notes-live-editor knowledge-live-editor', role: 'status', 'aria-label': '正在打开知识文档正文' },
+      element('div', { class: 'notes-editor-loading' }, '正在打开文档…'))
+    : renderMarkdownPreview(editor.body)
+  if (editable) mountMarkdownEditor(body, {
+    markdown: editor.body,
+    label: '编辑知识文档正文',
+    onChange: value => update('body', value),
+    onSave: () => { void saveDocumentEditor(workspace).then(saved => { if (saved) renderShell() }) },
+  })
   return element('main', { class: 'note-editor', 'aria-label': '文档编辑器' },
     element('header', { class: 'note-editor-toolbar' },
       element('div', { class: 'note-breadcrumb' },
         element('span', {}, base?.name || '知识库'),
         element('span', { 'aria-hidden': 'true' }, '/'),
-        element('strong', {}, editor.isNew ? '新文档' : documentWorkspaceDocuments(workspace).find(item => item.id === editor.id)?.relPath || editor.title)),
+        element('strong', {}, editor.isNew ? '新文档' : documentWorkspaceDocuments(workspace).find(item => item.id === editor.id)?.relPath || editor.title),
+        element('span', { class: 'note-toolbar-meta' },
+          element('span', {}, editor.isNew ? '尚未保存' : `更新于 ${formatDate(editor.updatedAt)}`),
+          element('span', {}, editor.scope.kind === 'global' ? '全局知识' : `项目 ${editor.scope.id}`))),
       element('div', { class: 'note-editor-actions' },
-        finalized ? badge(DOCUMENT_STATE_LABELS[editor.documentState] || '已结束', 'success') : readOnly ? badge('只读') : element('div', { class: 'note-mode-switch', role: 'tablist', 'aria-label': '文档视图' }, [
-          ['edit', '编辑'],
-          ['preview', '预览'],
-        ].map(([value, label]) => element('button', {
-          type: 'button', role: 'tab', 'aria-selected': String(mode === value),
-          onClick: () => switchDocumentMode(workspace, value),
-        }, label))),
+        finalized ? badge(DOCUMENT_STATE_LABELS[editor.documentState] || '已结束', 'success') : readOnly ? badge('只读') : null,
         element('span', { class: 'editor-save-status', role: 'status' }, editor.saveState),
         finalized && !readOnly ? actionButton('重新打开', () => reopenDocument(workspace, editor), 'small') : null,
         !readOnly && !editor.isNew && !finalized ? actionButton('标记结束', () => openFinalizeDocument(workspace, editor), 'small') : null,
@@ -1370,14 +1768,12 @@ function renderNoteEditor(workspace, editor, base) {
         editor.finalizationNote ? element('p', {}, editor.finalizationNote) : null,
         editor.finalizedAt ? element('small', {}, `结束于 ${formatDate(editor.finalizedAt)}`) : null,
       ) : null,
-      element('article', { class: `note-paper is-${mode}`, 'data-document-mode': mode },
-        mode === 'edit' ? title : element('h1', { class: 'note-preview-title' }, editor.title || '无标题文档'),
-        element('div', { class: 'note-document-meta' },
-          element('span', {}, editor.isNew ? '尚未保存' : `更新于 ${formatDate(editor.updatedAt)}`),
-          element('span', {}, editor.scope.kind === 'global' ? '全局知识' : `项目 · ${editor.scope.id}`)),
-        mode === 'edit' ? body : renderMarkdownPreview(editor.body),
+      element('article', { class: `note-paper is-${editable ? 'edit' : 'preview'}`, 'data-document-mode': editable ? 'edit' : 'preview' },
+        editable ? title : element('h1', { class: 'note-preview-title' }, editor.title || '无标题文档'),
+        body,
       ),
     ),
+    renderDocumentReferenceBar(workspace, editor, editable),
     element('footer', { class: 'note-inspector' },
       finalized || readOnly ? element('span', { class: 'note-format-hint' }, readOnly ? '知识库已归档 · 只读' : '只读封存 · 重新打开后才能编辑') : element('label', {}, element('span', {}, '类型'), element('select', {
         class: 'note-meta-select', onChange: event => update('type', event.target.value),
@@ -1385,16 +1781,109 @@ function renderNoteEditor(workspace, editor, base) {
       finalized || readOnly ? null : element('label', { class: 'note-tags-field' }, element('span', {}, '标签'), element('input', {
         value: editor.tagsText, placeholder: '用逗号分隔', onInput: event => update('tagsText', event.target.value),
       })),
-      !finalized && !readOnly ? element('span', { class: 'note-format-hint' }, mode === 'edit' ? 'Markdown · Ctrl/⌘ S 保存' : 'Markdown 预览') : null,
+      editable ? element('span', { class: 'note-format-hint' }, 'Markdown · Ctrl/⌘ S 保存') : null,
     ),
   )
 }
 
-function switchDocumentMode(workspace, mode) {
-  if (mode !== 'edit' && mode !== 'preview') return
-  workspace.view.mode = mode
-  renderShell()
-  if (mode === 'edit') window.requestAnimationFrame(() => document.querySelector('.note-body-editor')?.focus())
+function renderDocumentEditorLoading(base) {
+  return element('main', { class: 'note-editor note-editor-loading', role: 'status', 'aria-label': '正在打开知识文档' },
+    element('header', { class: 'note-editor-toolbar' },
+      element('div', { class: 'note-breadcrumb' }, element('span', {}, base?.name || '知识库'), element('span', { 'aria-hidden': 'true' }, '/'), element('strong', {}, '正在打开文档')),
+      element('span', { class: 'editor-load-label' }, '按需加载正文与关联笔记'),
+    ),
+    element('div', { class: 'note-editor-scroll' }, element('article', { class: 'note-paper editor-paper-skeleton', 'aria-hidden': 'true' },
+      element('div', { class: 'skeleton-line skeleton-paper-title' }),
+      ...Array.from({ length: 9 }, (_, index) => element('div', { class: `skeleton-line skeleton-paper-row is-${index % 4}` })),
+    )),
+  )
+}
+
+function renderDocumentReferenceBar(workspace, editor, editable) {
+  const references = editor.noteReferences || []
+  return element('section', { class: 'document-reference-bar', 'aria-label': '关联笔记' },
+    element('div', { class: 'document-reference-heading' },
+      element('span', { class: 'document-reference-mark', 'aria-hidden': 'true' }),
+      element('strong', {}, '关联笔记'),
+      element('small', {}, references.length ? `${references.length} 项` : '未关联')),
+    element('div', { class: 'document-reference-list' }, references.length
+      ? references.map(reference => element('span', { class: 'document-reference-chip' },
+        element('button', {
+          type: 'button', class: 'document-reference-open', title: `打开 ${reference.note.name}`,
+          onClick: () => { void openNoteReference(reference.note.id) },
+        }, renderNoteIcon(reference.note), element('span', {}, reference.note.name)),
+        editable ? element('button', {
+          type: 'button', class: 'document-reference-remove', 'aria-label': `移除 ${reference.note.name} 的关联`, title: '移除关联',
+          onClick: () => { void removeDocumentNoteReference(workspace, editor, reference) },
+        }, '×') : null,
+      ))
+      : element('span', { class: 'document-reference-empty' }, editor.isNew ? '保存文档后可以关联笔记或资料文件' : '这篇知识还没有关联笔记')),
+    editable && !editor.isNew ? actionButton('+ 添加', () => { void openDocumentNoteReferencePicker(workspace, editor) }, 'ghost small document-reference-add') : null,
+  )
+}
+
+async function openDocumentNoteReferencePicker(workspace, editor) {
+  const search = element('input', {
+    class: 'input', type: 'search', placeholder: '搜索笔记文档或文件', 'aria-label': '搜索可关联的笔记',
+  })
+  const results = element('div', { class: 'note-picker-results', 'aria-live': 'polite' })
+  let modal
+  let request = 0
+  const paint = async () => {
+    const current = ++request
+    const query = search.value.trim()
+    if (!query) {
+      results.replaceChildren(element('div', { class: 'note-picker-empty' }, '输入名称以搜索可关联的笔记文档和文件。'))
+      return
+    }
+    results.replaceChildren(element('div', { class: 'note-picker-empty' }, '正在搜索…'))
+    try {
+      const linked = new Set((editor.noteReferences || []).map(reference => reference.note.id))
+      const visible = (await api(`notes?q=${encodeURIComponent(query)}&limit=100`)).filter(node => node.kind !== 'folder' && !linked.has(node.id))
+      if (current !== request) return
+      results.replaceChildren(...(visible.length
+        ? visible.map(node => element('button', {
+          type: 'button', class: 'note-picker-row',
+          onClick: async event => {
+            event.currentTarget.disabled = true
+            try {
+              const reference = await api(`entries/${encodeURIComponent(editor.id)}/note-references`, { method: 'POST', body: { noteId: node.id } })
+              editor.noteReferences = [...(editor.noteReferences || []), reference]
+              modal.close(true)
+              renderShell()
+              showToast('已关联笔记。')
+            } catch (error) {
+              event.currentTarget.disabled = false
+              showToast(friendlyError(error), 'error')
+            }
+          },
+        },
+        renderNoteIcon(node),
+        element('span', {}, element('strong', {}, node.name), element('small', {}, `${node.kind === 'document' ? '笔记文档' : formatBytes(node.size)}  ${shortNoteId(node.id)}`))))
+        : [element('div', { class: 'note-picker-empty' }, '没有匹配的笔记文档或文件。')]))
+    } catch (error) {
+      if (current !== request) return
+      results.replaceChildren(element('div', { class: 'note-picker-empty is-error' }, friendlyError(error)))
+    }
+  }
+  let timer = 0
+  search.addEventListener('input', () => { window.clearTimeout(timer); timer = window.setTimeout(() => void paint(), 180) })
+  modal = openSheet({
+    title: '添加关联笔记',
+    description: '关联保存在文档正文之外；笔记移动或改名后仍然有效。',
+    body: element('div', { class: 'note-picker' }, search, results),
+    cancelLabel: '取消',
+  })
+  search.focus()
+}
+
+async function removeDocumentNoteReference(workspace, editor, reference) {
+  try {
+    await api(`entries/${encodeURIComponent(editor.id)}/note-references/${encodeURIComponent(reference.note.id)}`, { method: 'DELETE' })
+    editor.noteReferences = (editor.noteReferences || []).filter(item => item.note.id !== reference.note.id)
+    if (workspace.view.editor === editor) renderShell()
+    showToast('已移除关联。')
+  } catch (error) { showToast(friendlyError(error), 'error') }
 }
 
 function renderMarkdownPreview(markdown) {
@@ -1409,12 +1898,30 @@ function renderMarkdownPreview(markdown) {
     table.replaceWith(scroller)
     scroller.append(table)
   })
+  preview.querySelectorAll('[data-note-id]').forEach(link => {
+    link.setAttribute('role', 'button')
+    link.setAttribute('tabindex', '0')
+    link.setAttribute('title', '打开笔记文档')
+    const open = event => {
+      if (event.type === 'keydown' && event.key !== 'Enter' && event.key !== ' ') return
+      event.preventDefault()
+      void openNoteReference(link.dataset.noteId)
+    }
+    link.addEventListener('click', open)
+    link.addEventListener('keydown', open)
+  })
   return preview
 }
 
-function resizeDocumentEditor(editor) {
-  editor.style.height = 'auto'
-  editor.style.height = `${Math.max(420, editor.scrollHeight)}px`
+async function openNoteReference(id) {
+  try {
+    if (!await saveBeforeLeavingDocument()) return
+    const node = await api(`notes/${encodeURIComponent(id)}`)
+    state.view = 'notes'
+    state.loading = false
+    await selectNoteNode(node)
+    renderShell()
+  } catch (error) { showToast(friendlyError(error), 'error') }
 }
 
 function openFinalizeDocument(workspace, editor) {
@@ -1484,6 +1991,1070 @@ function confirmDeleteDocument(workspace, editor) {
   })
 }
 
+function renderNotes() {
+  const fileInput = element('input', {
+    class: 'visually-hidden', type: 'file', multiple: true, tabindex: '-1',
+    onChange: event => { void uploadNoteFiles([...event.target.files], state.notes.currentFolderId); event.target.value = '' },
+  })
+  const rootNodes = state.notes.children.get('root') || []
+  const tree = state.notes.query.trim()
+    ? renderNoteSearchResults()
+    : renderNoteTreeBranch(null)
+  const workspace = element('section', {
+    class: 'notes-workspace', 'data-drop-active': 'false',
+    onDragEnter: noteWorkspaceDragEnter, onDragOver: noteWorkspaceDragEnter,
+    onDragLeave: noteWorkspaceDragLeave,
+    onDrop: event => {
+      clearNoteDragState()
+      if (!hasDragType(event, 'Files')) return
+      event.preventDefault()
+      void importDroppedNotes(event.dataTransfer, state.notes.currentFolderId)
+    },
+  },
+    element('aside', { class: 'notes-browser', 'aria-label': '笔记目录' },
+      element('header', { class: 'notes-browser-header' },
+        element('div', {}, element('h2', {}, '目录'), element('span', {}, `${rootNodes.length} 个根目录项目`)),
+        element('div', { class: 'notes-browser-actions' },
+          actionButton('新建', () => openCreateNoteDocument(), 'primary small'),
+          actionButton('目录', () => openCreateNoteFolder(), 'small'),
+          actionButton('导入', () => fileInput.click(), 'ghost small'),
+          fileInput,
+        ),
+      ),
+      element('div', { class: 'notes-search' }, element('input', {
+        class: 'input', type: 'search', value: state.notes.query, placeholder: '搜索笔记文档', 'aria-label': '搜索笔记文档',
+        onInput: event => scheduleNoteSearch(event.target.value),
+      })),
+      element('div', {
+        class: 'notes-tree', role: 'tree', 'data-scroll-key': 'notes-tree',
+        onDragOver: event => {
+          if (hasDragType(event, 'application/x-dsh-note-id') || hasDragType(event, 'Files')) event.preventDefault()
+        },
+        onDrop: event => { if (event.target === event.currentTarget) void dropNoteNode(event, null) },
+      }, tree),
+    ),
+    renderNoteContent(),
+    element('div', { class: 'notes-drop-overlay', 'aria-hidden': 'true' },
+      element('strong', {}, '放开以导入当前目录'),
+      element('span', {}, '支持文件和完整目录，原有目录层级会被保留。')),
+    renderNoteTransfer(),
+  )
+  return element('section', { class: 'notes-page', 'aria-label': '笔记工作区' }, workspace)
+}
+
+function renderNoteTransfer() {
+  const transfer = state.notes.transfer
+  if (!transfer) return null
+  const dismissible = transfer.phase === 'complete' || transfer.phase === 'error'
+  return element('section', {
+    class: 'notes-transfer', 'data-note-transfer': transfer.id, 'data-state': transfer.phase,
+    role: transfer.phase === 'error' ? 'alert' : 'status', 'aria-live': 'polite',
+  },
+    element('div', { class: 'notes-transfer-heading' },
+      element('span', { class: 'notes-transfer-mark', 'aria-hidden': 'true' }),
+      element('strong', { class: 'notes-transfer-title' }, noteTransferTitle(transfer)),
+      dismissible ? actionButton('关闭', dismissNoteTransfer, 'ghost tiny notes-transfer-close', { 'aria-label': '关闭导入进度' }) : null,
+    ),
+    element('div', { class: 'notes-transfer-detail', title: transfer.currentName || '' }, noteTransferDetail(transfer)),
+    element('div', {
+      class: 'notes-transfer-track', role: 'progressbar',
+      'aria-label': '笔记导入进度', 'aria-valuemin': '0', 'aria-valuemax': '100',
+      'aria-valuenow': transfer.phase === 'scanning' ? undefined : String(noteTransferPercent(transfer)),
+    }, element('span', { class: 'notes-transfer-fill' })),
+    element('div', { class: 'notes-transfer-meta' },
+      element('span', { class: 'notes-transfer-count' }, noteTransferCount(transfer)),
+      element('span', { class: 'notes-transfer-percent' }, transfer.phase === 'scanning' ? '正在整理' : `${noteTransferPercent(transfer)}%`),
+    ),
+  )
+}
+
+function renderNoteTreeBranch(parentId, depth = 0) {
+  const key = parentId || 'root'
+  const nodes = state.notes.children.get(key) || []
+  if (!nodes.length && depth === 0) {
+    return element('div', { class: 'notes-tree-empty' }, element('strong', {}, '还没有笔记'), element('span', {}, '新建目录或文档开始整理。'))
+  }
+  return element('div', { class: 'notes-tree-branch', role: depth ? 'group' : undefined }, nodes.map(node => {
+    const selected = state.notes.selectedId === node.id
+    const expanded = node.kind === 'folder' && state.notes.expandedFolders.has(node.id)
+    const row = element('div', {
+      class: 'notes-tree-item', 'data-kind': node.kind, 'data-selected': String(selected),
+      'data-note-id': node.id,
+      'data-knowledge-motion-key': `note:${node.id}`,
+      draggable: 'true',
+      onDragStart: event => {
+        event.dataTransfer.effectAllowed = 'move'
+        event.dataTransfer.setData('application/x-dsh-note-id', node.id)
+        event.currentTarget.dataset.dragging = 'true'
+      },
+      onDragEnd: () => clearNoteDragState(),
+      onDragEnter: event => activateNoteFolderDropTarget(event, node),
+      onDragOver: event => activateNoteFolderDropTarget(event, node),
+      onDragLeave: event => { if (!event.currentTarget.contains(event.relatedTarget)) event.currentTarget.dataset.dropTarget = 'false' },
+      onDrop: event => { if (node.kind === 'folder') void dropNoteNode(event, node.id) },
+    },
+      element('button', {
+        type: 'button', class: 'notes-tree-row', role: 'treeitem',
+        'aria-selected': String(selected), 'aria-expanded': node.kind === 'folder' ? String(expanded) : undefined,
+        onClick: () => { void selectNoteNode(node, { toggleFolder: node.kind === 'folder' }) },
+      },
+        node.kind === 'folder' ? element('span', { class: 'notes-tree-chevron', 'aria-hidden': 'true' }) : element('span', { class: 'notes-tree-spacer' }),
+        renderNoteIcon(node),
+        element('span', { class: 'notes-tree-name', title: node.name }, node.name),
+      ),
+      element('div', { class: 'notes-row-actions' },
+        actionButton('重命名', event => { event.stopPropagation(); openRenameNoteNode(node) }, 'ghost tiny'),
+        actionButton('复制', event => { event.stopPropagation(); void copyNoteNode(node) }, 'ghost tiny'),
+        actionButton('删除', event => { event.stopPropagation(); void confirmDeleteNoteNode(node) }, 'ghost tiny danger-text'),
+      ),
+    )
+    const children = expanded
+      ? state.notes.loadedFolders.has(node.id)
+        ? renderNoteTreeBranch(node.id, depth + 1)
+        : element('div', { class: 'notes-tree-loading', role: 'status' }, '正在读取…')
+      : null
+    return element('div', { class: 'notes-tree-node' }, row, children)
+  }))
+}
+
+function renderNoteSearchResults() {
+  if (!state.notes.searchResults.length) return element('div', { class: 'notes-tree-empty' }, '没有匹配的笔记文档。')
+  return element('div', { class: 'notes-search-results' }, state.notes.searchResults.map(node => element('button', {
+    type: 'button', class: 'notes-search-row', 'data-knowledge-motion-key': `note-search:${node.id}`,
+    onClick: () => { void selectNoteNode(node) },
+  }, renderNoteIcon(node), element('span', {}, element('strong', {}, node.name), element('small', {}, noteKindLabel(node))))))
+}
+
+function renderNoteContent() {
+  const node = state.notes.selectedNode
+  if (!node) return renderNoteFolderContent(null)
+  if (state.notes.loadingNodeId === node.id) return renderNoteSelectionLoading(node)
+  if (node.kind === 'folder') return renderNoteFolderContent(node)
+  if (node.kind === 'document') return renderNoteDocument(node)
+  return renderNoteFile(node)
+}
+
+function renderNoteSelectionLoading(node) {
+  return element('main', { class: `notes-content notes-selection-loading is-${node.kind}`, role: 'status', 'aria-label': `正在打开 ${node.name}` },
+    element('header', { class: 'notes-content-header' },
+      element('div', { class: 'notes-breadcrumb' }, element('span', {}, '笔记文档'), element('span', { 'aria-hidden': 'true' }, '/'), element('strong', {}, node.name)),
+      element('div', { class: 'notes-content-title' }, element('div', {}, element('h2', {}, node.name), element('p', {}, node.kind === 'folder' ? '正在读取目录内容' : '正在按需读取文档内容'))),
+    ),
+    element('div', { class: 'notes-selection-skeleton', 'aria-hidden': 'true' },
+      element('div', { class: 'skeleton-line skeleton-paper-title' }),
+      ...Array.from({ length: node.kind === 'folder' ? 6 : 9 }, (_, index) => element('div', { class: `skeleton-line skeleton-paper-row is-${index % 4}` })),
+    ),
+  )
+}
+
+function renderNoteFolderContent(folder) {
+  const parentId = folder?.id || null
+  const children = state.notes.children.get(parentId || 'root') || []
+  return element('main', {
+    class: 'notes-content is-folder',
+    onDragOver: event => event.preventDefault(),
+    onDrop: event => void dropNoteNode(event, parentId),
+  },
+    renderNoteContentHeader(folder),
+    children.length
+      ? element('div', { class: 'notes-file-list', role: 'list' }, children.map(node => element('div', {
+        class: 'notes-file-row', role: 'listitem', draggable: 'true',
+        onDragStart: event => { event.dataTransfer.effectAllowed = 'move'; event.dataTransfer.setData('application/x-dsh-note-id', node.id) },
+        onDblClick: () => { void selectNoteNode(node, { toggleFolder: node.kind === 'folder' }) },
+      },
+        element('button', { type: 'button', class: 'notes-file-main', onClick: () => { void selectNoteNode(node) } },
+          renderNoteIcon(node, true),
+          element('span', {}, element('strong', {}, node.name), element('small', {}, noteKindLabel(node))),
+        ),
+        element('time', { datetime: node.updatedAt }, formatDate(node.updatedAt)),
+        element('span', { class: 'notes-file-size' }, node.kind === 'folder' ? '' : formatBytes(node.size)),
+        element('div', { class: 'notes-file-actions' },
+          actionButton('重命名', () => openRenameNoteNode(node), 'ghost tiny'),
+          actionButton('复制', () => { void copyNoteNode(node) }, 'ghost tiny'),
+          actionButton('删除', () => { void confirmDeleteNoteNode(node) }, 'ghost tiny danger-text'),
+        ),
+      )))
+      : element('div', { class: 'notes-folder-empty' },
+        element('span', { class: 'notes-empty-folder-mark', 'aria-hidden': 'true' }),
+        element('h3', {}, '这个目录还是空的'),
+        element('p', {}, '可以新建笔记文档、建立子目录，或把本地文件拖到这里。'),
+        element('div', {}, actionButton('新建文档', () => openCreateNoteDocument(parentId), 'primary small'), actionButton('新建目录', () => openCreateNoteFolder(parentId), 'small')),
+      ),
+  )
+}
+
+function renderNoteContentHeader(folder) {
+  const path = folder ? [...state.notes.breadcrumbs] : []
+  return element('header', { class: 'notes-content-header' },
+    element('nav', { class: 'notes-breadcrumb', 'aria-label': '当前位置' },
+      element('button', { type: 'button', onClick: () => { void openNoteRoot() } }, '笔记文档'),
+      path.map(node => element('span', {}, element('span', { 'aria-hidden': 'true' }, '/'), element('button', { type: 'button', onClick: () => { void selectNoteNode(node) } }, node.name))),
+    ),
+    element('div', { class: 'notes-content-title' },
+      element('div', {}, element('h2', {}, folder?.name || '全部笔记'), element('p', {}, folder ? `${(state.notes.children.get(folder.id) || []).length} 个项目` : '你的独立笔记与资料目录')),
+      element('div', { class: 'notes-content-actions' },
+        actionButton('新建文档', () => openCreateNoteDocument(folder?.id || null), 'primary small'),
+        actionButton('新建目录', () => openCreateNoteFolder(folder?.id || null), 'small'),
+      ),
+    ),
+  )
+}
+
+function renderNoteDocument(node) {
+  return renderEditableNote(node)
+}
+
+function renderEditableNote(node) {
+  const markdown = isMarkdownNote(node)
+  const title = editableNoteTitle(node)
+  const editor = markdown
+    ? element('div', { class: 'notes-live-editor', role: 'status', 'aria-label': `正在打开 ${node.name}` },
+      element('div', { class: 'notes-editor-loading' }, '正在打开文档…'))
+    : createPlainTextNoteEditor(node)
+  if (markdown) mountMarkdownNoteEditor(editor, node)
+  else mountPlainTextNoteEditor(editor, node)
+  return element('main', { class: `notes-content is-document${markdown ? '' : ' has-line-numbers'}` },
+    renderNoteFileToolbar(node, { editable: true }),
+    element('h1', {
+      class: 'notes-document-title', contenteditable: 'plaintext-only', spellcheck: 'false',
+      'aria-label': `修改 ${node.name} 的标题`, title: '点击修改标题',
+      onBlur: event => { void saveEditableNoteTitle(event.currentTarget, node) },
+      onKeyDown: event => {
+        if (event.key === 'Enter') { event.preventDefault(); event.currentTarget.blur() }
+        if (event.key === 'Escape') { event.preventDefault(); event.currentTarget.textContent = title; event.currentTarget.blur() }
+      },
+    }, title),
+    editor,
+  )
+}
+
+function editableNoteTitle(node) {
+  return node.kind === 'document' ? node.name.replace(/\.md$/i, '') : node.name
+}
+
+async function saveEditableNoteTitle(editor, node) {
+  const title = readPlainTextEditor(editor).replace(/\s+/g, ' ').trim()
+  const name = node.kind === 'document' && title ? `${title.replace(/\.md$/i, '')}.md` : title
+  if (!name) {
+    editor.textContent = editableNoteTitle(node)
+    showToast('标题不能为空。', 'error')
+    return
+  }
+  if (name === node.name) {
+    editor.textContent = editableNoteTitle(node)
+    return
+  }
+  editor.setAttribute('contenteditable', 'false')
+  try {
+    const updated = await api(`notes/${encodeURIComponent(node.id)}`, { method: 'PATCH', body: { name } })
+    if (state.notes.selectedNode?.id === node.id) state.notes.selectedNode = updated
+    editor.textContent = editableNoteTitle(updated)
+    const breadcrumb = document.querySelector('.notes-document-toolbar .notes-breadcrumb strong')
+    if (breadcrumb) breadcrumb.textContent = updated.name
+    await loadNoteChildren(updated.parentId, true).catch(() => {})
+    const treeName = document.querySelector(`.notes-tree-item[data-note-id="${updated.id}"] .notes-tree-name`)
+    if (treeName) treeName.textContent = updated.name
+    showToast('标题已更新。')
+  } catch (error) {
+    editor.textContent = editableNoteTitle(node)
+    showToast(friendlyError(error), 'error')
+  } finally {
+    if (editor.isConnected) editor.setAttribute('contenteditable', 'plaintext-only')
+  }
+}
+
+function createPlainTextNoteEditor(node) {
+  return element('div', { class: 'notes-plain-editor', role: 'status', 'aria-label': `正在打开 ${node.name}` },
+    element('div', { class: 'notes-editor-loading' }, '正在打开文档…'))
+}
+
+function readPlainTextEditor(editor) {
+  return editor.innerText.replace(/\r\n?/g, '\n')
+}
+
+function updateNoteDraft(value) {
+  state.notes.draft = value
+  state.notes.dirty = state.notes.draft !== state.notes.content
+  syncNoteEditorChrome()
+}
+
+function mountMarkdownNoteEditor(host, node) {
+  mountMarkdownEditor(host, {
+    markdown: state.notes.draft,
+    label: `编辑 ${node.name}`,
+    isCurrent: () => state.notes.selectedNode?.id === node.id,
+    onChange: updateNoteDraft,
+    onSave: () => { void saveNoteDocument() },
+  })
+}
+
+function mountPlainTextNoteEditor(host, node) {
+  const request = ++plainTextEditorMountRequest
+  window.requestAnimationFrame(async () => {
+    if (!host.isConnected || state.notes.selectedNode?.id !== node.id || request !== plainTextEditorMountRequest) return
+    try {
+      const runtime = await loadMarkdownNoteEditor()
+      if (!host.isConnected || state.notes.selectedNode?.id !== node.id || request !== plainTextEditorMountRequest) return
+      host.replaceChildren()
+      host.removeAttribute('role')
+      plainTextEditorHandle = runtime.createPlainTextEditor({
+        host,
+        text: state.notes.draft,
+        label: `编辑 ${node.name}`,
+        onChange: updateNoteDraft,
+        onSave: () => { void saveNoteDocument() },
+      })
+    } catch (error) {
+      if (!host.isConnected || request !== plainTextEditorMountRequest) return
+      host.replaceChildren(element('div', { class: 'notes-editor-error', role: 'alert' },
+        element('strong', {}, '无法打开纯文本编辑器'),
+        element('span', {}, friendlyError(error)),
+        actionButton('重试', () => { noteEditorLoader = null; host.replaceChildren(); mountPlainTextNoteEditor(host, node) }, 'small')))
+    }
+  })
+}
+
+function mountMarkdownEditor(host, options) {
+  const request = ++markdownEditorMountRequest
+  window.requestAnimationFrame(async () => {
+    if (!host.isConnected || options.isCurrent?.() === false || request !== markdownEditorMountRequest) return
+    try {
+      const runtime = await loadMarkdownNoteEditor()
+      if (!host.isConnected || options.isCurrent?.() === false || request !== markdownEditorMountRequest) return
+      host.replaceChildren()
+      host.removeAttribute('role')
+      markdownEditorHandle = runtime.createMarkdownEditor({
+        host,
+        markdown: options.markdown,
+        label: options.label,
+        onChange: options.onChange,
+        onSave: options.onSave,
+      })
+    } catch (error) {
+      if (!host.isConnected || request !== markdownEditorMountRequest) return
+      host.replaceChildren(element('div', { class: 'notes-editor-error', role: 'alert' },
+        element('strong', {}, '无法打开 Markdown 编辑器'),
+        element('span', {}, friendlyError(error)),
+        actionButton('重试', () => { noteEditorLoader = null; host.replaceChildren(); mountMarkdownEditor(host, options) }, 'small')))
+    }
+  })
+}
+
+function loadMarkdownNoteEditor() {
+  if (window.DshKnowledgeNoteEditor?.createMarkdownEditor) return Promise.resolve(window.DshKnowledgeNoteEditor)
+  if (noteEditorLoader) return noteEditorLoader
+  noteEditorLoader = new Promise((resolve, reject) => {
+    const script = document.createElement('script')
+    const suffix = ASSET_VERSION ? `?v=${encodeURIComponent(ASSET_VERSION)}` : ''
+    script.src = `${WEB_PATH.replace(/\/$/, '')}/note-editor.js${suffix}`
+    script.async = true
+    script.onload = () => window.DshKnowledgeNoteEditor?.createMarkdownEditor
+      ? resolve(window.DshKnowledgeNoteEditor)
+      : reject(new Error('Markdown 编辑器模块无效'))
+    script.onerror = () => { script.remove(); reject(new Error('Markdown 编辑器加载失败')) }
+    document.head.append(script)
+  }).catch(error => {
+    noteEditorLoader = null
+    throw error
+  })
+  return noteEditorLoader
+}
+
+function releaseNoteEditors() {
+  markdownEditorMountRequest += 1
+  plainTextEditorMountRequest += 1
+  markdownEditorHandle?.destroy()
+  plainTextEditorHandle?.destroy()
+  markdownEditorHandle = null
+  plainTextEditorHandle = null
+}
+
+function syncNoteEditorChrome() {
+  const status = document.querySelector('[data-note-save-state]')
+  if (status) {
+    status.textContent = state.notes.dirty ? '未保存' : '已保存'
+    status.dataset.dirty = String(state.notes.dirty)
+  }
+  const save = document.querySelector('[data-note-save]')
+  if (save) save.disabled = !state.notes.dirty
+}
+
+function renderNoteDocumentBreadcrumb(node) {
+  return element('nav', { class: 'notes-breadcrumb', 'aria-label': '当前位置' },
+    element('button', { type: 'button', onClick: () => { void openNoteRoot() } }, '笔记文档'),
+    state.notes.breadcrumbs.map(parent => element('span', {}, element('span', { 'aria-hidden': 'true' }, '/'), element('button', { type: 'button', onClick: () => { void selectNoteNode(parent) } }, parent.name))),
+    element('span', {}, element('span', { 'aria-hidden': 'true' }, '/'), element('strong', {}, node.name)),
+  )
+}
+
+function renderNoteFile(node) {
+  if (node.editable) return renderEditableNote(node)
+  const previewKind = noteFilePreviewKind(node)
+  let preview
+  if (previewKind === 'image' && state.notes.assetUrl) {
+    preview = element('img', { class: 'notes-inline-image', src: state.notes.assetUrl, alt: node.name })
+  } else if (previewKind === 'pdf' && state.notes.assetUrl) {
+    preview = element('iframe', { class: 'notes-inline-frame', src: state.notes.assetUrl, title: node.name })
+  } else {
+    preview = element('div', { class: 'notes-inline-unavailable' },
+      renderNoteIcon(node, true),
+      element('h2', {}, node.name),
+      element('p', {}, '该格式不能在浏览器中直接编辑，可以下载后使用本地应用打开。'),
+      actionButton('下载文件', () => { void downloadNoteFile(node) }, 'primary small'),
+    )
+  }
+  return element('main', { class: 'notes-content is-file' },
+    renderNoteFileToolbar(node),
+    element('section', { class: `notes-inline-viewer is-${previewKind}`, 'aria-label': `${node.name}内容` }, preview),
+  )
+}
+
+function renderNoteFileToolbar(node, options = {}) {
+  return element('header', { class: 'notes-document-toolbar' },
+    element('div', { class: 'notes-toolbar-leading' },
+      renderNoteDocumentBreadcrumb(node),
+      element('div', { class: 'notes-file-info', 'aria-label': '文件信息' },
+        noteInfoItem('编号', shortNoteId(node.id), node.id),
+        noteInfoItem('类型', node.kind === 'document' ? 'Markdown' : node.mediaType || '未知'),
+        noteInfoItem('大小', formatBytes(node.size), '', 'size'),
+        noteInfoItem('更新', formatDate(node.updatedAt), '', 'updated'),
+      ),
+    ),
+    element('div', { class: 'notes-document-actions' },
+      options.editable ? element('span', { class: 'notes-save-state', role: 'status', 'data-note-save-state': '', 'data-dirty': String(state.notes.dirty) }, state.notes.dirty ? '未保存' : '已保存') : null,
+      node.kind === 'file' ? actionButton('下载', () => { void downloadNoteFile(node) }, 'ghost small') : null,
+      actionButton('复制引用', () => { void copyNoteReference(node) }, 'ghost small'),
+      actionButton('重命名', () => openRenameNoteNode(node), 'ghost small'),
+      options.editable ? actionButton('保存', () => { void saveNoteDocument() }, 'primary small', { 'data-note-save': '', disabled: !state.notes.dirty }) : null,
+    ),
+  )
+}
+
+function noteInfoItem(label, value, title = '', key = '') {
+  return element('span', { class: 'notes-file-info-item', title: title || value, ...(key ? { 'data-note-info': key } : {}) }, element('strong', {}, label), element('span', {}, value))
+}
+
+function renderNoteIcon(node, large = false) {
+  const label = node.kind === 'folder' ? '' : noteExtension(node.name)
+  return element('span', { class: `note-node-icon is-${node.kind}${large ? ' is-large' : ''}`, 'data-media-kind': noteMediaKind(node), 'aria-hidden': 'true' }, label)
+}
+
+function noteKindLabel(node) {
+  if (node.kind === 'folder') return '目录'
+  if (node.kind === 'document') return 'Markdown 笔记'
+  return `${node.mediaType || '文件'}  ${formatBytes(node.size)}`
+}
+
+function isMarkdownNote(node) {
+  return node.kind === 'document' || node.mediaType === 'text/markdown' || /\.(md|markdown)$/i.test(node.name)
+}
+
+function noteFilePreviewKind(node) {
+  if (node.mediaType?.startsWith('image/')) return 'image'
+  if (node.mediaType === 'application/pdf' || /\.pdf$/i.test(node.name)) return 'pdf'
+  return 'unavailable'
+}
+
+async function selectNoteNode(node, options = {}) {
+  if (state.notes.dirty && !await saveNoteDocument()) return
+  const request = ++noteSelectionRequest
+  releaseNoteAsset()
+  state.notes.selectedId = node.id
+  state.notes.selectedNode = node
+  Object.assign(state.notes, { content: '', draft: '', dirty: false })
+  state.notes.loadingNodeId = node.id
+  renderShell()
+  try {
+    const breadcrumbs = await loadNoteBreadcrumbs(node)
+    if (request !== noteSelectionRequest || state.notes.selectedId !== node.id) return
+    state.notes.breadcrumbs = breadcrumbs
+    if (node.kind === 'folder') {
+      Object.assign(state.notes, { content: '', draft: '', dirty: false })
+      state.notes.currentFolderId = node.id
+      if (options.toggleFolder) {
+        if (state.notes.expandedFolders.has(node.id)) state.notes.expandedFolders.delete(node.id)
+        else state.notes.expandedFolders.add(node.id)
+      }
+      await loadNoteChildren(node.id)
+    } else if (node.editable) {
+      const blob = await binaryRequest(`notes/${encodeURIComponent(node.id)}/content`, { responseType: 'blob', accept: node.mediaType || 'text/plain' })
+      const content = await blob.text()
+      if (request !== noteSelectionRequest || state.notes.selectedId !== node.id) return
+      state.notes.content = content
+      state.notes.draft = content
+      state.notes.dirty = false
+      state.notes.currentFolderId = node.parentId
+    } else {
+      state.notes.content = ''
+      state.notes.draft = ''
+      state.notes.dirty = false
+      state.notes.currentFolderId = node.parentId
+      if (noteFilePreviewKind(node) !== 'unavailable') {
+        const blob = await binaryRequest(`notes/${encodeURIComponent(node.id)}/content`, { responseType: 'blob', accept: node.mediaType || 'application/octet-stream' })
+        if (request !== noteSelectionRequest || state.notes.selectedId !== node.id) return
+        state.notes.assetUrl = URL.createObjectURL(blob)
+      }
+    }
+  } catch (error) {
+    if (request === noteSelectionRequest) showToast(friendlyError(error), 'error')
+  } finally {
+    if (request === noteSelectionRequest && state.notes.loadingNodeId === node.id) {
+      state.notes.loadingNodeId = ''
+      renderShell()
+    }
+  }
+}
+
+async function loadNoteChildren(parentId, force = false) {
+  const key = parentId || 'root'
+  if (!force && state.notes.loadedFolders.has(key)) return state.notes.children.get(key) || []
+  const params = new URLSearchParams({ limit: '500' })
+  if (parentId) params.set('parentId', parentId)
+  const nodes = await api(`notes?${params}`)
+  state.notes.children.set(key, nodes)
+  state.notes.loadedFolders.add(key)
+  return nodes
+}
+
+async function loadNoteBreadcrumbs(node) {
+  const parents = []
+  let parentId = node.parentId
+  while (parentId) {
+    const parent = findCachedNote(parentId) || await api(`notes/${encodeURIComponent(parentId)}`)
+    parents.unshift(parent)
+    parentId = parent.parentId
+  }
+  return node.kind === 'folder' ? [...parents, node] : parents
+}
+
+function findCachedNote(id) {
+  for (const nodes of state.notes.children.values()) {
+    const found = nodes.find(node => node.id === id)
+    if (found) return found
+  }
+  return state.notes.selectedNode?.id === id ? state.notes.selectedNode : null
+}
+
+async function openNoteRoot() {
+  if (state.notes.dirty && !await saveNoteDocument()) return
+  noteSelectionRequest += 1
+  clearNoteSelection()
+  await loadNoteChildren(null)
+  renderShell()
+}
+
+function clearNoteSelection() {
+  releaseNoteAsset()
+  Object.assign(state.notes, { selectedId: '', selectedNode: null, currentFolderId: null, breadcrumbs: [], content: '', draft: '', dirty: false, loadingNodeId: '' })
+}
+
+function releaseNoteAsset() {
+  if (!state.notes?.assetUrl) return
+  URL.revokeObjectURL(state.notes.assetUrl)
+  state.notes.assetUrl = ''
+}
+
+function scheduleNoteSearch(value) {
+  state.notes.query = value
+  window.clearTimeout(noteSearchTimer)
+  noteSearchTimer = window.setTimeout(async () => {
+    try {
+      state.notes.searchResults = value.trim() ? await api(`notes?q=${encodeURIComponent(value.trim())}&limit=200`) : []
+      renderShell()
+    } catch (error) { showToast(friendlyError(error), 'error') }
+  }, 180)
+}
+
+function openCreateNoteFolder(parentId = state.notes.currentFolderId) {
+  const field = formField('目录名称', 'text', '', { maxlength: 255, placeholder: '例如：项目资料' })
+  const form = element('form', { class: 'form-grid' }, field.wrapper)
+  openSheet({
+    title: '新建目录', description: '目录可以继续包含子目录、笔记文档和任意文件。', body: form,
+    primaryLabel: '创建目录', onPrimary: async () => {
+      const node = await api('notes/folders', { method: 'POST', body: { name: field.input.value, parentId } })
+      await loadNoteChildren(parentId, true)
+      if (parentId) state.notes.expandedFolders.add(parentId)
+      await selectNoteNode(node)
+      return true
+    },
+  })
+  field.input.focus()
+}
+
+function openCreateNoteDocument(parentId = state.notes.currentFolderId) {
+  const field = formField('文档名称', 'text', '', { maxlength: 255, placeholder: '例如：部署记录' })
+  const form = element('form', { class: 'form-grid' }, field.wrapper)
+  openSheet({
+    title: '新建笔记文档', description: '文档使用 Markdown 编辑，默认不会被 AI 检索或回写。', body: form,
+    primaryLabel: '创建并编辑', onPrimary: async () => {
+      const node = await api('notes/documents', { method: 'POST', body: { name: field.input.value, parentId } })
+      await loadNoteChildren(parentId, true)
+      if (parentId) state.notes.expandedFolders.add(parentId)
+      await selectNoteNode(node)
+      return true
+    },
+  })
+  field.input.focus()
+}
+
+function openRenameNoteNode(node) {
+  const field = formField('名称', 'text', node.name, { maxlength: 255 })
+  openSheet({
+    title: '重命名', description: '知识文档中的 @ 引用使用稳定编号，不会因改名失效。', body: element('form', { class: 'form-grid' }, field.wrapper),
+    primaryLabel: '保存名称', onPrimary: async () => {
+      const updated = await api(`notes/${encodeURIComponent(node.id)}`, { method: 'PATCH', body: { name: field.input.value } })
+      await loadNoteChildren(node.parentId, true)
+      if (state.notes.selectedId === node.id) await selectNoteNode(updated)
+      else renderShell()
+      showToast('名称已更新。')
+      return true
+    },
+  })
+  field.input.select()
+}
+
+async function copyNoteNode(node) {
+  try {
+    const copy = await api(`notes/${encodeURIComponent(node.id)}/copy`, { method: 'POST', body: {} })
+    await loadNoteChildren(node.parentId, true)
+    renderShell()
+    showToast(`已创建“${copy.name}”。`)
+  } catch (error) { showToast(friendlyError(error), 'error') }
+}
+
+async function dropNoteNode(event, parentId) {
+  event.preventDefault()
+  event.stopPropagation()
+  clearNoteDragState()
+  const id = event.dataTransfer.getData('application/x-dsh-note-id')
+  if (!id) {
+    if (hasDragType(event, 'Files')) await importDroppedNotes(event.dataTransfer, parentId)
+    return
+  }
+  const node = findCachedNote(id)
+  if (!node || id === parentId || node.parentId === parentId) return
+  try {
+    await api(`notes/${encodeURIComponent(id)}`, { method: 'PATCH', body: { parentId } })
+    await Promise.all([loadNoteChildren(node.parentId, true), loadNoteChildren(parentId, true)])
+    if (state.notes.selectedId === id) state.notes.selectedNode = await api(`notes/${encodeURIComponent(id)}`)
+    renderShell()
+    showToast('已移动到目标目录。')
+  } catch (error) { showToast(friendlyError(error), 'error') }
+}
+
+async function uploadNoteFiles(files, parentId) {
+  const summary = createNoteImportSummary()
+  const plans = files.flatMap(file => createNoteFilePlan(file, summary))
+  if (!plans.length) return showToast('没有可上传的文件，单文件上限为 64 MiB。', 'error')
+  const transfer = beginNoteTransfer('uploading')
+  if (!transfer) return
+  prepareNoteTransfer(transfer, summary)
+  try {
+    await importNotePlans(plans, parentId, transfer)
+    await loadNoteChildren(parentId, true)
+    renderShell()
+    completeNoteTransfer(transfer)
+    showNoteImportResult(summary)
+  } catch (error) {
+    if (transfer.completedItems) await loadNoteChildren(parentId, true).catch(() => {})
+    renderShell()
+    failNoteTransfer(transfer, error)
+    showToast(friendlyError(error), 'error')
+  }
+}
+
+async function importDroppedNotes(dataTransfer, parentId) {
+  const payload = captureNoteDropPayload(dataTransfer)
+  if (!payload.entries.length) return uploadNoteFiles(payload.files, parentId)
+  const transfer = beginNoteTransfer('scanning')
+  if (!transfer) return
+  const summary = createNoteImportSummary()
+  try {
+    const plans = []
+    for (const entry of payload.entries) {
+      const plan = await collectNoteEntry(entry, summary, transfer)
+      if (plan) plans.push(plan)
+    }
+    if (!plans.length) {
+      dismissNoteTransfer()
+      showToast('没有可上传的内容，单文件上限为 64 MiB。', 'error')
+      return
+    }
+    prepareNoteTransfer(transfer, summary)
+    await importNotePlans(plans, parentId, transfer)
+    await loadNoteChildren(parentId, true)
+    if (parentId) state.notes.expandedFolders.add(parentId)
+    renderShell()
+    completeNoteTransfer(transfer)
+    showNoteImportResult(summary)
+  } catch (error) {
+    await loadNoteChildren(parentId, true).catch(() => {})
+    renderShell()
+    failNoteTransfer(transfer, error)
+    showToast(friendlyError(error), 'error')
+  }
+}
+
+function createNoteImportSummary() {
+  return { files: 0, folders: 0, skipped: 0, bytes: 0 }
+}
+
+function createNoteFilePlan(file, summary) {
+  if (file.size > NOTE_MAX_FILE_SIZE) {
+    summary.skipped += 1
+    return []
+  }
+  summary.files += 1
+  summary.bytes += file.size
+  return [{ kind: 'file', name: file.name, file }]
+}
+
+function captureNoteDropPayload(dataTransfer) {
+  const files = Array.from(dataTransfer?.files || [])
+  const entries = Array.from(dataTransfer?.items || []).flatMap(item => {
+    if (item.kind !== 'file' || typeof item.webkitGetAsEntry !== 'function') return []
+    try {
+      const entry = item.webkitGetAsEntry()
+      return entry ? [entry] : []
+    } catch {
+      return []
+    }
+  })
+  return { entries, files }
+}
+
+async function collectNoteEntry(entry, summary, transfer) {
+  transfer.currentName = entry.name || ''
+  transfer.scannedItems += 1
+  scheduleNoteTransferSync()
+  if (entry.isDirectory) {
+    summary.folders += 1
+    const children = []
+    for (const child of await readNoteDirectoryEntries(entry)) {
+      const plan = await collectNoteEntry(child, summary, transfer)
+      if (plan) children.push(plan)
+    }
+    return { kind: 'folder', name: entry.name, children }
+  }
+  if (!entry.isFile) return null
+  const file = await readNoteFileEntry(entry)
+  return createNoteFilePlan(file, summary)[0] || null
+}
+
+async function importNotePlans(plans, parentId, transfer) {
+  for (const plan of plans) {
+    transfer.currentName = plan.name
+    scheduleNoteTransferSync()
+    if (plan.kind === 'folder') {
+      const folder = await api('notes/folders', { method: 'POST', body: { name: plan.name, parentId } })
+      transfer.completedItems += 1
+      scheduleNoteTransferSync()
+      await importNotePlans(plan.children, folder.id, transfer)
+      continue
+    }
+    const settledBytes = transfer.loadedBytes
+    await uploadNoteFile(plan.file, parentId, loaded => {
+      transfer.loadedBytes = settledBytes + Math.min(loaded, plan.file.size)
+      scheduleNoteTransferSync()
+    })
+    transfer.loadedBytes = settledBytes + plan.file.size
+    transfer.completedItems += 1
+    scheduleNoteTransferSync()
+  }
+}
+
+async function readNoteDirectoryEntries(entry) {
+  const reader = entry.createReader()
+  const entries = []
+  while (true) {
+    const batch = await new Promise((resolve, reject) => reader.readEntries(resolve, reject))
+    if (!batch.length) return entries
+    entries.push(...batch)
+  }
+}
+
+function readNoteFileEntry(entry) {
+  return new Promise((resolve, reject) => entry.file(resolve, reject))
+}
+
+async function uploadNoteFile(file, parentId, onProgress) {
+  const params = new URLSearchParams({ name: file.name })
+  if (parentId) params.set('parentId', parentId)
+  return binaryUploadRequest(`notes/files?${params}`, file, {
+    method: 'POST', contentType: file.type || 'application/octet-stream', onProgress,
+  })
+}
+
+function beginNoteTransfer(phase) {
+  if (state.notes.transfer && ['scanning', 'uploading'].includes(state.notes.transfer.phase)) {
+    showToast('已有导入任务正在进行，请稍候。', 'error')
+    return null
+  }
+  const transfer = {
+    id: String(++noteTransferSequence), phase, currentName: '', error: '',
+    scannedItems: 0, completedItems: 0, totalItems: 0,
+    loadedBytes: 0, totalBytes: 0, files: 0, folders: 0, skipped: 0,
+  }
+  state.notes.transfer = transfer
+  refreshNoteTransferPanel()
+  return transfer
+}
+
+function prepareNoteTransfer(transfer, summary) {
+  transfer.phase = 'uploading'
+  transfer.currentName = ''
+  transfer.totalItems = summary.files + summary.folders
+  transfer.totalBytes = summary.bytes
+  transfer.files = summary.files
+  transfer.folders = summary.folders
+  transfer.skipped = summary.skipped
+  scheduleNoteTransferSync()
+}
+
+function completeNoteTransfer(transfer) {
+  if (state.notes.transfer !== transfer) return
+  transfer.phase = 'complete'
+  transfer.currentName = ''
+  transfer.completedItems = transfer.totalItems
+  transfer.loadedBytes = transfer.totalBytes
+  refreshNoteTransferPanel()
+  window.setTimeout(() => {
+    if (state.notes.transfer === transfer && transfer.phase === 'complete') dismissNoteTransfer()
+  }, 2600)
+}
+
+function failNoteTransfer(transfer, error) {
+  if (state.notes.transfer !== transfer) return
+  transfer.phase = 'error'
+  transfer.error = friendlyError(error)
+  refreshNoteTransferPanel()
+}
+
+function dismissNoteTransfer() {
+  state.notes.transfer = null
+  document.querySelector('.notes-transfer')?.remove()
+}
+
+function refreshNoteTransferPanel() {
+  const current = document.querySelector('.notes-transfer')
+  const panel = renderNoteTransfer()
+  if (!panel) {
+    current?.remove()
+    return
+  }
+  if (current) current.replaceWith(panel)
+  else document.querySelector('.notes-workspace')?.append(panel)
+  syncNoteTransferPanel()
+}
+
+function scheduleNoteTransferSync() {
+  if (noteTransferFrame) return
+  noteTransferFrame = requestAnimationFrame(() => {
+    noteTransferFrame = 0
+    syncNoteTransferPanel()
+  })
+}
+
+function syncNoteTransferPanel() {
+  const transfer = state.notes.transfer
+  const panel = document.querySelector('.notes-transfer')
+  if (!transfer || !panel || panel.dataset.noteTransfer !== transfer.id) return
+  const percent = noteTransferPercent(transfer)
+  panel.dataset.state = transfer.phase
+  panel.style.setProperty('--notes-transfer-progress', String(percent / 100))
+  const title = panel.querySelector('.notes-transfer-title')
+  const detail = panel.querySelector('.notes-transfer-detail')
+  const count = panel.querySelector('.notes-transfer-count')
+  const percentLabel = panel.querySelector('.notes-transfer-percent')
+  const progress = panel.querySelector('.notes-transfer-track')
+  if (title) title.textContent = noteTransferTitle(transfer)
+  if (detail) {
+    detail.textContent = noteTransferDetail(transfer)
+    detail.title = transfer.currentName || ''
+  }
+  if (count) count.textContent = noteTransferCount(transfer)
+  if (percentLabel) percentLabel.textContent = transfer.phase === 'scanning' ? '正在整理' : `${percent}%`
+  if (progress) {
+    if (transfer.phase === 'scanning') progress.removeAttribute('aria-valuenow')
+    else progress.setAttribute('aria-valuenow', String(percent))
+  }
+}
+
+function noteTransferPercent(transfer) {
+  if (transfer.phase === 'complete') return 100
+  const value = transfer.totalBytes > 0
+    ? transfer.loadedBytes / transfer.totalBytes
+    : transfer.totalItems > 0 ? transfer.completedItems / transfer.totalItems : 0
+  return Math.min(transfer.phase === 'uploading' ? 99 : 100, Math.max(0, Math.round(value * 100)))
+}
+
+function noteTransferTitle(transfer) {
+  if (transfer.phase === 'scanning') return '正在整理导入内容'
+  if (transfer.phase === 'complete') return '导入完成'
+  if (transfer.phase === 'error') return '导入未完成'
+  return '正在导入笔记'
+}
+
+function noteTransferDetail(transfer) {
+  if (transfer.phase === 'error') return transfer.error || '导入过程中发生错误'
+  if (transfer.phase === 'complete') return `${transfer.files} 个文件、${transfer.folders} 个目录已写入`
+  if (transfer.phase === 'scanning') return transfer.currentName || '正在读取文件和目录…'
+  return transfer.currentName || '准备写入…'
+}
+
+function noteTransferCount(transfer) {
+  if (transfer.phase === 'scanning') return `已读取 ${transfer.scannedItems} 项`
+  const count = `${transfer.completedItems} / ${transfer.totalItems} 项`
+  const bytes = transfer.totalBytes ? ` · ${formatBytes(transfer.loadedBytes)} / ${formatBytes(transfer.totalBytes)}` : ''
+  const skipped = transfer.skipped ? ` · 跳过 ${transfer.skipped}` : ''
+  return `${count}${bytes}${skipped}`
+}
+
+function showNoteImportResult(summary) {
+  const added = [summary.folders ? `${summary.folders} 个目录` : '', summary.files ? `${summary.files} 个文件` : ''].filter(Boolean).join('、')
+  const skipped = summary.skipped ? `，跳过 ${summary.skipped} 个超过 64 MiB 的文件` : ''
+  showToast(`已添加${added ? ` ${added}` : ''}${skipped}。`)
+}
+
+async function saveNoteDocument() {
+  const node = state.notes.selectedNode
+  if (!node || !node.editable || !state.notes.dirty) return true
+  try {
+    const updated = await binaryRequest(`notes/${encodeURIComponent(node.id)}/content`, {
+      method: 'PUT', body: new Blob([state.notes.draft], { type: node.mediaType || 'text/plain' }), contentType: node.mediaType || 'text/plain',
+    })
+    state.notes.selectedNode = updated
+    state.notes.content = state.notes.draft
+    state.notes.dirty = false
+    await loadNoteChildren(node.parentId, true)
+    const size = document.querySelector('[data-note-info="size"] > span')
+    const updatedAt = document.querySelector('[data-note-info="updated"] > span')
+    if (size) size.textContent = formatBytes(updated.size)
+    if (updatedAt) updatedAt.textContent = formatDate(updated.updatedAt)
+    syncNoteEditorChrome()
+    showToast('文件已保存。')
+    return true
+  } catch (error) {
+    showToast(friendlyError(error), 'error')
+    return false
+  }
+}
+
+async function downloadNoteFile(node) {
+  try {
+    const blob = await binaryRequest(`notes/${encodeURIComponent(node.id)}/content?download=1`, { responseType: 'blob', accept: node.mediaType || 'application/octet-stream' })
+    const url = URL.createObjectURL(blob)
+    const anchor = element('a', { href: url, download: node.name })
+    document.body.append(anchor); anchor.click(); anchor.remove()
+    window.setTimeout(() => URL.revokeObjectURL(url), 1000)
+  } catch (error) { showToast(friendlyError(error), 'error') }
+}
+
+async function copyNoteReference(node) {
+  try { await navigator.clipboard.writeText(noteReference(node)); showToast('笔记引用已复制。') }
+  catch { showToast('复制失败，请手动复制文档编号。', 'error') }
+}
+
+async function confirmDeleteNoteNode(node) {
+  try {
+    const references = await api(`notes/${encodeURIComponent(node.id)}/references`)
+    if (references.length) {
+      const names = references.slice(0, 4).map(item => `“${item.documentTitle}”`).join('、')
+      return openModal({
+        title: '仍被知识文档引用', description: node.name,
+        body: element('p', {}, `${names}${references.length > 4 ? `等 ${references.length} 篇文档` : ''}仍在引用这里的内容。请先移除引用，再删除。`),
+        cancelLabel: '知道了',
+      })
+    }
+    openConfirm({
+      title: `删除“${node.name}”？`,
+      message: node.kind === 'folder' ? '目录及其全部子目录和文件会被永久删除。' : '该文档会被永久删除，此操作无法撤销。',
+      confirmLabel: '永久删除', danger: true,
+      onConfirm: async () => {
+        await api(`notes/${encodeURIComponent(node.id)}`, { method: 'DELETE' })
+        await loadNoteChildren(node.parentId, true)
+        if (state.notes.selectedId === node.id || state.notes.breadcrumbs.some(parent => parent.id === node.id)) clearNoteSelection()
+        renderShell(); showToast('已删除。')
+      },
+    })
+  } catch (error) { showToast(friendlyError(error), 'error') }
+}
+
+function noteWorkspaceDragEnter(event) {
+  if (!hasDragType(event, 'Files')) return
+  event.preventDefault()
+  if (event.dataTransfer) event.dataTransfer.dropEffect = 'copy'
+  event.currentTarget.dataset.dropActive = 'true'
+}
+
+function noteWorkspaceDragLeave(event) {
+  if (event.currentTarget.contains(event.relatedTarget)) return
+  clearNoteDragState()
+}
+
+function activateNoteFolderDropTarget(event, node) {
+  if (node.kind !== 'folder') return
+  const hasFiles = hasDragType(event, 'Files')
+  if (!hasFiles && !hasDragType(event, 'application/x-dsh-note-id')) return
+  event.preventDefault()
+  event.stopPropagation()
+  if (event.dataTransfer) event.dataTransfer.dropEffect = hasFiles ? 'copy' : 'move'
+  const workspace = document.querySelector('.notes-workspace')
+  if (workspace) workspace.dataset.dropActive = 'false'
+  document.querySelectorAll('.notes-tree-item[data-drop-target="true"]').forEach(target => {
+    if (target !== event.currentTarget) target.dataset.dropTarget = 'false'
+  })
+  event.currentTarget.dataset.dropTarget = 'true'
+}
+
+function hasDragType(event, type) {
+  return Array.from(event.dataTransfer?.types || []).includes(type)
+}
+
+function clearNoteDragState() {
+  const workspace = document.querySelector('.notes-workspace')
+  if (workspace) workspace.dataset.dropActive = 'false'
+  document.querySelectorAll('.notes-tree-item[data-drop-target="true"]').forEach(node => { node.dataset.dropTarget = 'false' })
+  document.querySelectorAll('.notes-tree-item[data-dragging="true"]').forEach(node => { node.dataset.dragging = 'false' })
+}
+
+function installNoteDragRecovery() {
+  window.addEventListener('drop', clearNoteDragState, true)
+  window.addEventListener('dragend', clearNoteDragState, true)
+  window.addEventListener('blur', clearNoteDragState)
+  document.addEventListener('dragleave', event => {
+    if (event.relatedTarget === null) clearNoteDragState()
+  }, true)
+}
+
+function noteReference(node) {
+  const label = node.name.replaceAll('\\', '\\\\').replaceAll('[', '\\[').replaceAll(']', '\\]')
+  return `@[${label}](note://${node.id})`
+}
+
+function noteMediaKind(node) {
+  if (node.kind === 'folder') return 'folder'
+  if (node.kind === 'document' || node.mediaType?.startsWith('text/')) return 'text'
+  if (node.mediaType?.startsWith('image/')) return 'image'
+  if (node.mediaType === 'application/pdf') return 'pdf'
+  return 'file'
+}
+
+function noteExtension(name) {
+  const extension = name.includes('.') ? name.split('.').pop() : 'FILE'
+  return extension.slice(0, 4).toLocaleUpperCase()
+}
+
+function shortNoteId(id) {
+  return `${id.slice(0, 11)}…${id.slice(-5)}`
+}
+
+function formatBytes(value) {
+  if (value < 1024) return `${value} B`
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(value < 10 * 1024 ? 1 : 0)} KiB`
+  return `${(value / 1024 / 1024).toFixed(value < 10 * 1024 * 1024 ? 1 : 0)} MiB`
+}
+
 function renderCandidates() {
   const statuses = [['pending', '待审核'], ['approved', '已通过'], ['rejected', '已拒绝']]
   return element('section', { 'aria-labelledby': 'candidates-heading' },
@@ -2184,7 +3755,7 @@ function openTokenCreator() {
     return { permission, input, node: element('label', { class: 'check-option' }, input, permission) }
   })
   const body = element('form', { class: 'form-grid' }, name.wrapper,
-    element('div', { class: 'field span-2' }, element('label', {}, '权限'), element('div', { class: 'check-grid' }, checkboxes.map(item => item.node)), element('span', { class: 'field-hint' }, '普通客户端建议只授予 read + propose。')))
+    element('div', { class: 'field span-2' }, element('label', {}, '权限'), element('div', { class: 'check-grid' }, checkboxes.map(item => item.node)), element('span', { class: 'field-hint' }, '普通客户端建议只授予 read + propose。write 是当前中央服务的全局写权限，同时允许直接写入、管理知识库、挂载和笔记；仅在确实需要时授予。')))
   name.wrapper.classList.add('span-2')
   openModal({ title: '创建客户端令牌', description: '原始令牌只会在创建成功后显示一次。', body, primaryLabel: '创建令牌', onPrimary: async () => {
     if (!body.reportValidity()) return false
@@ -2233,21 +3804,25 @@ function openSheet(options) {
   return openModal({ ...options, presentation: 'sheet' })
 }
 
-function openModal({ title, description = '', body, primaryLabel, primaryVariant = 'primary', onPrimary, cancelLabel = '取消', presentation = 'modal' }) {
+function openModal({ title, description = '', body, primaryLabel, primaryVariant = 'primary', onPrimary, cancelLabel = '取消', presentation = 'modal', onClose }) {
   const previouslyFocused = document.activeElement
   const isSheet = presentation === 'sheet'
   const backdrop = element('div', { class: `dialog-backdrop${isSheet ? ' sheet-backdrop' : ''}` })
   const dialog = element('section', { class: `dialog${isSheet ? ' sheet' : ''} ${primaryLabel ? '' : 'narrow'}`.trim(), role: 'dialog', 'aria-modal': 'true', 'aria-labelledby': 'dialog-title' })
   let busy = false
   let formDirty = false
+  let closed = false
   const close = (explicit = false) => {
-    if (busy) return
+    if (busy || closed) return
     if (!explicit && formDirty) {
       showToast('表单有未保存的修改，请先保存，或使用“取消”放弃修改。', 'error')
       return
     }
     document.removeEventListener('keydown', onKeyDown)
+    closed = true
     backdrop.remove()
+    refreshWorkspaceEffects()
+    onClose?.()
     if (previouslyFocused instanceof HTMLElement) previouslyFocused.focus()
   }
   const closeButton = actionButton('×', () => close(), 'ghost', { 'aria-label': '关闭对话框' })
@@ -2288,6 +3863,7 @@ function openModal({ title, description = '', body, primaryLabel, primaryVariant
     body.addEventListener('change', () => { formDirty = true })
   }
   document.body.append(backdrop)
+  refreshWorkspaceEffects(backdrop)
   document.addEventListener('keydown', onKeyDown)
   window.setTimeout(() => (dialog.querySelector('input, textarea, select, button') || dialog).focus(), 0)
   return { close, dialog }
@@ -2319,9 +3895,10 @@ function friendlyError(error) {
 
 window.addEventListener('beforeunload', event => {
   const editor = activeDocumentWorkspace()?.view.editor
-  if (!editor?.dirty) return
+  if (!editor?.dirty && !state.notes.dirty) return
   event.preventDefault()
   event.returnValue = ''
 })
 
+installNoteDragRecovery()
 void installHostThemeBridge().then(() => boot())