feat(frontend): AI 对话核心——视图模型 + 数据/追加 hook + 抽屉（AC-3）

- lib/workbench/aiConversation.ts：纯视图模型（kind 标签/徽标、bubbleSide、
  按 thread 归组 (created_at,seq) 定序、按作用域分区、接受动作映射）+ 单测。
- lib/workbench/useAiConversation.ts：Workbench 级懒加载 + 批量 append（乐观插入 +
  正位对账 / 失败回滚），fail-soft 绝不 throw 进生成/HITL；silent 直投供工具箱页。
  renderHook 测试覆盖懒加载去重、对账、回滚、silent、项目切换复位。
- components/workbench/AiConversationDrawer.tsx：本章对话 + 项目级生成两段的气泡抽屉，
  克隆 ContextDrawer 的 a11y（role=dialog/log、Esc、focus trap、还原焦点）；
  ai 气泡挂 DRAFT-only 再接受按钮（替换整章/插入正文/回填选段），不绕开验收事务。
- lib/api/types.ts：re-export AiMessage* 码生成名。

apps/web/components/workbench/AiConversationDrawer.tsx

@@ -0,0 +1,360 @@
+"use client";
+
+import { useEffect, useRef, type RefObject } from "react";
+import { MessagesSquare, X } from "lucide-react";
+
+import { ThinkingIndicator } from "@/components/ThinkingIndicator";
+import { Badge } from "@/components/ui/Badge";
+import { Button } from "@/components/ui/Button";
+import { EmptyState } from "@/components/ui/EmptyState";
+import { StatusNote } from "@/components/ui/StatusNote";
+import { handleTabTrap } from "@/lib/a11y/focusTrap";
+import { useRestoreFocus } from "@/lib/a11y/useRestoreFocus";
+import { useBodyScrollLock } from "@/lib/ui/useBodyScrollLock";
+import { cn, overlayScrim } from "@/lib/ui/variants";
+import type { AiMessageView } from "@/lib/api/types";
+import {
+  acceptActionFor,
+  bubbleSide,
+  groupByThread,
+  kindBadge,
+  kindLabel,
+  partitionByScope,
+  type AcceptAction,
+  type AiThread,
+} from "@/lib/workbench/aiConversation";
+import type { UseAiConversation } from "@/lib/workbench/useAiConversation";
+
+// AI 对话总开关：一键关闭即回滚（触发按钮据此隐藏），仿 CONTEXT_DRAWER_ENABLED。
+export const AI_CONVERSATION_ENABLED = true;
+
+interface AiConversationDrawerProps {
+  open: boolean;
+  onClose: () => void;
+  conversation: UseAiConversation;
+  currentChapterNo: number;
+  // 从历史再接受（复用编辑器既有 DRAFT-only HITL 回调）；返回 true=成功则关抽屉。
+  onReplaceChapter: (content: string) => boolean;
+  onAppendDraft: (content: string) => boolean;
+  onRefillSegment: (segment: string, refined: string) => boolean;
+  triggerRef?: RefObject<HTMLElement | null>;
+}
+
+// 每章「AI 对话」抽屉（对话气泡视图）：本章对话 + 项目级生成两段，作者右 / AI 左，kind 徽标 + 线程归组。
+// 结构克隆 ContextDrawer：右侧 slide-over + overlayScrim + role=dialog + Esc + focus trap + scroll lock + 还原焦点。
+// append-only 只读展示；对 ai 产出可「从历史再接受」——只回填编辑器草稿，不绕开验收事务（守不变量 #3）。
+export function AiConversationDrawer({
+  open,
+  onClose,
+  conversation,
+  currentChapterNo,
+  onReplaceChapter,
+  onAppendDraft,
+  onRefillSegment,
+  triggerRef,
+}: AiConversationDrawerProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useBodyScrollLock(open);
+  useRestoreFocus(open, triggerRef);
+
+  // 打开即懒加载（Workbench 级 hook，append 早已可能触发过——已加载则空操作）。
+  useEffect(() => {
+    if (open) conversation.ensureLoaded();
+  }, [open, conversation]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onClose();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    closeRef.current?.focus();
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  const threads = groupByThread(conversation.messages);
+  const { chapterThreads, projectThreads } = partitionByScope(
+    threads,
+    currentChapterNo,
+  );
+  const summary = `本章 ${chapterThreads.length} 段对话，项目级 ${projectThreads.length} 项生成`;
+
+  // 再接受成功则关抽屉揭示改动后的编辑器；失败（如原选段漂移）保留抽屉与漂移提示。
+  const accept = (action: AcceptAction, m: AiMessageView): void => {
+    let ok = false;
+    if (action === "replace_chapter") ok = onReplaceChapter(m.content);
+    else if (action === "append_draft") ok = onAppendDraft(m.content);
+    else if (action === "refill_segment")
+      ok = onRefillSegment(readSegment(m.meta), m.content);
+    if (ok) onClose();
+  };
+
+  return (
+    <div className={overlayScrim} onClick={onClose}>
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label="AI 对话"
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => {
+          if (panelRef.current) handleTabTrap(panelRef.current, e);
+        }}
+        className="absolute right-0 top-0 flex h-full w-96 max-w-[90vw] flex-col border-l border-line bg-panel shadow-paper outline-none motion-safe:transition-transform"
+      >
+        <header className="flex items-center justify-between border-b border-line px-4 py-3">
+          <span className="flex items-center gap-2 font-serif text-base text-ink">
+            <MessagesSquare
+              className="h-4 w-4 text-cinnabar"
+              aria-hidden="true"
+            />
+            AI 对话
+          </span>
+          <Button
+            ref={closeRef}
+            onClick={onClose}
+            aria-label="关闭 AI 对话"
+            variant="ghost"
+            size="icon"
+          >
+            <X className="h-5 w-5" aria-hidden="true" />
+          </Button>
+        </header>
+
+        <div
+          role="log"
+          aria-live="polite"
+          aria-relevant="additions"
+          aria-label={summary}
+          className="flex-1 overflow-auto overscroll-contain px-4 py-4"
+        >
+          <DrawerBody
+            status={conversation.status}
+            chapterThreads={chapterThreads}
+            projectThreads={projectThreads}
+            onRetry={conversation.reload}
+            onAccept={accept}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+interface DrawerBodyProps {
+  status: UseAiConversation["status"];
+  chapterThreads: AiThread[];
+  projectThreads: AiThread[];
+  onRetry: () => void;
+  onAccept: (action: AcceptAction, m: AiMessageView) => void;
+}
+
+function DrawerBody({
+  status,
+  chapterThreads,
+  projectThreads,
+  onRetry,
+  onAccept,
+}: DrawerBodyProps) {
+  if (status === "loading" || status === "idle") {
+    return (
+      <div className="py-6 text-center">
+        <ThinkingIndicator label="加载中" className="text-sm text-ink-soft" />
+      </div>
+    );
+  }
+  if (status === "error") {
+    return (
+      <StatusNote variant="danger" title="加载失败">
+        <p>AI 对话暂不可用。</p>
+        <Button
+          onClick={onRetry}
+          variant="secondary"
+          size="sm"
+          className="mt-2"
+        >
+          重试
+        </Button>
+      </StatusNote>
+    );
+  }
+  if (chapterThreads.length === 0 && projectThreads.length === 0) {
+    return (
+      <EmptyState
+        icon={MessagesSquare}
+        title="还没有 AI 对话"
+        description="润色、整章重写、续写、工具箱生成的往复会自动留痕，重开也不丢。"
+      />
+    );
+  }
+  return (
+    <div className="space-y-5">
+      <ThreadSection
+        heading="本章对话"
+        threads={chapterThreads}
+        onAccept={onAccept}
+        emptyText="本章还没有对话。"
+      />
+      <ThreadSection
+        heading="项目级生成"
+        threads={projectThreads}
+        onAccept={onAccept}
+        emptyText="还没有项目级（工具箱）生成。"
+      />
+    </div>
+  );
+}
+
+interface ThreadSectionProps {
+  heading: string;
+  threads: AiThread[];
+  onAccept: (action: AcceptAction, m: AiMessageView) => void;
+  emptyText: string;
+}
+
+function ThreadSection({
+  heading,
+  threads,
+  onAccept,
+  emptyText,
+}: ThreadSectionProps) {
+  return (
+    <section>
+      <h3 className="mb-2 text-2xs font-medium uppercase tracking-wide text-ink-soft">
+        {heading}
+      </h3>
+      {threads.length === 0 ? (
+        <p className="text-xs text-ink-soft">{emptyText}</p>
+      ) : (
+        <ul className="space-y-3">
+          {threads.map((thread) => (
+            <li key={thread.threadId}>
+              <ThreadBlock thread={thread} onAccept={onAccept} />
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
+
+interface ThreadBlockProps {
+  thread: AiThread;
+  onAccept: (action: AcceptAction, m: AiMessageView) => void;
+}
+
+function ThreadBlock({ thread, onAccept }: ThreadBlockProps) {
+  const action = acceptActionFor(thread);
+  const headAt = thread.messages[0]?.created_at ?? "";
+  return (
+    <div className="rounded border border-line bg-bg/50 p-3">
+      <div className="mb-2 flex items-center gap-2">
+        <Badge variant={kindBadge(thread.kind)}>{kindLabel(thread.kind)}</Badge>
+        {thread.toolKey ? (
+          <span className="font-mono text-2xs text-ink-soft">
+            {thread.toolKey}
+          </span>
+        ) : null}
+        <span className="ml-auto font-mono text-2xs text-ink-soft">
+          {formatBubbleTime(headAt)}
+        </span>
+      </div>
+      <div className="space-y-2">
+        {thread.messages.map((m) => (
+          <Bubble key={m.id} message={m} action={action} onAccept={onAccept} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+interface BubbleProps {
+  message: AiMessageView;
+  action: AcceptAction | null;
+  onAccept: (action: AcceptAction, m: AiMessageView) => void;
+}
+
+// 单条气泡：作者右（cinnabar-wash）/ AI 左（border+bg）；clarify ai 气泡额外渲染只读方向选项。
+function Bubble({ message, action, onAccept }: BubbleProps) {
+  const side = bubbleSide(message.role);
+  const options = message.kind === "clarify" ? readOptions(message.meta) : [];
+  // 只有 ai 产出气泡（左侧）挂再接受按钮；作者气泡与 clarify 不挂。
+  const showAccept = action !== null && side === "left" && message.kind !== "clarify";
+  return (
+    <div className={cn("flex", side === "right" ? "justify-end" : "justify-start")}>
+      <div
+        className={cn(
+          "max-w-[85%] rounded border px-3 py-2",
+          side === "right"
+            ? "border-cinnabar/30 bg-[var(--color-cinnabar-wash)]"
+            : "border-line bg-bg",
+        )}
+      >
+        <p className="max-h-56 overflow-y-auto whitespace-pre-wrap text-sm text-ink">
+          {message.content}
+        </p>
+        {options.length > 0 ? (
+          <ul className="mt-2 flex flex-wrap gap-1.5">
+            {options.map((opt, i) => (
+              <li
+                key={i}
+                className="rounded border border-line bg-panel px-2 py-0.5 text-2xs text-ink-soft"
+              >
+                {opt}
+              </li>
+            ))}
+          </ul>
+        ) : null}
+        {showAccept && action ? (
+          <Button
+            onClick={() => onAccept(action, message)}
+            variant="secondary"
+            size="sm"
+            className="mt-2"
+          >
+            {ACCEPT_LABEL[action]}
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+const ACCEPT_LABEL: Record<AcceptAction, string> = {
+  replace_chapter: "接受这版（替换整章）",
+  append_draft: "插入正文（章末）",
+  refill_segment: "回填选段",
+};
+
+// meta.segment（refine ai 行每版都存原选段）——供「回填选段」按内容重锚。
+function readSegment(meta: AiMessageView["meta"]): string {
+  const v = (meta ?? {})["segment"];
+  return typeof v === "string" ? v : "";
+}
+
+// clarify ai 行 meta.options → 只读选项 label 列表（外部数据，逐项显式取值，不信任形状）。
+function readOptions(meta: AiMessageView["meta"]): string[] {
+  const raw = (meta ?? {})["options"];
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((o) =>
+      o && typeof o === "object" && "label" in o
+        ? String((o as { label: unknown }).label ?? "")
+        : "",
+    )
+    .filter((label) => label.length > 0);
+}
+
+// 气泡时间戳：本地 HH:MM（显示用，与自动保存「保存于 HH:MM」风格一致）。
+function formatBubbleTime(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}

apps/web/lib/api/types.ts

@@ -125,3 +125,11 @@ export type OutlineSceneIngestView =
 // F1：拆书入库产物（themes/archetypes/structure/hooks → 项目 rules 条目）。
 export type TeardownIngestView =
   components["schemas"]["TeardownIngestView"];
+
+// AC-3 AI 对话（聊天记录）：作者↔AI 五类往复留痕的 append/list 契约（AC-2 C3 扩，snake_case）。
+export type AiMessageView = components["schemas"]["AiMessageView"];
+export type AiMessageInput = components["schemas"]["AiMessageInput"];
+export type AiMessageAppendRequest =
+  components["schemas"]["AiMessageAppendRequest"];
+export type AiMessageListResponse =
+  components["schemas"]["AiMessageListResponse"];

apps/web/lib/workbench/aiConversation.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+import type { AiMessageView } from "@/lib/api/types";
+import {
+  acceptActionFor,
+  bubbleSide,
+  groupByThread,
+  KIND_LABEL,
+  kindLabel,
+  partitionByScope,
+} from "./aiConversation";
+
+// AiMessageView 工厂：只填测试关心的字段，其余给稳定默认。
+function view(partial: Partial<AiMessageView>): AiMessageView {
+  return {
+    id: partial.id ?? crypto.randomUUID(),
+    project_id: "p1",
+    chapter_no: partial.chapter_no ?? null,
+    thread_id: partial.thread_id ?? "t1",
+    seq: partial.seq ?? 0,
+    kind: partial.kind ?? "refine",
+    tool_key: partial.tool_key ?? null,
+    role: partial.role ?? "ai",
+    content: partial.content ?? "",
+    meta: partial.meta ?? {},
+    created_at: partial.created_at ?? "2026-07-09T00:00:00Z",
+  };
+}
+
+describe("kindLabel / KIND_LABEL", () => {
+  it("五类 kind 各有中文标签", () => {
+    expect(KIND_LABEL.refine).toBe("润色");
+    expect(KIND_LABEL.rewrite).toBe("整章重写");
+    expect(KIND_LABEL.clarify).toBe("反问澄清");
+    expect(KIND_LABEL.continue).toBe("续写");
+    expect(KIND_LABEL.generator).toBe("工具箱");
+  });
+
+  it("未知 kind 回退为原始串（不崩）", () => {
+    expect(kindLabel("mystery")).toBe("mystery");
+    expect(kindLabel("refine")).toBe("润色");
+  });
+});
+
+describe("bubbleSide", () => {
+  it("author 靠右、ai 靠左", () => {
+    expect(bubbleSide("author")).toBe("right");
+    expect(bubbleSide("ai")).toBe("left");
+  });
+});
+
+describe("groupByThread", () => {
+  it("按 thread_id 归组，返回每组 kind/toolKey/chapterNo", () => {
+    const msgs = [
+      view({ thread_id: "a", kind: "refine", chapter_no: 1, seq: 0 }),
+      view({ thread_id: "b", kind: "continue", tool_key: "continue", chapter_no: 1, seq: 0 }),
+      view({ thread_id: "a", kind: "refine", chapter_no: 1, seq: 1 }),
+    ];
+    const threads = groupByThread(msgs);
+    const a = threads.find((t) => t.threadId === "a");
+    expect(a?.messages).toHaveLength(2);
+    expect(a?.kind).toBe("refine");
+    const b = threads.find((t) => t.threadId === "b");
+    expect(b?.toolKey).toBe("continue");
+    expect(b?.chapterNo).toBe(1);
+  });
+
+  it("同一批次 created_at 相同时，按 seq 升序排组内（不靠 created_at 单独定序）", () => {
+    // 故意乱序传入；同 created_at，靠 seq 稳定定序。
+    const msgs = [
+      view({ thread_id: "a", seq: 2, content: "c2", created_at: "2026-07-09T00:00:00Z" }),
+      view({ thread_id: "a", seq: 0, content: "c0", created_at: "2026-07-09T00:00:00Z" }),
+      view({ thread_id: "a", seq: 1, content: "c1", created_at: "2026-07-09T00:00:00Z" }),
+    ];
+    const thread = groupByThread(msgs)[0]!;
+    expect(thread.messages.map((m) => m.content)).toEqual(["c0", "c1", "c2"]);
+  });
+
+  it("跨批次靠 created_at 定序，组内新批 append 在后", () => {
+    const msgs = [
+      view({ thread_id: "a", seq: 0, content: "old", created_at: "2026-07-09T00:00:00Z" }),
+      view({ thread_id: "a", seq: 0, content: "new", created_at: "2026-07-09T00:05:00Z" }),
+    ];
+    const thread = groupByThread(msgs)[0]!;
+    expect(thread.messages.map((m) => m.content)).toEqual(["old", "new"]);
+  });
+
+  it("线程按各自首条 (created_at, seq) 升序（老线程在前）", () => {
+    const msgs = [
+      view({ thread_id: "late", seq: 0, created_at: "2026-07-09T01:00:00Z" }),
+      view({ thread_id: "early", seq: 0, created_at: "2026-07-09T00:00:00Z" }),
+    ];
+    const threads = groupByThread(msgs);
+    expect(threads.map((t) => t.threadId)).toEqual(["early", "late"]);
+  });
+
+  it("空输入 → 空数组", () => {
+    expect(groupByThread([])).toEqual([]);
+  });
+});
+
+describe("partitionByScope", () => {
+  it("本章线程与项目级(chapter_no=null)线程分区", () => {
+    const msgs = [
+      view({ thread_id: "chap", chapter_no: 3, seq: 0 }),
+      view({ thread_id: "proj", chapter_no: null, kind: "generator", seq: 0 }),
+    ];
+    const threads = groupByThread(msgs);
+    const { chapterThreads, projectThreads } = partitionByScope(threads, 3);
+    expect(chapterThreads.map((t) => t.threadId)).toEqual(["chap"]);
+    expect(projectThreads.map((t) => t.threadId)).toEqual(["proj"]);
+  });
+
+  it("非本章号的章线程不落入本章分区（联合查询兜底）", () => {
+    const threads = groupByThread([
+      view({ thread_id: "other", chapter_no: 9, seq: 0 }),
+    ]);
+    const { chapterThreads, projectThreads } = partitionByScope(threads, 3);
+    expect(chapterThreads).toHaveLength(0);
+    expect(projectThreads).toHaveLength(0);
+  });
+});
+
+describe("acceptActionFor", () => {
+  it("按 kind 映射接受动作；clarify/未知无动作", () => {
+    const mk = (kind: string) =>
+      groupByThread([view({ thread_id: kind, kind, seq: 0 })])[0]!;
+    expect(acceptActionFor(mk("rewrite"))).toBe("replace_chapter");
+    expect(acceptActionFor(mk("continue"))).toBe("append_draft");
+    expect(acceptActionFor(mk("generator"))).toBe("append_draft");
+    expect(acceptActionFor(mk("refine"))).toBe("refill_segment");
+    expect(acceptActionFor(mk("clarify"))).toBeNull();
+    expect(acceptActionFor(mk("mystery"))).toBeNull();
+  });
+});

apps/web/lib/workbench/aiConversation.ts

@@ -0,0 +1,139 @@
+// AI 对话（聊天记录）纯视图模型：把 append-only 的 AiMessageView 扁平流归组成可渲染的
+// 线程/分区结构 + kind 标签/徽标/气泡方位映射。无 React/IO，确定性纯函数，供抽屉与单测共用。
+// 排序纪律（守 AC 契约）：组内与线程都按 (created_at ASC, seq ASC)——绝不单靠 created_at
+// （同一 append 批次共享 created_at，靠 repo 赋的 seq 消歧，这正是后端加 seq 的原因）。
+
+import type { AiMessageView } from "@/lib/api/types";
+import type { BadgeVariant } from "@/lib/ui/variants";
+
+// v1 记录的五类交互（与后端 AiKind Literal 对齐）。
+export type AiKind = "refine" | "rewrite" | "clarify" | "continue" | "generator";
+
+// 抽屉里对某条 ai 产出可执行的接受动作（复用编辑器既有 DRAFT-only HITL 回调，不绕开验收事务）。
+export type AcceptAction = "replace_chapter" | "append_draft" | "refill_segment";
+
+export const KIND_LABEL: Record<AiKind, string> = {
+  refine: "润色",
+  rewrite: "整章重写",
+  clarify: "反问澄清",
+  continue: "续写",
+  generator: "工具箱",
+};
+
+export const KIND_BADGE: Record<AiKind, BadgeVariant> = {
+  refine: "accent",
+  rewrite: "warning",
+  clarify: "info",
+  continue: "success",
+  generator: "neutral",
+};
+
+// kind → 中文标签；未知 kind（后端可零迁移新增）回退原始串，永不崩。
+export function kindLabel(kind: string): string {
+  return KIND_LABEL[kind as AiKind] ?? kind;
+}
+
+// kind → 徽标变体；未知 kind 回退中性徽标。
+export function kindBadge(kind: string): BadgeVariant {
+  return KIND_BADGE[kind as AiKind] ?? "neutral";
+}
+
+// 气泡方位：作者靠右、AI 靠左（对话视图约定）。
+export function bubbleSide(role: string): "left" | "right" {
+  return role === "author" ? "right" : "left";
+}
+
+// 一次往复交换（同 thread_id 归组），消息按 (created_at, seq) 升序。
+export interface AiThread {
+  threadId: string;
+  kind: string;
+  toolKey: string | null;
+  chapterNo: number | null;
+  messages: AiMessageView[];
+}
+
+// created_at → 毫秒时间戳（兼容 Z / +00:00 两种序列化；不可解析回退 0）。
+function timeOf(iso: string): number {
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? 0 : t;
+}
+
+// 稳定定序比较器：先 created_at，再 seq（跨批 created_at 定序、批内 seq 消歧）。
+function byTimeThenSeq(a: AiMessageView, b: AiMessageView): number {
+  const dt = timeOf(a.created_at) - timeOf(b.created_at);
+  return dt !== 0 ? dt : a.seq - b.seq;
+}
+
+// 扁平消息流 → 线程数组。组内按 (created_at, seq) 升序；线程按各自首条 (created_at, seq) 升序
+// （老线程在前，新往复追加在后——契合聊天视图 + aria additions 在末尾播报新增）。
+export function groupByThread(messages: readonly AiMessageView[]): AiThread[] {
+  const groups = new Map<string, AiMessageView[]>();
+  for (const msg of messages) {
+    const bucket = groups.get(msg.thread_id);
+    if (bucket) {
+      bucket.push(msg);
+    } else {
+      groups.set(msg.thread_id, [msg]);
+    }
+  }
+
+  const threads: AiThread[] = [];
+  for (const [threadId, rows] of groups) {
+    const sorted = [...rows].sort(byTimeThenSeq);
+    const head = sorted[0];
+    if (!head) continue; // 分组桶恒非空；仅为类型收窄。
+    threads.push({
+      threadId,
+      kind: head.kind,
+      toolKey: head.tool_key,
+      chapterNo: head.chapter_no,
+      messages: sorted,
+    });
+  }
+
+  // 线程按首条消息定序（复用同一比较器，取每组已排序的 messages[0]）。
+  return threads.sort((a, b) => {
+    const ha = a.messages[0];
+    const hb = b.messages[0];
+    if (!ha || !hb) return 0;
+    return byTimeThenSeq(ha, hb);
+  });
+}
+
+// 线程按作用域分区：本章线程（chapterNo === 当前章）与项目级线程（chapterNo == null，工具箱）。
+export interface ScopePartition {
+  chapterThreads: AiThread[];
+  projectThreads: AiThread[];
+}
+
+export function partitionByScope(
+  threads: readonly AiThread[],
+  currentChapterNo: number,
+): ScopePartition {
+  const chapterThreads: AiThread[] = [];
+  const projectThreads: AiThread[] = [];
+  for (const thread of threads) {
+    if (thread.chapterNo === currentChapterNo) {
+      chapterThreads.push(thread);
+    } else if (thread.chapterNo === null) {
+      projectThreads.push(thread);
+    }
+    // 其它章号（联合查询理论上不返回）：既不归本章也不归项目级，静默丢弃。
+  }
+  return { chapterThreads, projectThreads };
+}
+
+// 线程 kind → 抽屉里对 ai 气泡可执行的接受动作；clarify / 未知 kind 无接受动作。
+export function acceptActionFor(thread: AiThread): AcceptAction | null {
+  switch (thread.kind) {
+    case "rewrite":
+      return "replace_chapter";
+    case "continue":
+    case "generator":
+      return "append_draft";
+    case "refine":
+      return "refill_segment";
+    default:
+      return null;
+  }
+}

apps/web/lib/workbench/useAiConversation.test.ts

@@ -0,0 +1,188 @@
+// @vitest-environment jsdom
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useAiConversation } from "./useAiConversation";
+
+// 后端客户端与 Toast 是 hook 的外部副作用边界，单测一律 mock。
+const get = vi.fn();
+const post = vi.fn();
+const toast = vi.fn();
+vi.mock("@/lib/api/client", () => ({
+  api: {
+    GET: (...a: unknown[]) => get(...a),
+    POST: (...a: unknown[]) => post(...a),
+  },
+}));
+vi.mock("@/components/Toast", () => ({ useToast: () => toast }));
+
+const LIST_PATH = "/projects/{project_id}/ai-messages";
+
+function serverRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: overrides.id ?? crypto.randomUUID(),
+    project_id: "p1",
+    chapter_no: 1,
+    thread_id: "t1",
+    seq: 0,
+    kind: "refine",
+    tool_key: null,
+    role: "ai",
+    content: "server",
+    meta: {},
+    created_at: "2026-07-09T00:00:00Z",
+    ...overrides,
+  };
+}
+
+describe("useAiConversation", () => {
+  beforeEach(() => {
+    get.mockReset();
+    post.mockReset();
+    toast.mockReset();
+  });
+  afterEach(() => vi.clearAllMocks());
+
+  it("初始 idle，未触发前不发 GET", () => {
+    const { result } = renderHook(() => useAiConversation("p1", 1));
+    expect(get).not.toHaveBeenCalled();
+    expect(result.current.status).toBe("idle");
+    expect(result.current.messages).toEqual([]);
+  });
+
+  it("ensureLoaded 懒加载一次，缓存不重复拉取", async () => {
+    get.mockResolvedValue({ data: { messages: [serverRow()] }, error: null });
+    const { result } = renderHook(() => useAiConversation("p1", 1));
+    act(() => result.current.ensureLoaded());
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+    expect(result.current.messages).toHaveLength(1);
+    act(() => result.current.ensureLoaded());
+    expect(get).toHaveBeenCalledTimes(1);
+  });
+
+  it("GET 传 chapter_no 过滤（本章 ∪ 项目级）", async () => {
+    get.mockResolvedValue({ data: { messages: [] }, error: null });
+    const { result } = renderHook(() => useAiConversation("p1", 5));
+    act(() => result.current.ensureLoaded());
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+    expect(get).toHaveBeenCalledWith(
+      LIST_PATH,
+      expect.objectContaining({
+        params: expect.objectContaining({
+          path: { project_id: "p1" },
+          query: { chapter_no: 5 },
+        }),
+      }),
+    );
+  });
+
+  it("加载失败 → error 态 + toast，reload 可重试", async () => {
+    get.mockResolvedValueOnce({ data: null, error: { detail: "boom" } });
+    const { result } = renderHook(() => useAiConversation("p1", 1));
+    act(() => result.current.ensureLoaded());
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    expect(toast).toHaveBeenCalledWith(expect.any(String), "error");
+
+    get.mockResolvedValueOnce({ data: { messages: [serverRow()] }, error: null });
+    act(() => result.current.reload());
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+    expect(result.current.messages).toHaveLength(1);
+  });
+
+  it("appendMessages：乐观插入 → 成功后按服务器行正位对账", async () => {
+    get.mockResolvedValue({ data: { messages: [] }, error: null });
+    const persisted = serverRow({ id: "srv-1", content: "refined", role: "ai" });
+    post.mockResolvedValue({ data: { messages: [persisted] }, error: null });
+    const { result } = renderHook(() => useAiConversation("p1", 1));
+    act(() => result.current.ensureLoaded());
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+
+    await act(async () => {
+      await result.current.appendMessages({
+        threadId: "t1",
+        kind: "refine",
+        chapterNo: 1,
+        messages: [{ role: "ai", content: "refined" }],
+      });
+    });
+
+    expect(post).toHaveBeenCalledTimes(1);
+    // 临时行被服务器行替换（对账后只剩真实 id）。
+    expect(result.current.messages).toHaveLength(1);
+    expect(result.current.messages[0]?.id).toBe("srv-1");
+  });
+
+  it("appendMessages 失败 → 回滚乐观行 + toast，绝不 throw", async () => {
+    get.mockResolvedValue({ data: { messages: [] }, error: null });
+    post.mockResolvedValue({ data: null, error: { detail: "nope" } });
+    const { result } = renderHook(() => useAiConversation("p1", 1));
+    act(() => result.current.ensureLoaded());
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+
+    await act(async () => {
+      await expect(
+        result.current.appendMessages({
+          threadId: "t1",
+          kind: "refine",
+          chapterNo: 1,
+          messages: [{ role: "ai", content: "x" }],
+        }),
+      ).resolves.toBeUndefined();
+    });
+
+    expect(result.current.messages).toHaveLength(0);
+    expect(toast).toHaveBeenCalledWith(expect.any(String), "error");
+  });
+
+  it("silent 模式：不 GET、不 toast，append 只 fire-and-forget POST", async () => {
+    post.mockResolvedValue({ data: { messages: [serverRow()] }, error: null });
+    const { result } = renderHook(() =>
+      useAiConversation("p1", 0, { silent: true }),
+    );
+    act(() => result.current.ensureLoaded());
+    expect(get).not.toHaveBeenCalled();
+    expect(result.current.status).toBe("idle");
+
+    await act(async () => {
+      await result.current.appendMessages({
+        threadId: "t9",
+        kind: "generator",
+        toolKey: "book-title",
+        chapterNo: null,
+        messages: [{ role: "author", content: "brief" }],
+      });
+    });
+    expect(post).toHaveBeenCalledTimes(1);
+    expect(toast).not.toHaveBeenCalled();
+  });
+
+  it("silent 模式 append 失败也不 toast、不 throw", async () => {
+    post.mockResolvedValue({ data: null, error: { detail: "x" } });
+    const { result } = renderHook(() =>
+      useAiConversation("p1", 0, { silent: true }),
+    );
+    await act(async () => {
+      await result.current.appendMessages({
+        threadId: "t9",
+        kind: "generator",
+        chapterNo: null,
+        messages: [{ role: "author", content: "brief" }],
+      });
+    });
+    expect(toast).not.toHaveBeenCalled();
+  });
+
+  it("切换项目 → 清缓存并复位（重新可加载）", async () => {
+    get.mockResolvedValue({ data: { messages: [serverRow()] }, error: null });
+    const { result, rerender } = renderHook(
+      ({ pid }: { pid: string }) => useAiConversation(pid, 1),
+      { initialProps: { pid: "p1" } },
+    );
+    act(() => result.current.ensureLoaded());
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+
+    rerender({ pid: "p2" });
+    expect(result.current.status).toBe("idle");
+    expect(result.current.messages).toEqual([]);
+  });
+});

apps/web/lib/workbench/useAiConversation.ts

@@ -0,0 +1,187 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { api } from "@/lib/api/client";
+import { useToast } from "@/components/Toast";
+import type { AiMessageView } from "@/lib/api/types";
+import type { AiKind } from "./aiConversation";
+
+// AI 对话数据层（Workbench 级单实例）：懒加载本章 ∪ 项目级留痕 + 批量 append（乐观 + 正位对账）。
+// 记录写入是 fail-soft 副作用——append 失败绝不 throw 进调用方、不阻塞生成/HITL（守不变量 #3 意图），
+// 至多弹一次 toast。仿 useContextDrawerData：单飞哨兵 + reload nonce + 项目/章切换复位。
+
+export type AiConversationStatus = "idle" | "loading" | "ready" | "error";
+
+// 一条待落库 bubble（camelCase 入参，映射到 snake_case AiMessageInput）。
+export interface AiTurnMessage {
+  role: "author" | "ai";
+  content: string;
+  meta?: Record<string, unknown>;
+}
+
+// 一次已结束交换的一批 bubble（同 threadId 归组；批级字段提顶层，与后端 AppendRequest 对齐）。
+export interface AiTurnInput {
+  threadId: string;
+  kind: AiKind;
+  toolKey?: string | null;
+  chapterNo: number | null;
+  messages: AiTurnMessage[];
+}
+
+export interface UseAiConversationOptions {
+  // ToolboxPage 无抽屉：静默直投——不 GET、不 toast、append fire-and-forget。
+  silent?: boolean;
+}
+
+export interface UseAiConversation {
+  status: AiConversationStatus;
+  messages: AiMessageView[];
+  // 首次抽屉打开 / 首次 append 触发懒加载；已加载或在途则空操作。silent 下为空操作。
+  ensureLoaded: () => void;
+  // 出错后重试拉取。
+  reload: () => void;
+  // 追加一批往复；乐观插入 + 成功正位对账 / 失败回滚。绝不 throw。
+  appendMessages: (turn: AiTurnInput) => Promise<void>;
+}
+
+const LIST_PATH = "/projects/{project_id}/ai-messages" as const;
+
+// 按 id 并集去重（base 在前，extra 仅补 base 未含的 id）——防加载/追加并发时行重复或被覆盖。
+function mergeById(
+  base: readonly AiMessageView[],
+  extra: readonly AiMessageView[],
+): AiMessageView[] {
+  const ids = new Set(base.map((m) => m.id));
+  return [...base, ...extra.filter((m) => !ids.has(m.id))];
+}
+
+export function useAiConversation(
+  projectId: string,
+  chapterNo: number,
+  options: UseAiConversationOptions = {},
+): UseAiConversation {
+  const silent = options.silent ?? false;
+  const currentKey = `${projectId}:${chapterNo}`;
+  const [status, setStatus] = useState<AiConversationStatus>("idle");
+  const [messages, setMessages] = useState<AiMessageView[]>([]);
+  // 请求哪个 (project:chapter) 的记录；按 key 触发（而非布尔）——项目切换时残留请求不会误发到新项目。
+  const [loadKey, setLoadKey] = useState<string | null>(null);
+  const [reloadNonce, setReloadNonce] = useState(0);
+  // 单飞哨兵：已发起过 GET 就不再重复（成功缓存 / 在途去重）；出错时复位以允许重试。
+  const reqRef = useRef(false);
+  const toast = useToast();
+
+  // 项目/章切换 → 清缓存 + 复位（先于加载 effect 声明，保证同次提交先复位）。
+  useEffect(() => {
+    reqRef.current = false;
+    setMessages([]);
+    setStatus("idle");
+    setLoadKey(null);
+  }, [projectId, chapterNo]);
+
+  useEffect(() => {
+    if (silent || loadKey !== currentKey || reqRef.current) return;
+    reqRef.current = true;
+    let cancelled = false;
+    setStatus("loading");
+    void (async () => {
+      try {
+        const { data, error } = await api.GET(LIST_PATH, {
+          params: { path: { project_id: projectId }, query: { chapter_no: chapterNo } },
+        });
+        if (cancelled) return;
+        if (error || !data) {
+          reqRef.current = false;
+          setStatus("error");
+          toast("AI 对话加载失败，请重试。", "error");
+          return;
+        }
+        // 合并而非覆盖：不吞掉加载在途时已成功 append 的行。
+        setMessages((prev) => mergeById(data.messages, prev));
+        setStatus("ready");
+      } catch {
+        if (cancelled) return;
+        reqRef.current = false;
+        setStatus("error");
+        toast("AI 对话加载异常，请检查网络。", "error");
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [projectId, chapterNo, currentKey, loadKey, reloadNonce, silent, toast]);
+
+  const ensureLoaded = useCallback((): void => {
+    if (silent) return;
+    setLoadKey(currentKey);
+  }, [silent, currentKey]);
+
+  const reload = useCallback((): void => {
+    reqRef.current = false;
+    setStatus("idle");
+    setLoadKey(currentKey);
+    setReloadNonce((n) => n + 1);
+  }, [currentKey]);
+
+  const appendMessages = useCallback<UseAiConversation["appendMessages"]>(
+    async (turn) => {
+      ensureLoaded();
+      const now = new Date().toISOString();
+      // 乐观临时行（temp id + 本地 seq）；引用留存以便成功对账 / 失败回滚。
+      const optimistic: AiMessageView[] = turn.messages.map((m, i) => ({
+        id: `temp-${crypto.randomUUID()}`,
+        project_id: projectId,
+        chapter_no: turn.chapterNo,
+        thread_id: turn.threadId,
+        seq: i,
+        kind: turn.kind,
+        tool_key: turn.toolKey ?? null,
+        role: m.role,
+        content: m.content,
+        meta: m.meta ?? {},
+        created_at: now,
+      }));
+      if (!silent) {
+        setMessages((prev) => [...prev, ...optimistic]);
+      }
+      const dropOptimistic = (prev: AiMessageView[]): AiMessageView[] =>
+        prev.filter((m) => !optimistic.includes(m));
+      try {
+        const { data, error } = await api.POST(LIST_PATH, {
+          params: { path: { project_id: projectId } },
+          body: {
+            thread_id: turn.threadId,
+            chapter_no: turn.chapterNo,
+            kind: turn.kind,
+            tool_key: turn.toolKey ?? null,
+            messages: turn.messages.map((m) => ({
+              role: m.role,
+              content: m.content,
+              meta: m.meta ?? {},
+            })),
+          },
+        });
+        if (error || !data) {
+          if (!silent) {
+            setMessages(dropOptimistic);
+            toast("对话记录保存失败（不影响本次生成）。", "error");
+          }
+          return;
+        }
+        // 正位对账：移除临时行，按服务器返回行去重合并（response 不回显 temp id，靠位置替换）。
+        if (!silent) {
+          setMessages((prev) => mergeById(dropOptimistic(prev), data.messages));
+        }
+      } catch {
+        if (!silent) {
+          setMessages(dropOptimistic);
+          toast("对话记录保存异常（不影响本次生成）。", "error");
+        }
+      }
+    },
+    [ensureLoaded, projectId, silent, toast],
+  );
+
+  return { status, messages, ensureLoaded, reload, appendMessages };
+}