zclaw_openfang/plans/vast-stirring-wilkinson.md

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

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

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 人格风格预设

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 使用场景标签

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 时，根据人格设置生成初始配置：

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