Files

Yaojia Wang 90a66437d7 feat: improve app ui and project metadata

2026-06-28 07:31:20 +02:00

36 KiB

Raw Blame History

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"

第七批重点文件：

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"

第八批重点文件：

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 目标

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

页面按三层组织：

PageHeader：页面标题、简短说明、最高优先级操作。
Work Surface：主要任务区，避免卡片套卡片。
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：

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

<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

结构建议：

<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
提供商凭据

建议结构：

模型与提供商
├─ 左侧分组导航（路由 / 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：

[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 新增文件

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 重点修改文件

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 静态门禁

每个阶段完成后运行：

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. 完成定义

整体计划完成时应满足：

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

10. 推荐第一批实施任务

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

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

36 KiB Raw Blame History Unescape Escape

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

0. 实施记录

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

0.17 剩余说明

1. 目标与非目标

1.1 目标

1.2 非目标

2. 现状评估

2.1 已经改善的部分

2.2 仍有改进空间

3. 总体策略

3.1 组件先行

3.2 页面分层

3.3 动作优先级

3.4 响应式策略

4. 分阶段实施计划

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

A1. 新增表单基础组件

A2. 扩展 variant helper

A3. 验收标准

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

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

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

B3. 验收标准

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

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

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

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

C4. 验收标准

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

D1. 采用左右分组布局

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

D3. 验收标准

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

E1. EmptyState 增加 action policy

E2. 首页项目空状态增强

E3. 验收标准

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

F1. 增加主题变量

F2. 增加偏好开关

F3. 验收标准

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

G1. 项目列表增加轻筛选

G2. 卡片密度调节

G3. 验收标准

5. 建议执行顺序

6. 文件级修改清单

6.1 新增文件

6.2 重点修改文件

6.3 尽量不动的文件

7. 测试与验收

7.1 静态门禁

7.2 浏览器验收页面

7.3 视口验收

7.4 可访问性验收

8. 风险与应对

9. 完成定义

10. 推荐第一批实施任务

36 KiB

Raw Blame History