# UI 改进计划 · 纸感工作台二次打磨

> 文档类型：前端设计与实施计划（只规划，不直接改业务契约）  
> 适用范围：`apps/web`  
> 上游锚点：`UX_SPEC.md §2`（纸感视觉 token）/ `§6`（页面线框）/ `§7`（组件库）/ `§10`（响应式与可访问性）  
> 当前基线：已完成第一轮 UI 重构，新增 `Button`/`Badge`/`Card`/`EmptyState`/`PageHeader`，主流程页面已统一图标、空状态、卡片与按钮风格；桌面与移动端无页面级横向溢出。

---

## 0. 实施记录

### 0.1 2026-06-27 第一批已完成

本轮按计划完成了第一批高收益 UI 改造，未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase A 表单与状态组件收敛 | 部分完成 | 新增 `Field` / `TextInput` / `TextArea` / `Select` / `StatusNote` / `SectionHeader` / `SegmentedControl`；扩展 `variants.ts` 的 `inputClass` / `statusNoteClass` / `segmentedClass`；补 `variants.test.ts`。 |
| Phase A 页面替换 | 部分完成 | 已替换 `ProjectWizard`、`GeneratorRunner`、`StyleUpload`、`RegisterForm`、`RulesPage`、`ProvidersSettings` 中一批散落 input/select/textarea 样式。 |
| Phase B 审稿页信息架构 | 核心完成 | 新增 `ReviewSummaryRail` 和 `ReviewSectionPanel`；`ReviewReport` 右侧改为摘要栏 + 一致性/伏笔/节奏/文风分段面板；有冲突时优先展开一致性。 |
| Phase B 冲突裁决强化 | 部分完成 | `ConflictCard` 增加 `冲突 x/n` 编号；手改输入框增加说明；“跳到下一条未裁决”提升到右侧 sticky 摘要栏。 |
| Phase C 顶部 AI 工具条 | 完成 C1 | 新增 `AiToolbarMoreMenu`；小屏只显示“写本章 / 审稿 / 更多”，更多菜单包含“大纲 / 设定库 / 工具箱”；桌面保留完整工具条。 |
| Phase E 空状态行动化 | 部分完成 | `RulesPage` 的规则空状态增加直接添加对应级别规则的行动按钮。 |

本轮涉及的新增文件：

- `apps/web/components/ui/Field.tsx`
- `apps/web/components/ui/TextInput.tsx`
- `apps/web/components/ui/TextArea.tsx`
- `apps/web/components/ui/Select.tsx`
- `apps/web/components/ui/StatusNote.tsx`
- `apps/web/components/ui/SectionHeader.tsx`
- `apps/web/components/ui/SegmentedControl.tsx`
- `apps/web/components/AiToolbarMoreMenu.tsx`
- `apps/web/components/review/ReviewSectionPanel.tsx`
- `apps/web/components/review/ReviewSummaryRail.tsx`

已验证：

- `cd apps/web && pnpm lint`
- `cd apps/web && pnpm typecheck`
- `cd apps/web && pnpm test`（468 passed）
- `cd apps/web && pnpm build`
- 浏览器抽查 `http://localhost:3001/`：首页无可见横向溢出。
- 浏览器抽查 390px 宽度写作页：顶部工具条正确显示“写本章 / 审稿 / 更多”，更多菜单可打开。

### 0.2 2026-06-27 第二批已完成

第二批继续补齐了写作台与设置页，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase C 写作台三栏响应式 | 完成 C2 | 小屏正文上方增加“目录 / 助手”快捷入口；目录与本章助手继续经抽屉触达；`Drawer` 增加 `triggerRef`，关闭后焦点回到触发按钮。 |
| Phase C 本章生成控制台 | 完成 C3 | `DirectivePanel` 改为“本章生成控制台”；接入 `SectionHeader`、`TextArea`、统一 `Button` 预设 chips、`StatusNote`；显示当前指令数量与生成说明。 |
| Phase D 设置页控制台化 | 核心完成 | 设置页容器放宽到 `max-w-6xl`；`ProvidersSettings` 改为桌面左侧分组导航 + 右侧配置面板；窄屏使用 `SegmentedControl` 切换“路由 / OAuth / API Key”。 |
| Phase D Provider 行表格化 | 部分完成 | API Key 区改为更紧凑的配置行：状态点、provider 名、masked key、输入框、保存、测试同一行；保存按钮在空 key 时禁用；测试结果显示在行内下方。 |

第二批额外涉及的重点文件：

- `apps/web/components/workbench/Workbench.tsx`
- `apps/web/components/Drawer.tsx`
- `apps/web/components/ui/Button.tsx`
- `apps/web/app/settings/providers/page.tsx`
- `apps/web/components/settings/ProvidersSettings.tsx`

第二批已验证：

- `cd apps/web && pnpm lint`
- `cd apps/web && pnpm typecheck`
- `cd apps/web && pnpm test`（468 passed）
- `cd apps/web && pnpm build`
- 浏览器抽查 390px 写作页：可见“目录 / 助手”入口、“本章生成控制台”，无可见横向溢出。
- 浏览器抽查 1280px 设置页：左侧分组导航存在，当前面板正常显示，无可见横向溢出。

### 0.3 2026-06-27 第三批已完成

第三批补齐了部分空状态的直接行动入口，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase E 设定库空状态 | 部分完成 | `CodexPage` 的人物空状态增加“生成角色”按钮，世界观空状态增加“生成世界观”按钮，并滚动到对应生成器。 |
| Phase E 大纲空状态 | 完成核心 | `OutlineEditor` 的空状态增加“AI 排大纲”按钮，与页头主动作一致。 |
| Phase E 伏笔空状态 | 完成核心 | `ForeshadowBoard` 的空状态直接嵌入 `RegisterForm`，可从空状态登记第一条伏笔。 |

第三批涉及的重点文件：

- `apps/web/components/codex/CodexPage.tsx`
- `apps/web/components/outline/OutlineEditor.tsx`
- `apps/web/components/foreshadow/ForeshadowBoard.tsx`

第三批已验证：

- `cd apps/web && pnpm lint`
- `cd apps/web && pnpm typecheck`
- `cd apps/web && pnpm test`（468 passed）
- `cd apps/web && pnpm build`

### 0.4 2026-06-27 第四批已完成

第四批完成了项目列表筛选与密度调节的无契约版本；由于当前 `ProjectResponse` 没有更新时间 / 待审稿统计，本批只做前端可确定的搜索、轻筛选、标题/题材排序和视图密度切换。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase G 项目列表筛选 | 核心完成 | 首页新增 `ProjectLibrary` client 组件；支持按标题、题材、logline、theme 搜索；支持“全部 / 有题材 / 未归类”轻筛选。 |
| Phase G 项目排序 | 部分完成 | 支持按标题、按题材排序；按题材排序时未归类作品置后。 |
| Phase G 密度调节 | 完成 | `ProjectCard` 增加 `compact` 模式；首页支持卡片 / 紧凑列表切换，并用 `localStorage` 保存偏好。 |
| Phase G 空结果状态 | 完成 | 筛选无结果时显示行动导向空状态，提供“清空筛选”和“新建作品”。 |

第四批新增 / 重点文件：

- `apps/web/components/projects/ProjectLibrary.tsx`
- `apps/web/lib/projects/projects.ts`
- `apps/web/lib/projects/projects.test.ts`
- `apps/web/components/ProjectCard.tsx`
- `apps/web/app/page.tsx`

第四批已验证：

- `cd apps/web && pnpm lint`
- `cd apps/web && pnpm typecheck`
- `cd apps/web && pnpm test`（471 passed）
- `cd apps/web && pnpm build`
- 浏览器抽查 390px 首页：搜索控件存在，无可见横向溢出。

### 0.5 2026-06-27 第五批已完成

第五批完成了夜读模式的第一版；仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase F 主题变量 | 完成 | `globals.css` 增加 `paper` / `night` 两套 CSS token；Tailwind 阴影改为读取 `--shadow-paper`，冲突高亮也改为变量驱动。 |
| Phase F 偏好开关 | 完成 | 新增 `ThemeToggle`，接入 `AppShell` 顶栏；用 `localStorage` 保存 `ww.theme_mode`，支持纸感 / 夜读双向切换。 |
| Phase F 测试 | 完成 | 新增 `lib/ui/theme.ts` 纯逻辑与 `theme.test.ts`，覆盖主题合法性、兜底、切换和文案。 |

第五批新增 / 重点文件：

- `apps/web/components/ThemeToggle.tsx`
- `apps/web/lib/ui/theme.ts`
- `apps/web/lib/ui/theme.test.ts`
- `apps/web/app/globals.css`
- `apps/web/tailwind.config.ts`

### 0.6 2026-06-27 第六批已完成

第六批完成了夜读模式防闪增强和一批复杂表单收敛，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase F 首屏防闪 | 完成 | 新增 `ThemeScript`，在 React 水合前读取 `ww.theme_mode` 并设置 `html[data-theme]`，减少夜读模式刷新时的浅色闪烁。 |
| Phase A Kimi OAuth 收敛 | 完成核心 | `KimiCodeOauth` 改用 `SectionHeader` / `StatusNote` 展示说明、授权指引和错误状态。 |
| Phase A 生成器表单收敛 | 部分完成 | `CharacterGenerator` 和 `WorldGenerator` 改用 `Field` / `TextInput` / `TextArea` / `SectionHeader` / `StatusNote`。 |

第六批新增 / 重点文件：

- `apps/web/components/ThemeScript.tsx`
- `apps/web/components/settings/KimiCodeOauth.tsx`
- `apps/web/components/generation/CharacterGenerator.tsx`
- `apps/web/components/generation/WorldGenerator.tsx`
- `apps/web/lib/ui/theme.ts`
- `apps/web/lib/ui/theme.test.ts`
- `apps/web/app/layout.tsx`

### 0.7 2026-06-27 第七批已完成

第七批继续收敛卡片内部编辑控件，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase A 角色卡编辑控件 | 完成核心 | `CharacterCardItem` 的角色名 / 人物弧光就地编辑改用统一 `TextInput`。 |
| Phase A 伏笔卡控件 | 完成核心 | `ForeshadowCard` 的进展输入改用 `TextInput`，状态变更与“记”按钮改用统一 `Button`。 |
| Phase A 输入尺寸 | 完成 | `TextInput` 增加 `controlSize="sm" | "md"`，便于卡片、表格等紧凑区域复用。 |

第七批重点文件：

- `apps/web/components/ui/TextInput.tsx`
- `apps/web/components/generation/CharacterCardItem.tsx`
- `apps/web/components/foreshadow/ForeshadowCard.tsx`

### 0.8 2026-06-27 第八批已完成

第八批收敛低频表单页和审稿内联表单，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase A 模板页表单 | 完成核心 | `TemplatesManager` 的新建模板表单改用 `Field` / `TextInput` / `TextArea` / `SectionHeader` / `Button`；删除按钮改用统一危险按钮。 |
| Phase A 多章链表单 | 完成核心 | `ChainStarter` 的起始章号、连续章数和提交按钮改用统一组件。 |
| Phase A 大纲顶部控件 | 完成核心 | `OutlineEditor` 的卷筛选和卷号输入改用 `Select` / `TextInput` 紧凑尺寸。 |
| Phase A 审稿内联伏笔登记 | 完成核心 | `ForeshadowSuggestions` 的内联登记表单改用 `Field` / `TextInput` / `TextArea`。 |
| Phase A 控件尺寸 | 完成 | `TextArea` / `Select` 增加 `controlSize="sm" | "md"`，与 `TextInput` 保持一致。 |

第八批重点文件：

- `apps/web/components/templates/TemplatesManager.tsx`
- `apps/web/components/chain/ChainStarter.tsx`
- `apps/web/components/outline/OutlineEditor.tsx`
- `apps/web/components/review/ForeshadowSuggestions.tsx`
- `apps/web/components/ui/TextArea.tsx`
- `apps/web/components/ui/Select.tsx`

### 0.9 2026-06-27 第九批已完成

第九批完成审稿页窄屏布局微调和验收状态提示统一，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase B 审稿页窄屏布局 | 完成核心 | `ReviewReport` 在小屏改为自然纵向流：正文编辑区在上、报告/裁决/验收区在下；桌面仍保持左右两栏和右侧独立滚动。 |
| Phase B 验收区状态 | 完成核心 | `AcceptPanel` 的未决阻止、可验收、未审稿提示改用统一 `StatusNote`，阻止态边框更明确。 |
| Phase B 摘要动作 | 完成 | `ReviewSummaryRail` 的“跳到下一条未裁决”改用统一 `Button`。 |
| Phase B 节奏图溢出 | 完成 | `BeatMap` 增加内部横向滚动容器，避免小屏下节拍柱撑出页面。 |

第九批重点文件：

- `apps/web/components/review/ReviewReport.tsx`
- `apps/web/components/review/AcceptPanel.tsx`
- `apps/web/components/review/ReviewSummaryRail.tsx`
- `apps/web/components/review/BeatMap.tsx`

### 0.10 2026-06-27 第十批已完成

第十批完成当前伏笔页的视觉微修，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase E/页面微修 伏笔登记 | 完成 | `RegisterForm` 增加受控展开能力；`ForeshadowBoard` 的页头只保留“登记伏笔”按钮，表单改为页头下方完整面板，避免小屏挤在 action 区。 |

第十批重点文件：

- `apps/web/components/foreshadow/ForeshadowBoard.tsx`
- `apps/web/components/foreshadow/RegisterForm.tsx`

### 0.11 2026-06-27 第十一批已完成

第十一批继续增强伏笔页扫描效率，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| 页面微修 伏笔概览 | 完成 | `ForeshadowBoard` 增加 OPEN / PARTIAL / CLOSED / OVERDUE 状态概览条，显示数量与占比，移动端两列、桌面四列。 |
| 伏笔纯逻辑 | 完成 | `lib/foreshadow/board.ts` 增加 `countByStatus`，与 `groupByStatus` 使用同一兜底规则；补单测。 |

第十一批重点文件：

- `apps/web/components/foreshadow/ForeshadowBoard.tsx`
- `apps/web/lib/foreshadow/board.ts`
- `apps/web/lib/foreshadow/board.test.ts`

### 0.12 2026-06-27 第十二批已完成

第十二批优化伏笔页移动端滚动体验，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| 页面微修 伏笔移动端 | 完成 | `ForeshadowBoard` 小屏改为自然纵向滚动，桌面继续固定高度看板；`KanbanColumn` 小屏不再内部滚动，卡片顺着页面流展示。 |

第十二批重点文件：

- `apps/web/components/foreshadow/ForeshadowBoard.tsx`
- `apps/web/components/foreshadow/KanbanColumn.tsx`

### 0.13 2026-06-27 第十三批已完成

第十三批优化伏笔页状态命名可读性，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| 页面微修 伏笔状态中文化 | 完成 | `LANE_LABELS` 改为作者可读的“待推进 / 推进中 / 已回收 / 已逾期”；看板概览、泳道标题、状态转移按钮显示中文主标签，同时保留 `OPEN` 等状态码作为小字。 |

第十三批重点文件：

- `apps/web/lib/foreshadow/board.ts`
- `apps/web/lib/foreshadow/board.test.ts`
- `apps/web/components/foreshadow/ForeshadowBoard.tsx`
- `apps/web/components/foreshadow/KanbanColumn.tsx`
- `apps/web/components/foreshadow/ForeshadowCard.tsx`

### 0.14 2026-06-28 第十四批已完成

第十四批优化技能库只读注册表的信息层级，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase E 技能库辅助信息 | 完成 | `SkillsPage` 增加注册表概览、来源计数、能力档位统计和写入边界提示；右侧注册表列表保留读/写表详情，视觉层级更清晰。 |
| 技能库纯逻辑 | 完成 | `lib/skills/skills.ts` 增加 `summarizeSkills`，统计总数、可写/只读、来源、档位与读写表集合；补单测。 |

第十四批重点文件：

- `apps/web/components/skills/SkillsPage.tsx`
- `apps/web/lib/skills/skills.ts`
- `apps/web/lib/skills/skills.test.ts`

### 0.15 2026-06-28 第十五批已完成

第十五批一次性收尾剩余可做的 UI 微修，仍未修改后端 API / OpenAPI 契约。

| 阶段 | 状态 | 已完成内容 |
|---|---|
| Phase B 审稿密度 | 完成 | 冲突列表按类型折叠；有未裁决项的分组默认展开，已处理分组默认收起，长报告扫描压力更低。 |
| Phase B 验收成功态 | 完成 | `AcceptPanel` 的成功态改为回执式布局，突出版本、摘要、裁决数量和下一章入口。 |
| Phase C 写作台底栏 | 完成 | 写作台底部工具条改为 sticky、按钮改小尺寸，小屏下操作区更紧凑，保存状态独立成行。 |
| Phase D 设置页说明 | 完成 | 路由面板补充提交边界说明；API Key 面板增加已保存/可配置/测试结果统计和每行状态说明。 |
| Phase D OAuth 密度 | 完成 | Kimi OAuth 面板去掉多余外边距，授权码与授权按钮改为更紧凑的响应式布局，并补充加密保存说明。 |

第十五批重点文件：

- `apps/web/components/review/ReviewReport.tsx`
- `apps/web/components/review/AcceptPanel.tsx`
- `apps/web/components/workbench/Workbench.tsx`
- `apps/web/components/settings/ProvidersSettings.tsx`
- `apps/web/components/settings/KimiCodeOauth.tsx`

### 0.16 2026-06-28 后端补齐完成

用户要求把 Phase G 的后端依赖也补上，本批新增项目列表元数据契约，并完成前后端消费。

| 阶段 | 状态 | 已完成内容 |
|---|---|---|
| Phase G 后端元数据 | 完成 | `ProjectResponse` 增加 `updated_at` 和 `pending_review_count`；`chapters` 新增 `updated_at` 迁移，支持草稿重复保存后的真实编辑时间。 |
| Phase G 项目列表增强 | 完成 | 首页默认按“最近编辑”排序，新增“待审稿”筛选；作品卡显示最近编辑时间和待审稿徽标。 |
| 契约同步 | 完成 | 已更新 `memory/contracts.md` C3 扩展，并重生成前端 OpenAPI 类型。 |

本批重点文件：

- `packages/db/ww_db/models.py`
- `packages/db/migrations/versions/8c1d2e3f4a5b_chapters_updated_at.py`
- `packages/core/ww_core/domain/project_repo.py`
- `apps/api/ww_api/schemas/projects.py`
- `apps/web/components/projects/ProjectLibrary.tsx`
- `apps/web/components/ProjectCard.tsx`
- `apps/web/lib/projects/projects.ts`

### 0.17 剩余说明

| 阶段 | 状态 |
|---|---|
| Phase A | 已完成；正文编辑器、命令面板搜索、文件上传、checkbox/radio 保留为合理特化控件。 |
| Phase B | 已完成；审稿页信息架构、窄屏布局、冲突密度和验收态均已收尾。 |
| Phase C | 已完成；顶部工具条、移动端抽屉入口、本章控制台和底部工具条均已收尾。 |
| Phase D | 已完成；设置页控制台化、Provider 行、OAuth 密度和状态说明均已收尾。 |
| Phase E | 已完成；空状态行动入口与技能库概览均已收尾。 |
| Phase F | 已完成；夜读模式、防闪脚本和基础视觉 token 均已收尾。 |
| Phase G | 已完成；最近编辑排序、待审稿筛选和卡片元数据展示均已接真实后端字段。 |

结论：本轮 UI 改进计划内事项已收尾；后续建议转入代码整理、提交准备，或切换到 `PROGRESS.md` 中的 CR 整改项。

---

## 1. 目标与非目标

### 1.1 目标

1. **让长期写作更顺手**：减少写作台和审稿页的认知负担，把「下一步该做什么」放在最显眼位置。
2. **收敛表单与状态组件**：在已有 `Button`/`Badge` 基础上继续抽出输入控件与状态提示，降低样式漂移。
3. **提升复杂页面的信息层级**：设置、审稿、写作台等高密度页面要更像生产力工具，而不是卡片堆叠。
4. **强化响应式体验**：桌面保持高信息密度；平板/手机优先保留核心动作，次要入口折叠。
5. **守住纸感美术方向**：继续使用暖米白、朱砂、细线、衬线标题；避免大面积渐变、夸张阴影和营销式 hero。

### 1.2 非目标

- 不修改后端 API / OpenAPI schema。
- 不新增业务功能，例如权限、多用户、真实任务队列。
- 不改 `UX_SPEC.md` 的整体视觉方向。
- 不引入重型 UI 框架；继续使用 Tailwind + 本地轻量组件。

---

## 2. 现状评估

### 2.1 已经改善的部分

- 全局导航、项目卡片、工具箱、大纲、设定库、伏笔板、审稿页的基础视觉已经统一。
- `lucide-react` 图标已接入，旧字形符号大多已替换为语义图标。
- 统一组件已落地：
  - `apps/web/components/ui/Button.tsx`
  - `apps/web/components/ui/Badge.tsx`
  - `apps/web/components/ui/Card.tsx`
  - `apps/web/components/ui/EmptyState.tsx`
  - `apps/web/components/ui/PageHeader.tsx`
  - `apps/web/lib/ui/variants.ts`
- 首页、设置、新建、规则、审稿、文风、伏笔等页面已浏览器验收：CSS 正常加载，无页面级横向溢出。

### 2.2 仍有改进空间

| 区域 | 问题 | 影响 |
|---|---|---|
| 写作台移动端 | 顶部 AI 工具条横向滚动，低频入口与高频入口同权 | 小屏写作时操作成本高 |
| 审稿页右侧报告 | 四审报告纵向堆叠，主次优先级还不够强 | 作者不容易第一眼知道必须先处理什么 |
| 设置页 | 表单清楚但纵向空间偏散，像普通表单而非控制台 | 配置效率一般，扫描成本偏高 |
| 表单控件 | input/select/textarea 样式仍散在各组件中 | 后续继续迭代容易样式漂移 |
| 空状态 | 已统一视觉，但行动按钮覆盖不足 | 新用户不知道下一步从哪里开始 |
| 侧栏 + 顶部工具条 | 两套导航并存时视觉权重接近 | 页面位置与高频动作的职责边界不够清楚 |
| 夜间写作 | 仅有纸感浅色主题 | 长时间写作时缺少低亮模式 |

---

## 3. 总体策略

### 3.1 组件先行

继续扩展 `apps/web/components/ui/`，先抽象可复用组件，再替换页面内散落样式。建议新增：

- `Field.tsx`：label/help/error 包装。
- `TextInput.tsx`：统一 input。
- `TextArea.tsx`：统一 textarea。
- `Select.tsx`：统一 select。
- `StatusNote.tsx`：统一信息/警告/错误提示。
- `SectionHeader.tsx`：用于卡片或面板内部标题，避免滥用页面级 `h1`/`PageHeader`。
- `SegmentedControl.tsx`：用于 tab / 模式切换，例如设定库 tabs、审稿视图切换。

### 3.2 页面分层

页面按三层组织：

1. **PageHeader**：页面标题、简短说明、最高优先级操作。
2. **Work Surface**：主要任务区，避免卡片套卡片。
3. **Assistive Panels**：辅助信息、状态、历史、报告，必要时折叠。

### 3.3 动作优先级

每页最多一个朱砂主按钮。其余动作按如下规则：

- 主动作：`Button variant="primary"`。
- 次动作：`secondary`。
- 轻量动作：`ghost`。
- 状态切换：`SegmentedControl` 或 `Badge` + button。
- 危险动作：`danger`。

### 3.4 响应式策略

- ≥1280：保持三栏或双栏高密度布局。
- 1024–1279：辅助面板收窄或折叠。
- <1024：侧栏抽屉化，顶部 AI 工具条只保留 2–3 个高频动作，其余进入「更多」菜单。

---

## 4. 分阶段实施计划

## Phase A · 表单与状态组件收敛（部分完成）

**目标**：把散落在页面里的 input/select/textarea/status 样式统一，降低后续维护成本。

### A1. 新增表单基础组件

新增文件：

- `apps/web/components/ui/Field.tsx`
- `apps/web/components/ui/TextInput.tsx`
- `apps/web/components/ui/TextArea.tsx`
- `apps/web/components/ui/Select.tsx`
- `apps/web/components/ui/StatusNote.tsx`

建议 API：

```tsx
<Field label="书名（必填）" help="用于作品库和写作台标题">
  <TextInput value={title} onChange={handleTitleChange} />
</Field>
```

```tsx
<StatusNote variant="warning" title="验收前请确认">
  还有未裁决冲突，验收事务会被阻止。
</StatusNote>
```

需要替换的高收益文件：

- `apps/web/components/ProjectWizard.tsx`
- `apps/web/components/settings/ProvidersSettings.tsx`
- `apps/web/components/settings/KimiCodeOauth.tsx`
- `apps/web/components/rules/RulesPage.tsx`
- `apps/web/components/foreshadow/RegisterForm.tsx`
- `apps/web/components/toolbox/GeneratorRunner.tsx`
- `apps/web/components/style/StyleUpload.tsx`

### A2. 扩展 variant helper

修改：

- `apps/web/lib/ui/variants.ts`

新增：

- `fieldClass`
- `inputClass`
- `statusNoteClass`
- `segmentedClass`

测试：

- `apps/web/lib/ui/variants.test.ts`

新增断言：

- error 状态有 `border-conflict` 和文本提示。
- warning 状态不只靠颜色，有图标位。
- disabled/readOnly 状态视觉可区分。

### A3. 验收标准

- `rg "focus:border-cinnabar|rounded border border-line bg-bg px" apps/web/components` 结果明显减少。
- 所有表单控件 focus ring 一致。
- `pnpm lint` / `pnpm typecheck` / `pnpm test` / `pnpm build` 全绿。

---

## Phase B · 审稿页信息架构优化（核心完成）

**目标**：让作者优先处理「必须裁决」的信息，降低四审报告堆叠带来的扫描成本。

### B1. 右侧报告改为分段面板

新增组件：

- `apps/web/components/review/ReviewSectionPanel.tsx`
- `apps/web/components/review/ReviewSummaryRail.tsx`

结构建议：

```tsx
<ReviewSummaryRail>
  <ReviewSectionPanel kind="continuity" status="conflict" count={3} defaultOpen />
  <ReviewSectionPanel kind="foreshadow" status="ok" />
  <ReviewSectionPanel kind="pace" status="warning" />
  <ReviewSectionPanel kind="style" status="incomplete" />
</ReviewSummaryRail>
```

交互规则：

- 有未裁决冲突的 section 默认展开。
- 无问题 section 默认折叠，只显示状态摘要。
- `incomplete` 用 warning badge，不用弱提示文字。
- 在窄屏下，报告区变成正文下方的 accordion。

修改文件：

- `apps/web/components/review/ReviewReport.tsx`
- `apps/web/components/review/ForeshadowSuggestions.tsx`
- `apps/web/components/review/PacePanel.tsx`
- `apps/web/components/style/StylePanel.tsx`

### B2. 冲突裁决区强化“下一步”

改进点：

- 未裁决冲突卡顶部增加编号：`冲突 1 / 3`。
- 「跳到下一条未裁决」固定在报告区顶部，不随列表滚走。
- 所有冲突裁决完成后，验收区主按钮视觉提升。
- 手改输入框只在选择「手改」后展开，且加 help 文案。

修改文件：

- `apps/web/components/review/ConflictCard.tsx`
- `apps/web/components/review/AcceptPanel.tsx`
- `apps/web/components/review/ReviewReport.tsx`

### B3. 验收标准

- 有冲突时，首屏能看到：冲突数量、下一条未裁决入口、至少一张冲突卡。
- 无冲突时，右侧报告区不显得空，直接引导验收。
- 键盘 tab 顺序：重审 → 正文编辑 → 报告区 → 裁决按钮 → 验收。
- 桌面和 390px 宽度均无页面级横向溢出。

---

## Phase C · 写作台与顶部 AI 工具条优化（主体完成）

**目标**：把写作台的核心动作留在手边，把低频工具收进更轻的菜单。

### C1. 顶部工具条分主动作和更多菜单

当前问题：`写本章 / 审稿 / 大纲 / 设定库 / 工具箱` 在小屏同排滚动。

改法：

- 桌面保留完整工具条。
- <1024 宽度只显示：
  - 写本章
  - 审稿
  - 更多
- 更多菜单内放：
  - 大纲
  - 设定库
  - 工具箱

新增组件：

- `apps/web/components/AiToolbarMoreMenu.tsx`

修改文件：

- `apps/web/components/AiToolbar.tsx`
- `apps/web/lib/nav/ai-tools.ts`

实现建议：

- 不引入 popover 库，先用简单 client component + button + absolute menu。
- `Esc` 关闭。
- 点击菜单项后关闭。
- `aria-expanded` / `aria-controls` / `role="menu"`。

### C2. 写作台三栏响应式增强

当前方向：

- 桌面三栏正常。
- 小屏保留正文为主，目录/助手转为抽屉或折叠面板。

修改文件：

- `apps/web/components/workbench/Workbench.tsx`
- `apps/web/components/workbench/ChapterList.tsx`
- `apps/web/components/workbench/ChapterAssistant.tsx`

改进点：

- 小屏默认隐藏目录和助手。
- 顶部或底部加两个 icon button：目录 / 助手。
- 打开后覆盖式抽屉，不挤压正文。
- 正文编辑区最小高度根据 viewport 调整。

### C3. 本章指令区域更像“生成控制台”

改进点：

- 本章指令折叠区增加 `SectionHeader`。
- 风格预设 chips 改用 `SegmentedControl` 或统一小按钮。
- “写本章”按钮旁显示生成状态，避免状态只在正文流里体现。

### C4. 验收标准

- 390px 宽度下无需横向滚动即可看到写章和审稿。
- 目录/助手可通过按钮打开，且关闭后焦点回到触发按钮。
- `prefers-reduced-motion` 下抽屉无强动画。

---

## Phase D · 设置页控制台化（核心完成）

**目标**：把模型与提供商页从普通表单改成高密度、易扫描的配置控制台。

### D1. 采用左右分组布局

当前结构：

- 能力档位路由
- Kimi Code OAuth
- 提供商凭据

建议结构：

```text
模型与提供商
├─ 左侧分组导航（路由 / OAuth / API Key）
└─ 右侧配置面板
```

桌面：

- 左侧 160px 分组导航。
- 右侧表单区。

窄屏：

- 分组导航改为 `SegmentedControl`。

修改文件：

- `apps/web/app/settings/providers/page.tsx`
- `apps/web/components/settings/ProvidersSettings.tsx`
- `apps/web/components/settings/KimiCodeOauth.tsx`

### D2. 提供商行做成配置表格

改法：

- 每个 provider 一行。
- 状态点 + provider 名 + masked key + key input + 操作按钮。
- 操作按钮固定右侧。
- 测试结果显示在行内下方，而不是另起视觉块。

### D3. 验收标准

- 1280 宽度下一屏可看到路由、OAuth、至少两个 provider 行。
- 未配置状态清楚，但不造成大面积空白。
- 不输入 API Key 时保存按钮 disabled 或给明确错误。

---

## Phase E · 空状态与首次使用引导（主体完成）

**目标**：让新用户知道下一步，而不是只看到“暂无”。

### E1. EmptyState 增加 action policy

修改：

- `apps/web/components/ui/EmptyState.tsx`

规范：

- 空状态必须包含：
  - `title`
  - `description`
  - 至少一个推荐动作，除非该动作确实不可用。

优先改造：

- `RulesPage`：新增第一条规则。
- `ForeshadowBoard`：登记第一条伏笔。
- `OutlineEditor`：AI 排大纲。
- `CodexPage`：生成角色 / 生成世界观。
- `SkillsPage`：只读页可不加主动作，但说明技能来源。

### E2. 首页项目空状态增强

改进点：

- 新作品为空时，直接展示“新建作品”主按钮。
- 若后续有模板库，可加次动作“从模板开始”。

### E3. 验收标准

- 每个空状态都能回答：为什么空、下一步做什么、点哪里开始。
- 空状态文案不超过 2 行正文，避免说明书感。

---

## Phase F · 夜读模式（完成第一版）

**目标**：支持长时间写作场景，降低夜间亮度刺激。

### F1. 增加主题变量

修改：

- `apps/web/app/globals.css`
- `apps/web/tailwind.config.ts`

新增暗色 token：

```css
[data-theme="night"] {
  --color-bg: #191715;
  --color-panel: #22201d;
  --color-ink: #eee4d4;
  --color-ink-soft: #b7aa98;
  --color-line: #3a342c;
  --color-cinnabar: #d16a5b;
}
```

### F2. 增加偏好开关

实现位置：

- 设置页加「夜读模式」开关。
- 或 AppShell 顶栏加 icon button。

持久化：

- 第一阶段用 `localStorage`。
- 后续若有用户设置 API，再同步到后端。

### F3. 验收标准

- 切换后所有页面背景、卡片、输入框、按钮、badge 均可读。
- 正文区域对比度仍满足 `UX_SPEC §10`。
- 不影响 SSR 水合；`suppressHydrationWarning` 已存在，但仍要避免闪烁过大。

---

## Phase G · 项目列表筛选与密度调节（核心完成）

**目标**：项目变多后，首页仍然可扫描。

### G1. 项目列表增加轻筛选

改进点：

- 搜索框：按标题/题材过滤。
- 筛选：全部 / 最近写作 / 有审稿待处理。
- 排序：最近编辑 / 创建时间 / 标题。

前置注意：

- 当前 `ProjectResponse` 是否包含更新时间需确认。若没有，不改 API 的前提下只能做标题/题材过滤。
- 若需要后端排序字段，另起 API 契约任务，不混入本 UI 计划。

修改文件：

- `apps/web/app/page.tsx`
- `apps/web/components/ProjectCard.tsx`
- 新增 `apps/web/components/projects/ProjectFilters.tsx`

### G2. 卡片密度调节

支持：

- 标准卡片
- 紧凑列表

实现：

- local state 或 localStorage 保存视图偏好。

### G3. 验收标准

- 20 个项目时首屏仍能快速定位。
- 超长标题不撑破布局。
- 筛选无结果时显示行动导向空状态。

---

## 5. 建议执行顺序

| 顺序 | 阶段 | 价值 | 风险 | 建议批次 |
|---|---|---:|---:|---|
| 1 | Phase A 表单与状态组件收敛 | 高 | 低 | 1 PR |
| 2 | Phase B 审稿页信息架构 | 高 | 中 | 1 PR |
| 3 | Phase C 写作台/工具条响应式 | 高 | 中 | 1 PR |
| 4 | Phase D 设置页控制台化 | 中 | 低 | 1 PR |
| 5 | Phase E 空状态行动化 | 中 | 低 | 可并入 A/D |
| 6 | Phase F 夜读模式 | 中 | 中 | 独立 PR |
| 7 | Phase G 项目列表筛选 | 中 | 中 | 视 API 情况决定 |

推荐先做 **A → B → C**。这三步最能提升“长期使用感”，且不会触碰后端契约。

---

## 6. 文件级修改清单

### 6.1 新增文件

```text
apps/web/components/ui/Field.tsx
apps/web/components/ui/TextInput.tsx
apps/web/components/ui/TextArea.tsx
apps/web/components/ui/Select.tsx
apps/web/components/ui/StatusNote.tsx
apps/web/components/ui/SectionHeader.tsx
apps/web/components/ui/SegmentedControl.tsx
apps/web/components/AiToolbarMoreMenu.tsx
apps/web/components/review/ReviewSectionPanel.tsx
apps/web/components/review/ReviewSummaryRail.tsx
apps/web/components/projects/ProjectFilters.tsx
```

### 6.2 重点修改文件

```text
apps/web/lib/ui/variants.ts
apps/web/lib/ui/variants.test.ts
apps/web/app/globals.css
apps/web/tailwind.config.ts
apps/web/components/AiToolbar.tsx
apps/web/components/AppShell.tsx
apps/web/components/workbench/Workbench.tsx
apps/web/components/review/ReviewReport.tsx
apps/web/components/review/ConflictCard.tsx
apps/web/components/review/AcceptPanel.tsx
apps/web/components/settings/ProvidersSettings.tsx
apps/web/components/rules/RulesPage.tsx
apps/web/components/foreshadow/ForeshadowBoard.tsx
apps/web/components/outline/OutlineEditor.tsx
```

### 6.3 尽量不动的文件

- `apps/web/lib/api/schema.d.ts`：本计划默认不改 OpenAPI，不应重生成。
- `apps/api/**`：本计划不改后端。
- `packages/**`：本计划不改领域逻辑。

---

## 7. 测试与验收

### 7.1 静态门禁

每个阶段完成后运行：

```bash
cd apps/web
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

### 7.2 浏览器验收页面

至少覆盖：

- `/`
- `/projects/new`
- `/settings/providers`
- `/projects/:id/write`
- `/projects/:id/review`
- `/projects/:id/outline`
- `/projects/:id/codex`
- `/projects/:id/foreshadow`
- `/projects/:id/rules`
- `/projects/:id/style`
- `/projects/:id/toolbox`

### 7.3 视口验收

至少覆盖：

- 1280×720：桌面默认。
- 1024×768：平板横向。
- 390×844：手机宽度。

断言：

- `document.documentElement.scrollWidth <= document.documentElement.clientWidth + 2`
- CSS stylesheet 正常加载。
- 主动作在首屏可见。
- 文字不溢出按钮或卡片。
- 抽屉/菜单可打开、关闭、键盘可达。

### 7.4 可访问性验收

- 所有 icon-only button 必须有 `aria-label`。
- 警告/错误状态必须有图标或文字，不只靠颜色。
- 焦点环可见。
- `Esc` 可关闭菜单/抽屉。
- 尊重 `prefers-reduced-motion`。

---

## 8. 风险与应对

| 风险 | 可能后果 | 应对 |
|---|---|---|
| 组件抽象过度 | 小改动变复杂 | 只抽已重复 3 次以上的模式 |
| 审稿页折叠隐藏重要信息 | 作者漏处理冲突 | 未裁决冲突默认展开，并保留顶部总数 |
| 小屏菜单增加操作步骤 | 高频动作变慢 | 小屏只把低频入口收进更多，写章/审稿常驻 |
| 夜读模式颜色不完整 | 某些页面不可读 | 所有颜色走 CSS 变量，避免硬编码色值 |
| 项目筛选需要 API 字段 | UI 计划牵出后端契约 | 先做纯前端标题/题材过滤；后端字段另开任务 |

---

## 9. 完成定义

整体计划完成时应满足：

1. 表单控件、状态提示、页面 header、空状态、按钮、徽标均有统一组件。
2. 审稿页能清楚区分：必须处理、建议处理、已通过。
3. 写作台在 390px 宽度下可完成核心操作：写本章、停止、审稿、查看目录/助手。
4. 设置页在桌面上更像配置控制台，减少纵向滚动。
5. 所有阶段门禁通过：lint/typecheck/test/build。
6. 浏览器验收覆盖桌面和平板/手机宽度，无页面级横向溢出。

---

## 10. 推荐第一批实施任务

建议下一次直接做以下 6 个任务，控制范围且收益明显：

1. 新增 `Field/TextInput/TextArea/Select/StatusNote`。
2. 替换 `ProjectWizard`、`RulesPage`、`ProvidersSettings` 的表单控件。
3. 新增 `ReviewSectionPanel`，把审稿右侧四审状态改成 accordion。
4. 新增 `AiToolbarMoreMenu`，优化 <1024 宽度工具条。
5. 给 `EmptyState` 统一补推荐 action。
6. 跑完整前端门禁 + 浏览器验收并记录截图结论。