chore: add MCP configuration and Claude project instructions (#637)
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
tecvan
GitHub
parent
8712be6a6b
commit
c5f052892a
|
|
@ -0,0 +1,11 @@
|
|||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${GITHUB_PAT}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,196 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Coze Studio is an all-in-one AI agent development platform with both frontend (React + TypeScript) and backend (Go) components. The project uses a sophisticated monorepo architecture managed by Rush.js with 135+ frontend packages organized in a hierarchical dependency system.
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Environment Setup
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone https://github.com/coze-dev/coze-studio.git
|
||||
cd coze-studio
|
||||
|
||||
# Install frontend dependencies
|
||||
rush update
|
||||
|
||||
# For Docker-based development
|
||||
cd docker
|
||||
cp .env.example .env
|
||||
# Configure model settings in backend/conf/model/
|
||||
docker compose up -d
|
||||
# Access at http://localhost:8888
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
```bash
|
||||
# Start middleware services (MySQL, Redis, Elasticsearch, etc.)
|
||||
make middleware
|
||||
|
||||
# Start Go backend in development mode
|
||||
make server
|
||||
|
||||
# Start frontend development server
|
||||
cd frontend/apps/coze-studio
|
||||
npm run dev
|
||||
|
||||
# Full development environment
|
||||
make debug
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
```bash
|
||||
# Build frontend only
|
||||
make fe
|
||||
|
||||
# Build Go server
|
||||
make build_server
|
||||
|
||||
# Build everything with Docker
|
||||
make web
|
||||
|
||||
# Rush monorepo commands
|
||||
rush build # Build all packages
|
||||
rush rebuild -o @coze-studio/app # Build specific package
|
||||
rush test # Run all tests
|
||||
rush lint # Lint all packages
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run tests (Vitest-based)
|
||||
rush test
|
||||
npm run test # In specific package
|
||||
npm run test:cov # With coverage
|
||||
|
||||
# Backend tests
|
||||
cd backend && go test ./...
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Frontend Architecture
|
||||
- **Monorepo**: Rush.js with 135+ packages across 4 dependency levels
|
||||
- **Build System**: Rsbuild (Rspack-based) for fast builds
|
||||
- **UI Framework**: React 18 + TypeScript + Semi Design + Tailwind CSS
|
||||
- **State Management**: Zustand for global state
|
||||
- **Package Organization**:
|
||||
- `arch/`: Core infrastructure (level-1)
|
||||
- `common/`: Shared components and utilities (level-2)
|
||||
- `agent-ide/`, `workflow/`, `studio/`: Feature domains (level-3)
|
||||
- `apps/coze-studio`: Main application (level-4)
|
||||
|
||||
### Backend Architecture (Go)
|
||||
- **Framework**: Hertz HTTP framework
|
||||
- **Architecture**: Domain-Driven Design (DDD) with microservices
|
||||
- **Structure**:
|
||||
- `domain/`: Business logic and entities
|
||||
- `application/`: Application services and use cases
|
||||
- `api/`: HTTP handlers and routing
|
||||
- `infra/`: Infrastructure implementations
|
||||
- `crossdomain/`: Cross-cutting concerns
|
||||
|
||||
### Key Architectural Patterns
|
||||
- **Adapter Pattern**: Extensive use for loose coupling between layers
|
||||
- **Interface Segregation**: Clear contracts between domains
|
||||
- **Event-Driven**: NSQ message queue for async communication
|
||||
- **API-First**: Comprehensive OpenAPI specifications
|
||||
|
||||
## Database & Infrastructure
|
||||
|
||||
### Docker Services Stack
|
||||
- **Database**: MySQL 8.4.5
|
||||
- **Cache**: Redis 8.0
|
||||
- **Search**: Elasticsearch 8.18.0 with SmartCN analyzer
|
||||
- **Vector DB**: Milvus v2.5.10 for embeddings
|
||||
- **Storage**: MinIO for object storage
|
||||
- **Message Queue**: NSQ (nsqlookupd, nsqd, nsqadmin)
|
||||
- **Configuration**: etcd 3.5
|
||||
|
||||
### Database Management
|
||||
```bash
|
||||
# Sync database schema
|
||||
make sync_db
|
||||
|
||||
# Dump database schema
|
||||
make dump_db
|
||||
|
||||
# Initialize SQL data
|
||||
make sql_init
|
||||
|
||||
# Atlas migration management
|
||||
make atlas-hash
|
||||
```
|
||||
|
||||
## Key Development Patterns
|
||||
|
||||
### Frontend Package Development
|
||||
- Each package follows consistent structure with `README.md`, `package.json`, `tsconfig.json`, `eslint.config.js`
|
||||
- Adapter pattern extensively used for decoupling (e.g., `-adapter` suffix packages)
|
||||
- Base/Core pattern for shared functionality (e.g., `-base` suffix packages)
|
||||
- Use workspace references (`workspace:*`) for internal dependencies
|
||||
|
||||
### Backend Development
|
||||
- Follow DDD principles with clear domain boundaries
|
||||
- Use dependency injection via interfaces
|
||||
- Implement proper error handling with custom error types
|
||||
- Write comprehensive tests for domain logic
|
||||
|
||||
### Model Configuration
|
||||
Before deployment, configure AI models in `backend/conf/model/`:
|
||||
1. Copy template from `backend/conf/model/template/`
|
||||
2. Set `id`, `meta.conn_config.api_key`, and `meta.conn_config.model`
|
||||
3. Supported providers: OpenAI, Volcengine Ark, Claude, Gemini, Qwen, DeepSeek, Ollama
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Coverage Requirements by Package Level
|
||||
- **Level 1**: 80% coverage, 90% increment
|
||||
- **Level 2**: 30% coverage, 60% increment
|
||||
- **Level 3-4**: 0% coverage (flexible)
|
||||
|
||||
### Testing Framework
|
||||
- **Frontend**: Vitest for unit/integration tests
|
||||
- **Backend**: Go's built-in testing framework
|
||||
- **E2E**: Separate e2e subspace configuration
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### Frontend Development
|
||||
- Use `rush update` instead of `npm install` at root level
|
||||
- Build packages in dependency order using `rush build`
|
||||
- For hot reload issues, check Rsbuild configuration in specific package
|
||||
|
||||
### Backend Development
|
||||
- Ensure middleware services are running (`make middleware`)
|
||||
- Check database connectivity and schema sync
|
||||
- Verify model configurations are properly set
|
||||
|
||||
### Docker Issues
|
||||
- Ensure sufficient resources (minimum 2 Core, 4GB RAM)
|
||||
- Check port conflicts (8888 for frontend, various for services)
|
||||
- Use `make clean` to reset Docker volumes if needed
|
||||
|
||||
## IDL and Code Generation
|
||||
|
||||
The project uses Interface Definition Language (IDL) for API contract management:
|
||||
- IDL files in `idl/` directory (Thrift format)
|
||||
- Frontend code generation via `@coze-arch/idl2ts-*` packages
|
||||
- Backend uses generated Go structs
|
||||
|
||||
## Plugin Development
|
||||
|
||||
For custom plugin development:
|
||||
- Reference templates in `backend/conf/plugin/pluginproduct/`
|
||||
- Follow OAuth schema in `backend/conf/plugin/common/oauth_schema.json`
|
||||
- Configure authentication keys for third-party services
|
||||
|
||||
## Contributing
|
||||
|
||||
- Use conventional commits via `rush commit`
|
||||
- Run linting with `rush lint-staged` (pre-commit hook)
|
||||
- Ensure tests pass before submitting PRs
|
||||
- Follow team-based package organization and tagging conventions
|
||||
Loading…
Reference in New Issue