Imported from CloverKG369/Media-Tools (AGENTS.md). Install upstream with npx skills add CloverKG369/Media-Tools. Copyright stays with the author.

AGENTS.md — {{PROJECT_NAME}}

Agent System v2.0 for AI-assisted PySide6 Desktop Application Development.

Project Identity

Read .project.json for project-specific values. Replace {{PROJECT_NAME}} and {{PROJECT_EXECUTABLE}} with actual values from that file.

Project Context

• Type: Python Desktop Application
• Framework: PySide6 (Qt6 for Python)
• Python: 3.11+
• Architecture: MVC with Service Layer

Technology Stack

Agent System (13 Agents)

Skills Library (39 Skills)

Core Python (8)

python-pro · python-patterns · python-design-patterns · python-code-style · python-type-safety · python-project-structure · python-configuration · async-python-patterns

UI/Desktop (4)

qt-material · qt-signals-slots · qt-threading · pyside6-patterns

Quality (8)

clean-code · code-reviewer · error-handling-patterns · python-anti-patterns · python-testing-patterns · python-error-handling · python-observability · python-resource-management

Architecture (3)

architecture · api-design-principles · i18n-localization

Packaging (2)

desktop-packaging · python-packaging

Security (2)

api-security-best-practices · security-hardening

Automation & AI (3)

drissionpage-patterns · playwright-stealth · llm-integration

Testing (2)

test-driven-development · pytest-qt-patterns

Methodology (4)

systematic-debugging · writing-plans · brainstorming · context-engineering

Other (3)

flat-minimal-ui · ci-cd-desktop · python-performance-optimization

Instructions (8 Files)

Core Rules

Threading

• NEVER block main thread
• Use QThread + Worker pattern for background tasks
• Emit signals to update UI from threads
• Use QTimer.singleShot() instead of time.sleep() in main thread

Code Style

• Type hints required (Python 3.11+ syntax)
• Use pathlib.Path, not os.path
• Logging via core.logging_config.get_logger()
• Localization via core.localization.tr()
• All code MUST pass Pylint (see .pylintrc)

qt-material Theming

• Dark theme: dark_teal.xml (default)
• Light theme: light_teal_500.xml (always with invert_secondary=True)
• Semantic buttons: setProperty('class', 'danger/warning/success')
• Never write full QSS from scratch — use apply_stylesheet() + extra dict
• Access theme colors via os.environ['QTMATERIAL_PRIMARYCOLOR'] etc.

Security

• No hardcoded credentials — use OS keyring
• Validate all file paths against traversal
• No shell=True in subprocess calls
• HTTPS enforced for all external requests

Automation

• Use DrissionPage for simple automation, Playwright + stealth for complex/anti-bot
• Always apply stealth_async(page) for Playwright
• Always add human-like delays
• Implement retry logic with exponential backoff
• Run automation in QThread, never main thread
• Do NOT use Selenium

Forbidden Patterns

File Structure

{{PROJECT_EXECUTABLE}}/
├── main.py                 # Application entry point
├── .project.json           # Project identity
├── requirements.txt        # Dependencies
├── controllers/            # MVC Controllers
├── core/                   # Config, logging, models
├── services/               # Business logic
│   ├── automation/         # Browser automation
│   ├── downloader/         # Download services
│   ├── license/            # License management
│   └── subtitle/           # Subtitle processing
├── ui/                     # User interface
│   ├── main_window.py      # Main QMainWindow
│   ├── tabs/               # Tab widgets
│   ├── widgets/            # Reusable widgets
│   ├── dialogs/            # QDialog subclasses
│   └── resources/          # Icons, images
├── tests/                  # pytest tests
├── scripts/                # Build & automation scripts
├── bin/                    # External binaries
├── docs/                   # Documentation
└── .github/
    ├── agents/             # 13 agent definitions
    ├── skills/             # 39 skill files
    ├── instructions/       # 8 instruction files
    ├── templates/          # Code templates
    ├── prompts/            # Reusable prompts
    └── plans/              # Implementation plans

Quick Commands

# Activate venv first (required)
.\.venv\Scripts\Activate.ps1

# Run application
python main.py

# Run tests
pytest tests/ -v

# Type checking
mypy . --strict

# Lint (Ruff - fast)
ruff check .
ruff format .

# Security audit
pip audit

# Build executable
python scripts/build.py

# Install dependencies
pip install -r requirements.txt

Related Files

• .project.json — Edit this first! Project name and executable
• .pylintrc — Pylint configuration for PySide6
• .github/copilot-instructions.md — Detailed coding standards
• .github/agents/README.md — Agent system documentation
• .github/instructions/ — Path-specific rules
• .github/skills/ — Domain knowledge (39 skills)
• .github/plans/analysis-report.md — System analysis report

Version: 2.1.0 | Last updated: 2026-02-10