SillyTavern_replica/AGENTS.md

AI Agent Guidance for this Repository

Repository overview

• Backend: backend/ using FastAPI, Python 3.11+, uvicorn --reload for development.
• Frontend: frontend/ using React 18 + Vite + TypeScript, with Zustand for state.
• Runtime data is stored under data/ as JSON/files; do not treat it as source code.
• Docker support exists via docker-compose.yml and docs/DOCKER_DEV.md.

What an AI coding agent should do first

1. Read README.md and docs/DOCKER_DEV.md before proposing environment or run commands.
2. Identify whether a change belongs in backend/ or frontend/.
3. Prefer small, incremental edits.
4. When in doubt, ask the user before making large refactors or architectural changes.

Build / run commands

Backend local

• python -m venv venv
• venv\Scripts\activate (Windows)
• pip install -r backend/requirements.txt
• cd backend && python main.py

Frontend local

• cd frontend
• npm install
• npm run dev

Docker development

• .\scripts\docker-up.ps1
• .\scripts\docker-restart.ps1 -Service backend
• .\scripts\docker-rebuild.ps1 -Service backend
• .\scripts\docker-logs.ps1
• docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Testing and quality checks

• Backend tests live in backend/tests/.
• Use python -m pytest backend/tests for automated backend test runs.
• Frontend has lint/type-check scripts in frontend/package.json:
  • npm run lint
  • npm run type-check
• Prefer adding or updating tests for bug fixes, new features, and non-trivial behavior changes.
• Keep changes tidy and consistent with the repository's existing style.

Code conventions and review preferences

• The user prefers code that is:
  • 基本审查过的
  • 规范整洁的
  • 严谨测试覆盖的
• Do not perform sweeping refactors without explicit user approval.
• If a change affects core logic, clearly explain the reason and the hypothesis for the fix.
• For any change, state whether it is:
  • bug fix
  • cleanup/refactor
  • feature addition

Important paths and domains

• backend/main.py — FastAPI app entrypoint
• backend/api/ — HTTP route definitions
• backend/services/ — core business logic and domain services
• backend/models/ — data models and converters
• backend/utils/ — shared helper modules
• frontend/src/ — React source code
• frontend/package.json — frontend scripts and dependencies
• docs/DOCKER_DEV.md — Docker development guidance

Practical guidance for AI agents

• Avoid editing generated or runtime content in data/ unless explicitly asked.
• Prefer changes that are easy to reason about and test.
• Use existing test tools rather than inventing new workflows.
• Link to repository docs instead of duplicating long explanations.
• If a requested change is uncertain, ask for clarification rather than guessing.

References

• README.md
• docs/DOCKER_DEV.md
• frontend/package.json
• backend/requirements.txt