# ZCLAW Agent 人格设置引导功能

> **创建日期**: 2026-03-16
> **状态**: 待批准
> **预计周期**: 5-7 天

---

## 一、背景与目标

### 1.1 问题背景

用户反馈：当前系统新建 Agent 时缺少像 OpenClaw 那样的引导式人格设置体验。

**现状对比**:

| 功能 | OpenClaw | 当前 ZCLAW |
|-----|----------|-----------|
| 使用场景选择 | 多选标签（点击选择） | 文本输入（逗号分隔） |
| 人格风格 | 有（sharp, resourceful 等） | 无 |
| Emoji 选择 | 有 | 无 |
| 引导时机 | 新分身创建时弹出模态框 | 侧边栏内联表单 |
| 首次对话引导 | 有欢迎消息和快速建议 | 只有空状态 |

### 1.2 目标

1. **增强 Agent 创建体验**: 从简单表单升级为引导式向导
2. **人格风格设置**: 让用户选择 Agent 的性格和沟通风格
3. **首次对话引导**: 新 Agent 首次对话时显示个性化欢迎和快速开始建议
4. **与后端集成**: 人格设置写入 SOUL.md 等配置文件

---

## 二、数据模型扩展

### 2.1 Clone 接口扩展

**文件**: `desktop/src/store/agentStore.ts` 和 `desktop/src/store/gatewayStore.ts`

```typescript
export interface Clone {
  // ... existing fields ...

  // 新增人格相关字段
  emoji?: string;              // Agent emoji, e.g., "🦞", "🤖", "💻"
  personality?: string;        // 人格风格: professional, friendly, creative, concise
  communicationStyle?: string; // 沟通风格描述
  notes?: string;              // 用户备注

  // 首次引导状态
  onboardingCompleted?: boolean;  // 是否完成首次引导
}
```

### 2.2 QuickConfig 接口扩展

**文件**: `desktop/src/store/gatewayStore.ts`

```typescript
interface QuickConfig {
  // ... existing fields ...

  // 新增人格引导字段
  emoji?: string;
  personality?: string;
  communicationStyle?: string;
  notes?: string;
}
```

---

## 三、组件设计

### 3.1 新增组件

| 组件 | 路径 | 说明 |
|-----|------|------|
| AgentOnboardingWizard | `components/AgentOnboardingWizard.tsx` | Agent 创建向导主组件 |
| EmojiPicker | `components/ui/EmojiPicker.tsx` | Emoji 选择器 |
| PersonalitySelector | `components/PersonalitySelector.tsx` | 人格风格选择器 |
| ScenarioTags | `components/ScenarioTags.tsx` | 使用场景标签选择器 |
| FirstConversationPrompt | `components/FirstConversationPrompt.tsx` | 首次对话引导 |

### 3.2 AgentOnboardingWizard 向导步骤

| 步骤 | 标题 | 字段 |
|-----|------|------|
| 1 | 认识用户 | userName, userRole |
| 2 | Agent 身份 | name, role, nickname |
| 3 | 人格风格 | emoji + personality 标签 |
| 4 | 使用场景 | scenarios 多选标签 |
| 5 | 工作环境 | workspaceDir, restrictFiles, privacyOptIn, notes |

### 3.3 人格风格预设

```typescript
const PERSONALITY_OPTIONS = [
  { id: 'professional', label: '专业严谨', description: '精确、可靠、技术导向', icon: Briefcase },
  { id: 'friendly', label: '友好亲切', description: '温暖、耐心、易于沟通', icon: Heart },
  { id: 'creative', label: '创意灵活', description: '想象力丰富、善于探索', icon: Sparkles },
  { id: 'concise', label: '简洁高效', description: '快速、直接、结果导向', icon: Zap },
];
```

### 3.4 使用场景标签

```typescript
const SCENARIO_TAGS = [
  { id: 'coding', label: '编程开发', icon: Code },
  { id: 'writing', label: '内容写作', icon: PenLine },
  { id: 'product', label: '产品策划', icon: Package },
  { id: 'data', label: '数据分析', icon: BarChart },
  { id: 'design', label: '设计创意', icon: Palette },
  { id: 'devops', label: '运维部署', icon: Server },
  { id: 'research', label: '研究调研', icon: Search },
  { id: 'marketing', label: '营销推广', icon: Megaphone },
  { id: 'other', label: '其他', icon: MoreHorizontal },
];
```

### 3.5 Emoji 预设

```
动物: 🦞, 🐱, 🐶, 🦊, 🐼, 🦁, 🐬, 🦄
物体: 💻, 🚀, ⚡, 🔧, 📚, 🎨, ⭐, 💎
表情: 😊, 🤓, 😎, 🤖
```

---

## 四、用户流程

### 4.1 创建 Agent 流程

```
点击"快速配置新 Agent"
        ↓
┌─────────────────────────┐
│ Step 1: 认识用户         │
│ - userName (必填)        │
│ - userRole (可选)        │
└─────────────────────────┘
        ↓
┌─────────────────────────┐
│ Step 2: Agent 身份      │
│ - name (必填)           │
│ - role (可选)           │
│ - nickname (可选)       │
└─────────────────────────┘
        ↓
┌─────────────────────────┐
│ Step 3: 人格风格        │
│ - emoji 选择器          │
│ - personality 卡片选择  │
└─────────────────────────┘
        ↓
┌─────────────────────────┐
│ Step 4: 使用场景        │
│ - scenarios 多选标签    │
└─────────────────────────┘
        ↓
┌─────────────────────────┐
│ Step 5: 工作环境        │
│ - workspaceDir          │
│ - restrictFiles 开关    │
│ - notes (可选)          │
└─────────────────────────┘
        ↓
    完成配置
```

### 4.2 首次对话引导

当用户进入新创建的 Agent 聊天界面时：

```
┌─────────────────────────────────────────────┐
│                                             │
│              🦞                             │
│        你好，{userName}！                    │
│                                             │
│   我是 {agentName}，你的{scenarios}助手。     │
│   有什么我可以帮你的吗？                     │
│                                             │
│   快速开始：                                 │
│   ┌─────────────────────────────────────┐   │
│   │ 💡 帮我写一个 Python 脚本...        │   │
│   └─────────────────────────────────────┘   │
│   ┌─────────────────────────────────────┐   │
│   │ 📊 分析这个数据集的趋势              │   │
│   └─────────────────────────────────────┘   │
│                                             │
└─────────────────────────────────────────────┘
```

---

## 五、与后端集成

### 5.1 API 调用

现有 API 已支持:
- `createClone(opts)` - 创建 Agent
- `updateClone(id, updates)` - 更新 Agent

新字段作为扩展传递，后端 OpenFang 如不支持会忽略（非破坏性）。

### 5.2 Bootstrap 文件生成

**文件**: `desktop/src/lib/agent-identity.ts`

创建 Agent 时，根据人格设置生成初始配置：

```typescript
function initializeAgentIdentity(agentId: string, config: QuickConfig): void {
  // 自定义 SOUL.md
  if (config.personality || config.communicationStyle) {
    const customSoul = generateCustomSoul(config);
    manager.updateFile(agentId, 'soul', customSoul);
  }

  // 自定义 USER.md
  if (config.userName || config.userRole) {
    const userProfile = generateUserProfile(config);
    manager.updateFile(agentId, 'userProfile', userProfile);
  }
}
```

---

## 六、文件修改清单

### 6.1 需要创建的文件

| 文件 | 说明 |
|-----|------|
| `desktop/src/components/AgentOnboardingWizard.tsx` | 向导主组件 |
| `desktop/src/components/ui/EmojiPicker.tsx` | Emoji 选择器 |
| `desktop/src/components/PersonalitySelector.tsx` | 人格选择器 |
| `desktop/src/components/ScenarioTags.tsx` | 场景标签 |
| `desktop/src/components/FirstConversationPrompt.tsx` | 首次对话引导 |
| `desktop/src/lib/personality-presets.ts` | 人格预设配置 |

### 6.2 需要修改的文件

| 文件 | 修改内容 |
|-----|---------|
| `desktop/src/store/agentStore.ts` | 扩展 Clone 接口 |
| `desktop/src/store/gatewayStore.ts` | 扩展 Clone 和 QuickConfig 接口 |
| `desktop/src/components/CloneManager.tsx` | 集成 AgentOnboardingWizard |
| `desktop/src/components/RightPanel.tsx` | 显示人格信息 |
| `desktop/src/components/ChatArea.tsx` | 集成 FirstConversationPrompt |
| `desktop/src/components/ui/index.ts` | 导出新组件 |
| `desktop/src/lib/agent-identity.ts` | 人格生成逻辑 |

---

## 七、实现优先级

### Phase 1: 数据层 (1 天)
1. 扩展 Clone/QuickConfig 接口
2. 更新 gateway-client 传递新字段
3. 创建 personality-presets.ts

### Phase 2: 核心组件 (2-3 天)
1. 实现 EmojiPicker 组件
2. 实现 PersonalitySelector 组件
3. 实现 ScenarioTags 组件
4. 实现 AgentOnboardingWizard 主组件

### Phase 3: 集成 (1-2 天)
1. 修改 CloneManager 使用新向导
2. 实现 FirstConversationPrompt 并集成到 ChatArea
3. 修改 RightPanel 显示人格信息

### Phase 4: 测试与优化 (1 天)
1. 测试创建流程
2. 样式微调和动画优化

---

## 八、验证方式

### 8.1 功能验证

1. **创建 Agent 流程**
   - 点击"快速配置新 Agent"
   - 完成 5 步向导
   - 验证 Agent 出现在列表中

2. **人格设置验证**
   - 检查 Agent 卡片显示 emoji
   - 检查 RightPanel 显示人格信息

3. **首次对话引导**
   - 进入新 Agent 聊天
   - 验证显示个性化欢迎消息
   - 点击快速开始建议

### 8.2 持久化验证

1. 刷新页面后 Agent 信息保留
2. 切换 Tab 后状态保留

---

## 九、参考文件

- OpenClaw 快速配置: `docs/archive/openclaw-legacy/autoclaw界面/html版/4.html`
- OpenClaw Agent 面板: `docs/archive/openclaw-legacy/autoclaw界面/html版/3.html`
- 现有 Clone 表单: `desktop/src/components/CloneManager.tsx`
- 现有 Modal 模式: `desktop/src/components/CreateTriggerModal.tsx`
- SOUL.md 配置: `config/SOUL.md`