mirror of
https://github.com/willmiao/ComfyUI-Lora-Manager.git
synced 2026-03-21 21:22:11 -03:00
feat(docs): update AGENTS.md with improved testing and development instructions
- Simplify pytest coverage command by consolidating --cov flags - Remove redundant JSON coverage report - Reorganize frontend section into "Frontend Development (Standalone Web UI)" and "Vue Widget Development" - Add npm commands for Vue widget development (dev, build, typecheck, tests) - Consolidate Python code style sections (imports, formatting, naming, error handling, async) - Update architecture overview with clearer service descriptions - Fix truncated line in API endpoints note - Improve readability and remove redundant information
This commit is contained in:
Will Miao
181
AGENTS.md
181
AGENTS.md
@@ -25,168 +25,127 @@ pytest tests/test_recipes.py::test_function_name
|
||||
|
||||
# Run backend tests with coverage
|
||||
COVERAGE_FILE=coverage/backend/.coverage pytest \
|
||||
--cov=py \
|
||||
--cov=standalone \
|
||||
--cov=py --cov=standalone \
|
||||
--cov-report=term-missing \
|
||||
--cov-report=html:coverage/backend/html \
|
||||
--cov-report=xml:coverage/backend/coverage.xml \
|
||||
--cov-report=json:coverage/backend/coverage.json
|
||||
--cov-report=xml:coverage/backend/coverage.xml
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
### Frontend Development (Standalone Web UI)
|
||||
|
||||
```bash
|
||||
# Install frontend dependencies
|
||||
npm install
|
||||
npm test # Run all tests (JS + Vue)
|
||||
npm run test:js # Run JS tests only
|
||||
npm run test:watch # Watch mode
|
||||
npm run test:coverage # Generate coverage report
|
||||
```
|
||||
|
||||
# Run frontend tests
|
||||
npm test
|
||||
### Vue Widget Development
|
||||
|
||||
# Run frontend tests in watch mode
|
||||
npm run test:watch
|
||||
|
||||
# Run frontend tests with coverage
|
||||
npm run test:coverage
|
||||
```bash
|
||||
cd vue-widgets
|
||||
npm install
|
||||
npm run dev # Build in watch mode
|
||||
npm run build # Build production bundle
|
||||
npm run typecheck # Run TypeScript type checking
|
||||
npm test # Run Vue widget tests
|
||||
npm run test:watch # Watch mode
|
||||
npm run test:coverage # Generate coverage report
|
||||
```
|
||||
|
||||
## Python Code Style
|
||||
|
||||
### Imports
|
||||
### Imports & Formatting
|
||||
|
||||
- Use `from __future__ import annotations` for forward references in type hints
|
||||
- Group imports: standard library, third-party, local (separated by blank lines)
|
||||
- Use absolute imports within `py/` package: `from ..services import X`
|
||||
- Mock ComfyUI dependencies in tests using `tests/conftest.py` patterns
|
||||
|
||||
### Formatting & Types
|
||||
|
||||
- PEP 8 with 4-space indentation
|
||||
- Type hints required for function signatures and class attributes
|
||||
- Use `TYPE_CHECKING` guard for type-checking-only imports
|
||||
- Prefer dataclasses for simple data containers
|
||||
- Use `Optional[T]` for nullable types, `Union[T, None]` only when necessary
|
||||
- Use `from __future__ import annotations` for forward references
|
||||
- Group imports: standard library, third-party, local (blank line separated)
|
||||
- Absolute imports within `py/`: `from ..services import X`
|
||||
- PEP 8 with 4-space indentation, type hints required
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- Files: `snake_case.py` (e.g., `model_scanner.py`, `lora_service.py`)
|
||||
- Classes: `PascalCase` (e.g., `ModelScanner`, `LoraService`)
|
||||
- Functions/variables: `snake_case` (e.g., `get_instance`, `model_type`)
|
||||
- Constants: `UPPER_SNAKE_CASE` (e.g., `VALID_LORA_TYPES`)
|
||||
- Private members: `_single_underscore` (protected), `__double_underscore` (name-mangled)
|
||||
- Files: `snake_case.py`, Classes: `PascalCase`, Functions/vars: `snake_case`
|
||||
- Constants: `UPPER_SNAKE_CASE`, Private: `_protected`, `__mangled`
|
||||
|
||||
### Error Handling
|
||||
### Error Handling & Async
|
||||
|
||||
- Use `logging.getLogger(__name__)` for module-level loggers
|
||||
- Define custom exceptions in `py/services/errors.py`
|
||||
- Use `asyncio.Lock` for thread-safe singleton patterns
|
||||
- Raise specific exceptions with descriptive messages
|
||||
- Log errors at appropriate levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
||||
- Use `logging.getLogger(__name__)`, define custom exceptions in `py/services/errors.py`
|
||||
- `async def` for I/O, `@pytest.mark.asyncio` for async tests
|
||||
- Singleton with `asyncio.Lock`: see `ModelScanner.get_instance()`
|
||||
- Return `aiohttp.web.json_response` or `web.Response`
|
||||
|
||||
### Async Patterns
|
||||
### Testing
|
||||
|
||||
- Use `async def` for I/O-bound operations
|
||||
- Mark async tests with `@pytest.mark.asyncio`
|
||||
- Use `async with` for context managers
|
||||
- Singleton pattern with class-level locks: see `ModelScanner.get_instance()`
|
||||
- Use `aiohttp.web.Response` for HTTP responses
|
||||
- `pytest` with `--import-mode=importlib`
|
||||
- Fixtures in `tests/conftest.py`, use `tmp_path_factory` for isolation
|
||||
- Mark tests needing real paths: `@pytest.mark.no_settings_dir_isolation`
|
||||
- Mock ComfyUI dependencies via conftest patterns
|
||||
|
||||
### Testing Patterns
|
||||
|
||||
- Use `pytest` with `--import-mode=importlib`
|
||||
- Fixtures in `tests/conftest.py` handle ComfyUI mocking
|
||||
- Use `@pytest.mark.no_settings_dir_isolation` for tests needing real paths
|
||||
- Test files: `tests/test_*.py`
|
||||
- Use `tmp_path_factory` for temporary directory isolation
|
||||
|
||||
## JavaScript Code Style
|
||||
## JavaScript/TypeScript Code Style
|
||||
|
||||
### Imports & Modules
|
||||
|
||||
- ES modules with `import`/`export`
|
||||
- Use `import { app } from "../../scripts/app.js"` for ComfyUI integration
|
||||
- Export named functions/classes: `export function foo() {}`
|
||||
- Widget files use `*_widget.js` suffix
|
||||
- ES modules: `import { app } from "../../scripts/app.js"` for ComfyUI
|
||||
- Vue: `import { ref, computed } from 'vue'`, type imports: `import type { Foo }`
|
||||
- Export named functions: `export function foo() {}`
|
||||
|
||||
### Naming & Formatting
|
||||
|
||||
- camelCase for functions, variables, object properties
|
||||
- PascalCase for classes/constructors
|
||||
- Constants: `UPPER_SNAKE_CASE` (e.g., `CONVERTED_TYPE`)
|
||||
- Files: `snake_case.js` or `kebab-case.js`
|
||||
- camelCase for functions/vars/props, PascalCase for classes
|
||||
- Constants: `UPPER_SNAKE_CASE`, Files: `snake_case.js` or `kebab-case.js`
|
||||
- 2-space indentation preferred (follow existing file conventions)
|
||||
- Vue Single File Components: `<script setup lang="ts">` preferred
|
||||
|
||||
### Widget Development
|
||||
|
||||
- Use `app.registerExtension()` to register ComfyUI extensions
|
||||
- Use `node.addDOMWidget(name, type, element, options)` for custom widgets
|
||||
- Event handlers attached via `addEventListener` or widget callbacks
|
||||
- See `web/comfyui/utils.js` for shared utilities
|
||||
- ComfyUI: `app.registerExtension()`, `node.addDOMWidget(name, type, element, options)`
|
||||
- Event handlers via `addEventListener` or widget callbacks
|
||||
- Shared utilities: `web/comfyui/utils.js`
|
||||
|
||||
### Vue Composables Pattern
|
||||
|
||||
- Use composition API: `useXxxState(widget)`, return reactive refs and methods
|
||||
- Guard restoration loops with flag: `let isRestoring = false`
|
||||
- Build config from state: `const buildConfig = (): Config => { ... }`
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Service Layer
|
||||
|
||||
- Use `ServiceRegistry` singleton for dependency injection
|
||||
- Services follow singleton pattern via `get_instance()` class method
|
||||
- `ServiceRegistry` singleton for DI, services use `get_instance()` classmethod
|
||||
- Separate scanners (discovery) from services (business logic)
|
||||
- Handlers in `py/routes/handlers/` implement route logic
|
||||
- Handlers in `py/routes/handlers/` are pure functions with deps as params
|
||||
|
||||
### Model Types
|
||||
### Model Types & Routes
|
||||
|
||||
- BaseModelService is abstract base for LoRA, Checkpoint, Embedding services
|
||||
- ModelScanner provides file discovery and hash-based deduplication
|
||||
- Persistent cache in SQLite via `PersistentModelCache`
|
||||
- Metadata sync from CivitAI/CivArchive via `MetadataSyncService`
|
||||
|
||||
### Routes & Handlers
|
||||
|
||||
- Route registrars organize endpoints by domain: `ModelRouteRegistrar`, etc.
|
||||
- Handlers are pure functions taking dependencies as parameters
|
||||
- Use `WebSocketManager` for real-time progress updates
|
||||
- Return `aiohttp.web.json_response` or `web.Response`
|
||||
- `BaseModelService` base for LoRA, Checkpoint, Embedding
|
||||
- `ModelScanner` for file discovery, hash deduplication
|
||||
- `PersistentModelCache` (SQLite) for persistence
|
||||
- Route registrars: `ModelRouteRegistrar`, endpoints: `/loras/*`, `/checkpoints/*`, `/embeddings/*`
|
||||
- WebSocket via `WebSocketManager` for real-time updates
|
||||
|
||||
### Recipe System
|
||||
|
||||
- Base metadata in `py/recipes/base.py`
|
||||
- Enrichment adds model metadata: `RecipeEnrichmentService`
|
||||
- Parsers for different formats in `py/recipes/parsers/`
|
||||
- Base: `py/recipes/base.py`, Enrichment: `RecipeEnrichmentService`
|
||||
- Parsers: `py/recipes/parsers/`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- Always use English for comments (per copilot-instructions.md)
|
||||
- Dual mode: ComfyUI plugin (uses folder_paths) vs standalone (reads settings.json)
|
||||
- ALWAYS use English for comments (per copilot-instructions.md)
|
||||
- Dual mode: ComfyUI plugin (folder_paths) vs standalone (settings.json)
|
||||
- Detection: `os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1"`
|
||||
- Settings auto-saved in user directory or portable mode
|
||||
- WebSocket broadcasts for real-time updates (downloads, scans)
|
||||
- Symlink handling requires normalized paths
|
||||
- API endpoints follow `/loras/*`, `/checkpoints/*`, `/embeddings/*` patterns
|
||||
- Run `python scripts/sync_translation_keys.py` after UI string updates
|
||||
- Symlinks require normalized paths
|
||||
|
||||
## Frontend UI Architecture
|
||||
|
||||
This project has two distinct UI systems:
|
||||
|
||||
### 1. Standalone Lora Manager Web UI
|
||||
### 1. Standalone Web UI
|
||||
- Location: `./static/` and `./templates/`
|
||||
- Purpose: Full-featured web application for managing LoRA models
|
||||
- Tech stack: Vanilla JS + CSS, served by the standalone server
|
||||
- Development: Uses npm for frontend testing (`npm test`, `npm run test:watch`, etc.)
|
||||
- Tech: Vanilla JS + CSS, served by standalone server
|
||||
- Tests via npm in root directory
|
||||
|
||||
### 2. ComfyUI Custom Node Widgets
|
||||
- Location: `./web/comfyui/`
|
||||
- Purpose: Widgets and UI logic that ComfyUI loads as custom node extensions
|
||||
- Tech stack: Vanilla JS + Vue.js widgets (in `./vue-widgets/` and built to `./web/comfyui/vue-widgets/`)
|
||||
- Widget styling: Primary styles in `./web/comfyui/lm_styles.css` (NOT `./static/css/`)
|
||||
- Development: No npm build step for these widgets (Vue widgets use build system)
|
||||
|
||||
### Widget Development Guidelines
|
||||
- Use `app.registerExtension()` to register ComfyUI extensions (ComfyUI integration layer)
|
||||
- Use `node.addDOMWidget()` for custom DOM widgets
|
||||
- Widget styles should follow the patterns in `./web/comfyui/lm_styles.css`
|
||||
- Selected state: `rgba(66, 153, 225, 0.3)` background, `rgba(66, 153, 225, 0.6)` border
|
||||
- Hover state: `rgba(66, 153, 225, 0.2)` background
|
||||
- Color palette matches the Lora Manager accent color (blue #4299e1)
|
||||
- Use oklch() for color values when possible (defined in `./static/css/base.css`)
|
||||
- Vue widget components are in `./vue-widgets/src/components/` and built to `./web/comfyui/vue-widgets/`
|
||||
- When modifying widget styles, check `./web/comfyui/lm_styles.css` for consistency with other ComfyUI widgets
|
||||
|
||||
- Location: `./web/comfyui/` (Vanilla JS) + `./vue-widgets/` (Vue)
|
||||
- Primary styles: `./web/comfyui/lm_styles.css` (NOT `./static/css/`)
|
||||
- Vue builds to `./web/comfyui/vue-widgets/`, typecheck via `vue-tsc`
|
||||
|
||||
Reference in New Issue
Block a user