Hero 系统概述
Hero 系统概述
什么是 Hero？
Hero 是 Vibecape 中的 AI 智能体系统。每个 Hero 都是一个独立的 AI 助手，拥有：
- 独特的身份：名称、描述、头像
- 专门的系统提示词：定义 Hero 的角色和行为方式
- 专属工具集：决定 Hero 能执行哪些操作（如文档编辑、搜索等）
- 工具选择策略：控制 Hero 何时以及如何使用工具
- 欢迎消息：新对话时的开场白
- 建议预设：为用户提供快速开始的建议提示
Hero 的类型
内置 Hero（Built-in Heroes）
Vibecape 提供了多个预配置的 Hero：
- Nova：通用智能助手（默认 Hero）
- Iris：文档专家
- Luca：创意助手
- Max：分析师
- Sage：研究专家
- Muse：灵感伙伴
这些 Hero 内置于应用中，用户可以直接使用，无法修改。
自定义 Hero（Custom Heroes）
用户可以创建自己的 Hero：
- 通过可视化编辑器创建
- 支持完全自定义提示词、工具策略等
- 存储在
app.db数据库中 - 可随时编辑和删除
Hero 系统架构
Hero 系统采用分层架构设计：
┌─────────────────────────────────────────────────────────┐
│ 前端 (Renderer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ HeroSidebar │ │ HeroEditor │ │ HeroSelector │ │
│ │ (列表) │ │ (编辑器) │ │ (聊天选择) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ↓ ↓ ↓ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ useHeroStore / useHero Hook │ │
│ │ (Zustand 状态管理) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
↓ IPC
┌─────────────────────────────────────────────────────────┐
│ 后端 (Main) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ HeroHandler │→ │ HeroService │→ │HeroRepository│ │
│ │ (IPC 处理器) │ │ (业务逻辑) │ │ (数据库) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ↓ ↓ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ HeroesManager │ │
│ │ (Hero 注册、管理、创建 AI Agent) │ │
│ └──────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ HeroRunner │ │
│ │ (Hero 执行引擎、工具调用、上下文管理) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘前端层
- HeroSidebar：显示 Hero 列表，支持创建、选择、删除
- HeroEditor：基于 Tiptap 的可视化编辑器，使用特殊节点类型
- HeroSelector：聊天界面中的 Hero 切换器
- useHeroStore / useHero：Zustand 状态管理，处理 Hero 列表和选中状态
后端层
- HeroHandler：IPC 通信接口，暴露 Hero CRUD 操作
- HeroService：业务逻辑层，处理 Hero 的创建、更新、删除
- HeroRepository：数据访问层，封装数据库操作
- HeroesManager：Hero 注册表，管理内置和自定义 Hero
- HeroRunner：Hero 执行引擎，负责运行 AI 对话和工具调用
数据存储
- app.db (SQLite)：存储自定义 Hero 的配置（Tiptap JSONContent 格式）
- heroes.json：自定义 Hero 的运行时配置缓存
- 文件系统：Hero 头像存储在
~/vibecape/assets/avatars/
核心概念
1. Hero 配置
Hero 的核心配置包含：
interface HeroConfig {
id: string; // 唯一标识
name: string; // 显示名称
description: BilingualPrompt; // 双语描述
avatar: string; // 头像 URL
prompt: BilingualPrompt; // 系统提示词（双语）
tools?: Record<string, Tool>; // 工具集
maxSteps?: number; // 最大执行步数
toolChoice?: "auto" | "required" | "none"; // 工具策略
isDefault?: boolean; // 是否为默认
welcome?: BilingualPrompt; // 欢迎消息
suggestions?: HeroSuggestion[]; // 建议预设
}2. 双语支持
所有 Hero 支持中英文双语：
- 系统提示词根据当前语言自动切换
- 描述、欢迎消息、建议预设都支持双语
3. 工具系统
Hero 可以访问多种工具：
- docReader：读取文档内容
- docEditor：编辑文档（需用户确认）
- docManager：管理文档（创建、移动、删除）
- todoManager：待办事项管理
- agent：并行任务、任务链等高级功能
工具选择策略：
auto：AI 自动决定是否使用工具required：必须使用工具none：不使用工具（纯对话）
4. 数据流
创建 Hero 流程
用户点击"新建 Hero"
↓
HeroEditor 加载空内容
↓
用户使用 Slash Menu 插入节点：
- /name → 插入 heroName 节点
- /desc → 插入 heroDescription 节点
- /tool → 插入 heroToolChoice 节点
↓
自动保存（500ms debounce）到 app.db
↓
HeroService 同步到 heroes.json
↓
HeroesManager 重新加载自定义 Hero
↓
HeroSelector 和 HeroSidebar 更新列表使用 Hero 流程
用户在 ChatPanel 选择 Hero
↓
useHero Hook 记录选中的 heroId
↓
发送消息时，chat:handler 获取当前 Hero
↓
HeroRunner 创建 AI Agent 实例
↓
执行对话，处理工具调用
↓
返回响应并流式传输到前端