DESIGN.md@docs · git:20260427.b843bc2 · 2026-04-27 · sha256 c6353b46a9d24967
DESIGN.md@docs git:20260427.b843bc2A
Immutable. This exact content never changes and is served at /api/v1/blob/c6353b46a9d24967.
# Forge — 设计文档 (DESIGN.md)
**版本:** v2026.04.27-fupan-report-structure
**日期:** 2026-04-27
**状态:** 已确认
---
## 迭代历史摘要
### v2026.04.27-fupan-report-structure — Fupan 复盘报告结构优化
- 最终复盘不再生成“仪表盘速览”和“会话脉络”，阅读入口从图表概览改为短叙事 + 诊断 + 知识点。
- “工作叙事”必须是短段落，不再以阶段列表、精力分布或 token 图展示。
- Prompt 诊断去掉严重度颜色，避免批改感；每条只保留“表达问题”和“低关键词版 / 进阶版”表达优化。
- “行为诊断”承接原模式诊断和决策复盘，专注用户在 AI coding 协作中的低效行为、成因和修复建议。
- 知识拓展按单个知识点组织，并统一呈现“是什么 / 怎么用 / 延伸学习”。
- 每个展开知识模块顶部增加一张学习图，帮助用户把关键知识转成可回看的视觉记忆。
- Workbench 用户补充反馈成为最终内容的显式约束，用来校准调研重点、解释深度和 TLDR/SOP，而不是只作为提交备注展示。
- TLDR 移到全文最后，作为复习卡，只沉淀知识、表达优化和协作 SOP。
### v2026.04.25-fupan-workbench-polish — Fupan Workbench 阅读与队列体验优化
- 首页时间统一按中国上海时区语义呈现，并在顶部显示最近刷新时间。
- 已完成复盘不再停留在顶部任务队列；用户从历史复盘区回看结果。
- “表达待优化原话”改为阅读优先的 quote block，提升字号、行高和问题/建议说明可读性。
- 详情页左侧升级为“本篇目录 + 学到的知识 + 源文件”，目录支持点击跳转。
- 无待处理任务时隐藏空任务面板，让历史复盘直接成为首页主体。
- Markdown 图片支持点击放大，用于查看仪表盘、流程图和截图细节。
- 左侧“学到的知识”改为有编号的学习地图，降低大面积蓝色标签带来的视觉噪音。
- 最终复盘正文最后增加 TLDR，让用户读完后获得可记忆、可迁移的知识、表达优化和协作 SOP。
### v2026.04.24-fupan-workbench — Fupan Workbench 本地交互式复盘学习工作台
- 新增 Fupan Workbench 设计方向：**Local Knowledge Desk**。
- 新增首页工作台与复盘详情页设计规范。
- 新增学习知识点、学习深度选择、反馈提交、历史复盘列表、Markdown 阅读详情的组件规范。
- 新增三档学习深度的视觉表达：`了解 / 表达 / 复现`。
- 新增 Image 2 视觉稿门禁：所有前端设计必须先生成图片供用户确认。
- **变更影响**：`forge-fupan` 的复盘启动交互、历史复盘阅读体验、未来 workbench 前端实现。
---
## 一、产品美学定位
### 1.1 设计风格
**风格名称:** Local Knowledge Desk
**风格关键词:** 本地、安静、清楚、可信、低干扰、学习友好、开发者工具
**气质描述:**
Fupan Workbench 像一张干净的本地知识桌面：当前要处理的复盘任务放在桌面中央，历史复盘安静地排在后面。它不应该像运营后台，也不应该像营销网站；它应该让用户觉得“我可以在这里慢慢学明白”。
### 1.2 参考产品与借鉴
| 产品/形态 | 可借鉴点 | 不借鉴点 |
|---|---|---|
| Notion Wiki | 知识集中、侧边组织、最新版本可信 | 营销式大标题、过多装饰 |
| Readwise Reader | 阅读、标注、复习和重新遇见知识的感觉 | 消费内容流的复杂入口 |
| Obsidian | local-first、Markdown 文件、项目文件夹心智 | 图谱优先、过度插件化 |
| Docusaurus | 文档详情页目录、阅读结构、搜索心智 | 第一版不做复杂搜索和站点导航 |
### 1.3 设计原则
1. **当前任务优先** — 有待确认任务时，首页首屏必须优先服务这次复盘，不让历史列表抢注意力。
2. **学习内容优先** — 详情页先讲“发生了什么、我要学什么、下次怎么说”，工程证据放后。
3. **专业词先翻译** — 第一次出现的专业名词必须配套人话解释。
4. **选择像点菜，不像考试** — 知识点选择和深度选择要给用户掌控感，不能有批改感。
5. **本地可信** — 页面要明确这是本地服务、本地文件、本机可见，降低安全和隐私焦虑。
6. **克制，不装饰** — 不使用渐变英雄区、装饰圆球、大圆角卡片、营销插画。
7. **完成即归档** — 任务完成后从待办视野中消失，回到历史复盘；顶部只放需要用户或 AI 继续处理的事项。
---
## 二、设计体系 (Design Tokens)
### 2.1 颜色
#### Primitive Tokens
| Token | 值 | 用途 |
|---|---:|---|
| `--slate-950` | `#020617` | 极深文字 |
| `--slate-900` | `#0F172A` | 主文字 |
| `--slate-700` | `#334155` | 次级标题 |
| `--slate-500` | `#64748B` | 辅助文字 |
| `--slate-300` | `#CBD5E1` | 强边框 |
| `--slate-200` | `#E2E8F0` | 默认边框 |
| `--slate-100` | `#F1F5F9` | 浅背景块 |
| `--slate-50` | `#F8FAFC` | 页面背景 |
| `--white` | `#FFFFFF` | 面板背景 |
| `--blue-700` | `#1D4ED8` | 链接按下 |
| `--blue-600` | `#2563EB` | 主操作/焦点 |
| `--blue-50` | `#EFF6FF` | 选中背景 |
| `--amber-600` | `#D97706` | 当前任务强调 |
| `--amber-50` | `#FFFBEB` | 当前任务轻背景 |
| `--emerald-600` | `#059669` | 完成状态 |
| `--rose-600` | `#E11D48` | 错误/失败 |
#### Semantic Tokens
| Token | 值 | 用途 |
|---|---|---|
| `--color-bg` | `var(--slate-50)` | 页面背景 |
| `--color-surface` | `var(--white)` | 工作台面板 |
| `--color-surface-muted` | `var(--slate-100)` | 次级背景 |
| `--color-text` | `var(--slate-900)` | 主文字 |
| `--color-text-muted` | `var(--slate-500)` | 辅助文字 |
| `--color-border` | `var(--slate-200)` | 默认边框 |
| `--color-border-strong` | `var(--slate-300)` | 强边框 |
| `--color-primary` | `var(--blue-600)` | 主按钮、焦点、链接 |
| `--color-primary-muted` | `var(--blue-50)` | 选中态背景 |
| `--color-current` | `var(--amber-600)` | 当前待确认任务 |
| `--color-current-muted` | `var(--amber-50)` | 当前任务背景 |
| `--color-success` | `var(--emerald-600)` | 成功状态 |
| `--color-error` | `var(--rose-600)` | 错误状态 |
### 2.2 字体
字体族：
- UI / 正文：`IBM Plex Sans`, `-apple-system`, `BlinkMacSystemFont`, `Segoe UI`, `sans-serif`
- 技术文本：`JetBrains Mono`, `SFMono-Regular`, `Consolas`, `monospace`
| 级别 | 字号 | 字重 | 行高 | 用途 |
|---|---:|---:|---:|---|
| Display | 28px | 650 | 1.2 | 详情页主标题 |
| H1 | 24px | 650 | 1.25 | 首页主标题 |
| H2 | 18px | 600 | 1.35 | 区块标题 |
| H3 | 15px | 600 | 1.4 | 卡片标题 |
| Body | 15px | 400 | 1.6 | 正文 |
| Body Strong | 15px | 550 | 1.6 | 重点正文 |
| Caption | 13px | 400 | 1.45 | 辅助说明 |
| Mono | 12px | 500 | 1.45 | 路径、状态、技术关键词 |
### 2.3 间距
基于 4px / 8px 比例尺。
| Token | 值 | 用途 |
|---|---:|---|
| `--space-1` | 4px | 紧贴元素 |
| `--space-2` | 8px | 小控件内部 |
| `--space-3` | 12px | 表单/标签间距 |
| `--space-4` | 16px | 卡片内部基础 |
| `--space-5` | 20px | 区块内部 |
| `--space-6` | 24px | 区块间距 |
| `--space-8` | 32px | 大区块间距 |
| `--space-10` | 40px | 页面上下留白 |
### 2.4 圆角
| Token | 值 | 用途 |
|---|---:|---|
| `--radius-sm` | 4px | 标签、状态 pill |
| `--radius-md` | 6px | 按钮、输入框、选择控件 |
| `--radius-lg` | 8px | 面板、知识点卡片 |
> 第一版不得使用超过 12px 的圆角。避免“软萌卡片化”。
### 2.5 阴影
阴影只用于层级，不用于装饰。
| Token | 值 | 用途 |
|---|---|---|
| `--shadow-sm` | `0 1px 2px rgba(15, 23, 42, 0.06)` | 悬浮面板 |
| `--shadow-md` | `0 8px 24px rgba(15, 23, 42, 0.08)` | 详情页目录 sticky 面板 |
### 2.6 Component Tokens
| Token | 值 | 用途 |
|---|---|---|
| `--panel-padding` | `24px` | 首页主面板 |
| `--panel-gap` | `20px` | 首页分区间距 |
| `--task-border` | `1px solid var(--color-current)` | 当前任务面板 |
| `--review-content-width` | `760px` | 详情页正文最大宽度 |
| `--sidebar-width` | `260px` | 详情页目录侧栏 |
| `--control-height` | `36px` | 按钮/选择控件高度 |
---
## 三、页面布局
### 3.1 首页工作台 `/`
#### 布局结构
```text
┌──────────────────────────────────────────────────────────────┐
│ Fupan Workbench 127.0.0.1:PORT · 刷新状态 │
├──────────────────────────────────────────────────────────────┤
│ 上海时间 2026-04-25 11:48 │
│ 复盘任务队列（仅待处理 / 已提交 / 失败） │
│ [当前] Fupan Workbench 设计复盘 · pending [切换] │
│ [待处理] MiniMax 治理复盘 · pending │
│ [已提交] 安全收口复盘 · submitted │
│ │
│ 当前展开任务 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 本次复盘背景 │ │
│ │ 用户原话摘录 / 表达待优化原话 │ │
│ │ │ │
│ │ 知识点卡片 │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ React │ │ API 限流 │ │ Git 工作流 │ │ │
│ │ │ 人话解释 │ │ 人话解释 │ │ 人话解释 │ │ │
│ │ │ 了解 表达 复现 │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ │ │ │
│ │ 反馈输入框 提交选择 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ 历史复盘 │
│ 项目筛选：全部 / info2action / forge-skills / skill-system │
│ ┌──────────┬────────────────────────┬──────────────────────┐ │
│ │ 日期 │ 标题 │ 学到的知识 │ │
│ │ 04-24 │ MiniMax 调用治理 │ API限流 · 熔断 │ │
│ └──────────┴────────────────────────┴──────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
#### 响应式行为
| 断点 | 布局变化 |
|---|---|
| ≥1200px | 内容最大宽度 1120px，居中；当前任务区卡片 3 列 |
| 768-1199px | 内容左右 24px；知识点卡片 2 列 |
| <768px | 单列布局；历史列表变成纵向条目；提交按钮 sticky 到任务区底部 |
#### 层级规则
1. 有 `pending_selection` task 时，任务队列和当前展开任务占首屏主要空间。
2. 多个 task 并存时，只展开一个完整任务表单；其他 task 用紧凑队列行展示。
3. 当前会话创建的 task 默认置顶，标记为“当前”，并自动展开。
4. 没有当前任务时，首页标题下直接显示历史复盘区。
5. 历史复盘不得做成大卡片瀑布流，使用紧凑列表，服务扫描。
6. `consumed` task 不进入首页任务队列；它的可见入口是历史复盘列表。
7. UTC task 时间必须转换为中国上海时间展示；从文件名解析出的本地复盘时间按上海本地墙上时间展示，不做二次偏移。
### 3.2 复盘详情页 `/review/{review_id}`
#### 布局结构
```text
┌──────────────────────────────────────────────────────────────┐
│ ← 返回工作台 项目 / 日期 / 打开源文件 │
├──────────────────┬───────────────────────────────────────────┤
│ 本篇目录 / 知识地图│ 标题 │
│ │ 这次发生了什么 │
│ - 发生了什么 │ 我的原话 → 真实问题 │
│ - 我选择学什么 │ 知识点：人话解释 / 关键词 / 下次怎么说 │
│ - 下次怎么说 │ 工程事实与证据附录 │
│ 学习地图 6个 │ │
│ 源文件 │ │
│ │ │
└──────────────────┴───────────────────────────────────────────┘
```
#### 响应式行为
| 断点 | 布局变化 |
|---|---|
| ≥1024px | 左侧目录 260px sticky，右侧正文最大 760px |
| 768-1023px | 左侧目录收为顶部横向锚点条 |
| <768px | 单列阅读；目录折叠为“本页目录”按钮 |
#### 阅读层级
详情页正文顺序必须遵循：
1. 工作叙事：用短段落说明这次发生了什么、目标是什么、关键转折是什么。
2. 表达与行为复盘：先看用户表达和协作行为哪里可以优化。
3. 知识拓展：按单个知识点讲“是什么 / 怎么用 / 延伸学习”。
4. AI 表现复盘：说明 AI 哪些地方做得不好，以及用户下次怎么辅助。
5. 速查手册：只保留概念 / 解释 / 场景三列表。
6. TLDR：最后给出需要记住的知识、表达优化和协作 SOP。
---
## 四、组件规范
### 4.1 当前任务面板
**用途:** 承载用户当前必须确认的学习选择。
**视觉表现:**
- 背景：`var(--color-surface)`
- 顶部有 3px Amber 细线或左侧 Amber 状态条。
- 边框：`1px solid var(--color-border)`
- 当前任务状态 pill 使用 `var(--color-current-muted)` 背景和 `var(--color-current)` 文本。
**状态:**
| 状态 | 视觉表现 |
|---|---|
| pending_selection | Amber 状态，提交按钮可用 |
| submitted | Emerald 状态，选择控件只读 |
| consumed | 不在首页任务队列展示；只保留本地 JSON 供追溯 |
| failed | Rose 状态，显示失败原因和对话内降级提示 |
| loading | 内容区骨架屏，提交按钮 disabled |
### 4.1.1 复盘任务队列
**用途:** 多个复盘 task 并存时，让用户知道还有哪些待处理任务，同时避免多个完整表单同时铺开。
**展示字段:**
- 任务标题
- 项目名
- 创建时间
- 状态：`当前` / `待处理` / `已提交` / `失败`
**视觉规则:**
- 队列行高度 44-52px，使用紧凑列表。
- 当前会话 task 用 Amber 状态标记并置顶。
- 其他 pending task 不展开，只显示一行摘要和“切换”操作。
- `submitted` task 只显示状态，不允许重复提交。
- `consumed` task 不显示，避免已完成复盘继续占据顶部注意力。
**交互规则:**
- 点击队列行切换当前展开 task。
- 一次只能展开一个 task。
- 切换 task 前如当前表单有未提交修改，需显示轻量确认。
### 4.2 知识点卡片
**用途:** 让用户选择是否学习某个知识点，以及学到什么深度。
**内容结构:**
1. 标题：知识点名称。
2. 人话解释：一句话说明它是什么。
3. 为什么与本次有关：一句话连接到会话。
4. 推荐深度：AI 推荐，但不自动替用户确认。
5. 深度选择：`了解 / 表达 / 复现`。
**状态:**
| 状态 | 视觉表现 |
|---|---|
| 默认未选 | 白底，Slate 边框，深度控件 disabled 或弱化 |
| 已选 | Blue 细边框，`--color-primary-muted` 局部背景 |
| hover | 边框加深，背景轻微变为 `#FBFDFF` |
| focus-visible | 2px Blue focus ring |
| disabled | 透明度 0.55，cursor `not-allowed` |
**交互规则:**
- 点击卡片复选框只切换是否学习，不改变深度。
- 深度选择是 segmented control，不用下拉菜单。
- 推荐深度只作为轻标签，例如“推荐：表达”，不得预设成强制选择。
### 4.3 深度选择控件
**用途:** 表达学习深度。
**三个选项:**
| 选项 | 辅助文案 | 适合场景 |
|---|---|---|
| 了解 | 知道它是什么 | 名词扫盲 |
| 表达 | 会用关键词指挥 AI | 协作提效 |
| 复现 | 能复述和自己做一遍 | 深度学习 |
**视觉表现:**
- 三段等宽 segmented control。
- 选中态使用 Blue 文本和浅 Blue 背景。
- 不使用红/黄/绿区分深度，避免像成绩等级。
### 4.4 反馈输入框
**用途:** 用户补充自己的学习期待。
**占位文案:**
> 例如：React 从零讲，不要假设我懂；API 限流我想学到能自己判断方案。
**状态:**
| 状态 | 视觉表现 |
|---|---|
| 默认 | 3 行高度，Slate 边框 |
| focus | Blue focus ring |
| error | Rose 边框 + 内联错误 |
| disabled | 灰底，不可编辑 |
### 4.5 历史复盘列表
**用途:** 快速扫描历史复盘。
**字段:**
- 日期
- 标题
- 项目
- 学到的知识
**禁止字段:**
- `My selections`
- 用户当时选择了哪些知识点
- 用户当时选择的学习深度
- selection JSON 状态或内部字段
**视觉规则:**
- 桌面端使用紧凑表格，不使用大卡片。
- 移动端每条变成两行列表项。
- “学到的知识”使用短标签展示，来源于最终复盘内容，而不是用户选择过程。
- 最新复盘可以有轻微 highlight，但不得抢当前任务区注意力。
### 4.6 复盘详情阅读区
**用途:** 阅读最终复盘。
**排版规则:**
- 正文最大宽度 760px。
- 段落行高 1.65。
- H2 上方间距 40px，下方 12px。
- 代码、路径、命令使用 JetBrains Mono。
- 表格外层允许横向滚动，避免移动端溢出。
- H2/H3 必须生成稳定锚点，供侧栏目录点击跳转。
- 图片默认按正文宽度展示；点击图片后进入 lightbox 放大查看。
### 4.6.1 Markdown 图片放大
**用途:** 让用户能看清复盘中的仪表盘、流程图和真实截图。
**视觉表现:**
- 正文图片仍保持 `var(--color-border)` 细边框和 8px 圆角。
- 图片 hover 时轻微提升边框/阴影，并显示 `zoom-in` 光标。
- 放大层使用半透明深色遮罩，图片居中，最大宽高不超过视口 92%。
- 右上角提供“关闭”按钮；图片说明来自 alt 文本。
**交互规则:**
- 点击正文图片打开放大层。
- 点击遮罩空白、关闭按钮或按 Escape 关闭。
- 放大图片不改变正文滚动位置。
### 4.6.2 复盘详情目录
**用途:** 让用户快速理解和定位一篇复盘的结构。
**视觉表现:**
- 桌面端位于左侧 sticky 侧栏顶部，标题为“本篇目录”。
- H2 为主目录项，H3 缩进 12px，字号略小。
- 当前版本不做滚动监听高亮，避免引入复杂状态；hover 和 focus-visible 必须明确。
- “学到的知识”和源文件路径位于目录下方，不得挤占目录第一屏。
**交互规则:**
- 点击目录项跳转到正文同名章节。
- 目标标题设置 `scroll-margin-top: 24px`，避免跳转后贴住视口顶部。
- 没有 H2/H3 时显示“这篇复盘没有可用目录”。
### 4.6.3 左侧学习地图
**用途:** 给用户一个轻量学习路线，而不是一串看不出关系的标签。
**视觉表现:**
- 标题行显示“学到的知识”和数量，例如 `6 个`。
- 知识点使用编号列表，每行 32-36px，高度稳定。
- 编号使用 Blue 文本和浅 Blue 背景；主题文本使用 Slate 主文字。
- 列表背景保持白色，不使用满宽大蓝色标签，避免左侧视觉过重。
**交互规则:**
- 第一版知识点不跳转；它只是复盘主题地图。
- 后续若 Review Index 能提供 topic → heading 映射，再升级为点击跳转。
### 4.7 专业名词解释块
**用途:** 第一次出现专业名词时，给用户建立理解。
**结构:**
```text
专业词：Circuit Breaker
人话：服务连续失败时先停一停，别一直撞墙。
这次为什么出现：MiniMax 429 后多个脚本继续请求，会造成重试风暴。
下次怎么说：给 provider 加 circuit breaker + recovery probe。
```
**视觉表现:**
- 左侧 3px Blue 线。
- 背景 `var(--color-primary-muted)`。
- 标题用 Mono 小标签，不使用醒目的警告色。
---
## 五、交互方案
### 5.1 启动与首页打开
**触发条件:** 用户触发 `/forge-fupan`。
**状态流转:**
```text
未启动 → 启动/复用服务 → 浏览器打开首页 → 当前任务区 loading → 展示 task
↓
启动失败 → 对话内降级
```
**交互要求:**
- 页面顶部显示服务状态，但不要求用户理解端口细节。
- 如果自动打开失败，对话中输出 URL，页面本身不需要做特殊处理。
### 5.2 提交学习选择
**触发条件:** 用户点击“提交学习选择”。
**状态流转:**
```text
pending_selection → submitting → submitted → AI 继续生成 → consumed
↓
failed → 可重试 / 对话内降级
```
**交互要求:**
- 提交按钮在未选择任何知识点时 disabled，并显示说明。
- 提交成功后控件变只读，避免用户以为还能修改当前生成任务。
- 成功反馈为内联状态，不使用打断式弹窗。
### 5.3 历史复盘浏览
**触发条件:** 用户打开首页或点击项目筛选。
**状态流转:**
```text
加载历史索引 → 显示项目分组/列表 → 点击条目 → 详情页
↓
解析失败 → 显示基础文件信息
```
**交互要求:**
- 默认显示全部项目，按日期倒序。
- 项目筛选使用 segmented control 或 pill，不使用复杂侧边栏。
- 第一版不做全文搜索，但可预留搜索框位置。
### 5.4 详情页阅读
**触发条件:** 用户点击历史复盘条目。
**状态流转:**
```text
打开详情页 → 加载 Markdown → 渲染目录和正文
↓
加载失败 → 显示文件路径和错误说明
```
**交互要求:**
- 左上角必须有“返回工作台”。
- 详情页顶部显示项目、日期、源文件路径。
- 源文件路径是文本或安全链接，不提供任意文件写入。
---
## 六、空状态与异常状态
### 6.1 空状态
| 场景 | 展示内容 | 操作引导 |
|---|---|---|
| 没有当前任务 | “当前没有待确认复盘。触发 forge-fupan 后，这里会出现学习地图。” | 无主按钮 |
| 没有历史复盘 | “还没有复盘记录。” | 提示完成一次 forge-fupan |
| 某项目无结果 | “这个项目下暂无复盘。” | 清除筛选 |
### 6.2 加载状态
| 场景 | 加载方式 |
|---|---|
| 当前任务加载 | 任务面板骨架屏，保留标题位置 |
| 历史列表加载 | 5 行列表骨架 |
| 详情页加载 | 正文骨架 + 左侧目录骨架 |
### 6.3 错误状态
| 场景 | 展示方式 | 恢复操作 |
|---|---|---|
| 服务 API 失败 | 内联错误条，Rose 文本 | 重试 |
| task JSON 损坏 | 当前任务区显示可理解错误 | 对话内降级 |
| Markdown 读取失败 | 详情页显示路径和失败原因 | 返回工作台 |
| 提交失败 | 反馈输入框上方显示错误 | 重试提交 |
---
## 七、响应式与无障碍
### 7.1 响应式规则
- 移动端不保留桌面表格结构，历史列表改为纵向条目。
- 当前任务区在移动端仍优先显示，不被历史列表挤下去。
- 深度选择控件移动端保持三段横排；若宽度不足，使用更短说明文字，不换成下拉。
- 详情页移动端隐藏左侧目录，改为顶部目录按钮。
### 7.2 无障碍规则
- 所有按钮、segmented control、复选框必须可键盘操作。
- focus-visible 必须可见，使用 Blue ring。
- 不只靠颜色表达状态；状态文本必须可读。
- 触摸目标最小 44px。
- 正文和按钮文字对比度必须达到 WCAG AA。
---
## 八、AI 模板痕迹规避
禁止：
- 紫蓝渐变背景。
- 三列彩色图标功能卡。
- 大圆角玻璃拟态卡片。
- Emoji 作为核心图标。
- 装饰性圆球、波浪、漂浮色块。
- “知识空白”“浪费轮次”这类批改感文案。
- Hero 区和营销 CTA。
允许：
- 克制的状态 pill。
- 细边框、浅背景、清楚的文字层级。
- 小面积 Amber 表示当前待确认任务。
- 小面积 Blue 表示链接、焦点、选中。
---
## 九、Image 2 视觉稿规范
### 9.1 强制规则
所有涉及前端页面、组件、状态或布局的设计工作，必须先用 Image 2 生成视觉稿，再进入实现。文字设计文档只负责定义规则，Image 2 视觉稿负责让用户确认实际观感。
### 9.2 覆盖范围
第一版至少生成：
- 首页工作台桌面端视觉稿。
- 复盘详情页桌面端视觉稿。
- 首页移动端关键布局视觉稿。
后续如新增重要状态，需补充：
- 当前任务 pending / submitted / failed 状态。
- 多个复盘任务并存的队列状态。
- 空历史复盘状态。
- Markdown 读取失败状态。
### 9.3 视觉稿要求
- 必须使用 DESIGN.md 中定义的 Local Knowledge Desk 风格。
- 必须使用 Slate + Blue + Amber 色彩关系。
- 必须展示真实信息层级，不做营销 hero。
- 历史复盘列表必须显示“学到的知识”，不得显示 “My selections”。
- 所有文字必须在容器内完整显示，不得重叠。
---
## 十、设计质量评估
### 10.1 0-10 交互审查
| 维度 | 当前分数 | 满分标准 | 差距 |
|---|---:|---|---|
| 信息架构 | 8 | 用户打开后 3 秒知道当前要不要处理任务，历史在哪里看 | 需实现时确保当前任务置顶 |
| 交互状态覆盖 | 8 | pending/submitted/consumed/failed/loading 全部有清晰状态 | 需工程实现完整状态机 |
| 用户旅程情感弧线 | 8 | 从“复盘很难读”变成“我在点选要学什么” | 需文案避免批改感 |
| AI 模板痕迹风险 | 9 | 无营销 hero、无渐变、无泛用卡片装饰 | 实现时避免大卡片视觉 |
| 设计体系对齐 | 8 | Token 完整，可直接映射 CSS variables | 需实现时禁止硬编码散值 |
| 响应式与无障碍 | 8 | 移动端可选择、可阅读、可键盘操作 | 需 QA 覆盖 375px/768px/1024px |
| 未决设计问题 | 7 | 搜索、标签编辑、实时生成进度都明确暂不做 | 后续 P1 可补 |
**综合评分:** B+
**放行结论:** 达到 L1 门控要求，可以进入工程设计/实现。
### 10.2 A-F 评分
| 类别 | 评分 | 说明 |
|---|---|---|
| 视觉层级 | A- | 当前任务、历史列表、详情正文层级清楚 |
| 排版 | B+ | 字体组合适合开发者学习工具 |
| 间距与布局 | B+ | 8px 体系明确，布局克制 |
| 颜色与对比度 | A- | Slate/Blue/Amber 语义清楚 |
| 交互状态 | B+ | 状态定义完整，需实现验证 |
| 响应式 | B | 移动端方案明确但待实现验证 |
| 内容质量 | A- | 明确人话解释、下次怎么说 |
| AI 模板痕迹 | A | 明确规避常见模板 |
| 动效 | B | 有意克制，避免花哨 |
| 性能感受 | B+ | 静态前端 + 本地 API，预期轻快 |
**总体等级:** B+
**门控:** 通过。L1 要求 B 以上。
---
## 十一、设计决策记录
| 议题 | 决定 | 原因 |
|---|---|---|
| 设计方向 | Local Knowledge Desk | 最贴合本地学习工作台，不把页面做成后台或营销站 |
| 页面数量 | 首页工作台 + 详情页 | 首页减少切换，详情页保证阅读专注 |
| 主色系统 | Slate + Blue + Amber | 中性可信，Blue 表示操作，Amber 表示当前待确认 |
| 字体 | IBM Plex Sans + JetBrains Mono | 兼顾阅读友好和开发者工具感 |
| 历史复盘展示 | 紧凑列表，不做卡片墙 | 历史复盘用于扫描和查找，不应抢当前任务 |
| 历史列表字段 | 显示“学到的知识”，不显示 My selections | 用户回看时关心学习成果，不关心当时如何选择 |
| 多任务并存 | 任务队列 + 单任务展开 | 支持多个复盘任务同时存在，但不让多个表单挤在首屏 |
| 深度选择 | 三段 segmented control | 比下拉更直观，符合“点菜”心智 |
| 详情页结构 | 学习内容在前，工程证据在后 | 解决现有复盘“太专业、入口太硬”的问题 |
| 前端视觉确认 | 所有前端设计先用 Image 2 出图 | 让用户先看实际观感，减少抽象文档误差 |
| 图谱/搜索 | 第一版不做 | 防止范围膨胀，保留后续优化空间 |
---
## 已知设计问题
### 待优化
- [ ] 历史复盘数量很多时，第一版项目筛选可能不够，需要后续补全文搜索。
- [ ] 详情页 Markdown 中复杂表格在移动端需要横向滚动样式验证。
- [ ] 生成进度第一版不做实时展示，用户可能不知道 AI 是否已经开始写；后续可加轻量进度状态。
- [ ] 主题暂只定义亮色模式，暗色模式后续再做。