# CLAUDE.md

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

## 项目概述

ARS（Agent Runtime Server）前端 Demo，一个基于 Vue 3 + Vite 的 SPA，为智能体运行时后端提供会话管理和消息展示界面。与 `ars-backend` 配合使用。

## 常用命令

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建
npm run build

# 运行所有测试
npm test

# 运行单个测试文件
npx vitest tests/chat-view.spec.js

# 运行匹配模式的测试
npx vitest -t "message.delta"
```

## 环境配置

- `VITE_API_BASE`: 后端 API 基址，默认 `http://localhost:8000/api`

## 架构概览

### 技术栈
- **框架**: Vue 3 (Composition API + `<script setup>`)
- **UI 库**: Element Plus
- **路由**: Vue Router 4
- **HTTP**: Axios
- **Markdown**: markdown-it + mermaid
- **测试**: Vitest + Vue Test Utils + jsdom

### 目录结构
```
src/
├── main.js              # 应用入口，初始化主题/路由/Element Plus
├── App.vue              # 根布局：登录页布局 vs 管理后台布局（含侧边栏）
├── router/index.js      # 路由配置
├── views/               # 页面组件
│   ├── LoginView.vue    # 登录页
│   ├── WelcomeView.vue  # 欢迎/仪表盘
│   ├── UsersView.vue    # 用户管理
│   └── ChatView.vue     # 会话详情（核心页面）
├── components/
│   ├── SessionSidebar.vue  # 会话列表侧边栏
│   ├── NewChatButton.vue   # 新建会话按钮
│   └── tools/              # 工具调用结果卡片组件
└── composables/
    └── useTheme.js         # 主题切换逻辑
tests/                   # Vitest 测试文件
```

### 核心数据流

1. **认证**: JWT token 存储在 `localStorage` (`ars-token`)
2. **会话管理**: 当前会话 ID 存储在 `localStorage` (`ars-current-session`)
3. **实时消息**: 通过 SSE (Server-Sent Events) 接收增量消息
4. **主题**: 支持 light/dark/system，存储在 `localStorage` (`ars-theme`)

### ChatView 消息处理逻辑

ChatView 是最复杂的组件，处理以下消息类型：
- `user.prompt`: 用户输入
- `agent.message`: Agent 最终回复
- `message.delta`: 流式增量内容（打字机效果）
- `run.status`: 运行状态（RUNNING/DONE/FAILED）
- `error`: 系统错误

关键机制：
- `dedupe_key` 去重防止重复消息
- `run_id` 将同一运行的 delta 和 final message 关联
- `finalizedRunIds` 标记已完成的运行，忽略后续 delta
- 打字机效果通过 `typingStates` Map 管理

### 测试模式

测试使用 jsdom 环境，需要 mock：
- `axios` 的 HTTP 请求
- `EventSource` 的 SSE 连接
- `mermaid` 渲染
- `window.scrollTo`

## 样式约定

- 使用 CSS 变量定义主题色（见 `style.css`）
- 组件使用 `<style scoped>`
- 响应式断点：900px/960px