开发者指南¶
环境¶
使用 Python 3.10–3.13。以可编辑模式安装包,并带上开发与可选功能 扩展:
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
在 Python 3.10 上,all 不包含 Pillow(基于 Pillow 的 vision/media
扩展需要 3.11+)。核心依赖刻意保持精简;新的重量级依赖应放入扩展。
测试与代码检查¶
python -m pytest tests/ -q # unit + e2e suite
pre-commit run --all-files # Black, isort, flake8, encoding pragmas, …
提交前请运行 Black、isort 与 flake8。pre-commit 配置还会强制 UTF-8
编码声明、docstring 优先的顺序,以及行尾空白清理。mkdocs.yml 使用了
!!python/name: 标签,因此 check-yaml Hook 以 --unsafe 运行。
测试布局¶
tests/ut/— 单元测试,包括test_docs_consistency.py,用于守护 根目录 README/user-guide/migration/CHANGELOG 的契约。tests/e2e/— 针对假 Provider(tests/e2e/fake_provider.py)的 端到端运行,使测试套件可以在离线状态下演练 Agent 循环,而无需真实 的云端模型调用。
文档站点¶
双语文档站点(即本站点)使用 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)
英文页面位于 docs/en/(站点根路径),中文页面位于 docs/zh/
(/zh/)。参考页面使用 mkdocstrings 的 ::: 标识符,从 src/ 解析;
请保持 en/zh 的 ::: 块完全一致,仅翻译标题与正文。版本占位符
1.0.2 由 docs/hooks.py 从
src/dashscope_agenticx/_version.py 注入。
CI(.github/workflows/docs.yml)在 Pull Request 上以 --strict
构建,并在推送到 main 时部署到 GitHub Pages。
贡献规则¶
- 使用 Python 3.10–3.13。
- 提交聚焦的变更并附带测试。
- 提交前运行
pytest -q、Black、isort 与 flake8。 - 保持核心依赖精简;新的重量级依赖应放入扩展。
- 维护带类型的 Event、Runtime、App Manifest 与 Session 契约。
- 涉及安全的变更需要针对不可信输入的负向测试。
标识契约¶
规范的发行包与协议/包标识为 dashscope-agenticx,导入命名空间为
dashscope_agenticx,唯一的官方命令是 agenticx(无官方短别名)。
工作区使用 .agenticx/,环境变量使用 AGENTICX_*,全局应用名为
AgenticX。不要引入无关的 agenticx PyPI 发行包。
发布契约¶
python scripts/release_check.py
发布检查会验证包标识、版本、导入、CLI 与内置 App。覆盖率门槛、
跨平台 CI(Python 3.10–3.13;Ubuntu/macOS/Windows 冒烟检查)、App
校验与供应链检查是独立的发布要求 — 仅通过本地单元测试并不构成发布
或认证。Tag 构建会准备 wheel/源码发行包与平台二进制文件,并附带
SHA-256 校验和,放入草稿 GitHub Release 供最终审核。打包、校验和、
SBOM 与发布门槛参见仓库中的 RELEASE.md。