@allbluecn/web-app 0.19.2 → 0.19.4

package/src/components/hotkeys/shortcuts-panel.tsx

@@ -26,7 +26,8 @@ import {
 import { Button } from "@/components/ui/button"
 import { KeyboardMusic, X } from "lucide-react"
 import { ShortcutBadge } from "./shortcut-badge"
-import { HOTKEY_REGISTRY, CATEGORY_ORDER } from "@/lib/hotkeys/registry"
+import { HOTKEY_REGISTRY, CATEGORY_ORDER, HOTKEY_CATEGORY_LABEL_KEYS } from "@/lib/hotkeys/registry"
+import { t } from "@/lib/i18n/resolver"
 import { m } from "@/paraglide/messages.js";
 
 export function ShortcutsPanel() {
@@ -68,7 +69,7 @@ export function ShortcutsPanel() {
           {Array.from(grouped()).map(([category, shortcuts]) => (
             <div key={category}>
               <h4 className="mb-2 text-xs font-medium text-muted-foreground">
-                {category}
+                {t(HOTKEY_CATEGORY_LABEL_KEYS[category as keyof typeof HOTKEY_CATEGORY_LABEL_KEYS])}
               </h4>
               <div className="space-y-1.5">
                 {shortcuts.map((h) => (
@@ -76,7 +77,7 @@ export function ShortcutsPanel() {
                     key={h.id}
                     className="flex items-center justify-between rounded-md px-2 py-1.5 hover:bg-muted/50"
                   >
-                    <span className="text-sm">{h.description}</span>
+                    <span className="text-sm">{t(h.descriptionKey)}</span>
                     <ShortcutBadge keys={h.keys} />
                   </div>
                 ))}

package/src/components/iteration/auto-schedule-dialog.tsx

@@ -31,6 +31,7 @@ import { toast } from "@/components/ui/toast";
 import { useQuery } from "@tanstack/react-query";
 import { m } from "@/paraglide/messages.js";
 import { toastError } from "@/lib/toast-error";
+import { formatDateLocal } from "@/lib/datetime";
 
 interface AutoScheduleDialogProps {
   open: boolean;
@@ -41,7 +42,7 @@ interface AutoScheduleDialogProps {
 
 export function AutoScheduleDialog({ open, onOpenChange, projectId, onSaved }: AutoScheduleDialogProps) {
   const [enabled, setEnabled] = useState(false);
-  const [title, setTitle] = useState("迭代");
+  const [title, setTitle] = useState<string>(m.iterations_autoSchedule_defaultTitle());
   const [durationDays, setDurationDays] = useState(14);
   const [cooldownDays, setCooldownDays] = useState(0);
   const [startsOn, setStartsOn] = useState("");
@@ -66,15 +67,20 @@ export function AutoScheduleDialog({ open, onOpenChange, projectId, onSaved }: A
       setAutoRollover(data.config.autoRollover);
     } else if (open) {
       setEnabled(false);
-      setTitle("迭代");
+      setTitle(m.iterations_autoSchedule_defaultTitle());
       setDurationDays(14);
       setCooldownDays(0);
-      setStartsOn(new Date().toISOString().slice(0, 10));
+      // 本地时区「今天」（toISOString 用 UTC，UTC+8 早 8 点前会得到昨天）
+      setStartsOn(formatDateLocal(new Date()));
       setFutureCount(2);
       setAutoRollover(false);
     }
   }, [open, data]);
 
+  // 数字输入清空/非法时 Number("") === 0 / NaN，提交前按 min/max 收敛为合法整数
+  const clampInt = (v: number, min: number, max: number) =>
+    Math.min(max, Math.max(min, Math.floor(Number.isFinite(v) ? v : min)));
+
   async function handleSave() {
     setLoading(true);
     try {
@@ -83,10 +89,10 @@ export function AutoScheduleDialog({ open, onOpenChange, projectId, onSaved }: A
           projectId,
           enabled,
           title,
-          durationDays,
-          cooldownDays,
+          durationDays: clampInt(durationDays, 1, 90),
+          cooldownDays: clampInt(cooldownDays, 0, 30),
           startsOn,
-          futureCount,
+          futureCount: clampInt(futureCount, 1, 10),
           autoRollover,
         },
       });
@@ -94,7 +100,7 @@ export function AutoScheduleDialog({ open, onOpenChange, projectId, onSaved }: A
       onSaved?.();
       onOpenChange(false);
     } catch (e) {
-      toastError(e, "保存失败");
+      toastError(e, m.common_saveFailed());
     } finally {
       setLoading(false);
     }
@@ -142,7 +148,7 @@ export function AutoScheduleDialog({ open, onOpenChange, projectId, onSaved }: A
         </div>
         <DialogFooter>
           <Button variant="outline" onClick={() => onOpenChange(false)}>{m.iterations_actions_cancel()}</Button>
-          <Button onClick={() => void handleSave()} disabled={loading || !enabled}>{loading ? "保存中..." : m.iterations_actions_save()}</Button>
+          <Button onClick={() => void handleSave()} disabled={loading || !enabled}>{loading ? m.common_status_saving() : m.iterations_actions_save()}</Button>
         </DialogFooter>
       </DialogContent>
     </Dialog>

package/src/components/iteration/burndown-chart.tsx

@@ -14,7 +14,7 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
-import type { BurndownResult } from "@/server/serverFns/iteration/burndown-core";
+import type { BurndownResult } from "@/lib/iteration/burndown";
 import { m } from "@/paraglide/messages.js";
 
 export function BurndownChart({ data }: { data: BurndownResult & { timezone: string } }) {

package/src/components/iteration/create-iteration-dialog.tsx

@@ -87,7 +87,7 @@ export function CreateIterationDialog({ open, onOpenChange, projectId, editing,
       onOpenChange(false);
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
-      toastError(e, "操作失败");
+      toastError(e, m.common_operationFailed());
     } finally {
       setLoading(false);
     }
@@ -122,7 +122,7 @@ export function CreateIterationDialog({ open, onOpenChange, projectId, editing,
           <div className="space-y-2">
             <label className="text-sm font-medium leading-none">{m.iterations_fields_description()}</label>
             <Textarea
-              placeholder={m.iterations_fields_description()}
+              placeholder={m.iterations_fields_descriptionPlaceholder()}
               value={description}
               onChange={(e) => setDescription(e.target.value)}
               className="min-h-[80px]"

package/src/components/iteration/iteration-card.tsx

@@ -20,9 +20,11 @@ import { IterationStatusBadge } from "./iteration-status-badge";
 import { IterationProgressBar } from "./iteration-progress-bar";
 import type { IterationSummary } from "@/server/serverFns/iteration/schemas";
 import { m } from "@/paraglide/messages.js";
+import { formatDateLocal } from "@/lib/datetime";
 
 export function IterationCard({ item, projectId }: { item: IterationSummary; projectId: string }) {
-  const today = new Date().toISOString().slice(0, 10);
+  // 本地时区「今天」：toISOString 用 UTC，UTC+8 早 8 点前剩余天数会少算 1 天
+  const today = formatDateLocal(new Date());
   const remainingDays = Math.round((Date.parse(item.endDate) - Date.parse(today)) / 86400000);
   const isOverdue = remainingDays < 0 && item.status === "active";
 

package/src/components/iteration/iteration-editor.tsx

@@ -25,6 +25,7 @@ import { setStoryIterationFn } from "@/server/serverFns/iteration";
 import { toast } from "@/components/ui/toast";
 import type { IterationSummary } from "@/server/serverFns/iteration/schemas";
 import { m } from "@/paraglide/messages.js";
+import { toastError } from "@/lib/toast-error";
 
 interface IterationEditorProps {
   storyId: string;
@@ -40,7 +41,13 @@ export function IterationEditor({ storyId, current, options, onChanged }: Iterat
 
   async function executePick(id: string | null) {
     setPendingId(null);
-    await setStoryIterationFn({ data: { storyId, iterationId: id } });
+    try {
+      await setStoryIterationFn({ data: { storyId, iterationId: id } });
+    } catch (e) {
+      // 失败时 Popover 已关，必须提示否则用户误以为已切换
+      toastError(e, m.common_operationFailed());
+      return;
+    }
     const next = id ? joinable.find((i) => i.id === id) ?? null : null;
     toast.success(id && next ? m.iterations_editor_setSuccess({ name: next.name }) : m.iterations_editor_clearSuccess());
     onChanged(next ? { id: next.id, name: next.name } : null);
@@ -58,16 +65,23 @@ export function IterationEditor({ storyId, current, options, onChanged }: Iterat
   return (
     <>
       <Popover open={open} onOpenChange={setOpen}>
+        <div className="flex items-center">
         <PopoverTrigger render={<Button variant="ghost" size="sm" className="h-6 justify-start gap-1 px-1 text-xs font-normal" />}>
-            {current ? current.name : <span className="text-muted-foreground">{m.iterations_editor_placeholder()}</span>}
-            {current ? (
-              <X
-                className="ml-1 size-3 hover:text-destructive"
-                onClick={(e) => { e.stopPropagation(); void executePick(null); }}
-              />
-            ) : null}
-            <ChevronDown className="ml-auto size-3 text-muted-foreground" />
-          </PopoverTrigger>
+          {current ? current.name : <span className="text-muted-foreground">{m.iterations_editor_placeholder()}</span>}
+          <ChevronDown className="ml-auto size-3 text-muted-foreground" />
+        </PopoverTrigger>
+        {current ? (
+          <Button
+            variant="ghost"
+            size="icon"
+            aria-label={m.iterations_editor_clear()}
+            className="size-5 text-muted-foreground hover:text-destructive"
+            onClick={(e) => { e.stopPropagation(); void executePick(null); }}
+          >
+            <X className="size-3" />
+          </Button>
+        ) : null}
+      </div>
         <PopoverContent className="w-56 p-0" align="start">
           <Command>
             <CommandList>

package/src/components/kibo-ui/contribution-graph/index.tsx

@@ -245,14 +245,11 @@ const getMonthLabels = (
     .filter(({ weekIndex }, index, labels) => {
       const minWeeks = 3;
 
+      // 仅首标签有最小周距约束；其余恒保留（原「末项恒真 / 兜底恒真」死分支已删）
       if (index === 0) {
         return labels[1] && labels[1].weekIndex - weekIndex >= minWeeks;
       }
 
-      if (index === labels.length - 1) {
-        return true;
-      }
-
       return true;
     });
 };
@@ -360,6 +357,16 @@ export const ContributionGraphBlock = ({
     );
   }
 
+  // maxLevel > 4 时硬编码的 data-[level="0..4"] fill 类不命中（静默透明）：
+  // 超出档位按 20% 透明度阶梯内联兜底（Tailwind v4 JIT 不生成动态类名）
+  const overflowFillStyle =
+    activity.level > 4
+      ? {
+          fill: "var(--muted-foreground)",
+          fillOpacity: Math.min(1, activity.level * 0.2),
+        }
+      : undefined;
+
   return (
     <rect
       className={cn(
@@ -376,6 +383,7 @@ export const ContributionGraphBlock = ({
       height={blockSize}
       rx={blockRadius}
       ry={blockRadius}
+      style={overflowFillStyle}
       width={blockSize}
       x={(blockSize + blockMargin) * weekIndex}
       y={labelHeight + (blockSize + blockMargin) * dayIndex}
@@ -548,6 +556,14 @@ export const ContributionGraphLegend = ({
               height={blockSize}
               rx={blockRadius}
               ry={blockRadius}
+              style={
+                level > 4
+                  ? {
+                      fill: "var(--muted-foreground)",
+                      fillOpacity: Math.min(1, level * 0.2),
+                    }
+                  : undefined
+              }
               width={blockSize}
             />
           </svg>

package/src/components/knowledge/dialog/knowledge-form-dialog.tsx

@@ -30,6 +30,7 @@ import {
 import { LucideIconPicker } from "@/components/shared-kit/icons/lucide-icon-picker";
 import { createKnowledgeFn, updateKnowledgeFn } from "@/server/serverFns/knowledge";
 import { knowledgeFormSchema } from "../schemas/knowledge-form";
+import { standardSchemaValidator } from "@/lib/form/standard-schema-validator";
 import { m } from "@/paraglide/messages.js";
 import { emitEvent, AppEvents } from "@/lib/events";
 
@@ -52,7 +53,7 @@ export function KnowledgeFormDialog({ open, onOpenChange, kb, onSuccess }: Knowl
       description: kb?.description ?? "",
       icon: kb?.icon ?? "",
     },
-    validators: [{ run: knowledgeFormSchema as any, triggers: ['change'] }],
+    validators: [{ run: standardSchemaValidator(knowledgeFormSchema), triggers: ['change'] }],
   });
 
   const handleSubmit = async () => {
@@ -136,7 +137,7 @@ export function KnowledgeFormDialog({ open, onOpenChange, kb, onSuccess }: Knowl
                 onKeyDown={(e) => {
                   if (e.key === "Enter" && !e.shiftKey) {
                     e.preventDefault();
-                    handleSubmit();
+                    void handleSubmit();
                   }
                 }}
               />

package/src/components/knowledge/doc-properties.tsx

@@ -53,6 +53,7 @@ import {
   type LucideIcon,
 } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { toSafeHref } from '@/lib/safe-url'
 import { m } from "@/paraglide/messages.js";
 
 export type PropertyFieldType = 'text' | 'select' | 'date' | 'url' | 'tags'
@@ -164,8 +165,14 @@ function PropertyValueInput({ field, value, onChange, readOnly }: { field: Prope
       return <span className="text-sm">{Array.isArray(value) ? (value as string[]).join(', ') : (value as string) ?? ''}</span>
     }
     if (field.type === 'url') {
-      const url = (value as string) ?? ''
-      return url ? <a href={url} target="_blank" rel="noopener noreferrer" className="text-sm text-primary hover:underline">{url}</a> : null
+      const raw = (value as string) ?? ''
+      // 存储型 XSS 防线：javascript:/data: 等伪协议降级为纯文本展示
+      const safe = toSafeHref(raw)
+      return safe
+        ? <a href={safe} target="_blank" rel="noopener noreferrer" className="text-sm text-primary hover:underline">{raw}</a>
+        : raw
+          ? <span className="text-sm">{raw}</span>
+          : null
     }
     return <span className="text-sm">{(value as string) ?? ''}</span>
   }

package/src/components/knowledge/doc-type-meta.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import type { ComponentType } from 'react'
+import { FileText, Grid3X3, Network, Table } from 'lucide-react'
+import { m } from '@/paraglide/messages.js'
+
+/**
+ * 知识库文档类型元数据单一来源（审计 🔵：原 knowledge-tree.tsx 与
+ * knowledge-tree-item.tsx 各维护一份，新增类型需改两处）。
+ * label 为惰性消息函数引用，渲染处调用 `opt.label()`。
+ */
+
+export const DOC_TYPE_OPTIONS = [
+  { type: 'doc' as const, label: m.knowledge_treeType_doc, icon: FileText },
+  { type: 'mindmap' as const, label: m.knowledge_treeType_mindmap, icon: Network },
+  { type: 'sheet' as const, label: m.knowledge_treeType_sheet, icon: Table, disabled: true },
+  { type: 'table' as const, label: m.knowledge_treeType_table, icon: Grid3X3, disabled: true },
+]
+
+export const TYPE_DEFAULTS: Record<string, () => string> = {
+  doc: m.knowledge_untitledDoc,
+  mindmap: m.knowledge_untitledMindmap,
+  sheet: m.knowledge_untitledSheet,
+  table: m.knowledge_untitledTable,
+}
+
+export const TYPE_ICONS: Record<string, ComponentType<{ className?: string }>> = {
+  doc: FileText,
+  mindmap: Network,
+  sheet: Table,
+  table: Grid3X3,
+}

package/src/components/knowledge/editor/knowledge-doc-editor.tsx

@@ -30,6 +30,7 @@ import type { NotionEditorCollabExtensions } from '@/components/tiptap/notion-li
 import { useEditorWidth, type EditorWidth, EDITOR_WIDTH_MAX_WIDTH } from '@/components/knowledge/editor/editor-width-context'
 import { DOC_EDITOR_WIDTH_VARS } from './knowledge-doc-editor-vars'
 import { DocHeader } from '@/components/knowledge/editor/doc-header'
+import { useAutoSaveChannels } from '@/components/knowledge/editor/use-auto-save-channels'
 import { DocumentProperties, type PropertyField, type PropertyValues } from '@/components/knowledge/doc-properties'
 import type { NotionDocEditorProps, DocumentSuggestion } from '@/components/tiptap/notion-like'
 import type { MindmapDocEditorProps } from '@/components/knowledge/editor/mindmap-doc-editor'
@@ -99,6 +100,9 @@ interface KnowledgeDocEditorProps {
 
 export function KnowledgeDocEditor({ document, editorWidth = 'auto', kbName, propertyFields, propertyValues, onPropertyChange, addablePropertyFields, onAddProperty, onRemoveProperty, saveHandlers, readOnly, backButton, actions, collab, collabSnapshot, onEditorReady }: KnowledgeDocEditorProps) {
   if (document.type === 'mindmap') {
+    // 注意：mindmap 分支只支持 document/kbName——readOnly、saveHandlers、
+    // backButton、actions、属性面板等能力在此分支不生效（MindmapDocEditor
+    // 未实现），需要时先扩展 MindmapDocEditorProps 再在此透传。
     return <MindmapDocEditor document={document} kbName={kbName} />
   }
   const bodyProps = {
@@ -243,7 +247,6 @@ function CollabDocGate({ docId, snapshot, children }: CollabDocGateProps) {
 function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEnabled: boolean; collabState: CollabEditorRuntimeState }) {
   const { document, editorWidth = 'auto', kbName, propertyFields, propertyValues, onPropertyChange, addablePropertyFields, onAddProperty, onRemoveProperty, saveHandlers, readOnly, backButton, actions, onEditorReady, collabEnabled, collabState } = bodyProps
   const { docVersion, onDocTitleChanged } = useEditorWidth()
-  const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [displayTitle, setDisplayTitle] = useState(document.title)
   const [lastSavedAt, setLastSavedAt] = useState<Date | null>(
@@ -261,7 +264,7 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
   const collabActiveRef = useRef(collabState.collabActive)
   collabActiveRef.current = collabState.collabActive
 
-  // 降级/恢复切换语义：见下方 effect（依赖 debouncedSave，声明在其后）
+  // 降级/恢复切换语义：见下方 effect（依赖 triggerDebouncedSave，声明在其后）
   const prevCollabActiveRef = useRef(collabState.collabActive)
 
   const handleEditorReady = useCallback(
@@ -301,41 +304,30 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
     },
   }), [document.kbId])
 
-  const doSave = useCallback(async (content: { html: string; markdown: string }) => {
+  const { setDirty, triggerDebouncedSave } = useAutoSaveChannels<{ html: string; markdown: string }>({
+    getContent: () => latestContent.current,
     // 协同写手活跃时 DB 保存一律短路（Y 是唯一写手；降级期恢复前绝不双写）
-    if (collabActiveRef.current) return
-    setSaving(true)
-    try {
-      const saver = saveHandlers?.content ?? ((c: { html: string; markdown: string }) => updateDocumentFn({ data: { id: docId.current, content: c } }))
-      await saver(content)
-      setDirty(false)
-      setLastSavedAt(new Date())
-    } catch (e) {
-      console.error('Auto-save failed:', e instanceof Error ? e.message : String(e))
-    } finally {
-      setSaving(false)
-    }
-  }, [saveHandlers])
-
-  const doSaveRef = useRef(doSave)
-  doSaveRef.current = doSave
-
-  const dirtyRef = useRef(dirty)
-  dirtyRef.current = dirty
-
-  const debouncedSave = useDebouncedCallback(
-    () => {
-      const c = latestContent.current
-      if (c) doSaveRef.current(c)
+    guard: () => collabActiveRef.current,
+    save: async (content) => {
+      setSaving(true)
+      try {
+        const saver = saveHandlers?.content ?? ((c: { html: string; markdown: string }) => updateDocumentFn({ data: { id: docId.current, content: c } }))
+        await saver(content)
+        setDirty(false)
+        setLastSavedAt(new Date())
+      } catch (e) {
+        console.error('Auto-save failed:', e instanceof Error ? e.message : String(e))
+      } finally {
+        setSaving(false)
+      }
     },
-    { wait: EDITOR_AUTO_SAVE_MS },
-  )
+  })
 
   // 降级/恢复切换语义（核心不变式：任一时刻只有一条保存链路活跃）：
   //   切 offline 瞬间——把编辑器当前内容（含协同期 Y 独占、未落库的编辑）
   //   搬进 DB 保存链路的 latestContent 并置 dirty，同时武装 2s 防抖保存，
   //   旧链路由此接管；切回 collabActive 瞬间——清除 DB 保存意图（未到期的
-  //   debounced 保存到期时被 doSave 守卫短路），Y 继续增量同步，无内容丢失。
+  //   debounced 保存到期时被 guard 短路），Y 继续增量同步，无内容丢失。
   useEffect(() => {
     if (!collabEnabled) return
     if (prevCollabActiveRef.current === collabState.collabActive) return
@@ -350,13 +342,13 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
               ?.manager?.serialize?.(ed.getJSON()) ?? '',
         }
         setDirty(true)
-        debouncedSave()
+        triggerDebouncedSave()
       }
     } else {
       latestContent.current = null
       setDirty(false)
     }
-  }, [collabState.collabActive, collabEnabled, debouncedSave])
+  }, [collabState.collabActive, collabEnabled, setDirty, triggerDebouncedSave])
 
   const handleContentChange = useCallback(
     (content: { html: string; markdown: string }) => {
@@ -365,9 +357,9 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
       if (collabActiveRef.current) return
       latestContent.current = content
       setDirty(true)
-      debouncedSave()
+      triggerDebouncedSave()
     },
-    [readOnly, debouncedSave],
+    [readOnly, setDirty, triggerDebouncedSave],
   )
 
   const handleTitleChange = useCallback(async (newTitle: string) => {
@@ -416,33 +408,13 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
         setDisplayTitle(doc.title)
         setLastSavedAt(doc.updatedAt ? new Date(doc.updatedAt) : null)
       }
-    }).catch(() => {})
+    }).catch((e) => {
+      // 刷新失败时页面停留旧标题/旧保存时间，至少留日志可排查
+      console.error('Doc version refresh failed:', e instanceof Error ? e.message : String(e))
+    })
     return () => { cancelled = true }
   }, [docVersion])
 
-  useEffect(() => {
-    // 通道二守卫：协同态不启动轮询（降级恢复后 dirty 已清、interval 不再挂起）
-    if (!dirty || collabState.collabActive) return
-    const interval = setInterval(() => {
-      const c = latestContent.current
-      if (c) doSaveRef.current(c)
-    }, 5000)
-    return () => clearInterval(interval)
-  }, [dirty, collabState.collabActive])
-
-  useEffect(() => {
-    const handleBeforeUnload = () => {
-      // 通道三守卫：协同态 beforeunload 不写 DB（Y 已含全部编辑）
-      if (collabActiveRef.current) return
-      if (dirtyRef.current) {
-        const c = latestContent.current
-        if (c) doSaveRef.current(c)
-      }
-    }
-    window.addEventListener('beforeunload', handleBeforeUnload)
-    return () => window.removeEventListener('beforeunload', handleBeforeUnload)
-  }, [])
-
   const content: string | { html: string; markdown: string } = useMemo(() =>
     document.content && typeof document.content === 'object' && 'html' in document.content
       ? {

package/src/components/knowledge/editor/use-auto-save-channels.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import { useDebouncedCallback, EDITOR_AUTO_SAVE_MS } from "@/lib/pacer"
+
+/** 通道二轮询保存间隔（原两编辑器各自内联 5000 魔法数字） */
+export const EDITOR_POLL_SAVE_MS = 5000
+
+export interface AutoSaveChannelsOptions<T> {
+  /** 取最新待保存内容；null/undefined = 无内容可存 */
+  getContent: () => T | null | undefined
+  /** 执行保存（失败上报由调用方的 saver 自行负责，本 hook 不吞错） */
+  save: (content: T) => Promise<void> | void
+  /** 保存前短路守卫（如协同写手活跃时 DB 保存短路），返回 true 跳过 */
+  guard?: () => boolean
+  /** 通道一防抖等待 ms（默认 EDITOR_AUTO_SAVE_MS） */
+  debounceMs?: number
+  /** 通道二轮询间隔 ms（默认 EDITOR_POLL_SAVE_MS） */
+  pollMs?: number
+}
+
+/**
+ * 单机文档「三通道自动保存」共用状态机：2s 防抖（通道一）/ 5s 轮询兜底
+ * （通道二）/ beforeunload 尽力保存（通道三）。
+ *
+ * knowledge-doc-editor 与 mindmap-doc-editor 消费（审计 🔵：原两处同构
+ * 实现，修 beforeunload/轮询行为需改两处）。dirty 状态由本 hook 持有，
+ * 调用方经返回的 setDirty 标记/清除。
+ *
+ * 已知边界（接受窗口）：通道三是 async RPC，页面卸载时请求可能被浏览器
+ * 中止，最后 debounce 窗口内的编辑可能丢失；sendBeacon 不适用带鉴权
+ * header 的 serverFn RPC，维持现状。
+ */
+export function useAutoSaveChannels<T>(opts: AutoSaveChannelsOptions<T>) {
+  const [dirty, setDirty] = useState(false)
+  const dirtyRef = useRef(dirty)
+  dirtyRef.current = dirty
+  const saveRef = useRef(opts.save)
+  saveRef.current = opts.save
+  const getContentRef = useRef(opts.getContent)
+  getContentRef.current = opts.getContent
+  const guardRef = useRef(opts.guard)
+  guardRef.current = opts.guard
+
+  const saveIfContent = useCallback(async () => {
+    if (guardRef.current?.()) return
+    const c = getContentRef.current()
+    if (c != null) await saveRef.current(c)
+  }, [])
+
+  // 通道一：编辑变更后防抖保存
+  const triggerDebouncedSave = useDebouncedCallback(
+    () => {
+      void saveIfContent()
+    },
+    { wait: opts.debounceMs ?? EDITOR_AUTO_SAVE_MS },
+  )
+
+  // 通道二：dirty 期间轮询兜底（编辑器事件丢失/防抖未触发的场景）
+  useEffect(() => {
+    if (!dirty) return
+    const interval = setInterval(() => {
+      void saveIfContent()
+    }, opts.pollMs ?? EDITOR_POLL_SAVE_MS)
+    return () => clearInterval(interval)
+  }, [dirty, opts.pollMs, saveIfContent])
+
+  // 通道三：卸载前尽力保存
+  useEffect(() => {
+    const handleBeforeUnload = () => {
+      void saveIfContent()
+    }
+    window.addEventListener("beforeunload", handleBeforeUnload)
+    return () => window.removeEventListener("beforeunload", handleBeforeUnload)
+  }, [saveIfContent])
+
+  return { dirty, setDirty, triggerDebouncedSave }
+}

package/src/components/knowledge/knowledge-homepage.tsx

@@ -16,10 +16,9 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useEffect, useState } from 'react'
-import { FileText, Clock } from 'lucide-react'
+import { Dot, FileText, Clock } from 'lucide-react'
 import { Link } from '@tanstack/react-router'
 import { listDocumentsFn } from '@/server/serverFns/knowledge'
-import { Dot } from 'lucide-react'
 import { formatDate } from '@/lib/datetime'
 import { useTimezone } from '@/providers/timezone-provider'
 import { m } from "@/paraglide/messages.js";
@@ -34,7 +33,16 @@ export function KnowledgeHomepage({ kb, homepage }: HomepageProps) {
   const timezone = useTimezone()
 
   useEffect(() => {
-    listDocumentsFn({ data: { kbId: kb.id } }).then((docs) => setDocuments(docs))
+    let cancelled = false
+    listDocumentsFn({ data: { kbId: kb.id } })
+      .then((docs) => {
+        if (!cancelled) setDocuments(docs)
+      })
+      .catch((e) => {
+        // 加载失败不覆盖已有数据，留日志可排查
+        console.error('Homepage documents load failed:', e instanceof Error ? e.message : String(e))
+      })
+    return () => { cancelled = true }
   }, [kb.id])
 
   const recentDocs = documents