# 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 里注明改动原因。