feat: M1 — 立项→写章草稿(SSE)→自动保存；连一家 provider

- 薄自建 LLM 网关：OpenAI 兼容适配器(DeepSeek) + instructor 结构化输出 + usage_ledger 记账 + 档位路由
- 记忆服务 assemble：确定性选择(显式+主角+近况) + 渲染卡 + 缓存断点(中性文本)
- LangGraph 写章节点 + Postgres checkpointer + SSE 归一(token/done/error)
- API：立项 + 写章 draft(SSE) + PUT 自动保存 + 提供商凭据(Fernet 加密/测试连接)
- 前端：AppShell + 作品库 + 5 步立项向导 + 写作工作台(流式打字机+自动保存) + 设置页
- M1 E2E：真实 DB + mock 网关零 token 走通闭环

apps/web/lib/autosave/autosave.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createDebouncedSaver, formatSavedAt } from "./autosave";
+
+describe("createDebouncedSaver", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("saves only once after the debounce window for rapid edits", () => {
+    const save = vi.fn().mockResolvedValue(undefined);
+    const saver = createDebouncedSaver(save, 1000);
+    saver.schedule("a");
+    saver.schedule("ab");
+    saver.schedule("abc");
+    expect(save).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1000);
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(save).toHaveBeenCalledWith("abc");
+  });
+
+  it("flush triggers the pending save immediately", () => {
+    const save = vi.fn().mockResolvedValue(undefined);
+    const saver = createDebouncedSaver(save, 1000);
+    saver.schedule("hello");
+    saver.flush();
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(save).toHaveBeenCalledWith("hello");
+    // No double-fire when the timer would have elapsed.
+    vi.advanceTimersByTime(1000);
+    expect(save).toHaveBeenCalledTimes(1);
+  });
+
+  it("cancel prevents a scheduled save", () => {
+    const save = vi.fn().mockResolvedValue(undefined);
+    const saver = createDebouncedSaver(save, 1000);
+    saver.schedule("x");
+    saver.cancel();
+    vi.advanceTimersByTime(2000);
+    expect(save).not.toHaveBeenCalled();
+  });
+
+  it("each new schedule resets the timer (only last value persists)", () => {
+    const save = vi.fn().mockResolvedValue(undefined);
+    const saver = createDebouncedSaver(save, 1000);
+    saver.schedule("one");
+    vi.advanceTimersByTime(800);
+    saver.schedule("two");
+    vi.advanceTimersByTime(800);
+    expect(save).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(200);
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(save).toHaveBeenCalledWith("two");
+  });
+});
+
+describe("formatSavedAt", () => {
+  it("formats as 保存于 hh:mm zero-padded", () => {
+    const d = new Date(2026, 5, 18, 9, 4);
+    expect(formatSavedAt(d)).toBe("保存于 09:04");
+  });
+});

apps/web/lib/autosave/autosave.ts

@@ -0,0 +1,52 @@
+// 自动保存的纯逻辑：防抖调度器 + 时间格式化。与 React 解耦，便于单测。
+
+export const AUTOSAVE_DELAY_MS = 1200;
+
+export type SaveFn = (text: string) => Promise<void>;
+
+export interface DebouncedSaver {
+  schedule: (text: string) => void;
+  flush: () => void;
+  cancel: () => void;
+}
+
+// 防抖：最后一次输入静默 delayMs 后才真正保存。flush 立即触发待保存项。
+export function createDebouncedSaver(
+  save: SaveFn,
+  delayMs: number = AUTOSAVE_DELAY_MS,
+): DebouncedSaver {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let pending: string | null = null;
+
+  const run = (): void => {
+    if (pending === null) return;
+    const text = pending;
+    pending = null;
+    timer = null;
+    void save(text);
+  };
+
+  return {
+    schedule(text: string): void {
+      pending = text;
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(run, delayMs);
+    },
+    flush(): void {
+      if (timer !== null) clearTimeout(timer);
+      run();
+    },
+    cancel(): void {
+      if (timer !== null) clearTimeout(timer);
+      timer = null;
+      pending = null;
+    },
+  };
+}
+
+// 「保存于 hh:mm」标签。
+export function formatSavedAt(date: Date): string {
+  const hh = String(date.getHours()).padStart(2, "0");
+  const mm = String(date.getMinutes()).padStart(2, "0");
+  return `保存于 ${hh}:${mm}`;
+}

apps/web/lib/autosave/useAutosave.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { api } from "@/lib/api/client";
+import { useToast } from "@/components/Toast";
+import {
+  AUTOSAVE_DELAY_MS,
+  createDebouncedSaver,
+  formatSavedAt,
+  type DebouncedSaver,
+} from "./autosave";
+
+export type SaveStatus = "idle" | "saving" | "saved" | "error";
+
+export interface UseAutosave {
+  status: SaveStatus;
+  savedLabel: string | null;
+  onChange: (text: string) => void;
+  flush: () => void;
+}
+
+// 防抖自动保存草稿：乐观置 saving → PUT 成功置 saved（落「保存于 hh:mm」）；
+// 失败回滚状态 + toast，不丢正文（已在编辑器里）。
+export function useAutosave(
+  projectId: string,
+  chapterNo: number,
+): UseAutosave {
+  const [status, setStatus] = useState<SaveStatus>("idle");
+  const [savedLabel, setSavedLabel] = useState<string | null>(null);
+  const toast = useToast();
+  const lastSavedRef = useRef<string | null>(null);
+
+  const save = useCallback(
+    async (text: string): Promise<void> => {
+      if (text === lastSavedRef.current) return;
+      setStatus("saving");
+      const { error } = await api.PUT(
+        "/projects/{project_id}/chapters/{chapter_no}/draft",
+        {
+          params: { path: { project_id: projectId, chapter_no: chapterNo } },
+          body: { text },
+        },
+      );
+      if (error) {
+        setStatus("error");
+        toast("自动保存失败，稍后重试（正文未丢失）", "error");
+        return;
+      }
+      lastSavedRef.current = text;
+      setSavedLabel(formatSavedAt(new Date()));
+      setStatus("saved");
+    },
+    [projectId, chapterNo, toast],
+  );
+
+  const saver: DebouncedSaver = useMemo(
+    () => createDebouncedSaver(save, AUTOSAVE_DELAY_MS),
+    [save],
+  );
+
+  useEffect(() => () => saver.cancel(), [saver]);
+
+  const onChange = useCallback(
+    (text: string) => {
+      saver.schedule(text);
+    },
+    [saver],
+  );
+
+  const flush = useCallback(() => saver.flush(), [saver]);
+
+  return { status, savedLabel, onChange, flush };
+}