Developer Guide¶
Environment¶
Use Python 3.10–3.13. Install the package editable with the development and optional-feature extras:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev,all]"
python -m pip install pre-commit
all omits Pillow on Python 3.10 (the Pillow-backed vision/media extras
require 3.11+). Core dependencies are intentionally small; new heavy
dependencies belong in extras.
Tests and lint¶
python -m pytest tests/ -q # unit + e2e suite
pre-commit run --all-files # Black, isort, flake8, encoding pragmas, …
Run Black, isort, and flake8 before submitting. The pre-commit config also
enforces UTF-8 encoding pragmas, docstring-first ordering, and trailing-
whitespace cleanup. mkdocs.yml uses !!python/name: tags, so the
check-yaml hook runs with --unsafe.
Test layout¶
tests/ut/— unit tests, includingtest_docs_consistency.py, which guards the root README/user-guide/migration/CHANGELOG contracts.tests/e2e/— end-to-end runs against a fake provider (tests/e2e/fake_provider.py), so the suite exercises the agent loop offline without real cloud model calls.
Documentation site¶
The bilingual docs site (this site) builds with MkDocs Material:
python -m venv .venv-docs
source .venv-docs/bin/activate
python -m pip install -r requirements-doc.txt -e .
mkdocs serve # live preview at http://127.0.0.1:8000
mkdocs build --strict # CI-equivalent build (warnings are errors)
English pages live at docs/en/ (site root), Chinese at docs/zh/
(/zh/). Reference pages use mkdocstrings ::: identifiers resolved
against src/; keep the en/zh ::: blocks identical and translate only
headings and prose. The version placeholder 1.0.2 is
injected from src/dashscope_agenticx/_version.py by docs/hooks.py.
CI (.github/workflows/docs.yml) builds with --strict on pull requests
and deploys to GitHub Pages on pushes to main.
Contribution rules¶
- Use Python 3.10–3.13.
- Create focused changes with tests.
- Run
pytest -q, Black, isort, and flake8 before submitting. - Keep Core dependencies small; new heavy dependencies belong in extras.
- Preserve the typed Event, Runtime, App Manifest, and Session contracts.
- Security-sensitive changes require negative tests for untrusted input.
Identity contract¶
The canonical distribution and protocol/package identity is
dashscope-agenticx, the import namespace is dashscope_agenticx, and the
only official command is agenticx (no official short alias). Workspaces
use .agenticx/, environment variables use AGENTICX_*, and the global app
name is AgenticX. Do not introduce the unrelated bare agenticx PyPI
distribution.
Release contract¶
python scripts/release_check.py
The release check validates package identity, version, imports, CLI, and
bundled Apps. Coverage gates, cross-platform CI (Python 3.10–3.13;
Ubuntu/macOS/Windows smoke checks), App validation, and supply-chain checks
are separate release requirements — passing local unit tests alone does not
publish or certify a release. Tag builds prepare wheel/source distributions
and platform binaries with SHA-256 checksums in a draft GitHub Release for
final review. See the repository RELEASE.md for packaging, checksums,
SBOM, and publication gates.