ONE-OS/axhub-make/rules/variant-comparison-guide.md

方案比选指南

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

🎯 目标

通过结构化的比选流程，确保：

1. 为用户提供有价值的备选方案
2. 方案数量可控，便于用户决策
3. 及时引导用户进行收敛决策
4. 使用 VariantSwitcher 组件进行方案展示

📋 核心规则

1. 方案数量原则

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

为什么建议不超过 3 个？

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

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

2. 何时触发比选

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

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

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

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

3. 方案差异化原则

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

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

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

🛠️ 使用 VariantSwitcher 组件

组件导入

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

数据结构

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

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

基本用法

// 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 + .：显示/隐藏比选入口

外部控制

// 在浏览器控制台或 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. 方案介绍

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

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

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

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

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

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

2. 收敛提醒

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

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

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

3. 决策后确认

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

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

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

📝 典型使用场景

场景 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 - 开发指南