# UX 设计规范（对话层防卡顿 · 流畅度设计）

> **版本**：2.1.2  
> **定位**：本文件规范 FBS-BookWriter **对话层**的用户体验——防止流程卡顿、减少无效等待、提升推进透明度。  
> **适用范围**：AI 对话执行层（WorkBuddy / CodeBuddy），不涉及前端 UI 组件实现。  
> **与仓库对齐**：与 `SKILL.md` 执行约束、`fbs-runtime-hints.json`（`userExperience` / `antiStall`）及 [`references/05-ops/anti-stall-guide.md`](../05-ops/anti-stall-guide.md) 一并阅读；数值阈值分层见下文「原则2」，避免将 **15s** 与 **30s** 混为一条规则。

---

## 一、防卡顿核心原则

### 原则1：每步结束时，用户知道下一步是什么

AI 完成一个阶段后，**必须**在输出末尾说明：
- 刚做完了什么
- 下一步是什么
- 需要用户做什么（或"无需操作，我继续"）

```
✅ 正确示例：
「S0 调研已完成（时间线 ✓ 竞品 ✓ 读者 ✓）
  下一步：生成目录草案，约需 2 分钟。无需操作，马上开始。」

❌ 错误示例：
「调研完成。」（用户不知道下一步是等还是操作）
```

### 原则2：长耗时动作的时间阈值（分层，勿与单文件心跳混用）

以下两层**同时成立**，对应不同时机：

| 层级 | 阈值 | 触发时机 | 行为 |
|------|------|----------|------|
| **A. 事前声明** | 预计整段耗时 **> 15 秒** | 动作**开始前** | 说明「开始 {动作}，预计 {时长}，期间无需操作（或需用户配合的点）」 |
| **B. 执行中反馈** | **约 30 秒** | 动作**已开始执行后** | ① **长任务**（写作段落、多章、审计脚本等）：至少每约 **30 秒** 给一次进度或百分比；② **单文件静默操作**（写盘/调用工具无自然语言输出）：超过约 **30 秒** 仍无输出时，打 **一行** 简短进度（与 `antiStall.longTaskProgressHintSec`、[`anti-stall-guide.md`](../05-ops/anti-stall-guide.md) §3 一致） |

```
✅ 正确示例（A + B）：
「开始生成第 3 章初稿（约 2000 字），预计 1 分钟。」   ← 事前声明（>15s）

[约 30 秒后]
「第 3 章进度：已完成 60%（约 1200 字）。」   ← 执行中反馈

[完成]
「第 3 章初稿已完成，共 2,150 字。下一步：进入 S3 审校，约 30 秒。」
```

**说明**：**15 秒**不是「执行满 15 秒才开口」，而是「一旦预计整段超过 15 秒，**开口前**就要先说清」；**30 秒**是**执行过程中**的heartbeat/单行提示节奏，二者不矛盾。

### 原则3：决策节点最多 3 个选项

AI 询问用户选择时，**最多提供 3 个选项**，不得开放式等待。如果需要更多选项，先归类为 3 组，再在选中组内展开。

```
✅ 正确示例：
「大纲方向选择：
  A. 时间线叙事（按历史顺序展开）
  B. 主题式架构（按核心主题分章）
  C. 案例驱动（每章一个完整案例）
  你倾向哪个方向？」

❌ 错误示例：
「你想要什么样的大纲？」（开放式，用户不知道怎么回答）
```

---

## 二、阶段推进透明度

### 2.1 阶段切换声明

每次进入新阶段时，AI 必须声明：

```
━━ 阶段切换 ━━
刚刚完成：{上一阶段名称} → {关键产出物}
现在进入：{本阶段名称} → 预计产出 {产出物}
预计耗时：{时间}
需要你做：{操作/无需操作}
━━━━━━━━━━━━
```

### 2.2 进度条设计（文本版）

对于多步骤流程，使用文本进度条：

```
S0→S1→S2→S3→S4→S5→S6
 ✓   ✓   ▶   ·   ·   ·   ·
```

含义：
- `✓` 已完成
- `▶` 当前进行
- `·` 未开始
- `⚠` 需要修改后重做
- `✗` 打回

---

## 三、等待体验设计

### 3.1 等待时长分级

| 预计时长 | 行为 | 说明 |
|----------|------|------|
| < 5秒 | 静默执行 | 无需任何提示 |
| 5–15秒 | 开始前一句话提示 | 「开始 {动作}，稍等……」 |
| 15秒–数分钟 | 事前声明 + 执行中节奏 | 开始前说清预计总时长；**执行中**以约 **30 秒** 为粒度播报（与原则2-B 一致，可与「每 15–30 秒」区间表述兼容） |
| 1–5分钟 | 详细进度 + 阶段预告 | 保持约 30 秒级心跳，避免长时间无反馈 |
| > 5分钟 | 拆分为子任务 + 实时进度 | 每个子任务独立事前声明 + 执行中播报 |

### 3.2 长任务拆分策略

对于预计超过 5 分钟的任务（如全书审计、多章并行写稿），AI 必须：

1. 先列出子任务清单
2. 逐个执行并播报
3. 每个子任务完成后给出摘要

```
「全书质量审计，共 5 个维度，预计 8 分钟：
  1. S层句级扫描（~2分钟）
  2. P层段级检测（~1分钟）
  3. C层章级审查（~2分钟）
  4. B层全文体检（~2分钟）
  5. 汇总报告（~1分钟）
  现在开始第 1 项……」
```

---

## 四、错误与异常处理

### 4.1 错误分级

| 级别 | 表现 | AI 行为 |
|------|------|---------|
| **提示** | 可继续，但需注意 | 告知用户，继续执行 |
| **警告** | 可能影响质量 | 告知用户，给出 2 个选项 |
| **阻断** | 无法继续 | 明确说明原因，给出修复路径 |

### 4.2 错误消息模板

```
⚠️ {错误级别}：{简短描述}

原因：{一句话说明}
影响：{对最终产出的影响}
建议：{修复方案}

选项：
A. {修复后继续}
B. {接受风险继续}
```

### 4.3 常见异常场景

| 异常场景 | AI 行为 |
|---------|---------|
| 检索超时/无结果 | 降级为已有知识，标注「检索未果，基于已有知识」 |
| 用户输入模糊 | 提供 3 个选项，不猜测 |
| 质量审计未通过 | 给出具体问题清单 + 修复建议 |
| 构建失败 | 给出错误日志 + 可能原因 + 修复步骤 |

---

## 五、用户确认节点

### 5.1 必须用户确认的场景

- S1 定位确认书
- S2 大纲定稿
- S5 终稿审批
- 删除已有内容
- 修改核心论断
- 学术用途确认

### 5.2 确认界面设计

```
━━ 需要你的确认 ━━
事项：{简短描述}
影响：{如果不确认会怎样}
选项：
  ✅ 确认（继续）
  ❌ 否认（修改/暂停）
  ⏸️ 稍后（保存当前状态）
━━━━━━━━━━━━━━━━
```

### 5.3 超时默认行为

| 确认类型 | 超时（30秒）默认 | 说明 |
|---------|-----------------|------|
| 阶段推进 | 自动继续 | 不阻断流程 |
| 内容删除 | 不删除 | 安全优先 |
| 风险接受 | 不接受 | 安全优先 |
| 方向选择 | 选方案A | 默认方案 |

---

## 六、对话节奏控制

### 6.1 信息密度

| 阶段 | 单次输出长度 | 说明 |
|------|-------------|------|
| S0-S1 | 500-1000字 | 调研和定位，需要频繁互动 |
| S2-S3 | 1000-3000字 | 大纲和初稿，允许较长输出 |
| S4 | 500-1500字 | 扩写和修改，按章节输出 |
| S5 | 500-1000字 | 审校和交付，需要频繁互动 |
| S6 | 500-1000字 | 转化和发布准备，需要频繁互动 |

### 6.2 互动频率

- 每完成一个完整步骤，**必须**等待用户确认或反馈
- 连续输出超过 3000 字时，主动暂停询问
- 用户主动中断时，保存当前进度并给出恢复点

---

## 七、辅助功能

### 7.1 状态查询

用户可随时询问：
- 「当前进度」→ 返回阶段进度条
- 「还剩什么」→ 返回待完成清单
- 「上次做到哪」→ 返回最近确认点

### 7.2 回退机制

| 操作 | 回退方式 |
|------|----------|
| 误认方向 | 「回退到 S1」 |
| 大纲不满意 | 「重新生成大纲」 |
| 某章重写 | 「重写第 N 章」 |
| 全部重来 | 「从头开始」 |

### 7.3 上下文保持

- AI 在整个写作过程中维护 `.fbs/` 目录下的状态文件
- 跨会话时自动加载上次的进度
- 用户可手动指定从某个阶段恢复
