@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/harness/harness-workbench-page.tsx

@@ -36,7 +36,7 @@ import { Button } from '@/components/ui/button'
 import { ConfirmDialog } from '@/components/confirm-dialog';
 import { useSession } from '@/lib/auth/auth-client'
 import { listConversationsFn, createConversationFn, updateConversationFn, deleteConversationFn, forkConversationFn } from '@/server/serverFns/chat/conversations'
-import { listAgentsFn } from '@/server/serverFns/agents/agent-crud'
+import { agentsQueryOptions } from '@/lib/queries/agents'
 import { useSelectedModel } from '@/lib/ai/use-selected-model'
 import { useSearchCapability } from '@/lib/ai/use-search-capability'
 import { useCodeModeReadiness } from '@/lib/ai/use-code-mode-readiness'
@@ -109,8 +109,7 @@ export default function HarnessWorkbenchPage({ initialThreadId, initialMessages
   const { workspace } = useWorkspace()
 
   const { data: agents } = useQuery({
-    queryKey: ['agents'],
-    queryFn: () => listAgentsFn(),
+    ...agentsQueryOptions(),
     staleTime: 30_000,
     enabled: initialThreadId == null,
   })

package/src/components/harness/message-actions.tsx

@@ -23,7 +23,7 @@ import {
   RotateCcw,
 } from "lucide-react";
 import { useCallback, useRef, useState } from "react";
-import { useHotkey } from "@tanstack/react-hotkeys";
+import { useAppHotkeys, useHotkey } from "@tanstack/react-hotkeys";
 import { Button } from "@/components/ui/button";
 import {
   DropdownMenu,
@@ -52,10 +52,12 @@ export function MessageActions({
 }: MessageActionsProps) {
   const [isOpen, setIsOpen] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
-  useHotkey("Escape", () => setIsOpen(false), {
+  // 声明即绑定：close-panel / copy-message 条目单一来源（lib/hotkeys/registry.ts）
+  const hk = useAppHotkeys();
+  useHotkey(hk["close-panel"], () => setIsOpen(false), {
     enabled: isOpen,
   });
-  useHotkey("Mod+C", () => {
+  useHotkey(hk["copy-message"], () => {
     onCopy();
     setIsOpen(false);
   }, {

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

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useCallback, useState } from "react"
-import { useHotkey } from "@tanstack/react-hotkeys"
+import { useAppHotkeyList, useAppHotkeys, useHotkey } from "@tanstack/react-hotkeys"
 import {
   Dialog,
   DialogContent,
@@ -26,27 +26,38 @@ import {
 import { Button } from "@/components/ui/button"
 import { KeyboardMusic, X } from "lucide-react"
 import { ShortcutBadge } from "./shortcut-badge"
-import { HOTKEY_REGISTRY, CATEGORY_ORDER, HOTKEY_CATEGORY_LABEL_KEYS } from "@/lib/hotkeys/registry"
+import {
+  formatAppHotkeyForBadge,
+  CATEGORY_ORDER,
+  HOTKEY_CATEGORY_LABEL_KEYS,
+} from "@/lib/hotkeys/registry"
+import type { HotkeyCategory } from "@/lib/hotkeys/types"
 import { t } from "@/lib/i18n/resolver"
 import { m } from "@/paraglide/messages.js";
 
 export function ShortcutsPanel() {
   const [open, setOpen] = useState(false)
 
-  useHotkey("Mod+/", () => setOpen((prev) => !prev), {
+  const hk = useAppHotkeys()
+  useHotkey(hk["shortcuts-panel"], () => setOpen((prev) => !prev), {
     ignoreInputs: false,
   })
 
+  // 官方 useAppHotkeyList：声明顺序返回全部应用热键（含未挂载绑定的 inactive 条目）
+  const items = useAppHotkeyList()
+
   const grouped = useCallback(() => {
-    const map = new Map<string, (typeof HOTKEY_REGISTRY)[0][]>()
+    const map = new Map<HotkeyCategory, typeof items>()
     for (const category of CATEGORY_ORDER) {
-      const items = HOTKEY_REGISTRY.filter((h) => h.category === category)
-      if (items.length > 0) {
-        map.set(category, items)
+      const inCategory = items.filter(
+        ({ appHotkey }) => appHotkey.meta?.category === category,
+      )
+      if (inCategory.length > 0) {
+        map.set(category, inCategory)
       }
     }
     return map
-  }, [])
+  }, [items])
 
   return (
     <Dialog open={open} onOpenChange={setOpen}>
@@ -69,16 +80,20 @@ export function ShortcutsPanel() {
           {Array.from(grouped()).map(([category, shortcuts]) => (
             <div key={category}>
               <h4 className="mb-2 text-xs font-medium text-muted-foreground">
-                {t(HOTKEY_CATEGORY_LABEL_KEYS[category as keyof typeof HOTKEY_CATEGORY_LABEL_KEYS])}
+                {t(HOTKEY_CATEGORY_LABEL_KEYS[category])}
               </h4>
               <div className="space-y-1.5">
-                {shortcuts.map((h) => (
+                {shortcuts.map(({ appHotkey }) => (
                   <div
-                    key={h.id}
+                    key={appHotkey.id}
                     className="flex items-center justify-between rounded-md px-2 py-1.5 hover:bg-muted/50"
                   >
-                    <span className="text-sm">{t(h.descriptionKey)}</span>
-                    <ShortcutBadge keys={h.keys} />
+                    <span className="text-sm">
+                      {appHotkey.meta?.descriptionKey
+                        ? t(appHotkey.meta.descriptionKey)
+                        : ""}
+                    </span>
+                    <ShortcutBadge keys={formatAppHotkeyForBadge(appHotkey.hotkey)} />
                   </div>
                 ))}
               </div>

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

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+// 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 { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { BurndownChart } from "../burndown-chart";
+import type { BurndownResult } from "@/lib/iteration/burndown";
+
+// leading：末点 pending < ideal（与 computeBurndown 的状态判定语义一致）
+const leadingData: BurndownResult & { timezone: string } = {
+  timezone: "Asia/Shanghai",
+  status: "leading",
+  points: [
+    { date: "2026-01-01", scope: 10, pending: 10, ideal: 10 },
+    { date: "2026-01-02", scope: 10, pending: 6, ideal: 7 },
+    { date: "2026-01-03", scope: 11, pending: 3, ideal: 4 },
+  ],
+};
+
+const trailingData: BurndownResult & { timezone: string } = {
+  ...leadingData,
+  status: "trailing",
+  points: [
+    { date: "2026-02-01", scope: 10, pending: 10, ideal: 10 },
+    { date: "2026-02-02", scope: 10, pending: 9, ideal: 7 },
+    { date: "2026-02-03", scope: 11, pending: 8, ideal: 4 },
+  ],
+};
+
+function chartSvg(container: HTMLElement): SVGSVGElement {
+  const svg = container.querySelector("svg.ts-chart");
+  expect(svg).not.toBeNull();
+  return svg as SVGSVGElement;
+}
+
+describe("BurndownChart 数据→图形", () => {
+  it("无数据点时渲染空态且不出 SVG", () => {
+    const { container } = render(
+      <BurndownChart data={{ ...leadingData, points: [] }} />,
+    );
+    expect(screen.getByText("暂无数据，添加需求后生成")).toBeInTheDocument();
+    expect(container.querySelector("svg")).toBeNull();
+  });
+
+  it("按数据点绘制图形：5 条网格线 + 双折线 + 面积 + 每点一个圆点", () => {
+    const { container } = render(<BurndownChart data={leadingData} />);
+    const svg = chartSvg(container);
+    // 无障碍：图表 svg 以标题文案作为 aria-label
+    expect(svg.getAttribute("aria-label")).toBe("燃尽图");
+
+    // ruleY 网格线：0/25%/50%/75%/100% 五条水平线，全宽
+    const rules = svg.querySelectorAll("g.ts-chart__rule-y line");
+    expect(rules).toHaveLength(5);
+    const ruleYs = Array.from(rules).map((l) => Number(l.getAttribute("y1")));
+    expect([...ruleYs].sort((a, b) => a - b)).toEqual([16, 58, 100, 142, 184]);
+
+    // ideal 线：虚线、muted-foreground
+    const idealPath = svg.querySelector('path[stroke="var(--muted-foreground)"]');
+    expect(idealPath).not.toBeNull();
+    expect(idealPath!.getAttribute("stroke-dasharray")).toBe("4 3");
+    expect(idealPath!.getAttribute("stroke-width")).toBe("1.5");
+
+    // pending 线：实线、primary、宽 2
+    const pendingPath = svg.querySelector('path[stroke="var(--primary)"]:not([stroke-dasharray])');
+    expect(pendingPath).not.toBeNull();
+    expect(pendingPath!.getAttribute("stroke-width")).toBe("2");
+
+    // 面积：pending 与 ideal 之间的多边形，leading 为绿色 15% 透明度
+    const areaPath = svg.querySelector("g.ts-chart__area path");
+    expect(areaPath).not.toBeNull();
+    expect(areaPath!.getAttribute("fill")).toBe("var(--color-green-600)");
+    expect(areaPath!.getAttribute("fill-opacity")).toBe("0.15");
+    // 面积路径几何闭合（Z 收尾）且覆盖两个数据系列
+    expect(areaPath!.getAttribute("d")).toMatch(/Z$/);
+
+    // 圆点：每个 pending 数据点一个，r=2.5、primary 填充
+    const dots = svg.querySelectorAll("g.ts-chart__dot circle");
+    expect(dots).toHaveLength(leadingData.points.length);
+    for (const dot of dots) {
+      expect(dot.getAttribute("fill")).toBe("var(--primary)");
+      expect(Number(dot.getAttribute("r"))).toBe(2.5);
+    }
+  });
+
+  it("trailing 状态面积切换为红色", () => {
+    const { container } = render(<BurndownChart data={trailingData} />);
+    const areaPath = chartSvg(container).querySelector("g.ts-chart__area path");
+    expect(areaPath!.getAttribute("fill")).toBe("var(--color-red-600)");
+  });
+
+  it("首尾日期标注渲染为文本", () => {
+    render(<BurndownChart data={leadingData} />);
+    expect(screen.getByText("2026-01-01")).toBeInTheDocument();
+    expect(screen.getByText("2026-01-03")).toBeInTheDocument();
+  });
+
+  it("状态文案随 status 切换（领先/滞后）", () => {
+    const { unmount } = render(<BurndownChart data={leadingData} />);
+    expect(screen.getByText("领先")).toBeInTheDocument();
+    unmount();
+    render(<BurndownChart data={trailingData} />);
+    expect(screen.getByText("滞后")).toBeInTheDocument();
+  });
+});

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

@@ -14,21 +14,62 @@
 //
 // 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 { areaY, defineChart, dot, lineY, ruleY } from "@tanstack/charts";
+import { scaleLinear } from "@tanstack/charts/scales/linear";
+import { scalePoint } from "@tanstack/charts/scales/point";
+import { tooltip } from "@tanstack/charts/tooltip";
+import { Chart } from "@tanstack/charts/react";
+import { useMemo } from "react";
 import type { BurndownResult } from "@/lib/iteration/burndown";
 import { m } from "@/paraglide/messages.js";
 
 export function BurndownChart({ data }: { data: BurndownResult & { timezone: string } }) {
+  const leading = data.status === "leading";
+  const definition = useMemo(() => {
+    const points = data.points;
+    const maxVal = Math.max(1, ...points.map((p) => Math.max(p.scope, p.pending, p.ideal)));
+    return defineChart({
+      // 原手写 SVG 无坐标轴刻度，仅 5 条横向网格线，故整体关闭 guides 由 ruleY 复刻
+      guides: false,
+      margin: 16,
+      marks: [
+        ruleY([0, maxVal / 4, maxVal / 2, (maxVal * 3) / 4, maxVal], {
+          stroke: "var(--border)",
+          strokeWidth: 1,
+          strokeOpacity: 1,
+        }),
+        areaY(points, {
+          x: "date",
+          y1: "ideal",
+          y2: "pending",
+          // --color-green-600/--color-red-600 由头部状态文案的 text-* 工具类保活
+          //（Tailwind v4 会 tree-shake 未被引用的调色板变量）
+          fill: leading ? "var(--color-green-600)" : "var(--color-red-600)",
+          fillOpacity: 0.15,
+        }),
+        lineY(points, {
+          x: "date",
+          y: "ideal",
+          stroke: "var(--muted-foreground)",
+          strokeWidth: 1.5,
+          strokeDasharray: "4 3",
+        }),
+        lineY(points, { x: "date", y: "pending", stroke: "var(--primary)", strokeWidth: 2 }),
+        dot(points, { x: "date", y: "pending", r: 2.5, fill: "var(--primary)" }),
+      ],
+      scales: {
+        x: { scale: () => scalePoint<string>().padding(0) },
+        y: { scale: scaleLinear().domain([0, maxVal]) },
+      },
+      svgAnimation: true,
+      tooltip,
+    });
+  }, [data.points, leading]);
   if (data.points.length === 0) {
     return <div className="flex h-48 items-center justify-center text-xs text-muted-foreground">{m.iterations_burndown_noData()}</div>;
   }
-  const W = 640, H = 200, PAD = 28;
-  const maxVal = Math.max(1, ...data.points.map((p) => Math.max(p.scope, p.pending, p.ideal)));
-  const x = (i: number) => PAD + (i * (W - PAD * 2)) / Math.max(1, data.points.length - 1);
-  const y = (v: number) => H - PAD - (v * (H - PAD * 2)) / maxVal;
-  const line = (key: "pending" | "ideal") => data.points.map((p, i) => `${i === 0 ? "M" : "L"}${x(i)},${y(p[key])}`).join(" ");
-  const fill = data.points.map((p, i) => `${i === 0 ? "M" : "L"}${x(i)},${y(p.pending)}`).join(" ")
-    + " " + [...data.points].reverse().map((p, i) => `L${x(data.points.length - 1 - i)},${y(p.ideal)}`).join(" ");
-  const leading = data.status === "leading";
+  const first = data.points[0];
+  const last = data.points.at(-1)!;
   return (
     <div className="space-y-2">
       <div className="flex items-center justify-between text-xs">
@@ -37,21 +78,11 @@ export function BurndownChart({ data }: { data: BurndownResult & { timezone: str
           {leading ? m.iterations_burndown_leading() : data.status === "trailing" ? m.iterations_burndown_trailing() : m.iterations_burndown_pending()}
         </span>
       </div>
-      <svg viewBox={`0 0 ${W} ${H}`} className="w-full" role="img">
-        {[0, 0.25, 0.5, 0.75, 1].map((r) => (
-          <line key={r} x1={PAD} x2={W - PAD} y1={y(maxVal * r)} y2={y(maxVal * r)} className="stroke-border" strokeWidth={1} />
-        ))}
-        <path d={fill} className={leading ? "fill-green-500/15" : "fill-red-500/15"} />
-        <path d={line("ideal")} className="stroke-muted-foreground" strokeWidth={1.5} strokeDasharray="4 3" fill="none" />
-        <path d={line("pending")} className="stroke-primary" strokeWidth={2} fill="none" />
-        {data.points.map((p, i) => (
-          <circle key={p.date} cx={x(i)} cy={y(p.pending)} r={2.5} className="fill-primary">
-            <title>{`${p.date}: ${p.pending}`}</title>
-          </circle>
-        ))}
-        <text x={PAD} y={H - 8} className="fill-muted-foreground text-[10px]">{data.points[0].date}</text>
-        <text x={W - PAD} y={H - 8} textAnchor="end" className="fill-muted-foreground text-[10px]">{data.points.at(-1)!.date}</text>
-      </svg>
+      <Chart definition={definition} height={200} ariaLabel={m.iterations_burndown_title()} />
+      <div className="flex justify-between text-xs text-muted-foreground">
+        <span>{first.date}</span>
+        <span>{last.date}</span>
+      </div>
       <div className="flex gap-4 text-xs text-muted-foreground">
         <span className="flex items-center gap-1"><span className="inline-block h-0.5 w-4 bg-primary" />{m.iterations_burndown_pending()}</span>
         <span className="flex items-center gap-1"><span className="inline-block h-0.5 w-4 bg-muted-foreground" style={{ backgroundImage: "linear-gradient(90deg, currentColor 50%, transparent 50%)", backgroundSize: "4px 2px" }} />{m.iterations_burndown_ideal()}</span>

package/src/components/knowledge/editor/__tests__/knowledge-doc-editor-collab.test.tsx

@@ -108,6 +108,31 @@ vi.mock('@/components/shared-kit/auth/auth-client', () => ({
   useSession: mocks.useSession,
 }))
 
+// KnowledgeDocEditor 挂载 use-unsaved-guard（任务 2）：无 RouterProvider 的
+// 单测环境把 useBlocker 替换为 idle resolver（真实 blocker 注册属 router
+// 集成行为，见 hooks/__tests__/use-unsaved-guard.test.tsx）；opts 捕获槽供
+// dirty 信号回归测试直接驱动 shouldBlockFn
+const blockerCapture = vi.hoisted(() => ({
+  opts: null as null | {
+    shouldBlockFn: (args: unknown) => boolean | Promise<boolean>
+    enableBeforeUnload: boolean | (() => boolean)
+  },
+}))
+vi.mock('@tanstack/react-router', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useBlocker: (opts: NonNullable<typeof blockerCapture.opts>) => {
+    blockerCapture.opts = opts
+    return {
+      status: 'idle' as const,
+      current: undefined,
+      next: undefined,
+      action: undefined,
+      proceed: undefined,
+      reset: undefined,
+    }
+  },
+}))
+
 // 预热 lazy 的 NotionDocEditor 动态 import（模块图大，渲染前先解析完）
 const notionLikeReady = import('@/components/tiptap/notion-like')
 
@@ -540,3 +565,74 @@ function bannerText(testId: string): string | null {
 }
 const screenBannerText = () => bannerText('collab-offline-banner')
 const connectingBannerText = () => bannerText('collab-connecting-banner')
+
+// ---------------------------------------------------------------------------
+// 未保存拦截 dirty 信号（任务 2 审查修复回归）
+//   ① NotionLikeEditor onChange 经 EDITOR_CHANGE_DEBOUNCE_MS=500 防抖才通知
+//     父级 setDirty——最后一次击键后 500ms 内导航 guard 读到 false，内容静默
+//     丢失。修复：击键同步置位 pendingChangeRef，guard 读「同步 ref || dirty」。
+//   ② 文档刚打开时 UniqueID onCreate 的初始化 ID 归一化触发一次 onChange →
+//     setDirty(true)，init 保存（~2.5s）完成前导航误弹「未保存」。修复：
+//     无同步击键信号的 init 批次免 dirty（防抖保存照常，ID 持久化保留）。
+// ---------------------------------------------------------------------------
+
+describe('未保存拦截 dirty 信号（审查修复回归）', () => {
+  const SHOULD_BLOCK_ARGS = { action: 'PUSH', current: {}, next: {} }
+
+  it('① 击键后 500ms onChange 防抖窗口内导航必须 blocked（同步置位），落库完成后归零', async () => {
+    const { editor } = await renderUntilEditorReady({ collab: false })
+    expect(editor).not.toBeNull()
+    // init 批次已随 ready 轮询处理完（无击键不拦——② 的断言前提）
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+
+    await insertText(editor!, 'X')
+    // 关键断言：onChange 500ms 防抖尚未到期，guard 已须拦截（同步置位）
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(true)
+
+    // 防抖落库完成后归零（保存成功清 dirty + 同步 ref，无缝衔接）
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500)
+      await vi.advanceTimersByTimeAsync(2000)
+      await Promise.resolve()
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalled()
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+  })
+
+  it('② 打开后 init 归一化（UniqueID）保存完成前导航必须不 blocked', async () => {
+    const { editor } = await renderUntilEditorReady({ collab: false })
+    expect(editor).not.toBeNull()
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+    // init onChange 交付（500ms 防抖到期）→ init 保存（2s 防抖）完成前：
+    // 纯 init 批次免 dirty，guard 不拦（修复前此处 dirty=true 误拦——审查②）
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500)
+      await Promise.resolve()
+    })
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+    // init 防抖保存照常落库（ID 持久化行为保留），期间仍不拦
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2000)
+      await Promise.resolve()
+    })
+    expect(mockUpdateDocumentFn).toHaveBeenCalled()
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+  })
+
+  it('④ 降级期击键（未落库）→ 恢复协同：pendingChangeRef 归零，guard 不 dirty', async () => {
+    // offline 降级：DB 链路接管，击键同步置位 pendingChangeRef（collabActive=false）
+    fakeProvider = buildFakeProvider('offline')
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null })
+    expect(editor).not.toBeNull()
+
+    await insertText(editor!, '降级期编辑')
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(true)
+
+    // 2s 防抖保存到期前恢复协同（审查④：恢复分支漏归零 → 该实例存活期
+    // guard 恒 dirty——协同态保存被 guard 短路，唯一归零点永不执行）
+    await act(async () => {
+      fakeProvider!.__setStatus('synced')
+    })
+    expect(blockerCapture.opts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+  })
+})

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

@@ -31,6 +31,7 @@ import { useEditorWidth, type EditorWidth, EDITOR_WIDTH_MAX_WIDTH } from '@/comp
 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 { useUnsavedGuard } from '@/hooks/use-unsaved-guard'
 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'
@@ -304,7 +305,7 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
     },
   }), [document.kbId])
 
-  const { setDirty, triggerDebouncedSave } = useAutoSaveChannels<{ html: string; markdown: string }>({
+  const { dirty, setDirty, triggerDebouncedSave, saveIfContent } = useAutoSaveChannels<{ html: string; markdown: string }>({
     getContent: () => latestContent.current,
     // 协同写手活跃时 DB 保存一律短路（Y 是唯一写手；降级期恢复前绝不双写）
     guard: () => collabActiveRef.current,
@@ -314,6 +315,8 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
         const saver = saveHandlers?.content ?? ((c: { html: string; markdown: string }) => updateDocumentFn({ data: { id: docId.current, content: c } }))
         await saver(content)
         setDirty(false)
+        // 同步击键信号与 dirty 同点归零（任务 2 审查修复①）：无接缝盲区
+        pendingChangeRef.current = false
         setLastSavedAt(new Date())
       } catch (e) {
         console.error('Auto-save failed:', e instanceof Error ? e.message : String(e))
@@ -323,6 +326,38 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
     },
   })
 
+  // ── 未保存拦截 dirty 信号（任务 2 审查修复①②）──────────────────────
+  // pendingChangeRef：击键同步置位（NotionDocEditor.onDirtySignal，先于
+  //   500ms onChange 防抖），保存成功时与 dirty 同点归零——消灭「最后一次
+  //   击键后 500ms 内导航不拦」的数据丢失窗口。协同态不置位（Y 是唯一写手）。
+  // sawFirstChangeRef：挂载后首个 onChange 若无同步击键信号，即 UniqueID
+  //   初始化 ID 归一化批次（appendTransaction 插件事务，非用户编辑）——照常
+  //   刷新 latestContent 并武装防抖保存（ID 持久化行为不变），但不置 dirty，
+  //   init 保存 settle 前 guard 保持 clean（审查修复②：打开即误拦）。
+  const pendingChangeRef = useRef(false)
+  const sawFirstChangeRef = useRef(false)
+
+  // SPA 导航未保存拦截（任务 2）：dirty 时弹 AlertDialog，「离开」先 flush
+  // 尽力保存（saveIfContent）再放行——比现状（SPA 导航静默丢防抖窗口内容）
+  // 更安全；浏览器关闭/刷新的通道三尽力保存仍由 useAutoSaveChannels 保留
+  const unsavedGuard = useUnsavedGuard({
+    isDirty: () => pendingChangeRef.current || dirty,
+    onSaveAndLeave: () => {
+      // flush 前从编辑器实例取回防抖窗口内未交付的最新内容（可能含
+      // <500ms 击键），否则「离开」保存的是 stale latestContent
+      const ed = editorRef.current
+      if (ed && !ed.isDestroyed) {
+        latestContent.current = {
+          html: ed.getHTML(),
+          markdown:
+            (ed.storage.markdown as { manager?: { serialize?: (json: unknown) => string } } | undefined)
+              ?.manager?.serialize?.(ed.getJSON()) ?? '',
+        }
+      }
+      return saveIfContent()
+    },
+  })
+
   // 降级/恢复切换语义（核心不变式：任一时刻只有一条保存链路活跃）：
   //   切 offline 瞬间——把编辑器当前内容（含协同期 Y 独占、未落库的编辑）
   //   搬进 DB 保存链路的 latestContent 并置 dirty，同时武装 2s 防抖保存，
@@ -347,6 +382,10 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
     } else {
       latestContent.current = null
       setDirty(false)
+      // 恢复协同必须同点归零同步击键信号（审查修复④）：降级期击键置位后
+      // 若防抖保存到期前恢复，协同态保存被短路、保存成功归零点永不执行，
+      // 该实例存活期 guard 恒 dirty
+      pendingChangeRef.current = false
     }
   }, [collabState.collabActive, collabEnabled, setDirty, triggerDebouncedSave])
 
@@ -356,6 +395,16 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
       // 通道一守卫：协同态（含远端 update 触发的 onChange）不进 DB 保存链路
       if (collabActiveRef.current) return
       latestContent.current = content
+      // init 批次豁免（任务 2 审查修复②）：首个 onChange 且无同步击键信号
+      // = 初始化归一化（非用户编辑），只刷新内容 + 照常武装防抖保存，不置
+      // dirty（守卫 clean）；真实击键（含 init 窗口内）走正常 dirty 路径
+      if (!sawFirstChangeRef.current) {
+        sawFirstChangeRef.current = true
+        if (!pendingChangeRef.current) {
+          triggerDebouncedSave()
+          return
+        }
+      }
       setDirty(true)
       triggerDebouncedSave()
     },
@@ -449,6 +498,7 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
           {m.docEditor_saving()}
         </div>
       )}
+      {unsavedGuard.dialog}
       <div className="flex flex-col h-full" style={DOC_EDITOR_WIDTH_VARS[editorWidth] as React.CSSProperties}>
         <div className="px-20 pt-6 pb-2 mx-auto w-full" style={{ maxWidth: EDITOR_WIDTH_MAX_WIDTH[editorWidth] }}>
           <DocHeader
@@ -493,6 +543,11 @@ function KnowledgeDocEditorBody(bodyProps: KnowledgeDocEditorProps & { collabEna
           <NotionDocEditor
             content={collabState.config ? undefined : content}
             onChange={handleContentChange}
+            onDirtySignal={() => {
+              // 同步击键信号（审查修复①）：协同态不置位（Y 是唯一写手，
+              // 与通道一守卫同口径）
+              if (!collabActiveRef.current) pendingChangeRef.current = true
+            }}
             placeholder={m.docEditor_contentPlaceholder()}
             showTocSidebar
             kbId={document.kbId}

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

@@ -23,6 +23,7 @@ import { DocHeader } from "@/components/knowledge/editor/doc-header"
 import { parseMindmapContent, createDefaultMindmapData } from "@/components/tiptap/mindmap/lib/default-mindmap-data"
 import type { MindElixirData } from "mind-elixir"
 import { m } from "@/paraglide/messages.js";
+import { useUnsavedGuard } from "@/hooks/use-unsaved-guard";
 
 const MindMapLazy = lazy(() =>
   import("@/components/tiptap/mindmap/mind-map").then((m) => ({ default: m.MindMap })),
@@ -93,6 +94,16 @@ export function MindmapDocEditor({ document, kbName }: MindmapDocEditorProps) {
     { wait: EDITOR_AUTO_SAVE_MS },
   )
 
+  // SPA 导航未保存拦截（任务 2）：「离开」先 flush 当前内容（doSaveRef）再
+  // 放行；下方 beforeunload 尽力保存保留（浏览器关闭/刷新兜底）
+  const unsavedGuard = useUnsavedGuard({
+    isDirty: () => dirty,
+    onSaveAndLeave: () => {
+      const c = latestContent.current
+      if (c) return doSaveRef.current(c)
+    },
+  })
+
   const handleChange = useCallback((newData: MindElixirData, _operation: unknown) => {
     latestContent.current = newData
     setMindmapData(newData)
@@ -143,6 +154,7 @@ export function MindmapDocEditor({ document, kbName }: MindmapDocEditorProps) {
           {m.mindmap_saving()}
         </div>
       )}
+      {unsavedGuard.dialog}
       <div className="px-20 pt-6 pb-2 mx-auto w-full" style={{ maxWidth: headerMaxWidth }}>
         <DocHeader
           title={displayTitle}

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

@@ -89,5 +89,7 @@ export function useAutoSaveChannels<T>(opts: AutoSaveChannelsOptions<T>) {
     return () => window.removeEventListener("beforeunload", handleBeforeUnload)
   }, [saveIfContent])
 
-  return { dirty, setDirty, triggerDebouncedSave }
+  // saveIfContent 一并透出：use-unsaved-guard 的「离开」flush（任务 2）与
+  // 通道三复用同一保存入口
+  return { dirty, setDirty, triggerDebouncedSave, saveIfContent }
 }

package/src/components/layout/sidebar-03/__tests__/nav-workspace.test.tsx

@@ -53,10 +53,6 @@ vi.mock("@/lib/utils", () => ({
   cn: (...classes: string[]) => classes.filter(Boolean).join(" "),
 }));
 
-vi.mock("@/lib/collections/reference/workspaces-collection", () => ({
-  WORKSPACES_QUERY_KEY: ["workspaces"],
-}));
-
 vi.mock("@/server/serverFns/workspace", () => ({
   listPinnedWorkspacesBriefFn: vi.fn().mockResolvedValue([]),
   toggleWorkspacePinFn: vi.fn().mockResolvedValue({ success: true }),