feat: improve app ui and project metadata

2026-06-28 07:31:20 +02:00
parent 3bd464d400
commit 90a66437d7
86 changed files with 4892 additions and 1108 deletions
--- a/docs/design/ui-improvement-plan.md
+++ b/docs/design/ui-improvement-plan.md
@@ -0,0 +1,965 @@
+# 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. 跑完整前端门禁 + 浏览器验收并记录截图结论。