106 lines
4.5 KiB
Markdown
106 lines
4.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
云酒馆 (SillyTavern Cloud) — a full-stack AI role-playing chat platform. Frontend is React + TypeScript + Tailwind + Vite (`web-app/`). Backend is Go + Gin + GORM (`server/`). The two are fully separated and communicate via REST API + SSE streaming.
|
|
|
|
## Build & Run Commands
|
|
|
|
### Frontend (`web-app/`)
|
|
```bash
|
|
npm install
|
|
npm run dev # Dev server at http://localhost:5174
|
|
npm run build # tsc + vite build (type-check then bundle)
|
|
npm run preview # Preview production build
|
|
```
|
|
|
|
### Backend (`server/`)
|
|
```bash
|
|
go mod tidy
|
|
go build -o server .
|
|
./server -c config.yaml # Runs at http://localhost:8888
|
|
```
|
|
|
|
### Type-check only (no emit)
|
|
```bash
|
|
# Frontend
|
|
cd web-app && npx tsc --noEmit
|
|
|
|
# Backend
|
|
cd server && go build ./...
|
|
```
|
|
|
|
## Build Verification
|
|
|
|
After any code edit, always run the build/compile step before reporting success. For Go files: `go build ./...`. For TypeScript files: `npx tsc --noEmit`. Never assume edits are correct without verification.
|
|
|
|
## Architecture
|
|
|
|
### Backend (`server/`)
|
|
|
|
Layered architecture: **routes → API handlers → services → models/DB**
|
|
|
|
```
|
|
api/v1/app/ # App-facing HTTP handlers (auth, character, conversation, ai_config, etc.)
|
|
api/v1/system/ # Admin/system handlers
|
|
service/app/ # Business logic layer
|
|
model/app/ # GORM data models (AppUser, AiCharacter, Conversation, Preset, Worldbook, RegexScript)
|
|
router/app/ # Gin route registration
|
|
middleware/ # JWT auth, CORS, logging, recovery
|
|
initialize/ # DB, Redis, router, plugin setup (called from main.go)
|
|
core/ # Zap logging, Viper config loading, server startup
|
|
```
|
|
|
|
Key models: `AppUser`, `AiCharacter` (SillyTavern V2 card format), `Conversation`, `Preset` (sampling params), `Worldbook` (keyword-triggered context), `RegexScript` (message transforms).
|
|
|
|
AI providers: OpenAI-compatible + Anthropic. Unified through the AI config service. Conversations use SSE streaming for real-time token delivery.
|
|
|
|
### Frontend (`web-app/src/`)
|
|
|
|
MVU (Model-View-Update) pattern via **Zustand** with `persist` middleware (localStorage).
|
|
|
|
```
|
|
store/index.ts # Single global Zustand store — source of truth for user, currentCharacter,
|
|
# currentConversation, messages, variables, UI state
|
|
api/ # One file per domain: auth, character, conversation, preset, worldbook, regex
|
|
# All share the axios instance in api/client.ts (injects JWT, handles 401)
|
|
pages/ # Route-level components (ChatPage, CharacterManagePage, AdminPage, etc.)
|
|
components/ # Reusable UI — ChatArea, CharacterPanel, SettingsPanel, Sidebar, Navbar,
|
|
# MessageContent (renders markdown + HTML safely via rehype-sanitize)
|
|
```
|
|
|
|
Routes are defined in `App.tsx`. Auth guard redirects to `/login` when `isAuthenticated` is false.
|
|
|
|
The `variables: Record<string, string>` field in the store implements the MVU variable system used for template substitution in AI prompts (e.g., `{{user}}`, `{{char}}`).
|
|
|
|
### API Convention
|
|
|
|
- Base URL: `http://localhost:8888` (configured via `VITE_API_BASE_URL` in `.env.development`)
|
|
- Auth: `Authorization: Bearer <jwt>` header, injected automatically by `api/client.ts`
|
|
- App routes: `/app/auth/...`, `/app/user/...`, `/app/character/...`, `/app/conversation/...`
|
|
- Admin routes: `/system/...` (Casbin RBAC enforced)
|
|
|
|
## Go Development
|
|
|
|
When editing Go files, always check all call sites of modified functions. If a function signature changes (parameters or return values), grep for all usages and update them in the same edit batch.
|
|
|
|
Run `go build ./...` from `server/` to verify after every edit.
|
|
|
|
## Frontend Development
|
|
|
|
When editing Vue/TypeScript frontend files, verify all imports are present and no duplicate code remains after edits. Read the file back after editing to confirm structural integrity.
|
|
|
|
Run `npx tsc --noEmit` from `web-app/` to verify after every edit.
|
|
|
|
## Third-Party Integrations
|
|
|
|
When integrating third-party SDKs or APIs (payment providers, AI model APIs), read the actual SDK source or docs first before writing code. Do not guess method names, parameter types, or key sizes.
|
|
|
|
## Configuration
|
|
|
|
Backend config file: `server/config.yaml` (not committed; copy from `config.example.yaml` if present). Supports MySQL, PostgreSQL, SQLite, SQL Server, Oracle via GORM. Redis for sessions/caching.
|
|
|
|
Frontend env files: `web-app/.env.development` and `web-app/.env.production` — set `VITE_API_BASE_URL`.
|