AGENTS.md - Development Guidelines for AI22 Project

This document provides essential information for AI agents working on this FastAPI + Vue 3 full-stack application.

🏗️ Project Structure

ai22/
├── backend/                 # FastAPI Backend (Standard Architecture)
│   ├── app/
│   │   ├── main.py         # Application entry point
│   │   ├── config.py       # Configuration management
│   │   ├── core/           # Core configuration and global components
│   │   │   ├── config.py   # Environment config
│   │   │   ├── security.py # JWT, password hashing, auth logic
│   │   │   ├── database.py # Engine, SessionLocal, async session factory
│   │   │   ├── deps.py     # FastAPI dependency injection items
│   │   │   └── exceptions.py # Custom exception classes and handlers
│   │   ├── api/
│   │   │   └── v1/
│   │   │       ├── api.py  # APIRouter aggregation and mounting
│   │   │       └── endpoints/ # Endpoint handlers
│   │   ├── models/         # SQLAlchemy ORM Models
│   │   │   ├── base.py     # Base model with common fields
│   │   │   └── {entity}.py # Entity models
│   │   ├── schemas/        # Pydantic schemas for validation
│   │   │   └── {entity}.py # Request/Response DTOs
│   │   ├── services/       # Business logic layer
│   │   │   └── {entity}_service.py # Complex logic, cross-table operations
│   │   ├── repositories/   # Data access layer
│   │   │   └── {entity}_repo.py # Pure CRUD operations, queries
│   │   ├── utils/          # Utility functions
│   │   │   └── helpers.py  # Date conversion, string processing, validation
│   │   └── middleware/     # Custom middleware (optional)
│   ├── requirements.txt    # Python dependencies
│   └── pyproject.toml      # Project metadata
├── frontend/               # Vue 3 Frontend (Standard Architecture)
│   ├── src/
│   │   ├── main.ts         # App entry (TypeScript)
│   │   ├── api/            # API client layer
│   │   │   ├── http.ts     # Axios instance, interceptors
│   │   │   ├── index.ts    # API module exports
│   │   │   └── {entity}.api.ts # API calls per domain
│   │   ├── components/     # Global reusable components
│   │   │   ├── base/       # Buttons, Modals, Inputs
│   │   │   └── layout/     # Layout-related components
│   │   ├── composables/    # Reusable Composition API logic
│   │   │   └── use{Feature}.ts
│   │   ├── views/          # Page-level components (route targets)
│   │   │   └── {Entity}View.vue
│   │   ├── stores/         # Pinia stores
│   │   │   └── {entity}.store.ts
│   │   ├── types/          # Shared TypeScript types
│   │   │   └── {entity}.ts
│   │   ├── utils/          # Utility helpers
│   │   ├── styles/         # Global CSS (modern design system)
│   │   └── router/         # Vue Router config
│   ├── package.json       # NPM dependencies
│   ├── vite.config.ts      # Vite build config (TypeScript)
│   └── tsconfig.json       # TypeScript configuration
├── nginx/                  # Nginx configuration
└── docker-compose.yml      # Multi-container setup

🚀 Development Commands

Backend Commands

# Navigate to backend
cd backend

# Start development server (recommended)
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Alternative: Use uvicorn directly
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Install dependencies
pip install -r requirements.txt

Frontend Commands

# Navigate to frontend
cd frontend

# Start development server (default port 5180)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Install dependencies
npm install

# Type checking (TypeScript)
npm run type-check

# Linting (if configured)
npm run lint

Docker Commands

# Start all services
docker-compose up --build

# Stop all services
docker-compose down

# View logs
docker-compose logs -f [service_name]

🧪 Testing

Note: No testing framework is currently configured. When adding tests:

• For backend: Add pytest to requirements.txt and create test files in backend/tests/
• For frontend: Add testing setup to package.json (Jest/Vitest recommended)

Running Single Tests (when implemented)

# Backend (pytest)
pytest tests/test_specific.py::test_function_name -v

# Frontend (Jest/Vitest)
npm test -- --testNamePattern="specific test"

📝 Code Style Guidelines

Backend (Python/FastAPI)

Import Organization

# Standard library imports first
import os
from typing import List, Optional

# Third-party imports second
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel

# Local imports last
from app.models.user import UserResponse
from app.core.database import get_db

Naming Conventions

• Files: snake_case.py (e.g., user_service.py)
• Classes: PascalCase (e.g., UserService, UserResponse)
• Functions/Variables: snake_case (e.g., get_users(), user_id)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES)

Type Hints

• Required: All function parameters and return values must have type hints
• Use Pydantic models for request/response validation
• Examples:

async def get_user(user_id: int) -> UserResponse:
    return UserResponse(id=user_id, username="test", email="test@example.com")

def create_user(user: UserCreate) -> UserResponse:
    # Implementation

Error Handling

• Use FastAPI's HTTPException for API errors
• Always include status codes and descriptive messages
• Example:

from fastapi import HTTPException

if not user:
    raise HTTPException(status_code=404, detail="User not found")

Database

• Use SQLAlchemy with async support
• Models in app/db/models.py
• Use dependency injection for database sessions
• Pydantic models in app/models/ for API contracts

Frontend (Vue 3 + TypeScript)

Vue Component Structure

<template>
  <!-- Template content -->
</template>

<script setup lang="ts">
// Use Composition API with TypeScript
import { ref, computed, onMounted } from 'vue'
import { useUserStore } from '../stores/user.store.ts'
import type { User } from '@/types/user.ts'

// Reactive state and methods
const store = useUserStore()
const loading = ref(false)
const user = ref<User | null>(null)

// Expose to template
</script>

<style scoped>
/* Component-specific styles */
</style>

Import Organization

// Vue imports first
import { ref, computed, onMounted } from 'vue'

// External libraries second
import axios from 'axios'

// Local imports last
import { useUserStore } from '../stores/user.store.ts'
import api from '../services/api.js'

Naming Conventions

• Components: PascalCase.vue (e.g., UserProfile.vue)
• Files: kebab-case.js for utilities, PascalCase.vue for components, .ts for TypeScript
• Variables/Functions: camelCase (e.g., userName, fetchUsers())
• CSS Classes: kebab-case (e.g., user-card, loading-spinner)
• Types: PascalCase (e.g., User, UserCreate)

State Management

• Use Pinia for state management
• Stores in src/stores/
• Follow pattern: use[Feature]Store() (e.g., useUserStore())
• Example:

import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useUserStore = defineStore('user', () => {
  const users = ref([])
  const loading = ref(false)
  
  const fetchUsers = async () => {
    loading.value = true
    try {
      // API call
    } finally {
      loading.value = false
    }
  }
  
  return { users, loading, fetchUsers }
})

API Integration

• Use centralized API service in src/api/http.ts
• Axios instance with proper timeout and headers
• Error handling in store methods, not components
• Example:

// api/http.ts
import axios from 'axios'

const http = axios.create({
  baseURL: '/api/v1',
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' }
})

export default http

// In store
import { userApi } from '@/api'

const fetchUsers = async () => {
  const response = await userApi.getUsers()
  users.value = response.items
}

🎨 Styling Guidelines

CSS Architecture

• Global styles: src/styles/global.css (modern design system)
• Component styles: Scoped CSS in each component
• CSS Variables: Use the established design system variables

Design System Variables (from global.css)

/* Colors */
--primary: #667eea
--secondary: #764ba2
--success: #10b981
--warning: #f59e0b
--danger: #ef4444
--info: #3b82f6

/* Spacing */
--spacing-xs: 4px
--spacing-sm: 8px
--spacing-md: 12px
--spacing-lg: 16px
--spacing-xl: 24px

/* Typography */
--font-size-sm: 14px
--font-size-base: 16px
--font-size-lg: 18px
--font-size-xl: 20px

/* Transitions */
--transition-base: 300ms
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1)

Animation Guidelines

• Use CSS animations from global.css (fadeIn, slideUp, etc.)
• Keep animations subtle and purposeful
• Respect prefers-reduced-motion for accessibility

🔧 Environment Configuration

Backend Environment Variables

Create .env in backend directory:

DEBUG=true
APP_NAME="FastAPI Backend"
DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/ai22"

Frontend Configuration

• Vite dev server: http://localhost:5180
• API proxy: /api → http://localhost:8000
• Update vite.config.js for different proxy settings

2026-02-03 (Latest)

• Major Feature Update: 完整的用户管理和权限控制系统
  • 数据库重构: 添加 users, mcp_tools, model_configs, knowledge_graphs 表
  • 权限系统: 实现多对多权限关联表（用户-专家、用户-子智能体、用户-MCP、用户-技能、用户-知识）
  • 后端API:
    • /api/v1/users - 完整的用户CRUD和权限管理
    • /api/v1/mcp - MCP工具管理
    • /api/v1/models - 模型配置管理
    • /api/v1/experts/{id}/knowledge-graphs - 知识图谱管理
  • 前端页面:
    • UserManagement.vue - 用户管理（表格视图、权限配置）
    • MCPManagement.vue - MCP工具管理
    • ModelManagement.vue - 模型配置管理
    • 专家详情页新增"知识图谱"标签页
    • 专家列表新增"创建人"列
  • 数据库驱动: 从 psycopg 切换至 asyncpg，全异步查询优化

2026-02-05

• 专家问题库: 新增专家问题库表结构与CRUD接口
• 子智能体会话库: 新增会话库表结构与CRUD接口，支持点赞/踩与评论
• 前端增强: 专家详情页新增问题库标签页与子智能体会话库管理入口

2026-02-05 (Project Restructure)

• 后端架构重构: 按照FastAPI标准架构调整代码结构
  • 新增 schemas/, repositories/, utils/, middleware/ 目录
  • 新增 core/deps.py 依赖注入配置
  • 新增 core/exceptions.py 异常处理
  • 新增 models/base.py 基础模型
  • 创建示例 schemas/user.py, repositories/user_repo.py, services/user_service.py
• 前端架构重构: 按照Vue 3 + TypeScript标准架构调整
  • 迁移至TypeScript (从JavaScript)
  • 新增 api/, types/, composables/, components/base/, components/layout/ 目录
  • 创建 api/http.ts HTTP客户端配置
  • 创建 api/user.api.ts 用户API模块
  • 创建 stores/user.store.ts Pinia状态管理
  • 创建 types/user.ts, types/common.ts TypeScript类型定义
  • 创建 composables/usePagination.ts 可复用逻辑
• 代码清理: 删除冗余文件和缓存
  • 删除 __pycache__ 目录
  • 删除临时迁移脚本 migrate_question_session.py, migrate_file_fields.py
• 标准化: 统一代码风格和架构模式，符合skill规范要求

2026-02-03 (Earlier)

• Frontend Refactor: Standardized AIExpertManagement.vue and AIExpertDetail.vue to use Element Plus components (Tabs, Dialogs, Tables, Forms) instead of custom CSS components, ensuring consistency with the project's frontend stack requirements.
• Style Cleanup: Removed redundant custom CSS for modals, tabs, and form elements in favor of framework-provided styles.
• Improved UX: Added loading states (v-loading), improved form validation visual cues, and standardized status tags using Element Plus.

📊 Database

• Primary: PostgreSQL (configured in docker-compose.yml)
• ORM: SQLAlchemy 2.0 with async support
• Migration: Manual schema updates (consider Alembic for production)
• Connection: Async connection pool configured in core/database.py

🔐 Security

• Backend: CORS configured for localhost:5173, 3000
• Authentication: JWT tokens (implement when needed)
• Validation: Pydantic models for all API inputs
• Password Hashing: bcrypt via passlib

🌐 API Design

RESTful Conventions

• Endpoints: /api/v1/{resource}
• HTTP Methods: GET, POST, PUT, DELETE
• Status Codes: 200 (success), 201 (created), 400 (bad request), 404 (not found), 500 (server error)
• Responses: JSON with consistent structure

Response Format

# Success response
{"id": 1, "username": "test", "email": "test@example.com"}

# Error response (FastAPI default)
{"detail": "User not found"}

🚀 Performance Guidelines

Frontend

• Use Vue 3 Composition API for better reactivity
• Implement lazy loading for routes if needed
• Use computed properties for derived state
• Debounce search inputs and API calls

Backend

• Use async/await for all I/O operations
• Database queries should be async
• Implement proper connection pooling
• Use pydantic for fast serialization/deserialization

📱 Responsive Design

Breakpoints

• Mobile: < 768px
• Tablet: 768px - 1024px
• Desktop: > 1024px

Guidelines

• Mobile-first approach
• Use CSS Grid and Flexbox for layouts
• Test across all viewport sizes
• Touch-friendly tap targets (minimum 44px)

🔄 Development Workflow

1. Backend First: Create API endpoints and models
2. Frontend Integration: Build UI components and integrate with API
3. State Management: Implement Pinia stores for complex state
4. Styling: Apply design system and ensure responsiveness
5. Testing: Test both API endpoints and UI interactions
6. Docker: Verify docker-compose setup works correctly

🐛 Common Issues & Solutions

CORS Issues

• Ensure backend CORS includes frontend URL
• Check proxy configuration in vite.config.js

Database Connection

• Verify PostgreSQL is running in docker-compose
• Check connection string in environment variables

Import Errors

• Use correct relative imports in Python modules
• Include .js extensions in JavaScript imports

Port Conflicts

• Backend: 8000, Frontend: 5180, Nginx: 80, PostgreSQL: 5432
• Adjust if ports are in use

📚 Additional Resources

• FastAPI Documentation
• Vue 3 Documentation
• Pinia Documentation
• Vite Documentation
• Element Plus UI

🧾 变更记录

• 2026-02-04：专家详情知识库新增左侧目录与子智能体入口，支持按子智能体区分知识条目并在保存时记录归属；后端知识条目支持可选 sub_agent_id 字段与过滤参数。