这是「GSD 全景代码解析」专题的第 28 篇。

---

UI 与假设分析 Agent

在 GSD 的 33 个专业 Agent 中，有三类 Agent 的职责非常特殊：它们不直接生产代码，也不参与主执行流程，而是在特定质量维度上提供专业审查和深度分析。gsd-ui-auditor 和 gsd-ui-researcher 组成了 GSD 的 UI 质量双翼——一个负责事后审查，一个负责事前研究；gsd-assumptions-analyzer 则是 GSD 的认知纠偏器——在规划阶段识别需求中的隐含假设，防止「想当然」导致的系统性风险。

本文将深入解析这三个 Agent 的设计哲学、工作方式和协作机制。

---

一、gsd-ui-auditor：UI 质量的守门人

1.1 Agent 定位与核心职责

gsd-ui-auditor 是 GSD 中专责 UI 实现质量审查 的 Agent。与 gsd-verifier 关注「功能是否正确」不同，ui-auditor 关注「界面是否合格」——包括视觉一致性、交互合理性、可访问性合规性和响应式适配性。

它的核心职责可以用四个问题概括：

1. 视觉一致性：UI 实现是否遵循设计系统（Design System）的规范？颜色、字体、间距、圆角等视觉 token 是否正确使用？
2. 交互合理性：用户操作流程是否顺畅？状态反馈是否及时？错误处理是否友好？
3. 可访问性（A11y）：是否满足 WCAG 2.1 标准？键盘导航是否正常？屏幕阅读器兼容性如何？
4. 响应式适配：在不同视口（viewport）和断点（breakpoint）下，布局是否正确适配？

flowchart TD
    subgraph Input["输入上下文"]
        I1[设计稿 / Figma 链接]
        I2[Design System 规范]
        I3[实现代码 HTML/CSS/JS]
        I4[gates.md 质量标准]
    end

    subgraph Audit["gsd-ui-auditor 审查"]
        A1[视觉一致性检查]
        A2[交互合理性检查]
        A3[可访问性检查]
        A4[响应式适配检查]
        A5[综合评分]
    end

    subgraph Output["输出产物"]
        O1[UI-AUDIT.md]
    end

    I1 --> A1
    I2 --> A1
    I3 --> A2
    I3 --> A3
    I3 --> A4
    I4 --> A5
    A1 --> A5
    A2 --> A5
    A3 --> A5
    A4 --> A5
    A5 --> O1

gsd-ui-auditor 的 Agent 定义遵循 GSD 标准格式：

---
name: gsd-ui-auditor
description: |
  专责 UI 实现质量审查的 Agent。审查视觉一致性、交互合理性、
  可访问性（WCAG 2.1）和响应式适配性。输出结构化 UI-AUDIT.md。
tools: Read, Grep, Glob
---

关键约束：ui-auditor 不修改代码，只生成审查报告。修复工作由 gsd-executor 或 gsd-code-fixer 执行。这种「审改分离」的设计保证了审查的客观性。

1.2 UI 审查标准

gsd-ui-auditor 的审查标准分为四个层级，每个层级对应一组检查项：

层级一：视觉一致性（Visual Consistency）

检查项	检查内容	严重程度
色彩合规	是否使用 Design System 定义的颜色 token？是否存在硬编码色值？	Critical
字体规范	字体家族、字重、字号、行高是否符合类型系统（Type System）？	Critical
间距系统	边距、内边距是否遵循 4px/8px 网格系统？	Major
圆角与阴影	圆角值、阴影参数是否使用预设 token？	Minor
图标规范	图标风格（线型/面型）是否统一？尺寸是否符合规范？	Major

层级二：交互合理性（Interaction Quality）

检查项	检查内容	严重程度
状态完整性	是否覆盖 default、hover、active、disabled、loading 全部状态？	Critical
反馈及时性	用户操作后是否有视觉反馈？延迟是否可感知？	Major
错误处理	表单验证错误是否有明确提示？是否指导用户修复？	Major
加载状态	异步操作是否有 loading/skeleton 状态？	Minor
焦点管理	模态框打开时焦点是否正确捕获？关闭后是否回退？	Major

层级三：可访问性（Accessibility）

检查项	检查内容	严重程度
语义化 HTML	是否正确使用 header、nav、main、article 等语义标签？	Critical
ARIA 属性	复杂组件是否正确使用 role、aria-label、aria-describedby？	Major
色彩对比度	文字与背景对比度是否大于等于 4.5:1（AA 级）或大于等于 7:1（AAA 级）？	Critical
键盘导航	所有交互元素是否可通过 Tab 键访问？焦点顺序是否逻辑？	Critical
屏幕阅读器	表单标签是否与输入框正确关联（label for）？	Major

层级四：响应式适配（Responsive Adaptation）

检查项	检查内容	严重程度
断点覆盖	是否覆盖设计文档定义的全部断点（mobile、tablet、desktop、wide）？	Major
布局稳定性	视口变化时是否出现布局偏移（CLS）？	Major
触控适配	触控目标最小尺寸是否大于等于 44x44px？	Minor
字体缩放	浏览器字体缩放至 200% 时内容是否仍然可读？	Minor

1.3 可访问性检查详解

可访问性是 gsd-ui-auditor 审查中最严格的部分，因为 GSD 将 A11y 视为质量底线而非可选特性。

自动化检查清单（gsd-ui-auditor 的执行逻辑）：

// 可访问性检查核心逻辑（伪代码）
const a11yChecks = {
  // 1. 色彩对比度
  contrast: {
    test: (element) => getContrastRatio(element.color, element.background) >= 4.5,
    standard: "WCAG 2.1 AA",
    severity: "Critical"
  },

  // 2. 键盘可访问性
  keyboardAccess: {
    test: (element) => element.tabIndex >= 0 || isNaturallyFocusable(element),
    standard: "WCAG 2.1 2.1.1",
    severity: "Critical"
  },

  // 3. 图片替代文本
  altText: {
    test: (img) => img.hasAlt || img.hasAriaLabel || isDecorative(img),
    standard: "WCAG 2.1 1.1.1",
    severity: "Critical"
  },

  // 4. 表单标签关联
  formLabels: {
    test: (input) => input.hasAssociatedLabel || input.hasAriaLabel,
    standard: "WCAG 2.1 3.3.2",
    severity: "Major"
  },

  // 5. 动态内容通知
  liveRegions: {
    test: (region) => region.hasAriaLive || region.isRole("status", "alert"),
    standard: "WCAG 2.1 4.1.3",
    severity: "Major"
  }
};

人工审查点（需 auditor 结合上下文判断）：

• 导航 landmark 是否完整且语义正确
• 跳过链接（Skip Link）是否存在
• 模态框的 aria-modal 和焦点陷阱（Focus Trap）实现
• 复杂数据表格的表头关联（headers 属性）

1.4 响应式设计验证

响应式验证不是简单的「看看手机版能不能用」，而是系统性的多断点矩阵测试：

## 响应式验证矩阵

| 断点 | 宽度 | 布局模式 | 触控目标 | 字体缩放 | 状态 |
|------|------|---------|---------|---------|------|
| Mobile S | 320px | 单列堆叠 | 大于等于 44px | 100%-200% | 通过 |
| Mobile L | 425px | 单列堆叠 | 大于等于 44px | 100%-200% | 通过 |
| Tablet | 768px | 双列混合 | 大于等于 44px | 100%-200% | 侧边栏折叠异常 |
| Desktop | 1024px | 三列网格 | N/A | 100%-200% | 通过 |
| Wide | 1440px | 三列网格 + 最大宽度 | N/A | 100%-200% | 通过 |

ui-auditor 的验证策略包括：

1. 静态分析：检查 CSS 媒体查询是否覆盖全部设计断点
2. 内容溢出检测：识别固定宽度元素导致的水平滚动
3. 触控目标扫描：检查可点击元素的实际渲染尺寸
4. 视口元标签验证：确认 meta name="viewport" 配置正确

1.5 与 gsd-verifier 的协作

gsd-ui-auditor 和 gsd-verifier 是 GSD 质量保障体系中的互补角色：

维度	gsd-verifier	gsd-ui-auditor
关注点	功能正确性	UI 质量
审查对象	业务逻辑、API 契约、数据流	视觉呈现、交互体验、A11y
触发时机	每个 phase 完成时	UI 相关阶段完成时
输出产物	VERIFICATION.md	UI-AUDIT.md
失败处理	阻塞后续阶段	生成修复任务清单

sequenceDiagram
    participant W as Workflow (Orchestrator)
    participant E as gsd-executor
    participant V as gsd-verifier
    participant U as gsd-ui-auditor
    participant F as gsd-code-fixer

    W->>E: Spawn 执行 UI 阶段
    E-->>W: 完成，产出代码

    par 并行验证
        W->>V: Spawn verifier
        V-->>W: VERIFICATION.md
        W->>U: Spawn ui-auditor
        U-->>W: UI-AUDIT.md
    end

    alt UI-AUDIT 发现 Critical 问题
        W->>F: Spawn code-fixer
        F-->>W: 修复完成
        W->>U: 重新审计
    end

这种设计体现了 GSD 的专业分工原则：Verifier 不懂设计 token，ui-auditor 不判断业务逻辑——各专其长，各尽其责。

---

二、gsd-ui-researcher：UI 设计的智囊团

2.1 Agent 定位与核心职责

如果说 gsd-ui-auditor 是「UI 质检员」，那么 gsd-ui-researcher 就是「UI 情报员」。它的工作发生在编码之前——当 Planner 需要为前端阶段制定计划时，ui-researcher 负责调研最新的 UI 设计趋势、组件库生态和用户体验最佳实践，为设计决策提供情报支撑。

---
name: gsd-ui-researcher
description: |
  专责 UI/UX 设计趋势和组件库调研的 Agent。收集设计模式、
  分析用户体验数据、评估组件库适配性，输出 UI-RESEARCH.md。
tools: Read, Search, Browser
---

触发场景：

• new-project 初始化时，调研技术栈对应的组件库选择
• plan-phase 前端阶段前，评估具体 UI 需求的实现方案
• 用户执行 /gsd:research ui 主动请求调研

2.2 UI 研究策略

gsd-ui-researcher 的研究不是漫无目的的「网上冲浪」，而是围绕具体设计问题的结构化调研：

研究维度矩阵

维度	研究内容	输出格式
组件库生态	当前技术栈的主流组件库对比（功能、体积、定制性、维护活跃度）	对比表格
设计系统参考	行业标杆产品的 Design System 分析（Material、Ant Design、Chakra 等）	模式清单
交互模式	特定交互场景的最佳实践（如批量操作、表单分步、数据筛选）	模式卡片
A11y 趋势	最新的可访问性规范和工具（如 WAI-ARIA 1.2 新特性）	要点摘要
性能影响	UI 方案对性能的影响评估（如 CSS-in-JS vs CSS Modules）	数据对比

研究流程

flowchart TD
    A[接收研究请求] --> B{研究类型?}
    B -->|组件库选型| C[收集候选库信息]
    B -->|交互模式| D[分析相似产品]
    B -->|A11y 合规| E[查阅 WCAG 更新]
    B -->|性能评估| F[收集 benchmark 数据]

    C --> G[多维对比分析]
    D --> H[模式提取与归类]
    E --> I[规范映射检查表]
    F --> J[性能数据汇总]

    G --> K[生成 UI-RESEARCH.md]
    H --> K
    I --> K
    J --> K

2.3 设计模式收集

设计模式收集是 ui-researcher 最具价值的工作。它不只是罗列「有哪些组件」，而是分析**「为什么这样设计」和「什么场景适用」**。

一个典型的设计模式收集输出：

## 设计模式：批量操作（Bulk Actions）

### 模式描述
用户需要从列表中选择多项并执行统一操作（删除、导出、状态变更等）。

### 常见实现方案对比

| 方案 | 优点 | 缺点 | 适用场景 |
|------|------|------|---------|
| **行内复选框** | 直观、空间效率高 | 选择状态占用一行 | 简单列表 |
| **卡片多选** | 视觉突出、适合富媒体 | 占用更多空间 | 图库、商品列表 |
| **拖拽选择** | 操作流畅、适合连续选择 | 不精确、学习成本高 | 时间轴、画布 |
| **Shift 连续选择** | 高效、符合桌面习惯 | 移动端不支持 | 数据表格 |

### 用户体验考量
- **选择反馈**：选中项需有明显视觉区分（背景色、边框、勾选标记）
- **操作栏**：选中后应浮现操作栏（Floating Action Bar），位置稳定
- **防误触**：破坏性操作（删除）需二次确认
- **全选行为**：部分选中时全选按钮应显示 indeterminate 状态

### A11y 要求
- 复选框必须有 aria-label 或关联 label
- 操作栏出现时应朗读选中数量和可用操作
- 键盘支持：Space 选择/取消，Shift+方向键连续选择

### 参考实现
- Google Drive 批量操作
- Notion 数据库多选
- Airtable 行选择

这种结构化的模式卡片可以被 Planner 直接引用到 PLAN.md 中，确保设计决策有据可依。

2.4 用户体验分析

除了设计模式，ui-researcher 还负责分析特定用户场景的体验瓶颈。

分析方法：

1. 竞品走查（Competitive Audit）：分析 3-5 个竞品在相同场景下的处理方式
2. 启发式评估（Heuristic Evaluation）：对照 Nielsen 的 10 条可用性原则评估
3. 认知负荷评估：分析用户完成任务所需的步骤数和决策点

## 用户体验分析：表单填写流程

### 场景
新用户注册流程，包含邮箱验证、密码设置、个人信息三步。

### 竞品走查发现

| 产品 | 步骤数 | 亮点 | 痛点 |
|------|--------|------|------|
| Product A | 3 步 | 进度指示器清晰 | 第二步加载慢 |
| Product B | 1 页 | 减少页面切换 | 信息过载 |
| Product C | 4 步 | 每步有即时验证 | 返回修改不便 |

### 启发式评估结论
- 系统状态可见：进度条实时反馈
- 错误预防：密码规则提示后置，用户可能反复试错
- 灵活高效：不支持跳过此步，强制线性流程

### 建议方案
采用渐进式披露（Progressive Disclosure）：首屏只收集必要信息，后续在 dashboard 中引导补充。

---

三、gsd-assumptions-analyzer：认知盲点的探照灯

3.1 Agent 定位与核心职责

gsd-assumptions-analyzer 是 GSD 中最独特的 Agent 之一。它不审查代码，不研究 UI，而是专门做一件事——识别需求中的隐含假设。

在软件开发中，绝大多数失败不是源于技术无能，而是源于**「我们以为 X 成立，但 X 其实不成立」**。assumptions-analyzer 的职责就是在规划阶段把这些「以为」挖出来，显式化、分类、评估风险，并制定验证策略。

---
name: gsd-assumptions-analyzer
description: |
  专责分析需求中隐含假设的 Agent。识别技术假设、业务假设、
  环境假设，评估风险等级，制定验证策略。输出 ASSUMPTIONS.md。
model: Claude Haiku 3.5  # Tier 4：快速处理、低成本
---

为什么用 Haiku 3.5？

在第 22 篇中我们提到，assumptions-analyzer 属于 Tier 4 Agent——它的任务不是生成复杂代码或深度推理，而是模式识别和结构化输出。Haiku 3.5 的低成本特性使得 assumptions-analyzer 可以被频繁 spawn，而不消耗过多 token 预算。

3.2 假设识别和分类

assumptions-analyzer 采用四层分类模型对假设进行识别和归类：

假设类型体系

flowchart TD
    A[隐含假设] --> B{假设类型}
    B --> C[技术假设]
    B --> D[业务假设]
    B --> E[环境假设]
    B --> F[认知假设]

    C --> C1[技术可行性]
    C --> C2[性能预期]
    C --> C3[集成兼容性]

    D --> D1[用户行为]
    D --> D2[业务规则稳定性]
    D --> D3[市场需求]

    E --> E1[团队能力]
    E --> E2[基础设施就绪]
    E --> E3[第三方服务可用]

    F --> F1[术语共识]
    F --> F2[范围边界]
    F --> F3[优先级一致]

类型	示例	危险信号
技术假设	"Redis 集群可以承载 10K QPS"	没有 benchmark 数据支撑
业务假设	"用户会更喜欢新界面"	没有用户调研或 A/B 测试
环境假设	"团队所有人都熟悉 React"	新成员可能不熟悉
认知假设	"当我说实时时，大家都理解为小于 1s"	术语未定义

识别方法论

assumptions-analyzer 通过三种方法识别隐含假设：

方法一：关键词扫描

• 扫描 REQUIREMENTS.md 和 DISCUSSION-LOG.md 中的绝对化表述
• 标记包含「显然」「一定」「肯定」「所有人都」「不可能」等词汇的句子

方法二：反向提问

• 对每个需求陈述，反向提问：「如果这个前提不成立，需求还成立吗？」
• 示例：需求说「通过缓存提升性能」-> 反向问「如果缓存命中率小于 50%，性能目标还能达成吗？」

方法三：边界探测

• 识别需求中未定义的边界条件
• 示例：需求说「支持并发用户」-> 边界探测：「并发是多少？100？1000？10000？」

3.3 假设验证策略

识别出假设只是第一步，assumptions-analyzer 的核心价值在于为每个假设制定验证策略。

验证策略矩阵

策略	含义	适用场景	成本
Prove	在继续之前必须证明假设为真	高风险的阻塞性假设	高
Spike	快速原型验证可行性	技术可行性不确定	中
Monitor	先继续，但设置监控指标	可在运行中观察的假设	低
Accept	接受风险，记录为已知问题	风险低且验证成本过高	极低

一个完整的假设分析输出示例：

## 假设分析：从单体迁移到微服务

### 已识别假设

| ID | 假设内容 | 类型 | 风险 | 验证策略 |
|----|---------|------|------|---------|
| A1 | 团队已具备 Docker/K8s 运维能力 | 环境 | 高 | Prove |
| A2 | 服务间通信延迟小于 50ms 可接受 | 技术 | 中 | Spike |
| A3 | 当前数据库连接池不会成为瓶颈 | 技术 | 中 | Monitor |
| A4 | 产品功能边界已稳定，不会出现频繁的服务重组 | 业务 | 高 | Monitor |
| A5 | 监控和日志基础设施已就绪 | 环境 | 高 | Prove |

### 关键发现
- 假设 A1 和 A5 如果为假，将导致迁移项目失败
- 建议先执行 /gsd:spike 验证 A1 和 A5，再继续讨论

3.4 与 discuss-phase 的协作

gsd-assumptions-analyzer 最常见的触发场景是被 discuss-phase spawn 为子 Agent。

在第 17 篇《discuss-phase 与交互工作流》中，我们详细介绍了这种协作关系：

sequenceDiagram
    participant User as 用户
    participant DP as discuss-phase
    participant AA as gsd-assumptions-analyzer
    participant SDK as GSD SDK

    User->>DP: 启动 discuss-phase --mode=power
    DP->>SDK: gsd-sdk query init.discuss-phase
    SDK-->>DP: 项目上下文
    DP->>DP: 进行一般性讨论
    DP->>AA: Spawn assumptions-analyzer
    AA->>AA: 深度扫描隐含假设
    AA->>DP: 返回假设清单 + 风险评级
    DP->>User: 展示假设分析结果
    User->>DP: 确认/修改验证策略
    DP->>SDK: state.add-decision

协作的设计意图：

gsd-assumptions-analyzer 的设计体现了 GSD 的专业化 Agent 编排哲学——与其让一个通用 Agent 做所有事，不如让多个专业 Agent 各司其职。assumptions-analyzer 经过专门训练，更擅长识别认知盲点和隐含前提。

协作的关键约定：

• discuss-phase 负责讨论上下文和决策记录
• assumptions-analyzer 负责假设识别和验证策略
• 两者通过文件系统（ASSUMPTIONS.md）和结构化信号通信
• assumptions-analyzer 不参与讨论，只输出分析结果

---

四、三类 Agent 的协作关系

gsd-ui-auditor、gsd-ui-researcher 和 gsd-assumptions-analyzer 虽然分属不同职责域，但在 GSD 的工作流中形成了有机的协作网络：

flowchart TB
    subgraph Planning["规划阶段"]
        P1[gsd-planner]
        P2[gsd-roadmapper]
    end

    subgraph Research["研究阶段"]
        R1[gsd-ui-researcher]
        R2[gsd-project-researcher]
    end

    subgraph AssumptionCheck["假设审查"]
        A1[gsd-assumptions-analyzer]
    end

    subgraph Execution["执行阶段"]
        E1[gsd-executor]
    end

    subgraph Verification["验证阶段"]
        V1[gsd-verifier]
        V2[gsd-ui-auditor]
        V3[gsd-code-reviewer]
    end

    subgraph Fix["修复阶段"]
        F1[gsd-code-fixer]
    end

    P1 -->|需要 UI 方案| R1
    R1 -->|UI-RESEARCH.md| P1
    P1 -->|生成 PLAN.md| A1
    A1 -->|ASSUMPTIONS.md| P1
    P1 -->|确认后的 PLAN.md| E1
    E1 -->|产出代码| V1
    E1 -->|产出 UI 代码| V2
    V1 -->|VERIFICATION.md| F1
    V2 -->|UI-AUDIT.md| F1
    F1 -->|修复后| V2

协作时序：

1. 事前研究：gsd-ui-researcher 在规划阶段为 Planner 提供设计情报
2. 假设纠偏：gsd-assumptions-analyzer 在规划阶段识别隐含假设，防止方向性错误
3. 事中执行：gsd-executor 根据 PLAN.md 和 ASSUMPTIONS.md 执行实现
4. 事后审查：gsd-ui-auditor 在验证阶段审查 UI 质量，与 verifier 并行工作
5. 修复闭环：gsd-code-fixer 根据 UI-AUDIT.md 修复问题，ui-auditor 重新审计

这种「事前-事中-事后」的全周期覆盖，确保了 UI 质量和决策可靠性不是偶然的产物，而是工程化的结果。

---

五、小结

本文深入解析了 GSD 中三个 Specialist Agent 的设计与协作：

Agent	核心职责	关键设计	触发时机
gsd-ui-auditor	UI 实现质量审查	四层审查标准、审改分离、与 verifier 并行	UI 相关阶段完成时
gsd-ui-researcher	UI/UX 设计调研	结构化研究流程、设计模式卡片、竞品走查	前端阶段规划前
gsd-assumptions-analyzer	隐含假设识别	四层分类模型、验证策略矩阵、低成本模型	规划阶段 / discuss-phase

三者的协作逻辑：

• gsd-ui-researcher 负责事前情报——为设计决策提供依据
• gsd-assumptions-analyzer 负责事前纠偏——防止错误前提导致方向偏离
• gsd-ui-auditor 负责事后把关——确保实现质量达标

它们共同体现了 GSD 的一个核心理念：

质量不是偶然的，而是由专业化 Agent 在正确的时间点执行正确的检查所保障的。

这三个 Agent 的设计也揭示了 GSD Agent 架构的一个重要特征：不是所有 Agent 都需要最强模型。assumptions-analyzer 使用 Tier 4 的 Haiku 3.5 即可完成高质量工作，ui-researcher 使用 Browser 工具扩展能力边界——模型选择和工具配置始终服务于具体任务，而非追求「越大越好」。

---

下一篇预告：第 29 篇《其他 Agent 概览》

在解析了 Planner、Executor、Debugger、Verifier、Code-Reviewer、UI 和假设分析 Agent 之后，GSD 的 Agent 系统还有一批「特种部队」等待揭晓——gsd-security-auditor（安全审计）、gsd-doc-writer（文档撰写）、gsd-intel-updater（智能存储更新）、gsd-pattern-mapper（模式映射）等。它们各司其职，共同构成了 GSD 33 个 Agent 的完整生态。下一篇将为 Agent 系统篇章画上句号，全景呈现剩余 Agent 的设计精髓与协作网络。敬请期待！