jug0: Instructions file for Claude Code

CLAUDE.md — jug0 (AI Core Backend)

Tech Stack

Rust, Axum 0.7, SeaORM (PostgreSQL/MySQL/SQLite), async-openai, qdrant-client, DashMap, tokio

Build & Run

cargo build            # 编译
cargo run              # 启动 (默认 :3000)
RUST_LOG=jug0=debug cargo run   # 带 debug 日志
cargo run -p migration -- up    # 执行数据库迁移
cargo run -p migration -- status  # 查看迁移状态

Project Structure

src/
├── main.rs                    # AppState 定义 + 路由注册 + 启动
├── auth.rs                    # JWT/API Key 验证中间件
├── errors.rs                  # AppError 统一错误类型
├── entities/                  # SeaORM 实体
│   ├── chats.rs
│   ├── messages.rs            # message_types / states / roles 常量
│   ├── agents.rs
│   ├── prompts.rs
│   ├── workflows.rs
│   └── handles.rs
├── handlers/
│   ├── chat/
│   │   ├── mod.rs             # chat_handler, tool_result_handler, stop_chat_handler
│   │   ├── logic.rs           # run_chat_stream() — 核心流式生成逻辑
│   │   ├── types.rs           # 请求/响应类型, InternalStreamEvent, ToolResultPayload
│   │   └── helpers.rs         # merge_tools, try_repair_json
│   ├── prompts.rs
│   ├── agents.rs
│   ├── workflows.rs
│   ├── messages.rs
│   ├── memories.rs
│   └── ...
├── providers/
│   ├── factory.rs             # ProviderFactory (多 LLM 后端)
│   ├── openai.rs / deepseek.rs / qwen.rs / gemini.rs
│   └── embedding.rs
├── services/
│   ├── mcp.rs                 # MCP server-side tool 执行
│   ├── memory/                # 向量记忆 (Qdrant)
│   ├── qdrant.rs              # Qdrant 客户端
│   ├── cache.rs               # Redis 缓存
│   └── models.rs              # 模型同步
└── repositories/              # Agent/Prompt 缓存仓库

AppState 关键字段

pub struct AppState {
    pub db: DatabaseConnection,
    pub providers: ProviderFactory,
    pub active_requests: DashMap<Uuid, CancellationToken>,   // 活跃请求 (用于 stop)
    pub tool_result_channels: DashMap<Uuid, mpsc::Sender<Vec<ToolResultPayload>>>,  // SSE ↔ tool-result 通信
    pub mcp_client: McpClient,
    pub signing_key: Vec<u8>,          // Execution Token 签名密钥
    pub cache: CacheService,           // Redis
    pub agent_repo: AgentRepository,
    pub prompt_repo: PromptRepository,
    // ... embedding, vector_db, memory, models
}