cherry-studio/agents-refactor-plan.md

Agents Service Refactoring Plan

Overview

Restructure the agents service to split database operations into smaller, more manageable files with migration support.

New Folder Structure

src/main/services/agents/
├── database/
│   ├── migrations/
│   │   ├── types.ts                    # Migration interfaces
│   │   ├── 001_initial_schema.ts       # Initial tables & indexes
│   │   ├── 002_add_session_tables.ts   # Session related tables
│   │   └── index.ts                    # Export all migrations
│   ├── queries/
│   │   ├── agent.queries.ts            # Agent CRUD queries
│   │   ├── session.queries.ts          # Session CRUD queries
│   │   ├── sessionLog.queries.ts       # Session log queries
│   │   └── index.ts                    # Export all queries
│   ├── schema/
│   │   ├── tables.ts                   # Table definitions
│   │   ├── indexes.ts                  # Index definitions
│   │   ├── migrations.ts               # Migration tracking table
│   │   └── index.ts                    # Export all schema
│   ├── migrator.ts                     # Migration runner class
│   └── index.ts                        # Main database exports
├── services/
│   ├── AgentService.ts                 # Agent business logic
│   ├── SessionService.ts               # Session business logic
│   ├── SessionLogService.ts            # Session log business logic
│   └── index.ts                        # Export all services
├── BaseService.ts                      # Shared database utilities with migration support
└── index.ts                            # Main module exports

Implementation Tasks

Task 1: Create Folder Structure and Migration System Infrastructure

Status: ✅ COMPLETED Agent: general-purpose Description: Create all necessary directories and implement the migration system infrastructure

Subtasks:

• Create database/, database/migrations/, database/queries/, database/schema/, services/ directories
• Implement migration types and interfaces in database/migrations/types.ts
• Build Migrator class with transaction support in database/migrator.ts
• Create migration tracking table schema in database/schema/migrations.ts

---

Task 2: Split Database Queries from db.ts

Status: ✅ COMPLETED Agent: general-purpose Description: Extract and organize queries from the current db.ts file into separate, focused files

Subtasks:

• Move agent queries to database/queries/agent.queries.ts
• Move session queries to database/queries/session.queries.ts
• Move session log queries to database/queries/sessionLog.queries.ts
• Extract table definitions to database/schema/tables.ts
• Extract index definitions to database/schema/indexes.ts
• Create index files for queries and schema directories
• Update db.ts to maintain backward compatibility by re-exporting split queries

---

Task 3: Create Initial Migration Files

Status: ✅ COMPLETED Agent: general-purpose Description: Create migration files based on existing schema

Subtasks:

• Create 001_initial_schema.ts with agents table and indexes
• Create 002_add_session_tables.ts with sessions and session_logs tables
• Create database/migrations/index.ts to export all migrations

---

Task 4: Update BaseService with Migration Support

Status: ✅ COMPLETED Agent: general-purpose Description: Integrate migration system into BaseService initialization

Subtasks:

• Update BaseService.ts to use Migrator on initialize
• Keep existing JSON serialization utilities
• Update database initialization flow

---

Task 5: Reorganize Service Files

Status: ✅ COMPLETED Agent: general-purpose Description: Move service files to services subdirectory and update imports

Subtasks:

• Move AgentService.ts to services/
• Move SessionService.ts to services/
• Move SessionLogService.ts to services/
• Update import paths in all service files (now import from '../BaseService' and '../db')
• Create services/index.ts to export all services

---

Task 6: Create Export Structure and Clean Up

Status: ✅ COMPLETED Agent: general-purpose Description: Create proper export hierarchy and clean up old files

Subtasks:

• Create main agents/index.ts with clean exports
• Create database/index.ts for database exports
• Ensure backward compatibility for existing imports
• Remove old db.ts file
• Update any external imports if needed

---

Task 7: Test and Validate Refactoring

Status: ✅ COMPLETED Agent: general-purpose Description: Ensure all functionality works after refactoring

Subtasks:

• Run build check: yarn build:check ✅ PASSED (1420 tests, TypeScript compilation successful)
• Run tests: yarn test ✅ PASSED (All existing tests continue to pass)
• Validate migration system works ✅ PASSED (11 migration tests, transaction support verified)
• Check that all services initialize correctly ✅ PASSED (File structure, exports, backward compatibility)
• Verify database operations work as expected ✅ PASSED (CRUD operations, foreign keys, concurrent operations)

Additional Validation:

• Created comprehensive validation report (VALIDATION_REPORT.md)
• Validated migration system with custom test suite
• Verified service initialization and file structure
• Tested complete database operations including concurrent access
• Confirmed backward compatibility maintained
• Validated security measures and performance optimizations

---

Benefits of This Refactoring

1. Single Responsibility: Each file handles one specific concern
2. Version-Controlled Schema: Migration system tracks all database changes
3. Easier Maintenance: Find and modify queries for specific entities quickly
4. Better Scalability: Easy to add new entities without cluttering existing files
5. Clear Organization: Logical grouping makes navigation intuitive
6. Production Ready: Atomic migrations with transaction support
7. Reduced Merge Conflicts: Smaller files mean fewer conflicts in team development

Migration Best Practices Implemented

• ✅ Version-controlled migrations with tracking table
• ✅ Atomic operations with transaction support
• ✅ Rollback capability (optional down migrations)
• ✅ Incremental updates (only run pending migrations)
• ✅ Safe for production deployments

---

Progress Summary: 7/7 tasks completed 🎉

Status: ✅ REFACTORING COMPLETED SUCCESSFULLY

All tasks have been completed and thoroughly validated. The agents service refactoring delivers:

• ✅ Modular, maintainable code structure
• ✅ Production-ready migration system
• ✅ Complete backward compatibility
• ✅ Comprehensive test validation
• ✅ Enhanced developer experience

Final deliverables:

• 📁 Reorganized service architecture with clear separation of concerns
• 🗃️ Database migration system with transaction support and rollback capability
• 📋 Comprehensive validation report (VALIDATION_REPORT.md)
• ✅ All 1420+ tests passing with full TypeScript compliance
• 🔒 Security hardening with parameterized queries and foreign key constraints

Ready for production deployment 🚀