
# Forge 浏览器扩展 UI 设计 Brief —— 给 AI / 设计师用

> **如何使用**:把这份文档完整粘到一次新 Claude / 设计 AI 对话里,或直接交给设计师。它包含了产品上下文、当前 UI 现状、要新增的屏幕、视觉约束。**不要让 AI 自己脑补 Forge 是什么** —— 这份就是 ground truth。
>
> 配套文档(可选,深入需求时再给):
> - `forge-team-workflow.md` —— 完整工作流(详细)


## 1. 一句话产品定位

**Forge 浏览器扩展是 Chrome MV3 侧边栏,一个 AI chat 入口,让公司 Design / Dev / QA 三个团队的日常协作在一个对话框里完成。它复用用户已登录的公司系统(Mantis / GitLab / PMDB / Teams)session,通过浏览器 DOM 提取拿数据,不需要 API token。**


## 2. 用户角色与高频任务

| 角色 | 高频任务(按频次) |
|---|---|
| **Design** | 1. 看 PMDB inbox 新需求 2. 起 PD 设计文档草稿 3. 整理评审反馈 4. 同类历史 epic 检索 |
| **Dev (技术负责人)** | 1. Review PD 提反馈 2. 起技术设计文档 3. 拆 GitLab 子 issue 4. 看周进度简报 |
| **Dev (模块负责人)** | 1. 看分给我的 issue 2. MR 摘要 3. 实现期写决策记录 |
| **QA** | 1. 起测试用例草稿 2. 起自动化脚本 3. 创建 / 跟踪 Mantis bug |
| **Manager** | (Phase 1 不专门设计,看 Dev 视图即可)Release dashboard 后期再做 |

**所有人共同的高频任务**:在 chat 里输入问题 / 指令,看 chat 输出,接受/编辑后落地到 pd-docs git 仓库。


## 3. 当前 UI 现状(必读)

### 已实现 —— Direction A 侧边栏 4 个 Tab

```
┌─────────────────────────────────────┐
│ ⚙ Forge          [⚙]                │  ← Header(logo + 设置图标)
├─────────────────────────────────────┤
│ Chat | Jobs | Connectors | Settings │  ← Tab Bar(badge 可挂未读)
├─────────────────────────────────────┤
│                                     │
│                                     │
│         (Tab 内容区)                │
│                                     │
│                                     │
└─────────────────────────────────────┘
```

宽度:约 400-500 px(Chrome 侧边栏典型尺寸),高度全屏。

### 当前 4 个 Tab 的现状

| Tab | 现状 |
|---|---|
| **Chat** | 类 ChatGPT 风格,消息列表 + 输入框;支持多会话切换 / fork / 删除;消息支持 markdown 渲染 |
| **Jobs** | 列定时 / 一次性 / cron 任务,基本 CRUD;skill picker 可挑技能;**已实现但可深化** |
| **Connectors** | 列已安装的连接器,每个有"批准脚本"按钮(SHA-256 校验);**已实现** |
| **Settings** | Forge URL / 登录 / 多 LLM provider 配置 / 保存测试按钮;**已实现** |

### 视觉系统约束(必须遵守)

- 设计语言定义在 `docs/design/`(repo 内的"Smith Extension"设计包,Direction A side-panel)
- **颜色 / 字体 / 间距 token 已定**,新屏幕沿用,**不引入新色板**
- 主背景 `var(--paper)`(米白色基底)
- 风格关键词:**轻量、低对比、文字优先、克制动效**
- **不要拟物 / 渐变 / 大圆角**;参考 Notion / Linear 的克制感


## 4. Phase 1 要新增 / 改造的 UI

下面是**本期要做的 UI 工作**。每条都注明优先级和范围。

### 4.1 ⭐ P0 —— Chat Tab 增强:"绑定 Epic 上下文"

**问题**:目前 chat 不知道你在哪个 epic 上下文里。Design 起 PD 时 chat 要能拉对应 epic 的 inbox 文件。

**新增 UI 元素**:
- **顶部"Epic 选择器"** —— Chat tab 上方一条窄条,左边显示当前绑定的 epic(如 `📌 EPIC-9981 SAML-SSO · 2026-Q3`),点击弹下拉切换 / 解绑 / 新建 epic
- **未绑定状态**:显示 `📂 No epic context · select one` 提示色弱化
- 切换 epic 时,chat 自动注入系统消息说明"上下文已切到 X"

**视觉**:窄条高度 ~32px,跟 TabBar 同一级别但**视觉重量更轻**(灰色文字)。

### 4.2 ⭐ P0 —— Chat 输入框:Quick Actions

**问题**:Design / Dev / QA 各有几个常用动作,每次手打太重。

**新增 UI 元素**:
- **输入框上方一行 chip 按钮**,根据当前角色 / 当前 epic stage 上下文显示 3-5 个 Quick Action:
  - Design + 已绑 epic + 无 02-design.md → `[起 PD 草稿]` `[起会议纪要]` `[找历史 epic]`
  - Dev + 已绑 epic + 有 02-design.md → `[Review PD]` `[起技术设计]` `[拆子 issue]`
  - QA + 已绑 epic + 02 / 04 都齐 → `[起测试用例]` `[起自动化脚本]` `[报 bug]`
- 点 chip = 把对应 prompt 模板填进输入框,**用户可继续编辑后发出**(不直接发,避免误操作)
- chip 视觉:细边框 / 灰色背景 / 小字号 / hover 微高亮

### 4.3 ⭐ P0 —— 新 Tab: **Epic Workspace**(替换 / 升级现有 Connectors tab 上面?或独立 tab)

**问题**:Forge chat 是入口,但用户也需要看到"当前 epic 有哪些文档、什么阶段、关联了什么"。今天的 4 个 tab 不承载这个视图。

**建议**:**在 Chat 和 Jobs 中间插一个新 Tab,叫 `Epic`(或 `Work`)**。Tab Bar 变成 5 个:
```
Chat | Epic | Jobs | Connectors | Settings
```

**Epic Tab 的内容**:

```
┌────────────────────────────────────────┐
│ [搜索框]   [+ New Epic]                │
├────────────────────────────────────────┤
│ ▾ 2026-Q3                              │
│   📌 EPIC-9981 SAML-SSO    [Stage: Dev]│
│      pd-docs / Mantis / GitLab Epic    │
│      🟢 12 issues / 3 open / 0 blocker │
│                                        │
│   ⚪ EPIC-9985 Audit Log    [Stage: Design]│
│                                        │
│ ▾ 未规划                                │
│   ⚪ EPIC-TBD 双因素登录   [Stage: Design]│
│                                        │
│ ▾ Inbox (4 条新需求)                    │
│   📥 PMDB-7821 ACME SAML  · 3 天前      │
│   📥 PMDB-7822 ...        · 1 天前      │
│   ...                                  │
└────────────────────────────────────────┘
```

要点:
- **按 release 分组**,折叠
- 每个 epic 卡片显示:**ID 名字、当前 stage、外链(pd-docs / Mantis / GitLab)、状态摘要**
- **Inbox 区**单独一组,新需求倒序
- 点 epic 卡片 → 跳到 chat tab 并自动绑定该 epic 上下文
- 点 inbox 项 → 弹出"基于这条建 epic"对话框,确认后 chat 触发 Forge job

### 4.4 ⭐ P1 —— Epic 详情面板(从 Epic Tab 点入)

点击 Epic 卡片如果不希望直接跳 chat,而是**先看详情**,提供一个详情面板(也可以是 modal / 下推):

```
┌────────────────────────────────────────┐
│ ← 返回                                  │
│                                        │
│ EPIC-9981 SAML-SSO                     │
│ 2026-Q3 · Stage: Implementation        │
│                                        │
│ Links:                                 │
│   📄 pd-docs/.../EPIC-9981/            │
│   🐞 Mantis MA-9981                    │
│   🦊 GitLab Epic !9981                 │
│                                        │
│ Documents in this Epic:                │
│   ✅ 00-intake.md                       │
│   ✅ 01-discovery/ (3)                  │
│   ✅ 02-design.md (v1.0)                │
│   ✅ 03-review/ (2 rounds)              │
│   🔄 04-tech-design/ (3 modules)        │
│   ⏳ 06-test/ (not yet)                  │
│                                        │
│ [💬 Open Chat in This Epic]            │
│ [🔧 Run Job: Refresh Status]           │
└────────────────────────────────────────┘
```

要点:
- 列出 pd-docs 里这个 epic 目录下所有文件,**用 ✅ / 🔄 / ⏳ 表示当前状态**
- 点文件名能预览 markdown(可后期做)
- 底部主 CTA:"在这个 epic 上下文里开 chat"
- 次要 CTA:运行相关 job(刷新 GitLab 状态、生成周报等)

### 4.5 P1 —— Connectors Tab 增加视觉状态

**问题**:已有审批流(approved / pending / updated),但缺一些 affordance。

**改造**:
- 每个连接器卡片增加最后一次成功调用的时间戳(`✓ 5 min ago · list_my_bugs`)
- 出错时显示红色 pill(`⚠ last call failed: timeout`)
- 增加"测试连接"按钮,跑一个 read-only tool 看是否 healthy

### 4.6 P1 —— Jobs Tab 增加"上次运行结果摘要"

**问题**:已有 jobs 列表,但用户不知道每个 job 上次跑得怎么样。

**改造**:
- 每个 job 卡片增加上次运行的时间戳 + 简短结果摘要(`✓ 10 min ago · synced 3 new items`)
- 失败时红色,点开看 stderr / 错误

### 4.7 P2 —— 起 PD / 起测试用例的"分步引导"对话

**问题**:Quick Action chip 点一下 prompt 模板就填到输入框是够用的,但**起 PD 这种长流程**可以做得更引导。

**可选改造**(只在用户反馈不够好时做):
- 点 `[起 PD 草稿]` chip 弹一个轻量 wizard:
  1. "基于哪些 discovery 文件?"(多选已有的)
  2. "参考哪份历史 PD 的结构?"(下拉)
  3. "重点强调哪些维度?"(可选 chip:架构 / API / 性能 / 安全 / 兼容性)
- 走完 wizard 生成 prompt 给 chat 处理

**Phase 1 默认不做,只在 4.2 的 chip 不够好时再做。**


## 5. 你不需要设计的部分(Out of scope)

- 完整的 Forge 后台管理界面(管理员看 jobs / connectors / 用户管理)—— 不在浏览器扩展里
- Release dashboard(Manager 视角)—— Phase 1 不做
- 移动端 / 不同浏览器 —— 只支持 Chrome 桌面版
- 文件预览的高级渲染(Mermaid / 代码高亮)—— Phase 1 列表展示就够
- 协作多人光标 / 实时同步 —— 离线文档协作走 git MR,不在 chat 里


## 6. 给 AI 设计师的具体输出要求

请按以下顺序产出(每个屏幕都要):

1. **低保真线框图**(ASCII / markdown 表格 / 文字描述都行,Claude 输出的话用 ASCII)
2. **交互说明**:每个可点元素点了之后发生什么
3. **状态枚举**:loading / empty / error / success 各状态的视觉
4. **响应式考虑**:侧边栏宽度可变(400-600px),怎么 graceful
5. **可访问性**:键盘导航顺序,ARIA label 建议

**优先做 §4.1 / 4.2 / 4.3 / 4.4 这四个 P0 / P1**。

如果时间允许,可以再给 §4.5 / 4.6 一些建议。


## 7. 我可能会被问到的几个问题(提前回答)

**Q: 你为什么要把 Epic 视图做成独立 Tab 而不是放在 Chat 里?**
A: Chat 是"做事的地方",Epic 视图是"导航 / 状态总览的地方"。两种心智模型不一样。但**点 Epic 后跳回 Chat 自动绑定**这个动作是把两边粘合的关键,请重点设计这个转场。

**Q: Phase 1 是否要做 Manager 视角?**
A: 不要。Manager 看 Dev 视角的 Epic Tab 已经够。Release dashboard 留给后期。

**Q: 设计稿要不要细化到颜色 hex 值?**
A: 不需要。沿用现有 `docs/design/` 的 token。给布局 / 信息密度 / 交互流就够了。

**Q: 用户最常用的是不是 chat?其他 tab 会不会很少进?**
A: 是的。Chat 占 70%+ 时间。但 Epic Tab(§4.3)是**进入 chat 的入口** —— 用户每天开始工作时先看 Epic Tab,决定今天进哪个上下文。所以这两个 tab 的连接要顺。


## 8. 输出哪里好

你可以直接在对话里贴 ASCII 线框 + 说明。

如果你要给我多版方案(强烈推荐),用 markdown 标题分隔:`## 方案 A` / `## 方案 B`,我会逐个 review。


# 附录:产品截图描述(没有图但可以脑补)

当前 Chat tab 大致长这样(类 ChatGPT):

```
┌───────────────────────────────────┐
│ ⚙ Forge                       [⚙] │
├───────────────────────────────────┤
│ Chat | Jobs | Connectors | Set    │
├───────────────────────────────────┤
│ [< Session: New Conversation v ]  │
├───────────────────────────────────┤
│ 👤 帮我看下 EPIC-9981 的 PD 进展   │
│                                   │
│ 🤖 EPIC-9981 (SAML-SSO) 的 PD     │
│    目前在 v0.3 版本,3 轮评审已经… │
│    [详情列表]                      │
│                                   │
│ 👤 帮我起一份技术设计…             │
│                                   │
│ 🤖 [Tool: claude_code]             │
│    正在 fortinac/ cwd 跑分析...   │
│    ✓ 生成 04-tech-design/         │
│      overview.md (3.2 KB)         │
│                                   │
├───────────────────────────────────┤
│ [_____________________________]   │  ← 输入框
│ [发送]                            │
└───────────────────────────────────┘
```

**新版本主要改动是**:
1. 输入框上加一行 Quick Action chips
2. 顶部 session selector 之上 / 之下加 Epic 选择器
3. 增加 Epic tab(在 Chat 右边)
