live2d-assistant: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概览

Live2D Assistant 是一个多端（Web/Electron）助手平台，集成 Live2D 虚拟形象和 AI 对话功能。

live2d-assistant/
├── live2d-assistant-fe/     # 前端：Vue 3 + Vite + TypeScript
├── live2d-assistant-server/ # 后端：Python FastAPI (Python 3.12+)
├── electron-live2d/          # Electron 桌面端
├── Makefile
└── CLAUDE.md

常用命令

前端

cd live2d-assistant-fe
npm install
npm run dev          # 开发服务器 (localhost:5173)
npm run build        # 生产构建 → dist/

后端

cd live2d-assistant-server
uv sync              # 安装依赖
uv run fastapi run main.py --host 0.0.0.0 --port 8000 --static_path ../live2d-assistant-fe/dist

注意：--static_path 指向已构建的前端 dist/ 目录；去掉该参数则仅启动 API 服务。

Electron 桌面端

cd electron-live2d
npm install
npm run start         # 开发模式
npm run package       # 打包桌面应用

架构

前端 → 后端通信

• REST + SSE 流式响应（/api/agentic/chat）
• 后端 CORS 允许所有来源

Agent 系统（agentic-agents 多代理）

核心框架：agentic-agents（作为 git submodule 引入：external/agentic-agent）

核心文件：

• router.py — API 入口，/api/agentic/chat 端点
• agentic/agent_builder.py — Agent 工厂，根据前端 AgentConfig 构建 Agent
• agentic/model.py — AgentConfig 数据模型

执行流程：

用户输入 → AgentSession → SQLiteSessionStorage 持久化
                        → Router Agent（入口调度）
                        → transfer_to_Router（直接闲聊）
                        → transfer_to_<AgentName>（转交专家）
                        → 专家 Agent 执行任务
                        → transfer_to_Router
                        → 用户接收结果

SSE 事件格式：{"resp_type": "status"|"text"|"tool_result"|"transfer"|"error"|"finished"}

依赖说明

后端 Agent 框架：agentic-agents（作为 git submodule 引入：external/agentic-agent）

• AgentSession：会话管理，支持 SQLite 持久化
• Agent：单个代理实例，支持 ReAct 执行模式