Ars-Font/CLAUDE.md

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 配合使用。

常用命令

# 安装依赖
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