# 方案比选指南

本文档指导 AI Agent 如何为用户提供多方案比选，以及如何引导用户进行决策收敛。

## 🎯 目标

通过结构化的比选流程，确保：
1. 为用户提供有价值的备选方案
2. 方案数量可控，便于用户决策
3. 及时引导用户进行收敛决策
4. 使用 `VariantSwitcher` 组件进行方案展示

## 📋 核心规则

### 1. 方案数量原则

| 规则 | 说明 |
|------|------|
| **推荐方案数** | 原则上不超过 **3 个**方案 |
| **最小方案数** | 当存在明确分歧时，至少提供 2 个方案 |
| **特殊情况** | 如用户有特殊需求，可适当增加方案数量 |

**为什么建议不超过 3 个？**
- 超过 3 个方案会增加用户决策负担
- 方案过多容易导致决策疲劳
- 3 个方案足以覆盖大多数设计维度（如：保守、平衡、激进）

> 注意：这是工作指导原则，组件本身不强制限制方案数量。

### 2. 何时触发比选

以下情况 **应该** 提供多方案比选：

| 场景 | 示例 |
|------|------|
| 设计风格有多种合理选择 | 卡片式 vs 列表式布局 |
| 交互模式存在权衡 | 弹窗确认 vs 内联确认 |
| 技术实现有多条路径 | 动画效果的不同实现方式 |
| 用户需求模糊 | "做一个好看的按钮" |
| 用户明确要求比选 | "给我几个方案看看" |

以下情况 **不应该** 提供比选：

| 场景 | 原因 |
|------|------|
| 需求明确且唯一 | 用户已明确指定实现方式 |
| 只有一种合理实现 | 无需增加决策负担 |
| 差异极小 | 如仅颜色深浅微调，应直接询问偏好 |

### 3. 方案差异化原则

每个方案之间应该有 **明显的差异**，避免提供相似方案：

```
✅ 正确：
- 方案 A：极简风格，留白多，突出内容
- 方案 B：信息密集，功能明显，效率优先
- 方案 C：视觉丰富，强调品牌感

❌ 错误：
- 方案 A：蓝色按钮
- 方案 B：深蓝色按钮
- 方案 C：浅蓝色按钮
```

## 🛠️ 使用 VariantSwitcher 组件

### 组件导入

```typescript
import { VariantSwitcher, VariantItem } from '@/common/VariantSwitcher';
```

### 数据结构

每个方案需要定义为 `VariantItem` 类型：

```typescript
interface VariantItem {
  key?: string;        // 唯一标识（可选）
  content: ReactNode;  // 渲染内容
  title: string;       // 方案标题
  description: string; // 方案一句话描述
}
```

### 基本用法

```tsx
// 1. 定义方案数据
const CARD_VARIANTS: VariantItem[] = [
  {
    key: 'minimal',
    content: <CardStyleA />,
    title: '极简风格',
    description: '大量留白，突出内容本身'
  },
  {
    key: 'dense',
    content: <CardStyleB />,
    title: '信息密集',
    description: '功能区块明显，操作便捷'
  },
  {
    key: 'visual',
    content: <CardStyleC />,
    title: '视觉冲击',
    description: '强调视觉效果，品牌感强'
  }
];

// 2. 使用组件
<VariantSwitcher
  id="card-style"
  name="卡片样式"
  variants={CARD_VARIANTS}
  onConfirm={(index, item) => {
    console.log(`用户选择了: ${item.title}`);
  }}
/>
```

### Props 说明

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | 否 | 唯一标识符，用于全局寻址 |
| `name` | string | 否 | **中文名称**，显示在全局面板中（如"头部设计"、"登录页布局"） |
| `variants` | VariantItem[] | 是 | 方案列表 |
| `defaultIndex` | number | 否 | 默认选中索引，默认 0 |
| `onConfirm` | function | 否 | 确认回调，参数为 (index, item) |
| `onReset` | function | 否 | 重置回调 |
| `style` | CSSProperties | 否 | 容器样式 |
| `className` | string | 否 | 容器类名 |

### 组件特性

#### 1. 轻量化入口
- 鼠标悬停在组件上时，右上角显示切换图标
- 点击图标弹出方案选择面板
- 面板显示每个方案的标题和描述

#### 2. 全局面板
- 页面右下角有全局入口按钮（当存在比选组件时自动显示）
- 点击打开侧边栏，显示所有比选项目
- 每个项目显示 **中文名称**（`name` 属性）
- 支持快速定位到具体组件

#### 3. 快捷键支持
- `Ctrl + .` 或 `Cmd + .`：显示/隐藏比选入口

### 外部控制

```javascript
// 在浏览器控制台或 AI Agent 中
const manager = window.AXHUB_VARIANT_MANAGER;

// 获取实例
const switcher = manager.instances['card-style'];

// 切换方案
switcher.select(1);  // 选择第 2 个方案

// 确认选择
switcher.confirm();

// 定位到组件
switcher.focus();

// 获取所有实例
Object.values(manager.instances).forEach(inst => {
  console.log(`${inst.name}: 当前选择 ${inst.variants[inst.currentIndex].title}`);
});
```

## 💬 用户交互规则

### 1. 方案介绍

在提供方案时，必须简要说明每个方案的特点：

```markdown
我为您准备了 3 个设计方案，请预览后选择您偏好的风格：

**极简风格**
大量留白，突出核心内容，适合内容展示型页面

**信息密集**
功能区块明显，操作便捷，适合工具型/管理型页面

**视觉冲击**
强调视觉效果，品牌感强，适合营销型/展示型页面

请悬停在组件上点击切换图标预览，或点击右下角全局按钮查看所有比选项。
选定后点击"确认"按钮。
```

### 2. 收敛提醒

当用户长时间未做决策或继续提出新需求时，应主动提醒：

```markdown
💡 提醒：您目前还有待决策的方案比选，可以点击右下角的比选按钮查看：
- 卡片样式
- 头部设计

建议先确认这些方案，以便我基于您的选择继续优化。
```

### 3. 决策后确认

用户确认方案后，应给予反馈：

```markdown
✅ 已记录您的选择：
- 卡片样式：**极简风格**

我将基于这个选择继续后续开发。如需调整，可随时点击组件上的切换图标重新选择。
```

## 📝 典型使用场景

### 场景 1：用户需求模糊

```
用户: "帮我做一个登录页面"

AI: 我为您准备了 3 种登录页面风格：

**居中卡片**
经典设计，表单居中，背景可自定义

**左右分栏**
左侧品牌展示区，右侧登录表单

**沉浸式**
大图背景，表单叠加，视觉冲击力强

[使用 VariantSwitcher name="登录页布局" 展示三个方案]
```

### 场景 2：组件样式选择

```
用户: "这个按钮给我几个样式选择"

AI: 好的，这里是 3 种按钮样式：

**实心填充** - 高对比度，强调主要操作
**描边镂空** - 轻量化，适合次要操作
**渐变高亮** - 时尚动感，吸引用户注意

[使用 VariantSwitcher name="按钮样式" 展示三个方案]
```

### 场景 3：页面整体布局

```
用户: "帮我做一个产品详情页"

AI: 我为您准备了 3 种页面布局方案：

**左右分栏** - 左侧产品图片，右侧产品信息，经典电商布局
**上下结构** - 顶部大图轮播，下方详情信息，适合视觉型产品
**沉浸式** - 全屏背景，信息叠加，强调品牌调性

[使用 VariantSwitcher name="产品详情页布局" 展示三个页面方案]
```

## ⚠️ 注意事项

1. **命名规范**：`name` 属性应使用清晰的中文名称，便于用户在全局面板中识别
2. **方案描述**：每个 `VariantItem` 的 `title` 和 `description` 应简洁明了
3. **布局影响**：组件外层是 relative 定位的 div，确保父容器正确设置尺寸
4. **事件冒泡**：控制条按钮已阻止事件冒泡，不会触发下层点击事件
5. **层级覆盖**：全局面板 z-index 为 100000，注意与其他 Modal 的层级冲突
6. **快捷键**：使用 `Ctrl + .` 可以隐藏/显示比选入口，适合演示场景

## ✅ 检查清单

### 提供比选前

- [ ] 确认确实存在多种合理方案
- [ ] 方案之间有明显差异
- [ ] 原则上方案数量不超过 3 个
- [ ] 每个方案都有清晰的标题和描述

### 比选进行中

- [ ] 使用 `VariantSwitcher` 组件展示方案
- [ ] 设置有意义的 `name` 属性（中文名称）
- [ ] 为每个方案提供 `title` 和 `description`
- [ ] 向用户说明如何切换和确认

### 比选完成后

- [ ] 确认用户的选择
- [ ] 基于选择继续后续工作
- [ ] 如有多个待决策项，提醒用户收敛

## 🔗 相关文档

- `src/common/VariantSwitcher.tsx` - 组件实现代码
- `src/prototypes/ref-variant-switcher-demo/` - 演示页面
- `skills/third-party/brainstorming/SKILL.md` - 需求对齐规则
- `development-guide.md` - 开发指南