Development
Source map
| Directory | Responsibility |
|---|---|
sagents/v2/ | Runtime contracts, composition, providers, and execution |
app/v2/desktop/ | Flutter UI and local FastAPI sidecar |
app/v2/server/ | Multi-user server and Vue web client |
tests/sagents/v2/ | Runtime tests and conformance checks |
tests/app/v2/desktop/, tests/app/v2/server/ | Host integration tests |
docs/en/, docs/zh/ | Current bilingual v2 documentation |
Validate a change
Use the Python 3.12+ environment from Getting Started. Install server extras for server tests:
python -m pip install -e '.[server-v2]' pytest pytest-asyncio pytest-timeout
python -m pytest tests/sagents/v2 tests/app/v2/desktop tests/app/v2/server -q
Run focused tests while developing. Live-provider tests require explicit configuration and may incur model costs. Database tests with injected test stores do not prove production MySQL behavior.
cd app/v2/desktop
flutter analyze
flutter test
cd app/v2/server/web
npm install
npm run build
Documentation checks
.venv/bin/python docs/scripts/check_docs.py
.venv/bin/python -m unittest discover -s docs/scripts -p 'test_*.py'
bash docs/scripts/build_jekyll.sh
python3 docs/scripts/check_language_nav.py
The Jekyll build requires Ruby and the gems in docs/Gemfile. Current pages must have matching language metadata, valid local links, and a v2 source reference. Historical files belong in docs/archive/, which is excluded from publication. Do not turn old audit pass counts into current readiness guarantees.
The checks compare English/Chinese page sets, navigation metadata, heading structure, code examples, and link targets. Route and environment-variable inventories are checked against current Server v2 source. After building, every published language page is checked for a complete, consistent sidebar and an exact language-switch counterpart.