ai写作
This commit is contained in:
董宏凯 committed
1 parent
f358cfb7c7
commit
4fbd0bb5c5
4 files changed
+2689
No files matched your search
@@ -0,0 +1,538 @@
|
||||
# AI 写作 — 前端开发文档
|
||||
|
||||
> **本文档目的**：帮助前端开发者快速理解 AI 写作子系统的代码结构、数据流、状态机和扩展点。
|
||||
>
|
||||
> **配套文档**：
|
||||
> - `ai-writing-说明.md` — 故障排查与运维向解决方案
|
||||
> - `ai-writing-assistant-backend-api.md` — 后端 API 详细字段定义
|
||||
> - `ai-writing-assistant-source-map.md` — 旧版前端结构索引（已合并到本文档）
|
||||
|
||||
---
|
||||
|
||||
## 一、产品定位
|
||||
|
||||
AI 写作是 DeerFlow 的「**杂志社协作写作**」子产品，由 LangGraph 后端驱动 4 个 AI Agent（**素材收集专家 / 作家 / 编辑 / 系统**）协作完成一篇文章。用户通过 **4 个干预点**（素材确认、大纲确认、草稿确认、审核确认）参与决策，UI 实时呈现进度。
|
||||
|
||||
### UI 入口
|
||||
- 路由：`/canvas/ai-writing`（在 `WorkspaceRoutes.tsx` 注册）
|
||||
- 入口页：`src/open-canvas/pages/AIWritingPage.tsx`
|
||||
- 双栏布局：左 AI 写作面板（聊天 + 干预），右草稿预览
|
||||
|
||||
---
|
||||
|
||||
## 二、目录结构
|
||||
|
||||
```
|
||||
frontend-web/src/open-canvas/
|
||||
├── pages/
|
||||
│ └── AIWritingPage.tsx # 入口页（双栏 Resizable 布局）
|
||||
│
|
||||
├── api/ # ── 后端 API 适配层 ──
|
||||
│ ├── ai-writing.ts # /start /resume + SSE 订阅（核心）
|
||||
│ ├── ai-writing-sessions.ts # 历史会话 CRUD + transcript 保存
|
||||
│ └── ai-writing-article-types.ts # 文章类型 CRUD
|
||||
│
|
||||
├── hooks/ # ── 状态管理 ──
|
||||
│ ├── useAIWriting.ts # 写作主状态机（最重要）
|
||||
│ ├── useAIWritingSessions.ts # 历史会话列表 hook
|
||||
│ └── useArticleTypes.ts # 文章类型选项 hook
|
||||
│
|
||||
├── components/ai-writing/ # ── UI 组件 ──
|
||||
│ ├── AIWritingPanel.tsx # 左侧主面板（聊天 + 干预编排）
|
||||
│ ├── AIWritingDraftPanel.tsx # 右侧草稿预览面板
|
||||
│ ├── AIWritingPageHeader.tsx # 顶部标题/历史下拉
|
||||
│ ├── AIWritingForm.tsx # 写作请求表单（首次启动用）
|
||||
│ │
|
||||
│ ├── AIWritingTimeline.tsx # 时间线主容器
|
||||
│ ├── TimelineStep.tsx # 单条进度事件
|
||||
│ ├── CompletedInterventionCard.tsx # 已完成的干预记录
|
||||
│ │
|
||||
│ ├── InterventionCard.tsx # 4 个干预点 + 求助点的卡片（核心）
|
||||
│ ├── MaterialsCard.tsx # 素材确认
|
||||
│ ├── MaterialItem.tsx # 单个素材项
|
||||
│ ├── MaterialsToolbar.tsx # 素材筛选/搜索工具栏
|
||||
│ ├── OutlineCard.tsx # 大纲确认（含编辑）
|
||||
│ ├── OutlineSection.tsx # 大纲单章节
|
||||
│ ├── ReviewCard.tsx # 审核确认
|
||||
│ ├── IssueList.tsx # 审核意见列表
|
||||
│ ├── ScoreBar.tsx # 评分进度条
|
||||
│ │
|
||||
│ ├── OutlineStreamingView.tsx # 大纲流式打字机
|
||||
│ ├── DraftStreamingView.tsx # 草稿流式打字机
|
||||
│ ├── ReviewStreamingView.tsx # 审核流式打字机
|
||||
│ ├── WritingSkeletonCard.tsx # 加载骨架屏
|
||||
│ ├── RevisionSummaryCard.tsx # 修改前后对比摘要
|
||||
│ │
|
||||
│ ├── AIWritingHistoryDropdown.tsx # 历史会话下拉
|
||||
│ └── AIWritingHistoryView.tsx # 历史会话只读回显
|
||||
│
|
||||
└── types/
|
||||
└── ai-writing.ts # 全部类型定义（重要参考）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、数据流总览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AIWritingPanel │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ useAIWriting() 主状态 hook │ │
|
||||
│ │ ┌────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ startWriting() ─── POST /api/ai-writing/start │ │ │
|
||||
│ │ │ ↓ 返回 session_id │ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ subscribeToProgress(sessionId) │ │ │
|
||||
│ │ │ ─── GET /api/ai-writing/{id}/stream (SSE) │ │ │
|
||||
│ │ │ ─── 持续推 ProgressEvent 给 handleEvent │ │ │
|
||||
│ │ │ ─── handleEvent reducer → setState │ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ submitIntervention() │ │ │
|
||||
│ │ │ ─── POST /api/ai-writing/{id}/resume │ │ │
|
||||
│ │ │ ─── graph 续推 → 新事件继续走 SSE │ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ saveAIWritingTranscript()（fire-and-forget） │ │ │
|
||||
│ │ │ ─── PUT /api/ai-writing/sessions/{id}/transcript │ │
|
||||
│ │ └────────────────────────────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 渲染： │
|
||||
│ ├ AIWritingForm（idle 状态） │
|
||||
│ ├ AIWritingTimeline（运行中） │
|
||||
│ │ ├ TimelineStep × N（progressEvents） │
|
||||
│ │ └ CompletedInterventionCard × N（已完成的干预） │
|
||||
│ ├ {Outline,Draft,Review}StreamingView（流式打字机） │
|
||||
│ ├ InterventionCard（当前 currentPause 存在时弹出） │
|
||||
│ └ WritingSkeletonCard（运行中无 pause 时的骨架屏） │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、状态机（useAIWriting.ts）
|
||||
|
||||
### 状态字段（完整定义见 `types/ai-writing.ts`）
|
||||
|
||||
```typescript
|
||||
interface AIWritingState {
|
||||
// —— 核心标识 ——
|
||||
sessionId: string | null; // 后端返回的会话 id
|
||||
status: WritingStatus; // 当前阶段（13 种状态之一）
|
||||
isPaused: boolean; // 是否在干预点等待用户
|
||||
error: string | null;
|
||||
|
||||
// —— 配置 ——
|
||||
request: AIWritingRequest | null; // 用户提交的写作请求
|
||||
|
||||
// —— 累计数据 ——
|
||||
progressEvents: ProgressEvent[]; // SSE 事件全量历史（供时间线渲染）
|
||||
materials: AIMaterial[]; // 素材列表（素材就绪后填充）
|
||||
outline: AIOutline | null; // 大纲（大纲就绪后填充）
|
||||
currentDraftMarkdown: string; // 草稿正文（草稿就绪后填充）
|
||||
currentDraftTitle: string;
|
||||
reviewResult: ReviewResult | null;
|
||||
revisionCount: number;
|
||||
completedInterventions: CompletedIntervention[]; // 已完成的干预历史
|
||||
|
||||
// —— 干预 ——
|
||||
currentPause: ProgressEvent | null; // 当前挂起的 await_user 事件
|
||||
|
||||
// —— 流式视图状态 ——
|
||||
streamingDraftTitle: string;
|
||||
streamingDraftSections: StreamingDraftSection[];
|
||||
outlineStreamingText: string;
|
||||
outlineThinkingText: string;
|
||||
researchProgress: string;
|
||||
streamingReviewItems: StreamingReviewItem[];
|
||||
revisionSummary: RevisionSummary | null;
|
||||
pendingRevisionContext: { /* ... */ } | null;
|
||||
}
|
||||
```
|
||||
|
||||
### 状态转移图（写作状态机）
|
||||
|
||||
```
|
||||
┌──────┐
|
||||
│ idle │ ←─────────────────────────────────────┐
|
||||
└──┬───┘ │
|
||||
│ startWriting() │
|
||||
↓ │
|
||||
┌─────────────────┐ │
|
||||
│ researching │ │
|
||||
└──┬──────────────┘ │
|
||||
↓ materials_ready │
|
||||
┌─────────────────────────────┐ │
|
||||
│ awaiting_material_confirm │ ← await_user │
|
||||
└──┬──────────────────────────┘ │
|
||||
↓ submit(confirm) │
|
||||
┌─────────────────┐ │
|
||||
│ writing_outline │ ← (re_search 路径) │
|
||||
└──┬──────────────┘ │
|
||||
↓ outline_ready │
|
||||
┌─────────────────────────────┐ │
|
||||
│ awaiting_outline_confirm │ │
|
||||
└──┬──────────────────────────┘ │
|
||||
↓ submit(confirm) │
|
||||
┌─────────────────┐ │
|
||||
│ writing_draft │ ← (re_outline 路径) │
|
||||
└──┬──────────────┘ │
|
||||
│ │
|
||||
┌───────┴────────┐ │
|
||||
↓ ↓ │
|
||||
awaiting_section_ awaiting_draft_confirm │
|
||||
help (素材不足) └─┬───┬───┬──────────────┐ │
|
||||
│ (supplement) │ │ │ to_editor │ │
|
||||
│ ↑回到 research │ │ ↓ │ │
|
||||
│ │ │ reviewing │ │
|
||||
│ │ │ └─┬──────┐ │ │
|
||||
│ │ │ ↓ ↓ │ │
|
||||
│ │ │ awaiting_review_confirm │
|
||||
│ │ │ └─┬────────┐ │
|
||||
│ │ │ ↓ submit ↓ │
|
||||
│ │ │ revising done ───────────────┘
|
||||
│ │ │ │
|
||||
│ │ │ └─→ writing_draft (循环修订)
|
||||
│ │ │
|
||||
│ │ │ user_revise
|
||||
│ │ └─→ revising
|
||||
│ │
|
||||
│ │ finalize
|
||||
│ └─→ done
|
||||
│
|
||||
└──→ (delete/loose) writing_draft 继续
|
||||
```
|
||||
|
||||
### handleEvent reducer（核心）
|
||||
|
||||
`useAIWriting.ts` 里的 `handleEvent` 是个**纯 reducer**，根据 SSE 事件类型更新状态：
|
||||
|
||||
| 事件类型 | 主要影响的状态字段 |
|
||||
|---|---|
|
||||
| `connected` | 仅记录到 progressEvents |
|
||||
| `step_start` | 切到对应 `status`（如「编辑」→ reviewing） |
|
||||
| `step_done` | 仅记录 |
|
||||
| `research_progress` | `researchProgress`（实时检索进度文案） |
|
||||
| `materials_ready` | `materials`、清空 researchProgress |
|
||||
| `outline_chunk` | `outlineStreamingText` / `outlineThinkingText`（打字机） |
|
||||
| `outline_ready` | `outline`、清空流式文本 |
|
||||
| `draft_chunk` | `streamingDraftSections`（按章节拼接打字机） |
|
||||
| `draft_ready` | `currentDraftMarkdown` / `currentDraftTitle` |
|
||||
| `review_chunk` | `streamingReviewItems[i].streamingText`（逐条打字机） |
|
||||
| `review_item_done` | `streamingReviewItems[i]` 标记 isDone + 结构化结果 |
|
||||
| `review_ready` | `reviewResult` |
|
||||
| `await_user` | `currentPause = event`，`isPaused = true`，**弹出 InterventionCard** |
|
||||
| `resumed` | `currentPause = null` |
|
||||
| `notice` | 仅记录（非致命告警） |
|
||||
| `done` | `status = 'done'` |
|
||||
| `error` | `status = 'error'`，`error = event.message` |
|
||||
|
||||
---
|
||||
|
||||
## 五、API 层（api/）
|
||||
|
||||
### 1. `api/ai-writing.ts` — 核心写作 API
|
||||
|
||||
```typescript
|
||||
// 启动写作 → 返回 session_id
|
||||
export async function startWritingSession(req: AIWritingRequest): Promise<string>
|
||||
|
||||
// 订阅 SSE 进度流 → 返回取消订阅函数
|
||||
export function subscribeToProgress(
|
||||
sessionId: string,
|
||||
onEvent: (event: ProgressEvent) => void,
|
||||
): () => void
|
||||
|
||||
// 提交用户干预 → 让 graph 续推
|
||||
export async function resumeWriting(
|
||||
sessionId: string,
|
||||
payload: UserInterventionPayload,
|
||||
): Promise<void>
|
||||
```
|
||||
|
||||
**关键实现细节**：
|
||||
- **snake_case ↔ camelCase 转换**：后端返回 snake_case，前端类型是 camelCase。所有 normalize 函数（`normalizeMaterial`、`normalizeOutlineSection`...）集中在这一层做转换
|
||||
- **SSE 事件白名单**：`SSE_EVENT_TYPES` 数组列出所有合法事件名，未知事件会被静默忽略
|
||||
- **取消订阅**：`subscribeToProgress` 返回的函数会调用 `AbortController.abort()` 关闭 fetch stream
|
||||
- **重连机制**：当前**没有内置重连** — 如果 SSE 断开（网络抖动、反代超时），需要用户主动重启写作或刷新页面
|
||||
- 后端 `_recover_session` 能让 SSE 重连时从 checkpointer 恢复事件，但前端没主动重连逻辑
|
||||
|
||||
### 2. `api/ai-writing-sessions.ts` — 历史会话
|
||||
|
||||
```typescript
|
||||
// CRUD
|
||||
listAIWritingSessions() : Promise<AIWritingSessionSummary[]>
|
||||
getAIWritingSession(id) : Promise<AIWritingSessionSummary>
|
||||
renameAIWritingSession(id, title) : Promise<AIWritingSessionSummary>
|
||||
deleteAIWritingSession(id) : Promise<void>
|
||||
|
||||
// 时间线持久化（fire-and-forget，永不抛错）
|
||||
saveAIWritingTranscript(id, transcript) : Promise<boolean>
|
||||
```
|
||||
|
||||
**关键设计**：`saveAIWritingTranscript` 内部用 try/catch 吞掉所有异常（网络错误、HTTP 500 等），只 `console.warn` 不影响主流程。这是**「锦上添花」契约**的前端侧。
|
||||
|
||||
### 3. `api/ai-writing-article-types.ts` — 文章类型管理
|
||||
|
||||
| 函数 | 用途 |
|
||||
|---|---|
|
||||
| `listArticleTypes()` | 表单下拉框选项 |
|
||||
| `createArticleType()` | 管理员新增 |
|
||||
| `updateArticleType()` | 管理员编辑 |
|
||||
| `deleteArticleType()` | 管理员删除 |
|
||||
|
||||
---
|
||||
|
||||
## 六、组件树详解
|
||||
|
||||
### 顶层：`AIWritingPanel`（457 行，最大）
|
||||
|
||||
负责：
|
||||
1. 调用 `useAIWriting()` 拿主状态
|
||||
2. 调用 `useAIWritingSessions()` 拿历史列表
|
||||
3. 协调表单 / 时间线 / 干预卡 / 流式视图 / 草稿同步
|
||||
4. **自动滚底逻辑**：检测用户是否手动上划，决定是否跟随最新内容
|
||||
5. **草稿同步到右侧画布**：监听 `currentDraftMarkdown` 变化，调 `setArtifact` 更新右侧
|
||||
6. **历史会话回显**：当 `historySession` 非空时，渲染 `AIWritingHistoryView` 而不是实时面板
|
||||
|
||||
### 干预卡：`InterventionCard`（663 行，第二大）
|
||||
|
||||
按 `pausePoint` 渲染**不同的卡片**：
|
||||
|
||||
| pausePoint | 卡片 | 用户能做的 |
|
||||
|---|---|---|
|
||||
| `material_confirm` | `MaterialsCard` | 勾选保留素材 / 加关键词重新搜 |
|
||||
| `outline_confirm` | `OutlineCard` | 直接编辑大纲 / 给反馈让重写 |
|
||||
| `draft_confirm` | 草稿确认卡 | 定稿 / 给修订意见 / 提交编辑审核 |
|
||||
| `review_confirm` | `ReviewCard` | 勾选采纳的意见 / 强制通过 |
|
||||
| `section_help` | 求助卡 | 逐章选择：补充检索 / 删除 / 按通用知识续写 |
|
||||
|
||||
### 时间线：`AIWritingTimeline`
|
||||
|
||||
迭代 `progressEvents`，每个 `step_start` / `step_done` / `notice` 渲染成一条 `TimelineStep`。`CompletedInterventionCard` 穿插显示已完成的干预记录。
|
||||
|
||||
### 流式视图：`{Outline,Draft,Review}StreamingView`
|
||||
|
||||
- **OutlineStreamingView**：打字机渲染 `outlineStreamingText`，支持 `<think>...</think>` 折叠显示
|
||||
- **DraftStreamingView**：按章节流式拼接 `streamingDraftSections`，每章节独立打字机
|
||||
- **ReviewStreamingView**：3 条审核（事实 / 逻辑 / 语言）并行打字机，完成后切到结构化评分
|
||||
|
||||
### 历史回显：`AIWritingHistoryView`
|
||||
|
||||
只读模式，从 `AIWritingSessionSummary` 重建 UI。**当 `transcript` 字段有值时**，从里面拿到完整 `progressEvents`，UI 表现跟实时一模一样。`transcript` 没有时退回到只显示最终草稿。
|
||||
|
||||
---
|
||||
|
||||
## 七、SSE 事件协议（前后端契约）
|
||||
|
||||
后端通过 SSE 推 `event: <type>\ndata: <json>\n\n` 格式，前端用浏览器原生 `fetch + ReadableStream` 解析（不用 `EventSource`，因为 EventSource 不能自定义 header）。
|
||||
|
||||
### 解析流程
|
||||
|
||||
```
|
||||
ReadableStream → TextDecoder
|
||||
→ 按 "\n\n" 分帧
|
||||
→ 每帧匹配 /^event: (.+)\ndata: (.+)$/
|
||||
→ JSON.parse(data)
|
||||
→ normalize(parsed)（snake → camel）
|
||||
→ onEvent(normalized)
|
||||
```
|
||||
|
||||
### 事件载荷字段（不完全列表）
|
||||
|
||||
| 字段 | 出现在哪些事件 | 用途 |
|
||||
|---|---|---|
|
||||
| `type` | 全部 | 事件类别 |
|
||||
| `sessionId` | 全部 | 标识 |
|
||||
| `message` | 大多数 | 显示给用户的文案 |
|
||||
| `agentName` | step_* | 「素材收集专家」/「作家」/「编辑」/「系统」 |
|
||||
| `materials` | materials_ready | 素材数组 |
|
||||
| `outline` | outline_ready | 大纲对象 |
|
||||
| `draftMarkdown` / `draftTitle` | draft_ready | 草稿内容 |
|
||||
| `reviewResult` | review_ready | 完整审核结果 |
|
||||
| `pausePoint` | await_user | 哪个干预点 |
|
||||
| `pauseContext` | await_user | 干预所需的上下文（如待确认的素材列表） |
|
||||
| `blockedSections` | await_user (section_help) | 素材不足的章节列表 |
|
||||
| `title` / `detail` / `raw` | notice / error | 非致命告警的标题、详情、原始错误 |
|
||||
|
||||
---
|
||||
|
||||
## 八、扩展指南：常见开发任务
|
||||
|
||||
### 新增一个干预点
|
||||
|
||||
1. **前端类型扩展**：
|
||||
- 在 `types/ai-writing.ts` 的 `ProgressEvent.pausePoint` 联合类型里加新 case
|
||||
- 在 `WritingStatus` 加对应的 `awaiting_xxx`
|
||||
- 在 `CompletedIntervention.pausePoint` 加 case
|
||||
|
||||
2. **写 InterventionCard 分支**：在 `InterventionCard.tsx` 里加新 `pausePoint` 分支，做 UI + 提交逻辑
|
||||
|
||||
3. **后端配合**（详见后端开发文档）：
|
||||
- `graph.py` 加 `pause_xxx_confirm` 节点
|
||||
- graph 拓扑加这个节点的边
|
||||
|
||||
4. **完成干预后的清理**：在 `useAIWriting.ts` 的 `submitIntervention` 函数里，**确保把这次干预 push 到 `completedInterventions`**，让历史能看到
|
||||
|
||||
### 新增一个 SSE 事件类型
|
||||
|
||||
1. `types/ai-writing.ts`：
|
||||
- `ProgressEventType` 联合类型加新值
|
||||
- `ProgressEvent` 接口加新字段（如果有载荷）
|
||||
|
||||
2. `api/ai-writing.ts`：
|
||||
- `SSE_EVENT_TYPES` 数组加新值（不加会被忽略）
|
||||
- `normalizeEvent` 函数里加字段转换（如果是 snake_case 需要 normalize）
|
||||
|
||||
3. `useAIWriting.ts` 的 `handleEvent`：加新 case 处理状态更新
|
||||
|
||||
4. 组件层：根据需要在时间线 / 干预卡 / 流式视图里渲染
|
||||
|
||||
### 修改一个流式打字机的行为
|
||||
|
||||
每个 streaming view 内部都是独立的：
|
||||
- 状态在 `useAIWriting.ts` 的 `streaming*` 系列字段
|
||||
- 渲染在 `*StreamingView.tsx`
|
||||
- 流式 chunk 处理在 `handleEvent` 的 `outline_chunk` / `draft_chunk` / `review_chunk` 分支
|
||||
|
||||
### 新增草稿到右侧画布的逻辑
|
||||
|
||||
`AIWritingPanel.tsx` 里 `useEffect` 监听 `state.currentDraftMarkdown` → 调 `setArtifact` 更新右侧 `CanvasGraphContext`。如果需要新的 artifact 类型，看 `contexts/CanvasGraphContext.tsx` 的 artifact 接口。
|
||||
|
||||
---
|
||||
|
||||
## 九、容错与边界处理
|
||||
|
||||
### 已落实的容错（不会阻断写作）
|
||||
- ✅ `saveAIWritingTranscript` 失败仅 `console.warn`
|
||||
- ✅ 历史会话列表加载失败仅 `console.warn`
|
||||
- ✅ 重命名/删除会话失败静默吞掉
|
||||
- ✅ 后端 SSE 推 `notice` / `error` 事件时，前端只渲染不中断
|
||||
- ✅ JSON parse 失败时 SSE 帧被静默丢弃（不影响后续帧）
|
||||
|
||||
### 已知边界（可能影响 UI 体验）
|
||||
- ⚠️ **SSE 断线无自动重连** — 网络抖动 / 反代超时后用户需要手动刷新
|
||||
- ⚠️ **多 worker 部署下 SSE 事件丢失**（详见 `ai-writing-说明.md`）—— 前端只能感知到「卡住」，没有重连恢复机制
|
||||
- ⚠️ `outline_chunk` / `draft_chunk` / `review_chunk` 的 `text` / `is_thinking` 字段是 snake_case，前端类型是 `text` / `isThinking` 但 normalize 时是**保留 snake_case 直接读**（参考 `useAIWriting.ts` 的 `(event as unknown as { text: string }).text`），这是历史包袱，未来 normalize 函数应统一处理
|
||||
|
||||
---
|
||||
|
||||
## 十、调试技巧
|
||||
|
||||
### 看 SSE 原始事件
|
||||
浏览器 DevTools → Network → 找 `/api/ai-writing/<id>/stream` 请求 → Response（注意是 EventStream 格式，不能直接展开 JSON）。
|
||||
|
||||
### 查当前 hook 状态
|
||||
在浏览器 console 里：
|
||||
```js
|
||||
// 需要安装 React DevTools，在 Components tab 找到 AIWritingPanel
|
||||
// 或在 useAIWriting 里临时加：
|
||||
useEffect(() => { (window as any).__aiwriting = state; }, [state]);
|
||||
// 然后在 console 里 __aiwriting 看
|
||||
```
|
||||
|
||||
### 模拟事件
|
||||
开发期可以注释掉 `subscribeToProgress`，手动调 `handleEvent({...})` 测试 reducer 行为。
|
||||
|
||||
### 看后端 transcript
|
||||
```
|
||||
GET /api/ai-writing/sessions/<id>
|
||||
```
|
||||
返回里 `transcript` 字段就是前端组装过的完整时间线 JSON。
|
||||
|
||||
---
|
||||
|
||||
## 十一、性能注意点
|
||||
|
||||
### 大数组渲染
|
||||
- `progressEvents` 在长写作里可能上千条 → `AIWritingTimeline` 应该考虑虚拟滚动（当前未实现，会议室会议讨论过）
|
||||
- `streamingDraftSections` 章节多时也是潜在瓶颈
|
||||
|
||||
### transcript PUT 频率
|
||||
- 当前每次 `progressEvents` 变化都会触发保存（实际上是 useEffect 监听）
|
||||
- 大量 chunk 事件会导致**每秒 N 次 PUT**，后端 MySQL 写压力大
|
||||
- **优化建议**：在 `useAIWriting.ts` 给 saveAIWritingTranscript 加 debounce（1-2 秒），或者只在 `await_user` / `done` / `error` 关键节点保存
|
||||
|
||||
### 浏览器内存
|
||||
- progressEvents 不主动清理 → 长会话可能占用几十 MB
|
||||
- 完成一篇文章后建议 `reset()` 清空状态
|
||||
|
||||
---
|
||||
|
||||
## 十二、相关后端接口（速查）
|
||||
|
||||
| 接口 | 用途 | 前端调用方 |
|
||||
|---|---|---|
|
||||
| `POST /api/ai-writing/start` | 启动写作 | `startWritingSession` |
|
||||
| `GET /api/ai-writing/{id}/stream` | SSE 进度流 | `subscribeToProgress` |
|
||||
| `POST /api/ai-writing/{id}/resume` | 提交干预 | `resumeWriting` |
|
||||
| `GET /api/ai-writing/{id}/state` | 查 graph 状态快照（调试用） | 暂未调用 |
|
||||
| `GET /api/ai-writing/sessions` | 历史列表 | `listAIWritingSessions` |
|
||||
| `GET /api/ai-writing/sessions/{id}` | 历史详情 | `getAIWritingSession` |
|
||||
| `PATCH /api/ai-writing/sessions/{id}` | 重命名 | `renameAIWritingSession` |
|
||||
| `DELETE /api/ai-writing/sessions/{id}` | 删除会话 | `deleteAIWritingSession` |
|
||||
| `PUT /api/ai-writing/sessions/{id}/transcript` | 保存时间线（fire-and-forget） | `saveAIWritingTranscript` |
|
||||
| `GET /api/ai-writing/article-types` | 文章类型下拉 | `listArticleTypes` |
|
||||
| `POST /api/ai-writing/admin/cleanup` | admin 手动清理 | 暂未在 UI 暴露 |
|
||||
|
||||
---
|
||||
|
||||
## 十三、未来优化方向
|
||||
|
||||
| 项目 | 说明 | 工作量 |
|
||||
|---|---|---|
|
||||
| transcript PUT 防抖 | 减少 MySQL 写压力 | 1 小时 |
|
||||
| SSE 自动重连 | 网络抖动 / 反代超时后能恢复 | 0.5 天 |
|
||||
| 时间线虚拟滚动 | 处理超长 progressEvents | 0.5 天 |
|
||||
| 干预卡组件解耦 | 663 行的 InterventionCard 拆成 5 个独立卡片 | 1 天 |
|
||||
| AbortController 串行化 | 避免重启写作时旧 SSE 还没断 | 0.5 天 |
|
||||
| 后端字段统一 camelCase | 消除 snake_case ↔ camelCase 转换层 | 需后端配合 |
|
||||
|
||||
---
|
||||
|
||||
## 附录 A：所有类型一览
|
||||
|
||||
完整定义在 `types/ai-writing.ts`，主要类型：
|
||||
|
||||
```typescript
|
||||
// 业务实体
|
||||
AIMaterial // 单个素材
|
||||
AIOutline // 大纲
|
||||
OutlineSection // 大纲单章节
|
||||
ReviewIssue // 审核问题
|
||||
ReviewResult // 完整审核结果
|
||||
BlockedSection // 素材不足的章节
|
||||
SectionDecision // 章节求助决策
|
||||
|
||||
// 流程
|
||||
WritingStatus // 13 种状态
|
||||
ProgressEventType // 17 种事件类型
|
||||
ProgressEvent // SSE 事件载荷
|
||||
UserInterventionPayload // 干预提交体
|
||||
AIWritingRequest // 启动写作的请求
|
||||
CompletedIntervention // 已完成的干预记录
|
||||
|
||||
// 流式视图
|
||||
StreamingDraftSection
|
||||
StreamingReviewItem
|
||||
RevisionSummary
|
||||
|
||||
// Hook 状态
|
||||
AIWritingState // useAIWriting 的完整状态
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录 B：常见踩坑
|
||||
|
||||
| 现象 | 原因 | 解决 |
|
||||
|---|---|---|
|
||||
| 前端类型 camelCase 但拿到 undefined | 后端 snake_case 没 normalize | 在 `api/ai-writing.ts` 的 normalize 函数里加字段 |
|
||||
| 进度卡住不动 | SSE 断了或落到错的 worker | 刷新页面，看 `ai-writing-说明.md` 多 worker 部分 |
|
||||
| 历史会话回显时间线缺失 | transcript 保存失败 | DB 列容量 / 后端日志查 `save_transcript` |
|
||||
| 修改大纲后没生效 | 用户 PATCH editedOutline 但没勾选 confirm | InterventionCard 大纲分支检查 action 字段 |
|
||||
| 草稿渲染换行错乱 | LLM 输出包含奇怪 markdown | `DraftStreamingView` 里 markdown parser 设置 |
|
||||
|
||||
---
|
||||
|
||||
如需补充内容，请直接编辑本文件，并在 git commit message 里注明改动原因。
|
||||
Reference in new issue
Block a user