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 };
+}

apps/web/lib/settings/providers.ts

@@ -0,0 +1,16 @@
+// 已知提供商（UX §6.10）。后端按 provider 字符串识别；这里只是 UI 候选列表。
+export const KNOWN_PROVIDERS: { id: string; label: string }[] = [
+  { id: "anthropic", label: "Anthropic" },
+  { id: "deepseek", label: "DeepSeek" },
+  { id: "kimi", label: "Kimi" },
+  { id: "openai", label: "OpenAI" },
+  { id: "qwen", label: "通义千问" },
+  { id: "glm", label: "智谱 GLM" },
+  { id: "gemini", label: "Gemini" },
+];
+
+export const TIER_LABELS: Record<string, string> = {
+  writer: "写手档",
+  analyst: "分析档",
+  light: "轻量档",
+};

apps/web/lib/stream/sse.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  SseFrameBuffer,
+  initialStreamState,
+  parseSseBlock,
+  reduceStream,
+  type SseEvent,
+} from "./sse";
+
+describe("parseSseBlock", () => {
+  it("parses a token frame", () => {
+    const evt = parseSseBlock('event:token\ndata:{"text":"夜"}');
+    expect(evt).toEqual({ event: "token", data: { text: "夜" } });
+  });
+
+  it("parses a done frame", () => {
+    const evt = parseSseBlock('event:done\ndata:{"length":12}');
+    expect(evt).toEqual({ event: "done", data: { length: 12 } });
+  });
+
+  it("parses an error frame with request_id", () => {
+    const evt = parseSseBlock(
+      'event:error\ndata:{"code":"INTERNAL","message":"boom","request_id":"r1"}',
+    );
+    expect(evt).toEqual({
+      event: "error",
+      data: { code: "INTERNAL", message: "boom", request_id: "r1" },
+    });
+  });
+
+  it("ignores comment/heartbeat lines and tolerates leading space after colon", () => {
+    const evt = parseSseBlock(': keep-alive\nevent: token\ndata: {"text":"x"}');
+    expect(evt).toEqual({ event: "token", data: { text: "x" } });
+  });
+
+  it("returns null for unknown event types", () => {
+    expect(parseSseBlock('event:section\ndata:{"x":1}')).toBeNull();
+  });
+
+  it("returns null for malformed json", () => {
+    expect(parseSseBlock("event:token\ndata:{not json")).toBeNull();
+  });
+});
+
+describe("SseFrameBuffer", () => {
+  it("emits complete blocks split by blank line and buffers the tail", () => {
+    const buf = new SseFrameBuffer();
+    const first = buf.push('event:token\ndata:{"text":"a"}\n\nevent:tok');
+    expect(first).toEqual([{ event: "token", data: { text: "a" } }]);
+    const second = buf.push('en\ndata:{"text":"b"}\n\n');
+    expect(second).toEqual([{ event: "token", data: { text: "b" } }]);
+  });
+
+  it("handles CRLF boundaries", () => {
+    const buf = new SseFrameBuffer();
+    const out = buf.push('event:token\r\ndata:{"text":"z"}\r\n\r\n');
+    expect(out).toEqual([{ event: "token", data: { text: "z" } }]);
+  });
+});
+
+describe("reduceStream", () => {
+  it("accumulates token text and marks streaming", () => {
+    const tokens: SseEvent[] = [
+      { event: "token", data: { text: "夜色" } },
+      { event: "token", data: { text: "如墨" } },
+    ];
+    const state = tokens.reduce(reduceStream, initialStreamState);
+    expect(state.text).toBe("夜色如墨");
+    expect(state.phase).toBe("streaming");
+  });
+
+  it("marks done on done event preserving text", () => {
+    let s = reduceStream(initialStreamState, {
+      event: "token",
+      data: { text: "abc" },
+    });
+    s = reduceStream(s, { event: "done", data: { length: 3 } });
+    expect(s.phase).toBe("done");
+    expect(s.text).toBe("abc");
+  });
+
+  it("captures error and retains partial text", () => {
+    let s = reduceStream(initialStreamState, {
+      event: "token",
+      data: { text: "partial" },
+    });
+    s = reduceStream(s, {
+      event: "error",
+      data: { code: "LLM_UNAVAILABLE", message: "no key" },
+    });
+    expect(s.phase).toBe("error");
+    expect(s.text).toBe("partial");
+    expect(s.error?.code).toBe("LLM_UNAVAILABLE");
+  });
+});

apps/web/lib/stream/sse.ts

@@ -0,0 +1,106 @@
+// SSE 帧解析 + 草稿流归一（对齐 C3 / ARCH §7.3）。
+// 帧格式：`event:<token|done|error>\ndata:<json>\n\n`。
+// 纯逻辑，便于单测（不依赖浏览器/DOM）。
+
+export interface TokenEvent {
+  event: "token";
+  data: { text: string };
+}
+export interface DoneEvent {
+  event: "done";
+  data: { length: number };
+}
+export interface ErrorEvent {
+  event: "error";
+  data: { code: string; message: string; request_id?: string | null };
+}
+export type SseEvent = TokenEvent | DoneEvent | ErrorEvent;
+
+const KNOWN_EVENTS = new Set(["token", "done", "error"]);
+
+// 把一个完整 SSE 块（多行）解析成事件；无法解析则返回 null（跳过）。
+export function parseSseBlock(block: string): SseEvent | null {
+  let event = "";
+  const dataLines: string[] = [];
+  for (const rawLine of block.split("\n")) {
+    const line = rawLine.replace(/\r$/, "");
+    if (line.startsWith(":")) continue; // 注释/心跳
+    const sep = line.indexOf(":");
+    if (sep === -1) continue;
+    const field = line.slice(0, sep);
+    const value = line.slice(sep + 1).replace(/^ /, "");
+    if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+  }
+  if (!KNOWN_EVENTS.has(event) || dataLines.length === 0) return null;
+  let data: unknown;
+  try {
+    data = JSON.parse(dataLines.join("\n"));
+  } catch {
+    return null;
+  }
+  return { event, data } as SseEvent;
+}
+
+// 增量缓冲：吃进一段文本，吐出已完成的事件块（以空行分隔），保留未完成尾部。
+export class SseFrameBuffer {
+  private buf = "";
+
+  push(chunk: string): SseEvent[] {
+    this.buf += chunk;
+    const events: SseEvent[] = [];
+    let idx: number;
+    // 块之间以空行（\n\n，兼容 \r\n\r\n）分隔。
+    while ((idx = this.findBoundary(this.buf)) !== -1) {
+      const block = this.buf.slice(0, idx.valueOf());
+      this.buf = this.buf.slice(this.boundaryEnd(this.buf, idx));
+      const evt = parseSseBlock(block);
+      if (evt) events.push(evt);
+    }
+    return events;
+  }
+
+  private findBoundary(s: string): number {
+    const a = s.indexOf("\n\n");
+    const b = s.indexOf("\r\n\r\n");
+    if (a === -1) return b;
+    if (b === -1) return a;
+    return Math.min(a, b);
+  }
+
+  private boundaryEnd(s: string, idx: number): number {
+    return s.startsWith("\r\n\r\n", idx) ? idx + 4 : idx + 2;
+  }
+}
+
+export type StreamPhase = "idle" | "streaming" | "done" | "error" | "aborted";
+
+export interface StreamState {
+  phase: StreamPhase;
+  text: string;
+  error: { code: string; message: string; request_id?: string | null } | null;
+}
+
+export const initialStreamState: StreamState = {
+  phase: "idle",
+  text: "",
+  error: null,
+};
+
+// 纯 reducer：把单个事件折叠进状态（打字机文本累积）。
+export function reduceStream(state: StreamState, event: SseEvent): StreamState {
+  switch (event.event) {
+    case "token":
+      return {
+        ...state,
+        phase: "streaming",
+        text: state.text + event.data.text,
+      };
+    case "done":
+      return { ...state, phase: "done" };
+    case "error":
+      return { ...state, phase: "error", error: event.data };
+    default:
+      return state;
+  }
+}

apps/web/lib/stream/useDraftStream.ts

@@ -0,0 +1,122 @@
+"use client";
+
+import { useCallback, useReducer, useRef } from "react";
+
+import { API_BASE_PUBLIC } from "@/lib/api/config";
+import {
+  SseFrameBuffer,
+  initialStreamState,
+  reduceStream,
+  type StreamState,
+} from "./sse";
+
+type Action =
+  | { type: "start" }
+  | { type: "events"; events: ReturnType<SseFrameBuffer["push"]> }
+  | { type: "abort" }
+  | { type: "fail"; code: string; message: string }
+  | { type: "reset"; text: string };
+
+function reducer(state: StreamState, action: Action): StreamState {
+  switch (action.type) {
+    case "start":
+      return { phase: "streaming", text: "", error: null };
+    case "events":
+      return action.events.reduce(reduceStream, state);
+    case "abort":
+      return { ...state, phase: "aborted" };
+    case "fail":
+      return {
+        ...state,
+        phase: "error",
+        error: { code: action.code, message: action.message },
+      };
+    case "reset":
+      return { ...initialStreamState, text: action.text };
+    default:
+      return state;
+  }
+}
+
+export interface UseDraftStream {
+  state: StreamState;
+  isStreaming: boolean;
+  start: (projectId: string, chapterNo: number) => Promise<void>;
+  stop: () => void;
+  reset: (text: string) => void;
+}
+
+// 消费 POST .../draft 的 SSE 流。用 fetch+ReadableStream（EventSource 不支持 POST）。
+// "停" = abort 连接（已生成部分保留在 state.text，由调用方落入草稿）。
+export function useDraftStream(): UseDraftStream {
+  const [state, dispatch] = useReducer(reducer, initialStreamState);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  const stop = useCallback(() => {
+    controllerRef.current?.abort();
+    controllerRef.current = null;
+    dispatch({ type: "abort" });
+  }, []);
+
+  const reset = useCallback((text: string) => {
+    dispatch({ type: "reset", text });
+  }, []);
+
+  const start = useCallback(async (projectId: string, chapterNo: number) => {
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    dispatch({ type: "start" });
+    try {
+      const res = await fetch(
+        `${API_BASE_PUBLIC}/projects/${projectId}/chapters/${chapterNo}/draft`,
+        {
+          method: "POST",
+          headers: { Accept: "text/event-stream" },
+          signal: controller.signal,
+        },
+      );
+      if (!res.ok || !res.body) {
+        // 流前错误（如无凭据 → 503 LLM_UNAVAILABLE，JSON 信封而非帧）。
+        let code = "STREAM_FAILED";
+        let message = `写章请求失败（${res.status}）`;
+        try {
+          const body = (await res.json()) as {
+            error?: { code?: string; message?: string };
+          };
+          if (body.error?.code) code = body.error.code;
+          if (body.error?.message) message = body.error.message;
+        } catch {
+          // 非 JSON 信封，沿用默认文案。
+        }
+        dispatch({ type: "fail", code, message });
+        return;
+      }
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      const buffer = new SseFrameBuffer();
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        const events = buffer.push(decoder.decode(value, { stream: true }));
+        if (events.length > 0) dispatch({ type: "events", events });
+      }
+    } catch (err: unknown) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        // 用户主动停止：state 已置 aborted。
+        return;
+      }
+      const message = err instanceof Error ? err.message : "未知网络错误";
+      dispatch({ type: "fail", code: "NETWORK", message });
+    } finally {
+      controllerRef.current = null;
+    }
+  }, []);
+
+  return {
+    state,
+    isStreaming: state.phase === "streaming",
+    start,
+    stop,
+    reset,
+  };
+}

apps/web/lib/wizard/wizard.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  canAdvance,
+  canSubmit,
+  clampStep,
+  emptyWizardForm,
+  toCreateRequest,
+  WIZARD_STEPS,
+  type WizardForm,
+} from "./wizard";
+
+describe("wizard step gating", () => {
+  it("blocks advancing past step 1 without a title", () => {
+    expect(canAdvance(1, emptyWizardForm)).toBe(false);
+  });
+
+  it("allows advancing step 1 once title is set", () => {
+    expect(canAdvance(1, { ...emptyWizardForm, title: "逐光而行" })).toBe(true);
+  });
+
+  it("allows advancing later steps even when fields are empty", () => {
+    expect(canAdvance(3, emptyWizardForm)).toBe(true);
+  });
+
+  it("clamps step within bounds", () => {
+    expect(clampStep(0)).toBe(1);
+    expect(clampStep(WIZARD_STEPS + 3)).toBe(WIZARD_STEPS);
+    expect(clampStep(3)).toBe(3);
+  });
+
+  it("requires a title to submit", () => {
+    expect(canSubmit(emptyWizardForm)).toBe(false);
+    expect(canSubmit({ ...emptyWizardForm, title: "x" })).toBe(true);
+  });
+});
+
+describe("toCreateRequest", () => {
+  it("maps form to snake_case request, nulling empty optionals", () => {
+    const form: WizardForm = {
+      title: "  逐光而行  ",
+      genre: "玄幻",
+      logline: "",
+      sellingPoints: ["逆袭", "系统流"],
+      structure: "三幕",
+      premise: "  ",
+      theme: "抗争",
+    };
+    expect(toCreateRequest(form)).toEqual({
+      title: "逐光而行",
+      genre: "玄幻",
+      logline: null,
+      premise: null,
+      theme: "抗争",
+      selling_points: ["逆袭", "系统流"],
+      structure: "三幕",
+    });
+  });
+});
+
+// wizard→create 流程：归一后的请求体经 mock 客户端提交，返回新建项目 id。
+describe("wizard create flow (mocked client)", () => {
+  it("submits the normalized body and resolves a project id", async () => {
+    const post = async (
+      _path: string,
+      opts: { body: ReturnType<typeof toCreateRequest> },
+    ): Promise<{ data: { id: string }; error: null }> => {
+      expect(opts.body.title).toBe("青冥录");
+      expect(opts.body.selling_points).toEqual(["群像"]);
+      return { data: { id: "proj-123" }, error: null };
+    };
+
+    const form: WizardForm = {
+      ...emptyWizardForm,
+      title: "青冥录",
+      sellingPoints: ["群像"],
+    };
+    const { data } = await post("/projects", { body: toCreateRequest(form) });
+    expect(data.id).toBe("proj-123");
+  });
+});

apps/web/lib/wizard/wizard.ts

@@ -0,0 +1,62 @@
+import type { ProjectCreateRequest } from "@/lib/api/types";
+
+// 立项向导 5 步（UX §6.2）。表单状态用字符串/数组，提交时归一为 ProjectCreateRequest。
+export interface WizardForm {
+  title: string;
+  genre: string;
+  logline: string;
+  sellingPoints: string[];
+  structure: string;
+  premise: string;
+  theme: string;
+}
+
+export const WIZARD_STEPS = 5;
+
+export const emptyWizardForm: WizardForm = {
+  title: "",
+  genre: "",
+  logline: "",
+  sellingPoints: [],
+  structure: "",
+  premise: "",
+  theme: "",
+};
+
+export const GENRES = ["玄幻", "仙侠", "都市", "科幻", "历史", "悬疑"];
+export const STRUCTURES = ["三幕", "故事圈", "雪花"];
+export const SELLING_POINT_PRESETS = ["逆袭", "打脸", "系统流", "双男主", "群像"];
+
+// 每一步可否前进：仅第 1 步（书名）必填，其余可空着继续（草稿式立项）。
+export function canAdvance(step: number, form: WizardForm): boolean {
+  if (step === 1) return form.title.trim().length > 0;
+  return true;
+}
+
+// 整个向导可否提交：书名必填。
+export function canSubmit(form: WizardForm): boolean {
+  return form.title.trim().length > 0;
+}
+
+export function clampStep(step: number): number {
+  if (step < 1) return 1;
+  if (step > WIZARD_STEPS) return WIZARD_STEPS;
+  return step;
+}
+
+// 归一为后端请求体（snake_case，空值落 null/省略）。
+export function toCreateRequest(form: WizardForm): ProjectCreateRequest {
+  const trim = (s: string): string | null => {
+    const v = s.trim();
+    return v.length > 0 ? v : null;
+  };
+  return {
+    title: form.title.trim(),
+    genre: trim(form.genre),
+    logline: trim(form.logline),
+    premise: trim(form.premise),
+    theme: trim(form.theme),
+    selling_points: form.sellingPoints,
+    structure: trim(form.structure),
+  };
+}