Repository Guidelines

Project Structure & Module Organization

main.py: app entrypoint.
src/: primary source code.
- src/core/pages/: PyQt UI pages (home/settings/tools, etc.).
- src/core/services/: business services (LLM, template rendering, Chrome profile, etc.).
- src/core/processor/: content/image processing threads and helpers.
templates/: prompt templates (e.g. templates/prompts/*.json).
assets/: bundled template showcase assets.
tests/: unit/integration tests and pytest config (tests/pytest.ini).
docs/, images/: documentation and screenshots.

Install & run (macOS/Linux):

./install.sh
./启动程序.sh

Manual run:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

Playwright browser (only if needed):

PLAYWRIGHT_BROWSERS_PATH="$HOME/.xhs_system/ms-playwright" python -m playwright install chromium

Tests:

pip install -r tests/requirements.txt
pytest -q
pytest -m unit

Python: 4-space indentation, snake_case for functions/vars, CapWords for classes.
Keep UI code in src/core/pages/ and reusable logic in src/core/services/.
Prefer small, testable functions; avoid unrelated refactors in the same PR.

Framework: pytest (see markers in tests/pytest.ini like unit, integration, browser).
Naming: test_*.py, Test* classes, test_* functions.
Mark slow/network/browser tests appropriately and keep unit tests deterministic.

Commit style in this repo commonly uses prefixes like feat:, fix:, docs:, chore: (Chinese descriptions are OK).
PRs should include: a short problem/solution summary, steps to verify, and UI screenshots when changing layouts (store under docs/assets/ or images/).
If you change user-facing behavior, update both readme.md and readme_en.md.

Never commit real keys. Use .env locally (it’s gitignored) and keep secrets empty in .env.example.
Local runtime data lives under ~/.xhs_system/ (db, logs, cached images, Playwright browsers).